Medical-imaging workflows, executable end to end

From images on disk to reproducible experiments, production inference, and reusable clinical applications.

Quickstart · See it on real data · Large images · Bring PyTorch or MONAI · Ship an App · Automate with MCP · KonfAI Studio

KonfAI is a declarative medical-imaging execution engine. It turns a reproducible research workflow into patch-native training, complete medical-image inference, and a reusable application, without giving up the PyTorch and MONAI components you already trust.

One configuration model connects storage, transforms, model graphs, losses, training, prediction, evaluation, and output geometry. The resolved YAML is the experiment record: inspectable, diffable, and runnable by a researcher or an agent.

Trainer:
  Model:
    classpath: UNet.yml          # a model, referenced by name
  Dataset:
    groups_src: { CT: {...}, SEG: {...} }   # channel-first, lazy, patch-based
  epochs: 100                             # the shipped example ships 5, sized for a first run

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)

🤖 Agent-operable. KonfAI ships an MCP server so an LLM agent can drive the entire experiment loop (inspect a dataset, author & validate YAML, launch train / predict / evaluate / transform, monitor jobs, compare runs), always grounded in the same reproducible configs a human would run. → Agents & MCP

Where to start

• Evaluating KonfAI? → the App benchmark table below, then the docs landing.
• Running a published model? → the one-command App install (Real workloads).
• Adapting an experiment? → the Quickstart (train → predict → evaluate).
• Building an App? → konfai-apps.
• Contributing? → AGENTS.md.

Why KonfAI?

• Scale. Dataset patches can be read regionally from ITK, HDF5, DICOM, and OME-Zarr when preprocessing is stream-compatible; a bounded buffer preserves correctness when it is not. Prediction owns batching, TTA, ensembles, reductions, overlap reconstruction, geometry, and output writing.
• Reproduce. Training, prediction, and evaluation share named datasets and inspectable model graphs. Defaults are materialised into the YAML and configs travel with run artifacts.
• Ship and automate. Package the stable workflow as a local, Hugging Face, or remote App, use it from 3D Slicer, or let an MCP client operate the same validated builders and workspaces.

Already use another stack? Keep it. KonfAI can instantiate regular PyTorch and MONAI components, and its catalog includes documented compatibility paths for selected MONAI, nnU-Net, torchvision, and segmentation-models-pytorch models. See when to use KonfAI, or another tool.

One engine owns the complete medical workflow

That vertical integration is the product. YAML is its durable, inspectable interface, not the value proposition by itself.

Real workloads, one App contract

The same App interface already ships full segmentation, synthesis and registration systems, not reduced demonstration networks:

These figures retain each bundle's stated case, ensemble and hardware conditions; they are evidence of executable scale, not a cross-task leaderboard. The per-app time and RAM ratios come from each bundle's own small/medium/large benchmark table (see the bundle READMEs under apps/). The bundles share the same App contract across local directories, Hugging Face and HTTP, with SlicerKonfAI for general Apps and SlicerImpactReg for dedicated registration.

Consuming a published workflow does not require authoring YAML. Install its task-specific CLI and run one command, or address the same bundle through konfai-apps; the complete configuration remains available when you need to inspect, evaluate, fine-tune, or automate it.

pip install impact_synth_konfai
impact-synth-konfai synthesize MR -i input_mr.nii.gz -o output/

# The same packaged workflow through the generic App runtime
konfai-apps infer VBoussot/ImpactSynth:MR -i input_mr.nii.gz -o output/

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 (smp, ssim, fid, lpips, export, cluster, …) and a reproducible Pixi setup, see the installation guide.

Four workflows, four configs

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

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

The same four workflows are Python callables, with structured results and the config tree as a dict, which is the idiom for a sweep or a notebook:

import konfai
from konfai.data.transform import Reduce, Resample, Write

result = konfai.transform("template", "./Cohorte:mha",
    {"CT": {"CT": [Resample(reference="atlas_000", reference_group="CT"),
                   Reduce(operator="Median", output="template", grid="strict"),
                   Write(dataset="./Template:mha")]}})
result.outputs   # where each deliverable landed

konfai.plan_transform returns the plan without running it; konfai.train, konfai.predict and konfai.evaluate take a config path or the same tree as a dict. → Python workflows.

Quickstart (first smoke run)

git clone https://github.com/fideus-labs/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 shipped epochs: 5 is demo-sized: it walks the complete path in a few minutes and is not meant to produce a useful checkpoint; raise it to 100+ for a real run. To do all of the above in one go, including predict, evaluate and a plot of the result, run every cell of examples/Segmentation/Segmentation_demo.ipynb.

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

🩻 How volumes are read

Volumes are read as patches. Whether the volume is also held in RAM depends on the workflow's loading regime (training caches, and memory_budget makes that adaptive; prediction, evaluation and transform read each case once and never cache) and on whether your preprocessing chain can be streamed. KonfAI derives streamability from the transforms you declared:

A chain streams when every step declares the region it needs: the exact patch (OneHot), a halo (Dilate), a remap (Flip), a resample (Resample), or a whole-volume statistic read once from disk (Normalize). On the stream path, a 16 GiB uncompressed .mha trains at patch 64³ under an 8 GiB memory cap with a peak resident set of 0.46 GiB.

konfai TRANSFORM decides that per case before it writes a byte: STREAM or LOAD, WHOLE-VOLUME naming the stage that refused to stream, REDUCE or REFUSED for a reduction, SKIP when the output already exists. The console gets a one-line summary; the run's log opens with the plan in full. --plan prints that full report and stops without transforming.

→ Patch streaming: what streams, what does not, and why.

What's in the box

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

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 / transform 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.

💬 KonfAI Studio

KonfAI Studio is a single chatbot web UI over the MCP server. Point it at your own dataset and, from the conversation alone, inspect the data, author or reuse a model, train, predict, evaluate, compare runs, and view the volumes in a built-in NiiVue viewer. Every step is a konfai-mcp tool call, the compute staying on your machine. It is a product surface over konfai-mcp, not a new engine, and it ships no API key: you bring your own LLM, your Claude Code subscription by default, the Claude API with your key, or a fully local OpenAI-compatible server such as Ollama or vLLM.

pip install konfai-studio
konfai-studio            # -> http://127.0.0.1:8730

→ KonfAI Studio

Ecosystem

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
• Large images: regional reads, fallback, and tuning
• Adopt from PyTorch/MONAI: reuse and tool choice
• Component catalogue: everything you can configure
• Examples: runnable Segmentation, Synthesis & Registration workflows, plus five published-app demos

🐳 Docker: vboussot/konfai, guide.

Development & contributing

git clone https://github.com/fideus-labs/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.