# Gossip Learning System - Technical Documentation

## Proje Özeti

Bu proje, yerel ortamda 10 client ile çalışan bir **Gossip Learning** sistemidir. Federated Learning'e benzer şekilde, her client kendi verisinde eğitim yapar ve model ağırlıklarını peer'larıyla paylaşır. Merkezi bir sunucu yerine, peer-to-peer model paylaşımı kullanılır.

### Temel Özellikler
- **10 Client**: Her biri farklı miktarda veri ile (1.5K - 10K arası)
- **CIFAR-10 Dataset**: 50K eğitim, 10K test görüntüsü
- **Random Partial Mesh Topology**: Her node 2-4 peer'a bağlı
- **Sürekli Eğitim Döngüsü**: Train → Share → Aggregate → Repeat
- **Reliable UDP**: TCP benzeri güvenilirlik (ACK, retransmit)
- **Real-time Dashboard**: WebSocket ile canlı görselleştirme

---

## Dosya Yapısı ve Açıklamalar

```
c:\Users\Bak2\Desktop\localgl\
│
├── config.py                    # TÜM KONFİGÜRASYONLAR
├── requirements.txt             # Python bağımlılıkları
├── IMPLEMENTATION_PLAN.md       # Bu döküman
│
├── data/
│   ├── __init__.py
│   ├── partition.py             # CIFAR-10 indirme ve bölümleme
│   ├── clients/                 # Her client için ayrı klasör
│   │   ├── client_0/
│   │   │   ├── data.npy         # Görüntüler (N, 3, 32, 32)
│   │   │   └── labels.npy       # Etiketler (N,)
│   │   ├── client_1/
│   │   └── ... (client_9'a kadar)
│   ├── test/
│   │   ├── data.npy
│   │   └── labels.npy
│   └── topology.json            # Oluşturulan topoloji
│
├── models/
│   ├── __init__.py
│   └── simple_cnn.py            # CNN modeli + EarlyStopping
│
├── network/
│   ├── __init__.py
│   ├── protocol.py              # Paket yapıları, serialization
│   ├── reliable_udp.py          # UDP + reliability layer
│   └── topology.py              # Random mesh üreteci
│
├── gossip/
│   ├── __init__.py
│   ├── aggregator.py            # FedAvg implementasyonu
│   ├── client.py                # Gossip learning client
│   └── coordinator.py           # Durum yönetimi, dashboard bridge
│
├── dashboard/
│   ├── __init__.py
│   ├── app.py                   # FastAPI backend + WebSocket
│   ├── templates/
│   │   └── index.html           # Dashboard HTML
│   └── static/
│       └── dashboard.js         # Canvas-based visualization
│
└── scripts/
    ├── __init__.py
    ├── prepare_data.py          # Veri hazırlama scripti
    ├── run_system.py            # Tüm sistemi başlat
    └── run_client.py            # Tek client başlat
```

---

## Bileşen Detayları

### 1. config.py
Tüm global ayarlar burada:
```python
NUM_CLIENTS = 10
CLIENT_BASE_PORT = 6000              # Clientlar 6000-6009 portlarını kullanır
DASHBOARD_PORT = 8080

# Veri dağılımı (Non-IID, quantity-based)
CLIENT_DATA_DISTRIBUTION = [2000, 3000, 5000, 10000, 1500, 3500, 6000, 8000, 5500, 5500]

# Training
BATCH_SIZE = 32
LEARNING_RATE = 0.001

# Gossip client.py içinde tanımlı:
# EPOCHS_PER_ROUND = 10
# EARLY_STOPPING_PATIENCE = 3
```

### 2. models/simple_cnn.py
```python
class SimpleCNN(nn.Module):
    # 582,346 parametre
    # Input: (N, 3, 32, 32) CIFAR-10 görüntüleri
    # Output: (N, 10) class logits
    
    def get_weights(self) -> np.ndarray:
        # Tüm ağırlıkları flatten numpy array olarak döndür
        # Gossip iletişimi için kullanılır
        
    def set_weights(self, weights: np.ndarray):
        # Numpy array'den ağırlıkları modele yükle

class EarlyStopping:
    # patience: Kaç epoch iyileşme olmadan bekle
    # Validation loss iyileşmezse eğitimi durdur
```

