Generated from tools/manifest.json

Command reference

116 manifest entries with declared maturity, inputs, examples, implementation paths, and documentation links. The manifest remains the source of truth.

Manifested tools

adapter_parity_suite — Run parity checks for multiple adapter outputs against a reference adapter predictions file.

experimental tools/adapter_parity_suite.py

Inputs

--adapter-predictions — required, string
--reference-adapter — string
--image-size — string
--iou-thresh — number
--score-atol — number
--bbox-atol — number
--output — default=reports/adapter_parity_suite.json, file

Examples

python3 tools/adapter_parity_suite.py --adapter-predictions rtdetr=reports/pred_rtdetr.json --adapter-predictions mmdet=reports/pred_mmdet.json --adapter-predictions detectron2=reports/pred_detectron2.json --adapter-predictions yolo_runtime=reports/pred_yolo_runtime.json --adapter-predictions opencv_dnn=reports/pred_opencv_dnn.json --adapter-predictions custom_cpp=reports/pred_custom_cpp.json --reference-adapter rtdetr --output reports/adapter_parity_suite.json

Implementation · adapter_templates.md · adapter_contract.md · production_readiness.md

announce_release — Generate (and optionally post) release announcement bundle for LinkedIn/X/Reddit from GitHub release event payload.

stable tools/announce_release.py

Inputs

--event-json — file
--out-dir — default=reports/announce, dir
--post — string
--platform — string
--strict-post — string
--reddit-subreddit — string
--reddit-kind — string
--x-max-len — default=280, number

Examples

python3 tools/announce_release.py --out-dir reports/announce
python3 tools/announce_release.py --out-dir reports/announce --post --strict-post

Implementation · RELEASE.md · release_reliability_checklist.md

audit_backend_support — Audit YOLOX/YOLOv8/Detectron2/MMDetection exporters, with verified execution evidence for selected non-dry backends.

experimental tools/audit_backend_support.py

Inputs

--dataset-root — default=data/real_multitask_fewshot, dir
--split — default=val, string
--max-images — default=2, number
--output — default=reports/backend_support_audit.json, file
--work-dir — dir
--python — string
--strict — string
--non-dry-backend — string
--require-non-dry — string
--yolox-exp — file
--yolox-weights — file
--ultralytics-model — default=yolov8n.pt, string
--detectron2-config — file
--detectron2-weights — file
--mmdet-config — file
--mmdet-checkpoint — file

Examples

python3 tools/audit_backend_support.py --dataset-root data/real_multitask_fewshot --split val --max-images 2 --output reports/backend_support_audit.json
python3 tools/audit_backend_support.py --dataset-root data/real_multitask_fewshot --split val --max-images 2 --output reports/backend_support_audit.json --require-non-dry --non-dry-backend yolox --yolox-exp /path/to/yolox_exp.py --yolox-weights /path/to/yolox_ckpt.pth

Implementation · tools_index.md · external_inference.md · interop_detectron2_mmdet.md · interop_yolox.md

audit_docs_examples_drift — Audit README/docs examples against yolozu help, manual CLI drift, and manifest help drift gates.

stable tools/audit_docs_examples_drift.py

Inputs

--docs — default=None, file
--python — default=sys.executable, string
--json — string
--skip-manual — string
--skip-manifest — string

Examples

python3 tools/audit_docs_examples_drift.py --json
python3 tools/audit_docs_examples_drift.py --docs docs/cpu_only_dod.md --skip-manual --skip-manifest --json

Implementation · manifest_authoring_workflow.md · README.md

audit_manual_cli_drift — Audit manual chapter 04 against canonical yolozu CLI help and the legacy wrapper passthrough help surface.

stable tools/audit_manual_cli_drift.py

Inputs

--manual — default=manual/chapters/04_cli_reference.tex, file
--allowlist — default=docs/manual_cli_drift_allowlist.json, file
--python — string
--skip-wrapper — string
--json — string

Examples

python3 tools/audit_manual_cli_drift.py --json

Implementation · 04_cli_reference.tex · release_reliability_checklist.md · manual_cli_drift_allowlist.json

backend_parity_matrix — Run one-command backend parity matrix checks across torch/onnxrt/trt/opencv_dnn/custom_cpp and export JSON+HTML reports.

experimental tools/backend_parity_matrix.py

Inputs

--backend-predictions — required, string
--reference-backend — default=torch, string
--image-size — string
--max-images — number
--iou-thresh — default=0.99, number
--score-atol — default=0.0001, number
--bbox-atol — default=0.0001, number
--run-id — string
--runs-dir — default=runs, dir
--run-dir — dir
--output-json — file
--output-html — file

Examples

python3 tools/backend_parity_matrix.py --backend-predictions torch=reports/pred_torch.json --backend-predictions onnxrt=reports/pred_onnxrt.json --backend-predictions trt=reports/pred_trt.json --backend-predictions opencv_dnn=reports/pred_opencv_dnn.json --backend-predictions custom_cpp=reports/pred_custom_cpp.json --reference-backend torch --image-size 640 --iou-thresh 0.99 --score-atol 1e-4 --bbox-atol 1e-4

Implementation · backend_parity_matrix.md · onnx_export_parity.md

benchmark_eata_stability — Compare EATA stability/efficiency diagnostics with a baseline; efficacy remains not established and the report cannot promote defaults.

research tools/benchmark_eata_stability.py

Inputs

--baseline — required, file
--eata — required, file
--output-json — default=reports/eata_benchmark.json, file
--output-md — default=reports/eata_benchmark.md, file
--max-overhead-ratio — default=1.5, number
--max-loss-ratio — default=1.05, number
--min-selected-ratio — default=0.1, number

Examples

python3 tools/benchmark_eata_stability.py --baseline reports/preds_baseline_ttt.json --eata reports/preds_eata_ttt.json --output-json reports/eata_benchmark.json --output-md reports/eata_benchmark.md --max-overhead-ratio 1.5 --max-loss-ratio 1.05 --min-selected-ratio 0.1

Implementation · eata_design_spec.md · eata_benchmark.md

benchmark_keypoints_eval — Benchmark keypoints evaluation runtime (PCK + optional OKS mAP) and write a stable JSON report.

experimental tools/benchmark_keypoints_eval.py

Inputs

--dataset — dir
--split — string
--predictions — required, file
--max-images — number
--warmup — number
--iterations — number
--iou-threshold — number
--min-score — number
--pck-threshold — number
--oks — string
--oks-sigmas — string
--oks-sigmas-file — file
--oks-max-dets — number
--output — default=reports/benchmark_keypoints_eval.json, file

Examples

python3 tools/benchmark_keypoints_eval.py --dataset data/coco128 --predictions reports/predictions.json --max-images 50 --warmup 1 --iterations 5 --output reports/benchmark_keypoints_eval.json

Implementation · No dedicated prose page.

benchmark_latency — Latency/FPS benchmark harness producing stable JSON reports and optional JSONL history.

experimental tools/benchmark_latency.py

Inputs

--config — file
--model-template — string
--engine-template — string
--buckets — string
--run-id — string
--notes — string
--notes-file — file
--iterations — number
--warmup — number
--sleep-s — number
--target-fps — number
--target-latency-ms — number
--output — default=reports/benchmark_latency.json, file
--history — default=None, file

Examples

python3 tools/benchmark_latency.py --iterations 200 --warmup 20 --output reports/benchmark_latency.json --history reports/benchmark_latency.jsonl --notes "baseline on target HW"

Implementation · benchmark_latency.md

benchmark_model — Benchmark entrypoint with real torch/onnx/engine/torchscript and conditional OpenVINO detect orchestration when available; fail-closed rejection of detect artifact_eval; fail-closed, strict-JSON artifact-backed classification and OBB eval/parity with task-specific metrics and provenance; artifact-backed real eval/parity lanes for segmentation/keypoints/depth/pose6d on torch/onnx/engine/torchscript/openvino; task/source/format-aware flag and artifact interface contract validation; explicit task semantics, runtime/license boundary docs, stable artifacts, explicit skipped-format reporting, and a canonical support matrix.

experimental tools/benchmark_model.py

Inputs

--model — required, file
--data — required, string
--imgsz — default=640, number
--half — default=False, string
--no-half — default=False, string
--int8 — default=False, string
--no-int8 — default=False, string
--device — default=cpu, string
--verbose — default=False, string
--format — default=all, string
--task — default=detect, string
--split — string
--max-images — number
--dry-run — default=False, string
--strict — default=False, string
--repro-policy — default=relaxed, string
--runtime-lock — default=none, string
--run-id — string
--output — default=reports/benchmark_report.json, file
--history — file
--predictions-output — string
--eval-output — string
--parity-output — string
--batch — default=1, number
--dynamic — default=False, string
--no-dynamic — default=False, string
--nms — default=False, string
--no-nms — default=False, string
--simplify — default=False, string
--no-simplify — default=False, string
--opset — default=17, number
--workspace — default=4.0, number
--fraction — default=1.0, number
--latency-source — default=auto, string
--parity-reference-backend — default=auto, string
--classification-parity-score-atol — default=0.0001, number
--obb-parity-iou-thresh — default=0.99, number
--obb-parity-score-atol — default=0.0001, number
--iterations — default=50, number
--warmup — default=5, number
--sleep-s — default=0.0, number
--torch-model — file
--onnx-model — file
--engine-model — file
--torchscript-model — file
--openvino-model — file
--depth-mask — file
--depth-align — default=median_scale, string
--depth-parity-mae-atol — default=0.02, number
--depth-parity-rmse-atol — default=0.03, number
--segmentation-parity-mismatch-atol — default=0.0, number
--keypoints-parity-iou-thresh — default=0.99, number
--keypoints-parity-score-atol — default=0.0001, number
--keypoints-parity-bbox-atol — default=0.0001, number
--keypoints-parity-kp-atol — default=0.0001, number
--pose-parity-rot-deg-atol — default=0.001, number
--pose-parity-trans-atol — default=0.0001, number
--pose-parity-depth-atol — default=0.0001, number
--protocol — string

Examples

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_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,torchscript --torchscript-model exports/example.torchscript --latency-source auto --output reports/benchmark_report.json
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 --history reports/benchmark_report.jsonl --output reports/benchmark_report.json
python3 tools/benchmark_model.py --help  # then read docs/benchmark_support_matrix.md
python3 tools/benchmark_model.py --model exports/example.torchscript --data data/coco8.yaml --format torchscript --output reports/benchmark_report.json
python3 tools/benchmark_model.py --model exports/example.xml --openvino-model exports/example.xml --data data/coco8.yaml --format openvino --latency-source auto --output reports/benchmark_report.json
python3 tools/benchmark_model.py --model runs/example/model.pt --onnx-model exports/example.onnx --data data/coco8.yaml --format torch,onnx --latency-source auto --output reports/benchmark_report.json
python3 tools/benchmark_model.py --model runs/example/model.pt --onnx-model exports/example.onnx --data data/coco8.yaml --format torch,onnx --latency-source auto --parity-reference-backend onnx --output reports/benchmark_report.json
python3 tools/benchmark_model.py --model runs/example/model.pt --data data/coco8.yaml --task segmentation --format torchscript --dry-run --output reports/benchmark_report.json
python3 tools/benchmark_model.py --task segmentation --model reports/seg_torch.json --onnx-model reports/seg_onnx.json --data data/seg_dataset --format torch,onnx --latency-source artifact_eval --segmentation-parity-mismatch-atol 0.0 --output reports/benchmark_segmentation_report.json
python3 tools/benchmark_model.py --task keypoints --model reports/keypoints_torch.json --onnx-model reports/keypoints_onnx.json --data data/keypoints_dataset --format torch,onnx --latency-source artifact_eval --keypoints-parity-kp-atol 1e-4 --output reports/benchmark_keypoints_report.json
python3 tools/benchmark_model.py --task classification --model reports/classification_torch.json --onnx-model reports/classification_onnx.json --data data/classification_labels.json --format torch,onnx --latency-source artifact_eval --classification-parity-score-atol 1e-4 --output reports/benchmark_classification_report.json
python3 tools/benchmark_model.py --task obb --model reports/obb_torch.json --onnx-model reports/obb_onnx.json --data data/obb_labels.json --format torch,onnx --latency-source artifact_eval --obb-parity-iou-thresh 0.99 --obb-parity-score-atol 1e-4 --output reports/benchmark_obb_report.json
python3 tools/benchmark_model.py --model runs/example/model.pt --data data/coco8.yaml --task depth --format torchscript --dry-run --output reports/benchmark_report.json
python3 tools/benchmark_model.py --task depth --model reports/depth_torch.npy --onnx-model reports/depth_onnx.npy --data data/reference/gt_depth.npy --format torch,onnx --latency-source artifact_eval --depth-align median_scale --output reports/benchmark_depth_report.json
python3 tools/benchmark_model.py --task pose6d --model reports/pose_torch.json --onnx-model reports/pose_onnx.json --data data/pose_dataset --format torch,onnx --latency-source artifact_eval --pose-parity-trans-atol 1e-4 --output reports/benchmark_pose6d_report.json
python3 tools/benchmark_model.py --model runs/example/model.pt --data data/coco8.yaml --task pose6d --format torchscript --dry-run --output reports/benchmark_report.json

Implementation · benchmark_mode.md · benchmark_support_matrix.md · benchmark_mode_spec_parity_target.md · benchmark_latency.md · benchmark_mode_gap_audit.md · benchmark_backend_runtime_matrix.md · production_readiness.md

benchmark_sar_robustness — Compare local SAR/CoTTA/EATA diagnostics; efficacy remains not established and the report is not go/no-go evidence.

research tools/benchmark_sar_robustness.py

Inputs

--cotta — required, file
--eata — required, file
--sar — required, file
--output-json — default=reports/sar_robustness_report.json, file
--output-md — default=reports/sar_robustness_report.md, file
--max-overhead-ratio — default=1.5, number
--max-loss-ratio — default=1.05, number
--max-variance-ratio — default=1.2, number

Examples

python3 tools/benchmark_sar_robustness.py --cotta reports/preds_cotta_ttt.json --eata reports/preds_eata_ttt.json --sar reports/preds_sar_ttt.json --output-json reports/sar_robustness_report.json --output-md reports/sar_robustness_report.md --max-overhead-ratio 1.5 --max-loss-ratio 1.05 --max-variance-ratio 1.2

Implementation · sar_design_spec.md · sar_evaluation.md

build_manifest — Build a dataset manifest for data/coco128 (writes reports/manifest.json).

stable tools/build_manifest.py

Inputs

No declared CLI inputs.

Examples

python3 tools/build_manifest.py

Implementation · No dedicated prose page.

