Metadata-Version: 2.4
Name: metafed-fl
Version: 1.0.0
Summary: Federated Learning for Metaverse Infrastructures with MARL, Privacy, and Sustainability
Home-page: https://github.com/afrilab/MetaFed-FL
Author: Muhammet Anil Yagiz, Zeynep Sude Cengiz, Polat Goktas
Author-email: Muhammet Anil Yagiz <anill.yagiz@gmail.com>, Zeynep Sude Cengiz <z.sude.cengiz@gmail.com>, Polat Goktas <polatgoktas@gmail.com>
License: MIT License
        
        Copyright (c) 2025 AFRI Lab
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/afrilab/MetaFed-FL
Project-URL: Documentation, https://github.com/afrilab/MetaFed-FL#readme
Project-URL: Repository, https://github.com/afrilab/MetaFed-FL
Project-URL: Bug Tracker, https://github.com/afrilab/MetaFed-FL/issues
Keywords: federated learning,machine learning,distributed systems,privacy preserving,multi-agent reinforcement learning,carbon aware computing,sustainable AI,metaverse,PyTorch
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.2.2
Requires-Dist: torchvision>=0.17.2
Requires-Dist: numpy>=1.26.4
Requires-Dist: pandas>=2.2.2
Requires-Dist: matplotlib>=3.9.2
Requires-Dist: timm>=1.0.8
Requires-Dist: pyyaml>=6.0
Requires-Dist: tqdm>=4.64.0
Requires-Dist: scikit-learn>=1.1.0
Requires-Dist: seaborn>=0.11.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=2.20.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.19.0; extra == "docs"
Requires-Dist: myst-parser>=0.18.0; extra == "docs"
Provides-Extra: experiments
Requires-Dist: jupyter>=1.0.0; extra == "experiments"
Requires-Dist: jupyterlab>=3.4.0; extra == "experiments"
Requires-Dist: ipywidgets>=8.0.0; extra == "experiments"
Requires-Dist: plotly>=5.10.0; extra == "experiments"
Provides-Extra: privacy
Requires-Dist: opacus>=1.4.0; extra == "privacy"
Provides-Extra: all
Requires-Dist: pytest>=7.0.0; extra == "all"
Requires-Dist: pytest-cov>=4.0.0; extra == "all"
Requires-Dist: pytest-xdist>=3.0.0; extra == "all"
Requires-Dist: black>=22.0.0; extra == "all"
Requires-Dist: flake8>=5.0.0; extra == "all"
Requires-Dist: isort>=5.10.0; extra == "all"
Requires-Dist: mypy>=1.0.0; extra == "all"
Requires-Dist: pre-commit>=2.20.0; extra == "all"
Requires-Dist: sphinx>=5.0.0; extra == "all"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "all"
Requires-Dist: sphinx-autodoc-typehints>=1.19.0; extra == "all"
Requires-Dist: myst-parser>=0.18.0; extra == "all"
Requires-Dist: jupyter>=1.0.0; extra == "all"
Requires-Dist: jupyterlab>=3.4.0; extra == "all"
Requires-Dist: ipywidgets>=8.0.0; extra == "all"
Requires-Dist: plotly>=5.10.0; extra == "all"
Requires-Dist: opacus>=1.4.0; extra == "all"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# MetaFed-FL: Federated Learning for Metaverse Systems

<div align="center">

