Merge pull request #21 from calicarpa/9-feature-pip-installable

Reviewed with Peva

Author: ArthurDanjou

.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Cache native builds
+        uses: actions/cache@v5.0.5
+        with:
+          path: krum/native
+          key: native-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('krum/native/**/*.cpp', 'krum/native/**/*.cu', 'krum/native/**/*.hpp', 'uv.lock') }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Check imports (no deprecation warnings)
+        run: |
+          uv run python -W error::DeprecationWarning -W error::PendingDeprecationWarning -c "from krum import tools, experiments, aggregators, attacks"
+          uv run python -W error::DeprecationWarning -W error::PendingDeprecationWarning -c "import krum.tools, krum.experiments, krum.aggregators, krum.attacks"

.github/workflows/documentation.yml

@@ -1,9 +1,7 @@
 name: Build and Deploy Documentation
 
 on:
-  push:
-    branches:
-      - main
+  workflow_dispatch:
 
 permissions:
   contents: read
@@ -32,7 +30,7 @@ jobs:
           python-version-file: "pyproject.toml"
 
       - name: Install dependencies
-        run: uv sync --group docs
+        run: uv sync --extra dev
 
       - name: Build documentation
         run: uv run sphinx-build -b html docs docs/_build/html

.github/workflows/release.yml

@@ -0,0 +1,25 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  pypi:
+    name: Build & Publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Required for trusted publishing (recommended)
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -3,17 +3,21 @@
 
 # Except directories, placeholders, gitignores, LICENSE, Markdown files and Python sources
 !*/
+!krum/*
 !.placeholder
 !.gitignore
 !LICENSE
 !*.md
 !*.py
 !*.toml
 !.python-version
+!uv.lock
+!.pre-commit-config.yaml
 
 # Except documentation files
 docs/_build
 !*.rst
+!Makefile
 !*.html
 !*.css
 !*.js
@@ -24,4 +28,4 @@ docs/_build
 !*.yml
 
 # IDE stuff
-.idea
+.idea

.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.12
+    hooks:
+      - id: ruff
+        args: [--fix]
+        files: ^krum/
+      - id: ruff-format

.python-version

@@ -1 +1 @@
->=3.10
+>=3.10, <3.15

README.md

@@ -13,19 +13,46 @@ This project implements various Byzantine-resilient Gradient Aggregation Rules (
 - **Extensible**: Easy to add new aggregation rules or attacks.
 - **High-performance**: Optional native C++ backend for Krum.
 
+## Supported Python versions
+
+This project supports Python **3.10 through 3.14**.
+
 ## Installation
 
-This project uses `uv` for dependency management.
+### From PyPI
+
+```bash
+pip install krum
+```
+
+With `uv` (Recommended):
 
 ```bash
-# Clone the repository
-git clone https://github.com/your-username/krum.git
+uv pip install krum
+# or directly in a uv project
+uv add krum
+```
+
+### 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]"
+```
+
+With `uv` (Recommended):
 
-# Install dependencies
-uv pip install -e .
+```bash
+git clone https://github.com/calicarpa/krum.git
+cd krum
+uv sync --extra dev
 ```
 
+This installs all linting, type-checking, and documentation tools.
+
 ## Usage
 
 You can run training simulations using `train.py`. The script accepts numerous arguments to configure the experiment.
@@ -71,6 +98,45 @@ uv run python train.py \
 
 - *in progress*
 
+## 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.
+
+Run the formatter and linter:
+
+```bash
+ruff format .
+ruff check --fix .
+```
+
+Run the type checker:
+
+```bash
+ty check
+```
+
+### Pre-commit hooks
+
+Install pre-commit hooks to block non-compliant commits:
+
+```bash
+pre-commit install
+```
+
+### Documentation
+
+Build the documentation locally:
+
+```bash
+cd docs
+make html  # 
+make watch # 
+make serve # 
+make clean # 
+```
+
 ## License
 
-See [LICENSE](LICENSE) for details.
+MIT License — see [LICENSE](LICENSE).

docs/Makefile

@@ -1,22 +1,25 @@
 # Makefile for Krum documentation
 
-.PHONY: help html clean servedocs live watch
+.PHONY: help html build clean serve watch
 
 help:
 	@echo "Available targets:"
 	@echo "  html       - Build HTML documentation"
+	@echo "  build      - Build HTML documentation (alias for html)"
 	@echo "  clean      - Remove generated files"
-	@echo "  servedocs  - Build and serve static documentation"
+	@echo "  serve      - Build and serve static documentation"
 	@echo "  watch      - Watch for changes and serve (auto-rebuild)"
 
 html:
 	uv run sphinx-build -b html . _build/html
 
+build: html
+
 clean:
 	rm -rf _build
 
-servedocs:
+serve:
 	uv run sphinx-build -b html . _build/html && uv run python -m http.server 8000 -d _build/html
 
 watch:
-	uv run sphinx-autobuild -b html . _build/html --port 8000 --host 127.0.0.1
+	uv run sphinx-autobuild -b html . _build/html --port 8000 --host 127.0.0.1

docs/_static/custom.css

@@ -16,4 +16,9 @@
 
 .bd-toc .page-toc + .sidebar-secondary-item {
     display: none;
+}
+
+/* Contributions Avatar */
+.sphinx-contributors img {
+    border-radius: 50%;
 }

docs/conf.py

@@ -6,11 +6,16 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
+import importlib
 import os
 import sys
 
 sys.path.insert(0, os.path.abspath(".."))
 
+# Make krum submodules available as top-level imports for autodoc compatibility
+for _mod in ("aggregators", "attacks", "experiments", "native", "tools"):
+    sys.modules[_mod] = importlib.import_module(f"krum.{_mod}")
+
 project = "Krum, the Library"
 copyright = "2026"
 author = "Peva BLANCHARD, Arthur DANJOU, El-Mahdi EL-MHAMDI, Sébastien ROUAULT, Mohammed Ammar SAID"
@@ -30,9 +35,10 @@
     "sphinx.ext.intersphinx",
     "sphinx_favicon",
     "sphinx_togglebutton",
-    "sphinx_contributors"
+    "sphinx_contributors",
 ]
 
+
 def linkcode_resolve(domain, info):
     """Return a URL to the source code on GitHub for the given object."""
     if domain != "py":
@@ -90,9 +96,7 @@ def linkcode_resolve(domain, info):
 
 
 # Use MathJax to render math in HTML
-mathjax_path = (
-    "https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
-)
+mathjax_path = "https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
 
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
@@ -158,7 +162,7 @@ def linkcode_resolve(domain, info):
                 {
                     "title": "How to add a custom dataset",
                     "url": "how-to/add-custom-dataset",
-                }
+                },
             ],
         },
         {