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.

Quickstart

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

pip install krum

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

pip install "krum[experiments]"

With uv (Recommended):

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:

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

With uv (Recommended):

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 for unified linting and formatting, and ty for type-checking.

ruff format .
ruff check --fix .
ty check

Pre-commit hooks

pre-commit install

Running tests

Tests use pytest and are located under tests/.

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:

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.