krum 0.9.0__tar.gz

krum-0.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Distributed Computing Laboratory, EPFL
+
+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.

krum-0.9.0/PKG-INFO

@@ -0,0 +1,188 @@
+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).

krum-0.9.0/README.md

@@ -0,0 +1,146 @@
+# 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).

krum-0.9.0/krum/__init__.py

@@ -0,0 +1,22 @@
+"""Krum — Byzantine-resilient aggregation rules for distributed machine learning.
+
+The package is organized in two layers:
+
+* :mod:`krum.primitives.aggregators` exposes stateless, classmethod-based
+  Gradient Aggregation Rules (GARs).
+* :mod:`krum.primitives.attacks` exposes gradient attacks that simulate Byzantine
+  workers when evaluating the robustness of an aggregator.
+* :mod:`krum.primitives.models` provides a :class:`~krum.primitives.models.Model`
+  wrapper that exposes a ``torch.nn.Module``'s parameters and gradients as
+  zero-copy flat tensors, which is the data layout the aggregators consume.
+
+The :mod:`krum.simulations` package ships the original training simulations
+from the papers that introduced each rule.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("krum")
+except PackageNotFoundError:
+    __version__ = "0.0.0"  # Running from source without installation