konfai 1.5.9

A Modular and configurable Deep Learning framework with YAML and PyTorch

🧠 KonfAI

KonfAI is a modular, YAML-driven deep learning framework for medical imaging, built on PyTorch. You describe an entire pipeline — data loading, model, losses, metrics, augmentations, optimizer, and the train / predict / evaluate workflow — in configuration, not orchestration scripts. The config is the experiment: a complete, reproducible record you can diff, share, and re-run.

Trainer:
  Model:
    classpath: UNet.yml          # a model, referenced by name
  Dataset:
    groups_src: { CT: {...}, SEG: {...} }   # channel-first, lazy, patch-based
  epochs: 100

konfai TRAIN -c Config.yml --gpu 0     # then PREDICTION, then EVALUATION

KonfAI has powered top-ranking MICCAI-challenge results across segmentation, registration, and synthesis: SynthRAD2025 T1 · SynthRAD2025 T2 · CURVAS PDACVI · TrackRAD2025 · Panther · CURVAS

📄 Paper: KonfAI: A Modular and Fully Configurable Framework for Deep Learning in Medical Imaging (Boussot & Dillenseger, 2025)

---

Why KonfAI?

Most frameworks focus on models. KonfAI focuses on pipelines.

• 🧩 Compose full workflows from modular, named components — no glue code.
• 🔁 Iterate by editing YAML, not rewriting Python.
• 🔬 Reproduce every run: KonfAI resolves and writes back the full config.
• 🩻 Scale to real volumes: data is always read lazily as overlapping patches — never loaded whole into RAM.
• 📦 Ship a mature workflow as a reusable KonfAI App (CLI, HTTP server, 3D Slicer).
• 🤖 Drive it with an agent: KonfAI-MCP lets an LLM inspect data, author configs, and launch runs.

---

Install

pip install "konfai[imaging]"     # core + all imaging backends (recommended)
pip install konfai                # core only (bring your own data reader)

[imaging] pulls SimpleITK / h5py / pydicom / zarr — needed to read .mha, .nii.gz, DICOM, and OME-Zarr. For the full extras matrix (ssim, fid, lpips, export, cluster, …) and a reproducible Pixi setup, see the installation guide.

---

Three workflows, three configs

KonfAI is command-driven; each CLI state maps to one YAML file:

Command	Config	Does
konfai TRAIN / RESUME	Config.yml (Trainer:)	fit a model
konfai PREDICTION	Prediction.yml (Predictor:)	patch/TTA/ensemble inference → datasets
konfai EVALUATION	Evaluation.yml (Evaluator:)	metrics on saved predictions

Full CLI reference (flags, konfai-cluster, konfai-apps): docs/reference/cli.

---

Quickstart (5-minute teaser)

git clone https://github.com/vboussot/KonfAI.git && cd KonfAI
pip install -e ".[imaging]"
cd examples/Segmentation

# download the small public demo dataset
pip install -U "huggingface_hub[cli]"
hf download VBoussot/konfai-demo --repo-type dataset --include "Segmentation/**" --local-dir Dataset
mv Dataset/Segmentation/* Dataset/ && rmdir Dataset/Segmentation && rm -rf Dataset/.cache

konfai TRAIN -y --gpu 0 --config Config.yml     # use --cpu 1 if you have no GPU

💡 After a run, Config.yml will contain the resolved defaults KonfAI materialised — that's expected, and it's what makes runs reproducible.

The full walkthrough (predict, evaluate, what to inspect, common first issues, notebook entry points) lives in the Quickstart.

---

What's in the box

Everything below is referenceable by name in YAML. See the built-in component catalogue for classpaths and constructor arguments.

Kind	Examples	Catalogue
Models	UNet, NestedUNet, ResNet, VAE, VoxelMorph, GAN/diffusion families	models
Losses & metrics	Dice, MAE, PSNR, SSIM, LPIPS, FID, CrossEntropyLoss, TRE, IMPACTReg, IMPACTSynth	losses-metrics
Transforms	Standardize, Normalize, Clip, Resample*, OneHot, Crop (~40)	transforms
Augmentations	Flip, Rotate, Elastix, Noise, CutOUT (~15)	augmentations
Schedulers	weight (Constant, CosineAnnealing) + LR (PolyLRScheduler, Warmup, any torch)	schedulers
Storage backends	ITK, HDF5, DICOM series, OME-Zarr	storage-backends

Not limited to these: any importable class (monai.losses:DiceLoss, torch:nn:L1Loss, or a local Model:MyNet) works via the module:Class form.

---

🤖 Agent-ready by design

KonfAI is built to serve as a deterministic backend for LLM-driven experimentation. Through the KonfAI-MCP server, an agent can:

• 🔎 inspect datasets and infer their structure
• 📝 generate and validate YAML configurations
• 🚀 launch training / prediction / evaluation runs
• 📈 read live metrics, compare runs, and iterate

Every execution stays reproducible, structured, and grounded in the same YAML workflows a human would run — bridging LLM reasoning and real experimental execution. See the ecosystem map for the current status.

---

Ecosystem

Package	What it is
konfai	the core framework (this repo)
konfai-apps	package a workflow as an app — CLI, HTTP server, Python API
App bundles (apps/)	ready-to-run: impact-synth, impact-seg, mrsegmentator, totalsegmentator, impact-reg
SlicerKonfAI	run KonfAI apps from a 3D Slicer GUI
KonfAI-MCP	expose KonfAI to LLM agents — inspect data, author configs, launch and monitor runs

See the ecosystem map for what is shipped vs. in-progress.

---

Documentation

📚 Full docs: https://konfai.readthedocs.io/en/latest/

• Quickstart — first end-to-end run
• Core concepts — how YAML becomes Python objects
• Component catalogue — everything you can configure
• Examples — runnable Segmentation & Synthesis workflows

🐳 Docker: vboussot/konfai — guide.

---

Development & contributing

git clone https://github.com/vboussot/KonfAI.git && cd KonfAI
pixi install
pixi run test      # run the test suite
pixi run check     # lint + format-check + test (run before pushing)

Contributions are welcome — improve examples, clarify docs, add tests, or extend models / transforms / apps. See the developer guide.

AI coding agents: start with AGENTS.md — the canonical reference for conventions, commands, and repository rules.

---

Citation

@article{boussot2025konfai,
  title   = {KonfAI: A Modular and Fully Configurable Framework for Deep Learning in Medical Imaging},
  author  = {Boussot, Valentin and Dillenseger, Jean-Louis},
  journal = {arXiv preprint arXiv:2508.09823},
  year    = {2025}
}

Licensed under Apache-2.0.