{ "ai_surfaces": { "actions_public": { "availability": "requires optional actions dependencies", "tool_ids": [ "doctor", "validate_predictions", "validate_dataset", "eval_coco", "predict_images", "parity_check", "calibrate_predictions", "eval_instance_seg", "eval_long_tail", "run_scenarios", "convert_dataset", "train_job", "export_predictions_job", "test_job", "ttt_job", "ctta_job", "jobs_list", "jobs_status", "jobs_cancel", "runs_list", "runs_describe" ] }, "config_review": { "availability": "in-process config generation and review", "tool_ids": [ "generate_config", "review_config" ] }, "guaranteed_ai_safe": { "availability": "deterministic lightweight guarantee", "tool_ids": [ "doctor", "generate_config", "review_config", "validate_predictions" ] }, "image_service_safe": { "availability": "bounded single-tenant MCP image service", "tool_ids": [ "image_service_capabilities", "put_image_asset", "submit_image_job", "get_image_job", "cancel_image_job" ] }, "mcp_live": { "availability": "requires optional mcp dependency", "tool_ids": [ "ai_tools", "generate_config", "review_config", "doctor", "validate_predictions", "validate_dataset", "eval_coco", "predict_images", "recommend_image_pipeline", "process_images", "image_service_capabilities", "put_image_asset", "submit_image_job", "get_image_job", "cancel_image_job", "parity_check", "calibrate_predictions", "eval_instance_seg", "eval_long_tail", "run_scenarios", "convert_dataset", "train_job", "export_predictions_job", "export_onnx_job", "test_job", "ttt_job", "ctta_job", "jobs_list", "jobs_status", "jobs_cancel", "runs_list", "runs_describe" ] } }, "contracts": { "adaptive_vision_roadmap_json": { "schema": "docs/schemas/adaptive_vision_roadmap.schema.json", "summary": "Dated packaged projection of the future Experimental adaptive local-vision scope; Beads remains authoritative for live task state." }, "algorithm_bundle_registry_json": { "schema": "docs/schemas/algorithm_bundle_registry.schema.json", "summary": "Bounded immutable bundle set loaded from the packaged SSOT or as operator-asserted custom catalog input; packaged Candidate metadata is non-selectable without all later gates." }, "algorithm_bundle_spec_json": { "schema": "docs/schemas/algorithm_bundle_spec.schema.json", "summary": "Immutable pipeline, artifact, runtime, vocabulary, and execution facts; presence is not qualification or availability evidence." }, "algorithm_scout_report_json": { "producer": "python3 tools/scout_algorithms.py --sources docs/algorithm_intake/sources.json --output-dir reports/algorithm_scout --collection-date --trigger --collect", "schema": "docs/schemas/algorithm_scout_report.schema.json", "summary": "Dated Experimental monitored-source inbox metadata; this interface contract is not loadable as a bundle registry and is not qualification, support, recommendation, adoption, or promotion evidence." }, "algorithm_scout_sources_json": { "schema": "docs/schemas/algorithm_scout_sources.schema.json", "summary": "Canonical credential-free HTTPS scheme/host/path allowlist for the bounded algorithm scout." }, "artifact_research_qualification_json": { "producer": "python3 tools/qualify_artifact_research.py", "schema": "docs/schemas/artifact_research_qualification.schema.json", "summary": "Measured three-repeat qualification summary for offline distillation and Hessian research lanes." }, "bop_conversion_report_json": { "producer": "python3 tools/prepare_bop_yolozu.py", "schema": "docs/schemas/bop_conversion_report.schema.json", "summary": "BOP-to-YOLOZU conversion provenance, deterministic partition, CAD model hashes, units, and dataset license." }, "bop_download_manifest_json": { "producer": "python3 tools/download_bop_dataset.py", "schema": "docs/schemas/bop_download_manifest.schema.json", "summary": "BOP archive URLs, byte sizes, SHA-256 values, cache paths, and upstream dataset license." }, "bop_tless_qualification_json": { "producer": "python3 tools/summarize_bop_tless_qualification.py", "schema": "docs/schemas/bop_tless_qualification.schema.json", "summary": "Strict-GT BOP T-LESS baseline/trained task-native metrics, evidence hashes, hold decision, and independent semantic reproduction result." }, "bundle_lifecycle_record_json": { "schema": "docs/schemas/bundle_lifecycle_record.schema.json", "summary": "Append-only bundle state and channel-pointer record loaded with explicit managed or operator-asserted source trust for future Experimental routing." }, "candidate_isolation_probe_json": { "producer": "python3 tools/probe_candidate_isolation.py", "schema": "docs/schemas/candidate_isolation_probe.schema.json", "summary": "Bounded fail-closed host observation for the code-owned none-supported candidate-isolation decision; executable presence is not containment evidence." }, "candidate_screening_record_json": { "schema": "docs/schemas/candidate_screening_record.schema.json", "summary": "Append-only non-executing candidate screening facts and deterministic pass, hold, or reject outcome; only a current repository-managed pass can satisfy the screening gate." }, "coco_eval_report_json": { "producer": "python3 tools/eval_coco.py", "schema": "docs/schemas/coco_eval_report.schema.json", "summary": "Strict success/failure report emitted by yolozu eval-coco or tools/eval_coco.py (COCOeval or dry-run conversion)." }, "continual_promotion_decision_json": { "producer": "python3 tools/continual_decide.py", "schema": "docs/schemas/continual_promotion_decision.schema.json", "summary": "Promotion decision report derived from continual_eval.json plus optional curation soft gates." }, "environment_profile_json": { "producer": "python3 -m yolozu doctor --output - (environment_profile key)", "schema": "docs/schemas/environment_profile.schema.json", "summary": "Privacy-safe live measured configuration facts for future Experimental adaptive routing; failed probes stay unknown and presence is not qualification evidence." }, "eval_suite_report_json": { "producer": "python3 tools/eval_suite.py", "schema": "docs/schemas/eval_suite_report.schema.json", "summary": "Report payload emitted by tools/eval_suite.py (suite over prediction JSONs)." }, "evidence_activation_record_json": { "producer": "python3 tools/activate_qualification_evidence.py ", "schema": "docs/schemas/evidence_activation_record.schema.json", "summary": "Append-only reviewed activation state for one exact qualification evidence selection key." }, "external_runtime_qualification_json": { "schema": "docs/schemas/external_runtime_qualification.schema.json", "summary": "Cross-environment real-training, artifact, resource, failure-normalization, license-boundary, and independent reproduction record for optional external runtimes." }, "finetune_lane_qualification_json": { "producer": "python3 tools/qualify_finetune_lanes.py --output-dir ", "schema": "docs/schemas/finetune_lane_qualification.schema.json", "summary": "Execution, provenance, dependency, checkpoint-handoff, metric-scope, and hold decision for real-image and external fine-tuning lanes." }, "frame_result_json": { "schema": "docs/schemas/frame_result.schema.json", "summary": "Canonical bounded result for one processed stream frame, with source-frame, timing, task-result, and own-digest fields; dropped frames emit no row." }, "image_job_spec_json": { "schema": "docs/schemas/image_job_spec.schema.json", "summary": "Bounded typed image request for future Experimental adaptive routing; paths remain separate tool arguments." }, "instance_seg_eval_report_json": { "producer": "python3 tools/eval_instance_segmentation.py", "schema": "docs/schemas/instance_seg_eval_report.schema.json", "summary": "Instance segmentation eval report payload emitted by tools/eval_instance_segmentation.py." }, "instance_segmentation_predictions_json": { "schema": "docs/schemas/instance_segmentation_predictions.schema.json", "summary": "Instance segmentation predictions JSON (list of {image,instances} or {predictions:[...],meta:{...}}).", "validator": "python3 tools/validate_instance_segmentation_predictions.py " }, "lifecycle_rollback_bindings_json": { "schema": "docs/schemas/lifecycle_rollback_bindings.schema.json", "summary": "Canonical complete ordered repository-managed activation set for one explicit rollback to a previously assigned same-family target; caller-authored subsets and untrusted bindings fail closed." }, "local_artifact_inventory_json": { "schema": "docs/schemas/local_artifact_inventory.schema.json", "summary": "Trusted-preflight observations for every ordered immutable bundle artifact; paths are excluded from the persisted record." }, "managed_output_checksums_json": { "builder": "yolozu.adaptive.ManagedOutputTransaction", "summary": "Code-owned canonical manifest for every other declared managed output file; generated and revalidated before bounded publication, force cleanup, or recovery." }, "metrics_report_json": { "builder": "yolozu/eval/metrics_report.py", "schema": "docs/schemas/metrics_report.schema.json", "summary": "Stable metrics report schema emitted by yolozu.metrics_report.build_report()." }, "ocr_bundle_interface_json": { "schema": "docs/schemas/ocr_bundle_interface.schema.json", "summary": "Immutable OCR language, script, and detector/recognizer component declaration used by core; it contains no model availability or support claim." }, "ocr_result_json": { "schema": "docs/schemas/ocr_result.schema.json", "summary": "Bounded successful OCR output with inert untrusted recognized text, exact quadrilateral geometry, separate confidences, mapped language/script status, pinned provenance, and content-free summaries." }, "predictions_json": { "schema": "docs/schemas/predictions.schema.json", "summary": "YOLOZU predictions JSON (list of {image,detections} or {predictions:[...],meta:{...}}).", "validator": "python3 tools/validate_predictions.py [--strict]" }, "predictions_validation_result_json": { "producer": "python3 tools/validate_predictions.py --json", "schema": "docs/schemas/predictions_validation_result.schema.json", "summary": "Bounded machine-readable success/failure result for predictions validation." }, "qualification_freshness_report_json": { "producer": "python3 tools/check_qualification_freshness.py [--output ]", "schema": "docs/schemas/qualification_freshness_report.schema.json", "summary": "Read-only aggregate warning for active qualification expiry or governed runtime, artifact, bundle, license, revocation, and activation drift; it never extends or re-runs evidence." }, "qualification_report_json": { "producer": "python3 tools/qualify_image_pipeline.py --job --input --bundle-id --bundle-version ", "schema": "docs/schemas/qualification_report.schema.json", "summary": "Experimental unactivated measured-configuration evidence for one exact trusted bundle, artifact set, environment, workload, and frozen protocol; activity signals, fixtures, and report presence are not adoption or Stable support." }, "qualification_workload_profile_json": { "schema": "docs/schemas/qualification_workload_profile.schema.json", "summary": "Shareable performance-relevant workload identity that excludes prompt text, filenames, content hashes, and local sensitive digests." }, "reference_adapter_regression_report_json": { "producer": "python3 tools/run_reference_adapter_regression.py", "schema": "docs/schemas/reference_adapter_regression_report.schema.json", "summary": "Reference adapter regression report with schema/consistency/metric/speed gate results." }, "research_lane_report_json": { "schema": "docs/schemas/research_lane_report.schema.json", "summary": "Research-only artifact boundary with measured overhead, rollback, and an explicit promotion decision." }, "run_meta_json": { "schema": "docs/schemas/run_meta.schema.json", "summary": "Run provenance metadata interface contract emitted at runs//reports/run_meta.json.", "validator": "python3 tools/validate_run_meta.py " }, "screening_eligibility_observation_json": { "schema": "docs/schemas/screening_eligibility_observation.schema.json", "summary": "Bounded screening projection input for one immutable bundle; the pure future selector does not open screening streams." }, "sdft_continual_qualification_json": { "producer": "python3 tools/qualify_sdft_continual.py --output-dir ", "schema": "docs/schemas/sdft_continual_qualification.schema.json", "summary": "Three-seed naive-versus-SDFT-style continual qualification with real COCOeval, provenance, fairness checks, and an explicit decision boundary." }, "seg_dataset_json": { "schema": "docs/schemas/seg_dataset.schema.json", "summary": "Segmentation dataset.json descriptor produced by tools/prepare_*_seg.py." }, "seg_eval_report_json": { "producer": "python3 tools/eval_segmentation.py", "schema": "docs/schemas/seg_eval_report.schema.json", "summary": "Segmentation eval report payload emitted by tools/eval_segmentation.py." }, "segmentation_predictions_json": { "schema": "docs/schemas/segmentation_predictions.schema.json", "summary": "Segmentation predictions JSON (list of {id,mask} or {predictions:[...],meta:{...}}).", "validator": "python3 tools/validate_segmentation_predictions.py " }, "selection_decision_json": { "schema": "docs/schemas/selection_decision.schema.json", "summary": "Complete bounded selected or abstained future adaptive-routing decision with sensitive local digests and explicit candidate reasons." }, "stream_job_spec_json": { "schema": "docs/schemas/stream_job_spec.schema.json", "summary": "Bounded stream request and decoder policy interface contract; input paths and media contents remain outside the record." }, "stream_qualification_report_json": { "schema": "docs/schemas/stream_qualification_report.schema.json", "summary": "Unactivated exact-configuration stream qualification-report record shape with sustained-rate, drop, memory, quality, failure, and provenance observations." }, "stream_selection_decision_json": { "schema": "docs/schemas/stream_selection_decision.schema.json", "summary": "Complete bounded selected or abstained stream-routing decision with explicit per-candidate reasons and exact qualification references." }, "stream_summary_json": { "schema": "docs/schemas/stream_summary.schema.json", "summary": "Privacy-bounded aggregate stream outcome derived from the validated frame-result sequence without filenames, prompts, or media contents." }, "stream_workload_profile_json": { "schema": "docs/schemas/stream_workload_profile.schema.json", "summary": "Shareable performance-relevant stream workload identity with exact source rate and bounded decoder and scheduling facts." }, "support_profile_eligibility_observation_json": { "schema": "docs/schemas/support_profile_eligibility_observation.schema.json", "summary": "Bounded support-profile projection input for one immutable bundle and lifecycle channel; the pure future selector opens no support or lifecycle stream." }, "support_profile_record_json": { "schema": "docs/schemas/support_profile_record.schema.json", "summary": "Append-only reviewed exact-environment support-profile definition and dormant-set record." }, "support_profile_set_proposal_json": { "schema": "docs/schemas/support_profile_set_proposal.schema.json", "summary": "Canonical public review input that exactly covers one complete ordered dormant support-profile set." }, "support_profile_spec_json": { "schema": "docs/schemas/support_profile_spec.schema.json", "summary": "Immutable exact measured environment, workload, protocol, and advertised-gate scope; it does not extrapolate hardware families." }, "synthgen_sample_contract": { "schema": "schemas/synthgen_sample.schema.json", "spec": "docs/synthgen_contract.md", "summary": "SynthGen intake sample interface contract for external synthetic shard records (image/depth/inst/sem/kpts + schema metadata).", "validator": "python3 tools/validate_synthgen_contract.py --input [--max-samples N]" }, "tracking_output_interface_json": { "schema": "docs/schemas/tracking_output_interface.schema.json", "summary": "Immutable session-scoped tracking declaration with pinned task, state limits, privacy boundary, and no tracker availability claim." }, "tracking_output_record_json": { "schema": "docs/schemas/tracking_output_record.schema.json", "summary": "Canonical bounded tracking JSONL row for observed, predicted, lost, or ended state linked to one validated FrameResult." }, "training_orchestration_report_json": { "producer": "python3 tools/orchestrate_train.py --spec --output ", "schema": "docs/schemas/training_orchestration_report.schema.json", "summary": "Batch-level training orchestration report describing planned or executed multi-backend experiments." }, "training_registry_entry_json": { "producer": "python3 tools/support_external_training.py train-yolox --output ", "schema": "docs/schemas/training_registry_entry.schema.json", "summary": "Append-only training registry entry describing one executed training run and its wrapper-owned artifact bundle." }, "training_run_summary_json": { "producer": "python3 tools/support_external_training.py train-yolox --output ", "schema": "docs/schemas/training_run_summary.schema.json", "summary": "Backend-neutral training run summary interface contract emitted by the reference trainer and by external lanes that also publish a fixed wrapper-owned external run bundle and standardized next_steps commands." } }, "manifest_version": 1, "repo": { "description": "Apache-2.0 interface-contract-first evaluation + tooling harness (CPU-first) for multi-task vision workflows, with no built-in telemetry in shipped tooling and explicit quality-control/reporting boundaries.", "name": "YOLOZU" }, "tools": [ { "contracts": { "consumes": [ "algorithm_bundle_registry_json", "bundle_lifecycle_record_json", "qualification_report_json", "evidence_activation_record_json" ], "produces": [ "evidence_activation_record_json" ] }, "docs": [ "README.md", "Readme_jp.md", "docs/adaptive_image_routing.md", "docs/schemas/evidence_activation_record.schema.json" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Atomically appends only reviewed activation events; dry-run writes nothing and --approve is mandatory for mutation.", "flag": "--activation-stream", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/activate_qualification_evidence.py", "examples": [ { "command": "python3 tools/activate_qualification_evidence.py activate --report reports/image_pipeline_qualification/qualification_report.json --report-id --report-digest --selection-key --expected-head-digest --expected-current-activation-id none --reviewer-role-id site_operator --site-local-review-present --reason 'Reviewed exact local evidence' --activation-stream reports/site/evidence_activation.jsonl", "description": "Dry-run every activation gate; no record is written." }, { "command": "python3 tools/activate_qualification_evidence.py --help", "description": "Inspect the Experimental reviewed activation interface contract." } ], "id": "activate_qualification_evidence", "inputs": [ { "default": "activate", "kind": "string", "name": "operation", "required": false }, { "flag": "--report", "kind": "file", "name": "report", "required": false }, { "flag": "--report-id", "kind": "string", "name": "report_id", "required": false }, { "flag": "--report-digest", "kind": "string", "name": "report_digest", "required": false }, { "flag": "--selection-key", "kind": "string", "name": "selection_key", "required": false }, { "default": "yolozu/data/adaptive_routing/evidence_activation.jsonl", "flag": "--activation-stream", "kind": "file", "name": "activation_stream", "required": false }, { "flag": "--prior-report", "kind": "file", "name": "prior_report", "required": false }, { "flag": "--expected-head-digest", "kind": "string", "name": "expected_head_digest", "required": false }, { "flag": "--expected-current-activation-id", "kind": "string", "name": "expected_current_activation_id", "required": false }, { "flag": "--reviewer-role-id", "kind": "string", "name": "reviewer_role_id", "required": false }, { "flag": "--reason", "kind": "string", "name": "reason", "required": false }, { "flag": "--public-review-id", "kind": "string", "name": "public_review_id", "required": false }, { "flag": "--site-local-review-present", "kind": "string", "name": "site_local_review_present", "required": false }, { "flag": "--supersede", "kind": "string", "name": "supersede", "required": false }, { "flag": "--revoke", "kind": "string", "name": "revoke", "required": false }, { "default": ".", "flag": "--workspace", "kind": "dir", "name": "workspace", "required": false }, { "flag": "--approve", "kind": "string", "name": "approve", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "stdout", "description": "Complete machine-readable dry-run or apply outcome with every observed missing gate.", "kind": "stdout", "name": "activation_outcome" }, { "default": "", "description": "Append-only per-selection-key EvidenceActivationRecord stream after explicit approval.", "kind": "file", "name": "evidence_activation_stream" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Dry-run or atomically append an explicit reviewed activation, supersession, or terminal revocation for one exact current qualification report; report presence alone never activates evidence.", "tags": [ "adaptive-inference", "evidence", "experimental", "qualification", "review", "trust" ] }, { "contracts": { "consumes": [ "predictions_json" ] }, "docs": [ "docs/adapter_templates.md", "docs/adapter_contract.md", "docs/production_readiness.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes adapter parity suite JSON report.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/adapter_parity_suite.py", "examples": [ { "command": "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", "description": "Compare framework adapter outputs against RT-DETR reference predictions." } ], "id": "adapter_parity_suite", "inputs": [ { "description": "Repeatable adapter=predictions.json mapping.", "flag": "--adapter-predictions", "kind": "string", "name": "adapter_predictions", "required": true }, { "flag": "--reference-adapter", "kind": "string", "name": "reference_adapter", "required": false }, { "flag": "--image-size", "kind": "string", "name": "image_size", "required": false }, { "flag": "--iou-thresh", "kind": "number", "name": "iou_thresh", "required": false }, { "flag": "--score-atol", "kind": "number", "name": "score_atol", "required": false }, { "flag": "--bbox-atol", "kind": "number", "name": "bbox_atol", "required": false }, { "default": "reports/adapter_parity_suite.json", "flag": "--output", "kind": "file", "name": "output", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/adapter_parity_suite.json", "description": "Adapter parity report JSON.", "kind": "file", "name": "adapter_parity_suite_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Run parity checks for multiple adapter outputs against a reference adapter predictions file.", "tags": [ "adapter", "parity", "validation" ] }, { "docs": [ "RELEASE.md", "docs/release_reliability_checklist.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes announcement bundle and post report under out dir.", "flag": "--out-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/announce_release.py", "examples": [ { "command": "python3 tools/announce_release.py --out-dir reports/announce", "description": "Generate announcement bundle (no posting)." }, { "command": "python3 tools/announce_release.py --out-dir reports/announce --post --strict-post", "description": "Post to configured platforms (requires secrets)." } ], "id": "announce_release", "inputs": [ { "flag": "--event-json", "kind": "file", "name": "event_json", "required": false }, { "default": "reports/announce", "flag": "--out-dir", "kind": "dir", "name": "out_dir", "required": false }, { "flag": "--post", "kind": "string", "name": "post", "required": false }, { "flag": "--platform", "kind": "string", "name": "platform", "required": false }, { "flag": "--strict-post", "kind": "string", "name": "strict_post", "required": false }, { "flag": "--reddit-subreddit", "kind": "string", "name": "reddit_subreddit", "required": false }, { "flag": "--reddit-kind", "kind": "string", "name": "reddit_kind", "required": false }, { "default": 280, "flag": "--x-max-len", "kind": "number", "name": "x_max_len", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/announce/announcement.json", "description": "Generated announcement bundle JSON.", "kind": "file", "name": "announcement_json" }, { "default": "reports/announce/announcement.md", "description": "Generated announcement markdown.", "kind": "file", "name": "announcement_md" }, { "default": "reports/announce/post_report.json", "description": "Post attempt report (skips + errors + HTTP heads).", "kind": "file", "name": "post_report_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": true }, "runner": "python3", "summary": "Generate (and optionally post) release announcement bundle for LinkedIn/X/Reddit from GitHub release event payload.", "tags": [ "release", "announce", "social" ] }, { "docs": [ "docs/tools_index.md", "docs/external_inference.md", "docs/interop_detectron2_mmdet.md", "docs/interop_yolox.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes backend support audit report JSON.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Writes per-backend prediction artifacts (dry-run or non-dry depending on flags).", "flag": "--work-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/audit_backend_support.py", "examples": [ { "command": "python3 tools/audit_backend_support.py --dataset-root data/real_multitask_fewshot --split val --max-images 2 --output reports/backend_support_audit.json", "description": "Dry-run audit for YOLOX/YOLOv8/Detectron2/MMDetection exporter interface contract support." }, { "command": "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", "description": "Require verified non-dry YOLOX execution with explicit exp and checkpoint inputs." } ], "id": "audit_backend_support", "inputs": [ { "default": "data/real_multitask_fewshot", "flag": "--dataset-root", "kind": "dir", "name": "dataset_root", "required": false }, { "default": "val", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "default": 2, "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "default": "reports/backend_support_audit.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--work-dir", "kind": "dir", "name": "work_dir", "required": false }, { "flag": "--python", "kind": "string", "name": "python", "required": false }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false }, { "description": "Backend key to run without --dry-run (repeatable).", "flag": "--non-dry-backend", "kind": "string", "name": "non_dry_backend", "required": false }, { "description": "Fail unless at least one selected non-dry backend supplies verified runtime execution evidence.", "flag": "--require-non-dry", "kind": "string", "name": "require_non_dry", "required": false }, { "description": "YOLOX exp file required when YOLOX is selected for a non-dry audit.", "flag": "--yolox-exp", "kind": "file", "name": "yolox_exp", "required": false }, { "description": "YOLOX checkpoint required when YOLOX is selected for a non-dry audit.", "flag": "--yolox-weights", "kind": "file", "name": "yolox_weights", "required": false }, { "default": "yolov8n.pt", "description": "Ultralytics model path or name used for a non-dry YOLO runtime audit.", "flag": "--ultralytics-model", "kind": "string", "name": "ultralytics_model", "required": false }, { "description": "Detectron2 config file required when Detectron2 is selected for a non-dry audit.", "flag": "--detectron2-config", "kind": "file", "name": "detectron2_config", "required": false }, { "description": "Detectron2 weights file required when Detectron2 is selected for a non-dry audit.", "flag": "--detectron2-weights", "kind": "file", "name": "detectron2_weights", "required": false }, { "description": "MMDetection config file required when MMDetection is selected for a non-dry audit.", "flag": "--mmdet-config", "kind": "file", "name": "mmdet_config", "required": false }, { "description": "MMDetection checkpoint required when MMDetection is selected for a non-dry audit.", "flag": "--mmdet-checkpoint", "kind": "file", "name": "mmdet_checkpoint", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/backend_support_audit.json", "description": "Audit report with per-backend artifact and execution-evidence checks plus verified_non_dry_backends.", "kind": "file", "name": "backend_support_audit_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Audit YOLOX/YOLOv8/Detectron2/MMDetection exporters, with verified execution evidence for selected non-dry backends.", "tags": [ "audit", "backend", "interop", "predictions" ] }, { "docs": [ "docs/manifest_authoring_workflow.md", "docs/README.md" ], "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "tools/audit_docs_examples_drift.py", "examples": [ { "command": "python3 tools/audit_docs_examples_drift.py --json", "description": "Run the full docs example drift gate." }, { "command": "python3 tools/audit_docs_examples_drift.py --docs docs/cpu_only_dod.md --skip-manual --skip-manifest --json", "description": "Audit a single markdown file without subchecks." } ], "id": "audit_docs_examples_drift", "inputs": [ { "default": null, "flag": "--docs", "kind": "file", "name": "docs", "required": false }, { "default": "sys.executable", "flag": "--python", "kind": "string", "name": "python", "required": false }, { "flag": "--json", "kind": "string", "name": "json", "required": false }, { "flag": "--skip-manual", "kind": "string", "name": "skip_manual", "required": false }, { "flag": "--skip-manifest", "kind": "string", "name": "skip_manifest", "required": false } ], "maturity": "stable", "outputs": [ { "description": "Docs example drift audit JSON or text summary.", "kind": "stdout", "name": "stdout" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false }, "runner": "python3", "summary": "Audit README/docs examples against yolozu help, manual CLI drift, and manifest help drift gates.", "tags": [ "docs", "manifest", "ci", "drift" ] }, { "docs": [ "manual/chapters/04_cli_reference.tex", "docs/release_reliability_checklist.md", "docs/manual_cli_drift_allowlist.json" ], "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "tools/audit_manual_cli_drift.py", "examples": [ { "command": "python3 tools/audit_manual_cli_drift.py --json", "description": "Audit documented top-level yolozu commands against canonical CLI help and legacy wrapper help." } ], "id": "audit_manual_cli_drift", "inputs": [ { "default": "manual/chapters", "description": "A TeX chapter file or directory of chapters; checks command macros and code listings.", "flag": "--manual", "kind": "string", "name": "manual", "required": false }, { "default": "docs/manual_cli_drift_allowlist.json", "flag": "--allowlist", "kind": "file", "name": "allowlist", "required": false }, { "flag": "--python", "kind": "string", "name": "python", "required": false }, { "flag": "--skip-wrapper", "kind": "string", "name": "skip_wrapper", "required": false }, { "flag": "--json", "kind": "string", "name": "json", "required": false } ], "maturity": "stable", "outputs": [ { "description": "Human-readable or JSON audit summary on stdout.", "kind": "stdout", "name": "audit_report" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true, "notes": "Uses --help probes only; does not require optional backend runtimes." }, "requires": { "python_packages": [] }, "runner": "python3", "summary": "Audit all manual chapters, including code listings, against canonical yolozu CLI help and legacy wrapper help.", "tags": [ "cli", "manual", "quality-gate" ] }, { "contracts": { "consumes": [ "predictions_json" ] }, "docs": [ "docs/backend_parity_matrix.md", "docs/onnx_export_parity.md" ], "effects": { "fixed_writes": [ { "description": "Default run root when --run-dir is not provided.", "kind": "dir", "path": "runs/backend_parity_matrix", "scope": "tree" } ], "writes": [ { "description": "Writes backend parity matrix JSON report (defaults to /reports/backend_parity_matrix.json).", "flag": "--output-json", "kind": "file", "scope": "path" }, { "description": "Writes backend parity matrix HTML report (defaults to /reports/backend_parity_matrix.html).", "flag": "--output-html", "kind": "file", "scope": "path" }, { "description": "Creates run/report directories under --run-dir when provided.", "flag": "--run-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/backend_parity_matrix.py", "examples": [ { "command": "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", "description": "One-command parity matrix against torch reference with fixed thresholds." } ], "id": "backend_parity_matrix", "inputs": [ { "description": "Repeatable backend=predictions.json mapping (torch/onnxrt/trt/opencv_dnn/custom_cpp).", "flag": "--backend-predictions", "kind": "string", "name": "backend_predictions", "required": true }, { "default": "torch", "flag": "--reference-backend", "kind": "string", "name": "reference_backend", "required": false }, { "flag": "--image-size", "kind": "string", "name": "image_size", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "default": 0.99, "flag": "--iou-thresh", "kind": "number", "name": "iou_thresh", "required": false }, { "default": 0.0001, "flag": "--score-atol", "kind": "number", "name": "score_atol", "required": false }, { "default": 0.0001, "flag": "--bbox-atol", "kind": "number", "name": "bbox_atol", "required": false }, { "flag": "--run-id", "kind": "string", "name": "run_id", "required": false }, { "default": "runs", "flag": "--runs-dir", "kind": "dir", "name": "runs_dir", "required": false }, { "flag": "--run-dir", "kind": "dir", "name": "run_dir", "required": false }, { "flag": "--output-json", "kind": "file", "name": "output_json", "required": false }, { "flag": "--output-html", "kind": "file", "name": "output_html", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "runs/backend_parity_matrix//reports/backend_parity_matrix.json", "description": "JSON report artifact.", "kind": "file", "name": "report_json" }, { "default": "runs/backend_parity_matrix//reports/backend_parity_matrix.html", "description": "HTML report artifact.", "kind": "file", "name": "report_html" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Run one-command backend parity matrix checks across torch/onnxrt/trt/opencv_dnn/custom_cpp and export JSON+HTML reports.", "tags": [ "backend", "parity", "validation", "report" ] }, { "contracts": { "consumes": [ "predictions_json" ] }, "docs": [ "docs/eata_design_spec.md", "docs/eata_benchmark.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes EATA benchmark JSON artifact.", "flag": "--output-json", "kind": "file", "scope": "path" }, { "description": "Writes EATA benchmark Markdown summary.", "flag": "--output-md", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/benchmark_eata_stability.py", "examples": [ { "command": "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", "description": "Generate a non-promoting local diagnostic of baseline-vs-EATA stability and efficiency." } ], "id": "benchmark_eata_stability", "inputs": [ { "flag": "--baseline", "kind": "file", "name": "baseline", "required": true }, { "flag": "--eata", "kind": "file", "name": "eata", "required": true }, { "default": "reports/eata_benchmark.json", "flag": "--output-json", "kind": "file", "name": "output_json", "required": false }, { "default": "reports/eata_benchmark.md", "flag": "--output-md", "kind": "file", "name": "output_md", "required": false }, { "default": 1.5, "flag": "--max-overhead-ratio", "kind": "number", "name": "max_overhead_ratio", "required": false }, { "default": 1.05, "flag": "--max-loss-ratio", "kind": "number", "name": "max_loss_ratio", "required": false }, { "default": 0.1, "flag": "--min-selected-ratio", "kind": "number", "name": "min_selected_ratio", "required": false } ], "maturity": "research", "outputs": [ { "default": "reports/eata_benchmark.json", "description": "EATA benchmark JSON artifact.", "kind": "file", "name": "eata_benchmark_json" }, { "default": "reports/eata_benchmark.md", "description": "EATA benchmark Markdown artifact.", "kind": "file", "name": "eata_benchmark_md" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Compare EATA stability/efficiency diagnostics with a baseline; efficacy remains not established and the report cannot promote defaults.", "tags": [ "tta", "eata", "benchmark", "stability", "efficiency", "report" ] }, { "contracts": { "consumes": [ "predictions_json" ], "produces": [ "metrics_report_json" ] }, "effects": { "fixed_writes": [], "writes": [ { "description": "Write the benchmark evaluation JSON report.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/benchmark_keypoints_eval.py", "examples": [ { "command": "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", "description": "Quick PCK eval benchmark on a small slice." } ], "id": "benchmark_keypoints_eval", "inputs": [ { "description": "Dataset root; required unless --data is used.", "flag": "--dataset", "kind": "dir", "name": "dataset", "required": false }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--predictions", "kind": "file", "name": "predictions", "required": true }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--warmup", "kind": "number", "name": "warmup", "required": false }, { "flag": "--iterations", "kind": "number", "name": "iterations", "required": false }, { "flag": "--iou-threshold", "kind": "number", "name": "iou_threshold", "required": false }, { "flag": "--min-score", "kind": "number", "name": "min_score", "required": false }, { "flag": "--pck-threshold", "kind": "number", "name": "pck_threshold", "required": false }, { "flag": "--oks", "kind": "string", "name": "oks", "required": false }, { "flag": "--oks-sigmas", "kind": "string", "name": "oks_sigmas", "required": false }, { "flag": "--oks-sigmas-file", "kind": "file", "name": "oks_sigmas_file", "required": false }, { "flag": "--oks-max-dets", "kind": "number", "name": "oks_max_dets", "required": false }, { "default": "reports/benchmark_keypoints_eval.json", "flag": "--output", "kind": "file", "name": "output", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/benchmark_keypoints_eval.json", "description": "JSON report artifact.", "kind": "file", "name": "report_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Benchmark keypoints evaluation runtime (PCK + optional OKS mAP) and write a stable JSON report.", "tags": [ "benchmark", "keypoints", "pose", "eval" ] }, { "contracts": { "produces": [ "metrics_report_json" ] }, "docs": [ "docs/benchmark_latency.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Write the benchmark JSON report.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Optional JSONL history file to append benchmark reports to.", "flag": "--history", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/benchmark_latency.py", "examples": [ { "command": "python3 tools/benchmark_latency.py --iterations 200 --warmup 20 --output reports/benchmark_latency.json --history reports/benchmark_latency.jsonl --notes \"baseline on target HW\"", "description": "Synthetic benchmark (no inference) to validate harness." } ], "id": "benchmark_latency", "inputs": [ { "flag": "--config", "kind": "file", "name": "config", "required": false }, { "flag": "--model-template", "kind": "string", "name": "model_template", "required": false }, { "flag": "--engine-template", "kind": "string", "name": "engine_template", "required": false }, { "flag": "--buckets", "kind": "string", "name": "buckets", "required": false }, { "flag": "--run-id", "kind": "string", "name": "run_id", "required": false }, { "flag": "--notes", "kind": "string", "name": "notes", "required": false }, { "flag": "--notes-file", "kind": "file", "name": "notes_file", "required": false }, { "flag": "--iterations", "kind": "number", "name": "iterations", "required": false }, { "flag": "--warmup", "kind": "number", "name": "warmup", "required": false }, { "flag": "--sleep-s", "kind": "number", "name": "sleep_s", "required": false }, { "flag": "--target-fps", "kind": "number", "name": "target_fps", "required": false }, { "flag": "--target-latency-ms", "kind": "number", "name": "target_latency_ms", "required": false }, { "default": "reports/benchmark_latency.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "default": null, "flag": "--history", "kind": "file", "name": "history", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/benchmark_latency.json", "description": "JSON report artifact.", "kind": "file", "name": "report_json" }, { "default": null, "description": "Optional JSONL history when --history is set.", "kind": "file", "name": "history_jsonl" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Latency/FPS benchmark harness producing stable JSON reports and optional JSONL history.", "tags": [ "benchmark", "realtime" ] }, { "contract_outputs": { "metrics_report_json": "benchmark_report_json", "predictions_json": "predictions_json" }, "contracts": { "produces": [ "metrics_report_json", "predictions_json" ] }, "docs": [ "docs/benchmark_mode.md", "docs/benchmark_support_matrix.md", "docs/benchmark_mode_spec_parity_target.md", "docs/benchmark_latency.md", "docs/benchmark_mode_gap_audit.md", "docs/benchmark_backend_runtime_matrix.md", "docs/production_readiness.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Write the benchmark report JSON.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Append JSONL benchmark history when requested.", "flag": "--history", "kind": "file", "scope": "path" }, { "description": "Optional predictions artifact file/dir/template.", "flag": "--predictions-output", "kind": "file", "scope": "path" }, { "description": "Optional eval artifact file/dir/template.", "flag": "--eval-output", "kind": "file", "scope": "path" }, { "description": "Optional parity artifact file/dir/template.", "flag": "--parity-output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/benchmark_model.py", "examples": [ { "command": "python3 tools/benchmark_model.py --model runs/example/model.pt --data data/coco8.yaml --format all --dry-run --output reports/benchmark_report.json", "description": "Dry-run the benchmark wiring and artifact layout for all supported formats." }, { "command": "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", "description": "Run real torch/onnx/engine/torchscript detect backend orchestration when backend artifacts are available." }, { "command": "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", "description": "Run protocol-pinned backend orchestration and append JSONL history." }, { "command": "python3 tools/benchmark_model.py --help # then read docs/benchmark_support_matrix.md", "description": "Review the current benchmark/export-surface gap before extending format coverage." }, { "command": "python3 tools/benchmark_model.py --model exports/example.torchscript --data data/coco8.yaml --format torchscript --output reports/benchmark_report.json", "description": "Run a TorchScript detect benchmark using the declared combined-output decode path." }, { "command": "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", "description": "Run the conditional OpenVINO detect benchmark lane when OpenVINO runtime and IR artifacts are available." }, { "command": "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", "description": "Run real torch+onnx backend orchestration and emit backend parity artifacts." }, { "command": "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", "description": "Run detect benchmark parity with ONNX as the explicit reference backend instead of the default torch-preferred selection." }, { "command": "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", "description": "Inspect task-specific segmentation benchmark semantics in a dry-run report." }, { "command": "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", "description": "Run the artifact-backed semantic-segmentation benchmark/parity lane for backend-specific mask predictions artifacts." }, { "command": "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", "description": "Run the artifact-backed keypoints benchmark/parity lane for backend-specific predictions artifacts." }, { "command": "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", "description": "Run the artifact-backed classification eval/parity lane; its input interface contract rejects invalid top-level shapes, duplicate sample ids, non-finite or class-misaligned score vectors, invalid class vocabularies, and inconsistent ordered class lists." }, { "command": "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", "description": "Run the artifact-backed OBB eval/parity lane; its input interface contract rejects invalid top-level shapes, duplicate image ids, non-finite or out-of-range geometry/scores, invalid class ids or vocabularies, and inconsistent ordered class lists while allowing empty detection lists. Metrics use confidence-ranked per-class rotated-IoU AP and separately averaged recall." }, { "command": "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", "description": "Inspect YOLOZU-native depth benchmark semantics without claiming mainstream benchmark-surface parity." }, { "command": "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", "description": "Run the artifact-backed depth benchmark/parity lane for backend-specific depth outputs." }, { "command": "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", "description": "Run the artifact-backed 6DoF benchmark/parity lane for backend-specific predictions artifacts." }, { "command": "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", "description": "Inspect YOLOZU-native pose6d dry-run semantics while real artifact_eval remains artifact-backed." } ], "id": "benchmark_model", "inputs": [ { "flag": "--model", "kind": "file", "name": "model", "required": true }, { "flag": "--data", "kind": "string", "name": "data", "required": true }, { "default": 640, "flag": "--imgsz", "kind": "number", "name": "imgsz", "required": false }, { "default": false, "description": "Use FP16 in the torch detect backend; supported artifact_eval lanes require the false default.", "flag": "--half", "kind": "string", "name": "half", "required": false }, { "default": false, "description": "Explicitly keep FP16 disabled; this is the accepted default within supported artifact_eval lanes.", "flag": "--no-half", "kind": "string", "name": "half", "required": false }, { "default": false, "flag": "--int8", "kind": "string", "name": "int8", "required": false }, { "default": false, "flag": "--no-int8", "kind": "string", "name": "int8", "required": false }, { "default": "cpu", "flag": "--device", "kind": "string", "name": "device", "required": false }, { "default": false, "flag": "--verbose", "kind": "string", "name": "verbose", "required": false }, { "default": "all", "flag": "--format", "kind": "string", "name": "format", "required": false }, { "default": "detect", "description": "Benchmark task label. Canonical tasks: detect, segmentation, classification, obb, keypoints, depth, pose6d. Accepted aliases include detection, seg, classify, cls, pose, and 6dof.", "flag": "--task", "kind": "string", "name": "task", "required": false }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "default": false, "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "default": false, "description": "Return exit code 2 if any requested benchmark format is skipped, fails, or is partial.", "flag": "--strict", "kind": "string", "name": "strict", "required": false }, { "default": "relaxed", "flag": "--repro-policy", "kind": "string", "name": "repro_policy", "required": false }, { "default": "none", "flag": "--runtime-lock", "kind": "string", "name": "runtime_lock", "required": false }, { "flag": "--run-id", "kind": "string", "name": "run_id", "required": false }, { "default": "reports/benchmark_report.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--history", "kind": "file", "name": "history", "required": false }, { "flag": "--predictions-output", "kind": "string", "name": "predictions_output", "required": false }, { "flag": "--eval-output", "kind": "string", "name": "eval_output", "required": false }, { "flag": "--parity-output", "kind": "string", "name": "parity_output", "required": false }, { "default": 1, "description": "Torch detect backend batch size; supported artifact_eval lanes require the default value 1.", "flag": "--batch", "kind": "number", "name": "batch", "required": false }, { "default": false, "flag": "--dynamic", "kind": "string", "name": "dynamic", "required": false }, { "default": false, "flag": "--no-dynamic", "kind": "string", "name": "dynamic", "required": false }, { "default": false, "description": "Request NMS in the torch detect backend; supported artifact_eval lanes require the false default.", "flag": "--nms", "kind": "string", "name": "nms", "required": false }, { "default": false, "description": "Explicitly keep backend NMS disabled; this is the accepted default within supported artifact_eval lanes.", "flag": "--no-nms", "kind": "string", "name": "nms", "required": false }, { "default": false, "flag": "--simplify", "kind": "string", "name": "simplify", "required": false }, { "default": false, "flag": "--no-simplify", "kind": "string", "name": "simplify", "required": false }, { "default": 17, "flag": "--opset", "kind": "number", "name": "opset", "required": false }, { "default": 4.0, "flag": "--workspace", "kind": "number", "name": "workspace", "required": false }, { "default": 1.0, "flag": "--fraction", "kind": "number", "name": "fraction", "required": false }, { "default": "auto", "description": "Benchmark source selection. auto uses dataset_pass_wall_time for detect and artifact_eval for artifact-backed tasks on real formats. Detect rejects explicit artifact_eval before report, artifact, or backend writes because no prepared detection-artifact evaluation path is implemented; supported artifact_eval tasks reject non-default --half, --batch, and --nms. Non-dry-run artifact-backed tasks reject dataset_pass_wall_time and require auto or artifact_eval.", "flag": "--latency-source", "kind": "string", "name": "latency_source", "required": false }, { "choices": [ "auto", "torch", "onnx", "engine", "torchscript", "openvino" ], "default": "auto", "description": "Parity reference backend (auto prefers torch, then the first eligible real backend). OpenVINO detect requires a supplied IR and runtime; artifact-backed OpenVINO tasks use prepared artifacts without a runtime check.", "flag": "--parity-reference-backend", "kind": "string", "name": "parity_reference_backend", "required": false }, { "default": 0.0001, "description": "Classification parity absolute tolerance for aligned class scores.", "flag": "--classification-parity-score-atol", "kind": "number", "name": "classification_parity_score_atol", "required": false }, { "default": 0.99, "description": "OBB parity rotated-IoU threshold for same-sample, same-class matching.", "flag": "--obb-parity-iou-thresh", "kind": "number", "name": "obb_parity_iou_thresh", "required": false }, { "default": 0.0001, "description": "OBB parity absolute tolerance for confidence scores on matched detections.", "flag": "--obb-parity-score-atol", "kind": "number", "name": "obb_parity_score_atol", "required": false }, { "default": 50, "flag": "--iterations", "kind": "number", "name": "iterations", "required": false }, { "default": 5, "flag": "--warmup", "kind": "number", "name": "warmup", "required": false }, { "default": 0.0, "description": "Finite, non-negative synthetic latency sleep per step.", "flag": "--sleep-s", "kind": "number", "name": "sleep_s", "required": false }, { "flag": "--torch-model", "kind": "file", "name": "torch_model", "required": false }, { "flag": "--onnx-model", "kind": "file", "name": "onnx_model", "required": false }, { "flag": "--engine-model", "kind": "file", "name": "engine_model", "required": false }, { "flag": "--torchscript-model", "kind": "file", "name": "torchscript_model", "required": false }, { "description": "OpenVINO-lane artifact override. Detect expects a compatible IR and external runtime; artifact-backed tasks accept prepared task artifacts without checking or invoking the OpenVINO runtime.", "flag": "--openvino-model", "kind": "file", "name": "openvino_model", "required": false }, { "flag": "--depth-mask", "kind": "file", "name": "depth_mask", "required": false }, { "default": "median_scale", "flag": "--depth-align", "kind": "string", "name": "depth_align", "required": false }, { "default": 0.02, "flag": "--depth-parity-mae-atol", "kind": "number", "name": "depth_parity_mae_atol", "required": false }, { "default": 0.03, "flag": "--depth-parity-rmse-atol", "kind": "number", "name": "depth_parity_rmse_atol", "required": false }, { "default": 0.0, "description": "Segmentation parity mismatch-rate tolerance.", "flag": "--segmentation-parity-mismatch-atol", "kind": "number", "name": "segmentation_parity_mismatch_atol", "required": false }, { "default": 0.99, "description": "Keypoints parity IoU threshold.", "flag": "--keypoints-parity-iou-thresh", "kind": "number", "name": "keypoints_parity_iou_thresh", "required": false }, { "default": 0.0001, "description": "Keypoints parity score tolerance.", "flag": "--keypoints-parity-score-atol", "kind": "number", "name": "keypoints_parity_score_atol", "required": false }, { "default": 0.0001, "description": "Keypoints parity bbox tolerance.", "flag": "--keypoints-parity-bbox-atol", "kind": "number", "name": "keypoints_parity_bbox_atol", "required": false }, { "default": 0.0001, "description": "Keypoints parity keypoint tolerance in normalized coordinates.", "flag": "--keypoints-parity-kp-atol", "kind": "number", "name": "keypoints_parity_kp_atol", "required": false }, { "default": 0.001, "flag": "--pose-parity-rot-deg-atol", "kind": "number", "name": "pose_parity_rot_deg_atol", "required": false }, { "default": 0.0001, "flag": "--pose-parity-trans-atol", "kind": "number", "name": "pose_parity_trans_atol", "required": false }, { "default": 0.0001, "flag": "--pose-parity-depth-atol", "kind": "number", "name": "pose_parity_depth_atol", "required": false }, { "flag": "--protocol", "kind": "string", "name": "protocol", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/benchmark_report.json", "description": "Top-level benchmark report including task_requested/task/task_semantics, execution_semantics, support_summary, parity_summary, and per-format results. Per-format runtime.required/runtime.checked distinguish a real runtime probe from artifact-backed lanes that do not require or check the external runtime; runtime.available remains false when checked is false.", "kind": "file", "name": "benchmark_report_json" }, { "default": null, "description": "Optional JSONL history when --history is set.", "kind": "file", "name": "history_jsonl" }, { "default": null, "description": "Per-format predictions artifact (real output when the backend runs; for classification artifact_eval, a strict-JSON normalized score artifact after unique-id, finite-value, class-list, and vector-length validation; for OBB artifact_eval, a strict-JSON normalized rotated-box artifact after unique-id, finite-geometry, class-list, and [0,1] score validation with empty detections allowed; rewritten/copy metadata for other artifact-backed tasks; non-real fallback artifact otherwise).", "kind": "file", "name": "predictions_json" }, { "default": null, "description": "Per-format evaluation artifact (real output when evaluation runs, including strict-JSON artifact_eval reports with task-specific metrics, source checksums, and metric provenance for validated classification inputs; OBB reports with source checksums and metric provenance for confidence-ranked per-class rotated-IoU AP and separately averaged recall; and reports from tools/eval_segmentation.py, tools/eval_keypoints.py, tools/eval_depth.py, or tools/eval_pose.py for segmentation/keypoints/depth/pose6d; non-real fallback artifact otherwise).", "kind": "file", "name": "eval_report_json" }, { "default": null, "description": "Per-format parity artifact (real backend diff for successful real backend comparisons, including strict-JSON artifact-backed classification score parity and OBB rotated-IoU/score parity with input checksums, plus artifact-backed parity for task=segmentation/keypoints/depth/pose6d; non-real fallback artifact when comparison prerequisites are unavailable).", "kind": "file", "name": "parity_report_json" }, { "default": null, "description": "Per-format export settings artifact; classification and OBB artifact_eval lanes emit strict JSON and record task-specific parity thresholds.", "kind": "file", "name": "export_settings_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "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.", "tags": [ "benchmark", "parity", "export" ] }, { "contracts": { "consumes": [ "predictions_json" ] }, "docs": [ "docs/sar_design_spec.md", "docs/sar_evaluation.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes SAR robustness benchmark JSON artifact.", "flag": "--output-json", "kind": "file", "scope": "path" }, { "description": "Writes SAR robustness benchmark Markdown summary.", "flag": "--output-md", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/benchmark_sar_robustness.py", "examples": [ { "command": "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", "description": "Generate a non-promoting local SAR/CoTTA/EATA diagnostic." } ], "id": "benchmark_sar_robustness", "inputs": [ { "flag": "--cotta", "kind": "file", "name": "cotta", "required": true }, { "flag": "--eata", "kind": "file", "name": "eata", "required": true }, { "flag": "--sar", "kind": "file", "name": "sar", "required": true }, { "default": "reports/sar_robustness_report.json", "flag": "--output-json", "kind": "file", "name": "output_json", "required": false }, { "default": "reports/sar_robustness_report.md", "flag": "--output-md", "kind": "file", "name": "output_md", "required": false }, { "default": 1.5, "flag": "--max-overhead-ratio", "kind": "number", "name": "max_overhead_ratio", "required": false }, { "default": 1.05, "flag": "--max-loss-ratio", "kind": "number", "name": "max_loss_ratio", "required": false }, { "default": 1.2, "flag": "--max-variance-ratio", "kind": "number", "name": "max_variance_ratio", "required": false } ], "maturity": "research", "outputs": [ { "default": "reports/sar_robustness_report.json", "description": "SAR robustness JSON artifact.", "kind": "file", "name": "sar_robustness_json" }, { "default": "reports/sar_robustness_report.md", "description": "SAR robustness Markdown artifact.", "kind": "file", "name": "sar_robustness_md" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Compare local SAR/CoTTA/EATA diagnostics; efficacy remains not established and the report is not go/no-go evidence.", "tags": [ "tta", "sar", "benchmark", "robustness", "report" ] }, { "effects": { "fixed_writes": [ { "description": "Writes a dataset manifest JSON.", "kind": "file", "path": "reports/manifest.json", "scope": "path" } ], "writes": [] }, "entrypoint": "tools/build_manifest.py", "examples": [ { "command": "python3 tools/build_manifest.py", "description": "Emit manifest JSON for coco128." } ], "id": "build_manifest", "inputs": [], "maturity": "stable", "outputs": [ { "default": "reports/manifest.json", "description": "Manifest JSON artifact.", "kind": "file", "name": "manifest_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Build a dataset manifest for data/coco128 (writes reports/manifest.json).", "tags": [ "dataset" ] }, { "docs": [ "docs/tensorrt_pipeline.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes TensorRT engine plan.", "flag": "--engine", "kind": "file", "scope": "path" }, { "description": "Writes timing cache.", "flag": "--timing-cache", "kind": "file", "scope": "path" }, { "description": "Writes build metadata JSON.", "flag": "--meta-output", "kind": "file", "scope": "path" }, { "description": "Optional INT8 calibration cache output.", "flag": "--calib-cache", "kind": "file", "scope": "path" }, { "description": "Optional calibration image list output.", "flag": "--calib-list-output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/build_trt_engine.py", "examples": [ { "command": "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", "description": "Build FP16 engine (Linux/NVIDIA)." } ], "id": "build_trt_engine", "inputs": [ { "flag": "--onnx", "kind": "file", "name": "onnx", "required": true }, { "default": "engines/model.plan", "flag": "--engine", "kind": "file", "name": "engine", "required": false }, { "default": "engines/timing.cache", "flag": "--timing-cache", "kind": "file", "name": "timing_cache", "required": false }, { "default": "reports/trt_engine_meta.json", "flag": "--meta-output", "kind": "file", "name": "meta_output", "required": false }, { "flag": "--precision", "kind": "string", "name": "precision", "required": false }, { "flag": "--input-name", "kind": "string", "name": "input_name", "required": false }, { "flag": "--min-shape", "kind": "string", "name": "min_shape", "required": false }, { "flag": "--opt-shape", "kind": "string", "name": "opt_shape", "required": false }, { "flag": "--max-shape", "kind": "string", "name": "max_shape", "required": false }, { "flag": "--workspace", "kind": "number", "name": "workspace", "required": false }, { "flag": "--trtexec", "kind": "string", "name": "trtexec", "required": false }, { "flag": "--builder", "kind": "string", "name": "builder", "required": false }, { "flag": "--calib-cache", "kind": "file", "name": "calib_cache", "required": false }, { "flag": "--calib-dataset", "kind": "dir", "name": "calib_dataset", "required": false }, { "flag": "--calib-split", "kind": "string", "name": "calib_split", "required": false }, { "flag": "--calib-images", "kind": "number", "name": "calib_images", "required": false }, { "flag": "--calib-list-output", "kind": "file", "name": "calib_list_output", "required": false }, { "flag": "--extra-args", "kind": "string", "name": "extra_args", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "engines/model.plan", "description": "Engine plan artifact.", "kind": "file", "name": "engine_plan" }, { "default": "engines/timing.cache", "description": "Timing cache artifact.", "kind": "file", "name": "timing_cache" }, { "default": "reports/trt_engine_meta.json", "description": "Meta output artifact.", "kind": "file", "name": "meta_output" } ], "platform": { "cpu_ok": true, "gpu_required": true, "linux_ok": true, "macos_ok": false, "notes": "Typically requires Linux + NVIDIA + TensorRT (trtexec)." }, "requires": { "system": [ "trtexec" ] }, "runner": "python3", "summary": "Build a TensorRT engine from ONNX using trtexec and write a reproducible meta JSON.", "tags": [ "tensorrt", "engine" ] }, { "contracts": { "consumes": [ "predictions_json" ], "produces": [ "predictions_json", "metrics_report_json", "research_lane_report_json" ] }, "docs": [ "docs/score_calibration.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes calibrated predictions JSON.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Writes calibration report JSON.", "flag": "--output-report", "kind": "file", "scope": "path" }, { "description": "Writes calibration artifact JSON.", "flag": "--output-artifact", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/calibrate_scores.py", "examples": [ { "command": "python3 tools/calibrate_scores.py --dataset data/coco128 --predictions reports/predictions.json --output reports/predictions_calibrated.json --output-report reports/calibration_report.json", "description": "Calibrate scores on coco128 subset." } ], "id": "calibrate_scores", "inputs": [ { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--predictions", "kind": "file", "name": "predictions", "required": true }, { "default": "reports/predictions_calibrated.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "default": "reports/calibration_report.json", "flag": "--output-report", "kind": "file", "name": "output_report", "required": false }, { "default": "reports/calibration_artifact.json", "flag": "--output-artifact", "kind": "file", "name": "output_artifact", "required": false }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "default": "0.5,1.0,1.5,2.0", "flag": "--temperatures", "kind": "string", "name": "temperatures", "required": false }, { "flag": "--min-score", "kind": "number", "name": "min_score", "required": false }, { "flag": "--max-score", "kind": "number", "name": "max_score", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/predictions_calibrated.json", "description": "Predictions calibrated artifact.", "kind": "file", "name": "predictions_calibrated" }, { "default": "reports/calibration_report.json", "description": "JSON report artifact.", "kind": "file", "name": "report_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Temperature-scale detection scores to improve mAP proxy on a fixed subset (no NMS).", "tags": [ "predictions", "calibration" ] }, { "docs": [ "docs/image_service_mcp.md", "docs/llm_integrations.md", "docs/openai_mcp_actions.md" ], "effects": { "fixed_writes": [ { "kind": "dir", "path": "runs/mcp_image_service", "scope": "tree" } ], "writes": [] }, "entrypoint": "yolozu/integrations/mcp_server.py", "examples": [ { "command": "Call the cancel_image_job MCP tool with a queued or running job_id.", "description": "Cancel queued work or request termination of the running owned process; poll until terminal." } ], "id": "cancel_image_job", "inputs": [ { "description": "Opaque image job identity.", "kind": "string", "name": "job_id", "required": true } ], "maturity": "experimental", "outputs": [ { "description": "Structured result: cancelled=true for stopped queued work, or reason=cancellation_requested while running work is stopping.", "kind": "json", "name": "cancellation_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false, "python_packages": [ "mcp", "Pillow" ] }, "runner": "python3", "summary": "Cancel queued image work or stop a running owned process; release retained assets after termination and preserve tenant rate limits.", "tags": [ "ai-first", "image-service", "mcp", "security" ] }, { "contracts": { "consumes": [ "predictions_json", "segmentation_predictions_json", "instance_segmentation_predictions_json" ] }, "docs": [ "docs/rfc_workflow.md", "docs/schema_governance.md" ], "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "tools/check_golden_compatibility.py", "examples": [ { "command": "python3 tools/check_golden_compatibility.py --manifest baselines/golden/v1/manifest.json", "description": "Run golden compatibility gate using versioned baseline manifest." } ], "id": "check_golden_compatibility", "inputs": [ { "default": "baselines/golden/v1/manifest.json", "flag": "--manifest", "kind": "file", "name": "manifest", "required": false } ], "maturity": "experimental", "outputs": [ { "description": "Validation summary JSON; non-zero exit on incompatibility/hash mismatch.", "kind": "stdout", "name": "stdout" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Validate versioned golden compatibility assets and hash-pinned eval protocol snapshots.", "tags": [ "golden", "compatibility", "schema", "protocol", "gate" ] }, { "contracts": { "consumes": [ "predictions_json" ] }, "docs": [ "docs/benchmark_mode.md", "docs/onnx_export_parity.md", "docs/tools_index.md" ], "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "tools/check_keypoints_parity.py", "examples": [ { "command": "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", "description": "Parity check for keypoints in normalized coords." } ], "id": "check_keypoints_parity", "inputs": [ { "flag": "--reference", "kind": "file", "name": "reference", "required": true }, { "flag": "--candidate", "kind": "file", "name": "candidate", "required": true }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--iou-thresh", "kind": "number", "name": "iou_thresh", "required": false }, { "flag": "--score-atol", "kind": "number", "name": "score_atol", "required": false }, { "flag": "--bbox-atol", "kind": "number", "name": "bbox_atol", "required": false }, { "flag": "--kp-atol", "kind": "number", "name": "kp_atol", "required": false } ], "maturity": "experimental", "outputs": [ { "description": "Mismatch report (JSON/text) and exit status.", "kind": "stdout", "name": "stdout" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Compare two keypoints prediction JSONs and report mismatches (IoU/tolerance-based).", "tags": [ "predictions", "parity", "keypoints", "pose" ] }, { "docs": [ "docs/license_policy.md" ], "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "tools/check_license_policy.py", "examples": [ { "command": "python3 tools/check_license_policy.py", "description": "Run policy checks." } ], "id": "check_license_policy", "inputs": [], "maturity": "stable", "outputs": [ { "description": "OK or failure reason.", "kind": "stdout", "name": "stdout" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Enforce Apache-2.0-only constraints (denylist + no vendored GPL/AGPL license texts).", "tags": [ "policy", "license" ] }, { "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "tools/check_map_targets.py", "examples": [ { "command": "python3 tools/check_map_targets.py --suite reports/eval_suite.json --targets baselines/yolo26_targets.json --key map50_95", "description": "Gate a suite run vs targets." } ], "id": "check_map_targets", "inputs": [ { "default": "reports/eval_suite.json", "flag": "--suite", "kind": "file", "name": "suite", "required": false }, { "default": "baselines/yolo26_targets.json", "flag": "--targets", "kind": "file", "name": "targets", "required": false }, { "flag": "--key", "kind": "string", "name": "key", "required": false }, { "flag": "--min-delta", "kind": "number", "name": "min_delta", "required": false } ], "maturity": "stable", "outputs": [ { "description": "JSON report with ok/failures.", "kind": "stdout", "name": "stdout" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Compare eval_suite results against a target table and exit non-zero on failure.", "tags": [ "eval", "targets", "gates", "yolo26" ] }, { "docs": [ "docs/llm_integrations.md", "docs/tools_index.md", "manual/chapters/20_llm_mcp_integrations.tex", "docs/generated/mcp_actions_tool_reference.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes MCP settings audit report JSON.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/check_mcp_settings.py", "examples": [ { "command": "python3 tools/check_mcp_settings.py --output reports/mcp_settings_check.json", "description": "Run MCP settings checks against manifest and generated integration references." }, { "command": "python3 tools/check_mcp_settings.py --strict --output reports/mcp_settings_check.strict.json", "description": "Strict mode: treat warnings as failures." } ], "id": "check_mcp_settings", "inputs": [ { "default": "tools/manifest.json", "flag": "--manifest", "kind": "file", "name": "manifest", "required": false }, { "default": "docs/generated/mcp_actions_tool_reference.json", "flag": "--json-ref", "kind": "file", "name": "json_ref", "required": false }, { "default": "docs/generated/mcp_actions_tool_reference.md", "flag": "--md-ref", "kind": "file", "name": "md_ref", "required": false }, { "default": "reports/mcp_settings_check.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/mcp_settings_check.json", "description": "MCP settings audit report.", "kind": "file", "name": "mcp_settings_check_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Audit MCP settings by checking manifest alignment and generated MCP/Actions reference freshness.", "tags": [ "mcp", "integration", "validation", "docs" ] }, { "contracts": { "consumes": [ "predictions_json" ] }, "docs": [ "docs/onnx_export_parity.md" ], "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "tools/check_predictions_parity.py", "examples": [ { "command": "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", "description": "Parity check without reading image files (fixed image size)." } ], "id": "check_predictions_parity", "inputs": [ { "flag": "--reference", "kind": "file", "name": "reference", "required": true }, { "flag": "--candidate", "kind": "file", "name": "candidate", "required": true }, { "default": "auto", "description": "BBox format in both prediction artifacts: auto, cxcywh_norm, cxcywh_abs, xywh_abs, or xyxy_abs.", "flag": "--bbox-format", "kind": "string", "name": "bbox_format", "required": false }, { "flag": "--image-size", "kind": "string", "name": "image_size", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--iou-thresh", "kind": "number", "name": "iou_thresh", "required": false }, { "flag": "--score-atol", "kind": "number", "name": "score_atol", "required": false }, { "flag": "--bbox-atol", "kind": "number", "name": "bbox_atol", "required": false } ], "maturity": "experimental", "outputs": [ { "description": "Mismatch report (JSON/text) and exit status.", "kind": "stdout", "name": "stdout" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Compare two prediction JSONs and report mismatches (IoU/tolerance-based).", "tags": [ "predictions", "parity" ] }, { "contracts": { "consumes": [ "algorithm_bundle_registry_json", "bundle_lifecycle_record_json", "evidence_activation_record_json", "qualification_report_json" ], "produces": [ "qualification_freshness_report_json", "managed_output_checksums_json" ] }, "docs": [ "docs/adaptive_image_routing.md", "docs/qualification_freshness.md", "docs/schemas/qualification_freshness_report.schema.json", "manual/chapters/04_cli_reference.tex", "reports/adaptive_qualification_freshness_foundation_2026-08-29.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Only with --output, atomically publish one aggregate freshness report and checksum manifest inside the workspace.", "flag": "--output", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/check_qualification_freshness.py", "examples": [ { "command": "python3 tools/check_qualification_freshness.py", "description": "Read the packaged public activation state and print a no-write aggregate freshness report." }, { "command": "python3 tools/check_qualification_freshness.py --evidence-root site/evidence --output reports/qualification_freshness", "description": "Write one site-confined local-only report without uploading, notifying, or mutating Beads." }, { "command": "python3 tools/check_qualification_freshness.py --help", "description": "Inspect the read-only freshness monitor interface contract." } ], "id": "check_qualification_freshness", "inputs": [ { "flag": "--evidence-root", "kind": "dir", "name": "evidence_root", "required": false }, { "flag": "--registry-root", "kind": "dir", "name": "registry_root", "required": false }, { "flag": "--as-of", "kind": "string", "name": "as_of", "required": false }, { "flag": "--missed-run-date", "kind": "string", "name": "missed_run_date", "required": false }, { "flag": "--output", "kind": "dir", "name": "output", "required": false }, { "default": ".", "flag": "--workspace", "kind": "dir", "name": "workspace", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "stdout or /qualification_freshness_report.json", "description": "Aggregate public-ID or site-local expiry/drift rows with explicit unknown/conflict states and no raw telemetry.", "kind": "file", "name": "qualification_freshness_report" }, { "default": "/checksums.json when --output is used", "description": "Code-owned checksum manifest for the managed report.", "kind": "file", "name": "checksums" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false }, "runner": "python3", "summary": "Warn on active qualification expiry and governed drift without qualification, extension, activation, promotion, external notice, or Beads mutation.", "tags": [ "adaptive-inference", "automation", "evidence", "qualification" ] }, { "docs": [ "docs/repo_governance_audit.md", "docs/security_scorecard_governance.md", "docs/release_reliability_checklist.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Write the governance audit JSON report.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/check_repo_governance.py", "examples": [ { "command": "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", "description": "Run a full governance audit from exported GitHub settings snapshots." }, { "command": "python3 tools/check_repo_governance.py --repo-root . --allow-missing-evidence --output reports/repo_governance_check.local.json", "description": "Inspect local workflow/docs evidence only and treat missing snapshots as informational." } ], "id": "check_repo_governance", "inputs": [ { "default": ".", "flag": "--repo-root", "kind": "dir", "name": "repo_root", "required": false }, { "flag": "--repo-json", "kind": "file", "name": "repo_json", "required": false }, { "flag": "--branch-protection-json", "kind": "file", "name": "branch_protection_json", "required": false }, { "default": 1, "flag": "--require-reviews", "kind": "number", "name": "require_reviews", "required": false }, { "default": false, "flag": "--allow-missing-evidence", "kind": "string", "name": "allow_missing_evidence", "required": false }, { "default": "reports/repo_governance_check.json", "flag": "--output", "kind": "file", "name": "output", "required": false } ], "maturity": "stable", "outputs": [ { "description": "JSON report containing required checks, advisory checks, missing evidence, and manual followups.", "kind": "json", "name": "governance_report_json", "path": "reports/repo_governance_check.json" }, { "description": "One-line status summary plus failed check identifiers when the audit does not pass.", "kind": "stdout", "name": "stdout" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Audit repository governance posture from local workflow evidence and exported GitHub settings snapshots.", "tags": [ "security", "governance", "repo-policy" ] }, { "docs": [ "docs/versions.md", "docs/labeled_sample.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Creates a new report directory with logs, generated labeled samples, relocated copies, and COCO evaluation reports; refuses an existing output directory.", "flag": "--output-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/ci/check_sample_compatibility.py", "examples": [ { "command": "python3 tools/ci/check_sample_compatibility.py --wheel /path/to/yolozu-candidate.whl --output-dir reports/sample_compatibility", "description": "Check an already installed non-editable candidate wheel and its coco extra through sample generation, strict validation, and evaluation after relocation." } ], "id": "check_sample_compatibility", "inputs": [ { "description": "Exact candidate wheel already installed in the invoking interpreter.", "flag": "--wheel", "kind": "file", "name": "wheel", "required": true }, { "description": "New output directory; existing paths are never overwritten.", "flag": "--output-dir", "kind": "dir", "name": "output_dir", "required": true }, { "description": "Source Git revision used to build the candidate wheel.", "flag": "--source-revision", "kind": "string", "name": "source_revision", "required": false } ], "maturity": "experimental", "outputs": [ { "default": null, "description": "compatibility-report.json, command logs, samples, and COCO reports under --output-dir.", "kind": "dir", "name": "compatibility_evidence" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "yolozu", "pip", "pycocotools" ] }, "runner": "python3", "summary": "Verify installed candidate-wheel identity, dependency consistency, and labeled-sample evaluation before and after relocation.", "tags": [ "compatibility", "installation", "evaluation" ] }, { "contracts": { "consumes": [ "predictions_json" ] }, "docs": [ "docs/interop_detectron2_mmdet.md", "docs/tools_index.md", "docs/training_inference_export.md", "manual/chapters/04_cli_reference.tex", "manual/chapters/07_training_run_contract.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes segmentation parity JSON report.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/check_segmentation_parity.py", "examples": [ { "command": "python3 tools/check_segmentation_parity.py --reference reports/segmentation_predictions_ref.json --candidate reports/segmentation_predictions_cand.json --output reports/segmentation_parity.json", "description": "Compare two segmentation predictions artifacts and write a parity report." } ], "id": "check_segmentation_parity", "inputs": [ { "flag": "--reference", "kind": "file", "name": "reference", "required": true }, { "flag": "--candidate", "kind": "file", "name": "candidate", "required": true }, { "flag": "--mismatch-atol", "kind": "number", "name": "mismatch_atol", "required": false }, { "flag": "--max-samples", "kind": "number", "name": "max_samples", "required": false }, { "flag": "--output", "kind": "file", "name": "output", "required": false } ], "maturity": "experimental", "outputs": [ { "default": null, "description": "Segmentation parity report JSON.", "kind": "file", "name": "segmentation_parity_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Compare two segmentation predictions artifacts and report mask-level parity mismatches.", "tags": [ "segmentation", "parity", "evaluation" ] }, { "contract_outputs": { "continual_promotion_decision_json": "continual_promotion_decision_json" }, "contracts": { "produces": [ "continual_promotion_decision_json" ] }, "docs": [ "docs/continual_learning.md", "docs/tools_index.md", "manual/chapters/14_continual_learning.tex", "docs/production_readiness.md", "docs/research_lanes.md", "docs/schemas/research_lane_report.schema.json" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes promotion decision JSON report.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/continual_decide.py", "examples": [ { "command": "python3 tools/continual_decide.py --eval-json runs/continual//continual_eval.json --run-json runs/continual//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", "description": "Decide whether a continual-learning checkpoint should be promoted, reviewed, or held." } ], "id": "continual_decide", "inputs": [ { "flag": "--eval-json", "kind": "file", "name": "eval_json", "required": true }, { "flag": "--curation-json", "kind": "file", "name": "curation_json", "required": false }, { "flag": "--run-json", "kind": "file", "name": "run_json", "required": false }, { "flag": "--max-forgetting", "kind": "number", "name": "max_forgetting", "required": false }, { "flag": "--min-avg-acc", "kind": "number", "name": "min_avg_acc", "required": false }, { "flag": "--min-new-task-score", "kind": "number", "name": "min_new_task_score", "required": false }, { "flag": "--min-old-task-final", "kind": "number", "name": "min_old_task_final", "required": false }, { "flag": "--min-reviewed-labels", "kind": "number", "name": "min_reviewed_labels", "required": false }, { "flag": "--min-highconf-pseudo-labels", "kind": "number", "name": "min_highconf_pseudo_labels", "required": false }, { "flag": "--min-total-curated-examples", "kind": "number", "name": "min_total_curated_examples", "required": false }, { "flag": "--max-candidate-share", "kind": "number", "name": "max_candidate_share", "required": false }, { "flag": "--ttt-active", "kind": "string", "name": "ttt_active", "required": false }, { "flag": "--allow-ttt-active-promotion", "kind": "string", "name": "allow_ttt_active_promotion", "required": false }, { "flag": "--output", "kind": "file", "name": "output", "required": false } ], "maturity": "research", "outputs": [ { "default": null, "description": "Promotion decision JSON report including research_report latency/rollback/promotion-gate boundary fields.", "kind": "file", "name": "continual_promotion_decision_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Device-agnostic policy gate for continual-learning eval results that emits a promote/review/hold decision report with a research_report boundary.", "tags": [ "continual", "promotion", "gate", "automation" ] }, { "contracts": { "produces": [ "instance_segmentation_predictions_json" ] }, "effects": { "fixed_writes": [], "writes": [ { "description": "Writes instance segmentation predictions JSON.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Writes per-instance PNG masks under --masks-dir.", "flag": "--masks-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/convert_coco_instance_seg_predictions.py", "examples": [ { "command": "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", "description": "Convert COCO predictions to YOLOZU PNG masks (pycocotools required)." } ], "id": "convert_coco_instance_seg_predictions", "inputs": [ { "flag": "--predictions", "kind": "file", "name": "predictions", "required": true }, { "flag": "--instances-json", "kind": "file", "name": "instances_json", "required": true }, { "default": "reports/instance_seg_predictions.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "default": "reports/instance_seg_masks", "flag": "--masks-dir", "kind": "dir", "name": "masks_dir", "required": false }, { "flag": "--min-score", "kind": "number", "name": "min_score", "required": false }, { "flag": "--max-preds", "kind": "number", "name": "max_preds", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/instance_seg_predictions.json", "description": "Predictions JSON artifact.", "kind": "file", "name": "predictions_json" }, { "default": "reports/instance_seg_masks", "description": "Masks directory artifact.", "kind": "dir", "name": "masks_dir" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Convert COCO instance segmentation predictions (polygons/RLE) into the YOLOZU instance-seg PNG-mask interface contract.", "tags": [ "coco", "instance_segmentation", "predictions", "convert" ] }, { "contracts": { "consumes": [ "predictions_json" ], "produces": [ "predictions_json", "metrics_report_json", "research_lane_report_json" ] }, "docs": [ "docs/distillation.md", "docs/learning_features.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes the distilled predictions JSON artifact.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Writes metrics, measured latency, artifact hashes, rollback, and promotion boundary.", "flag": "--output-report", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/distill_predictions.py", "examples": [ { "command": "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", "description": "Recommended short path: use the checked-in YAML boilerplate for offline prediction distillation." }, { "command": "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", "description": "Explicit exploratory path: allow guarded teacher-only injection for fast ablations." } ], "id": "distill_predictions", "inputs": [ { "flag": "--student", "kind": "file", "name": "student", "required": true }, { "flag": "--teacher", "kind": "file", "name": "teacher", "required": true }, { "description": "Optional JSON/YAML config for distillation parameters.", "flag": "--config", "kind": "file", "name": "config", "required": false }, { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": false }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--alpha", "kind": "number", "name": "alpha", "required": false }, { "flag": "--iou-threshold", "kind": "number", "name": "iou_threshold", "required": false }, { "flag": "--add-missing", "kind": "string", "name": "add_missing", "required": false }, { "flag": "--add-score-scale", "kind": "number", "name": "add_score_scale", "required": false }, { "default": 0.0, "flag": "--teacher-min-score", "kind": "number", "name": "teacher_min_score", "required": false }, { "flag": "--max-added-per-image", "kind": "number", "name": "max_added_per_image", "required": false }, { "default": 0.9, "flag": "--add-duplicate-iou-threshold", "kind": "number", "name": "add_duplicate_iou_threshold", "required": false }, { "default": "reports/predictions_distilled.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "default": "reports/distill_report.json", "flag": "--output-report", "kind": "file", "name": "output_report", "required": false } ], "maturity": "research", "outputs": [ { "default": "reports/predictions_distilled.json", "description": "Distilled predictions artifact.", "kind": "file", "name": "predictions_distilled" }, { "default": "reports/distill_report.json", "description": "Distillation report artifact.", "kind": "file", "name": "report_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "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.", "tags": [ "predictions", "distillation", "offline" ] }, { "docs": [ "docs/cpu_only_dod.md", "README.md", "Readme_jp.md", "manual/chapters/02_installation.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes doctor proof, demo, validation, eval, and DoD summary artifacts.", "flag": "--run-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "scripts/dod_cpu_smoke.sh", "examples": [ { "command": "bash scripts/dod_cpu_smoke.sh", "description": "Run the CPU-only DoD preflight from a repo checkout." }, { "command": "bash scripts/dod_cpu_smoke.sh --run-dir /tmp/yolozu_dod_cpu_smoke", "description": "Write DoD artifacts to a temporary run directory." }, { "command": "YOLOZU_PYTHON=/path/to/venv/bin/python bash scripts/dod_cpu_smoke.sh --installed-package --run-dir /tmp/yolozu_dod_cpu_smoke", "description": "Run the DoD against an installed package without source-checkout imports." }, { "command": "bash scripts/dod_cpu_smoke.sh --help", "description": "Show DoD smoke options." } ], "id": "dod_cpu_smoke", "inputs": [ { "default": "reports/dod_cpu_smoke", "flag": "--run-dir", "kind": "dir", "name": "run_dir", "required": false }, { "default": "val2017", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "default": false, "description": "Use the installed yolozu package without adding the repository to PYTHONPATH.", "flag": "--installed-package", "kind": "string", "name": "installed_package", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/dod_cpu_smoke/dod_cpu_smoke_report.json", "description": "CPU-only DoD smoke summary report.", "kind": "file", "name": "dod_report" }, { "default": "reports/dod_cpu_smoke/doctor.json", "description": "Doctor report from the proof run.", "kind": "file", "name": "doctor_report" }, { "default": "reports/dod_cpu_smoke/doctor_proof/proof_report.json", "description": "Doctor proof report with dataset and predictions artifact paths.", "kind": "file", "name": "proof_report" }, { "default": "reports/dod_cpu_smoke/demo_instance_seg/instance_seg_demo_report.json", "description": "Instance-seg demo report.", "kind": "file", "name": "demo_report" }, { "default": "reports/dod_cpu_smoke/eval_coco_dry_run.json", "description": "Evaluation dry-run report for proof predictions.", "kind": "file", "name": "eval_report" }, { "default": "reports/dod_cpu_smoke/steps.jsonl", "description": "Exact commands, exit codes, elapsed times, and output-log paths.", "kind": "file", "name": "steps" }, { "default": "reports/dod_cpu_smoke/logs", "description": "Combined stdout and stderr for each stable-lane step.", "kind": "dir", "name": "logs" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false }, "runner": "bash", "summary": "Run and time the CPU-only public DoD path: doctor proof, demo, validation, and eval dry-run.", "tags": [ "dod", "smoke", "evaluation", "cpu" ] }, { "contract_outputs": { "bop_download_manifest_json": "download_manifest_json" }, "contracts": { "produces": [ "bop_download_manifest_json" ] }, "docs": [ "docs/bop_tless_protocol.md", "docs/dataset_processing_matrix.md", "reports/bop_pose_readiness_2026-07-28.md", "reports/bop_tless_evidence_2026-07-30.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes extracted BOP archives and download_manifest.json under --out after validating all ZIP members.", "flag": "--out", "kind": "dir", "scope": "tree" }, { "description": "Writes or reuses downloaded ZIP archives under --cache when explicitly supplied.", "flag": "--cache", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/download_bop_dataset.py", "examples": [ { "command": "python3 tools/download_bop_dataset.py --dataset tless --out reports/bop", "description": "Download the fixed T-LESS base, models, and train_primesense archives, validate extraction paths, and write provenance." }, { "command": "python3 tools/download_bop_dataset.py --help", "description": "Show network, cache, archive, and output options before execution." } ], "id": "download_bop_dataset", "inputs": [ { "description": "BOP dataset id under the fixed bop-benchmark Hugging Face namespace.", "flag": "--dataset", "kind": "string", "name": "dataset", "required": true }, { "default": null, "description": "Optional comma-separated plain ZIP filenames overriding the dataset defaults.", "flag": "--archives", "kind": "string", "name": "archives", "required": false }, { "description": "Destination root for extracted archives and download_manifest.json.", "flag": "--out", "kind": "dir", "name": "out", "required": true }, { "default": null, "description": "Optional ZIP cache; defaults to /zips.", "flag": "--cache", "kind": "dir", "name": "cache", "required": false }, { "description": "Re-download and re-extract archives.", "flag": "--force", "kind": "string", "name": "force", "required": false }, { "description": "Allow quota-interrupted partial extraction for smoke work; never use as completed dataset evidence.", "flag": "--allow-partial-extract", "kind": "string", "name": "allow_partial_extract", "required": false } ], "maturity": "research", "outputs": [ { "default": null, "description": "Extracted BOP dataset root created at --out.", "kind": "dir", "name": "dataset_root" }, { "default": "/zips", "description": "Downloaded archive cache, or the path supplied by --cache.", "kind": "dir", "name": "archive_cache" }, { "default": "/download_manifest.json", "description": "Archive provenance, hashes, byte sizes, and dataset license record.", "kind": "file", "name": "download_manifest_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": true }, "runner": "python3", "summary": "Safely download fixed-host BOP archives and record hashes, byte sizes, URLs, and license provenance.", "tags": [ "dataset", "bop", "tless", "pose6d", "provenance" ] }, { "docs": [ "docs/install.md", "docs/proof_onepager.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes a minimal COCO layout under /annotations and /images/ for demos.", "flag": "--out-root", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "scripts/download_coco_instances_tiny.py", "examples": [ { "command": "python3 scripts/download_coco_instances_tiny.py", "description": "Download the default tiny subset (2 images) under data/coco." }, { "command": "python3 scripts/download_coco_instances_tiny.py --help", "description": "Show CLI options." } ], "id": "download_coco_instances_tiny", "inputs": [ { "default": "data/coco", "description": "Output COCO root (writes annotations/ + images/ under this root).", "flag": "--out-root", "kind": "string", "name": "out_root", "required": false }, { "default": "val2017", "description": "COCO split name.", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "default": 2, "description": "How many images to download (default: 2).", "flag": "--num-images", "kind": "number", "name": "num_images", "required": false }, { "default": 0, "description": "Shuffle seed for selecting images.", "flag": "--seed", "kind": "number", "name": "seed", "required": false }, { "default": 60, "description": "HTTP timeout seconds.", "flag": "--timeout", "kind": "number", "name": "timeout", "required": false }, { "description": "Overwrite existing subset JSON and images.", "flag": "--force", "kind": "string", "name": "force", "required": false }, { "description": "Keep the downloaded annotations zip.", "flag": "--keep-zip", "kind": "string", "name": "keep_zip", "required": false } ], "maturity": "stable", "outputs": [ { "default": "data/coco", "description": "Created COCO root containing annotations + images.", "kind": "dir", "name": "dataset_root" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": true }, "runner": "python3", "summary": "Download a tiny COCO instances (polygon) subset (2 images by default) for `yolozu demo instance-seg` without bundling images in git.", "tags": [ "dataset", "coco", "demo", "instance_seg" ] }, { "contract_outputs": { "coco_eval_report_json": "coco_eval_json" }, "contracts": { "consumes": [ "predictions_json" ], "produces": [ "coco_eval_report_json" ] }, "docs": [ "docs/external_inference.md", "docs/python_api.md", "docs/predictions_schema.md", "docs/production_readiness.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Atomically writes a status=ok COCO report or replaces stale success evidence with a status=failed report.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/eval_coco.py", "examples": [ { "command": "python3 tools/eval_coco.py -d data/coco128 -p reports/predictions.json --dry-run -o reports/coco_eval_dry.json", "description": "Strict dry-run validation and conversion without pycocotools." }, { "command": "python3 tools/eval_coco.py -d data/coco128 -p reports/legacy_predictions.json --dry-run -r -o reports/coco_eval_repaired.json", "description": "Explicitly repair legacy ranges and record every repair in warnings." } ], "id": "eval_coco", "inputs": [ { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--predictions", "kind": "file", "name": "predictions", "required": true }, { "default": "reports/coco_eval.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--protocol", "kind": "string", "name": "protocol", "required": false }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--bbox-format", "kind": "string", "name": "bbox_format", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "flag": "--repair", "kind": "string", "name": "repair", "required": false }, { "flag": "--classes", "kind": "file", "name": "classes", "required": false }, { "flag": "--assume-class-id-is-category-id", "kind": "string", "name": "assume_class_id_is_category_id", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/coco_eval.json", "description": "Strict COCO evaluation JSON artifact with status, validation mode, subset counts, warnings, and structured failure details.", "kind": "file", "name": "coco_eval_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "notes": "Required for real COCOeval only; --dry-run performs strict validation/conversion without pycocotools.", "python_packages": [ "pycocotools" ] }, "runner": "python3", "summary": "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.", "tags": [ "coco", "data.yaml", "eval", "yolo" ] }, { "docs": [ "docs/continual_learning.md", "docs/production_readiness.md" ], "effects": { "fixed_writes": [ { "description": "Default outputs are written next to the run dir when using standard runs/continual locations.", "kind": "dir", "path": "runs/continual", "scope": "tree" } ], "writes": [ { "description": "Optional explicit JSON output path.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Optional explicit HTML output path.", "flag": "--html", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/eval_continual.py", "examples": [ { "command": "python3 tools/eval_continual.py --run-json runs/continual//continual_run.json --device cpu --metric coco --metric-key map50_95 --max-images 50", "description": "Evaluate with the real pycocotools COCOeval backend and initial-checkpoint FWT baseline." }, { "command": "python3 tools/eval_continual.py --run-json runs/continual//continual_run.json --device cpu --max-images 50", "description": "Evaluate and summarize forgetting." }, { "command": "python3 tools/eval_continual.py --run-json runs/continual//continual_run.json --device mps --max-images 50", "description": "Evaluate on macOS with MPS when torch reports mps_available=true." }, { "command": "python3 tools/eval_continual.py --run-json runs/continual//continual_run.json --device cpu --max-images 50 --metric pose --metric-key pose_success", "description": "Pose-mode evaluation (requires pose sidecar metadata in labels)." } ], "id": "eval_continual", "inputs": [ { "flag": "--run-json", "kind": "file", "name": "run_json", "required": true }, { "flag": "--device", "kind": "string", "name": "device", "required": false }, { "flag": "--metric", "kind": "string", "name": "metric", "required": false }, { "flag": "--metric-key", "kind": "string", "name": "metric_key", "required": false }, { "flag": "--image-size", "kind": "string", "name": "image_size", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--iou-threshold", "kind": "number", "name": "iou_threshold", "required": false }, { "flag": "--min-score", "kind": "number", "name": "min_score", "required": false }, { "flag": "--keep-per-image", "kind": "number", "name": "keep_per_image", "required": false }, { "flag": "--baseline-checkpoint", "kind": "file", "name": "baseline_checkpoint", "required": false }, { "flag": "--success-trans", "kind": "number", "name": "success_trans", "required": false }, { "flag": "--success-rot-deg", "kind": "number", "name": "success_rot_deg", "required": false }, { "flag": "--force", "kind": "string", "name": "force", "required": false }, { "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--html", "kind": "file", "name": "html", "required": false } ], "maturity": "research", "outputs": [ { "default": null, "description": "/continual_eval.json by default.", "kind": "file", "name": "eval_json" }, { "default": null, "description": "/continual_eval.html by default.", "kind": "file", "name": "eval_html" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "notes": "pycocotools is required only for --metric coco; simple_map and pose use repository evaluators.", "python_packages": [ "torch", "Pillow", "pycocotools" ] }, "runner": "python3", "summary": "Evaluate a continual learning run with real COCOeval, simple mAP proxy, or pose metrics; define FWT only from an explicit initial-checkpoint baseline; and write hash-bound JSON+HTML.", "tags": [ "continual", "eval", "report", "forgetting" ] }, { "contracts": { "consumes": [ "predictions_json" ] }, "docs": [ "docs/cotta_design_spec.md", "docs/cotta_validation.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes CoTTA drift validation JSON evidence artifact.", "flag": "--output-json", "kind": "file", "scope": "path" }, { "description": "Writes CoTTA drift validation Markdown summary.", "flag": "--output-md", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/eval_cotta_drift.py", "examples": [ { "command": "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", "description": "Compare baseline and CoTTA wrapped predictions as a non-promoting local drift diagnostic." } ], "id": "eval_cotta_drift", "inputs": [ { "description": "Wrapped predictions JSON for baseline TTT run.", "flag": "--baseline", "kind": "file", "name": "baseline", "required": true }, { "description": "Wrapped predictions JSON for CoTTA run.", "flag": "--cotta", "kind": "file", "name": "cotta", "required": true }, { "default": "reports/cotta_drift_report.json", "flag": "--output-json", "kind": "file", "name": "output_json", "required": false }, { "default": "reports/cotta_drift_report.md", "flag": "--output-md", "kind": "file", "name": "output_md", "required": false }, { "default": 1.0, "flag": "--stability-loss-ratio-threshold", "kind": "number", "name": "stability_loss_ratio_threshold", "required": false }, { "default": 5.0, "flag": "--max-safe-total-update-norm", "kind": "number", "name": "max_safe_total_update_norm", "required": false } ], "maturity": "research", "outputs": [ { "default": "reports/cotta_drift_report.json", "description": "CoTTA drift report JSON artifact.", "kind": "file", "name": "cotta_drift_report_json" }, { "default": "reports/cotta_drift_report.md", "description": "CoTTA drift report Markdown artifact.", "kind": "file", "name": "cotta_drift_report_md" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Compare baseline-vs-CoTTA TTT reports and generate reproducible drift/stability evidence artifacts (JSON+Markdown).", "tags": [ "tta", "cotta", "drift", "validation", "report" ] }, { "docs": [ "docs/tools_index.md", "docs/benchmark_mode_spec_parity_target.md", "manual/chapters/16_depth_6dof_symmetry.tex", "docs/production_readiness.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes one depth evaluation report JSON.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/eval_depth.py", "examples": [ { "command": "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", "description": "Evaluate one relative-depth prediction against one ground-truth map with median-scale alignment." }, { "command": "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", "description": "Evaluate only valid pixels when a task-specific mask is available." } ], "id": "eval_depth", "inputs": [ { "flag": "--pred-depth", "kind": "file", "name": "pred_depth", "required": true }, { "flag": "--gt-depth", "kind": "file", "name": "gt_depth", "required": true }, { "flag": "--mask", "kind": "file", "name": "mask", "required": false }, { "default": "median_scale", "flag": "--align", "kind": "string", "name": "align", "required": false }, { "default": 1.0, "flag": "--pred-scale", "kind": "number", "name": "pred_scale", "required": false }, { "default": 1.0, "flag": "--gt-scale", "kind": "number", "name": "gt_scale", "required": false }, { "default": 1e-06, "flag": "--min-depth", "kind": "number", "name": "min_depth", "required": false }, { "flag": "--max-depth", "kind": "number", "name": "max_depth", "required": false }, { "default": "reports/depth_eval.json", "flag": "--output", "kind": "file", "name": "output", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/depth_eval.json", "description": "Depth evaluation report with depth_error metrics.", "kind": "file", "name": "report_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Evaluate one predicted depth map against one ground-truth map and report depth_error metrics.", "tags": [ "depth", "evaluation", "metrics", "geometry" ] }, { "contract_outputs": { "instance_seg_eval_report_json": "instance_seg_eval_json" }, "contracts": { "consumes": [ "instance_segmentation_predictions_json" ], "produces": [ "instance_seg_eval_report_json" ] }, "effects": { "fixed_writes": [], "writes": [ { "description": "Writes instance segmentation evaluation JSON report.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Optional HTML report output.", "flag": "--html", "kind": "file", "scope": "path" }, { "description": "Optional overlay image outputs.", "flag": "--overlays-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/eval_instance_segmentation.py", "examples": [ { "command": "python3 tools/eval_instance_segmentation.py --dataset data/coco-yolo --predictions reports/instance_seg_predictions.json --output reports/instance_seg_eval.json", "description": "Evaluate instance segmentation predictions and write a JSON report." } ], "id": "eval_instance_segmentation", "inputs": [ { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--predictions", "kind": "file", "name": "predictions", "required": true }, { "default": "reports/instance_seg_eval.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "default": null, "flag": "--html", "kind": "file", "name": "html", "required": false }, { "default": null, "flag": "--overlays-dir", "kind": "dir", "name": "overlays_dir", "required": false }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--title", "kind": "string", "name": "title", "required": false }, { "flag": "--pred-root", "kind": "dir", "name": "pred_root", "required": false }, { "flag": "--classes", "kind": "file", "name": "classes", "required": false }, { "flag": "--allow-rgb-masks", "kind": "string", "name": "allow_rgb_masks", "required": false }, { "flag": "--diag-iou", "kind": "number", "name": "diag_iou", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--min-score", "kind": "number", "name": "min_score", "required": false }, { "flag": "--per-image-limit", "kind": "number", "name": "per_image_limit", "required": false }, { "flag": "--max-overlays", "kind": "number", "name": "max_overlays", "required": false }, { "flag": "--overlay-alpha", "kind": "number", "name": "overlay_alpha", "required": false }, { "flag": "--overlay-max-size", "kind": "number", "name": "overlay_max_size", "required": false }, { "flag": "--overlay-sort", "kind": "string", "name": "overlay_sort", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/instance_seg_eval.json", "description": "Instance segmentation evaluation JSON artifact.", "kind": "file", "name": "instance_seg_eval_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Evaluate instance segmentation predictions (mask mAP) from binary PNG masks with optional HTML/overlays.", "tags": [ "eval", "instance_segmentation", "segmentation" ] }, { "contracts": { "consumes": [ "predictions_json" ], "produces": [ "metrics_report_json" ] }, "effects": { "fixed_writes": [], "writes": [ { "description": "Writes keypoints evaluation JSON report.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Optional HTML report output.", "flag": "--html", "kind": "file", "scope": "path" }, { "description": "Optional overlay image outputs.", "flag": "--overlays-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/eval_keypoints.py", "examples": [ { "command": "python3 tools/eval_keypoints.py --dataset data/coco128 --predictions reports/predictions.json --output reports/keypoints_eval.json", "description": "Evaluate keypoint predictions and write a JSON report." }, { "command": "python3 tools/eval_keypoints.py --dataset data/coco128 --predictions reports/predictions.json --oks --output reports/keypoints_eval_oks.json", "description": "Evaluate keypoints with COCO OKS mAP (requires pycocotools)." } ], "id": "eval_keypoints", "inputs": [ { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--predictions", "kind": "file", "name": "predictions", "required": true }, { "default": "reports/keypoints_eval.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "default": null, "flag": "--html", "kind": "file", "name": "html", "required": false }, { "default": null, "flag": "--overlays-dir", "kind": "dir", "name": "overlays_dir", "required": false }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--title", "kind": "string", "name": "title", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--min-score", "kind": "number", "name": "min_score", "required": false }, { "flag": "--per-image-limit", "kind": "number", "name": "per_image_limit", "required": false }, { "flag": "--pck-threshold", "kind": "number", "name": "pck_threshold", "required": false }, { "flag": "--iou-threshold", "kind": "number", "name": "iou_threshold", "required": false }, { "flag": "--oks", "kind": "string", "name": "oks", "required": false }, { "flag": "--oks-max-dets", "kind": "number", "name": "oks_max_dets", "required": false }, { "flag": "--oks-sigmas", "kind": "string", "name": "oks_sigmas", "required": false }, { "flag": "--oks-sigmas-file", "kind": "file", "name": "oks_sigmas_file", "required": false }, { "flag": "--kp-line", "kind": "number", "name": "kp_line", "required": false }, { "flag": "--kp-radius", "kind": "number", "name": "kp_radius", "required": false }, { "flag": "--max-overlays", "kind": "number", "name": "max_overlays", "required": false }, { "flag": "--overlay-max-size", "kind": "number", "name": "overlay_max_size", "required": false }, { "flag": "--overlay-sort", "kind": "string", "name": "overlay_sort", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/keypoints_eval.json", "description": "Keypoints evaluation JSON artifact.", "kind": "file", "name": "keypoints_eval_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Evaluate keypoint predictions using PCK (bbox-normalized distance) with optional COCO OKS mAP, HTML, and overlays.", "tags": [ "eval", "keypoints", "pose" ] }, { "docs": [ "docs/tools_index.md", "manual/chapters/16_depth_6dof_symmetry.tex", "docs/continual_learning.md", "docs/production_readiness.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes one pose evaluation report JSON.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/eval_pose.py", "examples": [ { "command": "python3 tools/eval_pose.py --dataset /path/to/yolo_pose_dataset --predictions reports/predictions_pose.json --output reports/pose_eval.json", "description": "Evaluate one pose-aware predictions artifact against dataset sidecars and write a JSON report." }, { "command": "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", "description": "Apply explicit IoU / rotation / translation thresholds when scoring 6DoF pose predictions." } ], "id": "eval_pose", "inputs": [ { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--predictions", "kind": "file", "name": "predictions", "required": true }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "default": "reports/pose_eval.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "default": 0.5, "flag": "--iou-threshold", "kind": "number", "name": "iou_threshold", "required": false }, { "default": 0.0, "flag": "--min-score", "kind": "number", "name": "min_score", "required": false }, { "default": 15.0, "flag": "--success-rot-deg", "kind": "number", "name": "success_rot_deg", "required": false }, { "default": 0.1, "flag": "--success-trans", "kind": "number", "name": "success_trans", "required": false }, { "default": 0, "flag": "--keep-per-image", "kind": "number", "name": "keep_per_image", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/pose_eval.json", "description": "Pose evaluation report with pose6d_error metrics, pose_success, and optional ADD/ADDS metrics.", "kind": "file", "name": "report_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Evaluate one pose-aware predictions artifact against dataset sidecars and report pose6d_error metrics, success rates, and optional CAD-point metrics.", "tags": [ "pose6d", "evaluation", "metrics", "geometry" ] }, { "contract_outputs": { "seg_eval_report_json": "seg_eval_json" }, "contracts": { "consumes": [ "seg_dataset_json", "segmentation_predictions_json" ], "produces": [ "seg_eval_report_json" ] }, "effects": { "fixed_writes": [], "writes": [ { "description": "Writes segmentation evaluation JSON report.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Optional HTML report output.", "flag": "--html", "kind": "file", "scope": "path" }, { "description": "Optional overlay image outputs.", "flag": "--overlays-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/eval_segmentation.py", "examples": [ { "command": "python3 tools/eval_segmentation.py --dataset-json data/cityscapes_seg/dataset.json --predictions reports/seg_predictions.json --output reports/seg_eval.json", "description": "Evaluate segmentation predictions and write a JSON report." } ], "id": "eval_segmentation", "inputs": [ { "flag": "--dataset-json", "kind": "file", "name": "dataset_json", "required": true }, { "flag": "--predictions", "kind": "file", "name": "predictions", "required": true }, { "default": "reports/seg_eval.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--html", "kind": "file", "name": "html", "required": false }, { "flag": "--overlays-dir", "kind": "dir", "name": "overlays_dir", "required": false }, { "flag": "--overlay-alpha", "kind": "number", "name": "overlay_alpha", "required": false }, { "flag": "--overlay-max-size", "kind": "number", "name": "overlay_max_size", "required": false }, { "flag": "--max-overlays", "kind": "number", "name": "max_overlays", "required": false }, { "flag": "--pred-root", "kind": "dir", "name": "pred_root", "required": false }, { "flag": "--ignore-index", "kind": "number", "name": "ignore_index", "required": false }, { "flag": "--num-classes", "kind": "number", "name": "num_classes", "required": false }, { "flag": "--max-samples", "kind": "number", "name": "max_samples", "required": false }, { "flag": "--allow-gt-out-of-range", "kind": "string", "name": "allow_gt_out_of_range", "required": false }, { "flag": "--allow-rgb-masks", "kind": "string", "name": "allow_rgb_masks", "required": false }, { "flag": "--miou-ignore-background", "kind": "string", "name": "miou_ignore_background", "required": false }, { "flag": "--skip-missing-pred", "kind": "string", "name": "skip_missing_pred", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/seg_eval.json", "description": "Segmentation evaluation JSON artifact.", "kind": "file", "name": "seg_eval_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Evaluate semantic segmentation predictions (mIoU / per-class IoU) with ignore_index support and optional HTML/overlays.", "tags": [ "eval", "segmentation" ] }, { "contract_outputs": { "eval_suite_report_json": "eval_suite_json" }, "contracts": { "consumes": [ "predictions_json" ], "produces": [ "eval_suite_report_json" ] }, "docs": [ "docs/byop_quickstarts.md", "docs/yolo26_eval_protocol.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes eval suite JSON report.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/eval_suite.py", "examples": [ { "command": "python3 tools/eval_suite.py --protocol yolo26 --dataset data/coco128 --predictions-glob 'reports/pred_yolo26*.json' --dry-run --output reports/eval_suite.json", "description": "Evaluate all YOLO26 bucket predictions (no COCOeval) on coco128." } ], "id": "eval_suite", "inputs": [ { "flag": "--predictions-glob", "kind": "string", "name": "predictions_glob", "required": true }, { "default": "reports/eval_suite.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--protocol", "kind": "string", "name": "protocol", "required": false }, { "flag": "--allow-protocol-mismatches", "kind": "string", "name": "allow_protocol_mismatches", "required": false }, { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": false }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--bbox-format", "kind": "string", "name": "bbox_format", "required": false }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/eval_suite.json", "description": "Evaluation suite JSON artifact.", "kind": "file", "name": "eval_suite_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Evaluate prediction JSONs and preserve declared exporter settings in a single suite report.", "tags": [ "eval", "suite", "yolo26" ] }, { "contracts": { "consumes": [ "synthgen_sample_contract" ] }, "docs": [ "docs/synthgen_intake.md", "docs/synthgen_repo_integration.md", "recipes/synthgen/README.md", "docs/synthgen_contract.md", "docs/production_readiness.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes SynthGen evaluation report JSON.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/eval_synthgen.py", "examples": [ { "command": "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", "description": "Evaluate animal_v1 predictions exported from external inference, keeping shard-relative asset paths under shards/." } ], "id": "eval_synthgen", "inputs": [ { "flag": "--dataset-root", "kind": "dir", "name": "dataset_root", "required": true }, { "flag": "--predictions", "kind": "file", "name": "predictions", "required": true }, { "flag": "--schema-id", "kind": "string", "name": "schema_id", "required": false }, { "default": 0, "flag": "--max-samples", "kind": "number", "name": "max_samples", "required": false }, { "default": 0, "flag": "--num-classes", "kind": "number", "name": "num_classes", "required": false }, { "default": "reports/synthgen_eval.json", "flag": "--output", "kind": "file", "name": "output", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/synthgen_eval.json", "description": "SynthGen evaluation report.", "kind": "file", "name": "report_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Evaluate SynthGen predictions (keypoints + segmentation + depth) against shard ground truth.", "tags": [ "synthgen", "evaluation", "keypoints", "segmentation", "depth", "metrics" ] }, { "docs": [ "docs/openai_mcp_actions.md", "docs/mcp_extension_architecture.md", "docs/llm_integrations.md", "manual/chapters/20_llm_mcp_integrations.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes OpenAPI schema JSON.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/export_actions_openapi.py", "examples": [ { "command": "python3 tools/export_actions_openapi.py --output reports/actions_openapi.json", "description": "Export OpenAPI schema for GPT Actions registration." } ], "id": "export_actions_openapi", "inputs": [ { "default": "reports/actions_openapi.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "default": 2, "flag": "--indent", "kind": "number", "name": "indent", "required": false } ], "maturity": "stable", "outputs": [ { "default": null, "description": "Exported OpenAPI schema JSON.", "kind": "file", "name": "openapi_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "fastapi" ] }, "runner": "python3", "summary": "Export a static OpenAPI JSON schema for YOLOZU Actions API registration.", "tags": [ "openapi", "fastapi", "integration", "llm" ] }, { "docs": [ "docs/bop_tless_protocol.md", "docs/schemas/bop19_tless_pose_qualification.schema.json", "docs/tools_index.md", "reports/bop19_tless_official_evidence_2026-07-30.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes a fresh official BOP19 result CSV.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Writes a fresh inference provenance report.", "flag": "--report", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/export_bop19_rtdetr_pose.py", "examples": [ { "command": "python3 tools/export_bop19_rtdetr_pose.py --bop-root /workspace/tless --targets /workspace/tless/test_targets_bop19.json --config rtdetr_pose/configs/bop_tless_official.json --checkpoint /workspace/run/checkpoint.pt --output reports/method_tless-test.csv", "description": "Export target-conditioned RT-DETR pose estimates for official BOP19 localization evaluation." }, { "command": "python3 tools/export_bop19_rtdetr_pose.py --help", "description": "Show official-target, checkpoint, device, and bounded-probe options." } ], "id": "export_bop19_rtdetr_pose", "inputs": [ { "flag": "--bop-root", "kind": "dir", "name": "bop_root", "required": true }, { "flag": "--targets", "kind": "file", "name": "targets", "required": true }, { "flag": "--config", "kind": "file", "name": "config", "required": true }, { "flag": "--checkpoint", "kind": "file", "name": "checkpoint", "required": true }, { "flag": "--output", "kind": "file", "name": "output", "required": true }, { "default": null, "flag": "--report", "kind": "file", "name": "report", "required": false }, { "default": "test_primesense", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "default": "cpu", "flag": "--device", "kind": "string", "name": "device", "required": false }, { "default": 96, "flag": "--image-size", "kind": "number", "name": "image_size", "required": false }, { "default": null, "flag": "--max-images", "kind": "number", "name": "max_images", "required": false } ], "maturity": "research", "outputs": [ { "default": null, "description": "Official BOP19 localization CSV.", "kind": "file", "name": "bop19_results_csv" }, { "default": ".report.json", "description": "Checkpoint, target, runtime, resource, and license provenance; peak_rss_bytes is null when the host lacks the optional resource module.", "kind": "file", "name": "export_report_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "Pillow", "numpy", "torch" ] }, "runner": "python3", "summary": "Export trained RT-DETR object-pose predictions over official BOP19 targets without using test GT during inference.", "tags": [ "bop", "tless", "pose6d", "export", "research" ] }, { "contract_outputs": { "predictions_json": "predictions_json" }, "contracts": { "produces": [ "predictions_json" ] }, "docs": [ "docs/checkpoint_compatibility.md", "docs/real_model_interface.md", "docs/training_inference_export.md", "docs/ttt_protocol.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Repository-relative paths are anchored to the checkout. Removes any prior target before inference, then writes predictions JSON only after checkpoint compatibility and requested torch.compile execution/fallback are evidenced.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Optional TTA log JSON output; repository-relative paths are anchored to the checkout and a requested prior log is removed before inference.", "flag": "--tta-log-out", "kind": "file", "scope": "path" }, { "description": "Optional TTT log JSON output; repository-relative paths are anchored to the checkout and a requested prior log is removed before inference.", "flag": "--ttt-log-out", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/export_predictions.py", "examples": [ { "command": "python3 tools/export_predictions.py --adapter dummy --dataset data/coco128 --wrap --output reports/predictions_dummy.json", "description": "Export dummy predictions (schema smoke)." }, { "command": "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", "description": "Export predictions only after the requested torch.compile path completes its first model execution and records requested, actual, and available counter evidence." } ], "id": "export_predictions", "inputs": [ { "default": "dummy", "flag": "--adapter", "kind": "string", "name": "adapter", "required": false }, { "default": "data/coco128", "flag": "--dataset", "kind": "dir", "name": "dataset", "required": false }, { "default": "reports/predictions.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "description": "Optional domain shift recipe JSON; copied into wrapped meta.export_settings.domain_shift_target.", "flag": "--domain-shift-recipe", "kind": "file", "name": "domain_shift_recipe", "required": false }, { "flag": "--wrap", "kind": "string", "name": "wrap", "required": false }, { "flag": "--config", "kind": "file", "name": "config", "required": false }, { "flag": "--device", "kind": "string", "name": "device", "required": false }, { "flag": "--image-size", "kind": "number", "name": "image_size", "required": false }, { "flag": "--score-threshold", "kind": "number", "name": "score_threshold", "required": false }, { "flag": "--max-detections", "kind": "number", "name": "max_detections", "required": false }, { "flag": "--checkpoint", "kind": "file", "name": "checkpoint", "required": false }, { "description": "Explicit transfer/diagnostic opt-in for name-and-shape partial loading; requires --checkpoint and --wrap and records status=partial.", "flag": "--allow-partial-checkpoint", "kind": "string", "name": "allow_partial_checkpoint", "required": false }, { "flag": "--lora-r", "kind": "number", "name": "lora_r", "required": false }, { "flag": "--lora-alpha", "kind": "number", "name": "lora_alpha", "required": false }, { "flag": "--lora-dropout", "kind": "number", "name": "lora_dropout", "required": false }, { "flag": "--lora-target", "kind": "string", "name": "lora_target", "required": false }, { "flag": "--lora-freeze-base", "kind": "string", "name": "lora_freeze_base", "required": false }, { "flag": "--no-lora-freeze-base", "kind": "string", "name": "no_lora_freeze_base", "required": false }, { "flag": "--lora-train-bias", "kind": "string", "name": "lora_train_bias", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--tta", "kind": "string", "name": "tta", "required": false }, { "flag": "--tta-seed", "kind": "number", "name": "tta_seed", "required": false }, { "flag": "--tta-flip-prob", "kind": "number", "name": "tta_flip_prob", "required": false }, { "flag": "--tta-norm-only", "kind": "string", "name": "tta_norm_only", "required": false }, { "flag": "--tta-flip-keypoints", "kind": "string", "name": "tta_flip_keypoints", "required": false }, { "flag": "--no-tta-flip-keypoints", "kind": "string", "name": "no_tta_flip_keypoints", "required": false }, { "flag": "--tta-flip-pose-offsets", "kind": "string", "name": "tta_flip_pose_offsets", "required": false }, { "flag": "--no-tta-flip-pose-offsets", "kind": "string", "name": "no_tta_flip_pose_offsets", "required": false }, { "flag": "--tta-log-out", "kind": "file", "name": "tta_log_out", "required": false }, { "description": "Enable in-memory test-time training during inference (default: off; opt-in).", "flag": "--ttt", "kind": "string", "name": "ttt", "required": false }, { "description": "TTT preset profile (safe, adapter_only, mim_safe, cotta_safe, eata_safe, sar_safe, detector_response_safe, pose_safe, keypoints_safe, depth_safe, seg_safe, pose_mim); sar_safe requires --lora-r > 0.", "flag": "--ttt-preset", "kind": "string", "name": "ttt_preset", "required": false }, { "flag": "--ttt-method", "kind": "string", "name": "ttt_method", "required": false }, { "flag": "--ttt-reset", "kind": "string", "name": "ttt_reset", "required": false }, { "flag": "--ttt-steps", "kind": "number", "name": "ttt_steps", "required": false }, { "flag": "--ttt-batch-size", "kind": "number", "name": "ttt_batch_size", "required": false }, { "flag": "--ttt-lr", "kind": "number", "name": "ttt_lr", "required": false }, { "flag": "--ttt-stop-on-non-finite", "kind": "string", "name": "ttt_stop_on_non_finite", "required": false }, { "flag": "--no-ttt-stop-on-non-finite", "kind": "string", "name": "no_ttt_stop_on_non_finite", "required": false }, { "flag": "--ttt-rollback-on-stop", "kind": "string", "name": "ttt_rollback_on_stop", "required": false }, { "flag": "--no-ttt-rollback-on-stop", "kind": "string", "name": "no_ttt_rollback_on_stop", "required": false }, { "flag": "--ttt-seed", "kind": "number", "name": "ttt_seed", "required": false }, { "flag": "--ttt-max-update-norm", "kind": "number", "name": "ttt_max_update_norm", "required": false }, { "flag": "--ttt-max-total-update-norm", "kind": "number", "name": "ttt_max_total_update_norm", "required": false }, { "flag": "--ttt-max-loss-ratio", "kind": "number", "name": "ttt_max_loss_ratio", "required": false }, { "flag": "--ttt-max-loss-increase", "kind": "number", "name": "ttt_max_loss_increase", "required": false }, { "flag": "--ttt-update-filter", "kind": "string", "name": "ttt_update_filter", "required": false }, { "flag": "--ttt-include", "kind": "string", "name": "ttt_include", "required": false }, { "flag": "--ttt-exclude", "kind": "string", "name": "ttt_exclude", "required": false }, { "flag": "--ttt-log-out", "kind": "file", "name": "ttt_log_out", "required": false }, { "flag": "--ttt-patch-size", "kind": "number", "name": "ttt_patch_size", "required": false }, { "flag": "--ttt-mask-prob", "kind": "number", "name": "ttt_mask_prob", "required": false }, { "flag": "--ttt-mask-value", "kind": "number", "name": "ttt_mask_value", "required": false }, { "flag": "--ttt-max-batches", "kind": "number", "name": "ttt_max_batches", "required": false }, { "flag": "--ttt-max-grad-norm", "kind": "number", "name": "ttt_max_grad_norm", "required": false }, { "flag": "--ttt-cotta-ema-momentum", "kind": "number", "name": "ttt_cotta_ema_momentum", "required": false }, { "flag": "--ttt-cotta-augmentations", "kind": "string", "name": "ttt_cotta_augmentations", "required": false }, { "flag": "--ttt-cotta-aggregation", "kind": "string", "name": "ttt_cotta_aggregation", "required": false }, { "flag": "--ttt-cotta-restore-prob", "kind": "number", "name": "ttt_cotta_restore_prob", "required": false }, { "flag": "--ttt-cotta-restore-interval", "kind": "number", "name": "ttt_cotta_restore_interval", "required": false }, { "flag": "--ttt-eata-conf-min", "kind": "number", "name": "ttt_eata_conf_min", "required": false }, { "flag": "--ttt-eata-entropy-min", "kind": "number", "name": "ttt_eata_entropy_min", "required": false }, { "flag": "--ttt-eata-entropy-max", "kind": "number", "name": "ttt_eata_entropy_max", "required": false }, { "flag": "--ttt-eata-min-valid-dets", "kind": "number", "name": "ttt_eata_min_valid_dets", "required": false }, { "flag": "--ttt-eata-anchor-lambda", "kind": "number", "name": "ttt_eata_anchor_lambda", "required": false }, { "flag": "--ttt-eata-selected-ratio-min", "kind": "number", "name": "ttt_eata_selected_ratio_min", "required": false }, { "flag": "--ttt-eata-max-skip-streak", "kind": "number", "name": "ttt_eata_max_skip_streak", "required": false }, { "flag": "--ttt-sar-rho", "kind": "number", "name": "ttt_sar_rho", "required": false }, { "flag": "--ttt-sar-adaptive", "kind": "string", "name": "ttt_sar_adaptive", "required": false }, { "flag": "--no-ttt-sar-adaptive", "kind": "string", "name": "no_ttt_sar_adaptive", "required": false }, { "flag": "--ttt-sar-first-step-scale", "kind": "number", "name": "ttt_sar_first_step_scale", "required": false }, { "description": "SDFT task hint for preset auto-selection (pose | keypoints | depth | seg | full).", "flag": "--ttt-sdft-task", "kind": "string", "name": "ttt_sdft_task", "required": false }, { "description": "Auxiliary consistency loss weight for pose heads (rot6d/log_z/offsets/k_delta). 0 disables.", "flag": "--ttt-aux-pose-weight", "kind": "number", "name": "ttt_aux_pose_weight", "required": false }, { "description": "Auxiliary consistency loss weight for keypoint heads. 0 disables.", "flag": "--ttt-aux-keypoints-weight", "kind": "number", "name": "ttt_aux_keypoints_weight", "required": false }, { "description": "Auxiliary consistency loss weight for depth heads. 0 disables.", "flag": "--ttt-aux-depth-weight", "kind": "number", "name": "ttt_aux_depth_weight", "required": false }, { "description": "Auxiliary consistency loss weight for segmentation heads. 0 disables.", "flag": "--ttt-aux-seg-weight", "kind": "number", "name": "ttt_aux_seg_weight", "required": false }, { "description": "Temperature for auxiliary consistency losses. Default 1.0.", "flag": "--ttt-aux-temperature", "kind": "number", "name": "ttt_aux_temperature", "required": false }, { "description": "Use selected foreground class/box response consistency and exclude the final no-object class.", "flag": "--ttt-detector-response", "kind": "string", "name": "ttt_detector_response", "required": false }, { "flag": "--no-ttt-detector-response", "kind": "string", "name": "no_ttt_detector_response", "required": false }, { "flag": "--ttt-response-conf-min", "kind": "number", "name": "ttt_response_conf_min", "required": false }, { "flag": "--ttt-response-topk", "kind": "number", "name": "ttt_response_topk", "required": false }, { "default": 1, "description": "Abstain from a pure detector-response update below this selected-query count.", "flag": "--ttt-response-min-selected", "kind": "number", "name": "ttt_response_min_selected", "required": false }, { "flag": "--ttt-response-class-weight", "kind": "number", "name": "ttt_response_class_weight", "required": false }, { "flag": "--ttt-response-bbox-weight", "kind": "number", "name": "ttt_response_bbox_weight", "required": false }, { "flag": "--ttt-response-entropy-weight", "kind": "number", "name": "ttt_response_entropy_weight", "required": false }, { "default": 1, "flag": "--infer-batch-size", "kind": "number", "name": "infer_batch_size", "required": false }, { "flag": "--torch-compile", "kind": "string", "name": "torch_compile", "required": false }, { "default": "inductor", "flag": "--torch-compile-backend", "kind": "string", "name": "torch_compile_backend", "required": false }, { "default": "reduce-overhead", "flag": "--torch-compile-mode", "kind": "string", "name": "torch_compile_mode", "required": false }, { "flag": "--torch-compile-fullgraph", "kind": "string", "name": "torch_compile_fullgraph", "required": false }, { "flag": "--no-torch-compile-fullgraph", "kind": "string", "name": "no_torch_compile_fullgraph", "required": false }, { "default": "auto", "description": "torch.compile dynamic-shape policy: auto, true, or false.", "flag": "--torch-compile-dynamic", "kind": "string", "name": "torch_compile_dynamic", "required": false }, { "description": "Explicitly permit eager fallback when requested torch.compile setup or first execution fails; wrapped metadata records actual.status=fallback.", "flag": "--allow-compile-fallback", "kind": "string", "name": "allow_compile_fallback", "required": false }, { "default": "off", "flag": "--torch-amp", "kind": "string", "name": "torch_amp", "required": false }, { "flag": "--torch-channels-last", "kind": "string", "name": "torch_channels_last", "required": false }, { "flag": "--no-torch-channels-last", "kind": "string", "name": "no_torch_channels_last", "required": false }, { "flag": "--torch-inference-mode", "kind": "string", "name": "torch_inference_mode", "required": false }, { "flag": "--no-torch-inference-mode", "kind": "string", "name": "no_torch_inference_mode", "required": false }, { "description": "TTA mode: postprocess (default) or model.", "flag": "--tta-mode", "kind": "string", "name": "tta_mode", "required": false }, { "description": "Optional keypoint swap pairs (e.g., '1:2,3:4').", "flag": "--tta-keypoint-swap-pairs", "kind": "string", "name": "tta_keypoint_swap_pairs", "required": false }, { "description": "IoU threshold for model-space TTA branch merge.", "flag": "--tta-model-merge-iou", "kind": "number", "name": "tta_model_merge_iou", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/predictions.json", "description": "Predictions JSON; wrapped metadata includes checkpoint compatibility/provenance, task coverage, extended TTA settings, and separate requested/actual torch.compile evidence.", "kind": "file", "name": "predictions_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "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.", "tags": [ "predictions", "adapter" ] }, { "contracts": { "consumes": [ "predictions_json" ], "produces": [ "predictions_json" ] }, "docs": [ "docs/interop_detectron2_mmdet.md", "docs/tools_index.md", "docs/training_inference_export.md", "manual/chapters/04_cli_reference.tex", "manual/chapters/07_training_run_contract.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes YOLOZU predictions JSON converted from COCO keypoints results.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/export_predictions_coco_keypoints.py", "examples": [ { "command": "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", "description": "Convert COCO keypoints results JSON into the YOLOZU predictions interface contract." } ], "id": "export_predictions_coco_keypoints", "inputs": [ { "flag": "--results-json", "kind": "file", "name": "results_json", "required": true }, { "flag": "--instances-json", "kind": "file", "name": "instances_json", "required": true }, { "flag": "--output", "kind": "file", "name": "output", "required": true }, { "flag": "--score-threshold", "kind": "number", "name": "score_threshold", "required": false }, { "flag": "--force", "kind": "string", "name": "force", "required": false } ], "maturity": "experimental", "outputs": [ { "default": null, "description": "Predictions interface contract JSON produced from COCO keypoints results.", "kind": "file", "name": "predictions_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Convert COCO-style keypoints results JSON into the YOLOZU predictions interface contract for downstream eval and parity.", "tags": [ "keypoints", "predictions", "interop", "export" ] }, { "contracts": { "produces": [ "predictions_json" ] }, "docs": [ "README.md", "docs/README.md", "docs/byop_quickstarts.md", "docs/external_inference.md", "docs/interop_detectron2_mmdet.md", "docs/predictions_schema.md", "docs/schema_governance.md", "manual/chapters/05_workflows_eval_export.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes YOLOZU predictions JSON from Detectron2 outputs.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/export_predictions_detectron2.py", "examples": [ { "command": "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", "description": "Detectron2 export for YOLOZU eval." } ], "id": "export_predictions_detectron2", "inputs": [ { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "description": "Existing Detectron2 config file; required for non-dry inference.", "flag": "--config", "kind": "file", "name": "config", "required": true }, { "description": "Existing Detectron2 checkpoint file; required for non-dry inference.", "flag": "--weights", "kind": "file", "name": "weights", "required": true }, { "flag": "--output", "kind": "file", "name": "output", "required": true }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "default": 0.25, "flag": "--score-thr", "kind": "number", "name": "score_thr", "required": false }, { "default": 300, "flag": "--topk", "kind": "number", "name": "topk", "required": false }, { "default": "cuda", "flag": "--device", "kind": "string", "name": "device", "required": false }, { "default": 640, "flag": "--imgsz", "kind": "number", "name": "imgsz", "required": false }, { "default": "nms_applied", "flag": "--protocol", "kind": "string", "name": "protocol", "required": false }, { "default": "BGR", "flag": "--input-color", "kind": "string", "name": "input_color", "required": false }, { "default": "1.0", "flag": "--normalize-scale", "kind": "string", "name": "normalize_scale", "required": false }, { "default": "", "flag": "--normalize-mean", "kind": "string", "name": "normalize_mean", "required": false }, { "default": "", "flag": "--normalize-std", "kind": "string", "name": "normalize_std", "required": false }, { "default": "config_shortest_edge", "flag": "--resize-policy", "kind": "string", "name": "resize_policy", "required": false }, { "default": "config_pad_to_stride", "flag": "--pad-policy", "kind": "string", "name": "pad_policy", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false } ], "maturity": "experimental", "outputs": [ { "default": null, "description": "Predictions JSON with wrapper v1, entry v2, execution status, inference-call evidence, and config/checkpoint provenance; written only after successful non-dry inference.", "kind": "file", "name": "predictions_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "detectron2", "torch", "opencv-python", "numpy" ] }, "runner": "python3", "summary": "Run fail-closed Detectron2 inference and export explicitly versioned predictions.json with protocol, execution-evidence, and provenance metadata.", "tags": [ "export", "detectron2", "coco", "predictions", "nms", "e2e", "interop" ] }, { "contracts": { "produces": [ "predictions_json" ] }, "docs": [ "docs/external_inference.md", "manual/chapters/05_workflows_eval_export.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes predictions JSON.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/export_predictions_executorch.py", "examples": [ { "command": "python3 tools/export_predictions_executorch.py --dataset data/smoke --split val --dry-run --wrap --output reports/pred_executorch.json", "description": "Dry-run ExecuTorch exporter for schema/interface-contract validation." }, { "command": "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", "description": "Decode an ExecuTorch runtime output JSON artifact into strict predictions JSON." } ], "id": "export_predictions_executorch", "inputs": [ { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--model", "kind": "file", "name": "model", "required": false }, { "flag": "--boxes-scale", "kind": "string", "name": "boxes_scale", "required": false }, { "flag": "--runtime-output-json", "kind": "file", "name": "runtime_output_json", "required": false }, { "flag": "--min-score", "kind": "number", "name": "min_score", "required": false }, { "flag": "--topk", "kind": "number", "name": "topk", "required": false }, { "default": "reports/predictions_executorch.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--wrap", "kind": "string", "name": "wrap", "required": false }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/predictions_executorch.json", "description": "Predictions JSON artifact.", "kind": "file", "name": "predictions_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true, "notes": "Non-dry mode requires a .pte model path plus --runtime-output-json from an external ExecuTorch runtime pass." }, "requires": { "python_packages": [] }, "runner": "python3", "summary": "Decode declared ExecuTorch runtime output JSON into YOLOZU predictions JSON (dry-run supported for interface contract validation).", "tags": [ "predictions", "executorch" ] }, { "contracts": { "produces": [ "predictions_json" ] }, "docs": [ "README.md", "docs/README.md", "docs/byop_quickstarts.md", "docs/external_inference.md", "docs/interop_detectron2_mmdet.md", "docs/predictions_schema.md", "docs/schema_governance.md", "manual/chapters/05_workflows_eval_export.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes YOLOZU predictions JSON from MMDetection outputs.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/export_predictions_mmdet.py", "examples": [ { "command": "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", "description": "MMDetection export for YOLOZU eval." } ], "id": "export_predictions_mmdet", "inputs": [ { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "description": "Existing MMDetection config file; required for non-dry inference.", "flag": "--config", "kind": "file", "name": "config", "required": true }, { "description": "Existing MMDetection checkpoint file; required for non-dry inference.", "flag": "--checkpoint", "kind": "file", "name": "checkpoint", "required": true }, { "flag": "--output", "kind": "file", "name": "output", "required": true }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "default": 0.25, "flag": "--score-thr", "kind": "number", "name": "score_thr", "required": false }, { "default": 300, "flag": "--topk", "kind": "number", "name": "topk", "required": false }, { "default": "cuda:0", "flag": "--device", "kind": "string", "name": "device", "required": false }, { "default": 640, "flag": "--imgsz", "kind": "number", "name": "imgsz", "required": false }, { "default": "nms_applied", "flag": "--protocol", "kind": "string", "name": "protocol", "required": false }, { "default": "BGR", "flag": "--input-color", "kind": "string", "name": "input_color", "required": false }, { "default": "1.0", "flag": "--normalize-scale", "kind": "string", "name": "normalize_scale", "required": false }, { "default": "", "flag": "--normalize-mean", "kind": "string", "name": "normalize_mean", "required": false }, { "default": "", "flag": "--normalize-std", "kind": "string", "name": "normalize_std", "required": false }, { "default": "config_resize", "flag": "--resize-policy", "kind": "string", "name": "resize_policy", "required": false }, { "default": "config_pad", "flag": "--pad-policy", "kind": "string", "name": "pad_policy", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false } ], "maturity": "experimental", "outputs": [ { "default": null, "description": "Predictions JSON with wrapper v1, entry v2, execution status, inference-call evidence, and config/checkpoint provenance; written only after successful non-dry inference.", "kind": "file", "name": "predictions_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "mmdet", "mmengine", "mmcv", "torch", "numpy" ] }, "runner": "python3", "summary": "Run fail-closed MMDetection inference and export explicitly versioned predictions.json with protocol, execution-evidence, and provenance metadata.", "tags": [ "export", "mmdetection", "mmdet", "coco", "predictions", "nms", "e2e", "interop" ] }, { "contracts": { "produces": [ "predictions_json" ] }, "docs": [ "docs/onnx_export_parity.md", "docs/external_inference.md", "manual/chapters/05_workflows_eval_export.tex", "examples/infer_rust/README.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes predictions JSON.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Optional raw boxes output.", "flag": "--boxes-output", "kind": "file", "scope": "path" }, { "description": "Optional raw class output.", "flag": "--class-output", "kind": "file", "scope": "path" }, { "description": "Optional raw scores output.", "flag": "--scores-output", "kind": "file", "scope": "path" }, { "description": "Optional raw tensor output.", "flag": "--raw-output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/export_predictions_onnxrt.py", "examples": [ { "command": "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", "description": "Export ONNXRuntime predictions (dry-run mode exists)." } ], "id": "export_predictions_onnxrt", "inputs": [ { "default": null, "flag": "--onnx", "kind": "file", "name": "onnx", "required": false }, { "default": "reports/predictions_onnxrt.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": false }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--input-name", "kind": "string", "name": "input_name", "required": false }, { "flag": "--combined-output", "kind": "string", "name": "combined_output", "required": false }, { "flag": "--combined-format", "kind": "string", "name": "combined_format", "required": false }, { "flag": "--boxes-output", "kind": "file", "name": "boxes_output", "required": false }, { "flag": "--boxes-format", "kind": "string", "name": "boxes_format", "required": false }, { "flag": "--boxes-scale", "kind": "string", "name": "boxes_scale", "required": false }, { "flag": "--class-output", "kind": "file", "name": "class_output", "required": false }, { "flag": "--scores-output", "kind": "file", "name": "scores_output", "required": false }, { "flag": "--raw-output", "kind": "file", "name": "raw_output", "required": false }, { "flag": "--raw-format", "kind": "string", "name": "raw_format", "required": false }, { "flag": "--raw-postprocess", "kind": "string", "name": "raw_postprocess", "required": false }, { "flag": "--nms-iou", "kind": "number", "name": "nms_iou", "required": false }, { "flag": "--agnostic-nms", "kind": "string", "name": "agnostic_nms", "required": false }, { "flag": "--topk", "kind": "number", "name": "topk", "required": false }, { "flag": "--min-score", "kind": "number", "name": "min_score", "required": false }, { "flag": "--wrap", "kind": "string", "name": "wrap", "required": false }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/predictions_onnxrt.json", "description": "Predictions JSON artifact.", "kind": "file", "name": "predictions_json" }, { "default": null, "description": "Optional raw boxes output when --boxes-output is set.", "kind": "file", "name": "boxes_output" }, { "default": null, "description": "Optional raw class output when --class-output is set.", "kind": "file", "name": "class_output" }, { "default": null, "description": "Optional raw scores output when --scores-output is set.", "kind": "file", "name": "scores_output" }, { "default": null, "description": "Optional raw tensor output when --raw-output is set.", "kind": "file", "name": "raw_output" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true, "notes": "ONNXRuntime execution provider depends on your environment." }, "requires": { "python_packages": [ "onnxruntime", "numpy", "opencv-python" ] }, "runner": "python3", "summary": "Run ONNXRuntime inference and export YOLOZU predictions JSON (requires onnxruntime + numpy + opencv; see Rust ONNXRuntime template notes in external inference docs).", "tags": [ "predictions", "onnxruntime", "rust" ] }, { "docs": [ "docs/opencv_dnn_inference.md", "docs/external_inference.md", "manual/chapters/05_workflows_eval_export.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes predictions JSON.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Writes metadata JSON.", "flag": "--meta-output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/export_predictions_opencv_dnn.py", "examples": [ { "command": "python3 tools/export_predictions_opencv_dnn.py --dataset data/coco128 --dry-run --output reports/pred_opencv_dnn.json", "description": "Export OpenCV-DNN predictions (dry-run works without OpenCV installed)." }, { "command": "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", "description": "Export OpenCV-DNN predictions (YOLOv5-style 85+objectness raw head)." } ], "id": "export_predictions_opencv_dnn", "inputs": [ { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--onnx", "kind": "file", "name": "onnx", "required": false }, { "flag": "--input-size", "kind": "number", "name": "input_size", "required": false }, { "flag": "--output-names", "kind": "string", "name": "output_names", "required": false }, { "flag": "--output-index", "kind": "number", "name": "output_index", "required": false }, { "flag": "--raw-format", "kind": "string", "name": "raw_format", "required": false }, { "flag": "--boxes-scale", "kind": "string", "name": "boxes_scale", "required": false }, { "flag": "--min-score", "kind": "number", "name": "min_score", "required": false }, { "flag": "--nms-iou", "kind": "number", "name": "nms_iou", "required": false }, { "flag": "--max-det", "kind": "number", "name": "max_det", "required": false }, { "flag": "--agnostic-nms", "kind": "string", "name": "agnostic_nms", "required": false }, { "flag": "--swap-rb", "kind": "string", "name": "swap_rb", "required": false }, { "flag": "--dnn-backend", "kind": "string", "name": "dnn_backend", "required": false }, { "flag": "--dnn-target", "kind": "string", "name": "dnn_target", "required": false }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false }, { "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--meta-output", "kind": "file", "name": "meta_output", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "flag": "--dump-io", "kind": "file", "name": "dump_io", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/pred_opencv_dnn.json", "description": "Predictions JSON artifact.", "kind": "file", "name": "predictions_json" }, { "default": "reports/pred_opencv_dnn.json.meta.json", "description": "Meta JSON artifact.", "kind": "file", "name": "meta_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "numpy", "opencv-python" ] }, "runner": "python3", "summary": "Run OpenCV-DNN inference on an ONNX model and export YOLOZU predictions JSON (YOLOv8 84 or YOLOv5 85+obj raw heads supported).", "tags": [ "export", "opencv", "dnn", "onnx", "predictions" ] }, { "docs": [ "docs/opencv_dnn_inference.md", "docs/external_inference.md", "manual/chapters/05_workflows_eval_export.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes predictions JSON.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Writes metadata JSON.", "flag": "--meta-output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/export_predictions_opencv_dnn_rtdetr.py", "examples": [ { "command": "python3 tools/export_predictions_opencv_dnn_rtdetr.py --dataset data/coco128 --dry-run --output reports/pred_rtdetr_opencv_dnn.json", "description": "Export RT-DETR OpenCV-DNN predictions (dry-run works without OpenCV installed)." }, { "command": "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", "description": "Run via unified yolozu export backend" } ], "id": "export_predictions_opencv_dnn_rtdetr", "inputs": [ { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--onnx", "kind": "file", "name": "onnx", "required": false }, { "flag": "--imgsz", "kind": "number", "name": "imgsz", "required": false }, { "flag": "--keep-aspect", "kind": "string", "name": "keep_aspect", "required": false }, { "flag": "--letterbox-fill", "kind": "string", "name": "letterbox_fill", "required": false }, { "flag": "--input-color", "kind": "string", "name": "input_color", "required": false }, { "flag": "--scale", "kind": "number", "name": "scale", "required": false }, { "flag": "--mean", "kind": "string", "name": "mean", "required": false }, { "flag": "--std", "kind": "string", "name": "std", "required": false }, { "flag": "--outputs", "kind": "string", "name": "outputs", "required": false }, { "flag": "--boxes-output", "kind": "string", "name": "boxes_output", "required": false }, { "flag": "--logits-output", "kind": "string", "name": "logits_output", "required": false }, { "flag": "--labels-output", "kind": "string", "name": "labels_output", "required": false }, { "flag": "--scores-output", "kind": "string", "name": "scores_output", "required": false }, { "flag": "--print-outputs", "kind": "string", "name": "print_outputs", "required": false }, { "flag": "--boxes-format", "kind": "string", "name": "boxes_format", "required": false }, { "flag": "--boxes-scale", "kind": "string", "name": "boxes_scale", "required": false }, { "flag": "--scores-activation", "kind": "string", "name": "scores_activation", "required": false }, { "flag": "--background-class", "kind": "string", "name": "background_class", "required": false }, { "flag": "--score-thr", "kind": "number", "name": "score_thr", "required": false }, { "flag": "--topk", "kind": "number", "name": "topk", "required": false }, { "flag": "--dnn-backend", "kind": "string", "name": "dnn_backend", "required": false }, { "flag": "--dnn-target", "kind": "string", "name": "dnn_target", "required": false }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false }, { "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--meta-output", "kind": "file", "name": "meta_output", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "flag": "--dump-io", "kind": "file", "name": "dump_io", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/pred_rtdetr_opencv_dnn.json", "description": "Predictions JSON artifact.", "kind": "file", "name": "predictions_json" }, { "default": "reports/pred_rtdetr_opencv_dnn.json.meta.json", "description": "Meta JSON artifact.", "kind": "file", "name": "meta_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "numpy", "opencv-python" ] }, "runner": "python3", "summary": "Run OpenCV-DNN inference on an RT-DETR ONNX model and export YOLOZU predictions JSON (no NMS), recording fixed preprocess/export_settings.", "tags": [ "export", "opencv", "dnn", "onnx", "rtdetr", "predictions" ] }, { "contracts": { "produces": [ "predictions_json" ] }, "docs": [ "README.md", "docs/README.md", "docs/opencv_dnn_inference.md", "docs/external_inference.md", "manual/chapters/05_workflows_eval_export.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes YOLOZU predictions JSON via OpenCV DNN.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Writes export meta JSON alongside predictions.", "flag": "--meta-output", "kind": "file", "scope": "path" }, { "description": "Optional IO tensor dump JSON for debugging.", "flag": "--dump-io", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/export_predictions_opencv_dnn_unified.py", "examples": [ { "command": "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", "description": "Unified OpenCV-DNN export with auto decode and IO dump." } ], "id": "export_predictions_opencv_dnn_unified", "inputs": [ { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--onnx", "kind": "file", "name": "onnx", "required": true }, { "default": 640, "flag": "--imgsz", "kind": "number", "name": "imgsz", "required": false }, { "flag": "--preprocess", "kind": "string", "name": "preprocess", "required": false }, { "default": "auto", "flag": "--decode", "kind": "string", "name": "decode", "required": false }, { "default": 0.01, "flag": "--score-thr", "kind": "number", "name": "score_thr", "required": false }, { "default": 0.45, "flag": "--nms-iou", "kind": "number", "name": "nms_iou", "required": false }, { "default": 300, "flag": "--topk", "kind": "number", "name": "topk", "required": false }, { "default": "opencv", "flag": "--dnn-backend", "kind": "string", "name": "dnn_backend", "required": false }, { "default": "cpu", "flag": "--dnn-target", "kind": "string", "name": "dnn_target", "required": false }, { "flag": "--dump-io", "kind": "file", "name": "dump_io", "required": false }, { "flag": "--meta-output", "kind": "file", "name": "meta_output", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false }, { "flag": "--output", "kind": "file", "name": "output", "required": true } ], "maturity": "experimental", "outputs": [ { "default": null, "description": "Predictions JSON at --output.", "kind": "file", "name": "predictions_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Unified OpenCV-DNN exporter with preprocess/decode presets, IO dump, and backend/target controls.", "tags": [ "export", "opencv", "opencv-dnn", "onnx", "interop", "benchmark", "parity" ] }, { "contracts": { "produces": [ "predictions_json" ] }, "docs": [ "docs/external_inference.md", "docs/benchmark_support_matrix.md", "docs/benchmark_mode.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes predictions JSON.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/export_predictions_openvino.py", "examples": [ { "command": "python3 tools/export_predictions_openvino.py --dataset data/smoke --split val --model exports/model.xml --wrap --output reports/pred_openvino.json", "description": "Run OpenVINO detection export with the declared combined-output decode path." }, { "command": "python3 tools/export_predictions_openvino.py --dataset data/smoke --split val --dry-run --wrap --output reports/pred_openvino.json", "description": "Dry-run OpenVINO exporter schema wiring without requiring OpenVINO runtime." } ], "id": "export_predictions_openvino", "inputs": [ { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--model", "kind": "file", "name": "model", "required": false }, { "flag": "--device", "kind": "string", "name": "device", "required": false }, { "flag": "--imgsz", "kind": "number", "name": "imgsz", "required": false }, { "flag": "--input-size", "kind": "number", "name": "input_size", "required": false }, { "flag": "--input-name", "kind": "string", "name": "input_name", "required": false }, { "flag": "--combined-output", "kind": "string", "name": "combined_output", "required": false }, { "flag": "--combined-format", "kind": "string", "name": "combined_format", "required": false }, { "flag": "--boxes-scale", "kind": "string", "name": "boxes_scale", "required": false }, { "flag": "--min-score", "kind": "number", "name": "min_score", "required": false }, { "flag": "--topk", "kind": "number", "name": "topk", "required": false }, { "default": "reports/predictions_openvino.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--wrap", "kind": "string", "name": "wrap", "required": false }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/predictions_openvino.json", "description": "Predictions JSON artifact.", "kind": "file", "name": "predictions_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true, "notes": "Requires OpenVINO runtime for non-dry mode." }, "requires": { "python_packages": [ "openvino", "numpy", "pillow" ] }, "runner": "python3", "summary": "Run OpenVINO detection inference and export YOLOZU predictions JSON via the declared combined-output decode path.", "tags": [ "predictions", "openvino", "benchmark" ] }, { "contracts": { "produces": [ "predictions_json" ] }, "docs": [ "docs/external_inference.md", "docs/benchmark_support_matrix.md", "docs/benchmark_mode.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes predictions JSON.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/export_predictions_torchscript.py", "examples": [ { "command": "python3 tools/export_predictions_torchscript.py --dataset data/smoke --split val --model exports/model.torchscript --wrap --output reports/pred_torchscript.json", "description": "Run TorchScript detection export with the declared combined-output decode path." }, { "command": "python3 tools/export_predictions_torchscript.py --dataset data/smoke --split val --dry-run --wrap --output reports/pred_torchscript.json", "description": "Dry-run TorchScript exporter schema wiring." } ], "id": "export_predictions_torchscript", "inputs": [ { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--model", "kind": "file", "name": "model", "required": false }, { "flag": "--device", "kind": "string", "name": "device", "required": false }, { "flag": "--imgsz", "kind": "number", "name": "imgsz", "required": false }, { "flag": "--input-size", "kind": "number", "name": "input_size", "required": false }, { "flag": "--combined-output", "kind": "string", "name": "combined_output", "required": false }, { "flag": "--combined-format", "kind": "string", "name": "combined_format", "required": false }, { "flag": "--boxes-scale", "kind": "string", "name": "boxes_scale", "required": false }, { "flag": "--min-score", "kind": "number", "name": "min_score", "required": false }, { "flag": "--topk", "kind": "number", "name": "topk", "required": false }, { "default": "reports/predictions_torchscript.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--wrap", "kind": "string", "name": "wrap", "required": false }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/predictions_torchscript.json", "description": "Predictions JSON artifact.", "kind": "file", "name": "predictions_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true, "notes": "Requires local PyTorch for non-dry mode." }, "requires": { "python_packages": [ "torch", "numpy", "pillow" ] }, "runner": "python3", "summary": "Run TorchScript detection inference and export YOLOZU predictions JSON via the declared combined-output decode path.", "tags": [ "predictions", "torchscript", "benchmark" ] }, { "contracts": { "produces": [ "predictions_json" ] }, "docs": [ "docs/tensorrt_pipeline.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes predictions JSON.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Optional raw boxes output.", "flag": "--boxes-output", "kind": "file", "scope": "path" }, { "description": "Optional raw class output.", "flag": "--class-output", "kind": "file", "scope": "path" }, { "description": "Optional raw scores output.", "flag": "--scores-output", "kind": "file", "scope": "path" }, { "description": "Optional raw tensor output.", "flag": "--raw-output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/export_predictions_trt.py", "examples": [ { "command": "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", "description": "Export TensorRT predictions (engine must exist)." } ], "id": "export_predictions_trt", "inputs": [ { "default": null, "flag": "--engine", "kind": "file", "name": "engine", "required": false }, { "default": null, "flag": "--imgsz", "kind": "number", "name": "imgsz", "required": false }, { "default": "reports/predictions_trt.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": false }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--input-name", "kind": "string", "name": "input_name", "required": false }, { "flag": "--combined-output", "kind": "string", "name": "combined_output", "required": false }, { "flag": "--combined-format", "kind": "string", "name": "combined_format", "required": false }, { "flag": "--boxes-output", "kind": "file", "name": "boxes_output", "required": false }, { "flag": "--boxes-format", "kind": "string", "name": "boxes_format", "required": false }, { "flag": "--boxes-scale", "kind": "string", "name": "boxes_scale", "required": false }, { "flag": "--class-output", "kind": "file", "name": "class_output", "required": false }, { "flag": "--scores-output", "kind": "file", "name": "scores_output", "required": false }, { "flag": "--raw-output", "kind": "file", "name": "raw_output", "required": false }, { "flag": "--raw-format", "kind": "string", "name": "raw_format", "required": false }, { "flag": "--raw-postprocess", "kind": "string", "name": "raw_postprocess", "required": false }, { "flag": "--nms-iou", "kind": "number", "name": "nms_iou", "required": false }, { "flag": "--agnostic-nms", "kind": "string", "name": "agnostic_nms", "required": false }, { "flag": "--topk", "kind": "number", "name": "topk", "required": false }, { "flag": "--min-score", "kind": "number", "name": "min_score", "required": false }, { "flag": "--wrap", "kind": "string", "name": "wrap", "required": false }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/predictions_trt.json", "description": "Predictions JSON artifact.", "kind": "file", "name": "predictions_json" }, { "default": null, "description": "Optional raw boxes output when --boxes-output is set.", "kind": "file", "name": "boxes_output" }, { "default": null, "description": "Optional raw class output when --class-output is set.", "kind": "file", "name": "class_output" }, { "default": null, "description": "Optional raw scores output when --scores-output is set.", "kind": "file", "name": "scores_output" }, { "default": null, "description": "Optional raw tensor output when --raw-output is set.", "kind": "file", "name": "raw_output" } ], "platform": { "cpu_ok": false, "gpu_required": true, "linux_ok": true, "macos_ok": false }, "requires": { "python_packages": [ "tensorrt", "numpy", "opencv-python" ], "system": [ "CUDA bindings (pycuda or cuda-python)" ] }, "runner": "python3", "summary": "Run TensorRT engine inference and export YOLOZU predictions JSON (requires tensorrt + CUDA bindings).", "tags": [ "predictions", "tensorrt" ] }, { "contracts": { "produces": [ "predictions_json" ] }, "docs": [ "docs/external_finetune_smoke.md", "docs/external_inference.md", "docs/predictions_schema.md", "reports/external_runtime_evidence_2026-07-30.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes identity-safe Ultralytics inference results as YOLOZU predictions JSON.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/export_predictions_ultralytics.py", "examples": [ { "command": "python3 tools/export_predictions_ultralytics.py --model runs/ultralytics/weights/best.pt --dataset data/smoke --split val --max-images 10 --image-size 96 --device cpu --no-end2end --protocol nms_applied --wrap --strict --output reports/pred_ultralytics.json", "description": "Export one manifest image at a time so current Ultralytics releases preserve exact result-path identity." }, { "command": "python3 tools/export_predictions_ultralytics.py --help", "description": "Show model, source-selection, protocol, and predictions output options." } ], "id": "export_predictions_ultralytics", "inputs": [ { "flag": "--model", "kind": "file", "name": "model", "required": true }, { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "default": null, "flag": "--split", "kind": "string", "name": "split", "required": false }, { "default": null, "flag": "--source", "kind": "string", "name": "source", "required": false }, { "flag": "--output", "kind": "file", "name": "output", "required": true }, { "default": 640, "flag": "--image-size", "kind": "number", "name": "image_size", "required": false }, { "default": 0.001, "flag": "--conf", "kind": "number", "name": "conf", "required": false }, { "default": 0.7, "flag": "--iou", "kind": "number", "name": "iou", "required": false }, { "default": 32, "flag": "--stride", "kind": "number", "name": "stride", "required": false }, { "default": true, "flag": "--letterbox", "kind": "string", "name": "letterbox", "required": false }, { "flag": "--no-letterbox", "kind": "string", "name": "no_letterbox", "required": false }, { "default": 300, "flag": "--max-det", "kind": "number", "name": "max_det", "required": false }, { "default": null, "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "default": 1, "description": "Recorded backend batch preference; local paths are submitted individually for identity safety.", "flag": "--batch", "kind": "number", "name": "batch", "required": false }, { "default": "cuda", "flag": "--device", "kind": "string", "name": "device", "required": false }, { "flag": "--half", "kind": "string", "name": "half", "required": false }, { "default": true, "flag": "--end2end", "kind": "string", "name": "end2end", "required": false }, { "flag": "--no-end2end", "kind": "string", "name": "no_end2end", "required": false }, { "default": null, "flag": "--protocol", "kind": "string", "name": "protocol", "required": false }, { "flag": "--wrap", "kind": "string", "name": "wrap", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false } ], "maturity": "experimental", "outputs": [ { "default": null, "description": "Predictions JSON with exact manifest-image identity, model hash, protocol, runtime version, and execution metadata.", "kind": "file", "name": "predictions_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "ultralytics" ] }, "runner": "python3", "summary": "Run identity-safe Ultralytics inference and export strict YOLOZU predictions JSON without losing source paths in current runtime batching.", "tags": [ "predictions", "ultralytics", "export", "interop", "license-boundary" ] }, { "contracts": { "produces": [ "predictions_json" ] }, "docs": [ "docs/byop_quickstarts.md", "docs/external_inference.md", "docs/predictions_schema.md", "docs/schema_governance.md", "manual/chapters/05_workflows_eval_export.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes YOLOZU predictions JSON from external YOLO-runtime inference.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/export_predictions_yolo_runtime.py", "examples": [ { "command": "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", "description": "YOLO-runtime export bounded to the first eight selected manifest images." }, { "command": "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", "description": "CI-friendly interface-contract smoke without external YOLO runtime." } ], "id": "export_predictions_yolo_runtime", "inputs": [ { "flag": "--model", "kind": "file", "name": "model", "required": true }, { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "description": "Explicit local image file or directory, expanded deterministically; cannot be combined with --max-images.", "flag": "--source", "kind": "string", "name": "source", "required": false }, { "flag": "--output", "kind": "file", "name": "output", "required": true }, { "default": 640, "flag": "--image-size", "kind": "number", "name": "image_size", "required": false }, { "default": 0.001, "flag": "--conf", "kind": "number", "name": "conf", "required": false }, { "default": 0.7, "flag": "--iou", "kind": "number", "name": "iou", "required": false }, { "default": 32, "flag": "--stride", "kind": "number", "name": "stride", "required": false }, { "default": 300, "flag": "--max-det", "kind": "number", "name": "max_det", "required": false }, { "description": "Caps both selected manifest records and actual runtime inference inputs; cannot be combined with --source.", "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "default": 1, "flag": "--batch", "kind": "number", "name": "batch", "required": false }, { "default": "cuda", "flag": "--device", "kind": "string", "name": "device", "required": false }, { "flag": "--half", "kind": "string", "name": "half", "required": false }, { "flag": "--letterbox", "kind": "string", "name": "letterbox", "required": false }, { "flag": "--no-letterbox", "kind": "string", "name": "no_letterbox", "required": false }, { "flag": "--protocol", "kind": "string", "name": "protocol", "required": false }, { "flag": "--end2end", "kind": "string", "name": "end2end", "required": false }, { "flag": "--no-end2end", "kind": "string", "name": "no_end2end", "required": false }, { "description": "Wrap output as {schema_version,predictions,meta}.", "flag": "--wrap", "kind": "string", "name": "wrap", "required": false }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false }, { "description": "Write schema-valid predictions without the external YOLO runtime.", "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false } ], "maturity": "stable", "outputs": [ { "default": null, "description": "Predictions JSON with entry v2 and, when wrapped, wrapper v1, plus selected-input/result cardinality, execution status, and model provenance.", "kind": "file", "name": "predictions_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "external_yolo_runtime", "torch", "numpy" ] }, "runner": "python3", "summary": "Run bounded external YOLO-runtime inference and export explicitly versioned predictions.json with cardinality-checked execution evidence.", "tags": [ "export", "yolo_runtime", "yolov8", "yolo11", "yolo26", "predictions", "e2e", "data.yaml" ] }, { "contracts": { "produces": [ "predictions_json" ] }, "effects": { "fixed_writes": [], "writes": [ { "description": "Writes normalized YOLOZU predictions JSON.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/export_predictions_yolov5.py", "examples": [ { "command": "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", "description": "Convert YOLOv5 detect save-txt outputs to predictions.json." } ], "id": "export_predictions_yolov5", "inputs": [ { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--labels-dir", "kind": "dir", "name": "labels_dir", "required": false }, { "flag": "--json", "kind": "file", "name": "json", "required": false }, { "flag": "--output", "kind": "file", "name": "output", "required": true }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "default": 1.0, "flag": "--conf-default", "kind": "number", "name": "conf_default", "required": false }, { "default": "nms_applied", "flag": "--protocol", "kind": "string", "name": "protocol", "required": false }, { "default": 640, "flag": "--imgsz", "kind": "number", "name": "imgsz", "required": false }, { "default": 0.25, "flag": "--conf", "kind": "number", "name": "conf", "required": false }, { "default": 0.45, "flag": "--iou", "kind": "number", "name": "iou", "required": false }, { "default": 32, "flag": "--stride", "kind": "number", "name": "stride", "required": false }, { "flag": "--letterbox", "kind": "string", "name": "letterbox", "required": false }, { "flag": "--no-letterbox", "kind": "string", "name": "no_letterbox", "required": false }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false } ], "maturity": "experimental", "outputs": [ { "default": null, "description": "Predictions JSON at --output.", "kind": "file", "name": "predictions_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Convert YOLOv5 outputs (save-txt or xyxy JSON) into YOLOZU predictions.json with recorded export_settings.", "tags": [ "export", "yolov5", "yolov8", "yolo11", "yolo26", "predictions", "data.yaml", "nms" ] }, { "contracts": { "produces": [ "predictions_json" ] }, "docs": [ "README.md", "docs/README.md", "docs/byop_quickstarts.md", "docs/interop_yolox.md", "docs/external_inference.md", "docs/predictions_schema.md", "docs/schema_governance.md", "manual/chapters/05_workflows_eval_export.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes YOLOZU predictions JSON from YOLOX backend.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/export_predictions_yolox.py", "examples": [ { "command": "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", "description": "YOLOX export from exp/checkpoint to predictions.json." } ], "id": "export_predictions_yolox", "inputs": [ { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--output", "kind": "file", "name": "output", "required": true }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "description": "Existing YOLOX exp file; required together with --weights for non-dry inference.", "flag": "--exp", "kind": "file", "name": "exp", "required": false }, { "description": "Existing YOLOX checkpoint; required together with --exp for non-dry inference.", "flag": "--weights", "kind": "file", "name": "weights", "required": false }, { "default": "cuda", "flag": "--device", "kind": "string", "name": "device", "required": false }, { "default": 640, "flag": "--imgsz", "kind": "number", "name": "imgsz", "required": false }, { "default": 0.01, "flag": "--score-thr", "kind": "number", "name": "score_thr", "required": false }, { "default": 0.65, "flag": "--nms-thr", "kind": "number", "name": "nms_thr", "required": false }, { "default": 300, "flag": "--topk", "kind": "number", "name": "topk", "required": false }, { "default": "nms_applied", "flag": "--protocol", "kind": "string", "name": "protocol", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false } ], "maturity": "experimental", "outputs": [ { "default": null, "description": "Predictions JSON with wrapper v1, entry v2, execution status, inference-call evidence, and exp/checkpoint provenance; written only after successful non-dry inference.", "kind": "file", "name": "predictions_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "yolox", "torch", "numpy", "opencv-python" ] }, "runner": "python3", "summary": "Run fail-closed YOLOX inference (or dry-run) and export explicitly versioned predictions.json with execution evidence and exp/checkpoint provenance.", "tags": [ "export", "yolox", "coco", "predictions", "interop", "nms" ] }, { "docs": [ "docs/checkpoint_compatibility.md", "docs/tensorrt_pipeline.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Removes any prior requested target, then writes the ONNX model only after checkpoint compatibility succeeds.", "flag": "--onnx", "kind": "file", "scope": "path" }, { "description": "ONNX export metadata with checkpoint compatibility/provenance; prior target is removed before a real export.", "flag": "--onnx-meta", "kind": "file", "scope": "path" }, { "description": "Removes any prior requested target, then writes the TensorRT engine plan after successful ONNX export/build.", "flag": "--engine", "kind": "file", "scope": "path" }, { "description": "Engine build metadata; prior target is removed before a real build.", "flag": "--engine-meta", "kind": "file", "scope": "path" }, { "description": "Writes timing cache.", "flag": "--timing-cache", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/export_trt.py", "examples": [ { "command": "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", "description": "Export ONNX and build a FP16 engine (Linux/NVIDIA)." } ], "id": "export_trt", "inputs": [ { "default": "rtdetr_pose/configs/base.json", "flag": "--config", "kind": "file", "name": "config", "required": false }, { "description": "Optional checkpoint path; full compatibility is required and --skip-onnx is not allowed.", "flag": "--checkpoint", "kind": "file", "name": "checkpoint", "required": false }, { "description": "Explicit transfer/diagnostic opt-in for name-and-shape partial loading; records status=partial in ONNX metadata.", "flag": "--allow-partial-checkpoint", "kind": "string", "name": "allow_partial_checkpoint", "required": false }, { "flag": "--device", "kind": "string", "name": "device", "required": false }, { "flag": "--image-size", "kind": "number", "name": "image_size", "required": false }, { "default": "models/model.onnx", "flag": "--onnx", "kind": "file", "name": "onnx", "required": false }, { "flag": "--onnx-meta", "kind": "file", "name": "onnx_meta", "required": false }, { "flag": "--opset", "kind": "number", "name": "opset", "required": false }, { "flag": "--input-name", "kind": "string", "name": "input_name", "required": false }, { "flag": "--dynamic-hw", "kind": "string", "name": "dynamic_hw", "required": false }, { "default": "engines/model_fp16.plan", "flag": "--engine", "kind": "file", "name": "engine", "required": false }, { "flag": "--engine-meta", "kind": "file", "name": "engine_meta", "required": false }, { "flag": "--precision", "kind": "string", "name": "precision", "required": false }, { "flag": "--min-shape", "kind": "string", "name": "min_shape", "required": false }, { "flag": "--opt-shape", "kind": "string", "name": "opt_shape", "required": false }, { "flag": "--max-shape", "kind": "string", "name": "max_shape", "required": false }, { "flag": "--workspace", "kind": "number", "name": "workspace", "required": false }, { "default": "engines/timing.cache", "flag": "--timing-cache", "kind": "file", "name": "timing_cache", "required": false }, { "flag": "--trtexec", "kind": "string", "name": "trtexec", "required": false }, { "flag": "--extra-args", "kind": "string", "name": "extra_args", "required": false }, { "flag": "--skip-onnx", "kind": "string", "name": "skip_onnx", "required": false }, { "flag": "--skip-engine", "kind": "string", "name": "skip_engine", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "models/model.onnx", "description": "ONNX model artifact written only after compatible or explicitly partial checkpoint loading.", "kind": "file", "name": "onnx_model" }, { "default": "engines/model_fp16.plan", "description": "Engine plan artifact.", "kind": "file", "name": "engine_plan" }, { "default": "engines/timing.cache", "description": "Timing cache artifact.", "kind": "file", "name": "timing_cache" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true, "notes": "ONNX export can run on CPU; engine build requires Linux+NVIDIA+trtexec unless --skip-engine is set." }, "requires": { "python_packages": [ "torch", "onnx" ], "system": [ "trtexec (optional, for engine build)" ] }, "runner": "python3", "summary": "Fail-closed PyTorch → ONNX → TensorRT export route with shared RT-DETR checkpoint compatibility evidence.", "tags": [ "export", "onnx", "tensorrt", "rtdetr_pose" ] }, { "effects": { "fixed_writes": [ { "description": "Download + extract dataset to data/coco128.", "kind": "dir", "path": "data/coco128", "scope": "tree" } ], "writes": [] }, "entrypoint": "tools/fetch_coco128.sh", "examples": [ { "command": "bash tools/fetch_coco128.sh", "description": "Fetch dataset once for tests/smoke." } ], "id": "fetch_coco128", "inputs": [], "maturity": "stable", "outputs": [ { "default": "data/coco128", "description": "Created dataset root.", "kind": "dir", "name": "dataset_root" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": true }, "runner": "bash", "summary": "Fetch tiny COCO subset (YOLO-format) into data/coco128 (official COCO hosting).", "tags": [ "dataset" ] }, { "effects": { "fixed_writes": [], "writes": [ { "description": "Writes models// and meta.json.", "flag": "--out", "kind": "dir", "scope": "tree" }, { "description": "Writes cached downloads.", "flag": "--cache-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "yolozu/cli.py", "examples": [ { "command": "python3 -m yolozu fetch yolox-s-coco --out models --accept-license", "description": "Fetch a packaged model ID to ./models." }, { "command": "python3 -m yolozu fetch yolox-s-coco --out models --cache-dir ~/.cache/yolozu/models --accept-license", "description": "Fetch with explicit cache location." } ], "id": "fetch_model", "inputs": [ { "description": "Model identifier from `yolozu list models`.", "kind": "string", "name": "model_id", "required": true }, { "default": "models", "description": "Output root for fetched artifacts.", "flag": "--out", "kind": "string", "name": "out", "required": false }, { "default": "~/.cache/yolozu/models", "description": "Download cache root.", "flag": "--cache-dir", "kind": "string", "name": "cache_dir", "required": false }, { "description": "Optional registry JSON override.", "flag": "--registry", "kind": "string", "name": "registry", "required": false }, { "description": "Required license acceptance gate before download.", "flag": "--accept-license", "kind": "string", "name": "accept_license", "required": true }, { "description": "Allow fetching models without sha256 in the registry (not recommended).", "flag": "--allow-unsafe", "kind": "string", "name": "allow_unsafe", "required": false }, { "description": "Allow fetching models with non-Apache-friendly licenses (not recommended).", "flag": "--allow-non-apache", "kind": "string", "name": "allow_non_apache", "required": false }, { "default": 3, "description": "Download retry count (default: 3).", "flag": "--retries", "kind": "number", "name": "retries", "required": false }, { "default": 60, "description": "Download timeout in seconds (default: 60).", "flag": "--timeout", "kind": "number", "name": "timeout", "required": false }, { "description": "Force re-download into cache and overwrite output.", "flag": "--force", "kind": "string", "name": "force", "required": false } ], "maturity": "stable", "outputs": [ { "default": null, "description": "Fetched model artifact under models//.", "kind": "file", "name": "artifact" }, { "default": "models//meta.json", "description": "Metadata file with source/version/license/sha256/created_at.", "kind": "file", "name": "meta_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": true }, "runner": "python3", "summary": "Download a model artifact with cache reuse, sha256 pinning, and explicit license/integrity gates.", "tags": [ "models", "download", "interop", "yolo", "yolox", "detectron2", "mmdetection" ] }, { "docs": [ "docs/cpu_only_dod.md", "README.md", "Readme_jp.md", "manual/chapters/02_installation.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Creates a clean virtual environment, command logs, and stable-lane evidence.", "flag": "--run-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "scripts/fresh_install_journey.sh", "examples": [ { "command": "bash scripts/fresh_install_journey.sh --run-dir /tmp/yolozu_fresh_install", "description": "Install the latest public PyPI release and run the stable lane in a new environment." }, { "command": "bash scripts/fresh_install_journey.sh --python python3.12 --package yolozu==4.5.1 --run-dir /tmp/yolozu_4_5_1_py312", "description": "Reproduce the verified 4.5.1 public-PyPI matrix evidence; this historical pin is not advanced by release automation.", "release_version_evidence": "docs/ssot_capability_coverage_audit.md#confirmed-checks", "release_version_policy": "historical" }, { "command": "bash scripts/fresh_install_journey.sh --help", "description": "Show fresh-install journey options." } ], "id": "fresh_install_journey", "inputs": [ { "default": "python3", "description": "Python executable used to create the clean virtual environment.", "flag": "--python", "kind": "string", "name": "python", "required": false }, { "default": "yolozu", "description": "Public PyPI package spec: yolozu or yolozu==VERSION.", "flag": "--package", "kind": "string", "name": "package", "required": false }, { "default": "reports/fresh_install_journey", "description": "New output directory; existing paths are rejected to preserve fresh-install evidence.", "flag": "--run-dir", "kind": "dir", "name": "run_dir", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/fresh_install_journey/fresh_install_journey_report.json", "description": "Environment, resolved version, commands, elapsed times, exit codes, and artifact paths.", "kind": "file", "name": "journey_report" }, { "default": "reports/fresh_install_journey/dod/dod_cpu_smoke_report.json", "description": "Nested stable-lane DoD report from the installed package.", "kind": "file", "name": "dod_report" }, { "default": "reports/fresh_install_journey/logs", "description": "Virtual-environment creation, install, and stable-lane output logs.", "kind": "dir", "name": "logs" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": true }, "runner": "bash", "summary": "Install YOLOZU from public PyPI in a clean environment and record the complete stable-lane journey.", "tags": [ "adoption", "onboarding", "packaging", "pypi", "smoke" ] }, { "docs": [ "docs/ci_incidents.md", "README.md", "manual/chapters/11_troubleshooting.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes deterministic CI dummy ONNX model.", "flag": "--out", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/ci/gen_dummy_dets_onnx.py", "examples": [ { "command": "python3 tools/ci/gen_dummy_dets_onnx.py --out reports/ci_trt_smoke/model.onnx --shape 1x3x64x64 --opset 17 --ir-version 11", "description": "Generate CI dummy model with ORT-compatible IR version." } ], "id": "gen_ci_dummy_dets_onnx", "inputs": [ { "flag": "--out", "kind": "file", "name": "out", "required": true }, { "default": "images", "flag": "--input-name", "kind": "string", "name": "input_name", "required": false }, { "default": "output0", "flag": "--output-name", "kind": "string", "name": "output_name", "required": false }, { "default": "1x3x64x64", "flag": "--shape", "kind": "string", "name": "shape", "required": false }, { "default": 17, "flag": "--opset", "kind": "number", "name": "opset", "required": false }, { "default": 11, "flag": "--ir-version", "kind": "number", "name": "ir_version", "required": false }, { "default": 0.001, "flag": "--alpha", "kind": "number", "name": "alpha", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/ci_trt_smoke/model.onnx", "description": "Generated ONNX model file.", "kind": "file", "name": "onnx_model" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "onnx" ] }, "runner": "python3", "summary": "Generate a tiny deterministic ONNX model for CI TensorRT/ONNXRuntime smoke parity checks.", "tags": [ "ci", "onnx", "smoke", "tensorrt", "onnxruntime" ] }, { "docs": [ "docs/ci_incidents.md", "README.md", "manual/chapters/11_troubleshooting.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes minimal YOLO smoke dataset tree (images/ + labels/).", "flag": "--out", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/ci/gen_smoke_dataset.py", "examples": [ { "command": "python3 tools/ci/gen_smoke_dataset.py --out reports/ci_trt_smoke/dataset --split val --hw 48x64", "description": "Generate tiny dataset for exporter smoke checks." } ], "id": "gen_ci_smoke_dataset", "inputs": [ { "flag": "--out", "kind": "dir", "name": "out", "required": true }, { "default": "val", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "default": "000001", "flag": "--image-stem", "kind": "string", "name": "image_stem", "required": false }, { "default": "48x64", "flag": "--hw", "kind": "string", "name": "hw", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/ci_trt_smoke/dataset", "description": "Generated smoke dataset root directory.", "kind": "dir", "name": "dataset_root" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "numpy", "Pillow" ] }, "runner": "python3", "summary": "Generate a minimal YOLO-format dataset for CI exporter and parity smoke tests.", "tags": [ "ci", "dataset", "smoke" ] }, { "contracts": { "consumes": [ "adaptive_vision_roadmap_json" ] }, "docs": [ "docs/roadmap.md", "reports/adaptive_vision_roadmap.md", "yolozu/data/manifest/README.md" ], "effects": { "fixed_writes": [ { "description": "Regenerates the canonical adaptive vision roadmap report.", "kind": "file", "path": "reports/adaptive_vision_roadmap.md", "scope": "path" } ], "writes": [ { "description": "Optional repository-local generated adaptive vision roadmap report path.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/generate_adaptive_vision_roadmap.py", "examples": [ { "command": "python3 tools/generate_adaptive_vision_roadmap.py --check --json", "description": "Verify that the tracked roadmap report matches the packaged JSON projection." }, { "command": "python3 tools/generate_adaptive_vision_roadmap.py --source yolozu/data/manifest/adaptive_vision_roadmap.json --output reports/adaptive_vision_roadmap.md", "description": "Regenerate the human-readable adaptive vision roadmap projection." } ], "id": "generate_adaptive_vision_roadmap", "inputs": [ { "default": "yolozu/data/manifest/adaptive_vision_roadmap.json", "flag": "--source", "kind": "file", "name": "source", "required": false }, { "default": "reports/adaptive_vision_roadmap.md", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--check", "kind": "string", "name": "check", "required": false }, { "flag": "--json", "kind": "string", "name": "json", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/adaptive_vision_roadmap.md", "description": "Generated human-readable roadmap projection.", "kind": "file", "name": "adaptive_vision_roadmap_md" }, { "description": "Generation or drift-check status.", "kind": "stdout", "name": "stdout" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false }, "runner": "python3", "summary": "Generate the adaptive vision roadmap report from its packaged JSON projection.", "tags": [ "docs", "generated-docs", "roadmap", "ssot" ] }, { "docs": [ "docs/benchmark_support_matrix.md", "docs/benchmark_mode.md", "docs/manifest_authoring_workflow.md" ], "effects": { "fixed_writes": [ { "description": "Regenerates the canonical benchmark support matrix Markdown.", "kind": "file", "path": "docs/benchmark_support_matrix.md", "scope": "path" } ], "writes": [ { "description": "Optional generated benchmark support matrix output path.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/generate_benchmark_support_matrix.py", "examples": [ { "command": "python3 tools/generate_benchmark_support_matrix.py --check --json", "description": "Verify the generated benchmark support matrix is in sync with metadata." }, { "command": "python3 tools/generate_benchmark_support_matrix.py --metadata yolozu/data/manifest/benchmark_support.json --output docs/benchmark_support_matrix.md", "description": "Regenerate the canonical benchmark support matrix from support metadata." } ], "id": "generate_benchmark_support_matrix", "inputs": [ { "default": "yolozu/data/manifest/benchmark_support.json", "flag": "--metadata", "kind": "file", "name": "metadata", "required": false }, { "default": "docs/benchmark_support_matrix.md", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--check", "kind": "string", "name": "check", "required": false }, { "flag": "--json", "kind": "string", "name": "json", "required": false } ], "maturity": "stable", "outputs": [ { "default": "docs/benchmark_support_matrix.md", "description": "Generated benchmark support matrix Markdown.", "kind": "file", "name": "benchmark_support_matrix_md" }, { "description": "Generation or drift-check status.", "kind": "stdout", "name": "stdout" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false }, "runner": "python3", "summary": "Generate the canonical benchmark support matrix from support metadata.", "tags": [ "benchmark", "docs", "generated-docs", "manifest" ] }, { "docs": [ "docs/llm_integrations.md", "docs/mcp_extension_architecture.md", "docs/generated/mcp_actions_tool_reference.md", "manual/chapters/20_llm_mcp_integrations.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes generated MCP/Actions interface contract JSON.", "flag": "--json-out", "kind": "file", "scope": "path" }, { "description": "Writes generated MCP/Actions interface contract Markdown.", "flag": "--md-out", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/generate_integration_tool_reference.py", "examples": [ { "command": "python3 tools/generate_integration_tool_reference.py", "description": "Generate checked-in MCP/Actions reference docs." }, { "command": "python3 tools/generate_integration_tool_reference.py --check", "description": "CI drift gate: fail when generated reference is stale." } ], "id": "generate_integration_tool_reference", "inputs": [ { "default": "docs/generated/mcp_actions_tool_reference.json", "flag": "--json-out", "kind": "file", "name": "json_out", "required": false }, { "default": "docs/generated/mcp_actions_tool_reference.md", "flag": "--md-out", "kind": "file", "name": "md_out", "required": false }, { "flag": "--check", "kind": "string", "name": "check", "required": false } ], "maturity": "stable", "outputs": [ { "default": null, "description": "Generated machine-readable MCP/Actions interface contract.", "kind": "file", "name": "contract_json" }, { "default": null, "description": "Generated human-readable MCP/Actions interface contract.", "kind": "file", "name": "contract_md" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Generate the MCP↔Actions interface contract reference from tool_runner + server wrappers and fail on drift in check mode.", "tags": [ "mcp", "actions", "docs", "contract", "automation" ] }, { "docs": [ "docs/case_studies/maskrcnn_eager_torchscript.md", "docs/tools_index.md", "manual/chapters/09_parity_bench_protocols.tex" ], "effects": { "fixed_writes": [ { "description": "Writes the committed default case-study evidence bundle after treating an existing bundle as an implicit baseline.", "kind": "dir", "path": "docs/assets/case_studies/maskrcnn_eager_torchscript", "scope": "tree" } ], "writes": [ { "description": "Publishes staged wrapped predictions, evaluation/parity reports, protocol/environment/source evidence, reproduction identity when a baseline exists, SVG, and checksums after all checks pass.", "flag": "--output-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/generate_runtime_parity_case_study.py", "examples": [ { "command": "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", "description": "Regenerate the committed eager/TorchScript comparison; an existing output bundle is verified as an implicit baseline before replacement." }, { "command": "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", "description": "Run offline with a local official checkpoint and verify the result against the committed baseline." } ], "id": "generate_runtime_parity_case_study", "inputs": [ { "default": "data/smoke", "description": "YOLO-format dataset whose labels//classes.json declares the standard COCO80 order and sparse category-id mapping.", "flag": "--dataset", "kind": "dir", "name": "dataset", "required": false }, { "default": "val", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "default": 2, "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "default": 0.5, "flag": "--score-threshold", "kind": "number", "name": "score_threshold", "required": false }, { "default": 20, "flag": "--max-detections", "kind": "number", "name": "max_detections", "required": false }, { "default": 2026, "flag": "--seed", "kind": "number", "name": "seed", "required": false }, { "default": 1, "flag": "--threads", "kind": "number", "name": "threads", "required": false }, { "description": "Optional local state_dict; the tool always verifies the pinned official COCO_V1 full SHA-256.", "flag": "--weights", "kind": "file", "name": "weights", "required": false }, { "description": "Optional explicit assertion of the pinned official COCO_V1 full SHA-256.", "flag": "--expected-weights-sha256", "kind": "string", "name": "expected_weights_sha256", "required": false }, { "flag": "--allow-download", "kind": "string", "name": "allow_download", "required": false }, { "default": "docs/assets/case_studies/maskrcnn_eager_torchscript", "description": "Artifact directory. An existing case-study bundle is used as an implicit baseline and preserved if reproduction checks fail.", "flag": "--output-dir", "kind": "dir", "name": "output_dir", "required": false }, { "description": "Optional prior bundle for strict reproduction comparison; may equal --output-dir because generation is staged.", "flag": "--baseline-dir", "kind": "dir", "name": "baseline_dir", "required": false }, { "default": 1e-08, "flag": "--metric-atol", "kind": "number", "name": "metric_atol", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "docs/assets/case_studies/maskrcnn_eager_torchscript", "description": "Case-study bundle containing wrapped predictions, reports, protocol/environment/source evidence, SVG, reproduction identity when a baseline exists, and checksums.", "kind": "dir", "name": "case_study_artifacts" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true, "notes": "The pinned case study runs on CPU. Network is used only when --allow-download is explicit and the official checkpoint cache is empty." }, "requires": { "network": true, "python_packages": [ "torch", "torchvision", "Pillow", "pycocotools" ] }, "runner": "python3", "summary": "Generate and verify a real Mask R-CNN PyTorch eager versus TorchScript comparison through YOLOZU's stable evaluation lane.", "tags": [ "adoption", "case-study", "evaluation", "parity", "torchscript" ] }, { "effects": { "fixed_writes": [ { "description": "Creates/updates bundled smoke assets (images/val, labels/val, standard COCO80 classes mapping, predictions).", "kind": "dir", "path": "data/smoke", "scope": "tree" } ], "writes": [] }, "entrypoint": "tools/generate_smoke_assets.py", "examples": [ { "command": "python3 tools/generate_smoke_assets.py", "description": "Rebuild bundled smoke assets deterministically." }, { "command": "python3 tools/generate_smoke_assets.py --help", "description": "Show the smoke asset generator usage without modifying files." } ], "id": "generate_smoke_assets", "inputs": [ { "flag": "--help", "kind": "string", "name": "help", "required": false } ], "maturity": "stable", "outputs": [ { "default": "data/smoke", "description": "Smoke dataset root.", "kind": "dir", "name": "dataset_root" }, { "default": "data/smoke/predictions/predictions_dummy.json", "description": "Fixed dummy predictions (schema v1).", "kind": "file", "name": "predictions" }, { "default": "data/smoke/labels/val/classes.json", "description": "Standard COCO80 class names and sparse category-id mapping.", "kind": "file", "name": "classes_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false }, "runner": "python3", "summary": "Generate deterministic offline smoke assets under data/smoke from local data/coco128.", "tags": [ "dataset", "smoke" ] }, { "docs": [ "docs/python_api.md", "docs/llm_discovery.md", "docs/web_docs_content.json", "docs/web_docs_plan.md", "docs/generated/web_docs/index.html" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Atomically replaces only an empty or provenance-owned generated web-docs directory; refuses symlinks, critical directories, and unowned content.", "flag": "--output", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/generate_web_docs.py", "examples": [ { "command": "python3 tools/generate_web_docs.py", "description": "Regenerate searchable HTML, agent Markdown, llms.txt, capability JSON, and sitemap.xml after validating repository-local sources and safe HTTPS/internal links." }, { "command": "python3 tools/generate_web_docs.py --check --json", "description": "Fail without writing when manifest, schema, content, or asset changes have not been regenerated." } ], "id": "generate_web_docs", "inputs": [ { "default": "tools/manifest.json", "flag": "--manifest", "kind": "file", "name": "manifest", "required": false }, { "default": "docs/schemas", "flag": "--schemas", "kind": "dir", "name": "schemas", "required": false }, { "default": "docs/web_docs_content.json", "flag": "--content", "kind": "file", "name": "content", "required": false }, { "default": "docs/generated/web_docs", "flag": "--output", "kind": "dir", "name": "output", "required": false }, { "flag": "--check", "kind": "string", "name": "check", "required": false }, { "flag": "--json", "kind": "string", "name": "json", "required": false } ], "maturity": "stable", "outputs": [ { "default": "docs/generated/web_docs", "description": "Generated static web-docs bundle: HTML with JSON-LD, start.md, agents.md, llms.txt, capabilities.json, sitemap.xml, search/assets, and provenance.json with source hashes and a complete file inventory.", "kind": "dir", "name": "web_docs_bundle" }, { "description": "Generation or drift-check status.", "kind": "stdout", "name": "stdout" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false }, "runner": "python3", "summary": "Safely generate searchable web docs and LLM discovery/onboarding files from repository-local SSOT sources, schemas, and curated evidence.", "tags": [ "docs", "generated-docs", "manifest", "onboarding", "schemas", "web" ] }, { "docs": [ "docs/image_service_mcp.md", "docs/llm_integrations.md", "docs/openai_mcp_actions.md" ], "effects": { "fixed_writes": [ { "kind": "dir", "path": "runs/mcp_image_service", "scope": "tree" } ], "writes": [] }, "entrypoint": "yolozu/integrations/mcp_server.py", "examples": [ { "command": "Call the get_image_job MCP tool with the opaque job_id returned by submit_image_job.", "description": "Read bounded status, abstention, or completed predictions without exposing service storage paths." } ], "id": "get_image_job", "inputs": [ { "description": "Opaque image job identity.", "kind": "string", "name": "job_id", "required": true } ], "maturity": "experimental", "outputs": [ { "description": "Bounded job status and, when complete, managed predictions, provenance, and checksums.", "kind": "json", "name": "job_status_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false, "python_packages": [ "mcp", "Pillow" ] }, "runner": "python3", "summary": "Return bounded status and result data for one opaque image job, enforcing tenant polling and expiry limits without exposing internal paths.", "tags": [ "ai-first", "image-service", "mcp", "read-only", "security" ] }, { "docs": [ "docs/runpod_gpu_validation_split.md", "docs/doctor_diagnostics.md", "manual/chapters/17_realtime_batch_inference.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes preflight split report JSON.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/gpu_validation_preflight.py", "examples": [ { "command": "python3 tools/gpu_validation_preflight.py --output reports/gpu_validation_preflight.json", "description": "Generate local/GPU split report for the full GPU validation sweep." }, { "command": "python3 tools/gpu_validation_preflight.py --strict --output reports/gpu_validation_preflight.json", "description": "Fail CI when local prerequisites are still blocked." } ], "id": "gpu_validation_preflight", "inputs": [ { "default": "reports/gpu_validation_preflight.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/gpu_validation_preflight.json", "description": "JSON report artifact.", "kind": "file", "name": "report_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true, "notes": "Designed for local planning; reports GPU-required steps and runtime capability gaps." }, "runner": "python3", "summary": "Generate a preflight report that splits the YOLOZU-zisn GPU sweep into local-executable checks and GPU-runtime checks.", "tags": [ "gpu", "runpod", "validation", "doctor", "parity" ] }, { "docs": [ "docs/hpo_sweep.md" ], "effects": { "fixed_writes": [ { "description": "Default results JSONL (config can override).", "kind": "file", "path": "reports/hpo_sweep.jsonl", "scope": "path" }, { "description": "Default results CSV (config can override).", "kind": "file", "path": "reports/hpo_sweep.csv", "scope": "path" }, { "description": "Default results Markdown table (config can override).", "kind": "file", "path": "reports/hpo_sweep.md", "scope": "path" } ], "writes": [] }, "entrypoint": "tools/hpo_sweep.py", "examples": [ { "command": "python3 tools/hpo_sweep.py --config docs/hpo_sweep_example.json --dry-run", "description": "Dry-run example sweep." } ], "id": "hpo_sweep", "inputs": [ { "flag": "--config", "kind": "file", "name": "config", "required": true }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "flag": "--max-runs", "kind": "number", "name": "max_runs", "required": false }, { "flag": "--resume", "kind": "string", "name": "resume", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/hpo_sweep.jsonl", "description": "Result jsonl report artifact.", "kind": "file", "name": "result_jsonl" }, { "default": "reports/hpo_sweep.csv", "description": "Result csv CSV artifact.", "kind": "file", "name": "result_csv" }, { "default": "reports/hpo_sweep.md", "description": "Result Markdown artifact.", "kind": "file", "name": "result_md" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Run a configurable parameter sweep (grid or list) and emit JSONL/CSV/MD results.", "tags": [ "sweep", "hpo" ] }, { "docs": [ "docs/image_service_mcp.md", "docs/llm_integrations.md", "docs/openai_mcp_actions.md" ], "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "yolozu/integrations/mcp_server.py", "examples": [ { "command": "Call the image_service_capabilities MCP tool before uploading an image.", "description": "Inspect the bounded media, task, execution, and retention limits without creating service storage." } ], "id": "image_service_capabilities", "inputs": [], "maturity": "experimental", "outputs": [ { "description": "Bounded image-service capabilities and safety defaults.", "kind": "json", "name": "capabilities_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false, "python_packages": [ "mcp", "Pillow" ] }, "runner": "python3", "summary": "Describe image-service capacity, per-60-second request limits, retention, and isolation boundaries without selecting or executing a model.", "tags": [ "ai-first", "image-service", "mcp", "read-only", "security" ] }, { "docs": [ "docs/openai_image_service_plugin.md", "README.md", "Readme_jp.md", "manual/chapters/20_llm_mcp_integrations.tex" ], "effects": { "fixed_writes": [], "temporary_writes": [ "OS temporary yolozu-plugin-* workspace; image assets and job data removed on normal exit, may remain after forced termination." ], "writes": [] }, "entrypoint": "plugins/yolozu-image-service/scripts/image_service_client.py", "examples": [ { "command": "python3 plugins/yolozu-image-service/scripts/image_service_client.py --help", "description": "Inspect local client options without loading MCP dependencies." }, { "command": "python3 plugins/yolozu-image-service/scripts/image_service_client.py --capabilities", "description": "Check the bounded installed service without an image or provider call." }, { "command": "python3 plugins/yolozu-image-service/scripts/image_service_client.py --image data/smoke/images/val/000000000009.jpg --class cat", "description": "Preview selection through a separate temporary local stdio session." } ], "id": "image_service_plugin_client", "inputs": [ { "flag": "--help", "kind": "string", "name": "help", "required": false }, { "description": "Read capabilities without uploading; mutually exclusive with --image.", "flag": "--capabilities", "kind": "string", "name": "capabilities", "required": false }, { "description": "User-selected regular local JPEG/PNG/WebP, at most 8 MiB; never a URL.", "flag": "--image", "kind": "file", "name": "image", "required": false }, { "description": "Repeatable target label; required with --image.", "flag": "--class", "kind": "string", "name": "classes", "required": false }, { "description": "Opt in to processing; does not qualify or activate a model.", "flag": "--execute", "kind": "string", "name": "execute", "required": false }, { "default": 60, "description": "Finite job-wait seconds in 1..120; expiry stops queued/running work. Transport and process cleanup have separate bounded waits.", "flag": "--timeout", "kind": "number", "name": "timeout", "required": false } ], "maturity": "experimental", "outputs": [ { "description": "Capability or terminal job response, with abstention preserved; exit 0 is request completion, not proof of inference.", "kind": "stdout", "name": "result_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false, "python_packages": [ "mcp", "PIL", "yolozu" ] }, "runner": "python3", "summary": "Send one user-selected local image through a temporary bounded stdio MCP session; preview by default, preserve abstention, and remove temporary image/job data on normal exit.", "tags": [ "mcp", "plugin", "image-service" ] }, { "effects": { "fixed_writes": [], "writes": [ { "description": "Writes dataset.json and labels//classes mapping files.", "flag": "--output", "kind": "dir", "scope": "path" } ] }, "entrypoint": "tools/import_yolo_data_yaml.py", "examples": [ { "command": "python3 tools/import_yolo_data_yaml.py --data-yaml data/coco-yolo/data.yaml --split val2017 --output data/yolo_wrapper --force", "description": "Import YOLO-style data.yaml for the YOLOZU eval entrypoint." } ], "id": "import_yolo_data_yaml", "inputs": [ { "flag": "--data-yaml", "kind": "file", "name": "data_yaml", "required": true }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--output", "kind": "dir", "name": "output", "required": true }, { "flag": "--force", "kind": "string", "name": "force", "required": false } ], "maturity": "stable", "outputs": [ { "default": null, "description": "Output dataset wrapper JSON under --output/dataset.json.", "kind": "file", "name": "dataset_wrapper_json" }, { "default": null, "description": "Output classes mapping under --output/labels//classes.json.", "kind": "file", "name": "classes_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Import YOLO-style data.yaml into a YOLOZU dataset wrapper and classes mapping (classes.json/classes.txt).", "tags": [ "import", "yolo_runtime", "data.yaml", "yolov8", "yolo11", "yolo26", "coco" ] }, { "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "yolozu/cli.py", "examples": [ { "command": "python3 -m yolozu list models", "description": "List packaged model IDs." }, { "command": "python3 -m yolozu list models --registry path/to/model_registry.json --json", "description": "List with custom registry in JSON." } ], "id": "list_models", "inputs": [ { "description": "Optional registry JSON override.", "flag": "--registry", "kind": "string", "name": "registry", "required": false }, { "description": "Emit JSON list output.", "flag": "--json", "kind": "string", "name": "json", "required": false } ], "maturity": "stable", "outputs": [ { "description": "Model list table or JSON.", "kind": "stdout", "name": "stdout" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false }, "runner": "python3", "summary": "List fetchable model IDs from the built-in (or custom) model registry.", "tags": [ "models", "registry", "interop" ] }, { "docs": [ "docs/dataset_processing_matrix.md", "docs/dataset_contract.md", "reports/dataset_roundtrip_2026-07-27.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes an ownership-marked subset tree under --out, including selected images/labels, referenced mask/depth/CAD sidecars, keypoint metadata, and provenance hashes.", "flag": "--out", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/make_subset_dataset.py", "examples": [ { "command": "python3 tools/make_subset_dataset.py --dataset data/coco128 --split train2017 --n 50 --seed 0 --out reports/coco128_50", "description": "Create a frozen 50-image subset with referenced training sidecars and file hashes for ablations." } ], "id": "make_subset_dataset", "inputs": [ { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "default": null, "flag": "--split", "kind": "string", "name": "split", "required": false }, { "default": 50, "flag": "--n", "kind": "number", "name": "n", "required": false }, { "default": 0, "flag": "--seed", "kind": "number", "name": "seed", "required": false }, { "default": "reports/subset_dataset", "flag": "--out", "kind": "dir", "name": "out", "required": false }, { "description": "Copy selected images, labels, and referenced sidecars instead of creating symlinks.", "flag": "--copy", "kind": "string", "name": "copy", "required": false }, { "description": "Replace only a non-symlink output bearing the YOLOZU subset ownership marker; unowned and protected paths are refused.", "flag": "--overwrite", "kind": "string", "name": "overwrite", "required": false }, { "flag": "--strategy", "kind": "string", "name": "strategy", "required": false } ], "maturity": "stable", "outputs": [ { "default": null, "description": "Subset dataset root created at --out.", "kind": "dir", "name": "dataset_root" }, { "default": "/subset.json", "description": "Subset metadata with selection, per-file SHA-256, byte/runtime totals, and source metadata hashes.", "kind": "file", "name": "subset_json" }, { "default": "/subset_images.txt", "description": "Frozen image list.", "kind": "file", "name": "subset_images_txt" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Create a deterministic, provenance-hashed YOLO subset while preserving referenced training sidecars and refusing unowned output replacement.", "tags": [ "dataset" ] }, { "contracts": { "produces": [ "metrics_report_json" ] }, "docs": [ "docs/benchmark_latency.md", "docs/tensorrt_pipeline.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes metrics report JSON.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/measure_trt_latency.py", "examples": [ { "command": "python3 tools/measure_trt_latency.py --engine engines/yolo26n_fp16.plan --shape 1x3x640x640 --iterations 200 --warmup 20 --output reports/latency_yolo26n.json", "description": "Measure latency (Linux/NVIDIA)." } ], "id": "measure_trt_latency", "inputs": [ { "flag": "--engine", "kind": "file", "name": "engine", "required": false }, { "flag": "--shape", "kind": "string", "name": "shape", "required": false }, { "flag": "--input-name", "kind": "string", "name": "input_name", "required": false }, { "default": 200, "flag": "--iterations", "kind": "number", "name": "iterations", "required": false }, { "default": 20, "flag": "--warmup", "kind": "number", "name": "warmup", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "flag": "--notes", "kind": "string", "name": "notes", "required": false }, { "default": "reports/latency_trt.json", "flag": "--output", "kind": "file", "name": "output", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/latency_trt.json", "description": "JSON report artifact.", "kind": "file", "name": "report_json" } ], "platform": { "cpu_ok": true, "gpu_required": true, "linux_ok": true, "macos_ok": false }, "requires": { "python_packages": [ "tensorrt", "numpy" ], "system": [ "CUDA bindings (pycuda or cuda-python)" ] }, "runner": "python3", "summary": "Measure a TensorRT engine's latency/FPS and write a metrics report JSON.", "tags": [ "benchmark", "tensorrt" ] }, { "contract_outputs": { "predictions_json": "predictions_json" }, "contracts": { "consumes": [ "predictions_json" ], "produces": [ "predictions_json" ] }, "effects": { "fixed_writes": [], "writes": [ { "description": "Writes normalized predictions JSON.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/normalize_predictions.py", "examples": [ { "command": "python3 tools/normalize_predictions.py --input reports/predictions.json --output reports/predictions_norm.json --classes data/coco-yolo/labels/val2017/classes.json --wrap", "description": "Remap COCO category_id -> contiguous class_id and wrap output." } ], "id": "normalize_predictions", "inputs": [ { "flag": "--input", "kind": "file", "name": "input", "required": true }, { "flag": "--output", "kind": "file", "name": "output", "required": true }, { "flag": "--classes", "kind": "file", "name": "classes", "required": false }, { "flag": "--assume-class-id-is-category-id", "kind": "string", "name": "assume_class_id_is_category_id", "required": false }, { "flag": "--wrap", "kind": "string", "name": "wrap", "required": false } ], "maturity": "stable", "outputs": [ { "default": null, "description": "Normalized predictions JSON at --output.", "kind": "file", "name": "predictions_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Normalize prediction class ids (category_id↔class_id) and optionally wrap with meta.", "tags": [ "predictions", "transform" ] }, { "contracts": { "produces": [ "training_orchestration_report_json" ] }, "docs": [ "docs/training_backend_interface.md", "docs/training_capability_matrix.md", "docs/training_orchestration.md", "docs/tools_index.md", "manual/chapters/04_cli_reference.tex", "manual/chapters/07_training_run_contract.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes orchestration report JSON.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/orchestrate_train.py", "examples": [ { "command": "python3 tools/orchestrate_train.py --spec reports/train_orchestration_spec.json --output reports/training_orchestration_report.json", "description": "Plan a multi-backend training batch without executing it." }, { "command": "python3 -m yolozu train-orchestrate --spec reports/train_orchestration_spec.json --output reports/training_orchestration_report.json --execute", "description": "Execute the planned batch through the top-level CLI alias." }, { "command": "python3 tools/orchestrate_train.py --spec reports/train_orchestration_spec.json --output reports/training_orchestration_report.json --registry-out reports/training_registry.jsonl --execute", "description": "Execute a batch, append the shared registry, and record counts.by_backend plus registry_summary in the orchestration report." } ], "id": "orchestrate_train", "inputs": [ { "flag": "--spec", "kind": "file", "name": "spec", "required": true }, { "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--execute", "kind": "string", "name": "execute", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "flag": "--stop-on-failure", "kind": "string", "name": "stop_on_failure", "required": false }, { "flag": "--registry-out", "kind": "file", "name": "registry_out", "required": false } ], "maturity": "experimental", "outputs": [ { "default": null, "description": "Machine-readable orchestration report for the whole experiment batch.", "kind": "file", "name": "training_orchestration_report_json" }, { "default": null, "description": "Optional append-only JSONL training registry file when --registry-out is set.", "kind": "file", "name": "training_registry_jsonl" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "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.", "tags": [ "training", "orchestration", "platform" ] }, { "contracts": { "consumes": [ "seg_dataset_json" ], "produces": [ "segmentation_predictions_json" ] }, "docs": [ "docs/interop_detectron2_mmdet.md", "docs/tools_index.md", "docs/training_inference_export.md", "manual/chapters/04_cli_reference.tex", "manual/chapters/07_training_run_contract.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes segmentation predictions JSON packaged from a class-id mask directory.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/package_segmentation_predictions.py", "examples": [ { "command": "python3 tools/package_segmentation_predictions.py --dataset-json data/seg/dataset.json --masks-dir reports/mmseg_masks --output reports/segmentation_predictions_mmseg.json", "description": "Package a segmentation mask directory into the segmentation predictions interface contract." } ], "id": "package_segmentation_predictions", "inputs": [ { "flag": "--dataset-json", "kind": "file", "name": "dataset_json", "required": true }, { "flag": "--masks-dir", "kind": "dir", "name": "masks_dir", "required": true }, { "flag": "--output", "kind": "file", "name": "output", "required": true }, { "flag": "--suffix", "kind": "string", "name": "suffix", "required": false }, { "flag": "--relative-to-output", "kind": "string", "name": "relative_to_output", "required": false }, { "flag": "--force", "kind": "string", "name": "force", "required": false } ], "maturity": "experimental", "outputs": [ { "default": null, "description": "Segmentation predictions interface contract JSON.", "kind": "file", "name": "segmentation_predictions_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Package a class-id mask directory into the YOLOZU segmentation predictions interface contract.", "tags": [ "segmentation", "predictions", "interop", "export" ] }, { "docs": [ "CONTRIBUTING.md", "docs/release_reliability_checklist.md", "docs/ssot_capability_coverage_audit.md" ], "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "scripts/pre_push.sh", "examples": [ { "command": "bash scripts/pre_push.sh", "description": "Run default pre-push gates." }, { "command": "bash scripts/pre_push.sh --skip-real-preflight", "description": "Run pre-push gates without real-image dataset preflight." }, { "command": "bash scripts/pre_push.sh --skip-smoke", "description": "Run pre-push gates without running scripts/smoke.sh." } ], "id": "pre_push", "inputs": [ { "flag": "--skip-ruff", "kind": "string", "name": "skip_ruff", "required": false }, { "flag": "--skip-tests", "kind": "string", "name": "skip_tests", "required": false }, { "flag": "--skip-smoke", "kind": "string", "name": "skip_smoke", "required": false }, { "flag": "--skip-real-preflight", "kind": "string", "name": "skip_real_preflight", "required": false }, { "flag": "--prepare-real-data", "kind": "string", "name": "prepare_real_data", "required": false } ], "maturity": "stable", "outputs": [], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false }, "runner": "bash", "summary": "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.", "tags": [ "ci", "devx", "prepush", "lint", "tests" ] }, { "effects": { "fixed_writes": [], "writes": [ { "description": "Writes prepared segmentation dataset layout under --out (manifest + optional symlinks/copies).", "flag": "--out", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/prepare_ade20k_seg.py", "examples": [ { "command": "python3 tools/prepare_ade20k_seg.py --ade20k-root /path/to/ADEChallengeData2016 --split train --out data/ade20k_seg --mode manifest", "description": "Create a manifest-only dataset.json (no copying)." } ], "id": "prepare_ade20k_seg", "inputs": [ { "flag": "--ade20k-root", "kind": "dir", "name": "ade20k_root", "required": true }, { "flag": "--out", "kind": "dir", "name": "out", "required": true }, { "default": "train", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--ignore-index", "kind": "number", "name": "ignore_index", "required": false }, { "flag": "--mode", "kind": "string", "name": "mode", "required": false }, { "flag": "--force", "kind": "string", "name": "force", "required": false } ], "maturity": "stable", "outputs": [ { "default": null, "description": "Prepared output root created at --out.", "kind": "dir", "name": "dataset_root" }, { "default": "/dataset.json", "description": "dataset.json manifest.", "kind": "file", "name": "dataset_descriptor" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Prepare ADE20K semantic segmentation layout + dataset.json manifest.", "tags": [ "dataset", "ade20k", "segmentation" ] }, { "contract_outputs": { "bop_conversion_report_json": "conversion_report_json" }, "contracts": { "produces": [ "bop_conversion_report_json" ] }, "docs": [ "docs/bop_tless_protocol.md", "docs/dataset_processing_matrix.md", "docs/production_readiness.md", "manual/chapters/16_depth_6dof_symmetry.tex", "reports/bop_pose_readiness_2026-07-28.md", "reports/bop_tless_evidence_2026-07-30.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes an ownership-marked YOLOZU dataset tree, strict BOP sidecars, deterministic CAD subsets/keypoints, prepare_summary.json, and a conversion report under --out.", "flag": "--out", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/prepare_bop_yolozu.py", "examples": [ { "command": "python3 tools/prepare_bop_yolozu.py --bop-root /workspace/bop --split train_primesense --out reports/bop_tless_yolozu --out-split train2017 --partition-modulus 5 --partition-remainder 0 --partition-mode exclude --cad-keypoints 4 --link-images", "description": "Convert a deterministic T-LESS diagnostic training partition with strict masks/depth/object-pose and projected CAD-keypoint sidecars." }, { "command": "python3 tools/prepare_bop_yolozu.py --help", "description": "Show source, partition, CAD, owned-output, and conversion options." } ], "id": "prepare_bop_yolozu", "inputs": [ { "description": "Extracted BOP dataset root.", "flag": "--bop-root", "kind": "dir", "name": "bop_root", "required": true }, { "description": "BOP source split folder name.", "flag": "--split", "kind": "string", "name": "split", "required": true }, { "description": "Ownership-marked output dataset root.", "flag": "--out", "kind": "dir", "name": "out", "required": true }, { "default": "train2017", "flag": "--out-split", "kind": "string", "name": "out_split", "required": false }, { "default": "bbox_visib", "flag": "--bbox-source", "kind": "string", "name": "bbox_source", "required": false }, { "default": 0.0, "flag": "--visib-fract-min", "kind": "number", "name": "visib_fract_min", "required": false }, { "default": null, "flag": "--max-scenes", "kind": "number", "name": "max_scenes", "required": false }, { "default": null, "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "default": null, "flag": "--partition-modulus", "kind": "number", "name": "partition_modulus", "required": false }, { "default": 0, "flag": "--partition-remainder", "kind": "number", "name": "partition_remainder", "required": false }, { "default": "include", "flag": "--partition-mode", "kind": "string", "name": "partition_mode", "required": false }, { "description": "Create image symlinks instead of copies.", "flag": "--link-images", "kind": "string", "name": "link_images", "required": false }, { "default": "obj_id_minus_1", "flag": "--class-map", "kind": "string", "name": "class_map", "required": false }, { "default": 0.001, "description": "BOP translation and CAD point scale to metres.", "flag": "--t-scale", "kind": "number", "name": "t_scale", "required": false }, { "default": null, "description": "Optional BOP model directory; auto-detected under the source root.", "flag": "--models-dir", "kind": "dir", "name": "models_dir", "required": false }, { "default": 1000, "description": "Maximum deterministic CAD points retained per object.", "flag": "--cad-max-points", "kind": "number", "name": "cad_max_points", "required": false }, { "default": 0, "description": "Number of deterministic object-space CAD anchors projected with BOP K/R/t; visibility=2 additionally requires the instance mask_visib pixel.", "flag": "--cad-keypoints", "kind": "number", "name": "cad_keypoints", "required": false }, { "description": "Replace only an output bearing the valid YOLOZU BOP ownership marker.", "flag": "--overwrite", "kind": "string", "name": "overwrite", "required": false }, { "description": "Add a new split only to an owned output without replacing an existing split.", "flag": "--append-owned", "kind": "string", "name": "append_owned", "required": false } ], "maturity": "research", "outputs": [ { "default": null, "description": "Converted ownership-marked YOLOZU dataset root.", "kind": "dir", "name": "dataset_root" }, { "default": "/dataset.json", "description": "Dataset descriptor containing all appended splits.", "kind": "file", "name": "dataset_descriptor" }, { "default": "/conversion_reports/.json", "description": "Conversion, partition, units, model hashes, and license provenance report.", "kind": "file", "name": "conversion_report_json" }, { "default": "/prepare_summary.json", "description": "Strict ground-truth provenance, annotation counts, and qualification checks.", "kind": "file", "name": "prepare_summary_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false }, "runner": "python3", "summary": "Convert BOP rigid-object pose data into an owned YOLOZU dataset with deterministic splits, strict GT sidecars, metre-scaled CAD points/keypoints, and provenance.", "tags": [ "dataset", "bop", "tless", "object_pose", "pose6d", "cad" ] }, { "effects": { "fixed_writes": [], "writes": [ { "description": "Writes prepared segmentation dataset layout under --out (manifest + optional symlinks/copies).", "flag": "--out", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/prepare_cityscapes_seg.py", "examples": [ { "command": "python3 tools/prepare_cityscapes_seg.py --cityscapes-root /path/to/cityscapes --split train --out data/cityscapes_seg --mode manifest", "description": "Create a manifest-only dataset.json (no copying)." } ], "id": "prepare_cityscapes_seg", "inputs": [ { "flag": "--cityscapes-root", "kind": "dir", "name": "cityscapes_root", "required": true }, { "flag": "--out", "kind": "dir", "name": "out", "required": true }, { "default": "train", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--label-type", "kind": "string", "name": "label_type", "required": false }, { "flag": "--mode", "kind": "string", "name": "mode", "required": false }, { "flag": "--force", "kind": "string", "name": "force", "required": false } ], "maturity": "stable", "outputs": [ { "default": null, "description": "Prepared output root created at --out.", "kind": "dir", "name": "dataset_root" }, { "default": "/dataset.json", "description": "dataset.json manifest.", "kind": "file", "name": "dataset_descriptor" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Prepare Cityscapes semantic segmentation layout + dataset.json manifest.", "tags": [ "dataset", "cityscapes", "segmentation" ] }, { "effects": { "fixed_writes": [], "writes": [ { "description": "Writes YOLO-format dataset under --out (labels/ + masks/ + dataset.json).", "flag": "--out", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/prepare_coco_instance_seg.py", "examples": [ { "command": "python3 tools/prepare_coco_instance_seg.py --coco-root /path/to/coco --split val2017 --out data/coco-instance-seg", "description": "Prepare val2017 labels+masks (pycocotools required)." } ], "id": "prepare_coco_instance_seg", "inputs": [ { "flag": "--coco-root", "kind": "dir", "name": "coco_root", "required": true }, { "flag": "--out", "kind": "dir", "name": "out", "required": true }, { "default": "val2017", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--include-crowd", "kind": "string", "name": "include_crowd", "required": false }, { "flag": "--instances-json", "kind": "file", "name": "instances_json", "required": false }, { "flag": "--copy-images", "kind": "string", "name": "copy_images", "required": false }, { "flag": "--max-instances-per-image", "kind": "number", "name": "max_instances_per_image", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false } ], "maturity": "stable", "outputs": [ { "default": null, "description": "YOLO-format dataset root created at --out.", "kind": "dir", "name": "dataset_root" }, { "default": "/dataset.json", "description": "Convenience dataset.json.", "kind": "file", "name": "dataset_descriptor" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Convert official COCO instances JSON into YOLO-format labels + per-instance PNG masks + sidecar metadata for instance-seg eval.", "tags": [ "dataset", "coco", "instance_segmentation" ] }, { "effects": { "fixed_writes": [], "writes": [ { "description": "Writes YOLO-format dataset under --out (labels/ + dataset.json, optionally images/).", "flag": "--out", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/prepare_coco_yolo.py", "examples": [ { "command": "python3 tools/prepare_coco_yolo.py --coco-root /path/to/coco --split val2017 --out data/coco-yolo", "description": "Prepare val2017 labels without copying images." } ], "id": "prepare_coco_yolo", "inputs": [ { "flag": "--coco-root", "kind": "dir", "name": "coco_root", "required": true }, { "flag": "--out", "kind": "dir", "name": "out", "required": true }, { "default": "val2017", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--include-crowd", "kind": "string", "name": "include_crowd", "required": false }, { "flag": "--instances-json", "kind": "file", "name": "instances_json", "required": false }, { "flag": "--copy-images", "kind": "string", "name": "copy_images", "required": false } ], "maturity": "stable", "outputs": [ { "default": null, "description": "YOLO-format dataset root created at --out.", "kind": "dir", "name": "dataset_root" }, { "default": "/dataset.json", "description": "Convenience dataset.json.", "kind": "file", "name": "dataset_descriptor" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Convert official COCO instances JSON into YOLO-format labels + (optional) copy images.", "tags": [ "dataset", "coco" ] }, { "docs": [ "docs/schemas/compatible_host_external_runtime_qualification.schema.json", "docs/training_capability_matrix.md", "docs/external_finetune_smoke.md", "docs/tools_index.md", "reports/external_runtime_compatible_host_evidence_2026-07-30.md", "reports/external_runtime_compatible_host_primary_2026-07-30.json", "reports/external_runtime_compatible_host_primary_dataset_2026-07-30.json", "reports/external_runtime_compatible_host_primary_tao_2026-07-30.json", "reports/external_runtime_compatible_host_primary_workflow_2026-07-30.json", "reports/external_runtime_compatible_host_independent_2026-07-30.json", "reports/external_runtime_compatible_host_independent_dataset_2026-07-30.json", "reports/external_runtime_compatible_host_independent_tao_2026-07-30.json", "reports/external_runtime_compatible_host_independent_workflow_2026-07-30.json" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Creates fresh detection, keypoint, and segmentation runtime fixture trees.", "flag": "--output", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/prepare_external_runtime_smoke_datasets.py", "examples": [ { "command": "python3 tools/prepare_external_runtime_smoke_datasets.py --source data/real_multitask_fewshot --split train --output /tmp/yolozu-runtime-fixtures --max-images 6", "description": "Prepare bounded task-family fixtures for external runtime availability training." }, { "command": "python3 tools/prepare_external_runtime_smoke_datasets.py --help", "description": "Show source, split, output, and size-bound options." } ], "id": "prepare_external_runtime_smoke_datasets", "inputs": [ { "flag": "--source", "kind": "dir", "name": "source", "required": true }, { "default": "train", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--output", "kind": "dir", "name": "output", "required": true }, { "default": 6, "flag": "--max-images", "kind": "number", "name": "max_images", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "/preparation_report.json", "description": "Runtime-only label provenance, counts, paths, native COCO/Cityscapes layouts, internal label mirrors used to prevent unintended reconversion, and payload tree hash.", "kind": "file", "name": "preparation_report_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "Pillow" ] }, "runner": "python3", "summary": "Prepare bounded native COCO detection/keypoint and Cityscapes-style segmentation layouts plus internal label mirrors for runtime availability tests, with heuristic labels explicitly marked non-efficacy GT.", "tags": [ "dataset", "external-runtime", "training", "experimental" ] }, { "docs": [ "docs/openai_image_service_plugin.md", "README.md", "Readme_jp.md", "manual/chapters/20_llm_mcp_integrations.tex" ], "effects": { "fixed_writes": [], "writes": [ { "flag": "--output", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/prepare_image_service_plugin.py", "examples": [ { "command": "python3 tools/prepare_image_service_plugin.py --help", "description": "Inspect preparation options." }, { "command": "python3 tools/prepare_image_service_plugin.py --python .venv/bin/python --output /tmp/yolozu-staging/plugins/yolozu-image-service", "description": "Prepare a runtime-specific local copy at a new staging destination." } ], "id": "prepare_image_service_plugin", "inputs": [ { "flag": "--help", "kind": "string", "name": "help", "required": false }, { "description": "New destination ending in yolozu-image-service; existing paths are refused.", "flag": "--output", "kind": "dir", "name": "output", "required": true }, { "description": "Trusted interpreter with this source revision of yolozu[mcp] installed; virtualenv symlink identity is preserved.", "flag": "--python", "kind": "file", "name": "python", "required": true } ], "maturity": "experimental", "outputs": [ { "default": null, "description": "Manifest, MCP settings with absolute interpreter path, skill, image client, and code license.", "kind": "dir", "name": "plugin_directory" }, { "description": "Verified tool list and explicit installed_in_host=false and models_qualified=false markers.", "kind": "stdout", "name": "preparation_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false, "python_packages": [] }, "runner": "python3", "summary": "Prepare a non-overwriting local OpenAI plugin copy after checking the selected installed runtime's five-tool MCP surface; do not install dependencies, register a marketplace, or qualify a model.", "tags": [ "mcp", "plugin", "packaging" ] }, { "docs": [ "docs/cvat_keypoints_recovery.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes YOLOZU-ready dataset wrapper and/or converted labels.", "flag": "--out", "kind": "dir", "scope": "path" } ] }, "entrypoint": "tools/prepare_keypoints_dataset.py", "examples": [ { "command": "python3 tools/prepare_keypoints_dataset.py --source /path/to/export --format auto --out data/keypoints_dataset", "description": "Auto-detect and prepare keypoints dataset from CVAT export." }, { "command": "python3 tools/prepare_keypoints_dataset.py --source /path/to/cvat_export --format cvat_xml --out data/keypoints_dataset", "description": "Directly prepare keypoints dataset from CVAT XML export." } ], "id": "prepare_keypoints_dataset", "inputs": [ { "flag": "--source", "kind": "string", "name": "source", "required": true }, { "flag": "--out", "kind": "dir", "name": "out", "required": true }, { "flag": "--list-formats", "kind": "string", "name": "list_formats", "required": false }, { "flag": "--format", "kind": "string", "name": "format", "required": false }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--num-keypoints", "kind": "number", "name": "num_keypoints", "required": false }, { "flag": "--keypoint-names", "kind": "string", "name": "keypoint_names", "required": false }, { "flag": "--annotations", "kind": "file", "name": "annotations", "required": false }, { "flag": "--images-dir", "kind": "string", "name": "images_dir", "required": false }, { "flag": "--out-split", "kind": "string", "name": "out_split", "required": false }, { "flag": "--min-kps", "kind": "number", "name": "min_kps", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--link-images", "kind": "string", "name": "link_images", "required": false }, { "flag": "--category-id", "kind": "number", "name": "category_id", "required": false }, { "flag": "--category-name", "kind": "string", "name": "category_name", "required": false }, { "flag": "--class-id", "kind": "number", "name": "class_id", "required": false }, { "flag": "--cvat-images-dir", "kind": "string", "name": "cvat_images_dir", "required": false } ], "maturity": "stable", "outputs": [ { "default": null, "description": "Prepared dataset root with dataset.json for keypoints training.", "kind": "file", "name": "dataset_descriptor" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [] }, "runner": "python3", "summary": "Prepare keypoints dataset in one command (auto-detect YOLO Pose or COCO keypoints) and emit YOLOZU-ready dataset wrapper.", "tags": [ "dataset", "keypoints", "cvat", "coco", "yolo" ] }, { "docs": [ "docs/training_inference_export.md", "manual/chapters/16_depth_6dof_symmetry.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Creates dataset tree (images/labels/masks/depth) and summary files under output root.", "flag": "--out", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/prepare_real_multitask_fewshot.py", "examples": [ { "command": "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", "description": "Build a compact train/val few-shot dataset from COCO val2017." } ], "id": "prepare_real_multitask_fewshot", "inputs": [ { "default": "data/coco/annotations/instances_val2017.json", "flag": "--instances-json", "kind": "file", "name": "instances_json", "required": false }, { "default": "data/coco/images/val2017", "flag": "--images-dir", "kind": "dir", "name": "images_dir", "required": false }, { "default": "data/real_multitask_fewshot", "flag": "--out", "kind": "dir", "name": "out", "required": false }, { "default": 6, "flag": "--train-images", "kind": "number", "name": "train_images", "required": false }, { "default": 2, "flag": "--val-images", "kind": "number", "name": "val_images", "required": false }, { "default": 4, "flag": "--num-keypoints", "kind": "number", "name": "num_keypoints", "required": false }, { "description": "Request tiny COCO download when inputs are missing (requires --allow-auto-download and --accept-dataset-license).", "flag": "--download-if-missing", "kind": "string", "name": "download_if_missing", "required": false }, { "flag": "--download-num-images", "kind": "number", "name": "download_num_images", "required": false }, { "flag": "--download-seed", "kind": "number", "name": "download_seed", "required": false }, { "flag": "--download-timeout", "kind": "number", "name": "download_timeout", "required": false }, { "flag": "--force", "kind": "string", "name": "force", "required": false }, { "description": "Allow automatic tiny COCO download.", "flag": "--allow-auto-download", "kind": "string", "name": "allow_auto_download", "required": false }, { "description": "Acknowledge dataset license terms before auto download.", "flag": "--accept-dataset-license", "kind": "string", "name": "accept_dataset_license", "required": false }, { "description": "Fail if model-inference-generated labels are detected.", "flag": "--strict-provenance", "kind": "string", "name": "strict_provenance", "required": false }, { "description": "Fail if heuristic/derived labels are present.", "flag": "--strict-realism", "kind": "string", "name": "strict_realism", "required": false } ], "maturity": "stable", "outputs": [ { "default": "data/real_multitask_fewshot", "description": "Prepared real-image multitask few-shot dataset root.", "kind": "dir", "name": "dataset_root" }, { "default": "data/real_multitask_fewshot/prepare_summary.json", "description": "Preparation summary with counts, provenance checks, and warnings.", "kind": "file", "name": "prepare_summary_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "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.", "tags": [ "dataset", "fewshot", "multitask", "real-data" ] }, { "docs": [ "docs/ttt_protocol.md", "manual/chapters/15_ttt_tent_mim.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes an ownership-marked corrupted target dataset root; --force replaces only a valid owned, non-overlapping, non-symlink output.", "flag": "--out", "kind": "dir", "scope": "tree" }, { "description": "Writes domain shift recipe JSON inside the owned --out root; external and symlink paths are refused.", "flag": "--recipe-out", "kind": "file", "scope": "path" } ] }, "entrypoint": "scripts/prepare_ttt_domain_shift_target.py", "examples": [ { "command": "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", "description": "Generate deterministic corrupted target split and recipe JSON for TTT evidence." } ], "id": "prepare_ttt_domain_shift_target", "inputs": [ { "flag": "--dataset-root", "kind": "dir", "name": "dataset_root", "required": true }, { "default": "val", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--out", "kind": "dir", "name": "out", "required": true }, { "default": "gaussian_blur", "flag": "--corruption", "kind": "string", "name": "corruption", "required": false }, { "default": 2, "flag": "--severity", "kind": "number", "name": "severity", "required": false }, { "default": 0, "flag": "--seed", "kind": "number", "name": "seed", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--copy-labels", "kind": "string", "name": "copy_labels", "required": false }, { "flag": "--no-copy-labels", "kind": "string", "name": "no_copy_labels", "required": false }, { "flag": "--force", "kind": "string", "name": "force", "required": false }, { "flag": "--recipe-out", "kind": "file", "name": "recipe_out", "required": false } ], "maturity": "research", "outputs": [ { "default": null, "description": "Corrupted target dataset root for deterministic shift runs.", "kind": "dir", "name": "target_dataset_root" }, { "default": null, "description": "Recipe JSON including export_settings.domain_shift_target.", "kind": "file", "name": "domain_shift_recipe_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Prepare a deterministic, provenance-hashed domain-shift target and recipe while refusing source/output overlap, symlink outputs, protected roots, and unowned replacement.", "tags": [ "ttt", "domain-shift", "dataset", "deterministic" ] }, { "effects": { "fixed_writes": [], "writes": [ { "description": "Writes prepared segmentation dataset layout under --out (manifest + optional symlinks/copies).", "flag": "--out", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/prepare_voc_seg.py", "examples": [ { "command": "python3 tools/prepare_voc_seg.py --voc-root /path/to/VOCdevkit/VOC2012 --split train --out data/voc_seg --mode manifest", "description": "Create a manifest-only dataset.json (no copying)." } ], "id": "prepare_voc_seg", "inputs": [ { "flag": "--voc-root", "kind": "dir", "name": "voc_root", "required": true }, { "flag": "--out", "kind": "dir", "name": "out", "required": true }, { "default": "train", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--mode", "kind": "string", "name": "mode", "required": false }, { "flag": "--masks-dirname", "kind": "string", "name": "masks_dirname", "required": false }, { "flag": "--force", "kind": "string", "name": "force", "required": false }, { "flag": "--year", "kind": "string", "name": "year", "required": false } ], "maturity": "stable", "outputs": [ { "default": null, "description": "Prepared output root created at --out.", "kind": "dir", "name": "dataset_root" }, { "default": "/dataset.json", "description": "dataset.json manifest.", "kind": "file", "name": "dataset_descriptor" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Prepare Pascal VOC semantic segmentation layout + dataset.json manifest.", "tags": [ "dataset", "pascal_voc", "voc", "segmentation" ] }, { "contracts": { "produces": [ "candidate_isolation_probe_json" ] }, "docs": [ "docs/adaptive_image_routing.md", "docs/candidate_isolation_threat_model.md", "docs/schemas/candidate_isolation_probe.schema.json" ], "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "tools/probe_candidate_isolation.py", "examples": [ { "command": "python3 tools/probe_candidate_isolation.py", "description": "Print the bounded none-supported decision and host backend-presence observations without starting a backend or candidate." }, { "command": "python3 tools/probe_candidate_isolation.py --help", "description": "Inspect the read-only capability-probe interface contract." } ], "id": "probe_candidate_isolation", "inputs": [], "maturity": "experimental", "outputs": [ { "default": "stdout", "description": "CandidateIsolationCapabilityProbe JSON with every mandatory control left not_run and explicit failure codes while no backend row is supported.", "kind": "stdout", "name": "candidate_isolation_probe" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true, "notes": "Observes fixed executable presence only; never starts a backend or candidate." }, "runner": "python3", "summary": "Report the code-owned none-supported candidate-isolation decision without treating backend presence, mocks, or in-process guards as containment.", "tags": [ "adaptive-inference", "candidate", "experimental", "isolation", "security" ] }, { "contracts": { "consumes": [ "image_job_spec_json", "selection_decision_json" ], "produces": [ "managed_output_checksums_json", "predictions_json" ] }, "docs": [ "README.md", "Readme_jp.md", "docs/adaptive_image_routing.md", "docs/ai_first.md", "docs/llm_integrations.md", "docs/production_readiness.md", "docs/schema_governance.md", "docs/ssot_capability_coverage_audit.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "On explicit dry_run=false, atomically publishes only predictions.json, provenance.json, checksums.json, and referenced masks below output_dir.", "flag": "--output-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "yolozu/integrations/mcp_server.py", "examples": [ { "command": "Call the process_images MCP tool with job_spec, the complete selected SelectionDecision, workspace-relative input_path/output_dir, and dry_run=true.", "description": "Revalidate the pinned selection and all local state without importing or calling a runner or writing output." }, { "command": "Call the process_images MCP tool again with the same pinned inputs and dry_run=false after reviewing the preflight result.", "description": "Execute only the selected registered code-owned route and publish the bounded managed output tree." } ], "id": "process_images", "inputs": [ { "description": "Structured ImageJobSpec v1 object; natural-language parsing remains in the calling AI client.", "kind": "json", "name": "job_spec", "required": true }, { "description": "Complete selected SelectionDecision returned by recommend_image_pipeline.", "kind": "json", "name": "selection_decision", "required": true }, { "description": "Workspace-confined image file or bounded direct image directory matching the pinned job.", "kind": "string", "name": "input_path", "required": true }, { "description": "Fresh or exactly validated managed destination below the workspace.", "flag": "--output-dir", "kind": "dir", "name": "output_dir", "required": true }, { "default": null, "description": "Optional workspace-confined custom registry directory; operator_asserted registries remain non-selectable.", "kind": "dir", "name": "registry_root", "required": false }, { "default": null, "description": "Optional workspace-confined evidence directory using the same trust semantics as recommendation.", "kind": "dir", "name": "evidence_root", "required": false }, { "default": null, "description": "Optional workspace-confined local artifact root; omission uses the existing YOLOZU model cache.", "kind": "dir", "name": "artifact_root", "required": false }, { "default": true, "description": "When true, stop after full read-only pinned preflight before runner creation or output mutation.", "kind": "string", "name": "dry_run", "required": false }, { "default": false, "description": "When true, replace only an exact prior managed output whose checksum manifest validates.", "kind": "string", "name": "force", "required": false } ], "maturity": "experimental", "outputs": [ { "description": "Structured dry-run or execution result with no absolute paths or raw runner output.", "kind": "json", "name": "processing_result_json" }, { "default": null, "description": "For dry_run=false only, managed predictions/provenance/checksums tree with optional referenced masks.", "kind": "dir", "name": "managed_output" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false, "python_packages": [ "mcp", "Pillow" ] }, "runner": "python3", "summary": "Revalidate and explicitly execute one pinned qualified local image pipeline through a code-owned network-free route; dry-run is the default and performs no model execution or writes.", "tags": [ "adaptive-inference", "ai-first", "experimental", "local-inference", "mcp", "pinned-execution", "qualification", "routing" ] }, { "contracts": { "consumes": [ "algorithm_bundle_registry_json", "bundle_lifecycle_record_json", "support_profile_record_json", "candidate_screening_record_json", "qualification_report_json", "evidence_activation_record_json", "lifecycle_rollback_bindings_json" ], "produces": [ "bundle_lifecycle_record_json" ] }, "docs": [ "README.md", "Readme_jp.md", "docs/adaptive_image_routing.md", "docs/production_readiness.md", "docs/schemas/bundle_lifecycle_record.schema.json", "docs/schemas/support_profile_spec.schema.json", "reports/adaptive_promotion_governance_2026-08-29.md" ], "effects": { "fixed_writes": [ { "description": "With --approve, atomically appends only one exact evidence-bound reviewed channel assignment.", "kind": "file", "path": "yolozu/data/adaptive_routing/bundle_lifecycle.jsonl", "scope": "path" } ], "writes": [] }, "entrypoint": "tools/promote_image_pipeline.py", "examples": [ { "command": "python3 tools/promote_image_pipeline.py --family-id --source-channel Candidate --target-channel Experimental --bundle-spec-digest --expected-source-pointer-digest --expected-target-pointer-digest none --expected-lifecycle-head-digest --expected-support-profile-index-head --expected-profile-set-record-digest --expected-profile-set-digest --profile = --evidence-bindings reports/promotion-bindings.json --rollback-target none --approver-role-id repo_maintainer --public-review-id gh- --reason 'Review exact promotion'", "description": "Dry-run all exact source, target, support, evidence, approval, rollback-readiness, and channel-specific gates without mutation." }, { "command": "python3 tools/promote_image_pipeline.py --help", "description": "Inspect the reviewed promotion interface contract." } ], "id": "promote_image_pipeline", "inputs": [ { "flag": "--family-id", "kind": "string", "name": "family_id", "required": false }, { "flag": "--source-channel", "kind": "string", "name": "source_channel", "required": false }, { "flag": "--target-channel", "kind": "string", "name": "target_channel", "required": false }, { "flag": "--bundle-spec-digest", "kind": "string", "name": "bundle_spec_digest", "required": false }, { "flag": "--expected-source-pointer-digest", "kind": "string", "name": "expected_source_pointer_digest", "required": false }, { "flag": "--expected-target-pointer-digest", "kind": "string", "name": "expected_target_pointer_digest", "required": false }, { "flag": "--expected-lifecycle-head-digest", "kind": "string", "name": "expected_lifecycle_head_digest", "required": false }, { "flag": "--expected-support-profile-index-head", "kind": "string", "name": "expected_support_profile_index_head", "required": false }, { "flag": "--expected-profile-set-record-digest", "kind": "string", "name": "expected_profile_set_record_digest", "required": false }, { "flag": "--expected-profile-set-digest", "kind": "string", "name": "expected_profile_set_digest", "required": false }, { "flag": "--profile", "kind": "string", "name": "profile", "required": false }, { "flag": "--evidence-bindings", "kind": "file", "name": "evidence_bindings", "required": false }, { "flag": "--rollback-target", "kind": "string", "name": "rollback_target", "required": false }, { "flag": "--failure-drill-report", "kind": "file", "name": "failure_drill_report", "required": false }, { "flag": "--approver-role-id", "kind": "string", "name": "approver_role_id", "required": false }, { "flag": "--public-review-id", "kind": "string", "name": "public_review_id", "required": false }, { "flag": "--reason", "kind": "string", "name": "reason", "required": false }, { "default": ".", "flag": "--workspace", "kind": "dir", "name": "workspace", "required": false }, { "flag": "--approve", "kind": "string", "name": "approve", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "stdout", "description": "Bounded machine-readable dry-run or apply result with every failed gate and exact observed identities.", "kind": "stdout", "name": "promotion_outcome" }, { "default": "yolozu/data/adaptive_routing/bundle_lifecycle.jsonl", "description": "Canonical append-only lifecycle stream after explicit approval and successful readback.", "kind": "file", "name": "bundle_lifecycle_stream" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Dry-run or atomically append one exact reviewed Candidate-to-Experimental or Experimental-to-Stable assignment after complete managed evidence, rollback-readiness, and Stable non-regression gates.", "tags": [ "adaptive-inference", "experimental", "governance", "lifecycle", "promotion", "ssot" ] }, { "contracts": { "consumes": [ "metrics_report_json" ] }, "docs": [ "docs/benchmark_publication.md", "docs/yolo26_eval_protocol.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes benchmark table JSON artifact.", "flag": "--output-json", "kind": "file", "scope": "path" }, { "description": "Writes benchmark table Markdown artifact.", "flag": "--output-md", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/publish_benchmark_table.py", "examples": [ { "command": "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\"", "description": "Publish official benchmark table from one or more benchmark reports." } ], "id": "publish_benchmark_table", "inputs": [ { "description": "Repeatable benchmark report JSON input.", "flag": "--report", "kind": "file", "name": "report", "required": true }, { "default": "reports/benchmark_table.json", "flag": "--output-json", "kind": "file", "name": "output_json", "required": false }, { "default": "reports/benchmark_table.md", "flag": "--output-md", "kind": "file", "name": "output_md", "required": false }, { "flag": "--title", "kind": "string", "name": "title", "required": false }, { "default": "weekly", "flag": "--cadence", "kind": "string", "name": "cadence", "required": false }, { "default": "yolo26", "flag": "--protocol-id", "kind": "string", "name": "protocol_id", "required": false }, { "flag": "--source-command", "kind": "string", "name": "source_command", "required": false }, { "flag": "--publication-run-id", "kind": "string", "name": "publication_run_id", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/benchmark_table.json", "description": "Benchmark table JSON artifact.", "kind": "file", "name": "benchmark_table_json" }, { "default": "reports/benchmark_table.md", "description": "Benchmark table Markdown artifact.", "kind": "file", "name": "benchmark_table_md" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Generate official benchmark publication table (JSON+Markdown) from benchmark reports with run-id traceability.", "tags": [ "benchmark", "publication", "protocol", "report" ] }, { "docs": [ "docs/image_service_mcp.md", "docs/llm_integrations.md", "docs/openai_mcp_actions.md" ], "effects": { "fixed_writes": [ { "kind": "dir", "path": "runs/mcp_image_service", "scope": "tree" } ], "writes": [] }, "entrypoint": "yolozu/integrations/mcp_server.py", "examples": [ { "command": "Call the put_image_asset MCP tool with strict base64 and its decoded JPEG, PNG, or WebP media type.", "description": "Store one bounded private image and receive an opaque asset_id; caller paths and URLs are not accepted." } ], "id": "put_image_asset", "inputs": [ { "description": "Strict base64 for one image bounded to 8 MiB after decoding.", "kind": "string", "name": "content_base64", "required": true }, { "description": "Exact decoded media type: image/jpeg, image/png, or image/webp.", "kind": "string", "name": "media_type", "required": true } ], "maturity": "experimental", "outputs": [ { "description": "Opaque asset identity, digest, dimensions, and retention period; no storage path is returned.", "kind": "json", "name": "asset_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false, "python_packages": [ "mcp", "Pillow" ] }, "runner": "python3", "summary": "Rate-limit, decode, validate, and privately store one bounded image without accepting a filesystem path or remote URL.", "tags": [ "ai-first", "image-service", "mcp", "security" ] }, { "contracts": { "consumes": [ "predictions_json" ], "produces": [ "artifact_research_qualification_json" ] }, "docs": [ "docs/distillation.md", "docs/hessian_solver.md", "docs/research_lanes.md", "docs/schemas/artifact_research_qualification.schema.json", "docs/schemas/research_lane_report.schema.json", "reports/artifact_research_evidence_2026-07-28.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Creates a fresh evidence bundle and refuses to replace an existing directory.", "flag": "--output-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/qualify_artifact_research.py", "examples": [ { "command": "./.venv/bin/python tools/qualify_artifact_research.py --output-dir /tmp/yolozu-artifact-research", "description": "Run three deterministic distillation/Hessian repetitions plus real COCO evaluation." } ], "id": "qualify_artifact_research", "inputs": [ { "default": "reports/predictions_rtdetr_pose_baseline.json", "flag": "--student", "kind": "file", "name": "student", "required": false }, { "default": "data/smoke/predictions/predictions_dummy.json", "flag": "--teacher", "kind": "file", "name": "teacher", "required": false }, { "default": "data/coco128", "flag": "--dataset", "kind": "dir", "name": "dataset", "required": false }, { "default": "train2017", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "default": "configs/examples/distill_predictions.yaml", "flag": "--distill-config", "kind": "file", "name": "distill_config", "required": false }, { "default": "configs/runtime/hessian_refine_example.yaml", "flag": "--hessian-config", "kind": "file", "name": "hessian_config", "required": false }, { "default": "reports/artifact_research_qualification", "flag": "--output-dir", "kind": "dir", "name": "output_dir", "required": false }, { "default": 3, "flag": "--repeats", "kind": "number", "name": "repeats", "required": false } ], "maturity": "research", "outputs": [ { "default": "reports/artifact_research_qualification/qualification_summary.json", "description": "Hash-bound metrics, repetition results, negative controls, and hold decisions.", "kind": "file", "name": "artifact_research_qualification_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "pycocotools", "torch" ] }, "runner": "python3", "summary": "Qualify offline prediction distillation and Hessian refinement with three deterministic repetitions, stable COCO metrics, hashes, measured cost, rollback, and explicit hold gates.", "tags": [ "distillation", "evidence", "hessian", "research", "reproducibility" ] }, { "contracts": { "produces": [ "finetune_lane_qualification_json" ] }, "docs": [ "docs/external_finetune_smoke.md", "docs/schemas/finetune_lane_qualification.schema.json", "docs/training_capability_matrix.md", "docs/training_inference_export.md", "docs/tools_index.md", "manual/chapters/16_depth_6dof_symmetry.tex", "reports/finetune_lane_evidence_2026-07-29.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Creates a fresh qualification directory containing reports, logs, checkpoints, provider attempts, and checksums.", "flag": "--output-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/qualify_finetune_lanes.py", "examples": [ { "command": "./.venv/bin/python tools/qualify_finetune_lanes.py --output-dir /tmp/yolozu-finetune-qualification", "description": "Execute the repository-local five-stage trainer and non-dry external matrix, then emit one schema-defined hold decision." } ], "id": "qualify_finetune_lanes", "inputs": [ { "flag": "--output-dir", "kind": "dir", "name": "output_dir", "required": true }, { "default": "data/real_multitask_fewshot", "flag": "--dataset-root", "kind": "dir", "name": "dataset_root", "required": false }, { "flag": "--python", "kind": "string", "name": "python", "required": false }, { "default": "cpu", "flag": "--device", "kind": "string", "name": "device", "required": false }, { "default": 1, "flag": "--epochs", "kind": "number", "name": "epochs", "required": false }, { "default": 4, "flag": "--max-steps", "kind": "number", "name": "max_steps", "required": false }, { "default": 2, "flag": "--batch-size", "kind": "number", "name": "batch_size", "required": false }, { "default": 128, "flag": "--image-size", "kind": "number", "name": "image_size", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "/qualification_summary.json", "description": "Schema-defined machine-readable execution matrix, protocol completion signal, provenance, hashes, metric boundaries, and hold decision.", "kind": "file", "name": "finetune_lane_qualification_json" }, { "default": "/checksums.sha256", "description": "SHA-256 manifest for every emitted qualification artifact.", "kind": "file", "name": "checksums" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "torch" ] }, "runner": "python3", "summary": "Qualify real-image and external fine-tuning execution in one command while failing closed on projection-only non-dry lanes. Exit 0 means protocol_complete, while promotion remains a separate hold/pass decision and Experimental maturity is retained when labels or task-native metrics are insufficient.", "tags": [ "evidence", "finetune", "interop", "multitask", "reproducibility", "training" ] }, { "contracts": { "consumes": [ "algorithm_bundle_registry_json", "image_job_spec_json" ], "produces": [ "managed_output_checksums_json", "qualification_report_json" ] }, "docs": [ "README.md", "Readme_jp.md", "docs/adaptive_image_routing.md", "docs/schemas/qualification_report.schema.json" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Publishes only qualification_report.json and its code-owned checksums.json in one bounded managed directory.", "flag": "--output-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/qualify_image_pipeline.py", "examples": [ { "command": "python3 tools/qualify_image_pipeline.py --job configs/examples/adaptive_image_job.json --input data/smoke/images/val --bundle-id example --bundle-version 1 --output-dir reports/image_pipeline_qualification", "description": "Measure an exact eligible packaged bundle; the current empty registry fails actionably without dummy evidence." }, { "command": "python3 tools/qualify_image_pipeline.py --help", "description": "Inspect the Experimental bounded qualification interface contract." } ], "id": "qualify_image_pipeline", "inputs": [ { "flag": "--job", "kind": "file", "name": "job", "required": true }, { "flag": "--input", "kind": "string", "name": "input", "required": true }, { "flag": "--bundle-id", "kind": "string", "name": "bundle_id", "required": true }, { "flag": "--bundle-version", "kind": "string", "name": "bundle_version", "required": true }, { "default": "reports/image_pipeline_qualification", "flag": "--output-dir", "kind": "dir", "name": "output_dir", "required": false }, { "default": ".", "flag": "--workspace", "kind": "dir", "name": "workspace", "required": false }, { "flag": "--artifact-root", "kind": "dir", "name": "artifact_root", "required": false }, { "flag": "--ground-truth", "kind": "file", "name": "ground_truth", "required": false }, { "flag": "--evaluator-id", "kind": "string", "name": "evaluator_id", "required": false }, { "default": "Experimental", "flag": "--channel", "kind": "string", "name": "channel", "required": false }, { "default": 3600, "flag": "--qualification-timeout-seconds", "kind": "number", "name": "qualification_timeout_seconds", "required": false }, { "flag": "--smoke", "kind": "string", "name": "smoke", "required": false }, { "flag": "--force", "kind": "string", "name": "force", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/image_pipeline_qualification", "description": "Managed directory containing qualification_report.json and checksums.json only; the report is unactivated.", "kind": "dir", "name": "qualification_output" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Measure one exact registered local image pipeline with pinned inputs/assets, bounded child-process cancellation, exact aggregates, and atomic unactivated evidence output.", "tags": [ "adaptive-inference", "benchmark", "evidence", "experimental", "local-inference", "qualification" ] }, { "contracts": { "produces": [ "sdft_continual_qualification_json" ] }, "docs": [ "docs/continual_learning.md", "docs/research_lanes.md", "docs/schemas/sdft_continual_qualification.schema.json", "manual/chapters/14_continual_learning.tex", "reports/sdft_continual_evidence_2026-07-28.md", "reports/sdft_confirmatory_evidence_2026-07-30.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Creates a fresh qualification directory and refuses existing paths.", "flag": "--output-dir", "kind": "dir", "scope": "tree" }, { "description": "Creates a compressed checksum bundle and refuses existing paths.", "flag": "--archive", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/qualify_sdft_continual.py", "examples": [ { "command": "./.venv/bin/python tools/qualify_sdft_continual.py --output-dir /tmp/yolozu-sdft-qualification", "description": "Run the tracked three-seed naive-versus-SDFT-style sequence with real COCOeval." }, { "command": "./.venv/bin/python tools/qualify_sdft_continual.py --spec configs/continual/sdft_response_replay_preregistration.json --output-dir /tmp/yolozu-sdft-response-replay", "description": "Run the prospectively registered naive/SDFT-response/replay/combined four-group qualification." } ], "id": "qualify_sdft_continual", "inputs": [ { "default": "configs/continual/sdft_coco128_blur_qualification.json", "flag": "--spec", "kind": "file", "name": "spec", "required": false }, { "default": "reports/sdft_continual_qualification", "flag": "--output-dir", "kind": "dir", "name": "output_dir", "required": false }, { "default": null, "flag": "--archive", "kind": "file", "name": "archive", "required": false }, { "default": "primary", "flag": "--role", "kind": "string", "name": "role", "required": false }, { "default": null, "flag": "--source-summary", "kind": "file", "name": "source_summary", "required": false } ], "maturity": "research", "outputs": [ { "default": "/qualification_summary.json", "description": "Machine-readable metrics, provenance, fairness checks, and decision boundary.", "kind": "file", "name": "sdft_continual_qualification_json" }, { "default": ".tgz", "description": "Full evidence bundle with a checksum manifest.", "kind": "file", "name": "evidence_bundle" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "Pillow", "pycocotools", "torch" ] }, "runner": "python3", "summary": "Qualify checkpoint-distillation continual learning across fixed seeds and real COCOeval, including the prospective naive/SDFT-response/replay/combined ablation with selected-query and replay execution gates.", "tags": [ "continual", "coco", "evidence", "research", "sdft", "self-distillation" ] }, { "contracts": { "consumes": [ "candidate_screening_record_json", "image_job_spec_json" ], "produces": [ "selection_decision_json" ] }, "docs": [ "README.md", "Readme_jp.md", "docs/adaptive_image_routing.md", "docs/ai_first.md", "docs/llm_integrations.md", "docs/production_readiness.md", "docs/schema_governance.md", "docs/ssot_capability_coverage_audit.md" ], "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "yolozu/integrations/mcp_server.py", "examples": [ { "command": "Call the recommend_image_pipeline MCP tool with a structured job_spec and one workspace-relative input_path.", "description": "Return a selected or abstained SelectionDecision without model execution, downloads, network access, or writes." } ], "id": "recommend_image_pipeline", "inputs": [ { "description": "Structured ImageJobSpec v1 object; natural-language parsing remains in the calling AI client.", "kind": "json", "name": "job_spec", "required": true }, { "description": "Workspace-confined image file or bounded direct image directory matching job_spec.input_mode.", "kind": "string", "name": "input_path", "required": true }, { "default": null, "description": "Optional workspace-confined custom bundle_specs.json and bundle_lifecycle.jsonl directory; always operator_asserted and non-selectable in v1.", "kind": "dir", "name": "registry_root", "required": false }, { "default": null, "description": "Optional workspace-confined directory containing candidate_screening.jsonl; path-derived trust is always operator_asserted and cannot satisfy a managed pass gate.", "kind": "dir", "name": "screening_root", "required": false }, { "default": null, "description": "Optional workspace-confined evidence directory containing evidence_activation.jsonl and qualification_reports// retained records.", "kind": "dir", "name": "evidence_root", "required": false }, { "default": null, "description": "Optional workspace-confined local artifact root; omission uses the existing YOLOZU model cache read-only.", "kind": "dir", "name": "artifact_root", "required": false } ], "maturity": "experimental", "outputs": [ { "description": "Structured selected or abstained SelectionDecision plus privacy-safe read-only recommendation metadata.", "kind": "json", "name": "selection_decision_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false, "python_packages": [ "mcp", "Pillow" ] }, "runner": "python3", "summary": "Return an explainable read-only qualified local image-pipeline selection or explicit abstention from bounded typed inputs; this tool does not execute a model.", "tags": [ "adaptive-inference", "ai-first", "experimental", "local-inference", "mcp", "qualification", "read-only", "routing" ] }, { "contracts": { "consumes": [ "predictions_json" ], "produces": [ "predictions_json", "research_lane_report_json" ] }, "docs": [ "docs/README.md", "docs/ttt_protocol.md", "docs/hessian_solver.md", "docs/production_readiness.md", "docs/research_lanes.md", "docs/schemas/research_lane_report.schema.json" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes refined predictions JSON.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Writes measured latency, hashes, rollback, and promotion boundary.", "flag": "--log-output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/refine_predictions_hessian.py", "examples": [ { "command": "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", "description": "Enable offsets refinement in post-processing mode." } ], "id": "refine_predictions_hessian", "inputs": [ { "flag": "--predictions", "kind": "file", "name": "predictions", "required": true }, { "flag": "--output", "kind": "file", "name": "output", "required": true }, { "flag": "--config", "kind": "file", "name": "config", "required": false }, { "flag": "--enable", "kind": "string", "name": "enable", "required": false }, { "flag": "--disable", "kind": "string", "name": "disable", "required": false }, { "flag": "--wrap", "kind": "string", "name": "wrap", "required": false }, { "flag": "--refine-offsets", "kind": "string", "name": "refine_offsets", "required": false }, { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": false }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--device", "kind": "string", "name": "device", "required": false }, { "flag": "--steps", "kind": "number", "name": "steps", "required": false }, { "flag": "--damping", "kind": "number", "name": "damping", "required": false }, { "flag": "--fd-eps", "kind": "number", "name": "fd_eps", "required": false }, { "flag": "--line-search", "kind": "number", "name": "line_search", "required": false }, { "flag": "--line-search-decay", "kind": "number", "name": "line_search_decay", "required": false }, { "flag": "--w-reg", "kind": "number", "name": "w_reg", "required": false }, { "flag": "--w-depth", "kind": "number", "name": "w_depth", "required": false }, { "flag": "--w-mask", "kind": "number", "name": "w_mask", "required": false }, { "flag": "--max-step-px", "kind": "number", "name": "max_step_px", "required": false }, { "flag": "--max-total-update-px", "kind": "number", "name": "max_total_update_px", "required": false }, { "flag": "--tol-delta", "kind": "number", "name": "tol_delta", "required": false }, { "flag": "--tol-loss", "kind": "number", "name": "tol_loss", "required": false }, { "flag": "--log-output", "kind": "file", "name": "log_output", "required": false }, { "flag": "--log-steps", "kind": "string", "name": "log_steps", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false } ], "maturity": "research", "outputs": [ { "default": null, "description": "Refined predictions JSON written to --output; --log-output writes a research_report boundary when enabled.", "kind": "file", "name": "predictions_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "torch" ] }, "runner": "python3", "summary": "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.", "tags": [ "predictions", "refine", "hessian", "pose" ] }, { "docs": [ "README.md", "RELEASE.md", "deploy/docker/README.md", "deploy/runpod/README.md", "docs/release_reliability_checklist.md", "docs/manual_doi_release.md", "docs/tools_index.md", "manual/chapters/12_tool_registry.tex" ], "effects": { "fixed_writes": [ { "description": "Updates package version in the synchronized release metadata transaction.", "kind": "file", "path": "yolozu/__init__.py", "scope": "path" }, { "description": "Inserts the dated release heading in the synchronized release metadata transaction.", "kind": "file", "path": "CHANGELOG.md", "scope": "path" }, { "description": "Updates version and date-released in the synchronized release metadata transaction.", "kind": "file", "path": "CITATION.cff", "scope": "path" }, { "description": "Advances examples explicitly marked as current-release-coupled.", "kind": "file", "path": "tools/manifest.json", "scope": "path" }, { "description": "Keeps the packaged manifest byte-identical to the source manifest.", "kind": "file", "path": "yolozu/data/manifest/tools_manifest.json", "scope": "path" } ], "writes": [ { "description": "Writes release operation report JSON.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "release.sh", "examples": [ { "command": "bash release.sh", "description": "Run the default no-option release flow (auto bump + tag + GitHub/PyPI/Zenodo handoff)." }, { "command": "bash release.sh --dry-run --allow-dirty --allow-non-main --output reports/release_report.dry_run.json", "description": "Preview release actions and the next SemVer/CalVer version without mutating git/GitHub state." }, { "command": "bash release.sh --dry-run --versioning calver --allow-dirty --allow-non-main --output reports/release_report.calver.json", "description": "Preview CalVer auto-bump mode explicitly (YYYY.MM.DD.MICRO with same-day micro increment)." } ], "id": "release", "inputs": [ { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "description": "Validate current package, CHANGELOG, CITATION, tag-form, and manifest metadata without preparing or publishing a release.", "flag": "--check", "kind": "string", "name": "check", "required": false }, { "choices": [ "auto", "semver", "calver" ], "default": "auto", "description": "Release versioning scheme: auto detects SemVer X.Y.Z or CalVer YYYY.MM.DD.MICRO from yolozu.__version__.", "flag": "--versioning", "kind": "string", "name": "versioning", "required": false }, { "default": "reports/release_report.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--allow-dirty", "kind": "string", "name": "allow_dirty", "required": false }, { "flag": "--allow-non-main", "kind": "string", "name": "allow_non_main", "required": false }, { "flag": "--skip-checks", "kind": "string", "name": "skip_checks", "required": false }, { "flag": "--skip-gh", "kind": "string", "name": "skip_gh", "required": false }, { "description": "Deprecated fail-closed compatibility option. A published GitHub Release automatically triggers manual_doi.yml; use --skip-gh to avoid publishing the release.", "flag": "--skip-zenodo", "kind": "string", "name": "skip_zenodo", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/release_report.json", "description": "Release decision report with metadata validation/plan, bump policy, actions, and workflow handoff status.", "kind": "file", "name": "release_report_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": true }, "runner": "bash", "summary": "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/....", "tags": [ "release", "tag", "pypi", "zenodo", "automation" ] }, { "docs": [ "RELEASE.md", "deploy/docker/README.md", "deploy/runpod/README.md", "docs/release_reliability_checklist.md", "docs/manual_doi_release.md", "docs/tools_index.md", "manual/chapters/12_tool_registry.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes release/tag operation report JSON.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/release_tag.py", "examples": [ { "command": "python3 tools/release_tag.py --dry-run --run-checks --release-state draft --push-tag --output reports/release_tag_report.json", "description": "Plan release tagging flow with checks and draft release creation." }, { "command": "python3 tools/release_tag.py --run-checks --release-state publish --push-tag --output reports/release_tag_report.publish.json", "description": "Execute release flow and create a published GitHub release (triggers publish workflow)." } ], "id": "release_tag", "inputs": [ { "flag": "--version", "kind": "string", "name": "version", "required": false }, { "default": "v", "flag": "--tag-prefix", "kind": "string", "name": "tag_prefix", "required": false }, { "flag": "--title", "kind": "string", "name": "title", "required": false }, { "flag": "--notes-file", "kind": "file", "name": "notes_file", "required": false }, { "default": "none", "flag": "--release-state", "kind": "string", "name": "release_state", "required": false }, { "flag": "--push-tag", "kind": "string", "name": "push_tag", "required": false }, { "flag": "--run-checks", "kind": "string", "name": "run_checks", "required": false }, { "flag": "--allow-dirty", "kind": "string", "name": "allow_dirty", "required": false }, { "flag": "--allow-non-main", "kind": "string", "name": "allow_non_main", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "default": "reports/release_tag_report.json", "flag": "--output", "kind": "file", "name": "output", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/release_tag_report.json", "description": "Release/tag operation report with synchronized metadata validation, step outcomes, and next steps.", "kind": "file", "name": "release_tag_report_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "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/....", "tags": [ "release", "tag", "operations", "automation" ] }, { "contracts": { "consumes": [ "synthgen_sample_contract" ] }, "docs": [ "docs/synthgen_intake.md", "docs/synthgen_repo_integration.md", "docs/synthgen_contract.md", "docs/production_readiness.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes rendered SynthGen overlay image.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/render_synthgen_overlay.py", "examples": [ { "command": "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", "description": "Render one animal_v1 sample overlay." } ], "id": "render_synthgen_overlay", "inputs": [ { "flag": "--dataset-root", "kind": "dir", "name": "dataset_root", "required": true }, { "flag": "--schema-id", "kind": "string", "name": "schema_id", "required": false }, { "default": 0, "flag": "--sample-index", "kind": "number", "name": "sample_index", "required": false }, { "default": 0.45, "flag": "--alpha", "kind": "number", "name": "alpha", "required": false }, { "flag": "--output", "kind": "file", "name": "output", "required": true } ], "maturity": "experimental", "outputs": [ { "default": null, "description": "Rendered overlay PNG.", "kind": "file", "name": "overlay_png" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Render semantic + instance + keypoint overlays from SynthGen shard samples.", "tags": [ "synthgen", "visualization", "overlay", "keypoints", "segmentation", "depth" ] }, { "docs": [ "docs/ttt_protocol.md", "docs/ttt_compare_boilerplates.md", "manual/chapters/15_ttt_tent_mim.tex", "docs/production_readiness.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Write generated docs PNG assets.", "flag": "--docs-assets-dir", "kind": "dir", "scope": "tree" }, { "description": "Copy generated PNG assets into manual/figures.", "flag": "--manual-figures-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/render_ttt_manual_figures.py", "examples": [ { "command": "python3 tools/render_ttt_manual_figures.py", "description": "Render validated TTT evidence-boundary, pipeline, and provenance figures for docs and manual." }, { "command": "python3 tools/render_ttt_manual_figures.py --docs-assets-dir tmp/ttt_docs --manual-figures-dir tmp/ttt_manual", "description": "Render the same figures into alternate output directories for inspection." } ], "id": "render_ttt_manual_figures", "inputs": [ { "default": "docs/assets/ttt_method_results_source.json", "flag": "--source-json", "kind": "file", "name": "source_json", "required": false }, { "default": "docs/assets", "flag": "--docs-assets-dir", "kind": "dir", "name": "docs_assets_dir", "required": false }, { "default": "manual/figures", "flag": "--manual-figures-dir", "kind": "dir", "name": "manual_figures_dir", "required": false } ], "maturity": "research", "outputs": [ { "default": null, "description": "Validated TTT evidence-boundary summary PNG.", "kind": "file", "name": "summary_png", "path": "docs/assets/ttt_method_results_summary.png" }, { "default": null, "description": "TTT compare workflow PNG.", "kind": "file", "name": "pipeline_png", "path": "docs/assets/ttt_compare_pipeline.png" }, { "default": null, "description": "Provenance-bound TTT example PNG.", "kind": "file", "name": "qualitative_png", "path": "docs/assets/ttt_probe_example_panel.png" }, { "default": null, "description": "Fixed result source JSON used to render the manual figures.", "kind": "file", "name": "summary_source_json", "path": "docs/assets/ttt_method_results_source.json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Render the six-file docs/manual TTT figure bundle atomically from validated synthetic-fixture or hash-bound measured sources.", "tags": [ "ttt", "docs", "manual", "figures", "render" ] }, { "docs": [ "docs/license_policy.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Write the dependency license JSON report.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/report_dependency_licenses.py", "examples": [ { "command": "python3 tools/report_dependency_licenses.py --output reports/dependency_licenses.json", "description": "Write a dependency license report for the current environment." } ], "id": "report_dependency_licenses", "inputs": [ { "default": "reports/dependency_licenses.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--requirements", "kind": "file", "name": "requirements", "required": false }, { "flag": "--only-direct", "kind": "string", "name": "only_direct", "required": false }, { "flag": "--fail-on-copyleft", "kind": "string", "name": "fail_on_copyleft", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/dependency_licenses.json", "description": "Dependency licenses JSON artifact.", "kind": "file", "name": "dependency_licenses_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Generate a best-effort dependency license report from installed Python packages (not legal advice).", "tags": [ "policy", "license" ] }, { "contracts": { "consumes": [ "support_profile_set_proposal_json", "support_profile_spec_json", "support_profile_record_json" ], "produces": [ "support_profile_record_json" ] }, "docs": [ "README.md", "Readme_jp.md", "docs/adaptive_image_routing.md", "docs/schemas/support_profile_set_proposal.schema.json", "docs/schemas/support_profile_record.schema.json" ], "effects": { "fixed_writes": [ { "description": "With --approve, atomically appends only to the canonical dormant support-profile SSOT.", "kind": "file", "path": "yolozu/data/adaptive_routing/support_profiles.jsonl", "scope": "path" } ], "writes": [] }, "entrypoint": "tools/review_image_pipeline_support_profiles.py", "examples": [ { "command": "python3 tools/review_image_pipeline_support_profiles.py --proposal reports/support_profile_set_proposal.json --family-id yolox --channel Experimental --expected-head-digest --expect-no-current-profile-set --reviewer-role-id repo_maintainer --public-review-id gh- --reason 'Review complete dormant target scope'", "description": "Dry-run every complete-set, immutable-definition, review, and stale-head gate; no record is written." }, { "command": "python3 tools/review_image_pipeline_support_profiles.py --help", "description": "Inspect the Experimental dormant support-profile review interface contract." } ], "id": "review_image_pipeline_support_profiles", "inputs": [ { "flag": "--proposal", "kind": "file", "name": "proposal", "required": false }, { "flag": "--family-id", "kind": "string", "name": "family_id", "required": false }, { "flag": "--channel", "kind": "string", "name": "channel", "required": false }, { "flag": "--expected-head-digest", "kind": "string", "name": "expected_head_digest", "required": false }, { "flag": "--expected-current-profile-set-record-digest", "kind": "string", "name": "expected_current_profile_set_record_digest", "required": false }, { "flag": "--expected-current-profile-set-digest", "kind": "string", "name": "expected_current_profile_set_digest", "required": false }, { "flag": "--expect-no-current-profile-set", "kind": "string", "name": "expect_no_current_profile_set", "required": false }, { "flag": "--reviewer-role-id", "kind": "string", "name": "reviewer_role_id", "required": false }, { "flag": "--public-review-id", "kind": "string", "name": "public_review_id", "required": false }, { "flag": "--reason", "kind": "string", "name": "reason", "required": false }, { "default": ".", "flag": "--workspace", "kind": "dir", "name": "workspace", "required": false }, { "flag": "--approve", "kind": "string", "name": "approve", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "stdout", "description": "Bounded machine-readable dry-run or apply outcome that states dormant-only scope.", "kind": "stdout", "name": "support_profile_review_outcome" }, { "default": "yolozu/data/adaptive_routing/support_profiles.jsonl", "description": "Canonical append-only reviewed dormant support-profile stream after explicit approval.", "kind": "file", "name": "support_profile_stream" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Dry-run or atomically append one complete reviewed dormant exact-measured support-profile set; review alone never changes lifecycle support or availability.", "tags": [ "adaptive-inference", "experimental", "review", "support-profile", "ssot" ] }, { "docs": [ "docs/checkpoint_compatibility.md", "docs/real_model_interface.md", "docs/tensorrt_pipeline.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Removes any prior target, then writes the backend suite report only after checkpoint compatibility and parity/benchmark execution succeed.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/rtdetr_pose_backend_suite.py", "examples": [ { "command": "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", "description": "Torch ↔ ONNXRuntime parity + benchmark (CPU)." } ], "id": "rtdetr_pose_backend_suite", "inputs": [ { "flag": "--config", "kind": "file", "name": "config", "required": true }, { "description": "Optional checkpoint path; requires torch in --backends so compatibility is verified.", "flag": "--checkpoint", "kind": "file", "name": "checkpoint", "required": false }, { "description": "Explicit transfer/diagnostic opt-in for name-and-shape partial loading; records status=partial in the report.", "flag": "--allow-partial-checkpoint", "kind": "string", "name": "allow_partial_checkpoint", "required": false }, { "flag": "--device", "kind": "string", "name": "device", "required": false }, { "flag": "--image-size", "kind": "number", "name": "image_size", "required": false }, { "flag": "--batch", "kind": "number", "name": "batch", "required": false }, { "flag": "--samples", "kind": "number", "name": "samples", "required": false }, { "flag": "--seed", "kind": "number", "name": "seed", "required": false }, { "flag": "--onnx", "kind": "file", "name": "onnx", "required": false }, { "flag": "--engine", "kind": "file", "name": "engine", "required": false }, { "flag": "--input-name", "kind": "string", "name": "input_name", "required": false }, { "flag": "--onnx-meta", "kind": "file", "name": "onnx_meta", "required": false }, { "flag": "--engine-meta", "kind": "file", "name": "engine_meta", "required": false }, { "flag": "--embed-meta", "kind": "string", "name": "embed_meta", "required": false }, { "flag": "--trtexec", "kind": "string", "name": "trtexec", "required": false }, { "flag": "--backends", "kind": "string", "name": "backends", "required": false }, { "flag": "--reference", "kind": "string", "name": "reference", "required": false }, { "flag": "--score-atol", "kind": "number", "name": "score_atol", "required": false }, { "flag": "--bbox-atol", "kind": "number", "name": "bbox_atol", "required": false }, { "flag": "--warmup", "kind": "number", "name": "warmup", "required": false }, { "flag": "--iterations", "kind": "number", "name": "iterations", "required": false }, { "default": "reports/rtdetr_pose_backend_suite.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/rtdetr_pose_backend_suite.json", "description": "JSON report with checkpoint compatibility/provenance, parity, and benchmark evidence.", "kind": "file", "name": "report_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true, "notes": "torch/onnxrt can run on CPU; TensorRT requires Linux+NVIDIA+tensorrt and a built engine plan." }, "requires": { "python_packages": [ "torch", "numpy" ] }, "runner": "python3", "summary": "Fail-closed RT-DETR backend parity + benchmark suite with shared checkpoint compatibility evidence.", "tags": [ "rtdetr_pose", "parity", "benchmark" ] }, { "docs": [ "docs/continual_learning.md", "docs/backbones.md", "docs/quantization.md", "docs/training_inference_export.md", "rtdetr_pose/README.md" ], "effects": { "fixed_writes": [ { "description": "Default run root when --run-dir is not set.", "kind": "dir", "path": "runs/continual", "scope": "tree" } ], "writes": [ { "description": "Optional explicit run directory.", "flag": "--run-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "rtdetr_pose/tools/train_continual.py", "examples": [ { "command": "python3 rtdetr_pose/tools/train_continual.py --config configs/continual/rtdetr_pose_domain_inc_example.yaml", "description": "Domain-incremental continual fine-tuning (example config)." }, { "command": "python3 rtdetr_pose/tools/train_continual.py --config configs/continual/rtdetr_pose_domain_inc_example.yaml --replay-size 0", "description": "Memoryless mode (disable replay; still uses previous-checkpoint self-distillation when distill.enabled)." }, { "command": "python3 rtdetr_pose/tools/train_continual.py --config configs/continual/rtdetr_pose_domain_inc_example.yaml --initial-checkpoint runs/initial/checkpoint.pt --replay-size 0", "description": "Start both task training and later FWT evaluation from an explicit current-compatible checkpoint." } ], "id": "rtdetr_pose_train_continual", "inputs": [ { "flag": "--config", "kind": "file", "name": "config", "required": true }, { "flag": "--run-dir", "kind": "dir", "name": "run_dir", "required": false }, { "flag": "--initial-checkpoint", "kind": "file", "name": "initial_checkpoint", "required": false }, { "flag": "--replay-size", "kind": "number", "name": "replay_size", "required": false }, { "flag": "--replay-fraction", "kind": "number", "name": "replay_fraction", "required": false }, { "flag": "--replay-per-task-cap", "kind": "number", "name": "replay_per_task_cap", "required": false } ], "maturity": "research", "outputs": [ { "default": null, "description": "continual_run.json under the run dir.", "kind": "file", "name": "run_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true, "notes": "CPU works for smoke runs; GPU is recommended for real training." }, "requires": { "python_packages": [ "torch", "PyYAML" ] }, "runner": "python3", "summary": "Continual fine-tuning runner for rtdetr_pose with an explicit initial-checkpoint/FWT baseline, optional no-object-aware foreground response selection, replay/LoRA/EWC/SI, and per-task checkpoint, teacher, data-order, time, memory, and command provenance.", "tags": [ "rtdetr_pose", "continual", "train", "replay", "self_distill", "distill", "lora", "ewc", "si", "backbone" ] }, { "docs": [ "docs/llm_integrations.md", "docs/mcp_extension_architecture.md", "docs/openai_mcp_actions.md", "manual/chapters/20_llm_mcp_integrations.tex" ], "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "tools/run_actions_api.py", "examples": [ { "command": "python3 tools/run_actions_api.py", "description": "Start Actions API on default bind." }, { "command": "python3 tools/run_actions_api.py --host 127.0.0.1 --port 8080 --workers 1", "description": "Start Actions API with explicit host/port/workers." } ], "id": "run_actions_api", "inputs": [ { "default": "0.0.0.0", "description": "Bind host.", "flag": "--host", "kind": "string", "name": "host", "required": false }, { "default": 8080, "description": "Bind port.", "flag": "--port", "kind": "number", "name": "port", "required": false }, { "default": 1, "description": "Uvicorn worker count.", "flag": "--workers", "kind": "number", "name": "workers", "required": false }, { "description": "Enable auto-reload for local development.", "flag": "--reload", "kind": "string", "name": "reload", "required": false } ], "maturity": "stable", "outputs": [ { "description": "OpenAPI schema available at /openapi.json.", "kind": "string", "name": "openapi" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "fastapi", "uvicorn" ] }, "runner": "python3", "summary": "Run the GPT Actions API, including fail-closed typed TTT/CTTA export jobs with full checkpoint preflight.", "tags": [ "openapi", "fastapi", "integration", "llm" ] }, { "docs": [ "docs/external_finetune_smoke.md", "docs/interop_detectron2_mmdet.md", "docs/interop_yolox.md", "docs/license_policy.md", "docs/tools_index.md", "docs/training_inference_export.md", "reports/external_runtime_evidence_2026-07-30.md", "reports/external_runtime_qualification_2026-07-30.json" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes external finetune smoke report JSON with execution status, wall time, peak RSS, failures, and artifact hashes.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Writes generated helper files and per-framework working directories.", "flag": "--work-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/run_external_finetune_smoke.py", "examples": [ { "command": "python3 tools/run_external_finetune_smoke.py --dataset-root data/smoke --split train --output reports/external_finetune_smoke.json", "description": "Dry-run matrix for YOLOX/Ultralytics/MMDetection/Detectron2/RT-DETR finetune entrypoints." }, { "command": "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", "description": "Execute real training for selected frameworks, with YOLOX as the preferred Apache-2.0-friendly external lane." }, { "command": "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", "description": "Audit MMDetection/Detectron2 external launcher execution paths; projection failures are reported separately via projection_error." } ], "id": "run_external_finetune_smoke", "inputs": [ { "default": "data/smoke", "flag": "--dataset-root", "kind": "dir", "name": "dataset_root", "required": false }, { "default": "train", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "default": "reports/external_finetune_smoke.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--work-dir", "kind": "dir", "name": "work_dir", "required": false }, { "flag": "--python", "kind": "string", "name": "python", "required": false }, { "default": 1, "flag": "--epochs", "kind": "number", "name": "epochs", "required": false }, { "default": 1, "flag": "--max-steps", "kind": "number", "name": "max_steps", "required": false }, { "default": 2, "flag": "--batch-size", "kind": "number", "name": "batch_size", "required": false }, { "default": 96, "flag": "--image-size", "kind": "number", "name": "image_size", "required": false }, { "default": "cpu", "flag": "--device", "kind": "string", "name": "device", "required": false }, { "description": "Framework id to include in matrix (repeatable).", "flag": "--framework", "kind": "string", "name": "framework", "required": false }, { "description": "Framework id to execute in non-dry mode (repeatable).", "flag": "--non-dry-framework", "kind": "string", "name": "non_dry_framework", "required": false }, { "description": "Fail when no framework is configured for non-dry execution.", "flag": "--require-non-dry", "kind": "string", "name": "require_non_dry", "required": false }, { "description": "Fail when no framework executed a training command.", "flag": "--require-training-execution", "kind": "string", "name": "require_training_execution", "required": false }, { "flag": "--mmdet-train-script", "kind": "file", "name": "mmdet_train_script", "required": false }, { "flag": "--detectron2-train-script", "kind": "file", "name": "detectron2_train_script", "required": false }, { "flag": "--yolox-train-script", "kind": "file", "name": "yolox_train_script", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/external_finetune_smoke.json", "description": "Per-framework external finetune smoke report including failure_code, projection_error, and train_path_audited fields.", "kind": "file", "name": "external_finetune_smoke_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Run external finetune smoke matrix for YOLOX/Ultralytics/MMDetection/Detectron2/RT-DETR; non-dry projection-only lanes fail closed, while the report records dependency status, artifact hashes, wall time, peak RSS, runtime, source, and license boundaries.", "tags": [ "finetune", "interop", "smoke", "training" ] }, { "docs": [ "docs/schemas/compatible_host_external_runtime_qualification.schema.json", "docs/training_capability_matrix.md", "docs/external_finetune_smoke.md", "docs/tools_index.md", "reports/external_runtime_compatible_host_evidence_2026-07-30.md", "reports/external_runtime_compatible_host_primary_2026-07-30.json", "reports/external_runtime_compatible_host_primary_dataset_2026-07-30.json", "reports/external_runtime_compatible_host_primary_tao_2026-07-30.json", "reports/external_runtime_compatible_host_primary_workflow_2026-07-30.json", "reports/external_runtime_compatible_host_independent_2026-07-30.json", "reports/external_runtime_compatible_host_independent_dataset_2026-07-30.json", "reports/external_runtime_compatible_host_independent_tao_2026-07-30.json", "reports/external_runtime_compatible_host_independent_workflow_2026-07-30.json" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Installs pinned external runtimes and writes per-lane training evidence under a fresh output root.", "flag": "--output-dir", "kind": "dir", "scope": "tree" }, { "description": "Clones pinned external runtime source trees when absent.", "flag": "--runtime-root", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "scripts/run_external_runtime_gpu_qualification.sh", "examples": [ { "command": "bash scripts/run_external_runtime_gpu_qualification.sh --output-dir reports/compatible_host_external_runtimes --dataset-root data/real_multitask_fewshot", "description": "Run pinned YOLOX and OpenMMLab non-dry training on a compatible Linux CUDA host." }, { "command": "bash scripts/run_external_runtime_gpu_qualification.sh --help", "description": "Show compatible-host input and output options." } ], "id": "run_external_runtime_gpu_qualification", "inputs": [ { "flag": "--output-dir", "kind": "dir", "name": "output_dir", "required": true }, { "default": "data/real_multitask_fewshot", "flag": "--dataset-root", "kind": "dir", "name": "dataset_root", "required": false }, { "default": "/tmp/yolozu-external-runtimes", "flag": "--runtime-root", "kind": "dir", "name": "runtime_root", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "/qualification_summary.json", "description": "Pinned runtime versions, per-lane execution state, launcher resource use, reports, checkpoint hashes, and structural resume/export/eval/parity handoff validation.", "kind": "file", "name": "external_runtime_qualification_json" } ], "platform": { "cpu_ok": false, "gpu_required": true, "linux_ok": true, "macos_ok": false }, "requires": { "commands": [ "git", "nvidia-smi" ], "network": true, "python_packages": [ "torch" ] }, "runner": "bash", "summary": "Install pinned YOLOX and OpenMMLab runtimes and execute all non-dry training lanes on a compatible Linux CUDA host while retaining structured failures and requiring checkpoints, launcher resource use, and structural resume/export/eval/parity handoff validation.", "tags": [ "external-runtime", "gpu", "training", "qualification" ] }, { "docs": [ "docs/image_service_mcp.md", "docs/llm_integrations.md", "docs/mcp_extension_architecture.md", "docs/copilot_mcp_integration.md", "docs/openai_mcp_actions.md", "manual/chapters/20_llm_mcp_integrations.tex", "docs/ai_first.md", "docs/tools_index.md" ], "effects": { "fixed_writes": [ { "kind": "dir", "path": "runs/mcp_image_service", "scope": "tree" } ], "writes": [] }, "entrypoint": "tools/run_mcp_server.py", "examples": [ { "command": "yolozu-mcp", "description": "Start MCP stdio server." }, { "command": "yolozu-mcp --transport streamable-http --surface image-service --host 127.0.0.1 --port 8000 --http-path /mcp", "description": "Start the bounded five-tool image service on a loopback Streamable HTTP endpoint." }, { "command": "yolozu-mcp --print-tools --guaranteed --ids-only", "description": "Inspect the four guaranteed AI-safe MCP tool ids." }, { "command": "yolozu-mcp --print-tools --supported --ids-only", "description": "Inspect all registered live MCP tool ids." }, { "command": "yolozu-mcp --print-tools --ids-only --maturity stable --tag validation", "description": "Filter compact discovery by maturity and tag." }, { "command": "yolozu-mcp --sample-generate-config > reports/ai_generate_config.json && yolozu-mcp --sample-review-config reports/ai_generate_config.json", "description": "Generate deterministic sample config and review it." } ], "id": "run_mcp_server", "inputs": [ { "default": "stdio", "description": "MCP transport: stdio or streamable-http.", "flag": "--transport", "kind": "string", "name": "transport", "required": false }, { "default": "full", "description": "Tool surface: full, or the bounded five-tool image-service surface.", "flag": "--surface", "kind": "string", "name": "surface", "required": false }, { "default": "127.0.0.1", "description": "Streamable HTTP bind host; external binds require the image-service surface, HTTPS public URL, and bearer authentication.", "flag": "--host", "kind": "string", "name": "host", "required": false }, { "default": 8000, "description": "Streamable HTTP bind port in 1..65535.", "flag": "--port", "kind": "number", "name": "port", "required": false }, { "default": "/mcp", "description": "Absolute Streamable HTTP MCP path without traversal.", "flag": "--http-path", "kind": "string", "name": "http_path", "required": false }, { "description": "Exact external HTTPS MCP URL when running behind a reviewed TLS proxy.", "flag": "--public-url", "kind": "string", "name": "public_url", "required": false }, { "default": "YOLOZU_MCP_AUTH_TOKEN", "description": "Environment variable containing the bearer token; the token value is not accepted on the command line.", "flag": "--auth-token-env", "kind": "string", "name": "auth_token_env", "required": false }, { "default": "local", "description": "Credential-bound lowercase tenant identifier for private asset and job storage.", "flag": "--tenant-id", "kind": "string", "name": "tenant_id", "required": false }, { "default": 86400, "description": "Private asset, terminal job, and output retention in 300..604800 seconds.", "flag": "--retention-seconds", "kind": "number", "name": "retention_seconds", "required": false }, { "description": "Optional manifest override for tool-surface introspection; default is the resource packaged with yolozu.", "flag": "--manifest", "kind": "file", "name": "manifest", "required": false }, { "description": "Print manifest-backed tool metadata JSON and exit.", "flag": "--print-tools", "kind": "string", "name": "print_tools", "required": false }, { "description": "Filter discovery to the guaranteed AI-safe MCP set.", "flag": "--guaranteed", "kind": "string", "name": "guaranteed", "required": false }, { "description": "Compatibility filter for tools registered on the live MCP surface; registration is not an execution guarantee.", "flag": "--supported", "kind": "string", "name": "supported", "required": false }, { "description": "Repeatable explicit-maturity filter; unclassified exclusions are counted in filter_diagnostics.", "flag": "--maturity", "kind": "string", "name": "maturity", "required": false }, { "description": "Repeatable explicit-tag filter; unclassified exclusions are counted in filter_diagnostics.", "flag": "--tag", "kind": "string", "name": "tag", "required": false }, { "description": "Emit compact JSON with sorted selected ids instead of full records.", "flag": "--ids-only", "kind": "string", "name": "ids_only", "required": false }, { "description": "Print deterministic sample generate_config payload and exit.", "flag": "--sample-generate-config", "kind": "string", "name": "sample_generate_config", "required": false }, { "description": "Review config JSON file and print review payload.", "flag": "--sample-review-config", "kind": "file", "name": "sample_review_config", "required": false }, { "default": ".", "description": "Workspace root for review path-safety checks.", "flag": "--workspace-root", "kind": "dir", "name": "workspace_root", "required": false } ], "maturity": "stable", "outputs": [ { "description": "MCP stdio or Streamable HTTP transport for compatible clients.", "kind": "string", "name": "transport" }, { "description": "When --print-tools is used, prints explicit public surface sets, exact live MCP summaries/input schemas, applied filters with unclassified counts, and records or compact ids.", "kind": "stdout", "name": "tool_surface_json" }, { "description": "When --sample-generate-config is used, prints deterministic sample config JSON.", "kind": "stdout", "name": "sample_generate_config_json" }, { "description": "When --sample-review-config is used, prints review JSON.", "kind": "stdout", "name": "sample_review_config_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "mcp" ] }, "runner": "python3", "summary": "Run the YOLOZU MCP server over stdio or Streamable HTTP with bounded image-service tools, exclusive tenant ownership, cancellable process jobs, rate limits, and idle-time retention cleanup.", "tags": [ "mcp", "integration", "llm", "ai-first", "deterministic" ] }, { "docs": [ "docs/training_inference_export.md", "manual/chapters/16_depth_6dof_symmetry.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes per-task logs, checkpoints, and final multitask report.", "flag": "--out", "kind": "dir", "scope": "tree" }, { "description": "When --prepare is set, creates or overwrites prepared dataset root.", "flag": "--dataset-root", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/run_real_multitask_finetune_demo.py", "examples": [ { "command": "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", "description": "Run a CPU smoke of staged bbox->segmentation->keypoints->depth->pose6d finetuning." } ], "id": "run_real_multitask_finetune_demo", "inputs": [ { "default": "data/real_multitask_fewshot", "flag": "--dataset-root", "kind": "dir", "name": "dataset_root", "required": false }, { "flag": "--prepare", "kind": "string", "name": "prepare", "required": false }, { "description": "Request tiny COCO download when inputs are missing (requires --allow-auto-download and --accept-dataset-license).", "flag": "--download-if-missing", "kind": "string", "name": "download_if_missing", "required": false }, { "flag": "--download-num-images", "kind": "number", "name": "download_num_images", "required": false }, { "flag": "--prepare-args", "kind": "string", "name": "prepare_args", "required": false }, { "default": "reports/real_multitask_finetune_demo", "flag": "--out", "kind": "dir", "name": "out", "required": false }, { "default": "cpu", "flag": "--device", "kind": "string", "name": "device", "required": false }, { "default": 1, "flag": "--epochs", "kind": "number", "name": "epochs", "required": false }, { "default": 2, "flag": "--max-steps", "kind": "number", "name": "max_steps", "required": false }, { "default": 2, "flag": "--batch-size", "kind": "number", "name": "batch_size", "required": false }, { "default": 128, "flag": "--image-size", "kind": "number", "name": "image_size", "required": false }, { "default": 4, "flag": "--num-keypoints", "kind": "number", "name": "num_keypoints", "required": false }, { "flag": "--python", "kind": "string", "name": "python", "required": false }, { "default": "cspdarknet_s", "flag": "--backbone-name", "kind": "string", "name": "backbone_name", "required": false }, { "default": "bn", "flag": "--backbone-norm", "kind": "string", "name": "backbone_norm", "required": false }, { "default": "{\"width_mult\": 0.5, \"depth_mult\": 0.34}", "flag": "--backbone-args", "kind": "json", "name": "backbone_args", "required": false }, { "flag": "--skip-imbalance", "kind": "string", "name": "skip_imbalance", "required": false }, { "flag": "--force", "kind": "string", "name": "force", "required": false }, { "description": "Forward --allow-auto-download to preparation step.", "flag": "--allow-auto-download", "kind": "string", "name": "allow_auto_download", "required": false }, { "description": "Forward --accept-dataset-license to preparation step.", "flag": "--accept-dataset-license", "kind": "string", "name": "accept_dataset_license", "required": false }, { "description": "Fail if model-inference-generated labels are detected.", "flag": "--strict-provenance", "kind": "string", "name": "strict_provenance", "required": false }, { "description": "Fail if heuristic/derived labels are present.", "flag": "--strict-realism", "kind": "string", "name": "strict_realism", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/real_multitask_finetune_demo/multitask_finetune_demo_report.json", "description": "Final multitask finetune demo report with per-task status and evidence summary.", "kind": "file", "name": "report_json" }, { "default": "reports/real_multitask_finetune_demo", "description": "Output root containing per-task run directories.", "kind": "dir", "name": "run_root" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Run staged real-image bbox/segmentation/keypoints/depth/pose6d training with strict provenance, checkpoint-handoff hashes, runtime/memory, and explicit task-native metric and heuristic-label boundaries.", "tags": [ "demo", "finetune", "multitask", "real-data" ] }, { "contract_outputs": { "reference_adapter_regression_report_json": "reference_adapter_regression_json" }, "contracts": { "produces": [ "reference_adapter_regression_report_json" ] }, "docs": [ "docs/adapter_contract.md", "docs/adapter_strategy.md", "docs/predictions_interface_contract_policy.md", "docs/real_model_interface.md", "docs/reference_adapter_regression_policy.md", "docs/schema_governance.md" ], "effects": { "fixed_writes": [ { "description": "Default baseline path used by the reference adapter regression flow.", "kind": "file", "path": "baselines/reference_adapter/rtdetr_pose_smoke_val.json", "scope": "path" }, { "description": "Matrix baseline root used when --baseline-layout matrix and --write-baseline are enabled.", "kind": "dir", "path": "baselines/reference_adapter", "scope": "path" } ], "writes": [ { "description": "Writes regression report JSON.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Writes gate-wise diff summary JSON when baseline comparison fails.", "flag": "--diff-summary-out", "kind": "file", "scope": "path" }, { "description": "Writes top-k counterexample overlays when baseline comparison fails.", "flag": "--topk-examples-dir", "kind": "dir", "scope": "tree" }, { "description": "Writes/updates baseline JSON when --write-baseline is used.", "flag": "--baseline", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/run_reference_adapter_regression.py", "examples": [ { "command": "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", "description": "Run micro profile regression (interface contract hard + behavior warn)." }, { "command": "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", "description": "Run interface-contract-only hard gate (schema + consistency)." }, { "command": "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", "description": "Run behavior-only warn gate (aggregate + robust metrics + speed)." }, { "command": "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", "description": "Run full profile with matrix baseline layout." }, { "command": "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", "description": "Refresh the pinned baseline after an intentional interface contract/behavior change." } ], "id": "run_reference_adapter_regression", "inputs": [ { "default": "data/smoke", "flag": "--dataset", "kind": "dir", "name": "dataset", "required": false }, { "default": "val", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "default": 2, "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "default": "baselines/reference_adapter/rtdetr_pose_smoke_val.json", "flag": "--baseline", "kind": "file", "name": "baseline", "required": false }, { "default": "reports/reference_adapter_regression.json", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--diff-summary-out", "kind": "file", "name": "diff_summary_out", "required": false }, { "flag": "--topk-examples-dir", "kind": "dir", "name": "topk_examples_dir", "required": false }, { "default": 3, "flag": "--topk-examples", "kind": "number", "name": "topk_examples", "required": false }, { "flag": "--write-baseline", "kind": "string", "name": "write_baseline", "required": false }, { "default": "requirements-locks/requirements-ci.lock", "flag": "--runtime-lock", "kind": "file", "name": "runtime_lock", "required": false }, { "flag": "--enforce-runtime-lock", "kind": "string", "name": "enforce_runtime_lock", "required": false }, { "flag": "--enforce-weights-hash", "kind": "string", "name": "enforce_weights_hash", "required": false }, { "default": "rtdetr_pose/configs/base.json", "flag": "--config", "kind": "file", "name": "config", "required": false }, { "flag": "--checkpoint", "kind": "file", "name": "checkpoint", "required": false }, { "default": "cpu", "flag": "--device", "kind": "string", "name": "device", "required": false }, { "default": "160", "flag": "--image-size", "kind": "string", "name": "image_size", "required": false }, { "default": 0.05, "flag": "--score-threshold", "kind": "number", "name": "score_threshold", "required": false }, { "default": 20, "flag": "--max-detections", "kind": "number", "name": "max_detections", "required": false }, { "default": 2026, "flag": "--init-seed", "kind": "number", "name": "init_seed", "required": false }, { "default": 0.0, "flag": "--metric-total-detections-abs", "kind": "number", "name": "metric_total_detections_abs", "required": false }, { "default": 0.01, "flag": "--metric-score-sum-abs", "kind": "number", "name": "metric_score_sum_abs", "required": false }, { "default": 0.001, "flag": "--metric-score-mean-abs", "kind": "number", "name": "metric_score_mean_abs", "required": false }, { "default": 0.1, "flag": "--metric-bbox-checksum-abs", "kind": "number", "name": "metric_bbox_checksum_abs", "required": false }, { "default": 0.25, "flag": "--min-fps-ratio", "kind": "number", "name": "min_fps_ratio", "required": false }, { "default": 0.2, "flag": "--absolute-floor-fps", "kind": "number", "name": "absolute_floor_fps", "required": false }, { "default": "relaxed", "flag": "--repro-policy", "kind": "string", "name": "repro_policy", "required": false }, { "default": "hard", "flag": "--schema-gate-mode", "kind": "string", "name": "schema_gate_mode", "required": false }, { "default": "hard", "flag": "--consistency-gate-mode", "kind": "string", "name": "consistency_gate_mode", "required": false }, { "default": "warn", "flag": "--score-gate-mode", "kind": "string", "name": "score_gate_mode", "required": false }, { "default": "warn", "flag": "--perf-gate-mode", "kind": "string", "name": "perf_gate_mode", "required": false }, { "default": 6, "flag": "--canonical-decimals", "kind": "number", "name": "canonical_decimals", "required": false }, { "default": "micro", "flag": "--profile", "kind": "string", "name": "profile", "required": false }, { "default": "flat", "flag": "--baseline-layout", "kind": "string", "name": "baseline_layout", "required": false }, { "default": "baselines/reference_adapter", "flag": "--baseline-root", "kind": "dir", "name": "baseline_root", "required": false }, { "default": "rtdetr_pose", "flag": "--adapter-id", "kind": "string", "name": "adapter_id", "required": false }, { "default": "torch", "flag": "--backend-id", "kind": "string", "name": "backend_id", "required": false }, { "flag": "--matrix-device", "kind": "string", "name": "matrix_device", "required": false }, { "default": "v1", "flag": "--baseline-version", "kind": "string", "name": "baseline_version", "required": false }, { "flag": "--expected-dataset-hash", "kind": "string", "name": "expected_dataset_hash", "required": false }, { "flag": "--expected-weights-hash", "kind": "string", "name": "expected_weights_hash", "required": false }, { "flag": "--expected-checkpoint-hash", "kind": "string", "name": "expected_checkpoint_hash", "required": false }, { "default": "full", "flag": "--capture-provenance", "kind": "string", "name": "capture_provenance", "required": false }, { "default": 0.03, "flag": "--metric-map50-abs", "kind": "number", "name": "metric_map50_abs", "required": false }, { "default": 0.03, "flag": "--metric-map50-95-abs", "kind": "number", "name": "metric_map50_95_abs", "required": false }, { "default": 0.05, "flag": "--metric-worst-k-map50-abs", "kind": "number", "name": "metric_worst_k_map50_abs", "required": false }, { "default": 0.05, "flag": "--metric-median-class-map50-abs", "kind": "number", "name": "metric_median_class_map50_abs", "required": false }, { "default": 0.05, "flag": "--metric-recall-at-k-abs", "kind": "number", "name": "metric_recall_at_k_abs", "required": false }, { "default": 0.1, "flag": "--metric-iou-p10-abs", "kind": "number", "name": "metric_iou_p10_abs", "required": false }, { "default": 0.1, "flag": "--metric-iou-p50-abs", "kind": "number", "name": "metric_iou_p50_abs", "required": false }, { "default": 2.0, "flag": "--metric-missing-count-abs", "kind": "number", "name": "metric_missing_count_abs", "required": false }, { "default": 2.0, "flag": "--metric-extra-count-abs", "kind": "number", "name": "metric_extra_count_abs", "required": false }, { "default": 2.0, "flag": "--metric-class-mismatch-abs", "kind": "number", "name": "metric_class_mismatch_abs", "required": false }, { "default": 3, "flag": "--metric-worst-k", "kind": "number", "name": "metric_worst_k", "required": false }, { "default": 20, "flag": "--metric-recall-k", "kind": "number", "name": "metric_recall_k", "required": false }, { "flag": "--peer-report", "kind": "file", "name": "peer_report", "required": false }, { "default": "off", "flag": "--backend-parity-mode", "kind": "string", "name": "backend_parity_mode", "required": false }, { "default": 0.03, "flag": "--backend-parity-map50-abs", "kind": "number", "name": "backend_parity_map50_abs", "required": false }, { "default": 0.03, "flag": "--backend-parity-map50-95-abs", "kind": "number", "name": "backend_parity_map50_95_abs", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/reference_adapter_regression.json", "description": "Reference adapter regression report JSON.", "kind": "file", "name": "reference_adapter_regression_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "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.", "tags": [ "adapter", "regression", "baseline", "rtdetr_pose" ] }, { "docs": [ "docs/tensorrt_pipeline.md" ], "effects": { "fixed_writes": [ { "description": "Default run root when --run-dir is not provided.", "kind": "dir", "path": "runs/rtdetr_pose_backend_suite", "scope": "tree" } ], "writes": [ { "description": "Writes run artifacts under --run-dir.", "flag": "--run-dir", "kind": "dir", "scope": "tree" }, { "description": "Optional ONNX output path.", "flag": "--onnx", "kind": "file", "scope": "path" }, { "description": "Optional TensorRT engine output path.", "flag": "--engine", "kind": "file", "scope": "path" }, { "description": "Optional timing cache path.", "flag": "--timing-cache", "kind": "file", "scope": "path" }, { "description": "Optional suite report output path.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/run_rtdetr_pose_backend_suite.py", "examples": [ { "command": "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", "description": "Run export_trt + backend suite (GPU)." } ], "id": "run_rtdetr_pose_backend_suite", "inputs": [ { "default": "rtdetr_pose/configs/base.json", "flag": "--config", "kind": "file", "name": "config", "required": false }, { "flag": "--checkpoint", "kind": "file", "name": "checkpoint", "required": false }, { "flag": "--device", "kind": "string", "name": "device", "required": false }, { "flag": "--export-device", "kind": "string", "name": "export_device", "required": false }, { "flag": "--precision", "kind": "string", "name": "precision", "required": false }, { "flag": "--input-name", "kind": "string", "name": "input_name", "required": false }, { "flag": "--opset", "kind": "number", "name": "opset", "required": false }, { "flag": "--dynamic-hw", "kind": "string", "name": "dynamic_hw", "required": false }, { "flag": "--no-dynamic-hw", "kind": "string", "name": "no_dynamic_hw", "required": false }, { "flag": "--export-image-size", "kind": "number", "name": "export_image_size", "required": false }, { "flag": "--suite-image-size", "kind": "number", "name": "suite_image_size", "required": false }, { "flag": "--max-image-size", "kind": "number", "name": "max_image_size", "required": false }, { "flag": "--min-shape", "kind": "string", "name": "min_shape", "required": false }, { "flag": "--opt-shape", "kind": "string", "name": "opt_shape", "required": false }, { "flag": "--max-shape", "kind": "string", "name": "max_shape", "required": false }, { "flag": "--workspace", "kind": "number", "name": "workspace", "required": false }, { "flag": "--trtexec", "kind": "string", "name": "trtexec", "required": false }, { "flag": "--extra-args", "kind": "string", "name": "extra_args", "required": false }, { "flag": "--batch", "kind": "number", "name": "batch", "required": false }, { "flag": "--samples", "kind": "number", "name": "samples", "required": false }, { "flag": "--seed", "kind": "number", "name": "seed", "required": false }, { "flag": "--score-atol", "kind": "number", "name": "score_atol", "required": false }, { "flag": "--bbox-atol", "kind": "number", "name": "bbox_atol", "required": false }, { "flag": "--warmup", "kind": "number", "name": "warmup", "required": false }, { "flag": "--iterations", "kind": "number", "name": "iterations", "required": false }, { "flag": "--backends", "kind": "string", "name": "backends", "required": false }, { "flag": "--embed-meta", "kind": "string", "name": "embed_meta", "required": false }, { "flag": "--run-id", "kind": "string", "name": "run_id", "required": false }, { "flag": "--run-dir", "kind": "dir", "name": "run_dir", "required": false }, { "default": null, "flag": "--onnx", "kind": "file", "name": "onnx", "required": false }, { "default": null, "flag": "--engine", "kind": "file", "name": "engine", "required": false }, { "default": null, "flag": "--timing-cache", "kind": "file", "name": "timing_cache", "required": false }, { "default": null, "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--skip-onnx", "kind": "string", "name": "skip_onnx", "required": false }, { "flag": "--skip-engine", "kind": "string", "name": "skip_engine", "required": false }, { "flag": "--force", "kind": "string", "name": "force", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "runs/rtdetr_pose_backend_suite//backend_suite.json", "description": "Suite report report artifact.", "kind": "file", "name": "suite_report" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true, "notes": "Dry-run works anywhere; full export+TRT engine build requires Linux+NVIDIA+tensorrt and trtexec." }, "requires": { "python_packages": [ "torch", "numpy" ] }, "runner": "python3", "summary": "End-to-end runner for rtdetr_pose: export (PyTorch→ONNX→TRT) + backend parity/benchmark suite.", "tags": [ "rtdetr_pose", "tensorrt", "parity", "benchmark", "runpod" ] }, { "contracts": { "produces": [ "metrics_report_json" ] }, "effects": { "fixed_writes": [], "writes": [ { "description": "Write the scenario JSON report.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/run_scenarios.py", "examples": [ { "command": "python3 tools/run_scenarios.py --adapter dummy --dataset data/coco128 --max-images 50", "description": "Run a basic dummy scenario pass." } ], "id": "run_scenarios", "inputs": [ { "flag": "--config", "kind": "file", "name": "config", "required": false }, { "flag": "--adapter", "kind": "string", "name": "adapter", "required": false }, { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": false }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--predictions", "kind": "file", "name": "predictions", "required": false }, { "flag": "--checkpoint", "kind": "file", "name": "checkpoint", "required": false }, { "flag": "--device", "kind": "string", "name": "device", "required": false }, { "flag": "--image-size", "kind": "string", "name": "image_size", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--max-detections", "kind": "number", "name": "max_detections", "required": false }, { "flag": "--score-threshold", "kind": "number", "name": "score_threshold", "required": false }, { "default": "reports/scenario_run.json", "flag": "--output", "kind": "file", "name": "output", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/scenario_run.json", "description": "Scenario run JSON artifact.", "kind": "file", "name": "scenario_run_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Run the scenario suite pipeline (adapter + constraints utilities) and write a report JSON.", "tags": [ "scenarios", "pipeline" ] }, { "contracts": { "produces": [ "predictions_json", "eval_suite_report_json", "metrics_report_json" ] }, "docs": [ "deploy/runpod/README.md", "docs/tensorrt_pipeline.md" ], "effects": { "fixed_writes": [ { "description": "Default engine outputs and timing cache.", "kind": "dir", "path": "engines", "scope": "tree" }, { "description": "Default reports/artifacts (predictions, parity, eval suite, latency, generated configs).", "kind": "dir", "path": "reports", "scope": "tree" } ], "writes": [ { "description": "Optional run folder to copy key artifacts into.", "flag": "--run-dir", "kind": "dir", "scope": "tree" }, { "description": "Writes TensorRT engine outputs rendered from template.", "flag": "--engine-template", "kind": "file", "scope": "path" }, { "description": "Writes per-bucket engine build metadata rendered from template.", "flag": "--engine-meta-template", "kind": "file", "scope": "path" }, { "description": "Writes TensorRT timing cache.", "flag": "--timing-cache", "kind": "file", "scope": "path" }, { "description": "Writes INT8 calibration cache rendered from template (when used).", "flag": "--calib-cache-template", "kind": "file", "scope": "path" }, { "description": "Writes calibration image list rendered from template (when used).", "flag": "--calib-list-template", "kind": "file", "scope": "path" }, { "description": "Writes ONNXRuntime predictions JSON rendered from template.", "flag": "--pred-onnxrt-template", "kind": "file", "scope": "path" }, { "description": "Writes TensorRT predictions JSON rendered from template.", "flag": "--pred-trt-template", "kind": "file", "scope": "path" }, { "description": "Writes parity report JSON rendered from template.", "flag": "--parity-report-template", "kind": "file", "scope": "path" }, { "description": "Writes per-bucket latency report JSON rendered from template.", "flag": "--latency-template", "kind": "file", "scope": "path" }, { "description": "Writes generated benchmark harness config JSON.", "flag": "--benchmark-config", "kind": "file", "scope": "path" }, { "description": "Writes benchmark latency report JSON.", "flag": "--benchmark-output", "kind": "file", "scope": "path" }, { "description": "Optional JSONL history file for benchmark latency reports.", "flag": "--benchmark-history", "kind": "file", "scope": "path" }, { "description": "Writes eval suite output JSON.", "flag": "--eval-suite-output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/run_trt_pipeline.py", "examples": [ { "command": "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", "description": "Run full TRT pipeline (Runpod/Linux)." } ], "id": "run_trt_pipeline", "inputs": [ { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--onnx-template", "kind": "string", "name": "onnx_template", "required": true }, { "default": null, "flag": "--run-dir", "kind": "dir", "name": "run_dir", "required": false }, { "flag": "--benchmark-config", "kind": "file", "name": "benchmark_config", "required": false }, { "flag": "--benchmark-history", "kind": "file", "name": "benchmark_history", "required": false }, { "flag": "--benchmark-output", "kind": "file", "name": "benchmark_output", "required": false }, { "flag": "--boxes-scale", "kind": "string", "name": "boxes_scale", "required": false }, { "flag": "--buckets", "kind": "string", "name": "buckets", "required": false }, { "flag": "--calib-cache-template", "kind": "string", "name": "calib_cache_template", "required": false }, { "flag": "--calib-dataset", "kind": "dir", "name": "calib_dataset", "required": false }, { "flag": "--calib-images", "kind": "number", "name": "calib_images", "required": false }, { "flag": "--calib-list-template", "kind": "string", "name": "calib_list_template", "required": false }, { "flag": "--calib-split", "kind": "string", "name": "calib_split", "required": false }, { "flag": "--combined-output", "kind": "string", "name": "combined_output", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "flag": "--engine-meta-template", "kind": "string", "name": "engine_meta_template", "required": false }, { "flag": "--engine-template", "kind": "string", "name": "engine_template", "required": false }, { "flag": "--eval-suite-output", "kind": "file", "name": "eval_suite_output", "required": false }, { "flag": "--force", "kind": "string", "name": "force", "required": false }, { "flag": "--help", "kind": "string", "name": "help", "required": false }, { "flag": "--image-size", "kind": "string", "name": "image_size", "required": false }, { "flag": "--input-name", "kind": "string", "name": "input_name", "required": false }, { "flag": "--latency-iterations", "kind": "number", "name": "latency_iterations", "required": false }, { "flag": "--latency-template", "kind": "string", "name": "latency_template", "required": false }, { "flag": "--latency-warmup", "kind": "number", "name": "latency_warmup", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--max-shape", "kind": "string", "name": "max_shape", "required": false }, { "flag": "--min-score", "kind": "number", "name": "min_score", "required": false }, { "flag": "--min-shape", "kind": "string", "name": "min_shape", "required": false }, { "flag": "--notes", "kind": "string", "name": "notes", "required": false }, { "flag": "--opt-shape", "kind": "string", "name": "opt_shape", "required": false }, { "flag": "--parity-bbox-atol", "kind": "number", "name": "parity_bbox_atol", "required": false }, { "flag": "--parity-iou", "kind": "number", "name": "parity_iou", "required": false }, { "flag": "--parity-report-template", "kind": "string", "name": "parity_report_template", "required": false }, { "flag": "--parity-score-atol", "kind": "number", "name": "parity_score_atol", "required": false }, { "flag": "--precision", "kind": "string", "name": "precision", "required": false }, { "flag": "--pred-onnxrt-template", "kind": "string", "name": "pred_onnxrt_template", "required": false }, { "flag": "--pred-trt-template", "kind": "string", "name": "pred_trt_template", "required": false }, { "flag": "--run-id", "kind": "string", "name": "run_id", "required": false }, { "flag": "--shape", "kind": "string", "name": "shape", "required": false }, { "flag": "--skip-benchmark", "kind": "string", "name": "skip_benchmark", "required": false }, { "flag": "--skip-build", "kind": "string", "name": "skip_build", "required": false }, { "flag": "--skip-eval", "kind": "string", "name": "skip_eval", "required": false }, { "flag": "--skip-latency", "kind": "string", "name": "skip_latency", "required": false }, { "flag": "--skip-onnxrt", "kind": "string", "name": "skip_onnxrt", "required": false }, { "flag": "--skip-parity", "kind": "string", "name": "skip_parity", "required": false }, { "flag": "--skip-trt", "kind": "string", "name": "skip_trt", "required": false }, { "flag": "--timing-cache", "kind": "file", "name": "timing_cache", "required": false }, { "flag": "--topk", "kind": "number", "name": "topk", "required": false }, { "flag": "--trtexec", "kind": "string", "name": "trtexec", "required": false }, { "flag": "--workspace-mib", "kind": "number", "name": "workspace_mib", "required": false } ], "maturity": "experimental", "outputs": [ { "default": null, "description": "Run folder containing run.json and copied artifacts.", "kind": "dir", "name": "run_dir" } ], "platform": { "cpu_ok": true, "gpu_required": true, "linux_ok": true, "macos_ok": false, "notes": "Designed for Linux+NVIDIA (Runpod). Use --dry-run to generate schema-correct artifacts without GPU." }, "runner": "python3", "summary": "Orchestrate the YOLO26 TensorRT pipeline (engine build → predictions export → parity → eval_suite → latency report).", "tags": [ "deploy", "pipeline", "tensorrt", "yolo26" ] }, { "contracts": { "produces": [ "predictions_json", "research_lane_report_json" ] }, "docs": [ "docs/ttt_protocol.md", "docs/ttt_compare_boilerplates.md", "manual/chapters/15_ttt_tent_mim.tex", "docs/production_readiness.md", "docs/research_lanes.md", "docs/schemas/research_lane_report.schema.json" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes plan, baseline/adapted predictions, optional eval outputs, and before-after compare artifacts under one directory.", "flag": "--run-dir", "kind": "dir", "scope": "tree" }, { "description": "Concise alias for --run-dir; writes the same complete diagnostic artifact tree.", "flag": "--out", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/run_ttt_compare.py", "examples": [ { "command": "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", "description": "Run a concise Tent local diagnostic after supplying a checkpoint with full compatibility for the selected config." }, { "command": "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", "description": "Run a concise MIM local diagnostic with a fully compatible checkpoint and structured MIM hook." }, { "command": "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", "description": "Validate dataset, config, and full checkpoint compatibility, then write a CoTTA execution plan without exporting predictions." }, { "command": "python3 tools/run_ttt_compare.py --method detector_response --data data/smoke --weights checkpoints/yolo26n.pt --out reports/ttt_compare/detector_response --image-size 320 --score-threshold 0.1", "description": "Run the concise no-object-aware selected-foreground class/box consistency comparison." } ], "id": "run_ttt_compare", "inputs": [ { "flag": "--boilerplate", "kind": "string", "name": "boilerplate", "required": false }, { "description": "Concise method selector that derives the matching boilerplate.", "flag": "--method", "kind": "string", "name": "method", "required": false }, { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "description": "Concise alias for --dataset.", "flag": "--data", "kind": "dir", "name": "data_alias", "required": false }, { "default": "val", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "description": "Checkpoint path; required unless --weights is used.", "flag": "--checkpoint", "kind": "file", "name": "checkpoint", "required": false }, { "description": "Concise alias for --checkpoint.", "flag": "--weights", "kind": "file", "name": "weights_alias", "required": false }, { "default": "reports/ttt_compare/", "flag": "--run-dir", "kind": "dir", "name": "run_dir", "required": false }, { "description": "Concise alias for --run-dir.", "flag": "--out", "kind": "dir", "name": "out_alias", "required": false }, { "default": "torch", "flag": "--backend", "kind": "string", "name": "backend", "required": false }, { "default": "cpu", "flag": "--device", "kind": "string", "name": "device", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--protocol", "kind": "string", "name": "protocol", "required": false }, { "flag": "--image-size", "kind": "string", "name": "image_size", "required": false }, { "default": 0, "description": "Deterministic TTT seed recorded in the execution plan and passed to the adapter.", "flag": "--seed", "kind": "number", "name": "seed", "required": false }, { "default": 0.001, "description": "Shared prediction score threshold for baseline and adapted exports.", "flag": "--score-threshold", "kind": "number", "name": "score_threshold", "required": false }, { "default": 300, "description": "Shared maximum detections per image for baseline and adapted exports.", "flag": "--max-detections", "kind": "number", "name": "max_detections", "required": false }, { "default": "metadata", "description": "Use path+size metadata hashing by default, or content for strict byte-level image provenance.", "flag": "--dataset-hash-mode", "kind": "string", "name": "dataset_hash_mode", "required": false }, { "flag": "--skip-eval", "kind": "string", "name": "skip_eval", "required": false }, { "description": "Concise alias for --skip-eval.", "flag": "--no-eval", "kind": "string", "name": "no_eval_alias", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "flag": "--force", "kind": "string", "name": "force", "required": false } ], "maturity": "research", "outputs": [ { "default": "reports/ttt_compare/", "description": "Run directory artifact.", "kind": "dir", "name": "run_dir" }, { "default": "reports/ttt_compare//plan.json", "description": "Plan JSON artifact.", "kind": "file", "name": "plan_json" }, { "default": "reports/ttt_compare//baseline_predictions.json", "description": "Baseline predictions artifact.", "kind": "file", "name": "baseline_predictions" }, { "default": "reports/ttt_compare//_predictions.json", "description": "Adapted predictions artifact.", "kind": "file", "name": "adapted_predictions" }, { "default": "reports/ttt_compare//_ttt_log.json", "description": "TTT log with adaptation, rollback, memory, update-ratio, and forward/backward counters.", "kind": "file", "name": "ttt_log" }, { "default": "reports/ttt_compare//_before_after_compare.json", "description": "Compare JSON with real COCO metrics, calibration/collapse diagnostics, provenance, cost counters, and promotion boundary.", "kind": "file", "name": "compare_json" }, { "default": "reports/ttt_compare//_before_after_compare.md", "description": "Compare Markdown artifact.", "kind": "file", "name": "compare_md" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false }, "runner": "python3", "summary": "Run a fail-closed seeded TTT comparison with full checkpoint preflight, real COCO evaluation, adaptation-cost counters, and a concise detector-response boilerplate for selected foreground class/box consistency.", "tags": [ "ttt", "ctta", "compare", "boilerplate", "report" ] }, { "contracts": { "produces": [ "coco_eval_report_json" ] }, "docs": [ "docs/ttt_protocol.md", "manual/chapters/15_ttt_tent_mim.tex", "reports/ttt_evidence_2026-07-27.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes plans, per-domain/per-method/per-seed comparisons, and aggregate JSON/Markdown under one output directory without recursively deleting it.", "flag": "--out", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/run_ttt_evidence_suite.py", "examples": [ { "command": "python3 tools/run_ttt_evidence_suite.py -d data/coco128 -x /path/to/shifted -c /path/to/base.pt --mim-checkpoint /path/to/mim.pt -o reports/ttt_evidence -n 8 --seeds 11,22,33", "description": "Run the full clean/shifted five-method evidence matrix with concise aliases and three seeds." }, { "command": "python3 tools/run_ttt_evidence_suite.py -d data/coco128 -x /path/to/shifted -c /path/to/base.pt --mim-checkpoint /path/to/mim.pt -o reports/ttt_evidence --dry-run", "description": "Validate inputs and write all child execution plans without running inference." } ], "id": "run_ttt_evidence_suite", "inputs": [ { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--shifted-dataset", "kind": "dir", "name": "shifted_dataset", "required": true }, { "default": "train2017", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--checkpoint", "kind": "file", "name": "checkpoint", "required": true }, { "flag": "--mim-checkpoint", "kind": "file", "name": "mim_checkpoint", "required": true }, { "flag": "--out", "kind": "dir", "name": "out", "required": true }, { "default": "tent,mim,cotta,eata,sar", "flag": "--methods", "kind": "string", "name": "methods", "required": false }, { "default": "11,22,33", "flag": "--seeds", "kind": "string", "name": "seeds", "required": false }, { "default": 8, "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "default": 128, "flag": "--image-size", "kind": "number", "name": "image_size", "required": false }, { "default": "cpu", "flag": "--device", "kind": "string", "name": "device", "required": false }, { "default": 0.001, "flag": "--score-threshold", "kind": "number", "name": "score_threshold", "required": false }, { "default": 300, "flag": "--max-detections", "kind": "number", "name": "max_detections", "required": false }, { "flag": "--protocol", "kind": "string", "name": "protocol", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "description": "Overwrite known child artifacts without recursively deleting the output directory.", "flag": "--force", "kind": "string", "name": "force", "required": false } ], "maturity": "research", "outputs": [ { "default": "/plan.json", "description": "Complete matrix plan and per-child execution status.", "kind": "file", "name": "plan_json" }, { "default": "/summary.json", "description": "Generated multi-seed clean/shifted aggregate with protocol separation and explicit independent-reproduction status.", "kind": "file", "name": "summary_json" }, { "default": "/summary.md", "description": "Human-readable evidence summary with the efficacy boundary.", "kind": "file", "name": "summary_markdown" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false }, "runner": "python3", "summary": "Run and aggregate a fail-closed five-method clean/shifted TTT matrix for at least three seeds.", "tags": [ "ttt", "ctta", "benchmark", "evidence", "reproducibility" ] }, { "contracts": { "consumes": [ "algorithm_scout_sources_json" ], "produces": [ "algorithm_scout_report_json", "managed_output_checksums_json" ] }, "docs": [ "README.md", "Readme_jp.md", "docs/README.md", "docs/adaptive_image_routing.md", "docs/algorithm_intake/README.md", "docs/schemas/algorithm_scout_report.schema.json", "docs/schemas/algorithm_scout_sources.schema.json", "manual/chapters/04_cli_reference.tex", "reports/adaptive_algorithm_scout_foundation_2026-08-26.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "With --collect only, atomically publish one dated bounded candidate inbox and checksums manifest inside the workspace.", "flag": "--output-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/scout_algorithms.py", "examples": [ { "command": "python3 tools/scout_algorithms.py --sources docs/algorithm_intake/sources.json --output-dir reports/algorithm_scout --collection-date 2026-08-26 --trigger workflow_dispatch", "description": "Validate the canonical allowlist and print a network-free, write-free JSON plan." }, { "command": "python3 tools/scout_algorithms.py --sources docs/algorithm_intake/sources.json --output-dir reports/algorithm_scout --collection-date 2026-08-26 --trigger workflow_dispatch --collect", "description": "Collect only bounded metadata from the explicit official-source allowlist and publish one dated inbox report." }, { "command": "python3 tools/scout_algorithms.py --help", "description": "Inspect the Experimental monitored-source interface contract." } ], "id": "scout_algorithms", "inputs": [ { "flag": "--sources", "kind": "file", "name": "sources", "required": true }, { "flag": "--output-dir", "kind": "dir", "name": "output_dir", "required": true }, { "flag": "--collection-date", "kind": "string", "name": "collection_date", "required": true }, { "flag": "--trigger", "kind": "string", "name": "trigger", "required": true }, { "flag": "--missed-collection-date", "kind": "string", "name": "missed_collection_date", "required": false }, { "default": ".", "flag": "--workspace", "kind": "dir", "name": "workspace", "required": false }, { "flag": "--collect", "kind": "string", "name": "collect", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "//algorithm_scout_report.json", "description": "Dated candidate inbox with explicit failed/unknown fields and no retained raw source document.", "kind": "file", "name": "algorithm_scout_report" }, { "default": "//checksums.json", "description": "Code-owned checksum manifest for the dated report.", "kind": "file", "name": "checksums" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": true }, "runner": "python3", "summary": "Plan by default or collect a bounded read-only Experimental inbox from exact official HTTPS sources; discovered data cannot execute, download weights, mutate the bundle registry, qualify, or promote anything.", "tags": [ "adaptive-inference", "algorithm-scout", "candidate", "experimental", "provenance" ] }, { "contracts": { "consumes": [ "predictions_json" ], "produces": [ "coco_eval_report_json" ] }, "docs": [ "docs/README.md", "docs/synthgen_intake.md", "data/smoke/README.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes COCO dry-run smoke report JSON.", "flag": "--report", "kind": "file", "scope": "path" }, { "description": "Writes SynthGen smoke artifacts under output dir.", "flag": "--output-dir", "kind": "dir", "scope": "tree" }, { "description": "Writes deep-profile walkthrough evidence report JSON.", "flag": "--walkthrough-report", "kind": "file", "scope": "path" } ] }, "entrypoint": "scripts/smoke.sh", "examples": [ { "command": "bash scripts/smoke.sh", "description": "Run full copy-paste smoke flow." }, { "command": "bash scripts/smoke.sh --help", "description": "Show smoke CLI options." }, { "command": "bash scripts/smoke.sh --profile deep", "description": "Run deep walkthrough smoke profile and emit capability evidence report." }, { "command": "bash scripts/smoke.sh --profile deep --torch-device cuda", "description": "Run deep walkthrough smoke on a CUDA machine (TTT probe uses GPU)." } ], "id": "smoke", "inputs": [ { "default": "data/smoke", "flag": "--dataset", "kind": "dir", "name": "dataset", "required": false }, { "default": "data/smoke/predictions/predictions_dummy.json", "flag": "--predictions", "kind": "file", "name": "predictions", "required": false }, { "default": "reports/smoke_coco_eval_dry_run.json", "flag": "--report", "kind": "file", "name": "report", "required": false }, { "default": "data/smoke/synthgen_minishard", "flag": "--synthgen-root", "kind": "dir", "name": "synthgen_root", "required": false }, { "default": "data/smoke/synthgen_minishard/predictions_synthgen_smoke.json", "flag": "--synthgen-predictions", "kind": "file", "name": "synthgen_predictions", "required": false }, { "default": "reports", "flag": "--output-dir", "kind": "dir", "name": "output_dir", "required": false }, { "default": "reports/smoke_demo_instance_seg", "flag": "--demo-run-dir", "kind": "dir", "name": "demo_run_dir", "required": false }, { "flag": "--skip-demo", "kind": "string", "name": "skip_demo", "required": false }, { "default": "cpu", "flag": "--torch-device", "kind": "string", "name": "torch_device", "required": false }, { "default": "core", "flag": "--profile", "kind": "string", "name": "profile", "required": false }, { "default": "reports/smoke_walkthrough_report.json", "flag": "--walkthrough-report", "kind": "file", "name": "walkthrough_report", "required": false } ], "maturity": "stable", "outputs": [ { "default": "reports/smoke_coco_eval_dry_run.json", "description": "COCO dry-run smoke report.", "kind": "file", "name": "smoke_report" }, { "default": "reports/smoke_synthgen_summary.json", "description": "SynthGen smoke summary artifact.", "kind": "file", "name": "synthgen_summary" }, { "default": "reports/smoke_synthgen_eval.json", "description": "SynthGen smoke evaluation report.", "kind": "file", "name": "synthgen_eval_report" }, { "default": "reports/smoke_synthgen_overlay.png", "description": "SynthGen smoke overlay image.", "kind": "file", "name": "synthgen_overlay" }, { "default": "reports/smoke_walkthrough_report.json", "description": "Deep-profile walkthrough evidence report covering capability claims and deploy-path dry-runs.", "kind": "file", "name": "smoke_walkthrough_report" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false }, "runner": "bash", "summary": "Run one-command offline smoke flow (doctor -> validate dataset -> validate predictions -> eval-coco dry-run -> synthgen intake smoke) with optional deep walkthrough checks.", "tags": [ "smoke", "validation", "eval" ] }, { "contracts": { "consumes": [ "synthgen_sample_contract" ] }, "docs": [ "docs/synthgen_intake.md", "docs/synthgen_repo_integration.md", "docs/synthgen_contract.md", "reports/synthgen_handoff_2026-07-28.md", "data/smoke/synthgen_minishard/README.md", "docs/production_readiness.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes SynthGen smoke artifacts under output dir.", "flag": "--output-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/smoke_synthgen.py", "examples": [ { "command": "python3 tools/smoke_synthgen.py --dataset-root data/smoke/synthgen_minishard --output-dir reports", "description": "Run SynthGen smoke on bundled fixture." }, { "command": "./.venv/bin/python tools/smoke_synthgen.py --synthgen-repo ../YOLOZU-synthgen --output-dir /tmp/yolozu-synthgen-qualification", "description": "Generate and qualify a fresh Open3D-to-YOLOZU background-edit handoff." } ], "id": "smoke_synthgen", "inputs": [ { "default": "data/smoke/synthgen_minishard", "flag": "--dataset-root", "kind": "dir", "name": "dataset_root", "required": false }, { "default": "animal_v1", "flag": "--schema-id", "kind": "string", "name": "schema_id", "required": false }, { "default": "data/smoke/synthgen_minishard/predictions_synthgen_smoke.json", "flag": "--predictions", "kind": "file", "name": "predictions", "required": false }, { "default": 2, "flag": "--max-samples", "kind": "number", "name": "max_samples", "required": false }, { "default": "reports", "flag": "--output-dir", "kind": "dir", "name": "output_dir", "required": false }, { "flag": "--synthgen-repo", "kind": "dir", "name": "synthgen_repo", "required": false }, { "flag": "--synthgen-python", "kind": "file", "name": "synthgen_python", "required": false }, { "default": "open3d", "flag": "--backend", "kind": "string", "name": "backend", "required": false }, { "default": "bg_only_inpaint", "flag": "--mode", "kind": "string", "name": "mode", "required": false }, { "default": 20260727, "flag": "--global-seed", "kind": "number", "name": "global_seed", "required": false }, { "default": 3, "flag": "--num-train", "kind": "number", "name": "num_train", "required": false }, { "default": 2, "flag": "--num-val", "kind": "number", "name": "num_val", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/smoke_synthgen_summary.json", "description": "SynthGen smoke summary artifact.", "kind": "file", "name": "summary_json" }, { "default": "reports/smoke_synthgen_overlay.png", "description": "Rendered SynthGen overlay artifact.", "kind": "file", "name": "overlay_png" }, { "default": "reports/smoke_synthgen_eval.json", "description": "SynthGen smoke evaluation report.", "kind": "file", "name": "eval_report_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Run deterministic SynthGen intake smoke, or generate and qualify a fresh cross-repo handoff with strict QA and loader checks.", "tags": [ "synthgen", "smoke", "contract", "viz", "evaluation", "ai-safe" ] }, { "contracts": { "consumes": [ "image_job_spec_json" ], "produces": [ "selection_decision_json", "predictions_json" ] }, "docs": [ "docs/adaptive_image_routing.md", "docs/image_service_mcp.md", "docs/llm_integrations.md", "docs/openai_mcp_actions.md" ], "effects": { "fixed_writes": [ { "kind": "dir", "path": "runs/mcp_image_service", "scope": "tree" } ], "writes": [] }, "entrypoint": "yolozu/integrations/mcp_server.py", "examples": [ { "command": "Call the submit_image_job MCP tool with an asset_id, fixed_classes, and execute=false.", "description": "Queue a qualified selection request; the service abstains when no eligible pipeline exists." }, { "command": "Call the submit_image_job MCP tool with execute=true only after approving model execution.", "description": "Execute only a selected qualified pipeline with network denied and managed output." } ], "id": "submit_image_job", "inputs": [ { "description": "Opaque ID returned by put_image_asset.", "kind": "string", "name": "asset_id", "required": true }, { "description": "Bounded fixed-class request interpreted by the AI client before this call.", "kind": "json", "name": "fixed_classes", "required": true }, { "default": "object_detection", "description": "object_detection or instance_segmentation.", "kind": "string", "name": "task", "required": false }, { "default": false, "description": "False performs qualified selection/preflight only; true permits explicit model execution after selection.", "kind": "string", "name": "execute", "required": false }, { "default": 300, "description": "30..3600 seconds from queue admission, including selection and execution; expiry stops owned processes and reports timed_out.", "kind": "number", "name": "timeout_seconds", "required": false } ], "maturity": "experimental", "outputs": [ { "description": "Opaque asynchronous job identity and queued state.", "kind": "json", "name": "job_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false, "python_packages": [ "mcp", "Pillow" ] }, "runner": "python3", "summary": "Queue a deadline-bounded cancellable image process using only a qualified registered pipeline or abstention; execution is opt-in and terminal paths release retained assets.", "tags": [ "adaptive-inference", "ai-first", "image-service", "mcp", "qualification", "security" ] }, { "docs": [ "docs/bop_tless_protocol.md", "docs/schemas/bop19_tless_pose_qualification.schema.json", "docs/tools_index.md", "reports/bop19_tless_official_evidence_2026-07-30.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes a fresh official/task-native three-seed qualification summary.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/summarize_bop19_pose_evidence.py", "examples": [ { "command": "python3 tools/summarize_bop19_pose_evidence.py --bop-root /workspace/tless --targets /workspace/tless/test_targets_bop19.json --result reports/method-s11_tless-test.csv --result reports/method-s22_tless-test.csv --result reports/method-s33_tless-test.csv --official-eval-root reports/bop-eval --native-errors-root reports/bop-native --toolkit-commit cea62d651c7e395b2e1962b9749e4e89693c6ac4 --output reports/bop19_tless_pose_qualification.json", "description": "Combine official BOP19 scores and matched pose metrics for three seeds." }, { "command": "python3 tools/summarize_bop19_pose_evidence.py --help", "description": "Show official evaluator, native error, and independent reproduction inputs." } ], "id": "summarize_bop19_pose_evidence", "inputs": [ { "flag": "--bop-root", "kind": "dir", "name": "bop_root", "required": true }, { "flag": "--targets", "kind": "file", "name": "targets", "required": true }, { "flag": "--result", "kind": "file", "name": "result", "required": true }, { "flag": "--official-eval-root", "kind": "dir", "name": "official_eval_root", "required": true }, { "flag": "--native-errors-root", "kind": "dir", "name": "native_errors_root", "required": true }, { "flag": "--toolkit-commit", "kind": "string", "name": "toolkit_commit", "required": true }, { "flag": "--output", "kind": "file", "name": "output", "required": true }, { "default": "primary", "flag": "--role", "kind": "string", "name": "role", "required": false }, { "default": null, "flag": "--source-summary", "kind": "file", "name": "source_summary", "required": false } ], "maturity": "research", "outputs": [ { "default": null, "description": "Three-seed official BOP19 and matched rotation, translation, ADD, ADD-S, and pose-success summary.", "kind": "file", "name": "bop19_pose_qualification_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false }, "runner": "python3", "summary": "Combine official BOP19 VSD/MSSD/MSPD scores with matched rotation, translation, ADD, ADD-S, symmetry-aware pose success, and optional independent reproduction.", "tags": [ "bop", "tless", "pose6d", "evaluation", "reproducibility" ] }, { "contracts": { "produces": [ "bop_tless_qualification_json" ] }, "docs": [ "docs/bop_tless_protocol.md", "docs/schemas/bop_tless_qualification.schema.json", "reports/bop_tless_evidence_2026-07-30.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes a baseline/trained task-native BOP T-LESS qualification summary.", "flag": "--output", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/summarize_bop_tless_qualification.py", "examples": [ { "command": "python3 tools/summarize_bop_tless_qualification.py --run-base runs/bop_tless --dataset reports/bop_tless --download-manifest reports/bop/download_manifest.json --output reports/bop_tless_qualification.json", "description": "Aggregate three-seed strict-GT baseline/trained task-native metrics without promoting a diagnostic result." }, { "command": "python3 tools/summarize_bop_tless_qualification.py --help", "description": "Show primary/independent comparison and evidence input options." } ], "id": "summarize_bop_tless_qualification", "inputs": [ { "flag": "--run-base", "kind": "dir", "name": "run_base", "required": true }, { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--download-manifest", "kind": "file", "name": "download_manifest", "required": true }, { "flag": "--output", "kind": "file", "name": "output", "required": true }, { "default": "primary", "flag": "--role", "kind": "string", "name": "role", "required": false }, { "default": null, "flag": "--source-summary", "kind": "file", "name": "source_summary", "required": false } ], "maturity": "research", "outputs": [ { "default": null, "description": "Schema-defined BOP T-LESS strict-GT before/after qualification summary with hold decision and optional semantic reproduction comparison.", "kind": "file", "name": "qualification_summary_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false }, "runner": "python3", "summary": "Aggregate three-seed BOP T-LESS bbox and task-native baseline/trained evidence and compare an independent rerun semantically.", "tags": [ "bop", "tless", "pose6d", "qualification", "reproducibility" ] }, { "contracts": { "produces": [ "training_run_summary_json" ] }, "docs": [ "README.md", "docs/README.md", "docs/interop_yolox.md", "docs/license_policy.md", "docs/schemas/training_handoff.schema.json", "docs/schemas/training_run_summary.schema.json", "docs/tools_index.md", "docs/training_inference_export.md", "manual/chapters/04_cli_reference.tex", "manual/chapters/05_workflows_eval_export.tex", "manual/chapters/09_parity_bench_protocols.tex", "docs/training_backend_interface.md", "docs/training_capability_matrix.md", "docs/training_orchestration.md", "docs/run_contract.md", "docs/interop_detectron2_mmdet.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes machine-readable bridge report JSON.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Writes generated helper files and work directories for dataset resolution or projections.", "flag": "--work-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/support_external_training.py", "examples": [ { "command": "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", "description": "Dry-run Apache-2.0-friendly YOLOX-style training bridge and write a machine-readable report plus artifact_plan, next_commands, and the fixed external run bundle under work_dir/." }, { "command": "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", "description": "Dry-run the Detectron2 external training lane; the config can target bbox, instance segmentation, or keypoints." }, { "command": "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", "description": "Dry-run the MMDetection external training lane for bbox or instance-segmentation workflows." }, { "command": "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", "description": "Dry-run the MMPose external training lane for keypoints workflows." }, { "command": "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", "description": "Dry-run the MMSeg external training lane for semantic-segmentation workflows." }, { "command": "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", "description": "Dry-run the NVIDIA TAO external training lane and emit standardized resume/export/eval/parity handoff JSONs." }, { "command": "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", "description": "Dry-run the optional Ultralytics bridge while keeping the runtime/license boundary explicit." }, { "command": "python3 tools/support_external_training.py train-hf-detr -P smoke -n -o reports/support_external_training.train_hf_detr.json", "description": "Dry-run the optional HF DETR bridge and emit the shared training summary interface contract plus the wrapper-owned external run bundle." } ], "id": "support_external_training", "inputs": [ { "description": "One of: layers, dataset, train-yolox, train-detectron2, train-mmdetection, train-mmpose, train-mmseg, train-tao, train-ultralytics, train-hf-detr, export-onnx, predict-normalize.", "flag": "--subcommand", "kind": "string", "name": "subcommand", "required": true }, { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": false }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "description": "Global batch size for train-yolox.", "flag": "--batch", "kind": "number", "name": "batch", "required": false }, { "description": "YOLOX exp file for train-yolox.", "flag": "--exp", "kind": "file", "name": "exp", "required": false }, { "description": "Optional external launcher for train-yolox or train-hf-detr non-dry execution.", "flag": "--train-script", "kind": "file", "name": "train_script", "required": false }, { "flag": "--weights", "kind": "file", "name": "weights", "required": false }, { "flag": "--output", "kind": "file", "name": "output", "required": false }, { "description": "Wrapper-owned working directory. YOLOX also receives this path as its native checkpoint/output directory.", "flag": "--work-dir", "kind": "dir", "name": "work_dir", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "description": "Detectron2 config YAML for train-detectron2.", "flag": "--config", "kind": "file", "name": "config", "required": false }, { "description": "Reported task family for Detectron2 / MMDetection / MMPose / MMSeg / TAO external lanes. MMDetection auto inference treats explicit Mask R-CNN or mask_head markers as segmentation; a COCO instances filename alone remains bbox.", "flag": "--task-family", "kind": "string", "name": "task_family", "required": false }, { "description": "Optional checkpoint/model path forwarded into the standardized resume handoff for external training lanes.", "flag": "--resume-from", "kind": "file", "name": "resume_from", "required": false }, { "description": "Optional NVIDIA TAO task name when train-tao is used.", "flag": "--tao-task", "kind": "string", "name": "tao_task", "required": false }, { "description": "Repeatable backend-native config override pair forwarded to the external launcher.", "flag": "--train-opt", "kind": "string", "name": "train_opt", "required": false }, { "description": "Optional JSONL registry file that receives one append-only training registry entry per executed run.", "flag": "--registry-out", "kind": "file", "name": "registry_out", "required": false } ], "maturity": "experimental", "outputs": [ { "default": null, "description": "Machine-readable training summary describing the selected external training lane, launcher wall/CPU/peak-RSS resource use for non-dry runs, its fixed external run bundle, optional bridge runtime_license_boundary metadata, artifact_plan for expected outputs, and next_steps for resume/export/eval/parity.", "kind": "file", "name": "training_run_summary_json" }, { "default": null, "description": "Wrapper-owned training registry entry JSON written under work_dir/reports/training_registry_entry.json.", "kind": "file", "name": "training_registry_entry_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "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. YOLOX infers the class count from dataset metadata, requires an explicit YOLOZU_NUM_CLASSES override to be a positive integer, and confines native outputs to --work-dir. Missing external executables return machine-readable runtime failures instead of uncaught process-launch errors. 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.", "tags": [ "training", "interop", "yolox", "ultralytics", "license-boundary", "detectron2", "mmdetection", "mmpose", "mmseg", "tao", "keypoints", "segmentation" ] }, { "docs": [ "README.md", "Readme_jp.md", "Readme_zh.md", "docs/tools_index.md", "docs/yolo_detr_support.md", "manual/chapters/04_cli_reference.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes primary artifact/report depending on subcommand.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Writes subcommand report JSON.", "flag": "--report", "kind": "file", "scope": "path" }, { "description": "Writes intermediate conversion/export assets.", "flag": "--work-dir", "kind": "dir", "scope": "tree" }, { "description": "Optional TensorRT engine output path when export-onnx uses TRT handoff.", "flag": "--trt-engine", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/support_yolo_detr.py", "examples": [ { "command": "python3 tools/support_yolo_detr.py ls -j", "description": "Show fixed 3-layer support matrix for trainer/repo/export surfaces." }, { "command": "python3 tools/support_yolo_detr.py tu -P smoke -n -o reports/support_yolo_detr.train_yolo_runtime.json", "description": "YOLO-family runtime fine-tune wrapper with dataset conversion and training template report." }, { "command": "python3 tools/support_yolo_detr.py th -P smoke -n -o reports/support_yolo_detr.train_hf_detr.json", "description": "HF DETR/RT-DETR entry wrapper report (Transformers/Datasets bridge)." }, { "command": "python3 tools/support_yolo_detr.py eo -P smoke -o models/yolo11n.onnx -n -r reports/support_yolo_detr.export_onnx.json", "description": "ONNX export wrapper with optional TensorRT handoff." }, { "command": "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", "description": "Canonicalize predictions into YOLOZU predictions interface contract." } ], "id": "support_yolo_detr", "inputs": [ { "flag": "--preset", "kind": "string", "name": "preset", "required": false }, { "flag": "--from", "kind": "string", "name": "from_format", "required": false }, { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": false }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "description": "Global batch size for train-yolox.", "flag": "--batch", "kind": "number", "name": "batch", "required": false }, { "flag": "--instances-json", "kind": "file", "name": "instances_json", "required": false }, { "flag": "--images-dir", "kind": "dir", "name": "images_dir", "required": false }, { "flag": "--model", "kind": "string", "name": "model", "required": false }, { "flag": "--model-id", "kind": "string", "name": "model_id", "required": false }, { "flag": "--provider", "kind": "string", "name": "provider", "required": false }, { "flag": "--input", "kind": "file", "name": "input", "required": false }, { "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--report", "kind": "file", "name": "report", "required": false }, { "flag": "--train-script", "kind": "file", "name": "train_script", "required": false }, { "flag": "--trt-engine", "kind": "file", "name": "trt_engine", "required": false }, { "flag": "--work-dir", "kind": "dir", "name": "work_dir", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "reports/support_yolo_detr.*.json", "description": "Execution report for dataset/train/export/normalize support commands.", "kind": "file", "name": "support_report_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "external_yolo_runtime", "transformers", "datasets", "torch", "onnx" ] }, "runner": "python3", "summary": "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.", "tags": [ "yolo_runtime", "detr", "onnx", "training", "adapter", "normalization" ] }, { "docs": [ "docs/external_finetune_smoke.md", "reports/external_runtime_evidence_2026-07-30.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes Detectron2 checkpoints, native logs, and training_evidence.json under the explicit output directory.", "flag": "--output-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/train_detectron2_runtime_smoke.py", "examples": [ { "command": "YOLOZU_DATASET_ROOT=reports/coco_wrapper python3 tools/train_detectron2_runtime_smoke.py --config-file configs/examples/finetune_external/detectron2_finetune_smoke.yaml --output-dir reports/detectron2_runtime_smoke SOLVER.MAX_ITER 1", "description": "Run one bounded Detectron2 optimizer step on a YOLOZU COCO wrapper and record checkpoint/resource evidence." }, { "command": "python3 tools/train_detectron2_runtime_smoke.py --help", "description": "Show launcher-compatible config, output, resume, and override options without importing Detectron2." } ], "id": "train_detectron2_runtime_smoke", "inputs": [ { "flag": "--config-file", "kind": "file", "name": "config_file", "required": true }, { "default": null, "flag": "--output-dir", "kind": "dir", "name": "output_dir", "required": false }, { "flag": "--resume", "kind": "string", "name": "resume", "required": false }, { "flag": "--eval-only", "kind": "string", "name": "eval_only", "required": false }, { "default": 1, "flag": "--num-gpus", "kind": "number", "name": "num_gpus", "required": false }, { "default": 1, "flag": "--num-machines", "kind": "number", "name": "num_machines", "required": false }, { "default": 0, "flag": "--machine-rank", "kind": "number", "name": "machine_rank", "required": false }, { "default": "auto", "flag": "--dist-url", "kind": "string", "name": "dist_url", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "/model_final.pth", "description": "Bounded Detectron2 checkpoint.", "kind": "file", "name": "checkpoint" }, { "default": "/training_evidence.json", "description": "Config/dataset/checkpoint hashes, runtime version/license boundary, wall time, and peak RSS.", "kind": "file", "name": "training_evidence_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "detectron2", "torch" ] }, "runner": "python3", "summary": "Run bounded real Detectron2 training on a YOLOZU COCO wrapper and emit hash/resource evidence.", "tags": [ "training", "detectron2", "external-runtime", "evidence" ] }, { "docs": [ "docs/external_finetune_smoke.md", "reports/external_runtime_evidence_2026-07-30.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes a tiny DETR config, checkpoint, strict predictions JSON, and training_evidence.json.", "flag": "--output-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "tools/train_hf_detr_runtime_smoke.py", "examples": [ { "command": "python3 tools/train_hf_detr_runtime_smoke.py --dataset data/smoke --split val --epochs 1 --batch-size 2 --max-steps 1 --output-dir reports/hf_detr_runtime_smoke", "description": "Train a scratch tiny DETR for one optimizer step on real labeled images and emit predictions interface contract evidence." }, { "command": "python3 tools/train_hf_detr_runtime_smoke.py --help", "description": "Show bounded training, resume, and output options without importing Transformers." } ], "id": "train_hf_detr_runtime_smoke", "inputs": [ { "default": "local-tiny-detr", "flag": "--model-id", "kind": "string", "name": "model_id", "required": false }, { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "default": "train", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "default": 1, "flag": "--epochs", "kind": "number", "name": "epochs", "required": false }, { "default": 2, "flag": "--batch-size", "kind": "number", "name": "batch_size", "required": false }, { "default": 0.0001, "flag": "--learning-rate", "kind": "number", "name": "learning_rate", "required": false }, { "default": 1, "flag": "--max-steps", "kind": "number", "name": "max_steps", "required": false }, { "default": null, "flag": "--resume-from", "kind": "file", "name": "resume_from", "required": false }, { "default": null, "flag": "--output-dir", "kind": "dir", "name": "output_dir", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "/checkpoint.pt", "description": "Scratch tiny-DETR state-dict checkpoint.", "kind": "file", "name": "checkpoint" }, { "default": "/predictions.json", "description": "Strict YOLOZU predictions interface contract artifact from the trained model.", "kind": "file", "name": "predictions_json" }, { "default": "/training_evidence.json", "description": "Config/dataset/checkpoint/prediction hashes, runtime versions/license boundary, loss, wall time, and peak RSS.", "kind": "file", "name": "training_evidence_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "transformers", "torch", "scipy", "numpy", "pillow" ] }, "runner": "python3", "summary": "Run a bounded real scratch Transformers DETR optimizer step and emit deterministic checkpoint/predictions/resource evidence.", "tags": [ "training", "transformers", "detr", "external-runtime", "evidence" ] }, { "docs": [ "docs/ttt_protocol.md", "docs/ttt_compare_boilerplates.md", "manual/chapters/15_ttt_tent_mim.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Delegates to tools/run_ttt_compare.py and writes compare artifacts under one directory.", "flag": "--run-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "scripts/ttt_compare.sh", "examples": [ { "command": "bash scripts/ttt_compare.sh --method tent --data data/smoke --weights checkpoints/rtdetr_pose.pt --out reports/ttt_compare/tent -n 1 --no-eval", "description": "Run a concise Tent local diagnostic after supplying a fully compatible checkpoint." }, { "command": "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", "description": "Run a concise MIM local diagnostic with a fully compatible structured-MIM checkpoint." }, { "command": "bash scripts/ttt_compare.sh --method cotta --data data/smoke --weights checkpoints/rtdetr_pose.pt --out reports/ttt_compare/cotta -n 1 --dry-run", "description": "Validate prerequisites and write a CoTTA plan without exporting predictions." } ], "id": "ttt_compare", "inputs": [ { "flag": "--boilerplate", "kind": "string", "name": "boilerplate", "required": true }, { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "default": "val", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--checkpoint", "kind": "file", "name": "checkpoint", "required": true }, { "default": "reports/ttt_compare/", "flag": "--run-dir", "kind": "dir", "name": "run_dir", "required": false }, { "default": "torch", "flag": "--backend", "kind": "string", "name": "backend", "required": false }, { "default": "cpu", "flag": "--device", "kind": "string", "name": "device", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--protocol", "kind": "string", "name": "protocol", "required": false }, { "flag": "--image-size", "kind": "string", "name": "image_size", "required": false }, { "flag": "--skip-eval", "kind": "string", "name": "skip_eval", "required": false }, { "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "flag": "--force", "kind": "string", "name": "force", "required": false } ], "maturity": "research", "outputs": [ { "default": "reports/ttt_compare/", "description": "Run directory artifact.", "kind": "dir", "name": "run_dir" }, { "default": "reports/ttt_compare//plan.json", "description": "Plan JSON artifact.", "kind": "file", "name": "plan_json" }, { "default": "reports/ttt_compare//baseline_predictions.json", "description": "Baseline predictions artifact.", "kind": "file", "name": "baseline_predictions" }, { "default": "reports/ttt_compare//_predictions.json", "description": "Adapted predictions artifact.", "kind": "file", "name": "adapted_predictions" }, { "default": "reports/ttt_compare//_ttt_log.json", "description": "Ttt log artifact.", "kind": "file", "name": "ttt_log" }, { "default": "reports/ttt_compare//_before_after_compare.json", "description": "Compare JSON artifact.", "kind": "file", "name": "compare_json" }, { "default": "reports/ttt_compare//_before_after_compare.md", "description": "Compare Markdown artifact.", "kind": "file", "name": "compare_md" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false }, "runner": "bash", "summary": "Short shell entrypoint for the fail-closed TTT local diagnostic; requires a fully compatible checkpoint and never promotes efficacy.", "tags": [ "ttt", "ctta", "compare", "boilerplate", "shell" ] }, { "contracts": { "consumes": [ "predictions_json" ], "produces": [ "metrics_report_json" ] }, "docs": [ "docs/gate_weight_tuning.md" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes gate tuning report JSON.", "flag": "--output-report", "kind": "file", "scope": "path" }, { "description": "Optional tuned predictions JSON output.", "flag": "--output-predictions", "kind": "file", "scope": "path" } ] }, "entrypoint": "tools/tune_gate_weights.py", "examples": [ { "command": "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", "description": "Tune weights on a small coco128 slice." } ], "id": "tune_gate_weights", "inputs": [ { "flag": "--config", "kind": "file", "name": "config", "required": false }, { "flag": "--dataset", "kind": "dir", "name": "dataset", "required": true }, { "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--predictions", "kind": "file", "name": "predictions", "required": true }, { "default": "reports/gate_tuning_report.json", "flag": "--output-report", "kind": "file", "name": "output_report", "required": false }, { "default": null, "flag": "--output-predictions", "kind": "file", "name": "output_predictions", "required": false }, { "flag": "--metric", "kind": "string", "name": "metric", "required": false }, { "flag": "--det-score-key", "kind": "string", "name": "det_score_key", "required": false }, { "flag": "--template-score-key", "kind": "string", "name": "template_score_key", "required": false }, { "flag": "--sigma-z-key", "kind": "string", "name": "sigma_z_key", "required": false }, { "flag": "--sigma-rot-key", "kind": "string", "name": "sigma_rot_key", "required": false }, { "flag": "--preserve-det-score-key", "kind": "string", "name": "preserve_det_score_key", "required": false }, { "flag": "--grid-det", "kind": "string", "name": "grid_det", "required": false }, { "flag": "--grid-tmp", "kind": "string", "name": "grid_tmp", "required": false }, { "flag": "--grid-unc", "kind": "string", "name": "grid_unc", "required": false }, { "flag": "--grid-tau", "kind": "string", "name": "grid_tau", "required": false }, { "flag": "--template-gate", "kind": "string", "name": "template_gate", "required": false }, { "flag": "--no-template-gate", "kind": "string", "name": "no_template_gate", "required": false }, { "flag": "--tau", "kind": "number", "name": "tau", "required": false }, { "flag": "--min-score", "kind": "number", "name": "min_score", "required": false }, { "flag": "--topk-per-image", "kind": "number", "name": "topk_per_image", "required": false }, { "flag": "--wrap-output", "kind": "string", "name": "wrap_output", "required": false }, { "flag": "--no-wrap-output", "kind": "string", "name": "no_wrap_output", "required": false } ], "maturity": "research", "outputs": [ { "default": "reports/gate_tuning_report.json", "description": "JSON report artifact.", "kind": "file", "name": "report_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Offline grid-search for inference-time score-fusion weights (CPU-only, simple mAP proxy).", "tags": [ "predictions", "gates", "tuning" ] }, { "contracts": { "consumes": [ "algorithm_bundle_registry_json", "bundle_lifecycle_record_json", "support_profile_record_json", "candidate_screening_record_json", "qualification_report_json", "evidence_activation_record_json", "lifecycle_rollback_bindings_json" ], "produces": [ "bundle_lifecycle_record_json" ] }, "docs": [ "README.md", "Readme_jp.md", "docs/adaptive_image_routing.md", "docs/schemas/bundle_lifecycle_record.schema.json", "docs/schemas/lifecycle_rollback_bindings.schema.json" ], "effects": { "fixed_writes": [ { "description": "With --approve, atomically appends only one validated reviewed lifecycle event.", "kind": "file", "path": "yolozu/data/adaptive_routing/bundle_lifecycle.jsonl", "scope": "path" } ], "writes": [] }, "entrypoint": "tools/update_image_pipeline_lifecycle.py", "examples": [ { "command": "python3 tools/update_image_pipeline_lifecycle.py disable --family-id --bundle-spec-digest --artifact-set-digest --expected-lifecycle-head-digest --expected-bundle-state-event-digest --actor-role-id repo_maintainer --public-review-id gh- --review-status approved --reason 'Review exact global disable'", "description": "Dry-run every exact-identity, immutable-artifact, public-review, and stale-head gate; no record is written." }, { "command": "python3 tools/update_image_pipeline_lifecycle.py --help", "description": "Inspect the Experimental lifecycle maintenance and explicit rollback interface contract." } ], "id": "update_image_pipeline_lifecycle", "inputs": [ { "kind": "string", "name": "operation", "required": true }, { "flag": "--family-id", "kind": "string", "name": "family_id", "required": false }, { "flag": "--bundle-spec-digest", "kind": "string", "name": "bundle_spec_digest", "required": false }, { "flag": "--artifact-set-digest", "kind": "string", "name": "artifact_set_digest", "required": false }, { "flag": "--expected-lifecycle-head-digest", "kind": "string", "name": "expected_lifecycle_head_digest", "required": false }, { "flag": "--expected-bundle-state-event-digest", "kind": "string", "name": "expected_bundle_state_event_digest", "required": false }, { "flag": "--channel", "kind": "string", "name": "channel", "required": false }, { "flag": "--expected-current-pointer-digest", "kind": "string", "name": "expected_current_pointer_digest", "required": false }, { "flag": "--expected-prior-assignment-digest", "kind": "string", "name": "expected_prior_assignment_digest", "required": false }, { "flag": "--expected-support-profile-index-head", "kind": "string", "name": "expected_support_profile_index_head", "required": false }, { "flag": "--expected-prior-support-profile-index-head", "kind": "string", "name": "expected_prior_support_profile_index_head", "required": false }, { "flag": "--expected-prior-profile-set-record-digest", "kind": "string", "name": "expected_prior_profile_set_record_digest", "required": false }, { "flag": "--expected-prior-profile-set-digest", "kind": "string", "name": "expected_prior_profile_set_digest", "required": false }, { "flag": "--target-bundle-spec-digest", "kind": "string", "name": "target_bundle_spec_digest", "required": false }, { "flag": "--target-artifact-set-digest", "kind": "string", "name": "target_artifact_set_digest", "required": false }, { "flag": "--evidence-bindings", "kind": "file", "name": "evidence_bindings", "required": false }, { "flag": "--license-review", "kind": "string", "name": "license_review", "required": false }, { "flag": "--actor-role-id", "kind": "string", "name": "actor_role_id", "required": false }, { "flag": "--public-review-id", "kind": "string", "name": "public_review_id", "required": false }, { "flag": "--review-status", "kind": "string", "name": "review_status", "required": false }, { "flag": "--reason", "kind": "string", "name": "reason", "required": false }, { "default": ".", "flag": "--workspace", "kind": "dir", "name": "workspace", "required": false }, { "flag": "--approve", "kind": "string", "name": "approve", "required": false } ], "maturity": "experimental", "outputs": [ { "default": "stdout", "description": "Bounded machine-readable dry-run or apply outcome with exact observed identities and every failed gate.", "kind": "stdout", "name": "lifecycle_update_outcome" }, { "default": "yolozu/data/adaptive_routing/bundle_lifecycle.jsonl", "description": "Canonical append-only lifecycle stream after explicit approval and successful readback.", "kind": "file", "name": "bundle_lifecycle_stream" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Dry-run or atomically append one exact reviewed lifecycle maintenance or previously assigned same-family channel rollback event audit-bound to its historical assignment digest; metrics and dormant candidates never mutate lifecycle state.", "tags": [ "adaptive-inference", "experimental", "governance", "lifecycle", "rollback", "ssot" ] }, { "contracts": { "consumes": [ "instance_segmentation_predictions_json" ] }, "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "tools/validate_instance_segmentation_predictions.py", "examples": [ { "command": "python3 tools/validate_instance_segmentation_predictions.py reports/instance_seg_predictions.json", "description": "Validate an instance segmentation predictions artifact." } ], "id": "validate_instance_segmentation_predictions", "inputs": [ { "description": "Instance segmentation predictions JSON path.", "kind": "file", "name": "predictions", "required": true } ], "maturity": "stable", "outputs": [ { "description": "OK/WARN lines.", "kind": "stdout", "name": "stdout" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Validate YOLOZU instance segmentation predictions JSON (per-image instances; PNG masks).", "tags": [ "instance_segmentation", "predictions", "validation" ] }, { "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "tools/validate_map_targets.py", "examples": [ { "command": "python3 tools/validate_map_targets.py --targets baselines/yolo26_targets.json", "description": "Validate targets JSON." } ], "id": "validate_map_targets", "inputs": [ { "default": "baselines/yolo26_targets.json", "flag": "--targets", "kind": "file", "name": "targets", "required": false } ], "maturity": "stable", "outputs": [ { "description": "OK or error details.", "kind": "stdout", "name": "stdout" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Validate the mAP target table file (baselines/yolo26_targets.json).", "tags": [ "eval", "targets", "yolo26" ] }, { "contracts": { "consumes": [ "predictions_json" ], "produces": [ "predictions_validation_result_json" ] }, "docs": [ "docs/byop_quickstarts.md", "docs/ai_first.md", "docs/predictions_schema.md", "docs/production_readiness.md" ], "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "tools/validate_predictions.py", "examples": [ { "command": "python3 tools/validate_predictions.py reports/predictions.json --strict", "description": "Strict schema validation." }, { "command": "python3 tools/validate_predictions.py reports/predictions.json --strict --json", "description": "Emit a bounded machine-readable validation result." } ], "id": "validate_predictions", "inputs": [ { "description": "Predictions JSON path.", "kind": "file", "name": "predictions", "required": true }, { "flag": "--strict", "kind": "string", "name": "strict", "required": false }, { "flag": "--json", "kind": "string", "name": "json", "required": false } ], "maturity": "stable", "outputs": [ { "description": "OK/WARN lines.", "kind": "stdout", "name": "stdout" }, { "description": "With --json, a schema-versioned success/failure payload with bounded warnings.", "kind": "stdout", "name": "validation_result_json" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Validate YOLOZU predictions JSON (permissive by default; strict optional) with compatible human output or an explicit bounded JSON result.", "tags": [ "predictions", "validation" ] }, { "docs": [ "docs/run_contract.md" ], "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "tools/validate_run_meta.py", "examples": [ { "command": "python3 tools/validate_run_meta.py runs/ci_smoke/reports/run_meta.json", "description": "Validate contracted run metadata." } ], "id": "validate_run_meta", "inputs": [ { "description": "Path to runs//reports/run_meta.json.", "kind": "file", "name": "run_meta", "required": true }, { "flag": "--allow-missing-git-sha", "kind": "string", "name": "allow_missing_git_sha", "required": false } ], "maturity": "stable", "outputs": [ { "description": "OK line or validation error.", "kind": "stdout", "name": "stdout" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Validate the run_meta.json interface contract (git SHA, dependency lock, preprocess, hardware/runtime, command).", "tags": [ "run_meta", "validation", "repro" ] }, { "contracts": { "consumes": [ "segmentation_predictions_json" ] }, "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "tools/validate_segmentation_predictions.py", "examples": [ { "command": "python3 tools/validate_segmentation_predictions.py reports/seg_predictions.json", "description": "Validate a segmentation predictions artifact." } ], "id": "validate_segmentation_predictions", "inputs": [ { "description": "Segmentation predictions JSON path.", "kind": "file", "name": "predictions", "required": true } ], "maturity": "stable", "outputs": [ { "description": "OK/WARN lines.", "kind": "stdout", "name": "stdout" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Validate YOLOZU segmentation predictions JSON (id→mask path mapping; meta optional).", "tags": [ "segmentation", "predictions", "validation" ] }, { "contracts": { "consumes": [ "synthgen_sample_contract" ] }, "docs": [ "docs/synthgen_intake.md", "docs/synthgen_repo_integration.md", "docs/synthgen_contract.md", "docs/production_readiness.md" ], "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "tools/validate_synthgen_contract.py", "examples": [ { "command": "python3 tools/validate_synthgen_contract.py --input /path/to/synthgen_dataset/shards/train_000.jsonl --max-samples 200", "description": "Validate first 200 records from a SynthGen shard file." } ], "id": "validate_synthgen_contract", "inputs": [ { "flag": "--input", "kind": "file", "name": "input", "required": true }, { "default": 100, "flag": "--max-samples", "kind": "number", "name": "max_samples", "required": false } ], "maturity": "experimental", "outputs": [ { "description": "Validation status and error summary.", "kind": "stdout", "name": "status" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "Validate SynthGen sample/shard interface-contract fields, dtypes, shapes, and ranges before training/eval.", "tags": [ "synthgen", "dataset", "contract", "validation", "keypoints", "segmentation", "depth" ] }, { "docs": [ "docs/manifest_authoring_workflow.md", "docs/manifest_coverage_audit.md", "docs/README.md" ], "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "tools/validate_tool_manifest.py", "examples": [ { "command": "python3 tools/validate_tool_manifest.py --manifest tools/manifest.json --require-declarative", "description": "Validate the canonical manifest in strict declarative mode." }, { "command": "python3 tools/validate_tool_manifest.py --help", "description": "Show manifest validator options." } ], "id": "validate_tool_manifest", "inputs": [ { "default": "tools/manifest.json", "flag": "--manifest", "kind": "file", "name": "manifest", "required": false }, { "flag": "--require-declarative", "kind": "string", "name": "require_declarative", "required": false } ], "maturity": "stable", "outputs": [ { "description": "Validation status or actionable manifest errors.", "kind": "stdout", "name": "stdout" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "network": false }, "runner": "python3", "summary": "Validate tools/manifest.json structure, references, and declarative metadata.", "tags": [ "manifest", "validation", "ci" ] }, { "docs": [ "docs/yolo26_eval_protocol.md", "docs/training_inference_export.md" ], "effects": { "fixed_writes": [ { "description": "Smoke report from scripts/smoke.sh as first pre-PR quality checkpoint.", "kind": "file", "path": "reports/smoke_coco_eval_dry_run.json", "scope": "path" } ], "writes": [] }, "entrypoint": "scripts/pre_pr_quality.sh", "examples": [ { "command": "bash scripts/pre_pr_quality.sh", "description": "Run the single-command pre-PR quality checklist." } ], "id": "yolo26_pre_pr_quality", "inputs": [], "maturity": "stable", "outputs": [ { "description": "Checklist run output.", "kind": "stdout", "name": "stdout" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "bash", "summary": "Run pre-PR quality checklist for YOLO26 flow (smoke + lint + focused tests).", "tags": [ "quality", "checklist", "yolo26" ] }, { "docs": [ "docs/yolo26_eval_protocol.md" ], "effects": { "fixed_writes": [], "writes": [] }, "entrypoint": "tools/yolo26_quality_gate.sh", "examples": [ { "command": "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", "description": "Run lint + focused eval/predictions tests for YOLO26 tooling." } ], "id": "yolo26_quality_gate", "inputs": [], "maturity": "stable", "outputs": [ { "description": "Lint/test pass-fail output.", "kind": "stdout", "name": "stdout" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "requires": { "python_packages": [ "ruff", "pytest" ] }, "runner": "bash", "summary": "Run YOLO26-focused quality gate (lint + focused tests) before eval/target checks.", "tags": [ "quality", "gates", "yolo26" ] }, { "contracts": { "produces": [ "predictions_json" ] }, "docs": [ "docs/tools_index.md", "docs/import_adapters.md", "docs/doctor_diagnostics.md", "docs/labeled_sample.md", "docs/versions.md", "docs/interop_yolox.md", "docs/byop_quickstarts.md", "docs/training_inference_export.md", "manual/chapters/04_cli_reference.tex", "manual/chapters/05_workflows_eval_export.tex", "docs/training_backend_interface.md", "docs/training_capability_matrix.md", "docs/training_orchestration.md", "docs/run_contract.md", "manual/chapters/07_training_run_contract.tex", "docs/interop_detectron2_mmdet.md", "docs/migrate.md", "docs/benchmark_mode.md", "docs/benchmark_support_matrix.md", "docs/benchmark_mode_spec_parity_target.md", "docs/benchmark_mode_gap_audit.md", "docs/benchmark_backend_runtime_matrix.md", "manual/chapters/09_parity_bench_protocols.tex" ], "effects": { "fixed_writes": [], "writes": [ { "description": "Writes JSON output (predictions / reports depending on subcommand). Torch compile export validates requested/actual execution evidence; a forced replacement removes the prior target before inference.", "flag": "--output", "kind": "file", "scope": "path" }, { "description": "Writes doctor proof artifacts when `doctor --proof` is used.", "flag": "--proof-dir", "kind": "dir", "scope": "tree" }, { "description": "Writes fingerprinted cache artifacts under --cache-dir.", "flag": "--cache-dir", "kind": "dir", "scope": "tree" }, { "description": "Optional TTA log JSON output.", "flag": "--tta-log-out", "kind": "file", "scope": "path" }, { "description": "Optional TTT log JSON output.", "flag": "--ttt-log-out", "kind": "file", "scope": "path" }, { "description": "Run directory for continual runners and demos. demo dataset defaults to reports/labeled_sample and refuses any existing path.", "flag": "--run-dir", "kind": "dir", "scope": "tree" }, { "description": "Optional overlay image directory.", "flag": "--overlays-dir", "kind": "dir", "scope": "tree" }, { "description": "Optional HTML report output.", "flag": "--html", "kind": "file", "scope": "path" }, { "description": "Writes exported dataset layouts under --out-dir (for example YOLO data.yaml/images/labels, COCO images/annotations, KITTI image_2/label_2, or semantic-segmentation images/masks + dataset.json).", "flag": "--out-dir", "kind": "dir", "scope": "tree" } ] }, "entrypoint": "yolozu/cli.py", "examples": [ { "command": "python3 -m yolozu doctor --output reports/doctor.json", "description": "Doctor report." }, { "command": "python3 -m yolozu doctor --explain", "description": "Print a beginner-friendly environment summary with next actions and save reports/doctor.json." }, { "command": "python3 -m yolozu doctor --proof", "description": "Run a CPU-only toy dataset, known predictions, validation, eval report, and expected-metric comparison proof." }, { "command": "python3 -m yolozu guide --goal evaluate", "description": "Print a self-contained evaluation route using doctor-generated toy artifacts, with explicit dry-run and real-COCO guidance. Printing the guide does not execute the commands." }, { "command": "python3 -m yolozu guide --goal first-run", "description": "Print the beginner-safe route that writes a report plus visible PNG overlays." }, { "command": "python3 -m yolozu completion -s bash", "description": "Print bash completion script for yolozu CLI (eval output to enable tab completion)." }, { "command": "python3 -m yolozu demo overview --output reports/demo_overview_report.json", "description": "Demo overview report (capability coverage + dependency checks + visible quickstart command)." }, { "command": "python3 -m yolozu demo dataset --run-dir reports/labeled_sample --seed 0", "description": "Create eight portable synthetic images with YOLO labels, class mapping, known predictions, a labeled preview, and a versioned sample manifest; refuses existing output paths." }, { "command": "python3 -m yolozu demo instance-seg --run-dir reports/quickstart_instance_seg --progress", "description": "Beginner-visible instance-seg demo; writes images, masks, PNG overlays, a JSON report, and stderr progress." }, { "command": "python3 -m yolozu demo ttt --run-dir reports/demo_ttt_improvement --force", "description": "Local TTT diagnostic with non-COCO proxy AP; efficacy remains not established (requires torch)." }, { "command": "python3 -m yolozu demo instance-seg-tta --run-dir reports/demo_instance_seg_tta", "description": "Instance-seg TTA compare demo (real COCO image, deterministic corruption, raw Mask R-CNN vs augmentation-based TTA overlays; brightness shift uses brightness-lift+hflip, other shifts use hflip; requires torch+torchvision)." }, { "command": "python3 -m yolozu demo keypoints", "description": "Keypoints inference demo (passthrough to package CLI)." }, { "command": "python3 -m yolozu demo pose", "description": "6D pose demo (chessboard + OpenCV solvePnP)." }, { "command": "python3 -m yolozu demo pose --backend aruco", "description": "6D pose demo (ArUco marker pose; cached sample under demo_output/pose/_samples)." }, { "command": "python3 -m yolozu demo pose --backend densefusion", "description": "6D pose demo (DenseFusion backend; CUDA + large downloads)." }, { "command": "python3 -m yolozu demo depth", "description": "Monocular depth demo (default: Depth Anything via Transformers; optional MiDaS/DPT)." }, { "command": "python3 -m yolozu demo depth --compare", "description": "Monocular depth compare (runs Depth Anything + MiDaS + DPT; writes suffixed images)." }, { "command": "python3 -m yolozu demo train --max-steps 40", "description": "Training demo (MNIST fine-tune; bounded by --max-steps; downloads ResNet18 on first run)." }, { "command": "python3 -m yolozu doctor import --config-from auto --args /path/to/args.yaml --output -", "description": "Doctor import auto-detect (config)." }, { "command": "python3 -m yolozu export --backend dummy --dataset data/coco128 --max-images 5 --output reports/predictions_dummy_run.json", "description": "Export dummy predictions with run meta." }, { "command": "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", "description": "Folder input to predictions JSON + PNG overlays + HTML (dummy backend), with stderr progress." }, { "command": "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", "description": "Evaluate instance-seg demo predictions (mask mAP) with HTML overlays." }, { "command": "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", "description": "Validate the canonical conditional OpenVINO benchmark and explicit parity-reference wiring without requiring the external runtime." }, { "command": "python3 tools/hpo_sweep.py --config docs/hpo_sweep_example.json --dry-run", "description": "Run a sweep config directly via the repo-local sweep helper (dry-run)." }, { "command": "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", "description": "Long-tail post-hoc calibration + standardized eval." }, { "command": "python3 -m yolozu train --import auto --cfg /path/to/args_or_config.{yaml,py} --resolved-config-out reports/train_config_resolved_import.json", "description": "Train import preview with auto framework detection." }, { "command": "python3 -m yolozu doctor train-dataset --dataset data/smoke --split val --output -", "description": "Strictly validate the selected dataset records and report machine-readable direct-train readiness plus next commands." }, { "command": "python3 -m yolozu doctor train-dataset --from coco-instances --instances /path/to/instances_train2017.json --images-dir /path/to/images/train2017 --split train2017 --output -", "description": "Strictly preflight separate COCO annotation and image paths without requiring a synthetic dataset root." }, { "command": "python3 -m yolozu doctor train-dataset --from obb --dataset /path/to/yolo_obb_root --split train --output -", "description": "Check a YOLO OBB training intake and report that it belongs to an external training lane rather than the RT-DETR reference trainer." }, { "command": "python3 -m yolozu doctor train-dataset --from pose6d --dataset /path/to/yolozu_pose_wrapper --split train --output -", "description": "Check that a pose6d training wrapper has bbox labels plus pose/intrinsics sidecars before reference training." }, { "command": "python3 -m yolozu registry validate", "description": "Validate the canonical tool manifest through the top-level CLI." }, { "command": "python3 -m yolozu eval-coco --help", "description": "Check the canonical package CLI evaluation help output." }, { "command": "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", "description": "Top-level train route for the Apache-2.0-friendly external YOLOX bridge (dry-run)." }, { "command": "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", "description": "Top-level train route for the Detectron2 external lane (bbox / instance segmentation / keypoints via backend-native configs)." }, { "command": "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", "description": "Top-level train route for the MMDetection external lane (bbox / instance segmentation via backend-native configs)." }, { "command": "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", "description": "Top-level train route for the MMPose external lane (keypoints / pose via backend-native configs)." }, { "command": "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", "description": "Top-level train route for the MMSeg external lane (semantic segmentation via backend-native configs)." }, { "command": "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", "description": "Top-level train route for the NVIDIA TAO external lane (bbox / segmentation / keypoints via backend-native configs)." }, { "command": "python3 tools/support_external_training.py ls -j", "description": "Inspect external training support helpers from the repo-local bridge." }, { "command": "python3 -m yolozu train --external-backend ultralytics yolo11n.pt --dataset data/smoke --split val --dry-run --output reports/train_external_ultralytics.json", "description": "Top-level train route for the optional Ultralytics bridge (dry-run)." }, { "command": "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", "description": "Top-level train route for the optional HF DETR bridge (dry-run)." }, { "command": "python3 -m yolozu train-orchestrate --spec reports/train_orchestration_spec.json --output reports/training_orchestration_report.json", "description": "Plan a multi-backend training batch through the top-level CLI." }, { "command": "python3 -m yolozu export-dataset yolo --dataset reports/conversion_tiny_wrapper --split val2017 --out-dir reports/conversion_tiny_yolo --force", "description": "Export a YOLOZU wrapper into a standalone YOLO-style data.yaml/images/labels layout." }, { "command": "python3 -m yolozu export-dataset kitti --dataset reports/conversion_tiny_wrapper --split val2017 --out-dir reports/conversion_tiny_kitti --force", "description": "Export a YOLOZU wrapper into a KITTI-style image_2/label_2/ImageSets layout." }, { "command": "python3 -m yolozu doctor import --dataset-from auto --dataset data/conversion_tiny_coco --split val2017 --output -", "description": "Auto-detect a native dataset root before wrapper conversion so the user does not need to choose the source layout manually." }, { "command": "python3 -m yolozu migrate dataset --from auto --dataset data/conversion_tiny_coco --split val2017 --output reports/conversion_tiny_wrapper --force", "description": "Create a YOLOZU wrapper from an auto-detected dataset root so the RT-DETR reference trainer can consume a normalized YOLOZU/YOLO-style layout." }, { "command": "python3 -m yolozu export-dataset coco --dataset reports/conversion_tiny_wrapper --split val2017 --out-dir reports/conversion_tiny_coco --force", "description": "Export a YOLOZU wrapper back into a standard COCO images/annotations layout." }, { "command": "python3 -m yolozu doctor import --dataset-from auto --dataset /path/to/VOCdevkit/VOC2012 --split val --output -", "description": "Auto-detect a semantic-segmentation dataset root and report its task family before conversion." }, { "command": "python3 -m yolozu import dataset --from auto --dataset /path/to/coco_keypoints_root --split val2017 --output reports/coco_keypoints_wrapper --force", "description": "Auto-detect a COCO keypoints root and create a YOLOZU keypoints wrapper with keypoint schema metadata." }, { "command": "python3 -m yolozu import dataset --from coco-keypoints --dataset /path/to/coco_keypoints_root --split val2017 --output reports/coco_keypoints_wrapper --force", "description": "Explicitly import a COCO keypoints root into a train-ready YOLOZU keypoints wrapper." }, { "command": "python3 -m yolozu export-dataset segmentation --dataset reports/voc_seg_wrapper --out-dir reports/voc_seg_export --image-mode symlink --force", "description": "Export a semantic-segmentation descriptor into an images/masks layout without copying large assets." }, { "command": "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", "description": "Decode ExecuTorch runtime output JSON through the canonical export surface." }, { "command": "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", "description": "Export Torch predictions only after the requested compile path records compiled execution or an explicitly allowed eager fallback." } ], "id": "yolozu", "inputs": [ { "description": "Explicitly permit eager fallback when requested torch.compile setup or first execution fails; export metadata records actual.status=fallback.", "flag": "--allow-compile-fallback", "kind": "string", "name": "allow_compile_fallback", "required": false }, { "flag": "--allow-gpu", "kind": "string", "name": "allow_gpu", "required": false }, { "flag": "--allow-network", "kind": "string", "name": "allow_network", "required": false }, { "flag": "--allow-rgb-masks", "kind": "string", "name": "allow_rgb_masks", "required": false }, { "flag": "--allow-undeclared-effects", "kind": "string", "name": "allow_undeclared_effects", "required": false }, { "flag": "--allow-unknown-flags", "kind": "string", "name": "allow_unknown_flags", "required": false }, { "flag": "--allow-unsafe-paths", "kind": "string", "name": "allow_unsafe_paths", "required": false }, { "flag": "--allow-write-root", "kind": "string", "name": "allow_write_root", "required": false }, { "flag": "--alpha", "kind": "number", "name": "alpha", "required": false }, { "flag": "--backend", "kind": "string", "name": "backend", "required": false }, { "description": "Forwarded batch size for external YOLOX/Ultralytics helper execution.", "flag": "--batch", "kind": "number", "name": "batch", "required": false }, { "flag": "--boxes-scale", "kind": "string", "name": "boxes_scale", "required": false }, { "flag": "--cache", "kind": "string", "name": "cache", "required": false }, { "default": "runs/yolozu_runs", "flag": "--cache-dir", "kind": "dir", "name": "cache_dir", "required": false }, { "flag": "--calibration-bins", "kind": "number", "name": "calibration_bins", "required": false }, { "flag": "--calibration-iou", "kind": "number", "name": "calibration_iou", "required": false }, { "flag": "--checkpoint", "kind": "file", "name": "checkpoint", "required": false }, { "flag": "--class-balanced-beta", "kind": "number", "name": "class_balanced_beta", "required": false }, { "flag": "--classes", "kind": "file", "name": "classes", "required": false }, { "flag": "--combined-output", "kind": "string", "name": "combined_output", "required": false }, { "flag": "--config", "kind": "file", "name": "config", "required": false }, { "flag": "--contract", "kind": "string", "name": "contract", "required": false }, { "description": "Dataset root or descriptor path used by validation, doctor/import auto-detect, export-dataset, and external training lanes. For the RT-DETR reference lane, pass the normalized YOLOZU/YOLO-style root produced by doctor/import/migrate; auto-detect spans YOLO/Ultralytics, COCO/COCO keypoints, YOLOZU wrappers, and supported semantic-segmentation roots/descriptors.", "flag": "--dataset", "kind": "dir", "name": "dataset", "required": false }, { "description": "Forwarded to the RT-DETR reference trainer; points at a train-ready YOLOZU/YOLO-style dataset root or dataset.json/data.yaml descriptor.", "flag": "--dataset-root", "kind": "dir", "name": "dataset_root", "required": false }, { "description": "Dataset import source selector for doctor/import flows; `auto` inspects the provided dataset path or explicit COCO args so users do not need to identify native bbox, keypoints, or semantic-segmentation layouts manually before wrapper normalization. `coco-keypoints` selects COCO person_keypoints-style roots explicitly.", "flag": "--dataset-from", "kind": "string", "name": "dataset_from", "required": false }, { "flag": "--device", "kind": "string", "name": "device", "required": false }, { "description": "Forwarded device count for the external YOLOX launcher.", "flag": "--devices", "kind": "number", "name": "devices", "required": false }, { "flag": "--diag-iou", "kind": "number", "name": "diag_iou", "required": false }, { "description": "Forwarded to the external training helper; resolve/report without launching runtime training.", "flag": "--dry-run", "kind": "string", "name": "dry_run", "required": false }, { "description": "Forwarded to the RT-DETR reference trainer; optional JSON records to append to the scanned training dataset.", "flag": "--extra-records-json", "kind": "file", "name": "extra_records_json", "required": false }, { "description": "Selects the external training lane (`yolox`, `detectron2`, `mmdetection`, `mmpose`, `mmseg`, `tao`, `ultralytics`, or `hf-detr`) for `yolozu train`.", "flag": "--external-backend", "kind": "string", "name": "external_backend", "required": false }, { "description": "Print a human-readable doctor summary with next commands while preserving the JSON report at --output.", "flag": "--explain", "kind": "string", "name": "explain", "required": false }, { "description": "Forwarded checkpoint path for external fine-tune/resume flows.", "flag": "--resume-from", "kind": "file", "name": "resume_from", "required": false }, { "description": "Forwarded NVIDIA TAO task name when `train --external-backend tao` is active.", "flag": "--tao-task", "kind": "string", "name": "tao_task", "required": false }, { "flag": "--fit-iou", "kind": "number", "name": "fit_iou", "required": false }, { "flag": "--fit-max-detections", "kind": "number", "name": "fit_max_detections", "required": false }, { "flag": "--fit-temperature", "kind": "number", "name": "fit_temperature", "required": false }, { "flag": "--focal-gamma", "kind": "number", "name": "focal_gamma", "required": false }, { "description": "Forwarded to the external training helper to overwrite generated artifacts.", "flag": "--force", "kind": "string", "name": "force", "required": false }, { "flag": "--force-import-overwrite", "kind": "string", "name": "force_import_overwrite", "required": false }, { "description": "Dataset source selector for `yolozu doctor train-dataset`, `yolozu import dataset`, and `yolozu migrate dataset`; train-dataset supports auto, ultralytics, coco, coco-keypoints, coco-instances, segmentation, classification, obb, depth, and pose6d. Explicit coco-instances preflight accepts --instances with --images-dir. Import/migrate support the subset implemented by their dataset adapters.", "flag": "--from", "kind": "string", "name": "from_format", "required": false }, { "flag": "--gamma", "kind": "number", "name": "gamma", "required": false }, { "flag": "--glob", "kind": "string", "name": "glob", "required": false }, { "description": "Selects the beginner guide route for `yolozu guide` (`all`, `first-run`, `evaluate`, `export`, or `debug`). Evaluation/export/debug examples generate their own toy inputs and need no checkout assets.", "flag": "--goal", "kind": "string", "name": "goal", "required": false }, { "flag": "--head-fraction", "kind": "number", "name": "head_fraction", "required": false }, { "flag": "--help", "kind": "string", "name": "help", "required": false }, { "default": "reports/predict_images.html", "flag": "--html", "kind": "file", "name": "html", "required": false }, { "flag": "--image-size", "kind": "number", "name": "image_size", "required": false }, { "description": "COCO image directory used with --instances for explicit doctor/import dataset resolution.", "flag": "--images-dir", "kind": "dir", "name": "images_dir", "required": false }, { "description": "Include COCO iscrowd annotations during explicit doctor/import dataset resolution.", "flag": "--include-crowd", "kind": "string", "name": "include_crowd", "required": false }, { "default": 1, "description": "Torch inference batch size for export.", "flag": "--infer-batch-size", "kind": "number", "name": "infer_batch_size", "required": false }, { "flag": "--input-dir", "kind": "dir", "name": "input_dir", "required": false }, { "flag": "--input-name", "kind": "string", "name": "input_name", "required": false }, { "description": "COCO instances/person_keypoints JSON used with --images-dir for explicit train-dataset preflight; --dataset is not required.", "flag": "--instances", "kind": "file", "name": "instances", "required": false }, { "description": "Forwarded COCO instances JSON for external dataset resolution.", "flag": "--instances-json", "kind": "file", "name": "instances_json", "required": false }, { "flag": "--iou-threshold", "kind": "number", "name": "iou_threshold", "required": false }, { "flag": "--json", "kind": "string", "name": "json", "required": false }, { "flag": "--keep-per-image", "kind": "string", "name": "keep_per_image", "required": false }, { "flag": "--kp-line", "kind": "number", "name": "kp_line", "required": false }, { "flag": "--kp-radius", "kind": "number", "name": "kp_radius", "required": false }, { "flag": "--ldam-margin", "kind": "number", "name": "ldam_margin", "required": false }, { "flag": "--logit-adjustment-tau", "kind": "number", "name": "logit_adjustment_tau", "required": false }, { "flag": "--lora-alpha", "kind": "number", "name": "lora_alpha", "required": false }, { "flag": "--lora-dropout", "kind": "number", "name": "lora_dropout", "required": false }, { "flag": "--lora-freeze-base", "kind": "string", "name": "lora_freeze_base", "required": false }, { "flag": "--lora-r", "kind": "number", "name": "lora_r", "required": false }, { "flag": "--lora-target", "kind": "string", "name": "lora_target", "required": false }, { "flag": "--lora-train-bias", "kind": "string", "name": "lora_train_bias", "required": false }, { "flag": "--lort-tau", "kind": "number", "name": "lort_tau", "required": false }, { "flag": "--loss-plugin", "kind": "string", "name": "loss_plugin", "required": false }, { "flag": "--lr-scheduler", "kind": "string", "name": "lr_scheduler", "required": false }, { "flag": "--max-detections", "kind": "number", "name": "max_detections", "required": false }, { "description": "Cap records inspected by applicable commands; doctor train-dataset reports scope=first_n when validation is capped.", "flag": "--max-images", "kind": "number", "name": "max_images", "required": false }, { "flag": "--max-overlays", "kind": "number", "name": "max_overlays", "required": false }, { "flag": "--max-runs", "kind": "number", "name": "max_runs", "required": false }, { "flag": "--max-score", "kind": "number", "name": "max_score", "required": false }, { "flag": "--medium-fraction", "kind": "number", "name": "medium_fraction", "required": false }, { "flag": "--method", "kind": "string", "name": "method", "required": false }, { "flag": "--metric", "kind": "string", "name": "metric", "required": false }, { "flag": "--metric-key", "kind": "string", "name": "metric_key", "required": false }, { "flag": "--metric-plugin", "kind": "string", "name": "metric_plugin", "required": false }, { "flag": "--min-score", "kind": "number", "name": "min_score", "required": false }, { "flag": "--model", "kind": "string", "name": "model", "required": false }, { "flag": "--no-lora-freeze-base", "kind": "string", "name": "no_lora_freeze_base", "required": false }, { "flag": "--no-torch-channels-last", "kind": "string", "name": "no_torch_channels_last", "required": false }, { "flag": "--no-torch-compile-fullgraph", "kind": "string", "name": "no_torch_compile_fullgraph", "required": false }, { "flag": "--no-torch-inference-mode", "kind": "string", "name": "no_torch_inference_mode", "required": false }, { "flag": "--no-ttt-rollback-on-stop", "kind": "string", "name": "no_ttt_rollback_on_stop", "required": false }, { "flag": "--no-ttt-sar-adaptive", "kind": "string", "name": "no_ttt_sar_adaptive", "required": false }, { "flag": "--no-ttt-stop-on-non-finite", "kind": "string", "name": "no_ttt_stop_on_non_finite", "required": false }, { "flag": "--notes", "kind": "string", "name": "notes", "required": false }, { "flag": "--oks", "kind": "string", "name": "oks", "required": false }, { "flag": "--oks-max-dets", "kind": "number", "name": "oks_max_dets", "required": false }, { "flag": "--oks-sigmas", "kind": "string", "name": "oks_sigmas", "required": false }, { "flag": "--oks-sigmas-file", "kind": "file", "name": "oks_sigmas_file", "required": false }, { "default": "reports/predictions.json", "description": "Forwarded report JSON path for the external training helper.", "flag": "--output", "kind": "file", "name": "output", "required": false }, { "flag": "--output-report", "kind": "file", "name": "output_report", "required": false }, { "flag": "--proof", "kind": "string", "name": "proof", "required": false }, { "default": "reports/doctor_proof", "description": "Directory for CPU-only doctor proof artifacts.", "flag": "--proof-dir", "kind": "dir", "name": "proof_dir", "required": false }, { "flag": "--overlay-alpha", "kind": "number", "name": "overlay_alpha", "required": false }, { "flag": "--overlay-max-size", "kind": "number", "name": "overlay_max_size", "required": false }, { "flag": "--overlay-sort", "kind": "string", "name": "overlay_sort", "required": false }, { "default": "reports/overlays", "flag": "--overlays-dir", "kind": "dir", "name": "overlays_dir", "required": false }, { "description": "OpenVINO-lane artifact override for the experimental benchmark subcommand. Detect expects a compatible IR and external runtime; artifact-backed tasks accept prepared task artifacts without checking or invoking the OpenVINO runtime.", "flag": "--openvino-model", "kind": "file", "name": "openvino_model", "required": false }, { "choices": [ "auto", "torch", "onnx", "engine", "torchscript", "openvino" ], "default": "auto", "description": "Reference backend for benchmark parity artifacts; OpenVINO detect requires a supplied IR and runtime, while artifact-backed OpenVINO tasks use prepared artifacts without a runtime check.", "flag": "--parity-reference-backend", "kind": "string", "name": "parity_reference_backend", "required": false }, { "default": 0.0001, "description": "Classification benchmark parity absolute tolerance for aligned class scores.", "flag": "--classification-parity-score-atol", "kind": "number", "name": "classification_parity_score_atol", "required": false }, { "default": 0.99, "description": "OBB benchmark parity rotated-IoU threshold for same-sample, same-class matching.", "flag": "--obb-parity-iou-thresh", "kind": "number", "name": "obb_parity_iou_thresh", "required": false }, { "default": 0.0001, "description": "OBB benchmark parity absolute tolerance for confidence scores on matched detections.", "flag": "--obb-parity-score-atol", "kind": "number", "name": "obb_parity_score_atol", "required": false }, { "flag": "--pck-threshold", "kind": "number", "name": "pck_threshold", "required": false }, { "flag": "--per-image-limit", "kind": "number", "name": "per_image_limit", "required": false }, { "flag": "--pred-root", "kind": "dir", "name": "pred_root", "required": false }, { "flag": "--predictions", "kind": "file", "name": "predictions", "required": false }, { "description": "Show stderr progress bars for user-facing loops; --no-progress disables them.", "flag": "--progress", "kind": "string", "name": "progress", "required": false }, { "description": "Forwarded Python executable for external launcher subprocesses.", "flag": "--python", "kind": "string", "name": "python", "required": false }, { "flag": "--rebalance-sampler", "kind": "string", "name": "rebalance_sampler", "required": false }, { "description": "Forwarded to the RT-DETR reference trainer; JSON list or object with an images list containing training records.", "flag": "--records-json", "kind": "file", "name": "records_json", "required": false }, { "flag": "--replay-fraction", "kind": "number", "name": "replay_fraction", "required": false }, { "flag": "--replay-per-task-cap", "kind": "number", "name": "replay_per_task_cap", "required": false }, { "flag": "--replay-size", "kind": "number", "name": "replay_size", "required": false }, { "flag": "--resolved-config-out", "kind": "file", "name": "resolved_config_out", "required": false }, { "flag": "--resume", "kind": "string", "name": "resume", "required": false }, { "default": null, "description": "Subcommand-specific run directory. demo dataset defaults to reports/labeled_sample and never overwrites an existing path.", "flag": "--run-dir", "kind": "dir", "name": "run_dir", "required": false }, { "description": "ExecuTorch runtime output JSON decoded by yolozu export --backend executorch.", "flag": "--runtime-output-json", "kind": "file", "name": "runtime_output_json", "required": false }, { "flag": "--run-json", "kind": "file", "name": "run_json", "required": false }, { "flag": "--score-threshold", "kind": "number", "name": "score_threshold", "required": false }, { "flag": "--seed", "kind": "number", "name": "seed", "required": false }, { "description": "Forwarded split name for external training, dataset validation, auto-detect import, and dataset export helpers.", "flag": "--split", "kind": "string", "name": "split", "required": false }, { "flag": "--stage1-epochs", "kind": "number", "name": "stage1_epochs", "required": false }, { "flag": "--stage2-epochs", "kind": "number", "name": "stage2_epochs", "required": false }, { "flag": "--stats-in", "kind": "file", "name": "stats_in", "required": false }, { "flag": "--stats-out", "kind": "file", "name": "stats_out", "required": false }, { "flag": "--strength", "kind": "number", "name": "strength", "required": false }, { "flag": "--success-rot-deg", "kind": "number", "name": "success_rot_deg", "required": false }, { "flag": "--success-trans", "kind": "number", "name": "success_trans", "required": false }, { "flag": "--tag", "kind": "string", "name": "tag", "required": false }, { "flag": "--task", "kind": "string", "name": "task", "required": false }, { "flag": "--tau", "kind": "number", "name": "tau", "required": false }, { "flag": "--temperature", "kind": "number", "name": "temperature", "required": false }, { "flag": "--temperature-grid", "kind": "string", "name": "temperature_grid", "required": false }, { "default": "off", "flag": "--torch-amp", "kind": "string", "name": "torch_amp", "required": false }, { "flag": "--torch-channels-last", "kind": "string", "name": "torch_channels_last", "required": false }, { "description": "Request evidenced torch.compile execution for the Torch export backend.", "flag": "--torch-compile", "kind": "string", "name": "torch_compile", "required": false }, { "default": "inductor", "flag": "--torch-compile-backend", "kind": "string", "name": "torch_compile_backend", "required": false }, { "flag": "--torch-compile-fullgraph", "kind": "string", "name": "torch_compile_fullgraph", "required": false }, { "default": "auto", "description": "torch.compile dynamic-shape policy: auto, true, or false.", "flag": "--torch-compile-dynamic", "kind": "string", "name": "torch_compile_dynamic", "required": false }, { "default": "reduce-overhead", "flag": "--torch-compile-mode", "kind": "string", "name": "torch_compile_mode", "required": false }, { "flag": "--torch-inference-mode", "kind": "string", "name": "torch_inference_mode", "required": false }, { "flag": "--title", "kind": "string", "name": "title", "required": false }, { "flag": "--topk", "kind": "number", "name": "topk", "required": false }, { "description": "Forwarded external launcher path for non-dry YOLOX or HF DETR execution.", "flag": "--train-script", "kind": "file", "name": "train_script", "required": false }, { "flag": "--tta", "kind": "string", "name": "tta", "required": false }, { "description": "Forwarded to the RT-DETR reference trainer; JSON list or object with an images list containing validation records.", "flag": "--val-records-json", "kind": "file", "name": "val_records_json", "required": false }, { "flag": "--tta-flip-prob", "kind": "number", "name": "tta_flip_prob", "required": false }, { "description": "Optional keypoint swap pairs (e.g., '1:2,3:4').", "flag": "--tta-keypoint-swap-pairs", "kind": "string", "name": "tta_keypoint_swap_pairs", "required": false }, { "default": null, "flag": "--tta-log-out", "kind": "file", "name": "tta_log_out", "required": false }, { "description": "TTA mode for export: postprocess or model.", "flag": "--tta-mode", "kind": "string", "name": "tta_mode", "required": false }, { "description": "IoU threshold for model-space TTA merge.", "flag": "--tta-model-merge-iou", "kind": "number", "name": "tta_model_merge_iou", "required": false }, { "flag": "--tta-norm-only", "kind": "string", "name": "tta_norm_only", "required": false }, { "flag": "--tta-seed", "kind": "number", "name": "tta_seed", "required": false }, { "description": "Enable in-memory test-time training during inference (default: off; opt-in).", "flag": "--ttt", "kind": "string", "name": "ttt", "required": false }, { "description": "Auxiliary consistency loss weight for depth heads. 0 disables.", "flag": "--ttt-aux-depth-weight", "kind": "number", "name": "ttt_aux_depth_weight", "required": false }, { "description": "Auxiliary consistency loss weight for keypoint heads. 0 disables.", "flag": "--ttt-aux-keypoints-weight", "kind": "number", "name": "ttt_aux_keypoints_weight", "required": false }, { "description": "Auxiliary consistency loss weight for pose heads (rot6d/log_z/offsets/k_delta). 0 disables.", "flag": "--ttt-aux-pose-weight", "kind": "number", "name": "ttt_aux_pose_weight", "required": false }, { "description": "Auxiliary consistency loss weight for segmentation heads. 0 disables.", "flag": "--ttt-aux-seg-weight", "kind": "number", "name": "ttt_aux_seg_weight", "required": false }, { "description": "Temperature for auxiliary consistency losses. Default 1.0.", "flag": "--ttt-aux-temperature", "kind": "number", "name": "ttt_aux_temperature", "required": false }, { "description": "Use selected foreground class/box response consistency and exclude the final no-object class.", "flag": "--ttt-detector-response", "kind": "string", "name": "ttt_detector_response", "required": false }, { "flag": "--no-ttt-detector-response", "kind": "string", "name": "no_ttt_detector_response", "required": false }, { "flag": "--ttt-response-conf-min", "kind": "number", "name": "ttt_response_conf_min", "required": false }, { "flag": "--ttt-response-topk", "kind": "number", "name": "ttt_response_topk", "required": false }, { "default": 1, "description": "Abstain from a pure detector-response update below this selected-query count.", "flag": "--ttt-response-min-selected", "kind": "number", "name": "ttt_response_min_selected", "required": false }, { "flag": "--ttt-response-class-weight", "kind": "number", "name": "ttt_response_class_weight", "required": false }, { "flag": "--ttt-response-bbox-weight", "kind": "number", "name": "ttt_response_bbox_weight", "required": false }, { "flag": "--ttt-response-entropy-weight", "kind": "number", "name": "ttt_response_entropy_weight", "required": false }, { "flag": "--ttt-batch-size", "kind": "number", "name": "ttt_batch_size", "required": false }, { "flag": "--ttt-cotta-aggregation", "kind": "string", "name": "ttt_cotta_aggregation", "required": false }, { "flag": "--ttt-cotta-augmentations", "kind": "string", "name": "ttt_cotta_augmentations", "required": false }, { "flag": "--ttt-cotta-ema-momentum", "kind": "number", "name": "ttt_cotta_ema_momentum", "required": false }, { "flag": "--ttt-cotta-restore-interval", "kind": "number", "name": "ttt_cotta_restore_interval", "required": false }, { "flag": "--ttt-cotta-restore-prob", "kind": "number", "name": "ttt_cotta_restore_prob", "required": false }, { "flag": "--ttt-eata-anchor-lambda", "kind": "number", "name": "ttt_eata_anchor_lambda", "required": false }, { "flag": "--ttt-eata-conf-min", "kind": "number", "name": "ttt_eata_conf_min", "required": false }, { "flag": "--ttt-eata-entropy-max", "kind": "number", "name": "ttt_eata_entropy_max", "required": false }, { "flag": "--ttt-eata-entropy-min", "kind": "number", "name": "ttt_eata_entropy_min", "required": false }, { "flag": "--ttt-eata-max-skip-streak", "kind": "number", "name": "ttt_eata_max_skip_streak", "required": false }, { "flag": "--ttt-eata-min-valid-dets", "kind": "number", "name": "ttt_eata_min_valid_dets", "required": false }, { "flag": "--ttt-eata-selected-ratio-min", "kind": "number", "name": "ttt_eata_selected_ratio_min", "required": false }, { "flag": "--ttt-exclude", "kind": "string", "name": "ttt_exclude", "required": false }, { "flag": "--ttt-include", "kind": "string", "name": "ttt_include", "required": false }, { "description": "Entropy penalty weight for non-torch TTT-lite.", "flag": "--ttt-lite-entropy-weight", "kind": "number", "name": "ttt_lite_entropy_weight", "required": false }, { "description": "Enable min-max score normalization for non-torch TTT-lite.", "flag": "--ttt-lite-minmax", "kind": "string", "name": "ttt_lite_minmax", "required": false }, { "description": "Enable score-only TTT-lite for non-torch backends.", "flag": "--ttt-lite-non-torch", "kind": "string", "name": "ttt_lite_non_torch", "required": false }, { "description": "Temperature for non-torch TTT-lite score scaling.", "flag": "--ttt-lite-temperature", "kind": "number", "name": "ttt_lite_temperature", "required": false }, { "default": null, "flag": "--ttt-log-out", "kind": "file", "name": "ttt_log_out", "required": false }, { "flag": "--ttt-lr", "kind": "number", "name": "ttt_lr", "required": false }, { "flag": "--ttt-mask-prob", "kind": "number", "name": "ttt_mask_prob", "required": false }, { "flag": "--ttt-mask-value", "kind": "number", "name": "ttt_mask_value", "required": false }, { "flag": "--ttt-max-batches", "kind": "number", "name": "ttt_max_batches", "required": false }, { "flag": "--ttt-max-grad-norm", "kind": "number", "name": "ttt_max_grad_norm", "required": false }, { "flag": "--ttt-max-loss-increase", "kind": "number", "name": "ttt_max_loss_increase", "required": false }, { "flag": "--ttt-max-loss-ratio", "kind": "number", "name": "ttt_max_loss_ratio", "required": false }, { "flag": "--ttt-max-total-update-norm", "kind": "number", "name": "ttt_max_total_update_norm", "required": false }, { "flag": "--ttt-max-update-norm", "kind": "number", "name": "ttt_max_update_norm", "required": false }, { "flag": "--ttt-method", "kind": "string", "name": "ttt_method", "required": false }, { "flag": "--ttt-patch-size", "kind": "number", "name": "ttt_patch_size", "required": false }, { "description": "TTT preset profile (safe, adapter_only, mim_safe, cotta_safe, eata_safe, sar_safe, detector_response_safe, pose_safe, keypoints_safe, depth_safe, seg_safe, pose_mim); sar_safe requires --lora-r > 0.", "flag": "--ttt-preset", "kind": "string", "name": "ttt_preset", "required": false }, { "flag": "--ttt-reset", "kind": "string", "name": "ttt_reset", "required": false }, { "flag": "--ttt-rollback-on-stop", "kind": "string", "name": "ttt_rollback_on_stop", "required": false }, { "flag": "--ttt-sar-adaptive", "kind": "string", "name": "ttt_sar_adaptive", "required": false }, { "flag": "--ttt-sar-first-step-scale", "kind": "number", "name": "ttt_sar_first_step_scale", "required": false }, { "flag": "--ttt-sar-rho", "kind": "number", "name": "ttt_sar_rho", "required": false }, { "description": "SDFT task hint for preset auto-selection (pose | keypoints | depth | seg | full).", "flag": "--ttt-sdft-task", "kind": "string", "name": "ttt_sdft_task", "required": false }, { "flag": "--ttt-seed", "kind": "number", "name": "ttt_seed", "required": false }, { "flag": "--ttt-steps", "kind": "number", "name": "ttt_steps", "required": false }, { "flag": "--ttt-stop-on-non-finite", "kind": "string", "name": "ttt_stop_on_non_finite", "required": false }, { "flag": "--ttt-update-filter", "kind": "string", "name": "ttt_update_filter", "required": false }, { "description": "Forwarded checkpoint path for external fine-tune/resume flows.", "flag": "--weights", "kind": "file", "name": "weights", "required": false }, { "description": "Forwarded preset for the external training helper when `train --external-backend` is active.", "flag": "--preset", "kind": "string", "name": "preset", "required": false }, { "description": "Used by yolozu train-orchestrate to point at a batch spec.", "flag": "--spec", "kind": "file", "name": "spec", "required": false }, { "description": "Optional JSONL registry file appended by yolozu train-orchestrate when --execute is used.", "flag": "--registry-out", "kind": "file", "name": "registry_out", "required": false }, { "flag": "--execute", "kind": "string", "name": "execute", "required": false }, { "flag": "--stop-on-failure", "kind": "string", "name": "stop_on_failure", "required": false }, { "description": "Forwarded task family for `train --external-backend detectron2|mmdetection|mmpose|mmseg|tao`. MMDetection auto inference treats explicit Mask R-CNN or mask_head markers as segmentation; a COCO instances filename alone remains bbox.", "flag": "--task-family", "kind": "string", "name": "task_family", "required": false }, { "description": "Repeatable backend-native config override pair forwarded when `train --external-backend ...` is active.", "flag": "--train-opt", "kind": "string", "name": "train_opt", "required": false }, { "description": "Output directory for dataset layout exports produced by `yolozu export-dataset` (YOLO, COCO, KITTI, or semantic-segmentation images/masks layouts).", "flag": "--out-dir", "kind": "dir", "name": "out_dir", "required": false }, { "description": "Asset materialization mode for `yolozu export-dataset`; `copy` duplicates files, `symlink` keeps a lightweight export tree.", "flag": "--image-mode", "kind": "string", "name": "image_mode", "required": false } ], "maturity": "stable", "outputs": [ { "default": null, "description": "Primary output artifact controlled by --output (subcommand-dependent).", "kind": "file", "name": "output_json" }, { "default": null, "description": "Cache artifacts directory when --cache-dir is used.", "kind": "dir", "name": "cache_dir" }, { "default": null, "description": "Optional HTML output when --html is used.", "kind": "file", "name": "html" }, { "default": null, "description": "Optional overlay directory when --overlays-dir is used.", "kind": "dir", "name": "overlays_dir" }, { "default": null, "description": "Dataset export root written by `yolozu export-dataset` when --out-dir is provided.", "kind": "dir", "name": "export_dataset_root" }, { "default": "reports/doctor_proof", "description": "Doctor proof artifact directory containing toy dataset, known predictions, evaluation report, and proof report when --proof is used.", "kind": "dir", "name": "doctor_proof_dir" }, { "default": "reports/labeled_sample", "description": "demo dataset output: eight synthetic images, YOLO labels and classes, data.yaml, known predictions, labeled preview, README, and versioned sample manifest with hashes.", "kind": "dir", "name": "labeled_sample_dir" } ], "platform": { "cpu_ok": true, "gpu_required": false, "linux_ok": true, "macos_ok": true }, "runner": "python3", "summary": "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.", "tags": [ "cli", "predictions", "diagnostics", "report", "sweep", "long_tail", "import" ] } ] }