The event bus¶
Domain events¶
opennvr.events.<domain>.<event>.v<N>.<camera_id> — versioned in the
subject, so a v2 can run beside v1 during a migration and every
subscriber picks explicitly. The envelopes are normative and
CI-enforced:
EVENT_CONTRACTS.md.
From a facade rule, publishing is one call — the envelope, the producer
(app:<id>), the camera and the correlation id are already known:
app.publishes("occupancy.changed.v1") # so it appears in the spec
@app.on_detection("person")
def count(event):
event.publish("occupancy.changed.v1",
{"count": event.count("person"), "level": "normal"})
Underneath, and from a base class, it is DomainEventPublisher. Publish
the typed payload where you can, not a dict: the class carries the
contract's required fields, so a malformed event fails at publish time
rather than in someone else's app.
def publish_a_plate(publisher: DomainEventPublisher, camera_id: str) -> None:
"""The typed route — preferred. The payload class carries the
contract's required fields, so this cannot publish a malformed
event; the subject and envelope are derived for you."""
publisher.publish_typed(
PlateRecognized(
plate_text="MH12AB1234",
confidence=0.94,
vehicle_label="car",
observed_at="2026-09-10T08:15:00Z",
),
camera_id=camera_id,
correlation_id="corr-abc123", # thread it, never mint a new one
)
Consuming is the mirror image — name the schemas, not the subjects:
class Gate(DomainEventSubscriber):
subscriptions = ["plate.recognized.v1"]
def on_event(self, event):
plate = event.typed # -> PlateRecognized | None
Scopes¶
Some domain events carry PII. A plate read is one. Consuming those is a
declared capability: name it in requires_scopes, and it is granted
at install, audited, visible in the App Catalog, and published in your
app's AsyncAPI document. Without the scope the bus does
not deliver the event.
requires_scopes=["events:plate.recognized"]
Alerts¶
An alert is for a human; a domain event is for another app. The alert subject mirrors the alert's own source block, so subscribers filter without parsing the body:
opennvr.alerts.> every alert
opennvr.alerts.app.> every app-emitted alert
opennvr.alerts.*.*.cam-front-door one camera
opennvr.alerts.app.loitering.> one app
Prefer opennvr.alerts.app.> over opennvr.alerts.app.*.*: > matches
one or more tokens, so it survives a future contract revision that adds
a fifth segment.
Tier-0¶
The always-on detector. snapshot_from_event reduces a Tier-0 payload
to what apps ask of it — counts per label, a speakable phrase, and which
tracks have a fetchable best frame. Or set consume_tier0 = True on a
Detector and Tier-0 tracks arrive as ordinary detections, so one rule
serves both sources.
It is off by default on purpose: an app also subscribed to a heavy adapter would otherwise see the same object twice and alert twice.
Full examples:
05_domain_event_subscriber.py,
12_domain_event_publisher.py,
11_tier0.py.
Asking the store, and "not yet"¶
EventsClient.search(label=…, attrs=["blue"], start=…, end=…) returns the
visits the store can vouch for, newest first — [] for a genuinely empty
window, None when the question could not be asked (say those apart to
the user: "nothing came" and "I couldn't check" are different answers).
Search matches what a skill said about a visit — attrs=["blue"] —
not only what the detector classified. Those claims are written after the
fact, by enrichers that run when the box can afford them; so some of the
visits your window matches may not carry the claim yet. Core answers
from what exists and queues the rest for description now, and the list it
returns says so:
visits = await events.search(label="car", attrs=["blue"], start=since)
if visits is None:
return "I couldn't check the history."
if visits.pending and visits.pending["missing"]:
p = visits.pending
note = (f" {p['missing']} visits in that window haven't been described"
f" yet — about {round(p['eta_s'])} s; ask me again then.")
visits is still a list (an app built against the list contract keeps
working); .pending is None when nothing was needed, and the same block
is mirrored on events.last_pending for code that holds the client rather
than the rows. The enrichment_request_done system alert on the bus
announces when the request finished, if you would rather re-ask than wait.
Operators bound the work with EVENTS_ENRICHMENT_REQUEST_CAP; see
docs/ENRICHMENT.md.