build_trt_engine — Build a TensorRT engine from ONNX using trtexec and write a reproducible meta JSON.

experimental tools/build_trt_engine.py

Inputs

--onnx — required, file
--engine — default=engines/model.plan, file
--timing-cache — default=engines/timing.cache, file
--meta-output — default=reports/trt_engine_meta.json, file
--precision — string
--input-name — string
--min-shape — string
--opt-shape — string
--max-shape — string
--workspace — number
--trtexec — string
--builder — string
--calib-cache — file
--calib-dataset — dir
--calib-split — string
--calib-images — number
--calib-list-output — file
--extra-args — string
--dry-run — string

Examples

python3 tools/build_trt_engine.py --onnx yolo26n.onnx --engine engines/yolo26n_fp16.plan --precision fp16 --input-name images --min-shape 1x3x640x640 --opt-shape 1x3x640x640 --max-shape 1x3x640x640 --timing-cache engines/timing.cache --meta-output reports/trt_engine_yolo26n_fp16.json

Implementation · tensorrt_pipeline.md

calibrate_scores — Temperature-scale detection scores to improve mAP proxy on a fixed subset (no NMS).

stable tools/calibrate_scores.py

Inputs

--dataset — required, dir
--predictions — required, file
--output — default=reports/predictions_calibrated.json, file
--output-report — default=reports/calibration_report.json, file
--output-artifact — default=reports/calibration_artifact.json, file
--split — string
--temperatures — default=0.5,1.0,1.5,2.0, string
--min-score — number
--max-score — number

Examples

python3 tools/calibrate_scores.py --dataset data/coco128 --predictions reports/predictions.json --output reports/predictions_calibrated.json --output-report reports/calibration_report.json

Implementation · score_calibration.md

check_golden_compatibility — Validate versioned golden compatibility assets and hash-pinned eval protocol snapshots.

experimental tools/check_golden_compatibility.py

Inputs

--manifest — default=baselines/golden/v1/manifest.json, file

Examples

python3 tools/check_golden_compatibility.py --manifest baselines/golden/v1/manifest.json

Implementation · rfc_workflow.md · schema_governance.md

check_keypoints_parity — Compare two keypoints prediction JSONs and report mismatches (IoU/tolerance-based).

experimental tools/check_keypoints_parity.py

Inputs

--reference — required, file
--candidate — required, file
--max-images — number
--iou-thresh — number
--score-atol — number
--bbox-atol — number
--kp-atol — number

Examples

python3 tools/check_keypoints_parity.py --reference reports/pred_ref.json --candidate reports/pred_cand.json --iou-thresh 0.99 --kp-atol 1e-4 --score-atol 1e-4 --bbox-atol 1e-4

Implementation · benchmark_mode.md · onnx_export_parity.md · tools_index.md

check_license_policy — Enforce Apache-2.0-only constraints (denylist + no vendored GPL/AGPL license texts).

stable tools/check_license_policy.py

Inputs

No declared CLI inputs.

Examples

python3 tools/check_license_policy.py

Implementation · license_policy.md

check_map_targets — Compare eval_suite results against a target table and exit non-zero on failure.

stable tools/check_map_targets.py

Inputs

--suite — default=reports/eval_suite.json, file
--targets — default=baselines/yolo26_targets.json, file
--key — string
--min-delta — number

Examples

python3 tools/check_map_targets.py --suite reports/eval_suite.json --targets baselines/yolo26_targets.json --key map50_95

Implementation · No dedicated prose page.

check_mcp_settings — Audit MCP settings by checking manifest alignment and generated MCP/Actions reference freshness.

stable tools/check_mcp_settings.py

Inputs

--manifest — default=tools/manifest.json, file
--json-ref — default=docs/generated/mcp_actions_tool_reference.json, file
--md-ref — default=docs/generated/mcp_actions_tool_reference.md, file
--output — default=reports/mcp_settings_check.json, file
--strict — string

Examples

python3 tools/check_mcp_settings.py --output reports/mcp_settings_check.json
python3 tools/check_mcp_settings.py --strict --output reports/mcp_settings_check.strict.json

Implementation · llm_integrations.md · tools_index.md · 20_llm_mcp_integrations.tex · mcp_actions_tool_reference.md

check_predictions_parity — Compare two prediction JSONs and report mismatches (IoU/tolerance-based).

experimental tools/check_predictions_parity.py

Inputs

--reference — required, file
--candidate — required, file
--bbox-format — default=auto, string
--image-size — string
--max-images — number
--iou-thresh — number
--score-atol — number
--bbox-atol — number

Examples

python3 tools/check_predictions_parity.py --reference reports/pred_ref.json --candidate reports/pred_cand.json --image-size 640 --iou-thresh 0.99 --score-atol 1e-4 --bbox-atol 1e-4

Implementation · onnx_export_parity.md

check_repo_governance — Audit repository governance posture from local workflow evidence and exported GitHub settings snapshots.

stable tools/check_repo_governance.py

Inputs

--repo-root — default=., dir
--repo-json — file
--branch-protection-json — file
--require-reviews — default=1, number
--allow-missing-evidence — default=False, string
--output — default=reports/repo_governance_check.json, file

Examples

python3 tools/check_repo_governance.py --repo-json reports/github_governance/repo.json --branch-protection-json reports/github_governance/branch_protection_main.json --output reports/repo_governance_check.json
python3 tools/check_repo_governance.py --repo-root . --allow-missing-evidence --output reports/repo_governance_check.local.json

Implementation · repo_governance_audit.md · security_scorecard_governance.md · release_reliability_checklist.md

check_segmentation_parity — Compare two segmentation predictions artifacts and report mask-level parity mismatches.

experimental tools/check_segmentation_parity.py

Inputs

--reference — required, file
--candidate — required, file
--mismatch-atol — number
--max-samples — number
--output — file

Examples

python3 tools/check_segmentation_parity.py --reference reports/segmentation_predictions_ref.json --candidate reports/segmentation_predictions_cand.json --output reports/segmentation_parity.json

Implementation · interop_detectron2_mmdet.md · tools_index.md · training_inference_export.md · 04_cli_reference.tex · 07_training_run_contract.tex

continual_decide — Device-agnostic policy gate for continual-learning eval results that emits a promote/review/hold decision report with a research_report boundary.

research tools/continual_decide.py

Inputs

--eval-json — required, file
--curation-json — file
--run-json — file
--max-forgetting — number
--min-avg-acc — number
--min-new-task-score — number
--min-old-task-final — number
--min-reviewed-labels — number
--min-highconf-pseudo-labels — number
--min-total-curated-examples — number
--max-candidate-share — number
--ttt-active — string
--allow-ttt-active-promotion — string
--output — file

Examples

python3 tools/continual_decide.py --eval-json runs/continual/<run>/continual_eval.json --run-json runs/continual/<run>/continual_run.json --max-forgetting 0.05 --min-new-task-score 0.40 --min-old-task-final 0.40 --min-reviewed-labels 20 --min-highconf-pseudo-labels 50 --min-total-curated-examples 60

Implementation · continual_learning.md · tools_index.md · 14_continual_learning.tex · production_readiness.md · research_lanes.md · research_lane_report.schema.json

convert_coco_instance_seg_predictions — Convert COCO instance segmentation predictions (polygons/RLE) into the YOLOZU instance-seg PNG-mask interface contract.

stable tools/convert_coco_instance_seg_predictions.py

Inputs

--predictions — required, file
--instances-json — required, file
--output — default=reports/instance_seg_predictions.json, file
--masks-dir — default=reports/instance_seg_masks, dir
--min-score — number
--max-preds — number

Examples

python3 tools/convert_coco_instance_seg_predictions.py --predictions /path/to/coco_preds.json --instances-json /path/to/instances_val2017.json --output reports/instance_seg_predictions.json --masks-dir reports/instance_seg_masks

Implementation · No dedicated prose page.

distill_predictions — Offline prediction distillation helper: blend teacher predictions into a student predictions JSON, emit a distilled artifact plus report, and document the workflow with beginner-facing mental models and YAML boilerplates, clearly separate from training-time self-distillation or TTT.

research tools/distill_predictions.py

Inputs

--student — required, file
--teacher — required, file
--config — file
--dataset — dir
--split — string
--alpha — number
--iou-threshold — number
--add-missing — string
--add-score-scale — number
--teacher-min-score — default=0.0, number
--max-added-per-image — number
--add-duplicate-iou-threshold — default=0.9, number
--output — default=reports/predictions_distilled.json, file
--output-report — default=reports/distill_report.json, file

Examples

python3 tools/distill_predictions.py --student reports/predictions_student.json --teacher reports/predictions_teacher.json --dataset data/coco128 --split val2017 --config configs/examples/distill_predictions.yaml --output reports/predictions_distilled.json --output-report reports/distill_report.json
python3 tools/distill_predictions.py --student reports/predictions_student.json --teacher reports/predictions_teacher.json --dataset data/coco128 --split val2017 --alpha 0.5 --iou-threshold 0.7 --add-missing --teacher-min-score 0.25 --max-added-per-image 20 --add-duplicate-iou-threshold 0.9 --output reports/predictions_distilled.json --output-report reports/distill_report.json

Implementation · distillation.md · learning_features.md

dod_cpu_smoke — Run and time the CPU-only public DoD path: doctor proof, demo, validation, and eval dry-run.

stable scripts/dod_cpu_smoke.sh

Inputs

--run-dir — default=reports/dod_cpu_smoke, dir
--split — default=val2017, string
--installed-package — default=False, string

Examples

bash scripts/dod_cpu_smoke.sh
bash scripts/dod_cpu_smoke.sh --run-dir /tmp/yolozu_dod_cpu_smoke
YOLOZU_PYTHON=/path/to/venv/bin/python bash scripts/dod_cpu_smoke.sh --installed-package --run-dir /tmp/yolozu_dod_cpu_smoke
bash scripts/dod_cpu_smoke.sh --help

Implementation · cpu_only_dod.md · README.md · Readme_jp.md · 02_installation.tex

download_coco_instances_tiny — Download a tiny COCO instances (polygon) subset (2 images by default) for `yolozu demo instance-seg` without bundling images in git.

stable scripts/download_coco_instances_tiny.py

Inputs

--out-root — default=data/coco, string
--split — default=val2017, string
--num-images — default=2, number
--seed — default=0, number
--timeout — default=60, number
--force — string
--keep-zip — string

Examples

python3 scripts/download_coco_instances_tiny.py
python3 scripts/download_coco_instances_tiny.py --help

Implementation · install.md · proof_onepager.md

eval_coco — Strictly validate and evaluate predictions on a YOLO-format dataset using COCOeval, with concise path aliases, explicit repair, and bounded-subset accounting; --dry-run does not require pycocotools.

stable tools/eval_coco.py

Inputs

--dataset — required, dir
--predictions — required, file
--output — default=reports/coco_eval.json, file
--protocol — string
--split — string
--max-images — number
--bbox-format — string
--dry-run — string
--repair — string
--classes — file
--assume-class-id-is-category-id — string

Examples

python3 tools/eval_coco.py -d data/coco128 -p reports/predictions.json --dry-run -o reports/coco_eval_dry.json
python3 tools/eval_coco.py -d data/coco128 -p reports/legacy_predictions.json --dry-run -r -o reports/coco_eval_repaired.json

Implementation · external_inference.md · python_api.md · predictions_schema.md · production_readiness.md

eval_continual — Evaluate a continual learning run (simple mAP proxy or pose metrics + forgetting) and write JSON+HTML on CPU or, on supported macOS hosts, with --device mps when torch.backends.mps.is_available() is true.

research tools/eval_continual.py

Inputs

--run-json — required, file
--device — string
--metric — string
--metric-key — string
--image-size — string
--max-images — number
--iou-threshold — number
--min-score — number
--keep-per-image — number
--success-trans — number
--success-rot-deg — number
--force — string
--output — file
--html — file

Examples

python3 tools/eval_continual.py --run-json runs/continual/<run>/continual_run.json --device cpu --max-images 50
python3 tools/eval_continual.py --run-json runs/continual/<run>/continual_run.json --device mps --max-images 50
python3 tools/eval_continual.py --run-json runs/continual/<run>/continual_run.json --device cpu --max-images 50 --metric pose --metric-key pose_success

Implementation · continual_learning.md · production_readiness.md

eval_cotta_drift — Compare baseline-vs-CoTTA TTT reports and generate reproducible drift/stability evidence artifacts (JSON+Markdown).

research tools/eval_cotta_drift.py

Inputs

--baseline — required, file
--cotta — required, file
--output-json — default=reports/cotta_drift_report.json, file
--output-md — default=reports/cotta_drift_report.md, file
--stability-loss-ratio-threshold — default=1.0, number
--max-safe-total-update-norm — default=5.0, number

Examples

python3 tools/eval_cotta_drift.py --baseline reports/preds_baseline_ttt.json --cotta reports/preds_cotta_ttt.json --output-json reports/cotta_drift_report.json --output-md reports/cotta_drift_report.md --stability-loss-ratio-threshold 1.0 --max-safe-total-update-norm 5.0

Implementation · cotta_design_spec.md · cotta_validation.md

eval_depth — Evaluate one predicted depth map against one ground-truth map and report depth_error metrics.

experimental tools/eval_depth.py

Inputs

--pred-depth — required, file
--gt-depth — required, file
--mask — file
--align — default=median_scale, string
--pred-scale — default=1.0, number
--gt-scale — default=1.0, number
--min-depth — default=1e-06, number
--max-depth — number
--output — default=reports/depth_eval.json, file

Examples

python3 tools/eval_depth.py --pred-depth /path/to/pred_depth.npy --gt-depth /path/to/gt_depth.npy --align median_scale --output reports/depth_eval.json
python3 tools/eval_depth.py --pred-depth /path/to/pred_depth.npy --gt-depth /path/to/gt_depth.npy --mask /path/to/valid_mask.npy --align none --output reports/depth_eval_masked.json

Implementation · tools_index.md · benchmark_mode_spec_parity_target.md · 16_depth_6dof_symmetry.tex · production_readiness.md

eval_instance_segmentation — Evaluate instance segmentation predictions (mask mAP) from binary PNG masks with optional HTML/overlays.

stable tools/eval_instance_segmentation.py

Inputs

--dataset — required, dir
--predictions — required, file
--output — default=reports/instance_seg_eval.json, file
--html — default=None, file
--overlays-dir — default=None, dir
--split — string
--title — string
--pred-root — dir
--classes — file
--allow-rgb-masks — string
--diag-iou — number
--max-images — number
--min-score — number
--per-image-limit — number
--max-overlays — number
--overlay-alpha — number
--overlay-max-size — number
--overlay-sort — string

Examples

