Vss Setup Behavior Analytics

Purpose

Deploy the behavior-analytics service standalone with the user's chosen entrypoint, config, and calibration.

Instructions

Follow the routing tables and step-by-step workflows below. Each section that ends in workflow, quick start, or flow is intended to be executed top-to-bottom. Detailed reference material lives in references/.

Examples

Worked end-to-end examples are kept under evals/ (each *.json manifest contains a runnable scenario). Run a Tier-3 evaluation to replay them:

nv-base validate skills/deployment/vss-setup-behavior-analytics --agent-eval

A minimal standalone bring-up looks like:

cd $REPO/deploy/docker
export VSS_APPS_DIR=$(pwd)
docker compose -f services/analytics/behavior-analytics/compose.yml up -d vss-behavior-analytics-base

Follow references/deploy-behavior-analytics-service.md for the full workflow (entrypoint pick, config source, dynamic updates).

Limitations

• No HTTP API. This is a broker stream processor — it reads and writes Kafka / Redis Streams / MQTT and serves no REST endpoint, so there is nothing to curl and no /health to probe. Verify it through container logs and the output topics.
• CPU-only. It loads no models and reserves no GPU (gpu_count: 0 in this skill's own evals), so GPU memory and NIM rate-limits are not constraints here.
• At least one processor must be enabled, and forgetting is quiet. With every numWorkersFor* at 0 the runner logs FATAL - Error in app: No processors registered, closes its listeners and returns — the process exits 0, so to anything watching exit codes it looks like a clean shutdown. Only the log distinguishes it.
• A destination the config omits is a disabled output, not an error. The sink logs No destination configured for '<key>'; output for it is disabled once per key and drops the rest, so a missing topic looks like an empty stream rather than a failure.
• One behavior producer per deployment. Two instances producing behaviors for the same sensors write every behavior twice, from processes with independent state. Nothing detects this.

Troubleshooting

• Error: container restart-loops immediately; log shows FATAL - Config file ... contains invalid JSON or ... has invalid structure. Cause: the mounted config is malformed or fails AppConfig validation. Solution: fix the JSON / schema — the app calls exit(1), so compose's restart policy cycles it forever.
• Error: container exits almost immediately with status Exited (0) and the log ends in FATAL - Error in app: No processors registered in app .... Cause: every numWorkersFor* is 0 (the shipped composite_config.json ships this way on purpose). Solution: set the worker count for the capabilities you want. Note the exit code is 0, so a restart: on-failure policy will not cycle it — it just stays stopped.
• Error: container shows Restarting (N) and the log ends in a Kafka/Redis connection error. Cause: no broker reachable. The client retries a bounded number of times, then the worker raises and the scheduler shuts the whole app down. Solution: bring up the broker, or expect the restart loop until one exists.
• Error: an expected topic stays empty. Cause: either the destination is not defined in the config (look for the one-time No destination configured warning) or the processor that writes it has 0 workers. Solution: define the topic and set the worker count.
• Error: log shows Error reading calibration type from ...: defaulting to IMAGE. Cause: --calibration was omitted or unreadable. Solution: this is not fatal — the app runs image-calibrated, which silently changes coordinate semantics. Mount a calibration if you meant a cartesian or geo deployment.

VSS Setup Behavior Analytics — Standalone

Deploy just the vss-behavior-analytics container (the spatial-AI analytics pipeline from the upstream behavior-analytics repo), not as part of the full warehouse blueprint stack.

The full operational walkthrough — entrypoint table, config-source options, calibration types, dynamic-update wire contract, troubleshooting — is references/deploy-behavior-analytics-service.md. This SKILL.md only handles routing and prerequisites.

When to use

• "Deploy behavior analytics" / "run behavior-analytics standalone"
• "I just want to run analytics, not the full stack"
• "Change the entrypoint to search_and_alerts / analytics 3D / mv3dt"
• "Use my own behavior-analytics config / calibration JSON"
• "Point behavior-analytics at the warehouse-3d (or mv3dt) config without spinning up the rest of the warehouse profile"
• "Dynamic config / dynamic calibration into a running behavior-analytics"

When NOT to use

This skill deploys one container. Hand off instead when the request is:

• The full stack (UI, agent, perception, storage) — vss-build-vision-ai. Do not run both in parallel; it owns behavior-analytics as part of the profile.
• Producing the frames this service consumes — detection/tracking is upstream: vss-deploy-detection-tracking-2d or -3d. This service analyses mdx-raw; it does not create it.
• Generating a calibration file — vss-generate-video-calibration. This skill only mounts one.
• Reading the output — incidents, metrics and sensor queries are vss-query-analytics; alert workflows and verification verdicts are vss-manage-alerts.
• The REST API in front of the data — that is a different service: vss-setup-video-analytics-api. Behavior-analytics itself exposes no HTTP endpoint.