### 3. network/reliable_udp.py
UDP üzerinde TCP benzeri güvenilirlik:
```python
class ReliableUDP:
    # Packet yapısı:
    # [SEQ_NUM: 4B][MSG_TYPE: 1B][CHUNK_ID: 2B][TOTAL_CHUNKS: 2B][CHECKSUM: 4B][PAYLOAD]
    
    # Özellikler:
    # - Sequence numbers: Paket sıralaması
    # - ACK packets: Onay mekanizması
    # - Retransmission: Timeout'ta yeniden gönder
    # - Chunking: Büyük payload'ları 8KB parçalara böl
    # - CRC32 checksum: Veri bütünlüğü kontrolü
```

### 4. network/topology.py
```python
class TopologyManager:
    def generate_random_topology(self, min_peers=2, max_peers=4):
        # 1. Spanning tree oluştur (connectivity guarantee)
        # 2. Her node için min_peers'a ulaşana kadar rastgele edge ekle
        # 3. Bağlantılı graf garanti edilir
        
    def get_peers(self, client_id) -> List[int]:
        # Client'ın bağlı olduğu peer ID'leri
        
    def get_visualization_data() -> dict:
        # Dashboard için nodes ve edges
```

### 5. gossip/client.py - ÖNEMLİ
Ana eğitim döngüsü:
```python
class GossipClient:
    def run_continuous(self):
        """
        SÜREKLI DÖNGÜ (Ctrl+C ile durdurulana kadar):
        
        while self.running:
            self.current_round += 1
            
            # 1. TRAIN: 10 epoch eğit (early stopping ile)
            accuracy = self.train_round()
            
            # 2. SEND: Model ağırlıklarını tüm peer'lara gönder
            self.send_model_to_peers()
            
            # 3. WAIT: Peer modellerini bekle (15s timeout)
            self.wait_for_peers(timeout=15.0)
            
            # 4. AGGREGATE: Gelen modelleri FedAvg ile birleştir
            self.aggregate_models()
            
            # 5. Model güncellendi, bir sonraki round'a geç
        """
        
    def train_round(self):
        # EPOCHS_PER_ROUND (10) epoch eğit
        # EARLY_STOPPING_PATIENCE (3) ile erken dur
        
    def aggregate_models(self):
        # FedAvg: Σ(n_i × w_i) / Σ(n_i)
        # Kendi modeli + gelen peer modelleri
```

### 6. gossip/aggregator.py
```python
class FedAvgAggregator:
    def add_update(self, weights: np.ndarray, sample_count: int):
        # Aggregasyon için model ekle
        
    def aggregate(self) -> np.ndarray:
        # Weighted average hesapla
        # Daha çok veriye sahip client'ın modeli daha ağır basar
```

### 7. gossip/coordinator.py
```python
class GossipCoordinator:
    # Dashboard ile köprü görevi görür
    
    clients: Dict[int, ClientInfo]      # Her client'ın durumu
    transfers: List[TransferEvent]       # Model transferleri
    global_models: List[GlobalModelInfo] # Aggregasyon sonuçları
    best_accuracy: float                 # En iyi accuracy
    
    def update_client(self, metrics):
        # Client durumunu güncelle ve dashboard'a bildir
        
    def record_transfer(self, info):
        # Transfer event'i kaydet
        
    def _broadcast(self, event_type, data):
        # WebSocket ile dashboard'a gönder
```

### 8. dashboard/app.py
```python
# FastAPI + WebSocket
# Endpoints:
#   GET /           - Dashboard HTML
#   GET /api/data   - Mevcut durum
#   WS /ws          - Real-time updates
```

### 9. dashboard/static/dashboard.js
```javascript
// Canvas-based visualization
// Özellikler:
// - Circular layout topology
// - Node üstünde info dialog (training/sending/aggregating durumunda)
// - Transfer animasyonları
// - Global model listesi (accuracy sıralı)
```

---

## Gossip Learning Akışı