python3 tools/eval_instance_segmentation.py --dataset data/coco-yolo --predictions reports/instance_seg_predictions.json --output reports/instance_seg_eval.json

Implementation · No dedicated prose page.

eval_keypoints — Evaluate keypoint predictions using PCK (bbox-normalized distance) with optional COCO OKS mAP, HTML, and overlays.

stable tools/eval_keypoints.py

Inputs

--dataset — required, dir
--predictions — required, file
--output — default=reports/keypoints_eval.json, file
--html — default=None, file
--overlays-dir — default=None, dir
--split — string
--title — string
--max-images — number
--min-score — number
--per-image-limit — number
--pck-threshold — number
--iou-threshold — number
--oks — string
--oks-max-dets — number
--oks-sigmas — string
--oks-sigmas-file — file
--kp-line — number
--kp-radius — number
--max-overlays — number
--overlay-max-size — number
--overlay-sort — string

Examples

python3 tools/eval_keypoints.py --dataset data/coco128 --predictions reports/predictions.json --output reports/keypoints_eval.json
python3 tools/eval_keypoints.py --dataset data/coco128 --predictions reports/predictions.json --oks --output reports/keypoints_eval_oks.json

Implementation · No dedicated prose page.

eval_pose — Evaluate one pose-aware predictions artifact against dataset sidecars and report pose6d_error metrics, success rates, and optional CAD-point metrics.

experimental tools/eval_pose.py

Inputs

--dataset — required, dir
--predictions — required, file
--split — string
--output — default=reports/pose_eval.json, file
--iou-threshold — default=0.5, number
--min-score — default=0.0, number
--success-rot-deg — default=15.0, number
--success-trans — default=0.1, number
--keep-per-image — default=0, number
--max-images — number

Examples

python3 tools/eval_pose.py --dataset /path/to/yolo_pose_dataset --predictions reports/predictions_pose.json --output reports/pose_eval.json
python3 tools/eval_pose.py --dataset /path/to/yolo_pose_dataset --predictions reports/predictions_pose.json --iou-threshold 0.5 --success-rot-deg 15 --success-trans 0.1 --output reports/pose_eval_thresholded.json

Implementation · tools_index.md · 16_depth_6dof_symmetry.tex · continual_learning.md · production_readiness.md

eval_segmentation — Evaluate semantic segmentation predictions (mIoU / per-class IoU) with ignore_index support and optional HTML/overlays.

stable tools/eval_segmentation.py

Inputs

--dataset-json — required, file
--predictions — required, file
--output — default=reports/seg_eval.json, file
--html — file
--overlays-dir — dir
--overlay-alpha — number
--overlay-max-size — number
--max-overlays — number
--pred-root — dir
--ignore-index — number
--num-classes — number
--max-samples — number
--allow-gt-out-of-range — string
--allow-rgb-masks — string
--miou-ignore-background — string
--skip-missing-pred — string

Examples

python3 tools/eval_segmentation.py --dataset-json data/cityscapes_seg/dataset.json --predictions reports/seg_predictions.json --output reports/seg_eval.json

Implementation · No dedicated prose page.

eval_suite — Evaluate prediction JSONs and preserve declared exporter settings in a single suite report.

stable tools/eval_suite.py

Inputs

--predictions-glob — required, string
--output — default=reports/eval_suite.json, file
--protocol — string
--allow-protocol-mismatches — string
--dataset — dir
--split — string
--max-images — number
--bbox-format — string
--strict — string
--dry-run — string

Examples

python3 tools/eval_suite.py --protocol yolo26 --dataset data/coco128 --predictions-glob 'reports/pred_yolo26*.json' --dry-run --output reports/eval_suite.json

Implementation · byop_quickstarts.md · yolo26_eval_protocol.md

eval_synthgen — Evaluate SynthGen predictions (keypoints + segmentation + depth) against shard ground truth.

experimental tools/eval_synthgen.py

Inputs

--dataset-root — required, dir
--predictions — required, file
--schema-id — string
--max-samples — default=0, number
--num-classes — default=0, number
--output — default=reports/synthgen_eval.json, file

Examples

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_animal.json

Implementation · synthgen_intake.md · synthgen_repo_integration.md · README.md · synthgen_contract.md · production_readiness.md

export_actions_openapi — Export a static OpenAPI JSON schema for YOLOZU Actions API registration.

stable tools/export_actions_openapi.py

Inputs

--output — default=reports/actions_openapi.json, file
--indent — default=2, number

Examples

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

Implementation · openai_mcp_actions.md · mcp_extension_architecture.md · llm_integrations.md · 20_llm_mcp_integrations.tex

export_predictions — Repository wrapper for the packaged fail-closed predictions exporter with checkpoint compatibility evidence; installed yolozu export does not depend on repository-only tools, optional acceleration flags require backend/device qualification, TTA remains Experimental, TTT remains Research, and parent maturity does not promote either lane.

stable tools/export_predictions.py

Inputs

--adapter — default=dummy, string
--dataset — default=data/coco128, dir
--output — default=reports/predictions.json, file
--domain-shift-recipe — file
--wrap — string
--config — file
--device — string
--image-size — number
--score-threshold — number
--max-detections — number
--checkpoint — file
--allow-partial-checkpoint — string
--lora-r — number
--lora-alpha — number
--lora-dropout — number
--lora-target — string
--lora-freeze-base — string
--no-lora-freeze-base — string
--lora-train-bias — string
--max-images — number
--split — string
--tta — string
--tta-seed — number
--tta-flip-prob — number
--tta-norm-only — string
--tta-flip-keypoints — string
--no-tta-flip-keypoints — string
--tta-flip-pose-offsets — string
--no-tta-flip-pose-offsets — string
--tta-log-out — file
--ttt — string
--ttt-preset — string
--ttt-method — string
--ttt-reset — string
--ttt-steps — number
--ttt-batch-size — number
--ttt-lr — number
--ttt-stop-on-non-finite — string
--no-ttt-stop-on-non-finite — string
--ttt-rollback-on-stop — string
--no-ttt-rollback-on-stop — string
--ttt-seed — number
--ttt-max-update-norm — number
--ttt-max-total-update-norm — number
--ttt-max-loss-ratio — number
--ttt-max-loss-increase — number
--ttt-update-filter — string
--ttt-include — string
--ttt-exclude — string
--ttt-log-out — file
--ttt-patch-size — number
--ttt-mask-prob — number
--ttt-mask-value — number
--ttt-max-batches — number
--ttt-max-grad-norm — number
--ttt-cotta-ema-momentum — number
--ttt-cotta-augmentations — string
--ttt-cotta-aggregation — string
--ttt-cotta-restore-prob — number
--ttt-cotta-restore-interval — number
--ttt-eata-conf-min — number
--ttt-eata-entropy-min — number
--ttt-eata-entropy-max — number
--ttt-eata-min-valid-dets — number
--ttt-eata-anchor-lambda — number
--ttt-eata-selected-ratio-min — number
--ttt-eata-max-skip-streak — number
--ttt-sar-rho — number
--ttt-sar-adaptive — string
--no-ttt-sar-adaptive — string
--ttt-sar-first-step-scale — number
--ttt-sdft-task — string
--ttt-aux-pose-weight — number
--ttt-aux-keypoints-weight — number
--ttt-aux-depth-weight — number
--ttt-aux-seg-weight — number
--ttt-aux-temperature — number
--infer-batch-size — default=1, number
--torch-compile — string
--torch-compile-backend — default=inductor, string
--torch-compile-mode — default=reduce-overhead, string
--torch-compile-fullgraph — string
--no-torch-compile-fullgraph — string
--torch-compile-dynamic — default=auto, string
--allow-compile-fallback — string
--torch-amp — default=off, string
--torch-channels-last — string
--no-torch-channels-last — string
--torch-inference-mode — string
--no-torch-inference-mode — string
--tta-mode — string
--tta-keypoint-swap-pairs — string
--tta-model-merge-iou — number

Examples

python3 tools/export_predictions.py --adapter dummy --dataset data/coco128 --wrap --output reports/predictions_dummy.json
python3 tools/export_predictions.py --adapter rtdetr_pose --dataset data/coco128 --torch-compile --torch-compile-backend inductor --torch-compile-mode reduce-overhead --torch-compile-dynamic auto --wrap --output reports/predictions_compiled.json

Implementation · checkpoint_compatibility.md · real_model_interface.md · training_inference_export.md · ttt_protocol.md

export_predictions_coco_keypoints — Convert COCO-style keypoints results JSON into the YOLOZU predictions interface contract for downstream eval and parity.

experimental tools/export_predictions_coco_keypoints.py

Inputs

--results-json — required, file
--instances-json — required, file
--output — required, file
--score-threshold — number
--force — string

Examples

python3 tools/export_predictions_coco_keypoints.py --results-json reports/mmpose_results.json --instances-json data/coco/person_keypoints_val2017.json --output reports/predictions_mmpose.json

Implementation · interop_detectron2_mmdet.md · tools_index.md · training_inference_export.md · 04_cli_reference.tex · 07_training_run_contract.tex

export_predictions_detectron2 — Run fail-closed Detectron2 inference and export explicitly versioned predictions.json with protocol, execution-evidence, and provenance metadata.

experimental tools/export_predictions_detectron2.py

Inputs

--dataset — required, dir
--split — string
--config — required, file
--weights — required, file
--output — required, file
--max-images — number
--score-thr — default=0.25, number
--topk — default=300, number
--device — default=cuda, string
--imgsz — default=640, number
--protocol — default=nms_applied, string
--input-color — default=BGR, string
--normalize-scale — default=1.0, string
--normalize-mean — default=, string
--normalize-std — default=, string
--resize-policy — default=config_shortest_edge, string
--pad-policy — default=config_pad_to_stride, string
--dry-run — string
--strict — string

Examples

python3 tools/export_predictions_detectron2.py --dataset data/coco-yolo --split val2017 --config configs/detectron2/faster_rcnn_R_50_FPN_1x.yaml --weights runs/d2/model_final.pth --score-thr 0.25 --protocol nms_applied --output reports/pred_detectron2.json

Implementation · README.md · README.md · byop_quickstarts.md · external_inference.md · interop_detectron2_mmdet.md · predictions_schema.md · schema_governance.md · 05_workflows_eval_export.tex

export_predictions_executorch — Decode declared ExecuTorch runtime output JSON into YOLOZU predictions JSON (dry-run supported for interface contract validation).

experimental tools/export_predictions_executorch.py

Inputs

--dataset — required, dir
--split — string
--max-images — number
--model — file
--boxes-scale — string
--runtime-output-json — file
--min-score — number
--topk — number
--output — default=reports/predictions_executorch.json, file
--wrap — string
--strict — string
--dry-run — string

Examples

python3 tools/export_predictions_executorch.py --dataset data/smoke --split val --dry-run --wrap --output reports/pred_executorch.json
python3 tools/export_predictions_executorch.py --dataset data/smoke --split val --model exports/model.pte --runtime-output-json reports/executorch_runtime_outputs.json --wrap --output reports/pred_executorch.json

Implementation · external_inference.md · 05_workflows_eval_export.tex

export_predictions_mmdet — Run fail-closed MMDetection inference and export explicitly versioned predictions.json with protocol, execution-evidence, and provenance metadata.

experimental tools/export_predictions_mmdet.py

Inputs

--dataset — required, dir
--split — string
--config — required, file
--checkpoint — required, file
--output — required, file
--max-images — number
--score-thr — default=0.25, number
--topk — default=300, number
--device — default=cuda:0, string
--imgsz — default=640, number
--protocol — default=nms_applied, string
--input-color — default=BGR, string
--normalize-scale — default=1.0, string
--normalize-mean — default=, string
--normalize-std — default=, string
--resize-policy — default=config_resize, string
--pad-policy — default=config_pad, string
--dry-run — string
--strict — string

Examples

python3 tools/export_predictions_mmdet.py --dataset data/coco-yolo --split val2017 --config configs/mmdet/faster_rcnn_r50_fpn_1x_coco.py --checkpoint runs/mmdet/epoch_12.pth --score-thr 0.25 --protocol nms_applied --output reports/pred_mmdet.json

export_predictions_onnxrt — Run ONNXRuntime inference and export YOLOZU predictions JSON (requires onnxruntime + numpy + opencv; see Rust ONNXRuntime template notes in external inference docs).

experimental tools/export_predictions_onnxrt.py

Inputs

--onnx — default=None, file
--output — default=reports/predictions_onnxrt.json, file
--dataset — dir
--split — string
--max-images — number
--input-name — string
--combined-output — string
--combined-format — string
--boxes-output — file
--boxes-format — string
--boxes-scale — string
--class-output — file
--scores-output — file
--raw-output — file
--raw-format — string
--raw-postprocess — string
--nms-iou — number
--agnostic-nms — string
--topk — number
--min-score — number
--wrap — string
--strict — string
--dry-run — string

Examples

python3 tools/export_predictions_onnxrt.py --dataset data/coco128 --onnx /abs/path/model.onnx --combined-output output0 --combined-format xyxy_score_class --boxes-scale abs --min-score 0.0 --wrap --output reports/pred_onnxrt.json

Implementation · onnx_export_parity.md · external_inference.md · 05_workflows_eval_export.tex · README.md

export_predictions_opencv_dnn — Run OpenCV-DNN inference on an ONNX model and export YOLOZU predictions JSON (YOLOv8 84 or YOLOv5 85+obj raw heads supported).

experimental tools/export_predictions_opencv_dnn.py

Inputs

--dataset — required, dir
--split — string
--max-images — number
--onnx — file
--input-size — number
--output-names — string
--output-index — number
--raw-format — string
--boxes-scale — string
--min-score — number
--nms-iou — number
--max-det — number
--agnostic-nms — string
--swap-rb — string
--dnn-backend — string
--dnn-target — string
--strict — string
--output — file
--meta-output — file
--dry-run — string
--dump-io — file

Examples

python3 tools/export_predictions_opencv_dnn.py --dataset data/coco128 --dry-run --output reports/pred_opencv_dnn.json
python3 tools/export_predictions_opencv_dnn.py --dataset data/coco128 --raw-format yolo_85_obj --dry-run --output reports/pred_opencv_dnn_yolov5_raw.json

Implementation · opencv_dnn_inference.md · external_inference.md · 05_workflows_eval_export.tex

export_predictions_opencv_dnn_rtdetr — Run OpenCV-DNN inference on an RT-DETR ONNX model and export YOLOZU predictions JSON (no NMS), recording fixed preprocess/export_settings.

experimental tools/export_predictions_opencv_dnn_rtdetr.py

Inputs

