Metadata-Version: 2.4
Name: fairswarm
Version: 0.6.1
Summary: Provably fair particle swarm optimization for federated learning coalition selection
Project-URL: Homepage, https://github.com/dataeducator/fairswarm-library
Project-URL: Documentation, https://github.com/dataeducator/fairswarm-library#readme
Project-URL: Issues, https://github.com/dataeducator/fairswarm-library/issues
Project-URL: Source, https://github.com/dataeducator/fairswarm-library
Author-email: Tenicka Norwood <tenicka.norwood@gmail.com>
License-Expression: LicenseRef-PolyForm-Noncommercial-1.0.0
License-File: LICENSE.md
Keywords: fairness,federated-learning,healthcare,machine-learning,particle-swarm-optimization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
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: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: numpy>=1.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: typing-extensions>=4.0.0; python_version < '3.10'
Provides-Extra: dev
Requires-Dist: hypothesis>=6.82.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pre-commit>=3.4.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: flower
Requires-Dist: flwr>=1.5.0; extra == 'flower'
Provides-Extra: full
Requires-Dist: flwr>=1.5.0; extra == 'full'
Requires-Dist: hypothesis>=6.82.0; extra == 'full'
Requires-Dist: mypy>=1.5.0; extra == 'full'
Requires-Dist: pre-commit>=3.4.0; extra == 'full'
Requires-Dist: pytest-cov>=4.1.0; extra == 'full'
Requires-Dist: pytest>=7.4.0; extra == 'full'
Requires-Dist: ruff>=0.1.0; extra == 'full'
Description-Content-Type: text/markdown

# FairSwarm

> Provably fair particle swarm optimization for federated learning coalition selection

[![License](https://img.shields.io/badge/License-PolyForm_Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

## Overview

**FairSwarm** is a novel particle swarm optimization algorithm designed for fair client selection in federated learning. It provides provable guarantees on both convergence and demographic fairness.

### Key Innovation

FairSwarm introduces a **fairness-aware velocity update** that steers optimization toward demographically balanced coalitions:

```
v = ω·v + c₁·r₁·(pBest - x) + c₂·r₂·(gBest - x) + c₃·∇_fair
                                                    ^^^^^^^^
                                                    Novel fairness gradient
```

### Theoretical Guarantees

| Theorem | Guarantee |
|---------|-----------|
| **Theorem 1** | Convergence to stationary point with probability 1 |
| **Theorem 2** | ε-fairness: DemDiv(S*) ≤ ε with high probability |
| **Theorem 3** | (1-1/e-η) approximation for submodular objectives |
| **Theorem 4** | Privacy-fairness tradeoff lower bound |

## Data Access and Compliance

This library contains **no patient data**. Examples and tests use only
synthetic data generated by `create_synthetic_clients()`.

Experiments on restricted clinical datasets (MIMIC-III, eICU-CRD) require
that **you** independently obtain credentialed access:

1. Complete CITI "Data or Specimens Only Research" training.
2. Sign the PhysioNet Data Use Agreement at
   <https://physionet.org/about/database/>.
3. Download MIMIC-III / eICU under your own credentials.
4. Place derived cohort files **outside** the repository tree, or in a
   path covered by `.gitignore` (`data/processed/`, `data/raw/`).
5. Set the `MIMIC_DATA_PATH` (or `EICU_DATA_PATH`) environment variable
   to point the experiment scripts at your local data.

**Do NOT commit, redistribute, or share patient-level data in any form.**
You are solely responsible for compliance with the PhysioNet DUA, HIPAA,
and your institution's IRB requirements.

The full threat model — what the server sees, what is **out of scope**
(malicious servers, sybil clients, model inversion, side-channel
attacks), and how the package's privacy claims align with HIPAA Safe
Harbor / GDPR / PhysioNet DUA / All of Us terms — is in
[THREAT_MODEL.md](THREAT_MODEL.md).

## Installation

```bash
pip install fairswarm
```

For development:
```bash
pip install fairswarm[dev]
```

## Quick Start

```python
from fairswarm import FairSwarm, FairSwarmConfig, Client
from fairswarm.demographics import DemographicDistribution, CensusTarget
import numpy as np

# Create clients (hospitals) with demographic information
clients = [
    Client(
        id=f"hospital_{i}",
        demographics=np.random.dirichlet([2, 2, 2, 2]),
        dataset_size=1000 + i * 100,
    )
    for i in range(20)
]

# Configure the optimizer
config = FairSwarmConfig(
    swarm_size=30,
    max_iterations=100,
    coalition_size=10,
    fairness_weight=0.3,  # λ in fitness function
    seed=42,
)

# Create target demographics (e.g., US Census 2020)
target = DemographicDistribution.from_dict({
    "white": 0.576,
    "black": 0.124,
    "hispanic": 0.187,
    "asian": 0.061,
    "other": 0.052,
})

# Run optimization
optimizer = FairSwarm(
    clients=clients,
    coalition_size=10,
    target_demographics=target,
    config=config,
)
# Use built-in demographic fitness (or supply your own callable)
from fairswarm.fitness import DemographicFitness
fitness_fn = DemographicFitness(target=target)

result = optimizer.optimize(fitness_fn)

# Check results
print(f"Selected coalition: {result.coalition}")
print(f"Fitness: {result.fitness:.4f}")
print(f"ε-fair: {result.is_epsilon_fair(0.05)}")
```

## Documentation

Full API documentation is available in the source code docstrings. For the formal algorithm specification, theoretical proofs, and experimental methodology, please refer to:

> T. Norwood, D. Das, P. Chatterjee, E. Bentley, and U. Ghosh, "FairSwarm: Trustworthy Coalition Selection for Fair
and Secure Federated Intelligence," *IEEE Trans. Consum. Electron.*, 2026.
> note : Submitted

## Citation

If you use this library or its results, please cite the article
(preferred — the one that carries the formal theorems) and, if
relevant, the specific software release.

```bibtex
@article{norwood2026fairswarm,
  title   = {FairSwarm: Trustworthy Coalition Selection for Fair
             and Secure Federated Intelligence},
  author  = {Norwood, Tenicka and Das, D. and Chatterjee, P. and
             Bentley, E. and Ghosh, U.},
  journal = {IEEE Transactions on Consumer Electronics},
  year    = {2026},
  note    = {Submitted}
}
```

`CITATION.cff` backs GitHub's "Cite this repository" button and points
at the same record.

## License

This project is licensed under the [PolyForm Noncommercial License 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/). You are free to use, modify, and distribute it for any noncommercial purpose, including academic research, education, and personal projects.

**Commercial licensing is available.** For commercial use inquiries, please contact [Tenicka Norwood](mailto:tenicka.norwood@gmail.com).

See [LICENSE](LICENSE) for full terms.
