README.md

YOLOZU Docs

Use this page as the shortest route into the repo. Start with the 1-minute demo, read the first three docs, then pick one next route.

1-Minute Demo

python3 -m pip install -U yolozu
yolozu demo overview

Writes demo_output/overview/<utc>/demo_overview_report.json.

Read These 3 First

• predictions_schema.md: the predictions interface contract
• install.md: install, doctor, and environment setup
• external_inference.md: evaluate predictions exported elsewhere

Next 3 Routes

• Main production lane: evaluate precomputed predictions and keep the predictions interface contract stable
• Secondary lane: train/export flows that emit the same predictions interface contract
• Advanced lanes: backend parity, SynthGen handoff, continual learning, TTT, and Hessian refinement

Primary Focus

• Main lane: evaluate precomputed predictions fairly across frameworks and runtimes
• Secondary lane: export and reference training lanes that feed the same predictions interface contract
• Secondary external lane: Apache-2.0-friendly YOLOX-style training bridge, with optional external runtime bridges called out explicitly
• Advanced lane: continual learning, TTT, SynthGen, and backend parity research paths

Capability Maturity

• Stable: prediction validation/evaluation, wrapped predictions.json, install/doctor flow, repo smoke/demo path
• Experimental: backend parity, benchmark orchestration, SynthGen intake and handoff, macOS/MPS evaluation paths
• Research: continual learning, self-distillation, TTT, Hessian refinement

Production Readiness

• Production-ready today: prediction validation/evaluation and the predictions interface contract
• Needs qualification in your environment: backend parity, benchmark orchestration, SynthGen handoff, macOS/MPS paths
• Research-oriented: continual learning, self-distillation, TTT, Hessian refinement
• Details: production_readiness.md

Quick route map

• If you already have predictions: go to A) Evaluate from precomputed predictions
• If you need the in-repo reference trainer: go to B) Train → Export → Eval
• If you need an external training lane: use yolozu train --external-backend yolox|detectron2|ultralytics|hf-detr ... and then go to Training / inference / export
• If you need the current training scope boundary first: read Current training support
• If you need the platform view of training: read Training backend interface, Training capability matrix, and Training orchestration
• If you are qualifying non-default paths: use D) Bench/Parity, Continual learning, or SynthGen handoff

Offline repo smoke

The fastest safety check from repo root is:

bash scripts/smoke.sh

Expected report output:

• reports/smoke_coco_eval_dry_run.json

Optional deeper walkthrough (capability claims + deploy-path dry-runs + walkthrough report):

bash scripts/smoke.sh --profile deep

On a CUDA machine (single GPU), run the deep profile with the TTT probe on GPU:

bash scripts/smoke.sh --profile deep --torch-device cuda

Deep walkthrough report:

• reports/smoke_walkthrough_report.json

Supporting docs:

• Install: install.md
• Support/legal: support.md
• Security / cryptography scope: security_crypto_scope.md
• Repository governance / Scorecard posture: security_scorecard_governance.md, repo_governance_audit.md
• Production readiness: production_readiness.md
• Learning features overview: learning_features.md

---

A) Evaluate from precomputed predictions (no inference deps)

Use this path when predictions are exported elsewhere and you only need validation/evaluation here.

Shortest 3 commands:

python3 -m yolozu validate dataset data/smoke --strict
python3 -m yolozu validate predictions \
	data/smoke/predictions/predictions_dummy.json --strict
python3 -m yolozu eval-coco \
	--dataset data/smoke \
	--split val \
	--predictions data/smoke/predictions/predictions_dummy.json \
	--dry-run \
	--output reports/smoke_coco_eval_dry_run.json

Reference docs:

• External inference backends
• Predictions schema

B) Train → Export → Eval (RT-DETR reference trainer)

Use this path when you want a train-like flow with smoke-safe local artifacts.

Shortest 3 commands:

python3 -m yolozu validate dataset data/smoke --strict
python3 -m yolozu export \
	--backend labels \
	--dataset data/smoke \
	--output runs/smoke/predictions_labels.json \
	--force
python3 -m yolozu eval-coco \
	--dataset data/smoke \
	--split val \
	--predictions runs/smoke/predictions_labels.json \
	--dry-run \
	--output runs/smoke/coco_eval_dry_run.json

Reference docs:

• Training / inference / export
• Run contract

C) Interface Contracts (predictions / adapter / TTT protocol)

Use this path to confirm JSON interface contracts and manifest consistency before bigger runs.

Shortest 3 commands:

python3 -m yolozu validate predictions \
	data/smoke/predictions/predictions_dummy.json --strict
python3 -m yolozu validate dataset data/smoke --strict
python3 tools/validate_tool_manifest.py \
	--manifest tools/manifest.json \
	--require-declarative

