yolozu 4.5.1

Lane-based evaluation and workflow toolkit centered on a stable predictions interface contract, with qualified experimental and research paths.

YOLOZU (萬)

Japanese: Readme_jp.md | Chinese: Readme_zh.md

Official page: https://www.toppymicros.com/yolozu/ | PyPI: https://pypi.org/project/yolozu/ | Manual DOI: https://doi.org/10.5281/zenodo.18744926

Evaluate existing predictions

YOLOZU is an Apache-2.0 evaluation layer for predictions produced by your existing vision stack.

Give it a wrapped predictions.json, validate the predictions interface contract, and produce a comparable report.

1-Minute Demo

python3 -m pip install -U yolozu
yolozu doctor --proof
yolozu demo instance-seg --run-dir reports/quickstart_instance_seg --progress

Writes reports/quickstart_instance_seg/instance_seg_demo_report.json and visible PNG overlays under reports/quickstart_instance_seg/overlays/. The matching checklist lives at configs/quickstart/instance_seg_demo.yaml. For the full CPU-only DoD path (doctor --proof -> demo -> validate -> eval), see docs/cpu_only_dod.md. If you are unsure what to run next, use the built-in guide:

yolozu guide
yolozu guide --goal first-run
yolozu guide --goal evaluate

flowchart LR
    A["Ultralytics"] --> D["wrapped predictions.json"]
    B["RT-DETR"] --> D
    C["Detectron2 / MMDetection / custom"] --> D
    D --> E["validate"]
    E --> F["evaluate"]
    F --> G["comparable report"]

Read These First

• docs/README.md: top-level docs map and shortest working paths
• docs/predictions_schema.md: the predictions interface contract
• docs/install.md: install, doctor, and environment setup

Primary Focus

• Stable lane: evaluate precomputed predictions fairly across frameworks and runtimes
• Bridge lane: export or external training flows that emit the same predictions interface contract
• Benchmark lane: qualify backend parity after the stable evaluation path is working
• Research lane: opt-in workflows over already evaluated artifacts

Capability Maturity

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

Production Readiness

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

Who This Is For

• You already have predictions and want fair cross-framework evaluation.
• You want an Apache-2.0 evaluation layer without rewriting your training stack.
• You do not want framework-native evaluation differences to become silent metric drift.

Not The Best Fit

• You want one end-to-end training framework with one-click defaults.
• You do not need cross-framework comparison or a stable predictions interface contract.

Why Not Just Use Framework-Native Evaluation?

Framework-native evaluation is convenient inside one stack, but it is harder to compare fairly across stacks. YOLOZU keeps the evaluation boundary at one predictions interface contract so the comparison path stays pinned even when the inference stack changes.

Where To Go Next

• Evaluate precomputed predictions: docs/external_inference.md
• Train, export, then evaluate: docs/training_inference_export.md
• YOLO-style and Detectron2 external training lanes (yolozu train --external-backend yolox|detectron2|ultralytics|hf-detr ...): docs/training_inference_export.md
• Current training support matrix and scope boundary: docs/training_inference_export.md#current-training-support
• Training backend interface / capability matrix / orchestration: docs/training_backend_interface.md, docs/training_capability_matrix.md, docs/training_orchestration.md
• Qualify backend-parity and benchmark paths after the main eval lane is working: docs/backend_parity_matrix.md, docs/benchmark_mode.md, docs/benchmark_support_matrix.md
• Prepare YOLOZU-synthgen handoff: docs/synthgen_repo_integration.md
• Tool and manifest references: docs/tools_index.md, tools/manifest.json

Secondary And Research Lanes

• Training, export, benchmark, SynthGen, and research workflows feed or extend the evaluation boundary.
• External training bridge: YOLOX first, optional Ultralytics and HF DETR bridges second
• SynthGen handoff: docs/synthgen_repo_integration.md
• Research workflows: docs/research_lanes.md
• Real-image showcase: docs/assets/readme_multitask_showcase.png

Repo Users

python3 -m pip install -e .
bash scripts/smoke.sh

More repo-first guidance:

• Docs index: docs/README.md
• Install details: docs/install.md
• Manual sources: manual/README.md

Support And Legal

• Support: docs/support.md
• License policy: docs/license_policy.md
• External training boundary: YOLOX first, optional Ultralytics and HF DETR bridges second
• Apache-2.0 license: LICENSE
• Latest release: GitHub Releases
• Zenodo software DOI: 10.5281/zenodo.18744756
• Zenodo manual DOI: 10.5281/zenodo.18744926