Development and contributing#

This is the single contributor page: environment setup, the test and lint gates, commit and PR rules, a map of the repository, and the guidelines for examples and documentation. Read it before making your first change to KonfAI or its docs. The recommended path uses Pixi, which manages Python packages, system libraries, and task runners in a single reproducible environment.

All commands on this page assume your working directory is the root of a cloned KonfAI checkout.

Prerequisites#

  • Python 3.10 or later — the minimum version declared in pyproject.toml

  • Pixi — install once with:

    curl -fsSL https://pixi.sh/install.sh | bash

    See pixi.sh for alternative installers.

  • git

Clone and install#

git clone https://github.com/vboussot/KonfAI.git
cd KonfAI
pixi install       # resolves and installs all Pixi environments

pixi install creates isolated environments under .pixi/ and does not touch your system Python or any other virtual environment.

Repository map#

Where each part of the codebase lives:

Package

Responsibility

konfai.main

CLI entrypoints for low-level workflows and cluster mode

konfai.trainer

Training workflow and training loop

konfai.predictor

Prediction workflow and export logic

konfai.evaluator

Evaluation workflow and metric export

konfai.data

Dataset discovery, transforms, augmentations, and patching

konfai.network

Model graph composition, optimizer/scheduler loaders, criterion routing

konfai.metric

Metrics, losses, and schedulers

konfai.utils

Config system, dataset helpers, distributed runtime utilities

konfai_apps

Standalone package for local/remote app execution and app server

Note

konfai_apps lives in konfai-apps/ with its own pyproject.toml, dependencies, and tests — it is installed and tested separately from the core package (see below).

Available tasks#

Run tasks with pixi run <task>:

Task

Command

Description

test

pytest -q tests/

Run the full test suite

test-cov

pytest --cov=konfai tests/

Run tests with coverage report

lint

ruff check konfai konfai-apps/konfai_apps

Lint the source tree

format

ruff format konfai konfai-apps/konfai_apps

Auto-format source files

format-check

ruff format --check ...

Check formatting without modifying files

typecheck

mypy konfai --ignore-missing-imports

Static type checking

build

python -m build

Build sdist and wheel

check

lint + format-check + test

Full pre-push gate — run before finishing any change

Always run pixi run check before pushing or opening a PR.

pip fallback#

If Pixi is unavailable, use an editable pip install:

pip install -e ".[dev]"
pytest -q tests/
ruff check konfai
ruff format konfai

Pre-commit hooks#

The repository ships a .pre-commit-config.yaml with both source-file checks and commit-message validation. Install both hook types once:

# with Pixi:
pixi run pre-commit-install

# or with pip:
python -m pip install pre-commit
pre-commit install --hook-type pre-commit --hook-type commit-msg

After installation, git commit runs file checks plus Conventional Commit and forbidden-branding validation. Run all file checks manually with:

pre-commit run --all-files

Branches, commits, and pull requests#

Never commit directly to main. Create a focused feature branch for every change:

git switch -c fix/short-description

Use a Conventional Commit message such as fix(config): improve YAML validation errors. Commit messages must not contain agent names, generated-by/generated-with branding, or AI co-author trailers. The commit-msg hooks validate both the Conventional Commit structure and forbidden branding.

Before pushing, run pixi run format, pixi run check, and pre-commit run --all-files. Push the feature branch, open a pull request, and leave it open for a maintainer to review and merge; do not merge your own PR.

Writing and running tests#

Tests live under tests/unit/. Follow the conventions already established there:

  • one file per module under test (e.g. tests/unit/test_config.py)

  • use pytest fixtures and monkeypatch for environment variables

  • never import SimpleITK or h5py unconditionally — guard with pytest.importorskip

Run a single test file:

pixi run test -- tests/unit/test_config.py -v

What CI runs#

The GitHub Actions workflow in .github/workflows/konfai_ci.yml runs pytest across Python 3.10 to 3.13 on Linux, macOS, and Windows.

The konfai-apps test suite#

The konfai-apps package carries its own tests — including an integration test for the konfai-apps pipeline flow in konfai-apps/tests/integration/test_konfai_apps.py — and they are not part of pixi run test. Install the package first, then run its suite:

pip install -e ./konfai-apps
pytest konfai-apps/tests

Validate an example manually#

Some changes are best validated end-to-end against a shipped example. The most practical manual validation loop is:

  1. run a shipped example

  2. inspect Checkpoints/, Predictions/, Evaluations/, and Statistics/

  3. confirm that the generated config copy matches the intended run

Working on examples#

Examples in examples/ are part of the user-facing documentation of the framework. When changing example YAML or notebooks:

  • keep commands runnable from the example directory

  • keep dataset group names and folder layouts explicit

  • prefer adapting an existing example over inventing a new undocumented pattern

Building the documentation#

The documentation uses Sphinx with the MyST parser for Markdown files.

Build the HTML output:

pixi run -e docs build-docs

Or in live-reload mode during authoring:

pixi run -e docs dev-docs

Without Pixi:

pip install -r docs/requirements.txt
make -C docs html

The output lands in docs/_build/html/.

Documentation style#

Documentation should stay aligned with the codebase, examples, and tests. When updating the docs:

  • prefer code-backed statements

  • call out behavior inferred from code when needed

  • avoid documenting private helpers unless they are essential extension points

  • update cross-links when you rename or move pages

Packaging and release#

The repository contains a publish workflow in .github/workflows/publish.yml that builds:

  • konfai

  • impact-synth-konfai

  • mrsegmentator-konfai

  • totalsegmentator-konfai

This is a useful reminder that changes to the core package may affect both the framework and published KonfAI Apps.

AI agent rules#

If you are an AI agent contributing to this repository, read AGENTS.md at the repository root before making changes. It is the canonical source for branch and PR rules, Conventional Commits, forbidden commit branding, coding norms, checks, and project-specific pitfalls.

Next steps#

  • Core concepts — how the config engine, data pipeline, and model graph fit together before you change them.

  • Examples — the shipped workflows to run when validating a change end-to-end.

  • API reference — the curated API surface your extensions and fixes build against.