Your first adapter
Wrap any model as an OpenNVR AI adapter with the Apache-2.0 SDK: about thirty lines of Python, run and test it on its own, then plug it into KAI-C so every app that needs its task can use it.
On this page
An adapter is how a model becomes part of OpenNVR. Wrap your model once, and every app that asks for the task it serves can use it — the catalog apps, your own apps and the camera agent — with no change to any of them. The SDK is Apache-2.0, so your adapter can ship under any licence, proprietary or classified included.
You need Python 3.11+,
uvorpip, and a model you can call from Python. A running OpenNVR stack is only needed for step 4.
1. Install the SDK
uv add opennvr-adapter-sdk # in a uv project
pip install opennvr-adapter-sdk # or with pip
2. Wrap your model (about 30 lines)
from opennvr_adapter_sdk import (
AdapterApp, AdapterService, BodyShape, BODY_BYTES_KEY,
HardwareEvaluationResponse, HardwareVerdict,
InferResponse, ModelInfo,
)
class FallDetector(AdapterService):
def load(self): # load your weights once, at startup
...
def is_ready(self) -> bool:
return True
def fingerprint(self) -> str | None: # sha256 of the weights on disk
return "sha256:..."
def model_info(self) -> ModelInfo:
return ModelInfo(name="fall-detector", version="1.0.0",
framework="onnx", fingerprint=self.fingerprint())
def hardware_evaluation(self) -> HardwareEvaluationResponse:
return HardwareEvaluationResponse(verdict=HardwareVerdict.OK, details="")
def infer(self, payload) -> InferResponse:
frame_bytes = payload[BODY_BYTES_KEY]
# ... run your model on the frame ...
return InferResponse(result={"detections": [
{"label": "person_fallen", "confidence": 0.91, "bbox": [10, 20, 100, 200]},
]})
app = AdapterApp(
service=FallDetector(),
name="fall-detector", version="1.0.0", vendor="you", license="MIT",
tasks_advertised=["object_detection"],
body_shape=BodyShape.IMAGE,
).fastapi_app
That is a complete, contract-compliant adapter. The SDK supplies /health, /capabilities, /hardware/evaluation, /metrics and /infer, authentication, correlation IDs, multipart and JSON parsing, and the error envelope. You write the model wrapper.
Pick the task with care. An app asks for a task, never for an adapter by name, so tasks_advertised is how apps find you. Advertise a task apps already ask for — object_detection, license_plate_recognition, scene_caption, visual_qa and the others in the adapters that ship — or your adapter installs, reports healthy and receives no work.
Declare permissions honestly. An adapter that asks for nothing (no GPU, no network, no host paths) is approved the moment it registers. Anything you declare waits for an operator to grant it, and under the default local_only policy an adapter that declares network access is refused outright. The adapter SDK guide explains the rules.
3. Run it and check it on its own
uv run uvicorn fall_detector:app --port 9100
In another terminal:
curl -s localhost:9100/health
curl -s localhost:9100/capabilities
curl -s -F frame=@test.jpg -F 'params={"task":"object_detection"}' localhost:9100/infer
/capabilities is the card KAI-C reads to decide what your adapter is and what it may touch; /infer with a real image should return your detections.
4. Plug it into OpenNVR
KAI-C, OpenNVR’s AI middleware, registers adapters by URL: POST /api/v1/adapters/register with the adapter’s name and URL, from inside the stack’s network. On registration it reads /capabilities, checks your declared permissions against the site’s policy, fingerprints the weights, and from then on routes every request for your task to you, audited. KAI-C middleware lists the endpoints; the stack’s own compose files register the caption adapter this way, which is a working example to copy.
Run your adapter as a container on the stack’s network so KAI-C can reach it. KAI-C re-reads /capabilities every minute: a changed fingerprint is written to the audit log, and a newly declared permission stops the adapter until an operator approves it again.
Start from a template instead
The ai-adapter repository has a scaffold that generates a complete adapter project — service, Dockerfile, tests — and the shipped adapters to copy from:
git clone https://github.com/open-nvr/ai-adapter.git && cd ai-adapter
./templates/adapter-template/scaffold.sh fall-detection 9008 IMAGE
adapters/yolov8/ is the reference for images, adapters/whisper/ for audio, adapters/piper/ for text and adapters/bytetrack/ for a post-processor over another adapter’s output.
From the command line, with SDK 1.3.0:
pip install -U opennvr-adapter-sdkgives youopennvr-adapter.opennvr-adapter new fall-detectionscaffolds a project,devloads it and drives its endpoints with no stack,validateruns the conformance suite in-process,conformruns it against a running adapter, andlistingprints the catalog entry that makes it installable.
Get it listed
To make your adapter one click for every deployment, publish its image and open a pull request adding one entry to the adapters index. CONTRIBUTING_ADAPTERS.md walks through it. Listing is optional: an adapter you register yourself works the same.
Next
- Your first app — write a rule that uses your model
- The AI adapter model — how adapters, tasks and KAI-C fit
- Adapters we’d like next