# QuinkGL Framework Dönüşüm Raporu 📚

Bu rapor, **QuinkGL** projesini (şu anki halinden) genel amaçlı, geliştiricilerin kendi projelerinde kullanabileceği bir **Python Kütüphanesi (Framework)** haline getirmek için gereken adımları, analizi ve yol haritasını içerir.

---

## 1. Yönetici Özeti: Framework Olabilir mi? 🤔

**Cevap: KESİNLİKLE EVET.**

Mevcut proje yapısı (`quinkgl` klasörü altında modüler yapı) zaten bir framework temeline sahiptir.
*   ✅ **Modülerlik:** `models`, `network`, `topology`, `aggregation` gibi klasörler zaten ayrışmış durumda.
*   ✅ **Soyutlama:** `ModelWrapper` ve `GossipNode` gibi sınıflar, kullanıcının detayları bilmeden işlem yapmasını sağlıyor.
*   ✅ **Ayrık Uygulama:** `dashboard` ve `scripts` klasörleri, çekirdek kütüphaneden (`quinkgl`) nispeten bağımsız.

**Dönüşümün Özü:**
Şu anki `Run Script -> Çalıştır` mantığından, `Import Library -> Define Class -> Start` mantığına geçiş yapacağız. Yani kullanıcılar projeyi "çalıştırmayacak", projeyi "kodlarında kullanacak".

---

## 2. Framework Mimarisi Tasarımı 🏗️

Bir framework olarak QuinkGL, kullanıcıya şu deneyimi sunmalıdır:

### Hedeflenen Kullanıcı Deneyimi (DX)

Kullanıcı `pip install quinkgl` dedikten sonra şöyle bir kod yazabilmeli:

```python
from quinkgl import GossipNode
from quinkgl.models import PyTorchWrapper
from quinkgl.topology import Cyclon
import my_model  # Kullanıcının tanımladığı PyTorch modeli

# 1. Modeli Sar
model = PyTorchWrapper(my_model())

# 2. Node Oluştur
node = GossipNode(
    model=model,
    topology=Cyclon(view_size=20),
    gossip_interval=5.0
)

# 3. Başlat (Async)
await node.start()
await node.train(data_loader)
```

### Önerilen Dizin Yapısı

Şu anki yapıyı paketleme standartlarına (PyPI) uygun hale getirmek için:

```text
quinkgl-framework/
├── pyproject.toml       # (YENİ) Bağımlılık ve Build ayarları
├── README.md            # PyPI dokümantasyonu
├── src/                 # (OPSİYONEL ama Önerilen) Kaynak kod
│   └── quinkgl/         # Ana paket
│       ├── __init__.py  # Dışarıya açılan API'ler (export)
│       ├── core/        # Temel sınıflar (Node, Context)
│       ├── network/     # IPv8, Tunnel (Kullanıcı görmemeli)
│       ├── algorithms/  # (Eski `gossip`) Eğitim mantığı
│       └── utils/       # Yardımcı araçlar
├── examples/            # (YENİ) Örnek projeler (MNIST, Chat vb.)
└── tests/               # Unit testler
```

---

## 3. İzlenecek Adımlar (Yol Haritası) 🗺️

Bu dönüşümü gerçekleştirmek için aşağıdaki 4 aşamayı izlemelisiniz:

### Aşama 1: Temizlik ve Soyutlama (Refactoring)
Su anki kod, belirli bir demo senaryosu (Breast Cancer, Scale Test) için özelleşmiş durumda. Bunları genelleştirmeliyiz.

1.  **Hard-coded Değerleri Kaldır:** Kod içindeki varsayılan portlar, dataset isimleri vb. parametrik hale getirilmeli.
2.  **Bağımlılık Ayrıştırma:** `dashboard` uygulaması kütüphanenin içinde olmamalı. Dashboard, kütüphaneyi kullanan *ayrı* bir araç veya eklenti (`pip install quinkgl[dashboard]`) olmalı.
3.  **Config Yönetimi:** `TrainingConfig` gibi sınıfları daha esnek hale getirip, kullanıcının `dict` veya `dataclass` ile ayar vermesini sağlamalıyız.

### Aşama 2: API Tasarımı (`__init__.py`)
Kullanıcının 5-6 alt modülden import yapması yerine, ana paketten erişebilmesi gerekir.

*   `quinkgl/__init__.py` dosyasını düzenleyerek şunları dışarı açın:
    *   `GossipNode`
    *   `TrainingConfig`
    *   `FederatedDataset` (Veri dağıtımı için)

### Aşama 3: Paketleme (Packaging)
Python ekosisteminde (PyPI) yayınlamak için:

1.  **`pyproject.toml` Oluşturma:**
    Modern Python paketlemesinde `setup.py` yerine bu kullanılır. Bağımlılıkları (`torch`, `pyipv8` vb.) burada tanımlayacağız.
2.  **Build Sistemi:**
    `hatch` veya `poetry` kullanarak build sistemi kurulmalı.

### Aşama 4: Dokümantasyon ve Örnekler
Framework'ü framework yapan şey dokümanıdır.

1.  **Docstrings:** Her fonksiyona Google-style docstring yazılmalı.
2.  **Tutorials:** "5 dakikada P2P Öğrenme" gibi Jupyter Notebook'lar hazırlanmalı.

---

## 4. Sıkça Sorulan Sorular (SSS) ❓

**S: Kütüphane olunca Dashboard ne olacak?**
C: Dashboard, framework'ün yanında gelen bir "CLI tool" olabilir. Örn: `quinkgl-dashboard run --port 8080` komutuyla çalıştırılabilir.

**S: IPv8 (P2P) karmaşıklığını kullanıcıdan nasıl saklarız?**
C: Kullanıcı sadece `GossipNode` sınıfını görür. Arka plandaki `IPv8Manager`, `Community`, `Tunnel` gibi detaylar "private API" (`_ipv8_manager` gibi) olarak kalır.

**S: Kullanıcı kendi modelini (TensorFlow, JAX) kullanabilir mi?**
C: Evet. Şu anki `ModelWrapper` (abstract base class) yapısını koruyup, kullanıcıya "Kendi Wrapper'ını yaz, sisteme ver" diyebilirsiniz. Bu tam bir framework özelliğidir.

---

## 5. Sonraki Adım Önerisi

İlk olarak **`pyproject.toml`** dosyasını oluşturup projeyi yerel bir paket (`pip install -e .`) olarak kurmayı denemeliyiz. Bu, import hatalarını ve yapısal sorunları hemen ortaya çıkaracaktır.
