SDK and model
Python SDK: vitals-bio 1.0.0
The model as a Python package that runs on your own machine, plus the command line, a local HTTP server and a CPU Docker image. The result is the same JSON as the hosted API.
The wheel is not on PyPI yet. Design partners get it from us with a release bundle (the weights). Nothing is downloaded at run time.
Install
pip install vitals_bio-1.0.0-py3-none-any.whl # torch, torchvision, OpenCV (headless), Ultralytics export VITALS_BIO_BUNDLE=/path/to/vitals-bio-1.0.0 # the release bundle vitals-bio info # bundle checksum; what is on, preview, off
Python 3.10 or later. A CPU is enough: about 0.1 to 0.4 s per sampled frame on a laptop, mostly detection.
vitals_bio.analyze
vitals_bio.analyze(video, *, bundle=None, preview=(), species=None, gallery=None,
max_seconds=None, start_s=0.0, step_s=0.2, device=None, threads=4) -> AnalyzeResult
| Argument | What it does |
|---|---|
video | Path to a video file. |
bundle | Release bundle directory. Default: $VITALS_BIO_BUNDLE. |
preview | Parts to opt in to although their test did not pass, e.g. ["forecast"]. Their output is marked PREVIEW in model.components. |
species | As in the API. None detects any animal. |
gallery | A gallery .npz of known animals, for identity_id. Needs identity on, or preview=["identity"]. |
max_seconds, start_s, step_s | As in the API. |
device, threads | Torch device ("cpu", "cuda", "mps") and CPU threads. |
import vitals_bio
r = vitals_bio.analyze("barn.mp4", species="cattle", max_seconds=20)
for a in r.animals:
last = a.frames[-1]
top = max(last.behaviour, key=last.behaviour.get)
print(a.identity.track_id, a.species, top, len(a.frames))
doc = r.to_dict()
assert vitals_bio.validate(doc) == []
Types and helpers
AnalyzeResult | Dataclasses: video, model, animals (identity, species, frames, state), embeddings, notes. .to_dict(), .to_json(). |
vitals_bio.from_dict(d) | Typed result from a saved file or an API response. |
vitals_bio.validate(d) | Structural check against the schema, no dependencies. Returns a list of problems. vitals_bio.schema.validate_strict uses jsonschema (pip install "vitals-bio[schema]"). |
vitals_bio.JSON_SCHEMA, SCHEMA_VERSION | The result schema and "biomodel-v0.1". |
vitals_bio.release(bundle=None) | The bundle's version, checksum and production config. |
vitals_bio.verify(bundle=None, full=True) | Re-hash the bundle against its manifest. |
Command line
vitals-bio analyze VIDEO [--species cattle] [--preview forecast] [--gallery herd.npz]
[--max-seconds 20] [--start-s 0] [--step-s 0.2] [--out result.json] [--pretty]
vitals-bio serve [--host 127.0.0.1] [--port 8765] [--root DIR] [--preview ...]
vitals-bio schema > biomodel-v0.1.schema.json
vitals-bio info [--json]
vitals-bio verify [--fast]
Local server
vitals-bio serve answers POST /v0/analyze (JSON: video_b64, or video as a path under --root), GET /v0/schema, /v0/health and /v0/release. It has no authentication, so it binds 127.0.0.1. The hosted /v1/analyze is this server behind our keys, limits and metering.
Docker
docker run --rm -p 127.0.0.1:8765:8765 \ -v /path/to/vitals-bio-1.0.0:/opt/vitals-bio/bundle:ro \ -v "$PWD/videos":/data:ro vitals-bio:1.0.0 curl -s 127.0.0.1:8765/v0/release
A CPU image; the bundle is mounted read-only. Built locally from deploy/vitals-bio/; not on a public registry.
Licences
- The detector is Ultralytics YOLO11 (AGPL-3.0). A closed product, or a network service, built on the SDK needs an Ultralytics licence or another detector.
- AP-10K, the main set for body points, licenses its labels CC BY 4.0, but its pictures come from third-party sources.