<!-- Status and Quality Badges -->
![Build Status](https://img.shields.io/badge/build-passing-brightgreen)
![Python Version](https://img.shields.io/badge/python-3.9+-blue)
![PyTorch](https://img.shields.io/badge/PyTorch-2.2.2-orange)
![Code Quality](https://img.shields.io/badge/code%20quality-A-green)

<!-- Project Information Badges -->
![License](https://img.shields.io/badge/license-MIT-blue)
![Version](https://img.shields.io/badge/version-1.0.0-green)
![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-lightgrey)

<!-- Research and Academic Badges -->
![Paper](https://img.shields.io/badge/paper-arXiv-red)
![Conference](https://img.shields.io/badge/conference-pending-yellow)
![Framework](https://img.shields.io/badge/framework-federated%20learning-purple)

</div>

---

## 🔬 Research Overview

**MetaFed** is a cutting-edge federated learning (FL) framework specifically designed for **Metaverse infrastructures**. This research addresses the critical challenges of privacy, performance, and sustainability in distributed AI systems.

**Paper:** *MetaFed: Advancing Privacy, Performance, and Sustainability in Federated Metaverse Systems*  
**Authors:** Muhammet Anil Yagiz, Zeynep Sude Cengiz, Polat Goktas (2025)

🌐 **[Visit Project Website](https://metafed.vercel.app)** - Interactive demos, tutorials, and detailed documentation

---

## 🛠️ Installation

### Prerequisites

- **Python 3.9+**
- **PyTorch 2.2.2+**
- **CUDA** (optional, for GPU acceleration)

### Dependencies

```bash
# Core dependencies
pip install torch>=2.2.2 torchvision>=0.17.2
pip install numpy>=1.26.4 pandas>=2.2.2
pip install matplotlib>=3.9.2 timm>=1.0.8

# Development dependencies
pip install -r requirements-dev.txt
```

### Package Installation

```bash
# Install as editable package
pip install -e .

# Or install from PyPI (when available)
pip install metafed-fl
```

---

## 🚀 Quick Start

```bash
# Clone the repository
git clone https://github.com/afrilab/MetaFed-FL.git
cd MetaFed-FL

# Install dependencies
pip install -r requirements.txt

# Run MNIST experiment
python -m experiments.mnist.run_experiment

# Run CIFAR-10 experiment
python -m experiments.cifar10.run_experiment
```

---

## 📊 Key Features

🤖 **Multi-Agent Reinforcement Learning (MARL)**
- Dynamic client orchestration and selection
- Adaptive resource allocation
- Intelligent scheduling algorithms

🔒 **Privacy-Preserving Techniques**
- Homomorphic encryption for secure aggregation
- Differential privacy for data protection
- Zero-knowledge proof mechanisms

🌱 **Carbon-Aware Scheduling**
- Real-time carbon intensity tracking
- Renewable energy-aligned orchestration
- Sustainable resource management

📈 **Comprehensive Benchmarks**
- MNIST with ResNet-18 architecture
- CIFAR-10 with ResNet-18 architecture
- Multiple federated learning algorithms
- Extensive performance metrics

---

## 📈 Performance Metrics

| Dataset | Algorithm | Accuracy Improvement | CO2 Reduction | Efficiency Gain |
|---------|-----------|---------------------|---------------|----------------|
| MNIST   | FedAvg+MARL | +15% | -35% | +20% |
| CIFAR-10| FedProx+MARL| +20% | -45% | +25% |
| CIFAR-10| SCAFFOLD+MARL| +18% | -40% | +22% |

*Compared to baseline federated learning algorithms*

---

## 📂 Project Structure

```
MetaFed-FL/
├── src/metafed/              # Core package
│   ├── core/                 # FL core components
│   ├── algorithms/           # FL algorithms
│   ├── orchestration/        # MARL orchestration
│   ├── privacy/              # Privacy mechanisms
│   ├── green/                # Carbon-aware features
│   └── utils/                # Utilities
├── experiments/              # Experiment runners
│   ├── mnist/                # MNIST experiments
│   └── cifar10/              # CIFAR-10 experiments
├── tests/                    # Test suite
├── docs/                     # Documentation
└── scripts/                  # Utility scripts
```

---

## 🧪 Running Experiments

### Command Line Interface

```bash
# MNIST with FedAvg + MARL
metafed-mnist --algorithm fedavg --orchestrator rl --rounds 100

# CIFAR-10 with privacy preservation
metafed-cifar10 --algorithm fedprox --privacy differential --epsilon 1.0

# Green-aware scheduling
metafed-mnist --green-aware --carbon-tracking
```

### Configuration Files

```bash
# Using YAML configuration
python -m experiments.mnist.run_experiment --config configs/fedavg_privacy.yaml
```

### Jupyter Notebooks (Legacy)

```bash
# For research and exploration
jupyter notebook experiments/notebooks/
```

---

## 🔧 Advanced Configuration

### Algorithm Selection

- **FedAvg**: Standard federated averaging
- **FedProx**: Proximal federated optimization
- **SCAFFOLD**: Stochastic controlled averaging

### Orchestration Methods

- **Random**: Random client selection
- **RL-based**: Multi-agent reinforcement learning
- **Green-aware**: Carbon-optimized selection

### Privacy Settings

- **Homomorphic Encryption**: Secure aggregation
- **Differential Privacy**: ε-differential privacy
- **Hybrid**: Combined privacy mechanisms

---

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

```bash
# Clone and setup development environment
git clone https://github.com/afrilab/MetaFed-FL.git
cd MetaFed-FL
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run linting
flake8 src/ tests/
black src/ tests/
```

### Code Style

- **Black** for code formatting
- **Flake8** for linting
- **isort** for import sorting
- **Type hints** for better code documentation

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 📝 Citation

If you use MetaFed-FL in your research, please cite:

```bibtex
@misc{yagiz2025metafedadvancingprivacyperformance,
  title={MetaFed: Advancing Privacy, Performance, and Sustainability in Federated Metaverse Systems},
  author={Muhammet Anil Yagiz and Zeynep Sude Cengiz and Polat Goktas},
  year={2025},
  eprint={2508.17341},
  archivePrefix={arXiv},
  primaryClass={cs.LG},
  url={https://arxiv.org/abs/2508.17341}
}
```

---

## 🌟 Acknowledgments

- **AFRI Lab** for supporting this research
- **PyTorch Team** for the excellent deep learning framework
- **Federated Learning Community** for inspiration and collaboration

---

<div align="center">

**[🌐 Website](https://metafed.vercel.app)**

*Built with ❤️ for the Federated Learning Community*

</div>
