Documentation

AI Adapters Engine Overview

OpenNVR is built for the AI era. Instead of locking enterprises into proprietary analytics or exorbitant cloud pricing models, OpenNVR utilizes a stateless microservice architecture that entirely decouples continuous video recording from AI inference. We call this orchestration layer AI Adapters.

This decoupled architecture gives you:

Sovereignty by default: Your raw video streams never leave the NVR unless an administrator explicitly opens an outbound route.
Scales with your hardware: Because each adapter runs in its own container, you can run one on an edge CPU or spread many across a GPU cluster — without ever dropping a recorded frame on the primary NVR.
Instant modularity: Swap model pipelines without recompiling the NVR. To replace one detector with another — say, a stock YOLOv8 for a model you’ve fine-tuned — you just point the adapter at the new weights and restart the container.

How the Pipeline Works

Within the AI-adapters/ directory, OpenNVR supplies distinct, containerized AI listeners. They sit securely on the internal NVR Docker bridge and await inference routing requests from the core API.

When the OpenNVR engine detects a matching policy, it streams a raw visual frame across the bridge. The Adapter processes the frame using ONNX/PyTorch/TensorFlow, and returns highly-structured metadata (JSON bounding boxes, face arrays, timestamp matrices) back to the OpenNVR PostgreSQL Database for permanent retention.

Executing the Orchestrator (Docker)

Option A: Integrated NVR Core (Recommended)

The core stack already ships with the YOLOv8 adapter enabled in docker-compose.yml — nothing to configure for object detection out of the box. Additional example detector apps (intrusion, loitering, LPR, …) come via the apps overlay, which keeps them on the internal Docker network with no external interfaces exposed:

docker compose -f docker-compose.yml \
               -f docker-compose.apps.yml \
               --profile apps up -d

Because the containers share the internal Docker network, KAI-C discovers and registers your local adapter instances automatically.

Option B: Scaled Network Isolation

If your organization runs designated GPU nodes independent of the storage NVR, deploy an adapter standalone from the sibling ai-adapter repo and register its URL with KAI-C:

git clone https://github.com/open-nvr/ai-adapter.git
cd ai-adapter
uv sync --extra all --extra cpu   # or --extra gpu
uv run uvicorn app.main:app --host 0.0.0.0 --port 9100

The adapter exposes its contract API at http://[YOUR_GPU_HOST_IP]:9100; point KAI-C at it via ADAPTER_URL.

☁️ Integrating Cloud Tensor Pools (Hugging Face)

If your specific security requirements permit, OpenNVR allows you to seamlessly map massive Cloud Models (VLMs, Zero-Shot implementations) via Hugging Face.

Method 1: GUI Secret Injection (Recommended)

This method ensures your token is encrypted within the NVR database and only attached to proxy requests dynamically.

Generate a strict Read-Only endpoint token from your Hugging Face Security Settings.
Within the OpenNVR Dashboard, navigate to Cloud Models / BYOM.
Select Provider: Hugging Face.
Inject your API key and Save.

Method 2: Infrastructure as Code (IaC)

If you manage your NVR fleet via Terraform or Ansible, you can inject the token directly into the container’s environment variables.

services:
   ai-adapters:
      environment:
         - HF_TOKEN=hf_your_generated_token_here

👩‍💻 Local Developer Blueprint (No Docker)

If you are developing proprietary models and need to debug inference without containerization:

Prerequisites

Python 3.11+
uv (Python package manager - install guide)

Local Setup

Activate your Virtual Environment
```
uv venv venv
source venv/bin/activate
```
Hydrate Dependencies
```
cd AI-adapters/AIAdapters
uv sync
```
Fetch Essential Tensor Weights Pre-fetches essential weights (e.g., YOLO variants) into the local /model_weights directory:
```
python download_models.py
```
Ignite the Inference Server
```
uvicorn adapter.main:app --reload --port 9100
```
The logging subsystem will report successfully establishing the API and discovering your local inference plugins.

Observability Built In

Every adapter’s /metrics (Prometheus format) is scraped by KAI-C on its registry poll and served back as a decision dashboard on the AI Adapters page — latency percentiles, outcomes, saturation, optional hardware gauges, fingerprint drift, and hour-scale trends, plus a fleet-wide summary strip. See System Monitoring for the operator view.