Skip to main content

YOLOZU (萬)

Japanese: Readme_jp.md | Chinese: Readme_zh.md

Company: ToppyMicroServices OÜ | 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 a commercial product developed by ToppyMicroServices OÜ and provided free of charge. The repository code is licensed under Apache-2.0.

Its stable product lane validates and evaluates existing vision predictions through a stable predictions interface contract. Use it to compare object-detection outputs from different frameworks on the same labelled dataset and evaluation settings.

You keep your model and inference stack. YOLOZU reads a wrapped predictions.json and ground-truth labels, then writes a JSON evaluation report. It does not improve model accuracy by itself.

Install and evaluate your predictions

Requires Python 3.10 or newer. On macOS/Linux, start in a virtual environment (Windows and other setup options):

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install 'yolozu[coco]'
yolozu --help

Replace the two absolute paths below with your files. The dataset needs images/val/ and labels/val/ with YOLO-format ground truth. Predictions use normalized cx, cy, w, h boxes, matching zero-based class IDs, and image names that join to that split. See the input format or the framework export quickstarts if your output uses a different format.

yolozu validate predictions /absolute/path/to/predictions.json --strict
yolozu validate dataset /absolute/path/to/yolo-dataset --split val --strict
yolozu eval-coco \
  --dataset /absolute/path/to/yolo-dataset --split val \
  --predictions /absolute/path/to/predictions.json \
  --bbox-format cxcywh_norm --output reports/coco_eval.json

Open reports/coco_eval.json and inspect metrics.map50_95, metrics.map50, and the evaluated image/detection counts. Compare models with the same dataset, class mapping, preprocessing, and export settings. Adding --dry-run checks input conversion without COCOeval; its null metrics are not measured accuracy.

Try without a model or dataset

In an activated virtual environment, the core install can run this CPU demo. It creates synthetic shapes and predictions locally, with no model download.

python3 -m pip install -U yolozu
yolozu doctor --proof
yolozu demo instance-seg --background synthetic --inference none --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/. These synthetic metrics and overlays check the workflow; they do not measure the accuracy or speed of a real vision model. Need reusable images and YOLO labels? From version 4.8.0, yolozu demo dataset --run-dir reports/labeled_sample creates an eight-image sample, a labeled preview, and known predictions. See the labeled-sample walkthrough for evaluation and reuse.

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

Python And AI Quick Use

Use the typed in-process API when another Python program owns the workflow:

from pathlib import Path

from yolozu.api import evaluate_coco

result = evaluate_coco(
    dataset=Path("/absolute/path/to/dataset"),
    predictions=Path("/absolute/path/to/predictions.json"),
    dry_run=True,
)
print(result.to_dict())

This API example is a dry run. With yolozu[coco] installed, use dry_run=False to compute metrics from your predictions and ground truth.

Give an AI client the small guaranteed-tool list before exposing wider surfaces:

yolozu-mcp --print-tools --guaranteed --ids-only

See docs/python_api.md and docs/ai_first.md for typed errors, workspace boundaries, MCP setup, and larger opt-in discovery.

Before training, fail closed on an empty or invalid split and ask the train doctor for a machine-readable readiness decision:

yolozu validate dataset /path/to/yolo_dataset --split train --strict
yolozu doctor train-dataset --dataset /path/to/yolo_dataset --split train --output -

For separate COCO annotation and image paths, use --instances together with --images-dir; --dataset is not required. See docs/training_inference_export.md.

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"]

PyPI Python >=3.10 License CI

Read These First

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

Adaptive Local Vision Roadmap

Environment-aware local image processing remains Experimental delivery work. It does not change the current Stable prediction validation/evaluation surface.

The packaged adaptive models cannot currently execute: their runner bindings and qualified support evidence are absent. See the roadmap and OSS support scope for the current boundary.

Adaptive implementation details and evidence

The target design lets an AI client turn natural language into a typed request, then asks YOLOZU to select only among pipelines qualified for the matching task, hardware, runtime, workload, protocol, and license constraints. If the evidence is missing or mismatched, the result is abstention rather than an inferred "best" model. Recommendation and execution remain local and do not implicitly download assets.

