quinkgl 0.1.2__tar.gz

quinkgl-0.1.2/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include requirements.txt
+recursive-include quinkgl *.py
+global-exclude __pycache__
+global-exclude *.py[co]

quinkgl-0.1.2/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: quinkgl
+Version: 0.1.2
+Summary: A decentralized gossip learning framework for P2P edge intelligence
+Author-email: Ali Seyhan <aliseyhan@posta.mu.edu.tr>, Baki Turhan <bakiturhan@posta.mu.edu.tr>
+Project-URL: Homepage, https://github.com/aliseyhann/QuinkGL-Gossip-Learning-Framework
+Project-URL: Bug Tracker, https://github.com/aliseyhann/QuinkGL-Gossip-Learning-Framework/issues
+Keywords: gossip-learning,federated-learning,p2p,decentralized-ai,ipv8
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: torch>=2.0.0
+Requires-Dist: torchvision>=0.15.0
+Requires-Dist: scikit-learn>=1.0.0
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: pyipv8>=2.10.0
+Requires-Dist: grpcio>=1.50.0
+Requires-Dist: grpcio-tools>=1.50.0
+Requires-Dist: protobuf>=4.20.0
+Requires-Dist: msgpack>=1.0.0
+Provides-Extra: tensorflow
+Requires-Dist: tensorflow>=2.12.0; extra == "tensorflow"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: quinkgl[tensorflow]; extra == "all"
+
+# QuinkGL: Gossip Learning Framework
+
+[![PyPI version](https://badge.fury.io/py/quinkgl.svg)](https://badge.fury.io/py/quinkgl)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+QuinkGL is a **decentralized, peer-to-peer (P2P) machine learning framework** designed to enable edge intelligence through Gossip Learning algorithms. Unlike traditional Federated Learning, which relies on a central server for aggregation, QuinkGL distributes the training and aggregation process across all participating nodes.
+
+## Key Features
+
+- **Decentralized Architecture** – No central parameter server required
+- **Gossip Learning** – Random walk and gossip-based aggregation for model convergence
+- **IPv8 Networking** – Native P2P communication with NAT traversal (UDP hole punching)
+- **Scalability** – Handles dynamic networks with node churn
+- **Framework-Agnostic** – Supports PyTorch and TensorFlow models
+- **Built-in Data Splitting** – IID and Non-IID data distribution utilities
+
+## Installation
+
+```bash
+pip install quinkgl
+```
+
+For development:
+
+```bash
+git clone https://github.com/aliseyhann/QuinkGL-Gossip-Learning-Framework.git
+cd QuinkGL-Gossip-Learning-Framework
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import asyncio
+import torch.nn as nn
+from quinkgl import (
+    GossipNode,
+    PyTorchModel,
+    RandomTopology,
+    FedAvg,
+    TrainingConfig,
+    DatasetLoader,
+    FederatedDataSplitter
+)
+
+# 1. Define your model
+class SimpleNet(nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.fc1 = nn.Linear(784, 128)
+        self.fc2 = nn.Linear(128, 10)
+        self.relu = nn.ReLU()
+    
+    def forward(self, x):
+        x = x.view(x.size(0), -1)
+        return self.fc2(self.relu(self.fc1(x)))
+
+# 2. Wrap the model
+model = PyTorchModel(SimpleNet(), device="cpu")
+
+# 3. Create the gossip node
+node = GossipNode(
+    node_id="alice",
+    domain="mnist-vision",
+    model=model,
+    topology=RandomTopology(),
+    aggregation=FedAvg(weight_by="data_size"),
+    training_config=TrainingConfig(epochs=1, batch_size=32)
+)
+
+# 4. Load and split data
+loader = DatasetLoader()
+(X, y), info = loader.load_iris()
+
+splitter = FederatedDataSplitter(seed=42)
+splits = splitter.create_iid_split(X, y, num_nodes=5)
+my_data = splits[0]  # This node's data partition
+
+# 5. Run gossip learning
+async def main():
+    await node.start()
+    await node.run_continuous(data=my_data)
+
+asyncio.run(main())
+```
+
+## Public API
+
+### Core
+
+| Class | Description |
+|-------|-------------|
+| `GossipNode` | Main P2P gossip learning node with IPv8 networking |
+
+### Models
+
+| Class | Description |
+|-------|-------------|
+| `PyTorchModel` | Wrapper for PyTorch `nn.Module` |
+| `TensorFlowModel` | Wrapper for TensorFlow/Keras models |
+| `TrainingConfig` | Training configuration (epochs, batch_size, lr) |
+| `TrainingResult` | Training result with metrics |
+
+### Topology
+
+| Class | Description |
+|-------|-------------|
+| `RandomTopology` | Random peer selection strategy |
+| `CyclonTopology` | Scalable peer sampling (Cyclon algorithm) |
+| `PeerInfo` | Peer information dataclass |
+
+### Aggregation
+
+| Class | Description |
+|-------|-------------|
+| `FedAvg` | Federated Averaging aggregation |
+| `ModelAggregator` | Manages train→gossip→aggregate cycle |
+| `ModelUpdate` | Peer model update dataclass |
+
+### Data
+
+| Class | Description |
+|-------|-------------|
+| `DatasetLoader` | Load common datasets (CIFAR-10, Iris, etc.) |
+| `FederatedDataSplitter` | Create IID/Non-IID data splits |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                       GossipNode                            │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐  │
+│  │ PyTorchModel│  │RandomTopology│  │      FedAvg       │  │
+│  │ (or TF)     │  │ (or Cyclon)  │  │  (Aggregation)    │  │
+│  └─────────────┘  └──────────────┘  └───────────────────┘  │
+├─────────────────────────────────────────────────────────────┤
+│                    ModelAggregator                          │
+│              (Train → Gossip → Aggregate)                   │
+├─────────────────────────────────────────────────────────────┤
+│                     IPv8 Network Layer                      │
+│               (P2P, NAT Traversal, UDP)                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## License
+
+MIT License © 2025, 28 December - Ali Seyhan, Baki Turhan

quinkgl-0.1.2/README.md

@@ -0,0 +1,149 @@
+# QuinkGL: Gossip Learning Framework
+
+[![PyPI version](https://badge.fury.io/py/quinkgl.svg)](https://badge.fury.io/py/quinkgl)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+QuinkGL is a **decentralized, peer-to-peer (P2P) machine learning framework** designed to enable edge intelligence through Gossip Learning algorithms. Unlike traditional Federated Learning, which relies on a central server for aggregation, QuinkGL distributes the training and aggregation process across all participating nodes.
+
+## Key Features
+
+- **Decentralized Architecture** – No central parameter server required
+- **Gossip Learning** – Random walk and gossip-based aggregation for model convergence
+- **IPv8 Networking** – Native P2P communication with NAT traversal (UDP hole punching)
+- **Scalability** – Handles dynamic networks with node churn
+- **Framework-Agnostic** – Supports PyTorch and TensorFlow models
+- **Built-in Data Splitting** – IID and Non-IID data distribution utilities
+
+## Installation
+
+```bash
+pip install quinkgl
+```
+
+For development:
+
+```bash
+git clone https://github.com/aliseyhann/QuinkGL-Gossip-Learning-Framework.git
+cd QuinkGL-Gossip-Learning-Framework
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import asyncio
+import torch.nn as nn
+from quinkgl import (
+    GossipNode,
+    PyTorchModel,
+    RandomTopology,
+    FedAvg,
+    TrainingConfig,
+    DatasetLoader,
+    FederatedDataSplitter
+)
+
+# 1. Define your model
+class SimpleNet(nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.fc1 = nn.Linear(784, 128)
+        self.fc2 = nn.Linear(128, 10)
+        self.relu = nn.ReLU()
+    
+    def forward(self, x):
+        x = x.view(x.size(0), -1)
+        return self.fc2(self.relu(self.fc1(x)))
+
+# 2. Wrap the model
+model = PyTorchModel(SimpleNet(), device="cpu")
+
+# 3. Create the gossip node
+node = GossipNode(
+    node_id="alice",
+    domain="mnist-vision",
+    model=model,
+    topology=RandomTopology(),
+    aggregation=FedAvg(weight_by="data_size"),
+    training_config=TrainingConfig(epochs=1, batch_size=32)
+)
+
+# 4. Load and split data
+loader = DatasetLoader()
+(X, y), info = loader.load_iris()
+
+splitter = FederatedDataSplitter(seed=42)
+splits = splitter.create_iid_split(X, y, num_nodes=5)
+my_data = splits[0]  # This node's data partition
+
+# 5. Run gossip learning
+async def main():
+    await node.start()
+    await node.run_continuous(data=my_data)
+
+asyncio.run(main())
+```
+
+## Public API
+
+### Core
+
+| Class | Description |
+|-------|-------------|
+| `GossipNode` | Main P2P gossip learning node with IPv8 networking |
+
+### Models
+
+| Class | Description |
+|-------|-------------|
+| `PyTorchModel` | Wrapper for PyTorch `nn.Module` |
+| `TensorFlowModel` | Wrapper for TensorFlow/Keras models |
+| `TrainingConfig` | Training configuration (epochs, batch_size, lr) |
+| `TrainingResult` | Training result with metrics |
+
+### Topology
+
+| Class | Description |
+|-------|-------------|
+| `RandomTopology` | Random peer selection strategy |
+| `CyclonTopology` | Scalable peer sampling (Cyclon algorithm) |
+| `PeerInfo` | Peer information dataclass |
+
+### Aggregation
+
+| Class | Description |
+|-------|-------------|
+| `FedAvg` | Federated Averaging aggregation |
+| `ModelAggregator` | Manages train→gossip→aggregate cycle |
+| `ModelUpdate` | Peer model update dataclass |
+
+### Data
+
+| Class | Description |
+|-------|-------------|
+| `DatasetLoader` | Load common datasets (CIFAR-10, Iris, etc.) |
+| `FederatedDataSplitter` | Create IID/Non-IID data splits |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                       GossipNode                            │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐  │
+│  │ PyTorchModel│  │RandomTopology│  │      FedAvg       │  │
+│  │ (or TF)     │  │ (or Cyclon)  │  │  (Aggregation)    │  │
+│  └─────────────┘  └──────────────┘  └───────────────────┘  │
+├─────────────────────────────────────────────────────────────┤
+│                    ModelAggregator                          │
+│              (Train → Gossip → Aggregate)                   │
+├─────────────────────────────────────────────────────────────┤
+│                     IPv8 Network Layer                      │
+│               (P2P, NAT Traversal, UDP)                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## License
+
+MIT License © 2025, 28 December - Ali Seyhan, Baki Turhan

quinkgl-0.1.2/pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quinkgl"
+version = "0.1.2"
+description = "A decentralized gossip learning framework for P2P edge intelligence"
+readme = "README.md"
+authors = [
+  { name = "Ali Seyhan", email = "aliseyhan@posta.mu.edu.tr" },
+  { name = "Baki Turhan", email = "bakiturhan@posta.mu.edu.tr" }
+]
+license = { file = "LICENSE" }
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: System :: Distributed Computing",
+]
+keywords = ["gossip-learning", "federated-learning", "p2p", "decentralized-ai", "ipv8"]
+requires-python = ">=3.9"
+dependencies = [
+    # Core numerical computing
+    "numpy>=1.24.0",
+    # Deep learning
+    "torch>=2.0.0",
+    "torchvision>=0.15.0",
+    # Data handling
+    "scikit-learn>=1.0.0",
+    "pandas>=1.5.0",
+    # P2P networking
+    "pyipv8>=2.10.0",
+    # gRPC for communication
+    "grpcio>=1.50.0",
+    "grpcio-tools>=1.50.0",
+    "protobuf>=4.20.0",
+    # Safe serialization
+    "msgpack>=1.0.0",
+]
+
+[project.optional-dependencies]
+
+tensorflow = [
+    "tensorflow>=2.12.0",
+]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "black>=23.0.0",
+    "flake8>=6.0.0",
+    "mypy>=1.0.0",
+]
+all = [
+    "quinkgl[tensorflow]",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/aliseyhann/QuinkGL-Gossip-Learning-Framework"
+"Bug Tracker" = "https://github.com/aliseyhann/QuinkGL-Gossip-Learning-Framework/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["quinkgl*"]
+exclude = ["tests*", "scripts*", "docker*"]
+
+[tool.pyrefly]
+exclude = [
+    "archives",
+    "docker",
+    "docs",
+    "scripts",
+    "examples",
+
+    ".git",
+    "__pycache__",
+    "build",
+    "dist"
+]

quinkgl-0.1.2/requirements.txt

@@ -0,0 +1,42 @@
+# QuinkGL Requirements
+# Python 3.9+ required
+#
+# This file is auto-generated from pyproject.toml dependencies.
+# For development, use: pip install -e ".[dev]"
+# For all extras: pip install -e ".[all]"
+
+# Core numerical computing
+numpy>=1.24.0
+
+# Deep learning
+torch>=2.0.0
+torchvision>=0.15.0
+
+# Data handling
+scikit-learn>=1.0.0
+pandas>=1.5.0
+
+# P2P networking
+pyipv8>=2.10.0
+
+# gRPC for communication
+grpcio>=1.50.0
+grpcio-tools>=1.50.0
+protobuf>=4.20.0
+
+# Safe serialization (replaces pickle for security)
+msgpack>=1.0.0
+
+
+
+# Installation Notes:
+# ==================
+#
+# Standard installation:
+#   pip install -r requirements.txt
+#
+# Development installation:
+#   pip install -e ".[dev]"
+#
+# With all optional features:
+#   pip install -e ".[all]"

quinkgl-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

quinkgl-0.1.2/src/quinkgl/__init__.py

@@ -0,0 +1,122 @@
+"""
+QuinkGL: Decentralized Gossip Learning Framework
+
+A Python framework for decentralized machine learning using
+gossip-based peer-to-peer communication.
+
+Example:
+    from quinkgl import (
+        GossipNode,
+        PyTorchModel,
+        RandomTopology,
+        FedAvg,
+        TrainingConfig
+    )
+
+    model = PyTorchModel(my_pytorch_model)
+    node = GossipNode(
+        node_id="alice",
+        domain="health",
+        model=model,
+        topology=RandomTopology(),
+        aggregation=FedAvg()
+    )
+    await node.start()
+    await node.run_continuous(training_data)
+"""
+
+__version__ = "0.1.0"
+
+# =============================================================================
+# CORE - Main node class
+# =============================================================================
+from quinkgl.network.gossip_node import GossipNode
+
+# =============================================================================
+# MODELS - Framework-specific model wrappers
+# =============================================================================
+from quinkgl.models.base import (
+    ModelWrapper,
+    TrainingConfig,
+    TrainingResult
+)
+from quinkgl.models.pytorch import PyTorchModel
+
+# TensorFlow is optional - only import if available
+try:
+    from quinkgl.models.tensorflow import TensorFlowModel
+    _tensorflow_available = True
+except ImportError:
+    _tensorflow_available = False
+    TensorFlowModel = None  # type: ignore
+
+# =============================================================================
+# TOPOLOGY - Peer selection strategies
+# =============================================================================
+from quinkgl.topology.base import (
+    TopologyStrategy,
+    PeerInfo,
+    SelectionContext
+)
+from quinkgl.topology.random import RandomTopology
+from quinkgl.topology.cyclon import CyclonTopology
+
+# =============================================================================
+# AGGREGATION - Model combining strategies
+# =============================================================================
+from quinkgl.aggregation.base import (
+    AggregationStrategy,
+    ModelUpdate,
+    AggregatedModel
+)
+from quinkgl.aggregation.fedavg import FedAvg
+
+# =============================================================================
+# GOSSIP - Model aggregation orchestration
+# =============================================================================
+from quinkgl.gossip.orchestrator import ModelAggregator
+
+# =============================================================================
+# DATA - Dataset loading and splitting
+# =============================================================================
+from quinkgl.data.datasets import (
+    DatasetLoader,
+    FederatedDataSplitter,
+    DatasetInfo
+)
+
+# =============================================================================
+# PUBLIC API
+# =============================================================================
+__all__ = [
+    # Core
+    "GossipNode",
+    
+    # Models
+    "ModelWrapper",
+    "TrainingConfig",
+    "TrainingResult",
+    "PyTorchModel",
+    "TensorFlowModel",
+    
+    # Topology
+    "TopologyStrategy",
+    "RandomTopology",
+    "CyclonTopology",
+    "PeerInfo",
+    "SelectionContext",
+    
+    # Aggregation
+    "AggregationStrategy",
+    "FedAvg",
+    "ModelUpdate",
+    "AggregatedModel",
+    
+    # Gossip
+    "ModelAggregator",
+    
+    # Data
+    "DatasetLoader",
+    "FederatedDataSplitter",
+    "DatasetInfo",
+]

quinkgl-0.1.2/src/quinkgl/aggregation/__init__.py

@@ -0,0 +1,27 @@
+"""
+Aggregation Strategies Module
+
+This module provides pluggable aggregation strategies for combining
+model updates from multiple peers.
+
+Usage:
+    from quinkgl.aggregation import FedAvg
+
+    aggregator = FedAvg(weight_by="data_size")
+    aggregated = await aggregator.aggregate(updates)
+"""
+
+from quinkgl.aggregation.base import (
+    AggregationStrategy,
+    ModelUpdate,
+    AggregatedModel
+)
+from quinkgl.aggregation.fedavg import FedAvg
+
+# Export main classes
+__all__ = [
+    "AggregationStrategy",
+    "ModelUpdate",
+    "AggregatedModel",
+    "FedAvg",
+]