--dataset — required, dir
--split — string
--max-images — number
--onnx — file
--imgsz — number
--keep-aspect — string
--letterbox-fill — string
--input-color — string
--scale — number
--mean — string
--std — string
--outputs — string
--boxes-output — string
--logits-output — string
--labels-output — string
--scores-output — string
--print-outputs — string
--boxes-format — string
--boxes-scale — string
--scores-activation — string
--background-class — string
--score-thr — number
--topk — number
--dnn-backend — string
--dnn-target — string
--strict — string
--output — file
--meta-output — file
--dry-run — string
--dump-io — file

Examples

python3 tools/export_predictions_opencv_dnn_rtdetr.py --dataset data/coco128 --dry-run --output reports/pred_rtdetr_opencv_dnn.json
python3 -m yolozu export --backend opencv-dnn-rtdetr --onnx path/to/model.onnx --dataset data/coco128 --imgsz 640 --score-thr 0.01 --output reports/pred_rtdetr_opencv_backend.json --force

Implementation · opencv_dnn_inference.md · external_inference.md · 05_workflows_eval_export.tex

export_predictions_opencv_dnn_unified — Unified OpenCV-DNN exporter with preprocess/decode presets, IO dump, and backend/target controls.

experimental tools/export_predictions_opencv_dnn_unified.py

Inputs

--dataset — required, dir
--split — string
--max-images — number
--onnx — required, file
--imgsz — default=640, number
--preprocess — string
--decode — default=auto, string
--score-thr — default=0.01, number
--nms-iou — default=0.45, number
--topk — default=300, number
--dnn-backend — default=opencv, string
--dnn-target — default=cpu, string
--dump-io — file
--meta-output — file
--dry-run — string
--strict — string
--output — required, file

Examples

python3 tools/export_predictions_opencv_dnn_unified.py --dataset data/coco-yolo --split val2017 --onnx path/to/model.onnx --imgsz 640 --decode auto --preprocess yolo_letterbox_640 --dnn-backend opencv --dnn-target cpu --dump-io reports/opencv_dump_io.json --output reports/pred_opencv.json

Implementation · README.md · README.md · opencv_dnn_inference.md · external_inference.md · 05_workflows_eval_export.tex

export_predictions_openvino — Run OpenVINO detection inference and export YOLOZU predictions JSON via the declared combined-output decode path.

experimental tools/export_predictions_openvino.py

Inputs

--dataset — required, dir
--split — string
--max-images — number
--model — file
--device — string
--imgsz — number
--input-size — number
--input-name — string
--combined-output — string
--combined-format — string
--boxes-scale — string
--min-score — number
--topk — number
--output — default=reports/predictions_openvino.json, file
--wrap — string
--strict — string
--dry-run — string

Examples

python3 tools/export_predictions_openvino.py --dataset data/smoke --split val --model exports/model.xml --wrap --output reports/pred_openvino.json
python3 tools/export_predictions_openvino.py --dataset data/smoke --split val --dry-run --wrap --output reports/pred_openvino.json

Implementation · external_inference.md · benchmark_support_matrix.md · benchmark_mode.md

export_predictions_torchscript — Run TorchScript detection inference and export YOLOZU predictions JSON via the declared combined-output decode path.

experimental tools/export_predictions_torchscript.py

Inputs

--dataset — required, dir
--split — string
--max-images — number
--model — file
--device — string
--imgsz — number
--input-size — number
--combined-output — string
--combined-format — string
--boxes-scale — string
--min-score — number
--topk — number
--output — default=reports/predictions_torchscript.json, file
--wrap — string
--strict — string
--dry-run — string

Examples

python3 tools/export_predictions_torchscript.py --dataset data/smoke --split val --model exports/model.torchscript --wrap --output reports/pred_torchscript.json
python3 tools/export_predictions_torchscript.py --dataset data/smoke --split val --dry-run --wrap --output reports/pred_torchscript.json

Implementation · external_inference.md · benchmark_support_matrix.md · benchmark_mode.md

export_predictions_trt — Run TensorRT engine inference and export YOLOZU predictions JSON (requires tensorrt + CUDA bindings).

experimental tools/export_predictions_trt.py

Inputs

--engine — default=None, file
--imgsz — default=None, number
--output — default=reports/predictions_trt.json, file
--dataset — dir
--split — string
--max-images — number
--input-name — string
--combined-output — string
--combined-format — string
--boxes-output — file
--boxes-format — string
--boxes-scale — string
--class-output — file
--scores-output — file
--raw-output — file
--raw-format — string
--raw-postprocess — string
--nms-iou — number
--agnostic-nms — string
--topk — number
--min-score — number
--wrap — string
--strict — string
--dry-run — string

Examples

python3 tools/export_predictions_trt.py --dataset /path/to/coco-yolo --engine engines/yolo26n_fp16.plan --combined-output output0 --boxes-scale abs --wrap --output reports/pred_trt_yolo26n.json

Implementation · tensorrt_pipeline.md

export_predictions_yolo_runtime — Run bounded external YOLO-runtime inference and export explicitly versioned predictions.json with cardinality-checked execution evidence.

stable tools/export_predictions_yolo_runtime.py

Inputs

--model — required, file
--dataset — required, dir
--split — string
--source — string
--output — required, file
--image-size — default=640, number
--conf — default=0.001, number
--iou — default=0.7, number
--stride — default=32, number
--max-det — default=300, number
--max-images — number
--batch — default=1, number
--device — default=cuda, string
--half — string
--letterbox — string
--no-letterbox — string
--protocol — string
--end2end — string
--no-end2end — string
--wrap — string
--strict — string
--dry-run — string

Examples

python3 tools/export_predictions_yolo_runtime.py --model yolo11n.pt --dataset data/coco-yolo --split val2017 --max-images 8 --conf 0.25 --iou 0.45 --protocol nms_applied --wrap --output reports/pred_yolo_runtime.json
python3 tools/export_predictions_yolo_runtime.py --model yolo11n.pt --dataset data/smoke --split val --max-images 1 --protocol nms_applied --dry-run --wrap --strict --output reports/pred_yolo_runtime_dry_run.json

Implementation · byop_quickstarts.md · external_inference.md · predictions_schema.md · schema_governance.md · 05_workflows_eval_export.tex

export_predictions_yolov5 — Convert YOLOv5 outputs (save-txt or xyxy JSON) into YOLOZU predictions.json with recorded export_settings.

experimental tools/export_predictions_yolov5.py

Inputs

--dataset — required, dir
--split — string
--labels-dir — dir
--json — file
--output — required, file
--max-images — number
--conf-default — default=1.0, number
--protocol — default=nms_applied, string
--imgsz — default=640, number
--conf — default=0.25, number
--iou — default=0.45, number
--stride — default=32, number
--letterbox — string
--no-letterbox — string
--strict — string

Examples

python3 tools/export_predictions_yolov5.py --dataset data/coco-yolo --split val2017 --labels-dir runs/detect/exp/labels --protocol nms_applied --output reports/pred_yolov5.json

Implementation · No dedicated prose page.

export_predictions_yolox — Run fail-closed YOLOX inference (or dry-run) and export explicitly versioned predictions.json with execution evidence and exp/checkpoint provenance.

experimental tools/export_predictions_yolox.py

Inputs

--dataset — required, dir
--split — string
--output — required, file
--max-images — number
--exp — file
--weights — file
--device — default=cuda, string
--imgsz — default=640, number
--score-thr — default=0.01, number
--nms-thr — default=0.65, number
--topk — default=300, number
--protocol — default=nms_applied, string
--dry-run — string
--strict — string

Examples

python3 tools/export_predictions_yolox.py --dataset data/coco-yolo --split val2017 --exp /path/to/yolox_exp.py --weights /path/to/yolox_ckpt.pth --imgsz 640 --score-thr 0.01 --nms-thr 0.65 --output reports/pred_yolox.json

Implementation · README.md · README.md · byop_quickstarts.md · interop_yolox.md · external_inference.md · predictions_schema.md · schema_governance.md · 05_workflows_eval_export.tex

export_trt — Fail-closed PyTorch → ONNX → TensorRT export route with shared RT-DETR checkpoint compatibility evidence.

experimental tools/export_trt.py

Inputs

--config — default=rtdetr_pose/configs/base.json, file
--checkpoint — file
--allow-partial-checkpoint — string
--device — string
--image-size — number
--onnx — default=models/model.onnx, file
--onnx-meta — file
--opset — number
--input-name — string
--dynamic-hw — string
--engine — default=engines/model_fp16.plan, file
--engine-meta — file
--precision — string
--min-shape — string
--opt-shape — string
--max-shape — string
--workspace — number
--timing-cache — default=engines/timing.cache, file
--trtexec — string
--extra-args — string
--skip-onnx — string
--skip-engine — string
--dry-run — string

Examples

python3 tools/export_trt.py --config rtdetr_pose/configs/base.json --checkpoint /path/to/checkpoint.pt --image-size 320 --onnx models/rtdetr_pose.onnx --dynamic-hw --engine engines/rtdetr_pose_fp16.plan --precision fp16 --min-shape 1x3x320x320 --opt-shape 1x3x640x640 --max-shape 1x3x960x960

Implementation · checkpoint_compatibility.md · tensorrt_pipeline.md

fetch_coco128 — Fetch tiny COCO subset (YOLO-format) into data/coco128 (official COCO hosting).

stable tools/fetch_coco128.sh

Inputs

No declared CLI inputs.

Examples

bash tools/fetch_coco128.sh

Implementation · No dedicated prose page.

fetch_model — Download a model artifact with cache reuse, sha256 pinning, and explicit license/integrity gates.

stable yolozu/cli.py

Inputs

model_id — required, string
--out — default=models, string
--cache-dir — default=~/.cache/yolozu/models, string
--registry — string
--accept-license — required, string
--allow-unsafe — string
--allow-non-apache — string
--retries — default=3, number
--timeout — default=60, number
--force — string

Examples

python3 -m yolozu fetch yolox-s-coco --out models --accept-license
python3 -m yolozu fetch yolox-s-coco --out models --cache-dir ~/.cache/yolozu/models --accept-license

Implementation · No dedicated prose page.

fresh_install_journey — Install YOLOZU from public PyPI in a clean environment and record the complete stable-lane journey.

stable scripts/fresh_install_journey.sh

Inputs

--python — default=python3, string
--package — default=yolozu, string
--run-dir — default=reports/fresh_install_journey, dir

Examples

bash scripts/fresh_install_journey.sh --run-dir /tmp/yolozu_fresh_install
bash scripts/fresh_install_journey.sh --python python3.12 --package yolozu==4.5.1 --run-dir /tmp/yolozu_4_5_1_py312
bash scripts/fresh_install_journey.sh --help

Implementation · cpu_only_dod.md · README.md · Readme_jp.md · 02_installation.tex

gen_ci_dummy_dets_onnx — Generate a tiny deterministic ONNX model for CI TensorRT/ONNXRuntime smoke parity checks.

stable tools/ci/gen_dummy_dets_onnx.py

Inputs

--out — required, file
--input-name — default=images, string
--output-name — default=output0, string
--shape — default=1x3x64x64, string
--opset — default=17, number
--ir-version — default=11, number
--alpha — default=0.001, number

Examples

python3 tools/ci/gen_dummy_dets_onnx.py --out reports/ci_trt_smoke/model.onnx --shape 1x3x64x64 --opset 17 --ir-version 11

Implementation · ci_incidents.md · README.md · 11_troubleshooting.tex

gen_ci_smoke_dataset — Generate a minimal YOLO-format dataset for CI exporter and parity smoke tests.

stable tools/ci/gen_smoke_dataset.py

Inputs

--out — required, dir
--split — default=val, string
--image-stem — default=000001, string
--hw — default=48x64, string

Examples

python3 tools/ci/gen_smoke_dataset.py --out reports/ci_trt_smoke/dataset --split val --hw 48x64

Implementation · ci_incidents.md · README.md · 11_troubleshooting.tex

generate_benchmark_support_matrix — Generate the canonical benchmark support matrix from support metadata.

stable tools/generate_benchmark_support_matrix.py

Inputs

--metadata — default=yolozu/data/manifest/benchmark_support.json, file
--output — default=docs/benchmark_support_matrix.md, file
--check — string
--json — string

Examples

python3 tools/generate_benchmark_support_matrix.py --check --json
python3 tools/generate_benchmark_support_matrix.py --metadata yolozu/data/manifest/benchmark_support.json --output docs/benchmark_support_matrix.md

Implementation · benchmark_support_matrix.md · benchmark_mode.md · manifest_authoring_workflow.md

generate_integration_tool_reference — Generate the MCP↔Actions interface contract reference from tool_runner + server wrappers and fail on drift in check mode.

stable tools/generate_integration_tool_reference.py

Inputs

--json-out — default=docs/generated/mcp_actions_tool_reference.json, file
--md-out — default=docs/generated/mcp_actions_tool_reference.md, file
--check — string

Examples

python3 tools/generate_integration_tool_reference.py
python3 tools/generate_integration_tool_reference.py --check

Implementation · llm_integrations.md · mcp_extension_architecture.md · mcp_actions_tool_reference.md · 20_llm_mcp_integrations.tex

generate_runtime_parity_case_study — Generate and verify a real Mask R-CNN PyTorch eager versus TorchScript comparison through YOLOZU's stable evaluation lane.

experimental tools/generate_runtime_parity_case_study.py

Inputs

--dataset — default=data/smoke, dir
--split — default=val, string
--max-images — default=2, number
--score-threshold — default=0.5, number
--max-detections — default=20, number
--seed — default=2026, number
--threads — default=1, number
--weights — file
--expected-weights-sha256 — string
--allow-download — string
--output-dir — default=docs/assets/case_studies/maskrcnn_eager_torchscript, dir
--baseline-dir — dir
--metric-atol — default=1e-08, number

Examples

python3 tools/generate_runtime_parity_case_study.py --dataset data/smoke --split val --max-images 2 --score-threshold 0.5 --max-detections 20 --seed 2026 --threads 1 --allow-download --expected-weights-sha256 73cbd0190fcbe3ba339921fbce2c3a0b6bb9126c9a133c85e43a2a8e060a109e --output-dir docs/assets/case_studies/maskrcnn_eager_torchscript
python3 tools/generate_runtime_parity_case_study.py --dataset data/smoke --split val --max-images 2 --weights /path/to/maskrcnn_resnet50_fpn_v2_coco-73cbd019.pth --expected-weights-sha256 73cbd0190fcbe3ba339921fbce2c3a0b6bb9126c9a133c85e43a2a8e060a109e --output-dir /tmp/yolozu-runtime-reproduction --baseline-dir docs/assets/case_studies/maskrcnn_eager_torchscript