Strict request, environment, evidence, eligibility-observation, and SelectionDecision interface contracts are packaged for integration work. yolozu doctor --output - now includes a privacy-safe live environment_profile; failed probes stay unknown and do not prove that an accelerator is absent. The packaged bundle registry now contains three non-promoted Candidate baselines matching the existing model zoo: YOLOX-S, Detectron2 Faster R-CNN R50-FPN 1x, and MMDetection Faster R-CNN R50-FPN 1x. Their pinned weights are fetchable metadata, but their adaptive execution binding is explicitly unbound. Loading and validation do not import a model runtime. Experimental yolozu scout-algorithms now validates one canonical official-source allowlist and, only with --collect, writes a dated candidate inbox. The default command is a network-free, write-free plan. Collected pages are untrusted metadata; raw documents are not retained, and the inbox cannot be loaded as an AlgorithmBundle registry or used as qualification, support, recommendation, adoption, or promotion evidence. Experimental yolozu check-qualification-freshness reads active qualification deadlines and governed runtime/bundle drift without re-running or extending evidence. The repository schedule retains only bounded public identifiers; an explicit site evidence root remains local-only and never uploads site facts. The contract-only OCR result boundary keeps recognized text as inert untrusted user output, separate from detection labels. It ships no OCR model, adapter, document parser, remote service, or support claim. The contract-only streaming boundary defines bounded per-frame results, privacy-safe summaries, unactivated qualification-report record shapes, and explicit selection or abstention. The separate tracking boundary validates session-scoped state transitions against those frame results. This adds no decoder, live runner, tracker, model, or support claim. Candidate screening is implemented as a separate non-executing interface contract. It derives pass, hold, or reject from bounded provenance, integrity, license, local-availability, task/output, runtime, resource, maintenance, security, and human-review facts. Mandatory unknowns remain hold. The sole packaged append-only screening stream contains two current hold decisions from the 2026-08-29 candidate review, and workspace screening input is always operator-asserted. Neither record is a managed pass, so no candidate is made available by this implementation. Explicit workspace catalogs remain operator-asserted and nonselectable. The Experimental yolozu qualify-image-pipeline command now implements pinned no-follow input and asset preflight, a frozen repeat/soak protocol, bounded child-process cancellation, and atomic unactivated qualification_report.json publication. Experimental yolozu activate-qualification-evidence now dry-runs every review, trust, freshness, registry, lifecycle, and stale-head gate before it can append an activation, supersession, or terminal revocation. Mutation requires --approve. Experimental yolozu review-image-pipeline-support-profiles separately reviews one complete ordered exact-measured target set. It reads and, only with --approve, atomically appends to the sole packaged support_profiles.jsonl SSOT. A reviewed set remains dormant: it does not change a lifecycle pointer, activate evidence, bind a runner, download a model, or claim current support. The stream is currently empty. Recommendation and execution use the same loader-derived support-profile provider, and execution reprojects the lifecycle-pinned historical set before any runner session is opened. Experimental yolozu update-image-pipeline-lifecycle adds a separate reviewed, dry-run-first maintenance interface contract for exact disable, enable, license review, terminal global revoke, and explicit per-channel rollback. Mutation requires --approve, the observed lifecycle and support heads, immutable bundle/artifact identities, and an approved public review. A non-none rollback must restore the complete historical advertised profile set and one current repository-managed activation per profile for an eligible same-family target. It cannot choose a newer dormant target, accept a caller-authored subset, use a never-assigned Candidate as a promotion shortcut, promote a bundle, or mutate from metrics alone. The rollback event records the exact historical target-assignment digest. No lifecycle event was appended by this change. Experimental yolozu promote-image-pipeline implements the separate reviewed promotion path. Candidate-to-Experimental and Experimental-to-Stable are distinct operations, and omission of --approve is always a no-write dry-run. The command requires exact source/target pointers and stream heads, the complete canonical ordered support-profile set, and one current repository-managed activation per profile. Stable additionally requires a passed bounded failure-drill report, separate human repository approval, all preregistered absolute gates, and exact zero-tolerance comparison with the current Stable reports when a comparator exists. It cannot use site-managed evidence, infer approval, change the Stable profile set, or modify bundle, support, screening, evidence, report, or artifact inputs. This implementation did not promote any model; the packaged streams remain Candidate-only. Locally emitted reports can reach only site_managed / site_qualified; arbitrary workspace JSON remains nonselectable. Repository-managed trust additionally requires the retained, tracked review workflow and a public review reference. No adaptive runner is bound to those records, so the command currently fails actionably instead of producing dummy evidence. A pure internal selector now applies the fixed trust, compatibility, artifact, evidence, performance, and deterministic ranking rules to already validated in-memory observations. It performs no provider-file, model, runner, or network I/O. The Experimental MCP-only recommend_image_pipeline tool now exposes the same bounded selection policy as a read-only structured recommendation. It validates the typed job and local input, checks non-I/O gates before artifact access, and returns either a complete SelectionDecision or an honest abstention. It does not run inference, download or write assets, parse natural language, or expose absolute paths or raw probe output. Because the three records remain Candidate and the public evidence stream is empty, the default call currently abstains with maturity_disallowed. Experimental MCP-only process_images now accepts that complete selected decision, revalidates the job, current lifecycle/evidence, environment, workload, input, class mapping, and pinned artifact state, and defaults to a no-write dry_run=true. Explicit execution uses only a registered code-owned, network-free route and publishes an atomic managed predictions/provenance/checksum tree. The adaptive runner maps remain empty, so no real adaptive model can currently execute; no model adapter or performance claim was added. An activation record alone does not select or execute a model. Registry loading, an environment profile, a smoke result, and output publication alone are not qualification evidence or proof of human adoption.