```
Round 1:
┌─────────┐     ┌─────────┐     ┌─────────┐
│Client 0 │     │Client 1 │     │Client 2 │ ...
│ 2K veri │     │ 3K veri │     │ 5K veri │
└────┬────┘     └────┬────┘     └────┬────┘
     │               │               │
     ▼               ▼               ▼
  TRAIN           TRAIN           TRAIN
  10 epoch        10 epoch        10 epoch
     │               │               │
     ▼               ▼               ▼
  SEND to         SEND to         SEND to
  peers           peers           peers
     │               │               │
     ▼               ▼               ▼
  WAIT for        WAIT for        WAIT for
  peer models     peer models     peer models
     │               │               │
     ▼               ▼               ▼
  AGGREGATE       AGGREGATE       AGGREGATE
  FedAvg          FedAvg          FedAvg
     │               │               │
     └───────────────┴───────────────┘
                     │
                     ▼
              Round 2 (repeat)
```

---

## Kullanım Talimatları

### İlk Kurulum
```bash
cd c:\Users\Bak2\Desktop\localgl

# 1. Bağımlılıkları yükle
pip install -r requirements.txt

# 2. Veriyi hazırla (CIFAR-10 indir ve böl)
python scripts/prepare_data.py
```

### Sistemi Çalıştırma
```bash
# Tüm sistemi başlat (10 client + dashboard)
python scripts/run_system.py

# Dashboard: http://127.0.0.1:8080
# Durdurmak için: Ctrl+C
```

### Tek Client Test
```bash
# Önce topology oluştur
python scripts/run_system.py  # Ctrl+C ile hemen durdur

# Tek client çalıştır
python scripts/run_client.py 0  # Client 0
```

---

## Değişiklik Yapılacak Alanlar

### Epoch/Round Sayısını Değiştirmek
`gossip/client.py` dosyasında:
```python
EPOCHS_PER_ROUND = 10        # Bunu değiştir
EARLY_STOPPING_PATIENCE = 3  # Bunu değiştir
```

### Client Sayısını Değiştirmek
`config.py` dosyasında:
```python
NUM_CLIENTS = 10  # Bunu değiştir
CLIENT_DATA_DISTRIBUTION = [...]  # Yeni dağılım ekle
```

### Topolojiyi Değiştirmek
`config.py` dosyasında:
```python
MIN_PEERS = 2  # Minimum peer sayısı
MAX_PEERS = 4  # Maximum peer sayısı
```

### Model Mimarisini Değiştirmek
`models/simple_cnn.py` dosyasında `SimpleCNN` class'ını düzenle.
**DİKKAT**: `get_weights()` ve `set_weights()` metodlarının çalışmaya devam ettiğinden emin ol.

### Dashboard Portunu Değiştirmek
`config.py` dosyasında:
```python
DASHBOARD_PORT = 8080  # Bunu değiştir
```

---

## Bilinen Sorunlar ve Çözümler

### 1. "Data not found" Hatası
```bash
python scripts/prepare_data.py  # Veriyi hazırla
```

### 2. Port Already in Use
Önceki çalışmayı Ctrl+C ile düzgün durdurmadıysanız:
```bash
# Windows'ta portları kullanan işlemleri bul
netstat -ano | findstr :6000
netstat -ano | findstr :8080

# İşlemi sonlandır
taskkill /PID <pid> /F
```

### 3. Dashboard Güncellenmiyor
WebSocket bağlantısı kopmuş olabilir. Sayfayı yenileyin.

---

## Gelecek Geliştirmeler

1. **NAT Traversal**: STUN/TURN ile gerçek P2P
2. **Model Compression**: Quantization, pruning
3. **Byzantine Fault Tolerance**: Kötü niyetli client tespiti
4. **Differential Privacy**: Gizlilik garantisi
5. **Hierarchical Gossip**: 100+ client için ölçeklenebilirlik

---

## Teknik Referans

### Model Ağırlık Boyutu
- SimpleCNN: 582,346 parametre
- Float32: ~2.3 MB
- Serialize edilince: ~2.5 MB

### UDP Paket Yapısı
```
[SEQ_NUM: 4 byte, unsigned int]
[MSG_TYPE: 1 byte]
[CHUNK_ID: 2 bytes, unsigned short]
[TOTAL_CHUNKS: 2 bytes, unsigned short]
[CHECKSUM: 4 bytes, CRC32]
[PAYLOAD: variable, max 8KB per chunk]
```

### Message Types
```python
REGISTER = 0x01
MODEL_UPDATE = 0x02
ACK = 0x03
HEARTBEAT = 0x04
GOSSIP_REQUEST = 0x05
GOSSIP_RESPONSE = 0x06
CLIENT_STATUS = 0x07
TRAINING_COMPLETE = 0x08
```
