# QuinkGL - Gossip Learning Framework Roadmap

## Overview

Bu proje, mevcut P2P Gossip Learning sisteminden production-ready bir **Gossip Learning Framework**'üne evrime geçiş planıdır.

**Federated Learning ≠ Gossip Learning**
- **Federated Learning**: Merkezi sunucu ile koordinasyon
- **Gossip Learning**: Tam P2P, merkezi sunucusuz, peer-to-peer model sharing

```
Phase 1: Horizontal ──→ Phase 2: Vertical ──→ Phase 3: Framework
   (Aynı veri tipi)         (Farklı feature'lar)      (Extensible API)
```

---

## Phase 1: Horizontal Gossip Learning

**Amaç:** Aynı veri tipine ve aynı class'lara sahip client'ların P2P ağında model paylaşımı ve aggregation.

### 1.1 Core Interface Tanımları

Framework kullanıcısı minimal kod ile sisteme katılabilmeli:

```python
# Kullanıcı tarafında yazılacak kod
from quinkgl import GLNode

# 1. Model wrapper oluştur
class MyModel(ModelWrapper):
    def train(self, data):
        # Kendi training loop'un
        pass

    def get_weights(self):
        # Model ağırlıklarını döndür
        return self.model.state_dict()

    def set_weights(self, weights):
        # Ağırlıkları modele yükle
        self.model.load_state_dict(weights)

# 2. Node'u başlat
node = GLNode(
    model=MyModel(),
    domain="health",           # Domain identifier
    data_schema=hash_schema()  # Feature set fingerprint
)

# 3. Ağa katıl ve çalıştır
await node.join()
await node.run_continuous()
```

### 1.2 Topoloji Katmanı

**Sorun:** Peer'lar birbirlerine nasıl bağlanacak?

**Çözüm:** Pluggable Topology Strategy Pattern

```python
# Framework içinde
class TopologyStrategy(ABC):
    @abstractmethod
    async def select_targets(self, context: SelectionContext) -> List[PeerID]:
        """Bu round'ta kimlere model gönderilecek?"""
        pass

# Built-in stratejiler
class RandomTopology(TopologyStrategy):
    """Rastgele k peer seç"""

class SmallWorldTopology(TopologyStrategy):
    """Small-world: yakın + uzak bağlantılar"""

class SemanticTopology(TopologyStrategy):
    """Benzer veriye sahip peer'lara öncelik"""
```

**Kullanım:**
```python
node = GLNode(
    model=MyModel(),
    topology=SmallWorldTopology(k_neighbors=8, rewire_interval=300)
)
```

### 1.3 Aggregation Katmanı

**Sorun:** Gelen modeller nasıl birleştirilecek?

**Çözüm:** Pluggable Aggregation Strategy

```python
class AggregationStrategy(ABC):
    @abstractmethod
    async def aggregate(self, updates: List[ModelUpdate]) -> AggregatedModel:
        pass

# Built-in: FedAvg
class FedAvg(AggregationStrategy):
    def aggregate(self, updates):
        # Weighted average by sample count
        pass

# Built-in: Robust Aggregation (gelecekte)
class KrumAggregator(AggregationStrategy):
    # Byzantine fault tolerant
    pass
```

### 1.4 Domain Isolation

**Sorun:** Sağlık ve tarım client'ları karışmasın.

**Çözüm:** IPv8 Community Partitioning

```python
# Her domain için ayrı community
class GossipLearningCommunity(Community):
    def __init__(self, domain_id: str, schema_hash: str):
        # Domain + schema combination → community ID
        self.community_id = sha256(f"{domain_id}:{schema_hash}")

# Node sadece kendi community'sindeki peer'ları görür
```

**Discovery Flow:**
```
1. Node başlar → domain + schema bilgisiyle announce
2. Aynı domain/schema'dan peer'lardan "peer_offer" alır
3. Sadece compatible peer'lara bağlanır
4. Gossip başlar
```

### 1.5 Continuous Gossip Protocol

**Sorun:** Sürekli training nasıl koordine edilecek?

**Çözüm:** Event-driven async loop

```python
class GLNode:
    async def run_continuous(self):
        while self.running:
            # 1. Local training
            await self.train_local()

            # 2. Select targets (topology strategy)
            targets = await self.topology.select_targets(self.context)

            # 3. Send model to targets
            await self.send_model(targets)

            # 4. Wait for incoming models (async)
            updates = await self.collect_updates(timeout=60)

            # 5. Aggregate (aggregation strategy)
            new_model = await self.aggregator.aggregate(updates)

            # 6. Repeat
```

---

## Phase 2: Vertical Gossip Learning

**Amaç:** Farklı feature'lara sahip ama aynı sample'lara sahip client'ların işbirliği.

### 2.1 Temel Fark

| Aspect | Horizontal | Vertical |
|--------|---------------|-------------|
| Veri | Aynı feature'lar, farklı sample'lar | Farklı feature'lar, aynı sample'lar |
| Model | Tüm feature'lar için tam model | Feature subset için partial model |
| Aggregation | Model ağırlıklarını ortala | Gradient/Embedding sharing |

### 2.2 Ek Interface'ler

```python
class VerticalGLNode(GLNode):
    def align_samples(self, sample_ids: List[str]):
        """Ortak sample'ları belirle"""

    def compute_embedding(self, partial_input):
        """Feature subset'ten embedding üret"""

    def aggregate_embeddings(self, embeddings: List[Tensor]):
        """Embedding'leri merge et"""
```

