libreyolo

Cut a LibreYOLO version release end to end: evidence-backed changelog built by fan-out agents over the release..dev diff, a gate scoreboard (unit CI, GPU e2e on Modal reusing the nightly, weight autodownload probe, wheel smoke, notices sync, docs drift, breaking-change sweep), the branch/tag/PyPI mechanics, post-publish verification, and the handoff to the marketing repo's announcement pipeline. Use whenever the user says "release", "cut vX.Y.Z", "ship a version", "prepare the changelog for the release", or "is dev ready to release?".

Use LibreYOLO as a computer vision library: run inference, train, validate, export, and track with object-detection / segmentation (and pose, classify, gaze, OBB, semantic, depth, point, restore) models on your own images and video. This is the guide for *using* the `libreyolo` pip package — not for contributing to or developing it. Use whenever someone wants to detect, segment, or track with a YOLO9 or RF-DETR model, train on a YOLO-format dataset, measure mAP, run inference on an exported model, or export to ONNX / TensorRT / OpenVINO / CoreML / NCNN / TFLite. Covers both the `libreyolo` CLI and the `from libreyolo import LibreYOLO` Python API.

Add or extend a LibreYOLO CLI command or flag correctly: the Typer + KeyValueCommand architecture, both argument grammars (key=value and --key value), the --json/--quiet/--help-json contract, mode-aware aliases, family-derived defaults, and the unit tests that gate CLI behavior. Use when someone asks to add a CLI command, add a flag to predict/train/val/export, expose a Python feature on the CLI, or when a CLI parsing bug is reported (bool flags, aliases, key=value quirks). API naming decisions belong to libreyolo-api-conventions; this is the implementation side.

Add a new task type to LibreYOLO (a new output kind like detect, segment, semantic, pose, classify, gaze, obb, point, depth, restore), as opposed to adding a model family to an existing task. Use when someone proposes a new capability that no current task's result/label/metric contract fits, e.g. "add OCR", "add 3D boxes", "add image enhancement as a task". Covers the decision (new task vs existing task), and the full wiring checklist: tasks.py registration, the Results payload class, dataset loader + schema, validator, trainer support, filename suffix, docs/ADR, and the tests that gate each piece. For porting a model into an existing task use libreyolo-port-model.

The rules every user-facing LibreYOLO surface must follow (Python API, CLI, dataset YAMLs, metric keys, Results fields) and the safe method for checking parity with the de-facto YOLO ecosystem conventions. Use when designing or reviewing any new public API, CLI command or flag, train/val kwargs, metric names, or Results attributes; when someone asks "what should this be called?", "should predict return a list?", or "is this compatible with standard YOLO tooling?"; or when an API-parity gap is reported. Encodes the AGENTS.md rule that user-facing APIs follow the ecosystem standard, and the license-safe way to verify that (docs only, never source).

Inspect, validate, produce, and debug LibreYOLO .pt checkpoint metadata. Use when a checkpoint won't load ("not a LibreYOLO checkpoint", wrong family/task/class-count errors), when writing or reviewing a conversion script, when deciding what a converter must emit, when preparing weights for HF upload, or when a schema change is proposed. Covers the inspection commands, the serialization helpers that are the only sanctioned writer/reader, the lean-vs-training checkpoint distinction, the legacy/foreign-weights paths and auto-conversion, and the contract-change protocol. The schema itself lives in docs/checkpoint_schema.md; this skill is how to work with it.

Work on LibreYOLO's export subsystem: debug a failing export, fix an exported model that predicts differently from the .pt, extend a format's coverage to a new family/task, or add a new export format. Use when someone reports "export to X fails", "the ONNX/TensorRT model gives different results", asks which formats a family supports, or wants a new format wired. Covers the exporter/backend twin architecture, the metadata round-trip contract, per-format quirks and extras, the parity-testing method, and the support-claim bar. For a user just running export, see use-libreyolo; for Hailo specifically, libreyolo-export-hailo.

Audit and maintain LibreYOLO's licensing and provenance surfaces, and handle contamination correctly. Use when adding ported code or weights (which notice files must change), when reviewing a PR for license risk, when someone asks "can we use/host/ship X?", when a family's provenance is questioned, or when GPL/AGPL/NC-licensed material may have touched the work. Covers the four notice surfaces and when each changes, the code-vs-weights license distinction, the decision table for common licenses, the contamination protocol, and the hard rules: no clean-room laundering, surface decisions to the maintainer instead of quietly "fixing" them.

