horos 0.1.1.dev1

horos (ὅρος — boundary, definition) is the path that takes a detection model into production: one tool that carries a dataset from raw images through annotation, training, and evaluation to a deployable artifact — with a web UI, a Python API, and a CLI that share one capability set.

Quickstart · Web UI · Models · Platforms · Installation · Roadmap

Quickstart

Install (details & Jetson notes below):

pip install horos
horos doctor        # verifies the environment; --fix installs what's missing

Run the whole pipeline from the terminal:

horos init my-project                   # new project directory
horos import my-project path/to/data    # COCO / YOLO / VOC / Darknet / VIA, dir or zip
horos ui my-project                     # web UI: dataset, annotate, train, evaluate

Or from Python — every UI action has a scriptable twin:

import horos.api as api

project = api.open_project("my-project")
record = api.start_training(project, api.TrainRunConfig(model="rfdetr-small"))
# ... poll api.training_status(project, record.run_id) ...
report = api.get_eval_report(project, record.run_id, "test")

Web UI

horos ui <project> serves four pages on localhost.

Dataset

Import by dropping a zip (COCO / YOLO / VOC / Darknet / VIA — format is auto-detected), get a validation report with actionable errors, per-class statistics, and train/valid/test re-splitting.

Annotate

A keyboard-first canvas for boxes and polygons. OWLv2 turns text prompts into zero-shot pre-labels, so annotators start from correcting instead of from a blank image — with an accept / fix / reject review flow, and safe concurrent annotation for teams.

Train

One click to start: hyperparameters are derived from your dataset's statistics with the reasoning shown, and every value can be overridden. Live loss/mAP curves, a run queue with in-place editing, resume with full optimizer state, OOM auto-backoff, a selectable best-checkpoint criterion, and a post-run verdict with concrete suggestions.

Evaluate

Drop photos, GIFs, or videos onto a trained model and browse per-frame predictions in a gallery viewer (confidence slider, frame-by-frame navigation). COCO metrics with per-class AP and PR curves, persisted per run.

Models

All registered weights are Apache-2.0. Nothing is bundled — weights download on first use and cache locally.

Detection (trainable)

Annotation assistants (not for deployment)

RF-DETR XL/2XL are deliberately unregistered: their weights are not Apache-2.0 (PML 1.0). Loading them requires an explicit acknowledge_non_apache=True.

Platform support

Unsupported combinations raise a clear error at the API layer and show up as disabled buttons with an explanation in the UI — never a silent CPU fallback. Device priority: CUDA → MPS → CPU, recorded in each run's metadata.

Installation

The install scripts detect your platform (OS, NVIDIA GPU, Jetson) and install the matching torch build plus horos into ./.venv:

./install.sh        # Ubuntu / macOS / Jetson
install.bat         # Windows

Use a dedicated environment. horos pins rfdetr exactly (upstream has had silent annotation-corruption bugs; reproducibility wins) and requires transformers >= 5.1 — installing into a shared ML environment will upgrade transformers, supervision, huggingface-hub and friends, which can break other projects living in that environment.

Jetson (read this — it matters)

On Jetson, torch must come from NVIDIA's JetPack-matched wheel. The PyPI torch has no CUDA support on Jetson, and a plain pip install horos may silently replace your CUDA-enabled torch with a CPU-only build — everything still runs, just an order of magnitude slower.

./install.sh handles this automatically on Jetson: it creates the venv with --system-site-packages, verifies the existing torch has CUDA (warning loudly if not), and installs horos with --no-deps so pip can never swap torch out. horos also warns at backend load time when it detects a Jetson platform where torch.cuda.is_available() is False.

pip install horos --no-deps
pip install pydantic flask pyyaml pillow imageio imageio-ffmpeg "transformers>=5.1,<6"
# torch/torchvision: use the NVIDIA wheel matching your JetPack version — FIRST,
# because the training stack below declares torch as a dependency
pip install "rfdetr==1.9.4" --no-deps
pip install supervision pycocotools scipy peft \
    "pytorch_lightning>=2.6,!=2.6.2,!=2.6.3,<3" \
    "torchmetrics[detection]>=1.2" "faster-coco-eval>=1.7.2"

Roadmap

• Project & dataset core — formats, validation, stats, splits
• Manual annotation — bbox + polygon, multi-annotator
• Auto-labeling — OWLv2 open-vocabulary, review workflow
• Training — derived hyperparameters, queue, resume, live monitoring
• Evaluation — media gallery, COCO metrics, per-class analysis
• Error analysis — confusion pairs, worst-case mining
• Experiment management — run comparison, dataset fingerprints
• Export & deploy — ONNX / TensorRT / TFLite, model cards, parity checks

Development

python -m venv .venv && . .venv/bin/activate
pip install -e . --no-deps
pip install pydantic flask pyyaml pillow imageio pytest ruff
pytest tests/test_invariants.py && pytest

tests/test_invariants.py runs first for a reason: it statically enforces the architecture — model dependencies live only in horos/backends/, import horos never drags in torch, and the UI talks to the core exclusively through the web API. Models are adapters; the workflow is the product.

License

Distributed under the Apache License 2.0. Model weights are downloaded at runtime and cached locally — horos never bundles or redistributes them, and each model's license is recorded in the registry, shown in the UI, and stamped into every training run.

Acknowledgments

RF-DETR by Roboflow · OWLv2 by Google Research · Segment Anything by Meta AI