A privacy-preserving federated learning system with cluster shuffling, SMPC, and gradient pruning for communication-efficient, secure distributed training.

# Install
git clone https://github.com/Tanguyvans/cluster-shuffling-fl.git
cd cluster-shuffling-fl
pip3 install -r requirements.txt

# Run
python3 main.py

Result: Federated learning on CIFAR-10 with 6 clients, 10 rounds, 80% communication savings from gradient pruning!

📖 New to FL? → Quickstart Guide

• 🔄 Cluster Shuffling: Dynamic client reorganization prevents long-term inference
• 🔐 SMPC: Secret sharing (additive & Shamir's) protects model updates
• 🛡️ Differential Privacy: Calibrated noise for formal privacy guarantees

• 📉 Gradient Pruning (NEW!): 80% communication reduction via Deep Gradient Compression (DGC)
• ⚡ Top-k Sparsification: Send only 10% of gradients with momentum correction
• 🔗 Compatible: Works with SMPC, DP, and all privacy mechanisms

• ⚔️ Poisoning Attacks: 6 attack types (Label Flip, IPM, ALIE, Backdoor, etc.)
• 🔍 Privacy Attacks: Gradient inversion, membership inference
• 📊 Comprehensive Metrics: PSNR, accuracy, communication overhead

• Krum, Multi-Krum
• Trimmed Mean, Median
• FLTrust - Trust-based aggregation

• Installation Guide - Setup & dependencies
• Quickstart (5 min) - First FL experiment
• Configuration - Complete config.py reference

• Gradient Pruning - 80% communication savings
• Privacy Defenses - SMPC, DP, Clustering
• Aggregation Methods - Krum, FLTrust, etc.

• Poisoning Attacks - 6 attack types
• Gradient Inversion - Privacy attacks
• Pruned Models - Attack comparison

• Communication Metrics - Measure pruning impact

📖 Full Documentation Index

# Test gradient pruning impact
"gradient_pruning": {"enabled": True, "keep_ratio": 0.1}
python3 main.py

# Compare attack resistance
python3 run_grad_inv.py --config aggressive

# Enable all privacy mechanisms
"diff_privacy": True,
"clustering": True,
"type_ss": "shamir",
"gradient_pruning": {"enabled": True}

# Test poisoning attacks
"poisoning_attacks": {
    "enabled": True,
    "malicious_clients": ["c0_1"],
    "attack_type": "ipm",
    "attack_intensity": 0.5
}

┌─────────────┐
│   Clients   │ ──► Local Training
└─────────────┘
       │
       ├──► Gradient Pruning (80% reduction)
       │
       ├──► SMPC Secret Sharing
       │
       ▼
┌─────────────┐
│ Aggregation │ ──► Krum / FedAvg / FLTrust
└─────────────┘
       │
       ▼
┌─────────────┐
│ Global Model│ ──► Broadcast to Clients
└─────────────┘

Edit config.py for quick customization:

# Dataset & Model
"name_dataset": "cifar10",      # cifar10, cifar100, ffhq128
"arch": "simplenet",            # simplenet, resnet18, mobilenet

# Federated Learning
"n_rounds": 10,                 # Training rounds
"number_of_clients_per_node": 6,# Clients per node

# Gradient Pruning (NEW!)
"gradient_pruning": {
    "enabled": True,            # 80% communication savings
    "keep_ratio": 0.1,          # Keep 10% of gradients
}

# Privacy
"diff_privacy": True,           # Enable DP
"clustering": True,             # Cluster shuffling

# Aggregation
"aggregation": {
    "method": "krum",           # fedavg, krum, fltrust
}

📖 Complete Configuration Guide

cluster-shuffling-fl/
├── main.py                     # Main FL orchestrator
├── config.py                   # Configuration settings
│
├── docs/                       # 📚 Documentation
│   ├── getting-started/        # Installation, quickstart, config
│   ├── features/               # Gradient pruning, privacy, etc.
│   ├── attacks/                # Poisoning, gradient inversion
│   └── measurement/            # Metrics and evaluation
│
├── federated/                  # FL implementation
│   ├── client.py               # Client training
│   ├── server.py               # Server aggregation
│   └── flower_client.py        # Flower wrapper
│
├── security/                   # Privacy mechanisms
│   ├── secret_sharing.py       # SMPC implementation
│   └── gradient_pruning.py     # DGC implementation
│
├── attacks/poisoning/          # Attack framework
│   ├── labelflip_attack.py
│   ├── ipm_attack.py
│   └── ...
│
└── models/architectures/       # Neural network models
    ├── simplenet.py
    ├── resnet.py
    └── ...

# Test gradient pruning
python3 test_gradient_pruning.py

# Run gradient inversion attack
python3 run_grad_inv.py --config default

# Measure communication savings
python3 measure_communication.py --keep-ratio 0.1

This framework implements and evaluates:

• Deep Gradient Compression (Lin et al., ICLR 2018)
• Cluster Shuffling for federated learning
• Byzantine-robust aggregation (Krum, Trimmed Mean)
• Gradient inversion attacks (DLG, iDLG, GIAS, GIFD)

See Research Papers for full citations.

Contributions are welcome! Areas for improvement:

• Additional attack implementations
• More aggregation methods
• Enhanced privacy mechanisms
• Documentation improvements

This project is released under the MIT License. See LICENSE for details.

• Flower - Federated learning framework
• Opacus - Differential privacy library
• PyTorch - Deep learning framework

For questions or collaborations:

• GitHub Issues: Create an issue
• Email: [Your email]

🚀 Ready to get started? → Quickstart Guide