Port a model into LibreYOLO. Executable guide — finds your closest existing family to clone, gives paste-ready templates for the model class, conversion script, runtime auto-convert recognizer, and trainer subclass, then walks the port as a sequence of self-contained commits. Covers detection, pose, and segmentation in depth; routes classify / semantic / depth / restore / point / gaze ports to their merged exemplar families. Use this for any new family (RTMO, MobileDet, PP-YOLOE, a new HF model).

Review a LibreYOLO pull request the way this repo expects: contract-first (REVIEW.md axioms + /docs schemas), evidence-based, and verified live in a worktree rather than by reading the diff alone. Use whenever the user asks to review a PR, assess an external contribution, second-opinion a branch, or "deep review" something before merge. Covers the reading order, the worktree + live-verification method, the finding taxonomy and severity bar, and the delivery rules (findings go to the user; agents never post PR comments or reviews themselves).

Launch LibreYOLO's end-to-end (e2e) test suite the right way — the heavy GPU tests under tests/e2e/ that load real weights, export to ONNX/TensorRT/OpenVINO/ ncnn/TorchScript/CoreML, train on real datasets, and check inference parity. Use whenever someone wants to run e2e tests, the nightly suite, a single e2e file, a model family's e2e coverage, an export-backend check, or an RF1/RF5 training test — or is confused about why e2e tests "don't run" or all skip. Covers the Makefile targets, the direct-pytest fallback (Windows / no make+uv), the marker taxonomy, weight/dataset provisioning, and how to read the results. This is for *running* the e2e suite, not for writing new e2e tests.

Run and write LibreYOLO's unit tests and the PR gate: the fast, hermetic, CPU-only suite under tests/unit/ that gates every push and PR to dev. Use whenever someone wants to run unit tests, "run the tests before pushing", check whether a change breaks the PR gate, run one test file or one area (CLI, a model family, augmentations), or add a new unit test that must stay inside the PR-gate contract. Covers the marker taxonomy (unit / external_data / network), the hermeticity rules and the HTTP blocker, the Windows no-make fallback, golden fixtures, and how to keep a new test PR-gate-safe. For the heavy GPU suite use libreyolo-run-e2e-tests instead.

Triage a LibreYOLO GitHub issue or user bug report: reproduce it, classify it, find the owning code, and hand the user a decision-ready assessment. Use when someone says "look at issue #N", "a user reports X", "triage the new issues", or pastes a bug report / stack trace from a LibreYOLO user. Covers the reproduce-first discipline, the version gotcha (released vs dev), the classification taxonomy, multi-part report handling, and the reply the human can post. Agents never open issues, close issues, or post comments; triage output goes to the user.

Signpost for updating www.libreyolo.com (docs pages, feature announcements, SEO articles) when something ships in the library. Use when a change needs user-facing docs beyond the repo ("document this on the website", "add a docs page for X", "the site still says Y"), when the release process flags docs drift (Gate G), or when someone wants an article written or the site deployed. The website is a SEPARATE repo with its own skills; this skill orients you, states when a website update is required, and hands off.

Prepare and upload a LibreYOLO weight repo to the HuggingFace LibreYOLO org. Use when publishing new weights (new family, new size, or new task like -seg). Covers filename, README, LICENSE, NOTICE, and collection membership.

Prove that a LibreYOLO model actually trains correctly, not just that train() runs without crashing. Use when adding or changing a trainer, loss, augmentation, scheduler, or DDP path; when someone asks "does training work for family X?", "is this model trainable?", or reports bad fine-tune results; or before claiming a new family's training is production-ready. Covers the confidence ladder (overfit gate, RF1 marbles floor, regression and RF5 tiers, full-run spot checks), the objective definition of "experimental training", the recurring silent-training-bug classes and how to hunt each one, and how to watch a live run. Speed problems are libreyolo-profiling; running the suites is libreyolo-run-e2e-tests.

Add or extend LibreYOLO e2e test coverage the right way: a new model family's GPU coverage, a new export backend file, a nightly case, or a training e2e. Use when someone asks to "add e2e tests for X", wire a new family into the nightly, cover a new export format end to end, or when a PR review flags missing e2e coverage. Covers the marker taxonomy to declare, the MODEL_CATALOG and GENERAL_NIGHTLY_INFERENCE_MODELS rows, the versioned nightly contract (when to bump it), weight provisioning via require_test_weights, and the one-file-per-process constraint that shapes how files are laid out. For *running* the suite use libreyolo-run-e2e-tests.

