Stability tiers

Export support tiers

The tier that decides whether a call succeeds. It applies to the triple (family, task, format), and every combination has exactly one.

Validated and available both proceed without an acknowledgement or a blanket warning. The difference is evidence, not permission: a validated entry has a parity test behind it and a since release, and an available entry does not yet. A CoreML conversion without a macOS prediction run, for example, is available and not validated.

A blocked combination fails before dependency checks, calibration loading, tracing or artifact creation, so nothing partial is written.

Every validated cell carries a constraint describing the configuration the parity number came from, typically a fixed input canvas, batch 1, FP32 and a named runtime version. Read it as a claim about that configuration rather than about the format in general. The rules that fill cells with no explicit entry are on the export matrix page.

from libreyolo.models.registry import GROUPS, group_offrom libreyolo.export.support import get_support, validated_alternatives family = "yolo9" group = group_of(family)print(group, GROUPS[group]) print(get_support(family, "detect", "onnx").tier)print(validated_alternatives(family, "detect"))

API tiers

The tier that decides what a call looks like. A family sits in exactly one, chosen by call contract rather than by architecture.

The three sibling tiers deliberately do not register into the detector factory, which is why LibreYOLO("some-alias") does not reach them. They load by size alias and autodownload rather than by checkpoint sniffing.

All four return the same Results, so downstream code is unchanged across them. What differs is which methods work: the sibling tiers raise NotImplementedError for train(), val() and export(), and the SAM and open-vocabulary tiers raise for track() as well. Each tier page lists its own exclusions.

Coverage groups

The classification that decides which families a cross-family test run includes, and the one a reader is most likely to meet on a model page. Every registered family is enrolled in exactly one group, and a test fails when a registered family is missing from the enrollment. GROUPS in libreyolo/models/registry.py is the source of the Meaning column below; MODEL_GROUPS in the same file assigns every family, and the Families column counts that assignment directly. The Label column is the shorter name the site uses for the same group on a model page header.

That is 87 families across six groups. g3 alone holds more families than every other group combined, because most of the registry is inference-only lineage and museum coverage rather than actively trained detectors.

For a reader choosing a model, the group says where to expect engineering attention, not how accurate a family is. g0 and g1 are where a new feature is designed and land first; g2 is kept green in CI but a feature lands there opportunistically rather than on the same release wave. g3 states an absence rather than a limit: predict, validate and, where the family supports it, export all still work, and train() on a g3 or g4 family raises NotImplementedError naming the reason rather than doing something silently partial. s families do not sit in this trade-off at all, because they load through their own factory rather than LibreYOLO(). See core concepts for how a group fits alongside task, family and size when reading a checkpoint filename.

A group does not grant or restrict a user-facing capability by itself. Support comes from the family's implemented API and from format-specific capability checks, never from group membership alone. Groups classify families, not tasks, so a task-scoped coverage run names the task explicitly, as in "g1 detect".

Two places read the group at runtime rather than only in tests. collect_model_inventory() in libreyolo/models/inventory.py attaches the group to every entry the CLI inventory prints, and pretrained=False triggers the special from-scratch reinitialization path only for families in g0 and g1. Outside those two groups the check in libreyolo/models/base/model.py is skipped entirely, so pretrained=False reaches the family's own train() as an ordinary keyword instead.

Training

A family in g3 or g4 has no training implementation, and calling train() on one raises. That is a property of the family's code, not of its group: the group records the fact rather than causing it.

For a family that does train, whether an individual augmentation knob reaches the pipeline is a separate question with its own three-value vocabulary, used, gated_by_mosaic and ignored. See the augmentation matrix.

What a tier does not tell you

A tier is not an accuracy claim. A validated export says the artifact reproduces the native model within a stated threshold; it says nothing about how well the native model scores on a dataset. Benchmark numbers live on the model pages.

A tier is also not a licensing statement. Weight licenses vary within a family and the repository hosting a specific checkpoint is authoritative. A family being in the detector factory says nothing about whether its published weights permit commercial use.