Metadata-Version: 2.4
Name: krum
Version: 0.9.0
Summary: Byzantine-resilient aggregation rules for distributed machine learning.
Author-email: Sébastien Rouault <sebastien.rouault@alumni.epfl.ch>, Arthur Danjou <arthur.danjou@dauphine.eu>, Mohamad Ammar Said <mohamad-ammar.said@polytechnique.edu>
License-Expression: MIT
Project-URL: Homepage, https://github.com/calicarpa/krum
Project-URL: Documentation, https://calicarpa.github.io/krum/
Project-URL: Repository, https://github.com/calicarpa/krum
Project-URL: Issues, https://github.com/calicarpa/krum/issues
Keywords: byzantine-fault-tolerance,distributed-machine-learning,federated-learning,robust-aggregation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.13.0
Requires-Dist: torchvision>=0.28.0
Provides-Extra: experiments
Requires-Dist: matplotlib>=3.10.0; extra == "experiments"
Requires-Dist: numpy>=2.0.0; extra == "experiments"
Requires-Dist: pandas>=2.2.0; extra == "experiments"
Requires-Dist: seaborn>=0.13.0; extra == "experiments"
Provides-Extra: dev
Requires-Dist: pandas>=2.2.0; extra == "dev"
Requires-Dist: pandas-stubs~=3.0.2; extra == "dev"
Requires-Dist: pre-commit>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.15.22; extra == "dev"
Requires-Dist: ty>=0.0.61; extra == "dev"
Requires-Dist: sphinx>=8.1.3; extra == "dev"
Requires-Dist: sphinx-copybutton>=0.5.2; extra == "dev"
Requires-Dist: sphinx-favicon>=1.0.1; extra == "dev"
Requires-Dist: sphinx-togglebutton>=0.3.2; extra == "dev"
Requires-Dist: sphinx-contributors>=0.3.0; extra == "dev"
Requires-Dist: shibuya>=2026.7.12; extra == "dev"
Dynamic: license-file

# Krum

**Byzantine-resilient aggregation rules for distributed machine learning.**

Krum provides a modular framework for implementing, comparing, and evaluating
Byzantine-resilient Gradient Aggregation Rules (GARs) for distributed learning.
It ships with state-of-the-art aggregation rules, attack strategies, and
IID/non-IID data partitioning.

## Documentation

The reference documentation is available at
[calicarpa.github.io/krum](https://calicarpa.github.io/krum/).

## Quickstart

```python
import torch
from krum.primitives.aggregators.average import Average
from krum.primitives.aggregators.krum import Krum
from krum.primitives.attacks.gaussian import GaussianAttack

# Simulate gradients from 10 workers (8 honest, 2 Byzantine)
honest = torch.randn(8, 100)
byzantine = GaussianAttack.generate(honest, f=2, std=10.0)
gradients = torch.cat([honest, byzantine], dim=0)

# Compare robust vs naive aggregation
robust = Krum.aggregate(gradients, n=10, f=2)
naive = Average.aggregate(gradients)

print(f"Krum result norm:   {robust.norm().item():.4f}")
print(f"Average result norm: {naive.norm().item():.4f}")
```

## Installation

### Supported Python versions

This project supports Python **3.12 through 3.14**.

### From PyPI

```bash
pip install krum
```

This installs **PyTorch**, **torchvision**, and **pandas**. Additional
dependencies (``matplotlib``, ``numpy``, ``seaborn``) are required for running experiments
and visualisations:

```bash
pip install "krum[experiments]"
```

With `uv` (Recommended):

```bash
uv pip install krum
# or directly in a uv project
uv add krum
uv add "krum[experiments]"  # with optional experiment deps
```

### From source

For development or if you want to modify the source, clone the repository and
install in editable mode with the development dependencies:

```bash
git clone https://github.com/calicarpa/krum.git
cd krum
pip install -e ".[dev,experiments]"
```

With `uv` (Recommended):

```bash
git clone https://github.com/calicarpa/krum.git
cd krum
uv sync --all-extras --all-groups
```

This installs all linting, type-checking, and documentation tools.

## Features

- **11 aggregation rules**: Average, Median, Trimmed Mean, Krum, MultiKrum,
  Bulyan, Brute, GeometricMedian, Medoid, Aksel, Nearest Neighbor Average
- **5 attack strategies**: SignFlip, ALIE, Gaussian, FullGradientNegation,
  SmallPerturbation
- **Data partitioning**: IID and non-IID per-worker splits via a single
  `DataPartitioner` interface — `IidPartitioner`, `DirichletPartitioner`,
  `PerLabelsPartitioner`, `MixingPartitioner` — returning one
  `Sequence[Dataset]` per worker from a stateless `partition()` classmethod
- **Zero-copy model wrapper**: Flat parameter/gradient views via
  `krum.primitives.Model`
- **Stateless design**: Aggregators, attacks, and partitioners are
  classmethods, no instantiation needed

## Contributing

### Linting, formatting, and type-checking

This project uses [Ruff](https://docs.astral.sh/ruff/) for unified linting and
formatting, and [ty](https://github.com/astral-sh/ty) for type-checking.

```bash
ruff format .
ruff check --fix .
ty check
```

### Pre-commit hooks

```bash
pre-commit install
```

### Running tests

Tests use [pytest](https://docs.pytest.org/) and are located under `tests/`.

```bash
uv run pytest tests/ -v
uv run pytest tests/primitives/aggregators/ -v
```

Tests run automatically on every push and pull request via GitHub Actions
(Python 3.12–3.14).

### Documentation

Build the documentation locally:

```bash
cd docs
make html  # Build HTML documentation
make watch # Watch for changes and auto-rebuild
make serve # Build and serve on port 8000
make clean # Remove generated files
```

## License

MIT License — see [LICENSE](LICENSE).