The baseline bundle registry report records the current three-way state boundary. The earlier algorithm scout foundation report records the monitored-source, retention, parser, and nonselection boundaries. The earlier candidate screening foundation report records the fail-closed screening and path-derived trust boundaries. The earlier lifecycle maintenance and rollback report records the reviewed mutation, immutable-history, and exact rollback boundaries. The earlier installed-artifact verification report checks the same boundary from source, sdist, wheel, and installed MCP calls. Its positive selector and executor cases use internal fixtures; they do not qualify a real bundle or demonstrate a selected public run.

See the generated roadmap report, the packaged machine-readable projection, and the Beads synchronization rule.

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, TTA
  • Research: continual learning, self-distillation, TTT, Hessian refinement, and BOP T-LESS rigid-object 6DoF

These are capability-level boundaries. A Stable parent CLI or manifest entry does not promote opt-in subcommands or flags: export_predictions keeps baseline export Stable, TTA Experimental, and TTT Research.

Experimental and Research results and their limits

The BOP lane means rigid-object R,t pose, not human 3D skeleton pose. Its real T-LESS diagnostic has strict GT, three-seed task-native before/after evaluation, and an independent semantic reproduction. The follow-up exports matched pose estimates for the official BOP19 test targets and evaluates them with the pinned official toolkit. The lane remains Research because protocol completion produced only small, seed-inconsistent official and task-native scores; one seed had zero 0.1-diameter pose success. See the diagnostic report and official-test report.

The continual-learning lane now has a one-command, schema-defined three-seed naive-versus-checkpoint-distillation diagnostic: ./.venv/bin/python tools/qualify_sdft_continual.py --output-dir /tmp/yolozu-sdft-qualification. It runs real COCOeval and records baseline-relative FWT, hashes, time, memory, and fairness checks. This is an SDFT-style detector regularizer rather than a faithful reproduction of language-model SDFT, and it remains Research until efficacy is established. The completed 2026-07-28 run is a measured negative result: every real-COCOeval matrix cell and every SDFT-minus-naive delta was zero, so the decision is hold and efficacy is not_established. The hash-verified bundle is available as a GitHub prerelease; the bundle has been independently reproduced in a second Python/Torch environment. See the evidence report. The 2026-07-30 confirmatory spec produced non-zero task scores for all seeds, and an independent run reproduced the protocol and gate outcomes. Two of three seeds passed the preregistered retention/adaptation checks; seed 66 failed the strict old-task improvement gate. Efficacy therefore remains not_established; see the confirmatory report.

Experimental fine-tuning lanes can be audited in one command with ./.venv/bin/python tools/qualify_finetune_lanes.py --output-dir /tmp/yolozu-finetune-qualification. The schema-defined result separates executed training from config projection, records dependency failures and checkpoint/provenance hashes, and keeps the lane Experimental when task-native metrics or non-heuristic labels are absent. The bounded clean-source result remains hold; see the fine-tuning evidence report. The 2026-07-30 follow-up used strict T-LESS GT and executed real training in Ultralytics, HF DETR, and Detectron2 across two environments; five other external runtimes emitted structured availability failures. The runtime evidence remains Experimental and hold. A compatible Linux/CUDA workflow separately completed non-dry training for YOLOX, MMDetection, MMPose, MMSeg, and NVIDIA TAO in two independent runs on the same pinned T4 stack. This establishes compatible-host runtime availability and structural handoff reproducibility, not training quality or checkpoint byte determinism. All five lanes remain Experimental / hold; see the compatible-host report.