Reference docs:

• Predictions schema
• Adapter contract
• TTT protocol
• TTT before-after compare boilerplates

D) Bench/Parity (qualification lane)

Use this path after the main validation/eval lane is already working and you are qualifying backend parity or benchmark behavior. Some formats already support artifact-backed real eval/parity lanes; others still report explicit placeholder/skipped semantics rather than pretending to be fully implemented. The canonical support-status table is Benchmark support matrix.

Shortest 3 commands:

python3 -m yolozu parity \
	--reference data/smoke/predictions/predictions_dummy.json \
	--candidate data/smoke/predictions/predictions_dummy.json
python3 tools/benchmark_model.py \
	--model runs/example/model.pt \
	--data data/coco8.yaml \
	--format all \
	--dry-run \
	--output reports/benchmark_report.json
python3 tools/benchmark_latency.py --help

When backend artifacts are available, the benchmark entry can orchestrate real torch / onnx / engine / torchscript runs:

python3 tools/benchmark_model.py \
	--model runs/example/model.pt \
	--onnx-model exports/example.onnx \
	--engine-model exports/example.plan \
	--data data/coco8.yaml \
	--format torch,onnx,engine \
	--protocol nms_applied \
	--latency-source auto \
	--output reports/benchmark_report.json

Typical outputs:

• reports/benchmark_report.json
• reports/export_settings_<format>.json
• reports/predictions_<format>.json
• reports/eval_<format>.json
• reports/parity_<format>.json

torchscript is now a real detect benchmark lane when a local PyTorch runtime and compatible TorchScript artifact are present. The declared decode path expects [x1,y1,x2,y2,score,class_id] combined output rows.

The benchmark report now records:

• canonical task label
• requested task label
• metric family and expected metric keys
• whether the task is part of the mainstream benchmark surface or a YOLOZU-native extension

Reference docs:

• TensorRT pipeline
• Benchmark mode
• Benchmark support matrix
• Backend runtime / license boundary matrix
• License policy and no-telemetry repository boundary
• Benchmark latency
• Benchmark mode spec (parity target)
• Benchmark gap audit
• RunPod GPU split preflight

E) LLM / MCP integrations

Use this path when integrating YOLOZU tools with MCP clients or Actions/OpenAPI routes.

Shortest 3 commands:

python3 tools/run_mcp_server.py
python3 tools/run_actions_api.py
python3 tools/export_actions_openapi.py --output reports/actions_openapi.json

Reference docs:

• LLM integrations
• OpenAI MCP / Actions
• Copilot MCP integration
• MCP extension architecture
• AI-first guide (supported MCP scope)

F) YOLO-style migration (v5/v8/11/26)

Use this path when you keep training/inference in a YOLO-family runtime and only want YOLOZU interface-contract/eval.

Shortest 3 commands:

python3 tools/import_yolo_data_yaml.py --data-yaml /path/to/data.yaml --split val --output data/yolo_wrapper --force
python3 tools/export_predictions_yolo_runtime.py --model yolo11n.pt --dataset data/yolo_wrapper --split val --protocol nms_applied --wrap --output reports/pred_yolo_runtime.json
python3 -m yolozu eval-coco --dataset data/yolo_wrapper --split val --predictions reports/pred_yolo_runtime.json --protocol nms_applied --output reports/coco_eval_yolo_runtime.json

Protocol guidance:

• nms_applied: YOLOv5/YOLOv8/YOLO11 style post-NMS exports from a YOLO-family runtime.
• e2e_nms_free: YOLO26 / RT-DETR style NMS-free exports.

If predictions contain COCO category_id, pass --classes data/yolo_wrapper/labels/<split>/classes.json to eval-coco.

G) Detectron2/MMDetection migration

Use this path when you keep Detectron2/MMDetection training/inference and only export results into YOLOZU interface contracts.

Shortest flow:

yolozu migrate dataset --from coco --coco-root /path/to/coco --split val2017 --output data/coco_yolo_like --mode manifest
yolozu export-dataset yolo --dataset data/coco_yolo_like --split val2017 --out-dir data/coco_yolo_export --force
yolozu export-dataset coco --dataset data/coco_yolo_like --split val2017 --out-dir data/coco_export --force
yolozu export-dataset kitti --dataset data/coco_yolo_like --split val2017 --out-dir data/coco_kitti_export --force
yolozu export-dataset segmentation --dataset reports/cityscapes_seg_wrapper --out-dir data/cityscapes_seg_export --image-mode symlink --force
python3 tools/export_predictions_detectron2.py --dataset data/coco_yolo_like --split val2017 --config /path/to/d2_config.yaml --weights /path/to/model_final.pth --protocol nms_applied --output reports/pred_detectron2.json
python3 tools/export_predictions_mmdet.py --dataset data/coco_yolo_like --split val2017 --config /path/to/mmdet_config.py --checkpoint /path/to/epoch_12.pth --protocol nms_applied --output reports/pred_mmdet.json