Implementation · maskrcnn_eager_torchscript.md · tools_index.md · 09_parity_bench_protocols.tex

generate_smoke_assets — Generate deterministic offline smoke assets under data/smoke from local data/coco128.

stable tools/generate_smoke_assets.py

Inputs

--help — string

Examples

python3 tools/generate_smoke_assets.py
python3 tools/generate_smoke_assets.py --help

Implementation · No dedicated prose page.

generate_web_docs — Safely generate searchable onboarding web docs from repository-local SSOT sources, validated URLs, schemas, and curated evidence.

stable tools/generate_web_docs.py

Inputs

--manifest — default=tools/manifest.json, file
--schemas — default=docs/schemas, dir
--content — default=docs/web_docs_content.json, file
--output — default=docs/generated/web_docs, dir
--check — string
--json — string

Examples

python3 tools/generate_web_docs.py
python3 tools/generate_web_docs.py --check --json

Implementation · python_api.md · web_docs_content.json · web_docs_plan.md · index.html

gpu_validation_preflight — Generate a preflight report that splits the YOLOZU-zisn GPU sweep into local-executable checks and GPU-runtime checks.

experimental tools/gpu_validation_preflight.py

Inputs

--output — default=reports/gpu_validation_preflight.json, file
--strict — string

Examples

python3 tools/gpu_validation_preflight.py --output reports/gpu_validation_preflight.json
python3 tools/gpu_validation_preflight.py --strict --output reports/gpu_validation_preflight.json

Implementation · runpod_gpu_validation_split.md · doctor_diagnostics.md · 17_realtime_batch_inference.tex

hpo_sweep — Run a configurable parameter sweep (grid or list) and emit JSONL/CSV/MD results.

stable tools/hpo_sweep.py

Inputs

--config — required, file
--dry-run — string
--max-runs — number
--resume — string

Examples

python3 tools/hpo_sweep.py --config docs/hpo_sweep_example.json --dry-run

Implementation · hpo_sweep.md

import_yolo_data_yaml — Import YOLO-style data.yaml into a YOLOZU dataset wrapper and classes mapping (classes.json/classes.txt).

stable tools/import_yolo_data_yaml.py

Inputs

--data-yaml — required, file
--split — string
--output — required, dir
--force — string

Examples

python3 tools/import_yolo_data_yaml.py --data-yaml data/coco-yolo/data.yaml --split val2017 --output data/yolo_wrapper --force

Implementation · No dedicated prose page.

list_models — List fetchable model IDs from the built-in (or custom) model registry.

stable yolozu/cli.py

Inputs

--registry — string
--json — string

Examples

python3 -m yolozu list models
python3 -m yolozu list models --registry path/to/model_registry.json --json

Implementation · No dedicated prose page.

make_subset_dataset — Create a deterministic subset YOLO dataset (symlink/copy images+labels) for reproducible eval/ablation runs.

stable tools/make_subset_dataset.py

Inputs

--dataset — required, dir
--split — default=None, string
--n — default=50, number
--seed — default=0, number
--out — default=reports/subset_dataset, dir
--copy — string
--overwrite — string
--strategy — string

Examples

python3 tools/make_subset_dataset.py --dataset data/coco128 --split train2017 --n 50 --seed 0 --out reports/coco128_50

Implementation · No dedicated prose page.

measure_trt_latency — Measure a TensorRT engine's latency/FPS and write a metrics report JSON.

experimental tools/measure_trt_latency.py

Inputs

--engine — file
--shape — string
--input-name — string
--iterations — default=200, number
--warmup — default=20, number
--dry-run — string
--notes — string
--output — default=reports/latency_trt.json, file

Examples

python3 tools/measure_trt_latency.py --engine engines/yolo26n_fp16.plan --shape 1x3x640x640 --iterations 200 --warmup 20 --output reports/latency_yolo26n.json

Implementation · benchmark_latency.md · tensorrt_pipeline.md

normalize_predictions — Normalize prediction class ids (category_id↔class_id) and optionally wrap with meta.

stable tools/normalize_predictions.py

Inputs

--input — required, file
--output — required, file
--classes — file
--assume-class-id-is-category-id — string
--wrap — string

Examples

python3 tools/normalize_predictions.py --input reports/predictions.json --output reports/predictions_norm.json --classes data/coco-yolo/labels/val2017/classes.json --wrap

Implementation · No dedicated prose page.

orchestrate_train — Lightweight experiment orchestration entrypoint for training: expand a multi-backend spec into planned commands or execute them, support top-level defaults such as dataset/split/resume_from, emit one orchestration report JSON, and optionally append executed runs to a shared JSONL registry with backend counts and registry_summary.

experimental tools/orchestrate_train.py

Inputs

--spec — required, file
--output — file
--execute — string
--dry-run — string
--stop-on-failure — string
--registry-out — file

Examples

python3 tools/orchestrate_train.py --spec reports/train_orchestration_spec.json --output reports/training_orchestration_report.json
python3 -m yolozu train-orchestrate --spec reports/train_orchestration_spec.json --output reports/training_orchestration_report.json --execute
python3 tools/orchestrate_train.py --spec reports/train_orchestration_spec.json --output reports/training_orchestration_report.json --registry-out reports/training_registry.jsonl --execute

Implementation · training_backend_interface.md · training_capability_matrix.md · training_orchestration.md · tools_index.md · 04_cli_reference.tex · 07_training_run_contract.tex

package_segmentation_predictions — Package a class-id mask directory into the YOLOZU segmentation predictions interface contract.

experimental tools/package_segmentation_predictions.py

Inputs

--dataset-json — required, file
--masks-dir — required, dir
--output — required, file
--suffix — string
--relative-to-output — string
--force — string

Examples

python3 tools/package_segmentation_predictions.py --dataset-json data/seg/dataset.json --masks-dir reports/mmseg_masks --output reports/segmentation_predictions_mmseg.json

Implementation · interop_detectron2_mmdet.md · tools_index.md · training_inference_export.md · 04_cli_reference.tex · 07_training_run_contract.tex

pre_push — Run local pre-push gates (ruff, focused unit tests including manifest/generated-reference/SSOT coverage and external bridge dry-run DoD, offline smoke, and real-image preflight) to catch CI failures before pushing.

stable scripts/pre_push.sh

Inputs

--skip-ruff — string
--skip-tests — string
--skip-smoke — string
--skip-real-preflight — string
--prepare-real-data — string

Examples

bash scripts/pre_push.sh
bash scripts/pre_push.sh --skip-real-preflight
bash scripts/pre_push.sh --skip-smoke

Implementation · CONTRIBUTING.md · release_reliability_checklist.md · ssot_capability_coverage_audit.md

prepare_ade20k_seg — Prepare ADE20K semantic segmentation layout + dataset.json manifest.

stable tools/prepare_ade20k_seg.py

Inputs

--ade20k-root — required, dir
--out — required, dir
--split — default=train, string
--ignore-index — number
--mode — string
--force — string

Examples

python3 tools/prepare_ade20k_seg.py --ade20k-root /path/to/ADEChallengeData2016 --split train --out data/ade20k_seg --mode manifest

Implementation · No dedicated prose page.

prepare_cityscapes_seg — Prepare Cityscapes semantic segmentation layout + dataset.json manifest.

stable tools/prepare_cityscapes_seg.py

Inputs

--cityscapes-root — required, dir
--out — required, dir
--split — default=train, string
--label-type — string
--mode — string
--force — string

Examples

python3 tools/prepare_cityscapes_seg.py --cityscapes-root /path/to/cityscapes --split train --out data/cityscapes_seg --mode manifest

Implementation · No dedicated prose page.

prepare_coco_instance_seg — Convert official COCO instances JSON into YOLO-format labels + per-instance PNG masks + sidecar metadata for instance-seg eval.

stable tools/prepare_coco_instance_seg.py

Inputs

--coco-root — required, dir
--out — required, dir
--split — default=val2017, string
--include-crowd — string
--instances-json — file
--copy-images — string
--max-instances-per-image — number
--max-images — number

Examples

python3 tools/prepare_coco_instance_seg.py --coco-root /path/to/coco --split val2017 --out data/coco-instance-seg

Implementation · No dedicated prose page.

prepare_coco_yolo — Convert official COCO instances JSON into YOLO-format labels + (optional) copy images.

stable tools/prepare_coco_yolo.py

Inputs

--coco-root — required, dir
--out — required, dir
--split — default=val2017, string
--include-crowd — string
--instances-json — file
--copy-images — string

Examples

python3 tools/prepare_coco_yolo.py --coco-root /path/to/coco --split val2017 --out data/coco-yolo

Implementation · No dedicated prose page.

prepare_keypoints_dataset — Prepare keypoints dataset in one command (auto-detect YOLO Pose or COCO keypoints) and emit YOLOZU-ready dataset wrapper.

stable tools/prepare_keypoints_dataset.py

Inputs

--source — required, string
--out — required, dir
--list-formats — string
--format — string
--split — string
--num-keypoints — number
--keypoint-names — string
--annotations — file
--images-dir — string
--out-split — string
--min-kps — number
--max-images — number
--link-images — string
--category-id — number
--category-name — string
--class-id — number
--cvat-images-dir — string

Examples

python3 tools/prepare_keypoints_dataset.py --source /path/to/export --format auto --out data/keypoints_dataset
python3 tools/prepare_keypoints_dataset.py --source /path/to/cvat_export --format cvat_xml --out data/keypoints_dataset

Implementation · cvat_keypoints_recovery.md

prepare_real_multitask_fewshot — Create a small real-image multitask few-shot dataset (bbox/seg/keypoints/depth/pose sidecars) from COCO instances, with optional tiny COCO auto-download and explicit label provenance metadata.

stable tools/prepare_real_multitask_fewshot.py

Inputs

--instances-json — default=data/coco/annotations/instances_val2017.json, file
--images-dir — default=data/coco/images/val2017, dir
--out — default=data/real_multitask_fewshot, dir
--train-images — default=6, number
--val-images — default=2, number
--num-keypoints — default=4, number
--download-if-missing — string
--download-num-images — number
--download-seed — number
--download-timeout — number
--force — string
--allow-auto-download — string
--accept-dataset-license — string
--strict-provenance — string
--strict-realism — string

Examples

python3 scripts/download_coco_instances_tiny.py --out-root data/coco --split val2017 --num-images 8 --seed 0 --force && python3 tools/prepare_real_multitask_fewshot.py --instances-json data/coco/annotations/instances_val2017.json --images-dir data/coco/images/val2017 --out data/real_multitask_fewshot --train-images 6 --val-images 2 --num-keypoints 4 --strict-provenance --force

Implementation · training_inference_export.md · 16_depth_6dof_symmetry.tex

prepare_ttt_domain_shift_target — Prepare deterministic domain-shift target dataset and recipe JSON for reproducible TTT evidence.

research scripts/prepare_ttt_domain_shift_target.py

Inputs

--dataset-root — required, dir
--split — default=val, string
--out — required, dir
--corruption — default=gaussian_blur, string
--severity — default=2, number
--seed — default=0, number
--max-images — number
--copy-labels — string
--no-copy-labels — string
--force — string
--recipe-out — file

Examples

python3 scripts/prepare_ttt_domain_shift_target.py --dataset-root data/smoke --split val --out reports/domain_shift/smoke_gaussian_blur_s2 --corruption gaussian_blur --severity 2 --seed 2026 --force

Implementation · ttt_protocol.md · 15_ttt_tent_mim.tex

prepare_voc_seg — Prepare Pascal VOC semantic segmentation layout + dataset.json manifest.

stable tools/prepare_voc_seg.py

Inputs

--voc-root — required, dir
--out — required, dir
--split — default=train, string
--mode — string
--masks-dirname — string
--force — string
--year — string

Examples

python3 tools/prepare_voc_seg.py --voc-root /path/to/VOCdevkit/VOC2012 --split train --out data/voc_seg --mode manifest

Implementation · No dedicated prose page.

publish_benchmark_table — Generate official benchmark publication table (JSON+Markdown) from benchmark reports with run-id traceability.

stable tools/publish_benchmark_table.py

Inputs

--report — required, file
--output-json — default=reports/benchmark_table.json, file
--output-md — default=reports/benchmark_table.md, file
--title — string
--cadence — default=weekly, string
--protocol-id — default=yolo26, string
--source-command — string
--publication-run-id — string

Examples

python3 tools/publish_benchmark_table.py --report reports/benchmark_latency.json --output-json reports/benchmark_table.json --output-md reports/benchmark_table.md --source-command "python3 tools/benchmark_latency.py --config configs/benchmark_latency_example.json"

Implementation · benchmark_publication.md · yolo26_eval_protocol.md

refine_predictions_hessian — Refine pose-related prediction fields with an engine-external Newton/finite-diff Hessian stepper and optional research_report log boundary; the public CLI rollout is offsets-first and opt-in.

research tools/refine_predictions_hessian.py

Inputs

--predictions — required, file
--output — required, file
--config — file
--enable — string
--disable — string
--wrap — string
--refine-offsets — string
--dataset — dir
--split — string
--device — string
--steps — number
--damping — number
--fd-eps — number
--line-search — number
--line-search-decay — number
--w-reg — number
--w-depth — number
--w-mask — number
--max-step-px — number
--max-total-update-px — number
--tol-delta — number
--tol-loss — number
--log-output — file
--log-steps — string
--dry-run — string

Examples

python3 tools/refine_predictions_hessian.py --predictions reports/predictions.json --output reports/predictions_refined.json --enable --refine-offsets --config configs/runtime/hessian_refine_example.yaml --wrap

Implementation · README.md · ttt_protocol.md · hessian_solver.md · production_readiness.md · research_lanes.md · research_lane_report.schema.json

release — Single-command release automation: validate current metadata, atomically synchronize package version, dated CHANGELOG and CITATION metadata, and explicitly current-release-coupled source/packaged manifest examples; then auto-version, tag, publish a GitHub release, and hand off once to the PyPI and Zenodo workflows. Historical manifest examples require explicit evidence and are not auto-bumped. The publish workflow revalidates synchronized metadata before upload, then verifies that PyPI exposes the released wheel and sdist. The container workflow can reuse the same release_tag for GHCR publication and NGC mirroring under nvcr.io/yolozu/....

stable release.sh

Inputs

--dry-run — string
--check — string
--versioning — default=auto, string
--output — default=reports/release_report.json, file
--allow-dirty — string
--allow-non-main — string
--skip-checks — string
--skip-gh — string
--skip-zenodo — string

Examples

bash release.sh
bash release.sh --dry-run --allow-dirty --allow-non-main --output reports/release_report.dry_run.json
bash release.sh --dry-run --versioning calver --allow-dirty --allow-non-main --output reports/release_report.calver.json

