livepeer-modules-object-detection-rf-detr-runner

Workload binary that serves a custom object-detection HTTP endpoint to the Livepeer capability broker, backed by RF-DETR. One Docker image per capability; one process per broker-dispatched container. Follows the same harness and packaging conventions as the sibling livepeer-modules-object-detection-runner (Ultralytics YOLO) repo, but uses a permissively-licensed (Apache-2.0) detector.

For agents: start at AGENTS.md.

What this repo ships

Image	Language	Capability
rf-detr-objdetect-runner	Python	object-detection (RF-DETR; image + video)

One shared base image underpins the runner:

• cuda13-python-base — Python 3.13 + uv on nvidia/cuda:13.2.1-runtime-ubuntu24.04.

Weights resolve from MODEL_DIR if present, otherwise the runner auto-downloads them on first model load — there is no separate downloader image.

Build

Per CORE-BELIEFS.md: every gesture is Docker-first.

./build-images.sh build                          # build all images (bases first)
./build-images.sh build rf-detr-objdetect-runner  # build a single image
./build-images.sh validate                       # validate every compose overlay
./build-images.sh push                            # push all to ${REGISTRY} (requires docker login)
./build-images.sh clean                           # remove locally-built images
./build-images.sh help                            # show all subcommands

No host Python required.

Quick start

# 1. Build the images (the base builds automatically as a dep).
./build-images.sh build

# 2. Run the runner (weights auto-download on first load if not already cached).
docker compose -f infra/compose/docker-compose.rf-detr-objdetect-runner.yml up

# 3. Detect objects in an image.
curl -s http://localhost:8086/v1/detections \
  -H 'Content-Type: application/json' \
  -d '{"image": "https://media.roboflow.com/dog.jpg", "conf_threshold": 0.5}' | jq

For offline / no-egress hosts, pre-stage weights into the ai-detection-models volume before starting the runner (see RUNNERS.md).

Repo layout

.
├── AGENTS.md, CLAUDE.md            # agent map (+ 1-liner pointer)
├── README.md, LICENSE, NOTICE, CHANGELOG.md
├── ARCHITECTURE.md, DESIGN.md, PLANS.md, PRODUCT_SENSE.md
├── QUALITY_SCORE.md, RELIABILITY.md, SECURITY.md
├── CORE-BELIEFS.md, BROKER-CONTRACT.md, TRUST-MODEL.md
├── CANONICAL-CAPABILITIES.md, SHARED-BASE-IMAGES.md, RUNNER-INVARIANTS.md
├── RUNNERS.md                      # per-runner sections (READMEs + runbooks)
├── build-images.sh
├── infra/
│   ├── compose/        # docker-compose overlay
│   ├── offerings/      # offering.yaml manifest
│   ├── env/            # .env.example template
│   └── dockerfiles/    # 2 Dockerfiles, all build context = repo root
├── rf-detr-objdetect-runner/        # Python source
├── docs/references/                # External material (point-in-time)
└── .github/workflows/              # CI: build, release, doc-gardening

Configuration

The runner accepts common env vars (CAPABILITY_NAME, DEVICE, METRICS_ENABLED) plus per-capability keys. See RUNNERS.md for the full list, and infra/env/ for a copy-able .env.example template.

License

Apache-2.0 — see LICENSE and NOTICE.

This runner serves RF-DETR, which is Apache-2.0 licensed. Unlike the sibling Ultralytics-YOLO runner (AGPL-3.0), there is no copyleft and no AGPL §13 network-use source-offer obligation here — operators may run and modify it under the permissive Apache terms. The shipped model variants (Nano/Small/Medium/Large) and their weights are Apache-2.0.

⚠️ The RF-DETR XLarge / 2XLarge variants require the separate rfdetr_plus package and are licensed under PML 1.0, not Apache-2.0. They are not shipped by default; review the PML 1.0 terms before enabling them.