### 2.3 Topoloji Uyarlaması

Vertical FL için ek kriter:
- **Sample alignment**: Aynı sample ID'lere sahip node'lar bağlanmalı
- **Feature complementarity**: Tamamlayıcı feature'lar öncelikli

---

## Phase 3: Framework Haline Getirme

**Amaç:** Kullanıcı topolojiden aggregation'a kadar her şeyi customize edebilsin.

### 3.1 Paket Yapısı

```
quinkgl/
├── __init__.py              # Public API
│
├── core/                    # Core framework
│   ├── node.py              # GLNode base class
│   ├── context.py           # ExecutionContext
│   └── lifecycle.py         # Hook management
│
├── topology/                # Topoloji stratejileri
│   ├── base.py              # TopologyStrategy ABC
│   ├── random.py
│   ├── small_world.py
│   └── semantic.py
│
├── aggregation/             # Aggregation stratejileri
│   ├── base.py              # AggregationStrategy ABC
│   ├── fedavg.py
│   └── robust.py            # Krum, etc.
│
├── gossip/                  # Gossip protocol
│   ├── protocol.py          # Message types
│   └── orchestrator.py      # Gossip loop
│
├── transport/               # IPv8 integration
│   ├── communities.py       # Domain-specific communities
│   └── serialization.py     # Model ser/de
│
├── storage/                 # Model versioning
│   └── model_store.py
│
└── config/                  # Default configurations
    └── strategies.py
```

### 3.2 Configuration Options

Framework kullanıcıları 3 seviyede customization yapabilmeli:

**Seviye 1: Declarative Config**
```yaml
# config.yaml
topology:
  type: small_world
  k_neighbors: 8

aggregation:
  type: fedavg
  weight_by: data_size

gossip:
  push_interval: 60
  pull_probability: 0.3
```

**Seviye 2: Strategy Selection**
```python
node = GLNode(
    topology=SmallWorldTopology(k=8),
    aggregation=FedAvg(weight_by="data_size")
)
```

**Seviye 3: Custom Implementation**
```python
class MyTopology(TopologyStrategy):
    async def select_targets(self, context):
        # Kendi logic'in
        pass

node = GLNode(topology=MyTopology())
```

### 3.3 Lifecycle Hooks

Kullanıcılar critical noktalara kendi logic'lerini inject edebilsin:

```python
class GLNode:
    hooks = {
        "before_train":      Callable,
        "after_train":       Callable,
        "before_send":       Callable,
        "after_receive":     Callable,
        "before_aggregate":  Callable,
        "after_aggregate":   Callable,
    }

# Kullanım
node.register_hook("before_send", lambda m: add_noise(m, epsilon=1.0))
```

### 3.4 Extensibility Checklist

| Bileşen | Extensible? | Nasıl? |
|---------|-------------|--------|
| Topoloji | ✓ | Abstract base class + built-in strategies |
| Aggregation | ✓ | Abstract base class + built-in strategies |
| Gossip protocol | ✓ | Configurable parameters |
| Model format | ✓ | Framework agnostic (numpy/bytes) |
| Domain logic | ✓ | Community ID generation override |
| Transport | ✓ | IPv8 community extend edilebilir |
| Privacy | ✓ | Hook points for DP, encryption |

---

## Implementation Sırası

### Phase 1: Horizontal Gossip Learning
1. **Core abstractions** (ModelWrapper, GLNode, Context)
2. **IPv8 community structure** (domain discovery + learning)
3. **Basic topology** (RandomTopology)
4. **Basic aggregation** (FedAvg)
5. **Continuous gossip loop**
6. **Testing** (local multi-process simulation)

### Phase 2: Vertical Gossip Learning
1. **Sample alignment protocol**
2. **Embedding computation interface**
3. **Vertical-specific aggregation**
4. **Topology update** (feature complementarity)

### Phase 3: Framework
1. **Public API cleanup**
2. **Configuration system**
3. **Documentation**
4. **Example implementations**
5. **Testing suite**

---

## Kritik Tasarım Kararları

| Karar | Seçim | Gerekçe |
|-------|-------|---------|
| **Model format** | Framework agnostic | PyTorch/TF/JAX bağımsız | 
| **Aggregation location** | Her node lokal | Tam P2P, SPOF yok |
| **Domain discovery** | Separate community | Bootstrap + strict isolation |
| **Schema validation** | One-time handshake | Aynı veri formatı guarantee |
| **Versioning** | Semver model architecture | Breaking change detection |
| **BFT in Phase 1** | Hayır | Basitlik için ertelenir |
| **Sync model** | Continuous gossip | Round-based daha sonra |

---

## Açık Sorular

Implementasyona başlamadan önce netleşmesi gerekenler:

1. **Model wrapper detay seviyesi:** Sadece `get/set_weights` mi yoksa training loop da framework içinde mi olmalı?

2. **Validation:** Phase 1 için local validation yeterli mi, yoksa global validation mekanizması da gerekli mi?

3. **Byzantine tolerance:** Hangi phase'de eklenmeli? Phase 1 sonrası mı?

4. **Configuration format:** YAML, TOML, veya Python dataclass?

---

## Kaynaklar

- [GossipGrad: Scalable Deep Learning](https://arxiv.org/abs/1809.04543)
- [Peer-to-Peer Federated Learning](https://arxiv.org/abs/2009.08267)
- IPv8 Documentation: https://ipv8.readthedocs.io/