If you want a preflight that tells you what the dataset already is, use:

yolozu doctor import --dataset-from auto --dataset /path/to/dataset_root --split val2017 --output -

Auto-detect also recognizes semantic-segmentation roots/descriptors and COCO keypoints roots, so the same preflight works for bbox / keypoints / segmentation with one command.

Validation/eval:

python3 tools/validate_predictions.py reports/pred_detectron2.json --strict
python3 tools/eval_coco.py --dataset data/coco_yolo_like --split val2017 --predictions reports/pred_detectron2.json --protocol nms_applied --classes data/coco_yolo_like/labels/val2017/classes.json --output reports/coco_eval_detectron2.json

Reference: Detectron2/MMDetection interop

External finetune smoke matrix:

• python3 tools/run_external_finetune_smoke.py --dataset-root data/smoke --split train --output reports/external_finetune_smoke.json
• Guide: External finetune smoke

H) OpenCV-DNN migration (CPU/CUDA/OpenVINO)

Use this path when OpenCV DNN is your runtime of record (C++/embedded/field inference) and you want YOLOZU validation/eval/parity. Canonical CLI shown below (yolozu ... or python3 -m yolozu ...). The legacy python3 tools/yolozu.py ... wrapper still works in a repo checkout but is now compatibility-only.

Shortest flow:

python3 -m yolozu export --backend opencv-dnn --onnx /path/to/model.onnx --dataset /path/to/coco-yolo --split val2017 --imgsz 640 --decode auto --preprocess yolo_letterbox_640 --dump-io reports/opencv_dump_io.json --output reports/pred_opencv.json
python3 tools/validate_predictions.py reports/pred_opencv.json --strict
python3 tools/eval_coco.py --dataset /path/to/coco-yolo --split val2017 --predictions reports/pred_opencv.json --output reports/eval_opencv.json

Runtime switches:

• --dnn-backend opencv|cuda|openvino
• --dnn-target cpu|cuda|cuda_fp16|opencl|opencl_fp16

Reference: OpenCV-DNN inference exporter

I) YOLOX migration

Use this path when YOLOX is your training/inference stack and you want YOLOZU interface-contract validation + eval. Canonical CLI shown below (yolozu ... or python3 -m yolozu ...).

python3 -m yolozu export --backend yolox --dataset /path/to/coco-yolo --split val2017 --exp /path/to/yolox_exp.py --weights /path/to/yolox_ckpt.pth --imgsz 640 --score-thr 0.01 --nms-iou 0.65 --output reports/pred_yolox.json
python3 tools/validate_predictions.py reports/pred_yolox.json --strict
python3 tools/eval_coco.py --dataset /path/to/coco-yolo --split val2017 --predictions reports/pred_yolox.json --protocol nms_applied --classes /path/to/coco-yolo/labels/val2017/classes.json --output reports/eval_yolox.json

Reference: YOLOX interop

J) Model fetch (portable weights intake)

Use this path to download curated model artifacts with license gating, cache reuse, and metadata recording.

python3 -m yolozu list models
python3 -m yolozu fetch yolox-s-coco --out models --accept-license
cat models/yolox-s-coco/meta.json

The metadata interface contract at models/<id>/meta.json always includes:

• source
• version
• license
• sha256
• created_at

Reference: Model fetch

K) SynthGen intake (external generator boundary)

Use this path when synthetic shards are produced outside YOLOZU and you only need intake/interface-contract/eval here.

python3 tools/validate_synthgen_contract.py --input /path/to/synthgen_dataset/shards/train_000.jsonl --max-samples 200
python3 tools/render_synthgen_overlay.py --dataset-root /path/to/synthgen_dataset --schema-id animal_v1 --sample-index 0 --output reports/synthgen_overlay.png
python3 tools/eval_synthgen.py --dataset-root /path/to/synthgen_dataset --predictions /path/to/synthgen_dataset/shards/predictions_synthgen.json --schema-id animal_v1 --output reports/synthgen_eval.json
python3 tools/smoke_synthgen.py --dataset-root data/smoke/synthgen_minishard --output-dir reports

References:

• SynthGen intake guide
• SynthGen interface contract
• YOLOZU-synthgen integration checklist

If your predictions artifact reuses shard-relative paths, keep it under shards/ or rewrite those paths before running eval_synthgen.py.

CI incidents

CI incident memo has moved to a dedicated page:

• CI incidents memo
• Release reliability checklist
• 1.0 stability boundary
• Manual PDF DOI release
• YOLO/DETR support (3-layer)