livepeer-modules-object-detection-runner

Workload binary that serves a custom object-detection HTTP endpoint to the Livepeer capability broker. One Docker image per capability; one process per broker-dispatched container. Follows the same harness and packaging conventions as the sibling livepeer-modules-openai-runners repo.

For agents: start at AGENTS.md.

What this repo ships

Image	Language	Capability
yolov12-objdetect-runner	Python	object-detection (Ultralytics YOLO; 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 yolov12-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.yolov12-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://ultralytics.com/images/bus.jpg", "conf_threshold": 0.25}' | 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, 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
├── yolov12-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

AGPL-3.0-or-later — see LICENSE and NOTICE.

This runner links the Ultralytics library and serves YOLO weights, both AGPL-3.0, so the combined work is AGPL-3.0. Because it runs as a network service, anyone interacting with it remotely is entitled to the corresponding source (AGPL §13); the runner advertises its source location in GET /object-detection/options (extra.source_url) and the org.opencontainers.image.source image label. To use it under different terms, replace Ultralytics + the weights with a permissively-licensed detector, or obtain an Ultralytics Enterprise License.