Implementation · README.md · RELEASE.md · README.md · README.md · release_reliability_checklist.md · manual_doi_release.md · tools_index.md · 12_tool_registry.tex

release_tag — Release/tag operation helper that fails closed unless package version, requested tag, dated CHANGELOG heading, CITATION version/date, and source/packaged manifests agree; after validation it can create/push tags and create GitHub draft/published releases with report output. Downstream publish automation can reuse the same release_tag for GHCR publication and NGC mirroring under nvcr.io/yolozu/....

stable tools/release_tag.py

Inputs

--version — string
--tag-prefix — default=v, string
--title — string
--notes-file — file
--release-state — default=none, string
--push-tag — string
--run-checks — string
--allow-dirty — string
--allow-non-main — string
--dry-run — string
--output — default=reports/release_tag_report.json, file

Examples

python3 tools/release_tag.py --dry-run --run-checks --release-state draft --push-tag --output reports/release_tag_report.json
python3 tools/release_tag.py --run-checks --release-state publish --push-tag --output reports/release_tag_report.publish.json

Implementation · RELEASE.md · README.md · README.md · release_reliability_checklist.md · manual_doi_release.md · tools_index.md · 12_tool_registry.tex

render_synthgen_overlay — Render semantic + instance + keypoint overlays from SynthGen shard samples.

experimental tools/render_synthgen_overlay.py

Inputs

--dataset-root — required, dir
--schema-id — string
--sample-index — default=0, number
--alpha — default=0.45, number
--output — required, file

Examples

python3 tools/render_synthgen_overlay.py --dataset-root /path/to/synthgen_dataset --schema-id animal_v1 --sample-index 0 --output reports/synthgen_overlay_animal.png

Implementation · synthgen_intake.md · synthgen_repo_integration.md · synthgen_contract.md · production_readiness.md

render_ttt_manual_figures — Render the six-file docs/manual TTT figure bundle atomically from validated synthetic-fixture or hash-bound measured sources.

research tools/render_ttt_manual_figures.py

Inputs

--source-json — default=docs/assets/ttt_method_results_source.json, file
--docs-assets-dir — default=docs/assets, dir
--manual-figures-dir — default=manual/figures, dir

Examples

python3 tools/render_ttt_manual_figures.py
python3 tools/render_ttt_manual_figures.py --docs-assets-dir tmp/ttt_docs --manual-figures-dir tmp/ttt_manual

Implementation · ttt_protocol.md · ttt_compare_boilerplates.md · 15_ttt_tent_mim.tex · production_readiness.md

report_dependency_licenses — Generate a best-effort dependency license report from installed Python packages (not legal advice).

stable tools/report_dependency_licenses.py

Inputs

--output — default=reports/dependency_licenses.json, file
--requirements — file
--only-direct — string
--fail-on-copyleft — string

Examples

python3 tools/report_dependency_licenses.py --output reports/dependency_licenses.json

Implementation · license_policy.md

rtdetr_pose_backend_suite — Fail-closed RT-DETR backend parity + benchmark suite with shared checkpoint compatibility evidence.

experimental tools/rtdetr_pose_backend_suite.py

Inputs

--config — required, file
--checkpoint — file
--allow-partial-checkpoint — string
--device — string
--image-size — number
--batch — number
--samples — number
--seed — number
--onnx — file
--engine — file
--input-name — string
--onnx-meta — file
--engine-meta — file
--embed-meta — string
--trtexec — string
--backends — string
--reference — string
--score-atol — number
--bbox-atol — number
--warmup — number
--iterations — number
--output — default=reports/rtdetr_pose_backend_suite.json, file
--dry-run — string

Examples

python3 tools/rtdetr_pose_backend_suite.py --config rtdetr_pose/configs/base.json --checkpoint /path/to/checkpoint.pt --onnx models/rtdetr_pose.onnx --backends torch,onnxrt --device cpu --image-size 320 --samples 2 --warmup 20 --iterations 200 --output reports/rtdetr_pose_backend_suite.json

Implementation · checkpoint_compatibility.md · real_model_interface.md · tensorrt_pipeline.md

rtdetr_pose_train_continual — Continual fine-tuning runner for rtdetr_pose that wires replay + checkpoint-based self-distillation (passes --self-distill-from <prev_ckpt> to train_minimal), with optional LoRA/EWC/SI and a documented QLoRA-compatible path through the trainer config. Backbone swaps are configured via model.backbone.* in the model config (P3/P4/P5 interface contract).

research rtdetr_pose/tools/train_continual.py

Inputs

--config — required, file
--run-dir — dir
--replay-size — number
--replay-fraction — number
--replay-per-task-cap — number

Examples

python3 rtdetr_pose/tools/train_continual.py --config configs/continual/rtdetr_pose_domain_inc_example.yaml
python3 rtdetr_pose/tools/train_continual.py --config configs/continual/rtdetr_pose_domain_inc_example.yaml --replay-size 0

Implementation · continual_learning.md · backbones.md · quantization.md · training_inference_export.md · README.md

run_actions_api — Run the GPT Actions API, including fail-closed typed TTT/CTTA export jobs with full checkpoint preflight.

stable tools/run_actions_api.py

Inputs

--host — default=0.0.0.0, string
--port — default=8080, number
--workers — default=1, number
--reload — string

Examples

python3 tools/run_actions_api.py
python3 tools/run_actions_api.py --host 127.0.0.1 --port 8080 --workers 1

Implementation · llm_integrations.md · mcp_extension_architecture.md · openai_mcp_actions.md · 20_llm_mcp_integrations.tex

run_external_finetune_smoke — Run external finetune smoke matrix for YOLOX/Ultralytics/MMDetection/Detectron2/RT-DETR and emit a machine-readable interface contract report with dependency-classified failures, train-path audit fields, and an explicit Apache-2.0-first license boundary.

experimental tools/run_external_finetune_smoke.py

Inputs

--dataset-root — default=data/smoke, dir
--split — default=train, string
--output — default=reports/external_finetune_smoke.json, file
--work-dir — dir
--python — string
--epochs — default=1, number
--max-steps — default=1, number
--batch-size — default=2, number
--image-size — default=96, number
--device — default=cpu, string
--framework — string
--non-dry-framework — string
--require-non-dry — string
--require-training-execution — string
--mmdet-train-script — file
--detectron2-train-script — file
--yolox-train-script — file

Examples

python3 tools/run_external_finetune_smoke.py --dataset-root data/smoke --split train --output reports/external_finetune_smoke.json
python3 tools/run_external_finetune_smoke.py --dataset-root data/smoke --split train --non-dry-framework yolox --non-dry-framework yolov --non-dry-framework rtdetr --yolox-train-script /path/to/YOLOX/tools/train.py --epochs 1 --max-steps 1 --batch-size 2 --image-size 96 --device cpu --require-training-execution --output reports/external_finetune_smoke.exec.json
python3 tools/run_external_finetune_smoke.py --dataset-root /path/to/dataset --split train --non-dry-framework mmdetection --non-dry-framework detectron2 --mmdet-train-script /path/to/mmdetection/tools/train.py --detectron2-train-script /path/to/detectron2/tools/train_net.py --epochs 1 --batch-size 2 --require-training-execution --output reports/external_finetune_smoke.external.json

Implementation · external_finetune_smoke.md · interop_detectron2_mmdet.md · interop_yolox.md · license_policy.md · tools_index.md · training_inference_export.md

run_mcp_server — Run the YOLOZU MCP stdio server, expose canonical live tool ids and filtered packaged discovery, and provide typed TTT/CTTA export jobs that reject arbitrary extra args and require status=full checkpoint preflight.

stable tools/run_mcp_server.py

Inputs

--transport — default=stdio, string
--manifest — file
--print-tools — string
--guaranteed — string
--supported — string
--maturity — string
--tag — string
--ids-only — string
--sample-generate-config — string
--sample-review-config — file
--workspace-root — default=., dir

Examples

yolozu-mcp
yolozu-mcp --print-tools --guaranteed --ids-only
yolozu-mcp --print-tools --supported --ids-only
yolozu-mcp --print-tools --ids-only --maturity stable --tag validation
yolozu-mcp --sample-generate-config > reports/ai_generate_config.json && yolozu-mcp --sample-review-config reports/ai_generate_config.json

Implementation · llm_integrations.md · mcp_extension_architecture.md · copilot_mcp_integration.md · openai_mcp_actions.md · 20_llm_mcp_integrations.tex · ai_first.md · tools_index.md

run_real_multitask_finetune_demo — Run staged real-image multitask finetune demo across bbox/segmentation/keypoints/depth/pose6d with strict task-data checks.

experimental tools/run_real_multitask_finetune_demo.py

Inputs

--dataset-root — default=data/real_multitask_fewshot, dir
--prepare — string
--download-if-missing — string
--download-num-images — number
--prepare-args — string
--out — default=reports/real_multitask_finetune_demo, dir
--device — default=cpu, string
--epochs — default=1, number
--max-steps — default=2, number
--batch-size — default=2, number
--image-size — default=128, number
--num-keypoints — default=4, number
--python — string
--backbone-name — default=cspdarknet_s, string
--backbone-norm — default=bn, string
--backbone-args — default={"width_mult": 0.5, "depth_mult": 0.34}, json
--skip-imbalance — string
--force — string
--allow-auto-download — string
--accept-dataset-license — string
--strict-provenance — string
--strict-realism — string

Examples

python3 tools/run_real_multitask_finetune_demo.py --dataset-root data/real_multitask_fewshot --out reports/real_multitask_finetune_demo --device cpu --epochs 1 --max-steps 1 --batch-size 2 --image-size 96 --strict-provenance --force

Implementation · training_inference_export.md · 16_depth_6dof_symmetry.tex

run_reference_adapter_regression — Run RT-DETR reference-adapter regression with hardened record I/O+preprocess interface contract checks, profile-aware micro/full flows, backend-aware behavior gates, optional parity checks, provenance/SBOM capture, and automatic diff-summary/top-k failure artifacts.

experimental tools/run_reference_adapter_regression.py

Inputs

--dataset — default=data/smoke, dir
--split — default=val, string
--max-images — default=2, number
--baseline — default=baselines/reference_adapter/rtdetr_pose_smoke_val.json, file
--output — default=reports/reference_adapter_regression.json, file
--diff-summary-out — file
--topk-examples-dir — dir
--topk-examples — default=3, number
--write-baseline — string
--runtime-lock — default=requirements-locks/requirements-ci.lock, file
--enforce-runtime-lock — string
--enforce-weights-hash — string
--config — default=rtdetr_pose/configs/base.json, file
--checkpoint — file
--device — default=cpu, string
--image-size — default=160, string
--score-threshold — default=0.05, number
--max-detections — default=20, number
--init-seed — default=2026, number
--metric-total-detections-abs — default=0.0, number
--metric-score-sum-abs — default=0.01, number
--metric-score-mean-abs — default=0.001, number
--metric-bbox-checksum-abs — default=0.1, number
--min-fps-ratio — default=0.25, number
--absolute-floor-fps — default=0.2, number
--repro-policy — default=relaxed, string
--schema-gate-mode — default=hard, string
--consistency-gate-mode — default=hard, string
--score-gate-mode — default=warn, string
--perf-gate-mode — default=warn, string
--canonical-decimals — default=6, number
--profile — default=micro, string
--baseline-layout — default=flat, string
--baseline-root — default=baselines/reference_adapter, dir
--adapter-id — default=rtdetr_pose, string
--backend-id — default=torch, string
--matrix-device — string
--baseline-version — default=v1, string
--expected-dataset-hash — string
--expected-weights-hash — string
--expected-checkpoint-hash — string
--capture-provenance — default=full, string
--metric-map50-abs — default=0.03, number
--metric-map50-95-abs — default=0.03, number
--metric-worst-k-map50-abs — default=0.05, number
--metric-median-class-map50-abs — default=0.05, number
--metric-recall-at-k-abs — default=0.05, number
--metric-iou-p10-abs — default=0.1, number
--metric-iou-p50-abs — default=0.1, number
--metric-missing-count-abs — default=2.0, number
--metric-extra-count-abs — default=2.0, number
--metric-class-mismatch-abs — default=2.0, number
--metric-worst-k — default=3, number
--metric-recall-k — default=20, number
--peer-report — file
--backend-parity-mode — default=off, string
--backend-parity-map50-abs — default=0.03, number
--backend-parity-map50-95-abs — default=0.03, number

Examples

python3 tools/run_reference_adapter_regression.py --dataset data/smoke --split val --max-images 2 --profile micro --device cpu --image-size 160 --score-threshold 0.05 --max-detections 20 --init-seed 2026 --repro-policy relaxed --capture-provenance minimal --runtime-lock requirements-locks/requirements-ci.lock --baseline baselines/reference_adapter/rtdetr_pose_smoke_val.json --diff-summary-out reports/reference_adapter_regression.diff_summary.json --topk-examples-dir reports/reference_adapter_regression_topk --topk-examples 3 --output reports/reference_adapter_regression.json
python3 tools/run_reference_adapter_regression.py --dataset data/smoke --split val --max-images 2 --profile micro --score-gate-mode off --perf-gate-mode off --runtime-lock requirements-locks/requirements-ci.lock --enforce-runtime-lock --enforce-weights-hash --baseline baselines/reference_adapter/rtdetr_pose_smoke_val.json --output reports/reference_adapter_regression_contract.json
python3 tools/run_reference_adapter_regression.py --dataset data/smoke --split val --max-images 2 --profile micro --schema-gate-mode off --consistency-gate-mode off --score-gate-mode warn --perf-gate-mode warn --runtime-lock requirements-locks/requirements-ci.lock --enforce-runtime-lock --baseline baselines/reference_adapter/rtdetr_pose_smoke_val.json --output reports/reference_adapter_regression_behavior.json
python3 tools/run_reference_adapter_regression.py --dataset data/smoke --split val --max-images 2 --profile full --baseline-layout matrix --baseline-root baselines/reference_adapter --adapter-id rtdetr_pose --backend-id torch --device cpu --baseline-version v1 --repro-policy strict --capture-provenance full --runtime-lock requirements-locks/requirements-ci.lock --output reports/reference_adapter_regression_full.json
python3 tools/run_reference_adapter_regression.py --dataset data/smoke --split val --max-images 2 --profile micro --repro-policy relaxed --capture-provenance full --runtime-lock requirements-locks/requirements-ci.lock --baseline baselines/reference_adapter/rtdetr_pose_smoke_val.json --write-baseline --output reports/reference_adapter_regression_baseline_write.json

Implementation · adapter_contract.md · adapter_strategy.md · predictions_interface_contract_policy.md · real_model_interface.md · reference_adapter_regression_policy.md · schema_governance.md

