Skip to main content

opennvr-app-sdk

The SDK for building vision apps on OpenNVR, the self-hosted AI video platform. Cameras, Tier-0 detections, pluggable inference, an event bus, recordings, an operator alert inbox, users and per-camera permissions, and a catalog every deployment opens — all already running. You write the rule, the model or the workflow; this package is the only import you need.

Apache-2.0 — ship your app under any licence, closed included, with no fee to OpenNVR. Why that holds even though the platform core is AGPL: LICENSING.md.

pip install opennvr-app-sdk

An app in one function

from opennvr_app_sdk import App

app = App("loitering", name="Loitering", version="1.0.0", category="perimeter")
app.param("dwell_s", float, default=30.0)
app.metric("alerted", label="Alerts fired")

@app.on_detection("person", zone="driveway", dwell="$dwell_s")
def loitering(event):
    event.alert(f"Person loitering on {event.camera}", severity="high")
    app.store["alerted"] = app.store.get("alerted", 0) + 1

if __name__ == "__main__":
    raise SystemExit(app.run())

That app subscribes to the platform's detections, serves the registry contract (/health, /state, /manifest, config form, actions), registers itself in the App Catalog, is issued its own credential, and fires alerts that reach the operator inbox — none of which you wrote. The zone becomes an editor named driveway that the operator draws on a camera still; dwell_s becomes a field in the config form they can tune; alerted becomes a tile on the app's dashboard. The presence timer, the once-per-episode latch, the alert envelope and the config file are the SDK's.

Declaring a surface implements it: @app.action adds an operator button, @app.ui an embedded page, @app.on_license the gate for a paid app, @app.state / app.metric a dashboard, and inside a rule event.publish() reaches other apps while event.nvr is the platform.

See it fire before you touch Docker:

opennvr-app new loitering        # a runnable app + tests
opennvr-app dev                  # run it against a simulated camera
opennvr-app validate .           # what a reviewer would check
opennvr-app spec                 # its OpenAPI 3.1 document

Try a workflow's AI step

Write a Look step as it goes in a workflow file (RFC #620) and run it on your own snapshots with a local model, before any workflow exists:

# gate.yml
mode: look
prompt: Someone is at the gate. Who are they?
decision: [delivery, cab, visitor]
fields: { company: [swiggy, zomato, amazon, other, none] }
opennvr-app ai try gate.yml snap1.jpg snap2.jpg --model qwen3-vl:2b-instruct

It prints each picture's decision, the facts, the rule that fired, the reason and the seconds, and says why when the answer is unsure. The step is checked and run by the same code the engine uses (opennvr_app_sdk.workflows). Pictures are shrunk to 768 px on the long side when Pillow is installed: on CPU a 1080p picture alone can use most of a step's 120 s. --input plate=KA01AB1234 passes an event value as data, --json prints the results for a script.

Your app self-describes: the contract server it gets for free serves OpenAPI 3.1 at /openapi.json and AsyncAPI 3.0 at /asyncapi.json, both generated from your manifest — a declared action is a path with a typed body, a declared param is a schema. Point Swagger UI or a client generator at a running app and it works.

The reference

opennvr.org/sdk — every export, in tiers, generated from these docstrings. Start at the front door: six names, and most apps need nothing else.

One example per class

cookbook/ is a runnable file per class — how it is constructed or subclassed, and which APIs it uses. Every file is imported and exercised by the test suite, so an example that references a name the SDK no longer exports breaks in CI rather than misleading you months later. Start at 01_app_facade.py.

…or the class underneath it

App compiles to a Detector. When a rule outgrows the decorators, write the Detector directly — same process, same manifest, same alerts:

from opennvr_app_sdk import Alert, AppManifest, Detector, Param, app

class Loitering(Detector):
    manifest = AppManifest(
        id="loitering", name="Loitering", version="1.0.0", category="perimeter",
        requires_tasks=["object_detection"],
        params=[Param("dwell_s", float, default=30.0)],
    )

    def setup(self):
        self.present = self.keyed_state(ttl=10.0)   # forgets a camera 10 s after the last person

    def on_detections(self, camera_id, detections, event):
        people = [d for d in detections if d.get("label") == "person"]
        if not people:
            return
        rec = self.present.touch(camera_id)
        if rec.age >= self.cfg.dwell_s and not rec.alerted:
            rec.alerted = True
            yield Alert(title="Loitering", description=f"{len(people)} person(s) for {rec.age:.0f}s",
                        camera_id=camera_id, severity="medium")

if __name__ == "__main__":
    raise SystemExit(app(Loitering).run())

FrameApp drives its own inference, AlertSubscriber consumes the alert bus and DomainEventSubscriber consumes contracted domain events — same shape, different input.

The platform, from an app

from opennvr_app_sdk import OpenNVR            # or opennvr_app_sdk.aio.AsyncOpenNVR

nvr = OpenNVR()                                 # OPENNVR_URL + the app's key
for cam in nvr.cameras():                       # only cameras assigned to this app
    jpeg = nvr.snapshot(cam)
    det = nvr.ai.infer("yolov8", jpeg, task="object_detection", camera_id=cam.handle)
nvr.state.set("last_seen", {"cam1": 12.5})      # durable, survives restarts
clips = nvr.recordings("cam1").list(start="2026-09-05T00:00:00Z")
mine = nvr.alerts.inbox(unacked=True)

Where to go next

Compatibility: the app-registry contract is versioned (api_version) and tested in the OpenNVR repository on every change; min_sdk_version only moves when an older SDK would misbehave. Issues tagged sdk at open-nvr/open-nvr.

Metadata

Release files for opennvr-app-sdk 0.13.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for opennvr-app-sdk 0.13.0
File Size Uploaded Provenance Actions
opennvr_app_sdk-0.13.0.tar.gz 317.4 kB With provenance Details for opennvr_app_sdk-0.13.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for opennvr-app-sdk 0.13.0
File Interpreter ABI Platform Actions
opennvr_app_sdk-0.13.0-py3-none-any.whl Python 3 none any Details for opennvr_app_sdk-0.13.0-py3-none-any.whl

Total release size: 573.2 kB

Release files / opennvr_app_sdk-0.13.0.tar.gz

Download URL opennvr_app_sdk-0.13.0.tar.gz
Size 317.4 kB
Tags Source
SHA-256 checksum
How to use checksums
43d6a39b7f769349d526a9cb9a0fdd3ea39ded48a19cc52d856502818e6bd88a
BLAKE2b-256 checksum
How to use checksums
c202a423eeb998d882a02d3af18d57f7a7dea57743ca373233cad59c41cc198e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / opennvr_app_sdk-0.13.0-py3-none-any.whl

Download URL opennvr_app_sdk-0.13.0-py3-none-any.whl
Size 255.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dc4ca79e6b131a3ed3d0af6e05737a69e751db29fff22e89f5ccb700a9ada748
BLAKE2b-256 checksum
How to use checksums
b18bf6ef02c4e1a1889044397104fd063c41d6c6b32fb52edce9e3d891f1c63f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for opennvr-app-sdk 0.13.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for opennvr_app_sdk-0.13.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page