TTT comparisons can be run as a fail-closed multi-seed clean/shift matrix with tools/run_ttt_evidence_suite.py; generated metrics do not promote the Research lane. The bounded 2026-07-27 diagnostic bundle is available as a GitHub prerelease; the archive SHA-256 is bb200d0c0a36447f0b6ed262a56ee09bef44ded8f10c55673243080fe1054068. All 30 matrix cells have been independently reproduced with zero semantic differences. This establishes diagnostic reproducibility, not efficacy. See docs/ttt_protocol.md.

A separate 2026-08-01 local diagnostic uses a stronger, fully compatible source checkpoint and a detector-native response objective: it excludes the final no-object class, selects confident foreground queries, and keeps same-query class/box consistency across a weak photometric view. It abstains without backward or optimizer execution and restores normalization buffers when the selected count is below the configured minimum. On the fixed 10-image clean/shifted fixtures, COCO mAP50:95 changed from 0.000990→0.001188 and 0.000330→0.000396, respectively, with no guard stops. This is a positive bounded observation, not independent evidence or an efficacy claim. See the detection-native report.

Production Readiness

  • Stable scope: 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

Best Fit

  • Compare predictions from multiple frameworks or runtimes on the same dataset and pinned evaluation protocol.
  • Validate and wrap predictions from your own or a third-party vision stack before running one evaluation path.
  • Add CI or regression reports that expose metric, preprocessing, or backend drift.

Not The Best Fit

YOLOZU is not the best fit when you need a managed training platform, hosted inference service, guaranteed support or SLA, or one-click production deployment. If you evaluate only within one framework and do not need a stable cross-stack boundary, that framework's native evaluator may be simpler. Training, benchmark, adapter, and research capabilities are secondary qualified lanes, not the stable product promise.

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

Secondary And Research Lanes

Repo Users

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

More repo-first guidance:

Support, Feedback, And Legal

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

yolozu-4.8.0.tar.gz (2.0 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

yolozu-4.8.0-py3-none-any.whl (1.1 MB view details)

Uploaded Python 3

File details

Details for the file yolozu-4.8.0.tar.gz.

File metadata

  • Download URL: yolozu-4.8.0.tar.gz
  • Upload date:
  • Size: 2.0 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for yolozu-4.8.0.tar.gz
Algorithm Hash digest
SHA256 14ba05a02477fe33df843ded2c9294e253a6251d37793af1658e2e516931de18
MD5 3d89aa99ed787036330589a83e13de66
BLAKE2b-256 7ef9bf2126e9bc79e3f323b57f69fbef2575511e78828c658f6656df5a7fbd14

See more details on using hashes here.

Provenance

The following attestation bundles were made for yolozu-4.8.0.tar.gz:

Publisher: publish.yml on ToppyMicroServices/YOLOZU

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file yolozu-4.8.0-py3-none-any.whl.

File metadata

  • Download URL: yolozu-4.8.0-py3-none-any.whl
  • Upload date:
  • Size: 1.1 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for yolozu-4.8.0-py3-none-any.whl
Algorithm Hash digest
SHA256 36894d84deac82971a88bbc07efa2fbe66fe33b85db0a4219919fe9c096d8391
MD5 20d41716fa5dc508a32df3bc980489e7
BLAKE2b-256 604b9fc49d4b1daa2085d7ca19ecf647c3de08d73bf4d79845d2e26f1fdd3cc4

See more details on using hashes here.

Provenance

The following attestation bundles were made for yolozu-4.8.0-py3-none-any.whl:

Publisher: publish.yml on ToppyMicroServices/YOLOZU

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

4.8.0 This release

2 files

4.7.0

2 files

4.6.0

2 files

4.5.1

2 files

4.5.0

2 files

4.4.1

2 files

4.4.0

2 files

4.3.1

2 files

4.3.0

2 files

4.2.0

2 files

4.1.0

2 files

4.0.0

2 files

3.0.0

2 files

2.0.0

2 files

1.0.8

2 files

1.0.3

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page