Use LibreYOLO's zero-shot and promptable tiers: open-vocabulary detection with text vocabularies (LibreOpenVocab: Grounding DINO, OWLv2), promptable segmentation with points/boxes (LibreSAM: SAM-1, SAM-2, MobileSAM), zero-shot classification (LibreCLIP set_classes), and VLM-as-detector (LibreVLM). Use when someone wants to detect arbitrary text-described classes without training ("find the forklifts", custom vocabulary), click-to-segment / box-to-mask, segment-everything, open-set classification, or asks which zero-shot model to pick. Covers choosing a tier, each tier's API and gotchas, extras to install, and honest guidance on speed/calibration. For the standard trained detectors see use-libreyolo.

The whole dance for landing code on LibreYOLO's dev branch: branch, commit, push to upstream, then hand the user a one-click compare URL that opens an empty PR form for them to submit (agents must not open the PR themselves), and once they have opened it, babysit the Greptile bot review until it is happy. Use whenever the user says "put this on dev", "push this to dev", "merge this to dev", "ship this", "open a PR for this", or hands over finished work on LibreYOLO/libreyolo. The user should never have to ask for the PR link; producing it is the task.

Signpost for benchmarking LibreYOLO models for visionanalysis.org. Use when someone wants to "benchmark for visionanalysis", produce a submission for the site, measure a model on COCO for publication, or add a hardware/runtime row to the site. The actual work lives in two OTHER repos; this skill orients you and hands off. It does not run benchmarks itself.

Prepare and upload a LibreYOLO dataset repo to the HuggingFace LibreYOLO org. Use when publishing a training/eval/smoke dataset (detection, segmentation, OBB, pose, semantic, depth, restore, or classification). Covers the redistribution license gate, rebuilding from clean upstreams, the LibreYOLO format for each task, the dataset card, and how to wire auto-download.

Export LibreYOLO models for Hailo accelerators (Hailo-8/8L, Raspberry Pi AI Kit/AI HAT+). Use when a user asks to run LibreYOLO on Hailo, compile to HEF, or asks whether a given model family can be deployed on Hailo. Covers the "will it compile?" architectural rule (most families cannot), the ONNX-then-DFC two-stage flow, end nodes, calibration, and toolchain blockers.

Launch a one-off / batch GPU job (training, evaluation, export, benchmarking) on a rented or serverless GPU when you don't have a local one — or need a bigger/faster card than you have. Covers three providers: Vast.ai (cheap marketplace GPUs you rent + tear down; fully automated here via a helper CLI), Modal (managed serverless, per-second, auto scale-to-zero — what LibreYOLO's own nightly e2e runs on), and Beam (managed serverless, simple decorator). Use whenever someone wants to "run this on a cloud GPU", "train on a rented GPU", "spin up a GPU for a job", "launch on Vast/Modal/Beam", or check what's still billing. NOT for standing inference endpoints / autoscaling serving — this is for batch jobs that start, do work, and stop.

Delegate work to OpenAI's Codex from inside Claude Code — a generic task (implement a feature, investigate a bug, refactor) or a code review as a cross-model second opinion. Trigger ONLY when the user explicitly names Codex — e.g. "use codex to implement this", "have codex fix this", "delegate this to codex", "review this with codex", "codex adversarial review", "set up codex". Do NOT trigger on a plain "implement…" / "fix…" / "review…" with no mention of codex — those are Claude's own job (reviews go to the built-in /code-review). Also covers installing/setting up Codex.

Diagnose and fix slow LibreYOLO with the `libreyolo profile` CLI — both TRAINING throughput (`profile run`) and INFERENCE latency (`profile infer`). Use whenever training feels slow, GPU utilization is low, images/sec is disappointing, inference/predict latency is too high, a run is dataloader- / host-launch- / NMS- / preprocess-bound, or someone wants to optimize step time, batch size, throughput, or p50/p90/p99 latency. Teaches the profile → diagnose → change → compare loop an agent runs to push speed to the max. This is for SPEED, not accuracy (mAP).

Legacy guide for adding a detection model to LibreYOLO before the explicit task-paradigm refactor. Covers both YOLO-grid families (YOLOX, YOLOv9, YOLO-NAS) and DETR-style families (RF-DETR, D-FINE; future RT-DETR), but should be treated as pre-task-architecture guidance.