konfai 1.5.4

A Modular and configurable Deep Learning framework with YAML and PyTorch

🧠 KonfAI

KonfAI is a flexible and extensible deep learning framework built on PyTorch, designed for fully YAML-driven configuration.
It provides a clean separation between configuration and implementation, allowing users to orchestrate entire workflows, from data loading to evaluation, with no hardcoded logic.

KonfAI natively supports multi-model training, patch-based learning, test-time augmentation, and loss scheduling, making it ideal for medical imaging research and large-scale experimentation.

KonfAI has been used in several top-performing challenge projects:
🔗 SynthRAD2025 – Task 1 •
🔗 SynthRAD2025 – Task 2 •
🔗 CURVAS PDACVI 2025 •
🔗 TrackRAD 2025 •
🔗 Panther •
🔗 CURVAS •

For more details on the design principles and scientific background, refer to the paper:

KonfAI: A Modular and Fully Configurable Framework for Deep Learning in Medical Imaging

---

🔧 Key Features

• 🔀 Full training/prediction/evaluation orchestration via YAML configuration files
• 🧩 Modular plugin-like structure (transforms, augmentations, models, losses, schedulers)
• 🔄 Dynamic criterion scheduling per head / target
• 🧠 Multi-branch / multi-output model support
• 🖥️ Cluster-ready
• 📈 TensorBoard and custom logging support

---

🚀 Installation

From PyPI

Install KonfAI from PyPI:

pip install konfai

This will install the command-line tools:

konfai --help
konfai-cluster --help

---

From GitHub

Clone the repository and install:

git clone https://github.com/vboussot/KonfAI.git
cd KonfAI
pip install -e .

---

🧪 Usage

konfai TRAIN --gpu 0
konfai PREDICTION --models checkpoint.pt --gpu 0
konfai EVALUATION

---

📦 KonfAI Apps

A KonfAI App is a self-contained workflow package built with KonfAI.
It defines how a model is executed, how outputs are generated, and how optional evaluation or uncertainty workflows are performed.

Several ready-to-use KonfAI Apps are available directly in the repository under the apps/ directory.

They can be executed identically from:

Interface	Command
🖥️ CLI	konfai-apps infer / eval / uncertainty / pipeline app name
🧠 3D Slicer	Via SlicerKonfAI GUI https://github.com/vboussot/SlicerKonfAI
🐍 Python API	Via konfai.app.KonfAIApp
🌐 Remote Server (client/server mode)

---

📂 Structure of a KonfAI App

my_konfai_app/
├── app.json                # Metadata for UI + behaviors
├── Prediction.yml          # Inference workflow (required)
├── Evaluation.yml          # Evaluation workflow (optional)
├── Uncertainty.yml         # Uncertainty workflow (optional)
└── checkpoint.pt           # Trained model (single or ensemble)

Example app.json:

{
    "display_name": "Lung Lobe Segmentation",
    "short_description": "Segmentation of lung lobes on CBCT scans.",
    "description": "This App synthesizes CT-like contrast from CBCT then segments lung lobes.",
    "tta": 4,
    "mc": 0
}

---

🚀 Using a KonfAI App (CLI)

Inference:

konfai-apps infer my_app -i input.mha -o ./Predictions --tta 4

Evaluation:

konfai-apps eval my_app -i input/ --gt labels/

Uncertainty:

konfai-apps uncertainty my_app -i input.mha

Pipeline (inference → evaluation → uncertainty):

konfai-apps pipeline my_app -i input.mha --gt gt.mha -uncertainty

Fine-tuning:

konfai-apps fine-tune my_app name -d ./Dataset --epochs 20

The very same commands can be executed on a remote KonfAI Apps server by adding --host, --port, and --token. This allows heavy workloads to run on shared GPU machines while keeping a lightweight local client.

More detailed documentation and usage examples for each app are available in the corresponding subdirectories of the apps/ folder.

---

🧩 TODO & Perspectives

📘 Documentation

The official KonfAI documentation is in progress and will be released soon.

🤖 KonfAI-MCP Server

We are actively developing KonfAI-MCP, an extension of the framework enabling language-driven deep learning experimentation. Through the Model Context Protocol (MCP), KonfAI will serve as the deterministic and transparent execution layer for agentic LLMs, allowing large language models to specify, launch, and refine deep learning experiments directly through natural language.

Imagine instructing an AI to: “Train a model for lung tumor segmentation from this dataset and optimize the Dice score.” KonfAI-MCP aims to turn such instructions into reproducible, verifiable experiments.

This represents the next stage of AI-assisted scientific research, where language becomes a medium of empirical discovery.