Get started

Install KonfAI and run the Segmentation example.

Install

KonfAI needs Python 3.11 or newer. The line most people want brings the engine and every image reader (SimpleITK, h5py, pydicom, zarr, ngff-zarr):

python -m pip install "konfai[imaging]"
python -c "import konfai; print(konfai.__version__)"
konfai --help

konfai alone has no image reader and cannot open a .mha. KonfAI declares torch but cannot pick the wheel for your drivers: if you need a specific CUDA or a CPU-only build, install PyTorch first. GPUs are CUDA devices; on macOS every workflow runs on the CPU (--cpu N). The examples do not travel in the wheel: clone the repository to run them.

git clone https://github.com/fideus-labs/KonfAI.git
cd KonfAI
python -m pip install ".[imaging]"

Other extras (itk, hdf5, dicom, omezarr, s3, tensorboard, monai, export, all, dev) are listed in the installation page of the reference.

The first run: four tiny CT volumes

The quickstart trains, predicts and evaluates a two-class segmentation on four synthetic volumes (32 × 32 × 4 voxels, labels 0 = background and 1 = foreground), on one CPU, without downloading anything. From a clone:

cp -r examples/Segmentation/TwoClasses ../konfai-first-run
cd ../konfai-first-run
python quickstart.py prepare                 # Dataset/CASE_000 .. CASE_003, each with CT.mha and SEG.mha
export OMP_NUM_THREADS=1
konfai TRAIN -y --cpu 1 --config Config.yml
konfai PREDICTION -y --cpu 1 --config Prediction.yml --models "$(python quickstart.py checkpoint)"
konfai EVALUATION -y --cpu 1 --config Evaluation.yml
python quickstart.py verify

The three YAML files are short: Config.yml (a 2D UNet from the catalogue, two output channels, cross entropy and foreground Dice, twenty epochs), Prediction.yml (the same model, the Argmax head written as PRED.mha), Evaluation.yml (PRED against SEG, label [1]). CASE_003 is held out during training. Twenty epochs reach a Dice of about 0.98; the final check verifies the files, their geometry and the reported values, not accuracy on medical images.

What appears on disk

Each command writes under a directory named after train_name (CT_TWO_CLASSES in the quickstart):

Folder	Holds
`Checkpoints/<train_name>/`	the dated `BEST` model and `resume_latest.pt` (a training continuation, not a model to predict with)
`Statistics/<train_name>/`	the resolved `Config.yml` the run read, `Seed.txt`, `Train_0.txt` and `Validation_0.txt` (the split), `log_0.txt`, `tb/` when TensorBoard is installed
`Predictions/<train_name>/`	`Dataset/<case>/PRED.mha`, a copy of `Prediction.yml`, `log_0.txt`, `checkpoints.json` (which checkpoint wrote each case)
`Evaluations/<train_name>/`	`Metric_TRAIN.json`, the per-case `Metric_TRAIN.cases.rank0.jsonl`, a copy of `Evaluation.yml`, `log_0.txt`

A run writes its resolved defaults back into the YAML files, so after a run the file is the complete record of the experiment. For another fresh run, copy the example to a new directory.

Next: Configuration for what those files say, Workflows for the commands and their options.