Federated Learning Subsystem

6. The Federated Learning Subsystem

federated.py (633 lines) implements a coordinator for multi-institution model training in which raw patient data never leaves a participating site. The module's own header is candid about its scope: it provides "weighted aggregation, optional differential-privacy noise, and basic update outlier detection," not a production-grade federated learning platform. This section examines the three algorithmic components in turn — aggregation, differential privacy, and Byzantine-participant detection — and the round life cycle that ties them together.

sequenceDiagram
    participant Coord as FederatedCoordinator
    participant P1 as Participant Site 1
    participant P2 as Participant Site 2
    participant DP as GaussianMechanism
    participant Agg as SecureAggregator
    participant A as AuditChain

    Coord->>P1: dispatch round (reference model)
    Coord->>P2: dispatch round (reference model)
    P1-->>Coord: local update (weights, num_samples)
    P2-->>Coord: local update (weights, num_samples)
    Coord->>Coord: validate layer names + shapes
    Coord->>Coord: detect_byzantine (cosine sim + L2 z-score)
    Coord->>DP: clip(update), add Gaussian noise
    DP-->>Coord: noised update
    Coord->>Agg: weighted aggregate(updates, num_samples)
    Agg-->>Coord: new global model
    Coord->>A: append(action=round_complete, participants)

Loading

Figure 5. Sequence of a single federated round: participant dispatch, update collection, differential-privacy application, and weighted aggregation.

6.1 Weighted Aggregation

Aggregation is performed by a class named SecureAggregator, whose own docstring immediately qualifies its name: "despite the retained public class name, this class does not implement a cryptographic secure-aggregation protocol." This kind of self-correcting documentation is characteristic of the repository's overall stance toward naming that could otherwise overstate a guarantee. The actual aggregation algorithm is sample-weighted averaging: each participant's contribution to a layer is scaled by num_samples / total_samples before being summed, after the coordinator has verified that every update in the round shares an identical set of layer names and that each layer's tensor shape matches the reference model. A configurable prox_mu parameter signals FedProx-inspired intent, though the in-code comment clarifies that the proximal term is understood to modify the participant's local training objective, while server-side aggregation itself remains ordinary sample-weighted averaging.

6.2 Differential Privacy via a Gaussian Mechanism

The GaussianMechanism class implements the standard two-step (ε, δ)-differential-privacy recipe for aggregated updates: gradient clipping followed by calibrated Gaussian noise.

clip_coef    = min(1.0, max_grad_norm / (total_norm + 1e-8))
clipped      = weights * clip_coef
sensitivity  = 2.0 * max_grad_norm / num_participants
noise_std    = noise_multiplier * sensitivity
noised       = clipped + Normal(0, noise_std)

This is the correct mechanical shape of the Gaussian mechanism used throughout the differential-privacy literature, and the DifferentialPrivacyConfig dataclass validates its own parameters on construction — rejecting non-positive ε, a δ outside (0, 1), a non-positive clipping norm, and a negative noise multiplier. What the module does not provide is a formal privacy accountant that tracks cumulative privacy loss across many rounds (for example, via moments accounting or Rényi differential privacy composition), nor a proof that the sampling procedure feeding the mechanism satisfies the independence assumptions the Gaussian mechanism's guarantees rely on. The architecture documentation labels this explicitly as "an experiment, not a complete DP system," a distinction this wiki preserves.

6.3 Byzantine-Participant Detection

A detect_byzantine method screens incoming updates using cosine similarity and L2-norm outlier statistics, flagging a participant when its update's norm deviates from the round's distribution by more than a configured z-score threshold. Detected participants have their persistent trust_score multiplicatively decayed (by a factor of 0.5 per detection in the observed logic), which is used elsewhere in the coordinator to gate future round eligibility. This is a heuristic, statistical defense rather than a cryptographic or game-theoretic one: it can catch a participant whose update is a gross statistical outlier, but it is not designed to withstand an adaptive adversary who shapes an update specifically to evade norm-based detection — which is why the threat-model documentation lists "a dishonest majority of federated participants" among the repository's explicit non-goals.

6.4 Privacy of the Overall Data Path

Figure 6 traces the full path a training signal takes from a participant's local data to the shared global model, making explicit exactly where raw data stops and a privacy-bounded artifact begins.

flowchart LR
    D["Raw patient data\n(never leaves site)"] --> LT["Local training\n(on-site)"]
    LT --> W["Local weight update"]
    W --> CL["Gradient clipping\n(L2 norm ≤ max_grad_norm)"]
    CL --> NZ["Gaussian noise addition\n(ε, δ calibrated)"]
    NZ --> TX["Transmission to coordinator"]
    TX --> BZ["Byzantine outlier check"]
    BZ --> AG["Sample-weighted aggregation"]
    AG --> GM["Updated global model"]
    GM -.->|broadcast next round| LT

Loading

Figure 6. Data flow from local training through clipping, noise addition, transmission, and aggregation. Raw patient data (leftmost node) never crosses the site boundary.

6.5 Boundary Summary

Table 4. Federated learning capability status

Capability	Status
Sample-weighted aggregation with shape/layer validation	Implemented
Gaussian-mechanism clipping and noise addition	Implemented (experimental)
Norm/cosine-similarity Byzantine outlier detection	Implemented (heuristic)
Formal (ε, δ) privacy accounting across rounds	Not implemented
Cryptographic secure aggregation	Not implemented
Mutually authenticated participant transport	Not implemented (deployment responsibility)

---

Previous: ← The Clinical Decision Support Subsystem · Next: The Tamper-Evident Audit Layer →