run_rtdetr_pose_backend_suite — End-to-end runner for rtdetr_pose: export (PyTorch→ONNX→TRT) + backend parity/benchmark suite.

experimental tools/run_rtdetr_pose_backend_suite.py

Inputs

--config — default=rtdetr_pose/configs/base.json, file
--checkpoint — file
--device — string
--export-device — string
--precision — string
--input-name — string
--opset — number
--dynamic-hw — string
--no-dynamic-hw — string
--export-image-size — number
--suite-image-size — number
--max-image-size — number
--min-shape — string
--opt-shape — string
--max-shape — string
--workspace — number
--trtexec — string
--extra-args — string
--batch — number
--samples — number
--seed — number
--score-atol — number
--bbox-atol — number
--warmup — number
--iterations — number
--backends — string
--embed-meta — string
--run-id — string
--run-dir — dir
--onnx — default=None, file
--engine — default=None, file
--timing-cache — default=None, file
--output — default=None, file
--skip-onnx — string
--skip-engine — string
--force — string
--dry-run — string

Examples

python3 tools/run_rtdetr_pose_backend_suite.py --config rtdetr_pose/configs/base.json --checkpoint /path/to/checkpoint.pt --device cuda --precision fp16 --dynamic-hw --export-image-size 320 --suite-image-size 640

Implementation · tensorrt_pipeline.md

run_scenarios — Run the scenario suite pipeline (adapter + constraints utilities) and write a report JSON.

stable tools/run_scenarios.py

Inputs

--config — file
--adapter — string
--dataset — dir
--split — string
--predictions — file
--checkpoint — file
--device — string
--image-size — string
--max-images — number
--max-detections — number
--score-threshold — number
--output — default=reports/scenario_run.json, file

Examples

python3 tools/run_scenarios.py --adapter dummy --dataset data/coco128 --max-images 50

Implementation · No dedicated prose page.

run_trt_pipeline — Orchestrate the YOLO26 TensorRT pipeline (engine build → predictions export → parity → eval_suite → latency report).

experimental tools/run_trt_pipeline.py

Inputs

--dataset — required, dir
--onnx-template — required, string
--run-dir — default=None, dir
--benchmark-config — file
--benchmark-history — file
--benchmark-output — file
--boxes-scale — string
--buckets — string
--calib-cache-template — string
--calib-dataset — dir
--calib-images — number
--calib-list-template — string
--calib-split — string
--combined-output — string
--dry-run — string
--engine-meta-template — string
--engine-template — string
--eval-suite-output — file
--force — string
--help — string
--image-size — string
--input-name — string
--latency-iterations — number
--latency-template — string
--latency-warmup — number
--max-images — number
--max-shape — string
--min-score — number
--min-shape — string
--notes — string
--opt-shape — string
--parity-bbox-atol — number
--parity-iou — number
--parity-report-template — string
--parity-score-atol — number
--precision — string
--pred-onnxrt-template — string
--pred-trt-template — string
--run-id — string
--shape — string
--skip-benchmark — string
--skip-build — string
--skip-eval — string
--skip-latency — string
--skip-onnxrt — string
--skip-parity — string
--skip-trt — string
--timing-cache — file
--topk — number
--trtexec — string
--workspace-mib — number

Examples

python3 tools/run_trt_pipeline.py --dataset /data/coco-yolo --onnx-template /data/models/{bucket}.onnx --precision fp16 --combined-output output0 --boxes-scale abs --min-score 0.0 --topk 300 --max-images 500

Implementation · README.md · tensorrt_pipeline.md

run_ttt_compare — Run a fail-closed baseline-vs-adapted TTT local diagnostic with full checkpoint preflight, atomic stage status, and non-COCO proxy naming.

research tools/run_ttt_compare.py

Inputs

--boilerplate — string
--method — string
--dataset — required, dir
--data — dir
--split — default=val, string
--checkpoint — file
--weights — file
--run-dir — default=reports/ttt_compare/<method>, dir
--out — dir
--backend — default=torch, string
--device — default=cpu, string
--max-images — number
--protocol — string
--image-size — string
--skip-eval — string
--no-eval — string
--dry-run — string
--force — string

Examples

python3 tools/run_ttt_compare.py --method tent --data data/smoke --weights checkpoints/rtdetr_pose.pt --out reports/ttt_compare/tent -n 1 --no-eval
python3 tools/run_ttt_compare.py --method mim --data data/smoke --weights checkpoints/rtdetr_pose_mim.pt --out reports/ttt_compare/mim -n 1 --no-eval
python3 tools/run_ttt_compare.py --method cotta --data data/smoke --weights checkpoints/rtdetr_pose.pt --out reports/ttt_compare/cotta -n 1 --dry-run

Implementation · ttt_protocol.md · ttt_compare_boilerplates.md · 15_ttt_tent_mim.tex · production_readiness.md · research_lanes.md · research_lane_report.schema.json

smoke — Run one-command offline smoke flow (doctor -> validate dataset -> validate predictions -> eval-coco dry-run -> synthgen intake smoke) with optional deep walkthrough checks.

stable scripts/smoke.sh

Inputs

--dataset — default=data/smoke, dir
--predictions — default=data/smoke/predictions/predictions_dummy.json, file
--report — default=reports/smoke_coco_eval_dry_run.json, file
--synthgen-root — default=data/smoke/synthgen_minishard, dir
--synthgen-predictions — default=data/smoke/synthgen_minishard/predictions_synthgen_smoke.json, file
--output-dir — default=reports, dir
--demo-run-dir — default=reports/smoke_demo_instance_seg, dir
--skip-demo — string
--torch-device — default=cpu, string
--profile — default=core, string
--walkthrough-report — default=reports/smoke_walkthrough_report.json, file

Examples

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

Implementation · README.md · synthgen_intake.md · README.md

smoke_synthgen — Run deterministic SynthGen smoke (interface-contract validate + one overlay + eval) using local mini-shard fixtures.

experimental tools/smoke_synthgen.py

Inputs

--dataset-root — default=data/smoke/synthgen_minishard, dir
--schema-id — default=animal_v1, string
--predictions — default=data/smoke/synthgen_minishard/predictions_synthgen_smoke.json, file
--max-samples — default=2, number
--output-dir — default=reports, dir

Examples

python3 tools/smoke_synthgen.py --dataset-root data/smoke/synthgen_minishard --output-dir reports

Implementation · synthgen_intake.md · synthgen_repo_integration.md · synthgen_contract.md · README.md · production_readiness.md

support_external_training — External training bridge with a fixed 3-layer interface contract: Apache-2.0-friendly YOLOX-style training as the primary lane, Detectron2/MMDetection/MMPose/MMSeg/TAO external lanes for common vision tasks, plus optional Ultralytics and HF DETR bridges with explicit runtime/license boundaries. Executed runs also write standardized resume/export/eval/parity handoff JSONs and an optional append-only registry entry. OpenCV DNN and ONNX Runtime remain export/inference runtimes rather than training backends.

experimental tools/support_external_training.py

Inputs

--subcommand — required, string
--dataset — dir
--split — string
--batch — number
--exp — file
--train-script — file
--weights — file
--output — file
--work-dir — dir
--dry-run — string
--config — file
--task-family — string
--resume-from — file
--tao-task — string
--train-opt — string
--registry-out — file

Examples

python3 tools/support_external_training.py train-yolox --dataset data/smoke --split val --exp configs/examples/finetune_external/yolox_s_finetune_smoke.py --dry-run --output reports/support_external_training.train_yolox.json
python3 tools/support_external_training.py train-detectron2 --config configs/examples/finetune_external/detectron2_finetune_smoke.yaml --dataset data/smoke --split val --task-family bbox --dry-run --output reports/support_external_training.train_detectron2.json
python3 tools/support_external_training.py train-mmdetection --config configs/examples/finetune_external/mmdetection_finetune_smoke.py --dataset data/smoke --split val --task-family bbox --dry-run --output reports/support_external_training.train_mmdetection.json
python3 tools/support_external_training.py train-mmpose --config configs/examples/finetune_external/mmpose_finetune_smoke.py --dataset data/smoke --split val --dry-run --output reports/support_external_training.train_mmpose.json
python3 tools/support_external_training.py train-mmseg --config configs/examples/finetune_external/mmseg_finetune_smoke.py --dataset data/smoke --split val --dry-run --output reports/support_external_training.train_mmseg.json
python3 tools/support_external_training.py train-tao --config configs/examples/finetune_external/tao_finetune_smoke.yaml --dataset data/smoke --split val --task-family bbox --dry-run --output reports/support_external_training.train_tao.json
python3 tools/support_external_training.py train-ultralytics --dataset data/smoke --split val --preset smoke --dry-run --output reports/support_external_training.train_ultralytics.json
python3 tools/support_external_training.py train-hf-detr -P smoke -n -o reports/support_external_training.train_hf_detr.json

Implementation · README.md · README.md · interop_yolox.md · license_policy.md · training_handoff.schema.json · training_run_summary.schema.json · tools_index.md · training_inference_export.md · 04_cli_reference.tex · 05_workflows_eval_export.tex · 09_parity_bench_protocols.tex · training_backend_interface.md · training_capability_matrix.md · training_orchestration.md · run_contract.md · interop_detectron2_mmdet.md

support_yolo_detr — YOLO/DETR support utility with fixed 3-layer integration interface contract (trainer/repo/export), short-option + alias UX, preset defaults, shared dataset conversion, ONNX export template, and prediction normalization.

experimental tools/support_yolo_detr.py

Inputs

--preset — string
--from — string
--dataset — dir
--split — string
--batch — number
--instances-json — file
--images-dir — dir
--model — string
--model-id — string
--provider — string
--input — file
--output — file
--report — file
--train-script — file
--trt-engine — file
--work-dir — dir
--dry-run — string
--strict — string

Examples

python3 tools/support_yolo_detr.py ls -j
python3 tools/support_yolo_detr.py tu -P smoke -n -o reports/support_yolo_detr.train_yolo_runtime.json
python3 tools/support_yolo_detr.py th -P smoke -n -o reports/support_yolo_detr.train_hf_detr.json
python3 tools/support_yolo_detr.py eo -P smoke -o models/yolo11n.onnx -n -r reports/support_yolo_detr.export_onnx.json
python3 tools/support_yolo_detr.py pn -i reports/raw_predictions.json -o reports/predictions.normalized.json -r reports/support_yolo_detr.predict_normalize.json

Implementation · README.md · Readme_jp.md · Readme_zh.md · tools_index.md · yolo_detr_support.md · 04_cli_reference.tex

ttt_compare — Short shell entrypoint for the fail-closed TTT local diagnostic; requires a fully compatible checkpoint and never promotes efficacy.

research scripts/ttt_compare.sh

Inputs

--boilerplate — required, string
--dataset — required, dir
--split — default=val, string
--checkpoint — required, file
--run-dir — default=reports/ttt_compare/<method>, dir
--backend — default=torch, string
--device — default=cpu, string
--max-images — number
--protocol — string
--image-size — string
--skip-eval — string
--dry-run — string
--force — string

Examples

bash scripts/ttt_compare.sh --method tent --data data/smoke --weights checkpoints/rtdetr_pose.pt --out reports/ttt_compare/tent -n 1 --no-eval
bash scripts/ttt_compare.sh --method mim --data data/smoke --weights checkpoints/rtdetr_pose_mim.pt --out reports/ttt_compare/mim -n 1 --no-eval
bash scripts/ttt_compare.sh --method cotta --data data/smoke --weights checkpoints/rtdetr_pose.pt --out reports/ttt_compare/cotta -n 1 --dry-run

Implementation · ttt_protocol.md · ttt_compare_boilerplates.md · 15_ttt_tent_mim.tex

tune_gate_weights — Offline grid-search for inference-time score-fusion weights (CPU-only, simple mAP proxy).

research tools/tune_gate_weights.py

Inputs

--config — file
--dataset — required, dir
--split — string
--max-images — number
--predictions — required, file
--output-report — default=reports/gate_tuning_report.json, file
--output-predictions — default=None, file
--metric — string
--det-score-key — string
--template-score-key — string
--sigma-z-key — string
--sigma-rot-key — string
--preserve-det-score-key — string
--grid-det — string
--grid-tmp — string
--grid-unc — string
--grid-tau — string
--template-gate — string
--no-template-gate — string
--tau — number
--min-score — number
--topk-per-image — number
--wrap-output — string
--no-wrap-output — string

Examples

python3 tools/tune_gate_weights.py --dataset data/coco128 --predictions reports/predictions.json --metric map50_95 --grid-det 1.0 --grid-tmp 0.0,0.5,1.0 --grid-unc 0.0,0.5,1.0 --output-report reports/gate_tuning_report.json

Implementation · gate_weight_tuning.md

validate_instance_segmentation_predictions — Validate YOLOZU instance segmentation predictions JSON (per-image instances; PNG masks).

stable tools/validate_instance_segmentation_predictions.py

Inputs

predictions — required, file

Examples

python3 tools/validate_instance_segmentation_predictions.py reports/instance_seg_predictions.json

Implementation · No dedicated prose page.

validate_map_targets — Validate the mAP target table file (baselines/yolo26_targets.json).

stable tools/validate_map_targets.py

Inputs

--targets — default=baselines/yolo26_targets.json, file

Examples

python3 tools/validate_map_targets.py --targets baselines/yolo26_targets.json

Implementation · No dedicated prose page.

validate_predictions — Validate YOLOZU predictions JSON (permissive by default; strict optional) with compatible human output or an explicit bounded JSON result.

stable tools/validate_predictions.py

Inputs

predictions — required, file
--strict — string
--json — string

Examples

python3 tools/validate_predictions.py reports/predictions.json --strict
python3 tools/validate_predictions.py reports/predictions.json --strict --json

Implementation · byop_quickstarts.md · ai_first.md · predictions_schema.md · production_readiness.md

validate_run_meta — Validate the run_meta.json interface contract (git SHA, dependency lock, preprocess, hardware/runtime, command).

stable tools/validate_run_meta.py

Inputs

run_meta — required, file
--allow-missing-git-sha — string

Examples

python3 tools/validate_run_meta.py runs/ci_smoke/reports/run_meta.json

Implementation · run_contract.md

validate_segmentation_predictions — Validate YOLOZU segmentation predictions JSON (id→mask path mapping; meta optional).

stable tools/validate_segmentation_predictions.py

Inputs

predictions — required, file

Examples

python3 tools/validate_segmentation_predictions.py reports/seg_predictions.json

Implementation · No dedicated prose page.

validate_synthgen_contract — Validate SynthGen sample/shard interface-contract fields, dtypes, shapes, and ranges before training/eval.

