Docs
Docs pages

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
ArgumentWhat it does
videoPath to a video file.
bundleRelease bundle directory. Default: $VITALS_BIO_BUNDLE.
previewParts to opt in to although their test did not pass, e.g. ["forecast"]. Their output is marked PREVIEW in model.components.
speciesAs in the API. None detects any animal.
galleryA gallery .npz of known animals, for identity_id. Needs identity on, or preview=["identity"].
max_seconds, start_s, step_sAs in the API.
device, threadsTorch 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

AnalyzeResultDataclasses: 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_VERSIONThe 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