Core concepts

Tasks

A task is what a model returns. LibreYOLO has seventeen canonical task names, and each one names the field on the Results object that carries its output.

Those are the names that appear in checkpoint metadata and in filenames. Familiar aliases are accepted wherever a task is passed and normalized before anything else happens: detection and det become detect, keypoints becomes pose, cls becomes classify, deblur, denoise and super-resolution all become restore, face-recognition and reid become embed. An unrecognized name raises rather than silently defaulting.

segment, semantic and panoptic are three different tasks, not three words for one. Instance masks, per-pixel labels and the merged thing-plus-stuff map have different ground truth, different metrics and different result fields.

Model families

A family is one architecture lineage with its own loading, preprocessing and postprocessing code. Every family declares a FAMILY identifier such as yolo9, rfdetr or dfine, the tasks it supports, and the input resolution for each size it ships.

LibreYOLO() is a factory rather than a class. Given a path it loads the file, identifies the family from the checkpoint's metadata or, failing that, from the tensor keys themselves, and returns an instance of that family's model. This is why swapping detectors is a one-line change: the object that comes back exposes the same predict, train, val and export surface and returns the same Results type.

# Tasks, sizes and input resolutions for every registered family.libreyolo models

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt") print(model.family, model.size, model.task)print(model.input_size)print(model.nb_classes, model.names[0])

from libreyolo import LibreYOLO # Aliases normalize at the API boundary: "keypoints" resolves to# "pose", "det" to "detect", "semantic-segmentation" to "semantic".model = LibreYOLO("LibreYOLO9t.pt", task="det")print(model.task)

A family that serves more than one task usually publishes a separate checkpoint per task, often with a different set of sizes for each; a few share one artifact between two runtime tasks instead. Either way the supported tasks are a fixed list, and asking for one outside it raises with the supported list in the message rather than loading something approximate.

The full list, with per-family benchmarks and published weights, is at all models.

Sizes

A size is a variant within a family, written as a lowercase code attached directly to the family prefix. The common letters are n for nano, t for tiny, s for small, m for medium, l for large and x for xlarge, but the codes are family-specific and several families use something else entirely: backbone-named codes such as r50 or r101 where the size is a ResNet depth, compound-scaling codes such as b0 through b3, or a name that identifies the one released checkpoint. YOLOv9 uses c for compact where other families use l.

Size also fixes the input resolution, and for families with several tasks the resolution can differ per task. Both are read from the family, never assumed; libreyolo models prints them.

Checkpoint filenames

Every published weight file follows one schema:

Libre<FAMILY><size>[-<task>].pt

The family prefix is a fixed string per family, the size is lowercase and attached with no separator, and the task suffix is hyphen-prefixed. Detection carries no suffix, following the convention YOLO checkpoints have always used, so LibreYOLO9t.pt is a detector and LibreRFDETRn-seg.pt is a segmentation model of the same family.

A family with no suffixless task can require the suffix, so that a name without one is not accepted as a valid checkpoint for it. A family that publishes weights trained on a dataset other than its default appends the dataset name as a further suffix, and that variant stays part of the repository name the file is downloaded from.

Three tiers stand outside this schema. The promptable segmentation families, the vision-language families and the open-vocabulary detectors are not registered into the checkpoint factory and emit no Libre<FAMILY><size>.pt file. Their prefix names a downloaded Hugging Face snapshot or a promptable checkpoint instead, and upstream brand casing is preserved there on purpose.

How the task is decided

When several signals could name a task, they are consulted in a fixed order and the first one that is present wins: the task argument you passed, then the task recorded in the checkpoint metadata, then the task suffix in the filename, then the family's default task. The result is checked against the family's supported tasks before the model is built, so a mismatch fails at load time rather than producing wrong output later.

Support tiers

Families are enrolled in exactly one tier. A tier is a statement about engineering attention, not about accuracy: it tells you where a new feature lands first and what is kept green.

Each model page carries its family's tier in the header. The two flagship families are YOLOv9 for the CNN detectors and RF-DETR for the transformer detectors; start there unless you have a reason not to.

Inference only says what is missing, which is a training loop in LibreYOLO. Predict, validate and, where the family supports it, export all work. Calling train() on such a family raises NotImplementedError naming the reason.