experimental tools/validate_synthgen_contract.py

Inputs

--input — required, file
--max-samples — default=100, number

Examples

python3 tools/validate_synthgen_contract.py --input /path/to/synthgen_dataset/shards/train_000.jsonl --max-samples 200

Implementation · synthgen_intake.md · synthgen_repo_integration.md · synthgen_contract.md · production_readiness.md

validate_tool_manifest — Validate tools/manifest.json structure, references, and declarative metadata.

stable tools/validate_tool_manifest.py

Inputs

--manifest — default=tools/manifest.json, file
--require-declarative — string

Examples

python3 tools/validate_tool_manifest.py --manifest tools/manifest.json --require-declarative
python3 tools/validate_tool_manifest.py --help

Implementation · manifest_authoring_workflow.md · manifest_coverage_audit.md · README.md

yolo26_pre_pr_quality — Run pre-PR quality checklist for YOLO26 flow (smoke + lint + focused tests).

stable scripts/pre_pr_quality.sh

Inputs

No declared CLI inputs.

Examples

bash scripts/pre_pr_quality.sh

Implementation · yolo26_eval_protocol.md · training_inference_export.md

yolo26_quality_gate — Run YOLO26-focused quality gate (lint + focused tests) before eval/target checks.

stable tools/yolo26_quality_gate.sh

Inputs

No declared CLI inputs.

Examples

ruff check tools yolozu tests && pytest -q tests/test_eval_suite_export_settings.py tests/test_eval_suite_determinism.py tests/test_check_map_targets_contract.py tests/test_yolo26_protocol.py tests/test_predictions.py

Implementation · yolo26_eval_protocol.md

yolozu — Top-level YOLOZU dispatcher for validation, migration, dataset, training, and predictions/eval workflows, including a packaged torch/TTT exporter usable outside a source checkout; Stable applies to the parent/core lane and does not promote Experimental or Research subcommands and flags.

stable yolozu/cli.py

Inputs

--allow-compile-fallback — string
--allow-gpu — string
--allow-network — string
--allow-rgb-masks — string
--allow-undeclared-effects — string
--allow-unknown-flags — string
--allow-unsafe-paths — string
--allow-write-root — string
--alpha — number
--backend — string
--batch — number
--boxes-scale — string
--cache — string
--cache-dir — default=runs/yolozu_runs, dir
--calibration-bins — number
--calibration-iou — number
--checkpoint — file
--class-balanced-beta — number
--classes — file
--combined-output — string
--config — file
--contract — string
--dataset — dir
--dataset-root — dir
--dataset-from — string
--device — string
--devices — number
--diag-iou — number
--dry-run — string
--extra-records-json — file
--external-backend — string
--explain — string
--resume-from — file
--tao-task — string
--fit-iou — number
--fit-max-detections — number
--fit-temperature — number
--focal-gamma — number
--force — string
--force-import-overwrite — string
--from — string
--gamma — number
--glob — string
--goal — string
--head-fraction — number
--help — string
--html — default=reports/predict_images.html, file
--image-size — number
--images-dir — dir
--infer-batch-size — default=1, number
--input-dir — dir
--input-name — string
--instances-json — file
--iou-threshold — number
--json — string
--keep-per-image — string
--kp-line — number
--kp-radius — number
--ldam-margin — number
--logit-adjustment-tau — number
--lora-alpha — number
--lora-dropout — number
--lora-freeze-base — string
--lora-r — number
--lora-target — string
--lora-train-bias — string
--lort-tau — number
--loss-plugin — string
--lr-scheduler — string
--max-detections — number
--max-images — number
--max-overlays — number
--max-runs — number
--max-score — number
--medium-fraction — number
--method — string
--metric — string
--metric-key — string
--metric-plugin — string
--min-score — number
--model — string
--no-lora-freeze-base — string
--no-torch-channels-last — string
--no-torch-compile-fullgraph — string
--no-torch-inference-mode — string
--no-ttt-rollback-on-stop — string
--no-ttt-sar-adaptive — string
--no-ttt-stop-on-non-finite — string
--notes — string
--oks — string
--oks-max-dets — number
--oks-sigmas — string
--oks-sigmas-file — file
--output — default=reports/predictions.json, file
--output-report — file
--proof — string
--proof-dir — default=reports/doctor_proof, dir
--overlay-alpha — number
--overlay-max-size — number
--overlay-sort — string
--overlays-dir — default=reports/overlays, dir
--openvino-model — file
--parity-reference-backend — default=auto, string
--classification-parity-score-atol — default=0.0001, number
--obb-parity-iou-thresh — default=0.99, number
--obb-parity-score-atol — default=0.0001, number
--pck-threshold — number
--per-image-limit — number
--pred-root — dir
--predictions — file
--progress — string
--python — string
--rebalance-sampler — string
--records-json — file
--replay-fraction — number
--replay-per-task-cap — number
--replay-size — number
--resolved-config-out — file
--resume — string
--run-dir — default=None, dir
--runtime-output-json — file
--run-json — file
--score-threshold — number
--seed — number
--split — string
--stage1-epochs — number
--stage2-epochs — number
--stats-in — file
--stats-out — file
--strength — number
--success-rot-deg — number
--success-trans — number
--tag — string
--task — string
--tau — number
--temperature — number
--temperature-grid — string
--torch-amp — default=off, string
--torch-channels-last — string
--torch-compile — string
--torch-compile-backend — default=inductor, string
--torch-compile-fullgraph — string
--torch-compile-dynamic — default=auto, string
--torch-compile-mode — default=reduce-overhead, string
--torch-inference-mode — string
--title — string
--topk — number
--train-script — file
--tta — string
--val-records-json — file
--tta-flip-prob — number
--tta-keypoint-swap-pairs — string
--tta-log-out — default=None, file
--tta-mode — string
--tta-model-merge-iou — number
--tta-norm-only — string
--tta-seed — number
--ttt — string
--ttt-aux-depth-weight — number
--ttt-aux-keypoints-weight — number
--ttt-aux-pose-weight — number
--ttt-aux-seg-weight — number
--ttt-aux-temperature — number
--ttt-batch-size — number
--ttt-cotta-aggregation — string
--ttt-cotta-augmentations — string
--ttt-cotta-ema-momentum — number
--ttt-cotta-restore-interval — number
--ttt-cotta-restore-prob — number
--ttt-eata-anchor-lambda — number
--ttt-eata-conf-min — number
--ttt-eata-entropy-max — number
--ttt-eata-entropy-min — number
--ttt-eata-max-skip-streak — number
--ttt-eata-min-valid-dets — number
--ttt-eata-selected-ratio-min — number
--ttt-exclude — string
--ttt-include — string
--ttt-lite-entropy-weight — number
--ttt-lite-minmax — string
--ttt-lite-non-torch — string
--ttt-lite-temperature — number
--ttt-log-out — default=None, file
--ttt-lr — number
--ttt-mask-prob — number
--ttt-mask-value — number
--ttt-max-batches — number
--ttt-max-grad-norm — number
--ttt-max-loss-increase — number
--ttt-max-loss-ratio — number
--ttt-max-total-update-norm — number
--ttt-max-update-norm — number
--ttt-method — string
--ttt-patch-size — number
--ttt-preset — string
--ttt-reset — string
--ttt-rollback-on-stop — string
--ttt-sar-adaptive — string
--ttt-sar-first-step-scale — number
--ttt-sar-rho — number
--ttt-sdft-task — string
--ttt-seed — number
--ttt-steps — number
--ttt-stop-on-non-finite — string
--ttt-update-filter — string
--weights — file
--preset — string
--spec — file
--registry-out — file
--execute — string
--stop-on-failure — string
--task-family — string
--train-opt — string
--out-dir — dir
--image-mode — string

Examples

python3 -m yolozu doctor --output reports/doctor.json
python3 -m yolozu doctor --explain
python3 -m yolozu doctor --proof
python3 -m yolozu guide --goal evaluate
python3 -m yolozu guide --goal first-run
python3 -m yolozu completion -s bash
python3 -m yolozu demo overview --output reports/demo_overview_report.json
python3 -m yolozu demo instance-seg --run-dir reports/quickstart_instance_seg --progress
python3 -m yolozu demo ttt --run-dir reports/demo_ttt_improvement --force
python3 -m yolozu demo instance-seg-tta --run-dir reports/demo_instance_seg_tta
python3 -m yolozu demo keypoints
python3 -m yolozu demo pose
python3 -m yolozu demo pose --backend aruco
python3 -m yolozu demo pose --backend densefusion
python3 -m yolozu demo depth
python3 -m yolozu demo depth --compare
python3 -m yolozu demo train --max-steps 40
python3 -m yolozu doctor import --config-from auto --args /path/to/args.yaml --output -
python3 -m yolozu export --backend dummy --dataset data/coco128 --max-images 5 --output reports/predictions_dummy_run.json
python3 -m yolozu predict-images --backend dummy --input-dir data/coco128/images/val2017 --max-images 5 --output reports/predict_images_dummy.json --overlays-dir reports/overlays_dummy --html reports/predict_images_dummy.html --progress
python3 -m yolozu eval-instance-seg --dataset examples/instance_seg_demo/dataset --split val2017 --predictions examples/instance_seg_demo/predictions/instance_seg_predictions.json --pred-root examples/instance_seg_demo/predictions --classes examples/instance_seg_demo/classes.txt --html reports/instance_seg_demo_eval.html --overlays-dir reports/instance_seg_demo_overlays --max-overlays 10
python3 -m yolozu benchmark --model runs/example/model.pt --openvino-model exports/example.xml --data data/coco8.yaml --format torch,openvino --parity-reference-backend openvino --dry-run --output reports/benchmark_openvino_report.json
python3 tools/hpo_sweep.py --config docs/hpo_sweep_example.json --dry-run
python3 -m yolozu calibrate --method fracal --dataset data/coco128 --predictions reports/predictions.json --output reports/predictions_calibrated.json && python3 -m yolozu eval-long-tail --dataset data/coco128 --predictions reports/predictions_calibrated.json --output reports/long_tail_eval.json
python3 -m yolozu train --import auto --cfg /path/to/args_or_config.{yaml,py} --resolved-config-out reports/train_config_resolved_import.json
python3 -m yolozu doctor train-dataset --dataset data/smoke --split val --output -
python3 -m yolozu doctor train-dataset --from obb --dataset /path/to/yolo_obb_root --split train --output -
python3 -m yolozu doctor train-dataset --from pose6d --dataset /path/to/yolozu_pose_wrapper --split train --output -
python3 -m yolozu registry validate
python3 -m yolozu eval-coco --help
python3 -m yolozu train --external-backend yolox configs/examples/finetune_external/yolox_s_finetune_smoke.py --dataset data/smoke --split val --dry-run --output reports/train_external_yolox.json
python3 -m yolozu train --external-backend detectron2 configs/examples/finetune_external/detectron2_finetune_smoke.yaml --dataset data/smoke --split val --task-family bbox --dry-run --output reports/train_external_detectron2_bbox.json
python3 -m yolozu train --external-backend mmdetection configs/examples/finetune_external/mmdetection_finetune_smoke.py --dataset data/smoke --split val --task-family bbox --dry-run --output reports/train_external_mmdetection_bbox.json
python3 -m yolozu train --external-backend mmpose configs/examples/finetune_external/mmpose_finetune_smoke.py --dataset data/smoke --split val --dry-run --output reports/train_external_mmpose.json
python3 -m yolozu train --external-backend mmseg configs/examples/finetune_external/mmseg_finetune_smoke.py --dataset data/smoke --split val --dry-run --output reports/train_external_mmseg.json
python3 -m yolozu train --external-backend tao configs/examples/finetune_external/tao_finetune_smoke.yaml --dataset data/smoke --split val --task-family bbox --dry-run --output reports/train_external_tao_bbox.json
python3 tools/support_external_training.py ls -j
python3 -m yolozu train --external-backend ultralytics yolo11n.pt --dataset data/smoke --split val --dry-run --output reports/train_external_ultralytics.json
python3 -m yolozu train --external-backend hf-detr facebook/detr-resnet-50 --dataset data/smoke --split val --dry-run --output reports/train_external_hf_detr.json
python3 -m yolozu train-orchestrate --spec reports/train_orchestration_spec.json --output reports/training_orchestration_report.json
python3 -m yolozu export-dataset yolo --dataset reports/conversion_tiny_wrapper --split val2017 --out-dir reports/conversion_tiny_yolo --force
python3 -m yolozu export-dataset kitti --dataset reports/conversion_tiny_wrapper --split val2017 --out-dir reports/conversion_tiny_kitti --force
python3 -m yolozu doctor import --dataset-from auto --dataset data/conversion_tiny_coco --split val2017 --output -
python3 -m yolozu migrate dataset --from auto --dataset data/conversion_tiny_coco --split val2017 --output reports/conversion_tiny_wrapper --force
python3 -m yolozu export-dataset coco --dataset reports/conversion_tiny_wrapper --split val2017 --out-dir reports/conversion_tiny_coco --force
python3 -m yolozu doctor import --dataset-from auto --dataset /path/to/VOCdevkit/VOC2012 --split val --output -
python3 -m yolozu import dataset --from auto --dataset /path/to/coco_keypoints_root --split val2017 --output reports/coco_keypoints_wrapper --force
python3 -m yolozu import dataset --from coco-keypoints --dataset /path/to/coco_keypoints_root --split val2017 --output reports/coco_keypoints_wrapper --force
python3 -m yolozu export-dataset segmentation --dataset reports/voc_seg_wrapper --out-dir reports/voc_seg_export --image-mode symlink --force
python3 -m yolozu export --backend executorch --dataset data/smoke --split val --model exports/model.pte --runtime-output-json reports/executorch_runtime_outputs.json --boxes-scale norm --output reports/pred_executorch.json --force
python3 -m yolozu export --backend torch --dataset data/coco128 --torch-compile --torch-compile-backend inductor --torch-compile-mode reduce-overhead --torch-compile-dynamic auto --output reports/predictions_compiled.json --force

Implementation · tools_index.md · import_adapters.md · doctor_diagnostics.md · interop_yolox.md · byop_quickstarts.md · training_inference_export.md · 04_cli_reference.tex · 05_workflows_eval_export.tex · training_backend_interface.md · training_capability_matrix.md · training_orchestration.md · run_contract.md · 07_training_run_contract.tex · interop_detectron2_mmdet.md · migrate.md · benchmark_mode.md · benchmark_support_matrix.md · benchmark_mode_spec_parity_target.md · benchmark_mode_gap_audit.md · benchmark_backend_runtime_matrix.md · 09_parity_bench_protocols.tex

Open the source manifest.