Skip to content

docs: collaborative training architecture design document - #1298

Open
ale18V wants to merge 1 commit into
mainfrom
docs/collaborative-training-architecture
Open

ale18V wants to merge 1 commit into
mainfrom
docs/collaborative-training-architecture

Conversation

@ale18V

@ale18V ale18V commented Nov 18, 2026

Copy link
Copy Markdown
Collaborator

What & why

Disco currently models collaborative learning variations primarily through a single aggregationStrategy axis while embedding algorithm-specific state and update clipping directly inside Trainer. This coupling prevents composing client-side optimization strategies (such as FedProx, SCAFFOLD, or Ditto) with robust or private aggregators (ByzantineRobustAggregator, SecureAggregator) and forces Trainer and Model to accumulate ad-hoc branches for every new algorithm. This PR introduces a design document (docs/TRAINING_ARCHITECTURE.md) detailing these architectural limitations and proposing a modular target architecture.

Technical plan

Add docs/TRAINING_ARCHITECTURE.md documenting the current responsibility leaks across TrainingInformation, Trainer, Model, and Aggregator, and specifying the proposed three-axis decomposition (intra-round local training strategy, post-round update transforms/privacy, and inter-client weight aggregation). The document defines concrete TypeScript contracts for composable RoundHook lifecycle stages, backend-agnostic Model local objective options operating strictly on trainableWeights, and a phased migration path.

Deviations from plan

None.

Todo

  • Implement Phase 1 (Model.trainableWeights and Trainer RoundHook pipeline).
  • Implement Phase 2 (decouple trainingStrategy from aggregationStrategy in TrainingInformation, cli, and webapp).
  • Implement Phase 3 (decouple client-side update clipping from ByzantineRobustAggregator).

@ale18V

ale18V commented Nov 18, 2026

Copy link
Copy Markdown
Collaborator Author

@JulienVig I think we need to refactor a bit the architecture of disco. The goal would be to decouple some components a bit more and make it easier to implement different algorithms in the future.

PR #1289 already does some refactoring in this direction, but still there are some smells, like algorithm-specific parameters being thrown in the trainer.

I will use this PR to come up with a design doc for a new architecture which we can review together before moving forward with it (if you agree)

@JulienVig

Copy link
Copy Markdown
Collaborator

Yes, refactoring the architecture makes a lot of sense. Let me know when the document is ready for review.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants