Metadata-Version: 2.4
Name: swarmfl
Version: 0.1.0
Summary: Federated multi-agent research framework for authorized specialist consultation
Author: SwarmFL contributors
License-Expression: Apache-2.0
Project-URL: Documentation, https://github.com/saadbinather/SwarmFL#readme
Project-URL: Issues, https://github.com/saadbinather/SwarmFL/issues
Project-URL: Repository, https://github.com/saadbinather/SwarmFL
Keywords: federated-learning,flower,multi-agent,machine-learning,research
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: flwr[simulation]==1.40.0
Requires-Dist: numpy<3,>=2.1
Requires-Dist: pydantic<3,>=2.9
Requires-Dist: torch<2.15,>=2.5
Provides-Extra: research
Requires-Dist: pandas<4,>=2.2; extra == "research"
Requires-Dist: scikit-learn<2,>=1.5; extra == "research"
Requires-Dist: ucimlrepo==0.0.7; extra == "research"
Provides-Extra: qwen
Requires-Dist: requests<3,>=2.32; extra == "qwen"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pip-audit<3,>=2.7; extra == "dev"
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: ruff<1,>=0.11; extra == "dev"
Requires-Dist: twine<7,>=6; extra == "dev"
Provides-Extra: all
Requires-Dist: pandas<4,>=2.2; extra == "all"
Requires-Dist: requests<3,>=2.32; extra == "all"
Requires-Dist: scikit-learn<2,>=1.5; extra == "all"
Requires-Dist: ucimlrepo==0.0.7; extra == "all"
Dynamic: license-file

 <div align="center">
  <img src="resources/swarmfl-logo-transparent.png" alt="SwarmFL" width="600">
</div>

[![CI](https://github.com/saadbinather/SwarmFL/actions/workflows/ci.yml/badge.svg)](https://github.com/saadbinather/SwarmFL/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/swarmfl)](https://pypi.org/project/swarmfl/)
[![Python](https://img.shields.io/pypi/pyversions/swarmfl)](https://pypi.org/project/swarmfl/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)

**SwarmFL** is an experimental Python framework for federated multi-agent learning. It enables independently managed specialists to collaborate through Flower, with cost-aware consultation, dynamic prediction fusion, feedback-driven updates, and version control.

## Features

- **Specialist Registry:** Register heterogeneous specialists with explicit compatibility and authorization contracts.
- **Intelligent Routing:** Select eligible specialists using fixed, learned, or graph-inspired routing policies under consultation costs.
- **Federated Collaboration:** Execute selected-only consultations using Flower.
- **Dynamic Fusion:** Combine predictions through mean, reliability-weighted, or DeepSets fusion.
- **Feedback Learning:** Support authenticated delayed feedback and federated shared-parameter updates.
- **Version Control:** Validate, activate, reject, and roll back learned policies.

## Installation

Install from PyPI:

```bash
pip install swarmfl
```

*Note: SwarmFL v0.1.0 is awaiting publication. Until then, install the released alpha using `pip install --pre swarmfl`.*

For source installation:

```bash
git clone https://github.com/saadbinather/SwarmFL.git
cd SwarmFL
pip install -e .
```

Python 3.11–3.13 is supported. A virtual environment is recommended.

## Quickstart

Run the synthetic CPU demonstration:

```bash
swarmfl-quickstart --output demo --feedback
```

The example runs three Flower clients and demonstrates selected-only consultation, prediction fusion, feedback verification, version activation and rollback.

Results are saved to `demo/result.json`.

## Documentation

- [Architecture](docs/architecture.md)
- [Custom Specialist Example](examples/custom_specialist.py)
- [Research](research/README.md)
- [Experimental Results](research/results.md)
- [Limitations](docs/limitations.md)
- [Security](SECURITY.md)

## Research

SwarmFL includes research implementations and experimental results for federated specialist collaboration.

Some datasets, model checkpoints, and internal scripts are intentionally excluded from public distributions.

SwarmFL is research software and is not validated for clinical deployment or formal privacy guarantees.


## Authors

Maintained by [Saad](https://github.com/saadbinather), [Ali Hassan](https://github.com/Alihassan0155), and [Saif](https://github.com/rajasaifr).

## License

Licensed under the [Apache License 2.0](LICENSE). 
