Pipeline reference

Reference doc – not a tutorial. For walkthroughs see Getting started or Adding a new model.

CLI

uv run dtai <command> [args]

Command	Purpose
list	List models. --json-output for the CI matrix. Skips models with a .skip file.
setup [model_id]	Download checkpoints from the URLs in model.yaml. No model_id → run for all.
convert [model_id]	Run the per-model convert.py, write ONNX + config.json into output/.
validate [model_id]	Sanity-check the ONNX output (shapes, dtypes, opset).
package [model_id]	Zip the model's output/ artifacts into output/<model-id>.dtmodel.
demo [model_id]	Run the per-model demo.py against samples/<task>/.
run [model_id]	setup → convert → validate → package, in order.
versions	Generate output/versions.json from every model's version field.
eval <task> <model_id> [extra]	Task-level evaluation (e.g. dtai eval mask mask-object-segnext-b2hq --limit 5).

model.yaml schema

Top-level keys:

Key	Type	Required	Description
id	string	yes	Unique id. Matches the directory name and the .dtmodel zip top-level dir.
name	string	yes	Human-readable name (shown in darktable's UI).
description	string	yes	One-line description.
task	string	yes	denoise, rawdenoise, mask, upscale, embed, depth, erase.
version	string	yes	Bumped on every meaningful change; flows into config.json and versions.json.
backend	string	yes	Currently always onnx.
type	string	yes	single / split / multi – affects packaging and demo() signature.
tiling	bool	yes	Whether the runtime tiles the input.
dep_group	string	yes	Dependency group name in pyproject.toml.
coreml_format	string	no	mlprogram opts into CoreML's newer MLProgram format.
attributes	object	no	Per-model attributes the runtime reads from config.json (e.g. input_sizes).
repo	object	no	{ submodule: vendor/<path> } if external code is needed.
checkpoints	list	yes	Each { url, path } downloaded by dtai setup.
model_card	object	yes	Metadata for the in-app model card. See below.
convert	list	yes	Conversion steps, each { script, args }. Run in order.
demo	object	no	{ image_args: { ... } } for per-image arguments to demo().

model_card sub-fields

Key	Description
long_description	Multi-sentence description shown in the in-app card.
scope	What the model does (e.g. single-image denoising).
author	Author or research group.
source	Upstream repo URL.
paper	Paper or technical report URL.
license	Model weights license.
training_data	Brief description of training data.
training_data_license	License(s) of the training data.
notes	Free-form notes – known limitations, gotchas.

Template variables

Resolved anywhere inside convert.args and demo.image_args:

Variable	Resolves to
{root}	repo root
{model_dir}	models/<id>/
{temp}	temp/<id>/
{output}	output/<id>/
{repo}	the submodule path declared in repo.submodule

config.json

Generated by dtai convert alongside each model's ONNX file. Embedded into the .dtmodel archive. darktable reads it at install time. Fields include the model id, version, task, tiling info, input sizes, and anything from attributes.

versions.json

{
  "models": {
    "denoise-nind": "1.0",
    "mask-object-sam21-small": "1.0"
  }
}

Published as a release asset. darktable fetches it to check for updates without downloading full packages – bumping a model's version is what surfaces an "update available" status in the AI preferences pane.

.dtmodel archive layout

A .dtmodel is a plain ZIP. Top-level directory must match the model id:

denoise-nind/
  model.onnx
  config.json
  ... (any extra files declared by the model)

dtai package builds the archive; darktable extracts it under its models directory.

.skip files

A file at models/<model-id>/.skip excludes the model from dtai list, batch operations, and CI. Use to temporarily disable a broken model without removing it. Delete the file to re-enable.