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 as guidance to walk through with the user. Before any compose file edit, any docker compose up or down, or any broker publish, show the user the exact command or diff and get the user's explicit confirmation first. Scope any teardown to the behavior-analytics compose file and service. Detailed reference material lives in references/.

The skill needs only docker, docker compose, and optionally nv-base. Every shell command it suggests goes through the confirmation step above.

Examples

Worked end-to-end examples are kept under evals/ (each *.json manifest contains a runnable scenario). Replaying them is optional. Run a Tier-3 evaluation only when the user explicitly asks for it, from a pinned and reviewed checkout, after reviewing the manifest contents, and inside an isolated environment. Run nv-base only if it was installed from a trusted, verified source the operator controls; otherwise skip the eval.

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

A minimal standalone bring-up looks like the block below. Before running it, confirm the repo path is set and points at the pinned checkout, stop if the directory change fails, and confirm that services/analytics/behavior-analytics/compose.yml exists under $VSS_APPS_DIR and that the path holds no spaces. Get the user's confirmation before starting the container.

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

• Requires the matching VSS profile / microservice to be deployed and reachable from the caller.
• NGC-hosted models and NIMs may be subject to rate-limits, GPU memory requirements, and license restrictions.
• Concurrency, GPU memory, and storage limits depend on the host hardware and the profile's compose file.

Troubleshooting

• Error: REST call returns connection refused. Cause: target microservice not running. Solution: probe /docs or /health; redeploy via vss-deploy-profile or the matching vss-deploy-* skill.
• Error: HTTP 401/403 from NGC pulls. Cause: missing/expired NGC_CLI_API_KEY. Solution: set the key with a hidden prompt as described in references/ngc-api-key-registry-login.md, then log in with printf '%s' "$NGC_CLI_API_KEY" | docker login --username '$oauthtoken' --password-stdin nvcr.io before retrying. Prefer a docker credential helper over plain text Docker config, and keep the key out of logs, output, and command arguments.
• Error: container OOM or model fails to load. Cause: insufficient GPU memory for the selected profile. Solution: switch to a smaller variant, or free GPUs by stopping this service with docker compose -f services/analytics/behavior-analytics/compose.yml down once the user confirms. Ask the user before stopping any other container.

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 fusion_search / dev_example / 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"

Prerequisites

1. Repo checkout with $VSS_APPS_DIR pointing at <repo>/deploy/docker/. Required by the service compose's volume binds. The checkout should be at a pinned release tag or commit of the repository named in the metadata github-url.
2. NGC credentials — $NGC_CLI_API_KEY set so docker can pull the image. See references/ngc-api-key-registry-login.md.
3. Docker runtime — Docker Engine 28.3.3 with Docker Compose plugin v2.39.1+. Verify with docker --version and docker compose version.
4. Optional broker (Kafka / Redis Streams / MQTT). The container starts fine without one — the Kafka client retries a bounded number of times, then the app exits and restart: always cycles the container. Status will show Restarting (N) in docker ps until a broker is reachable. With a broker, dynamic config / dynamic calibration over mdx-notification become available. Any broker used for dynamic updates must require authentication and encrypted connections, and must be reachable only from the local host or a private network, kept off public networks. When no broker is planned, report the restart loop to the user and offer to override restart: to on-failure or no instead of leaving the loop running.
5. Optional config / calibration files on disk if the user is bringing their own. Validate a custom calibration against the vendored schema at behavior-analytics/src/mdx/analytics/core/transform/calibration/schemas/calibration.schema.json, and check a custom config against the shape in references/configuration.md, before mounting. Mount both read only where possible.
6. Pinned image — confirm the compose file pins the vss-behavior-analytics image to a specific release tag and content digest the operator has reviewed, and confirm the pulled digest matches the published value before starting. Use a fixed release rather than a floating or latest image.

If any required prerequisite fails, surface the gap before going further.

Workflow

Hand the user references/deploy-behavior-analytics-service.md and walk them through its steps in order:

1. Pick an entrypoint (analytics 2D / 3D / mv3dt, dev_example, fusion_search).
2. Choose a config — profile-shipped or custom.
3. Choose a calibration — optional; profile-shipped or custom; otherwise the app waits for a dynamic-calibration notification.
4. Decide whether a broker is reachable; if yes, point them at the dynamic-update flows.

The compose-file edits, YAML diffs, deploy + verify commands, and troubleshooting table all live in that reference — don't duplicate them here. Show each compose or YAML diff and each command to the user for approval before applying or running it.

Dynamic updates (runtime, no restart)

Once the container is up and a broker is reachable, two runtime-update flows are available — neither requires redeploying.

Use these flows only on a broker that requires authentication, uses encrypted connections, and restricts write access on the mdx-notification topic to approved producers. Get the operator's explicit confirmation before publishing any update, and back up the current config or calibration first so it can be rolled back.

Dynamic config

Publish an upsert (per-key patch) or upsert-all (full snapshot) message to the mdx-notification topic with Kafka key behavior-analytics-config and headers:

• event.type: upsert | upsert-all | request-config | ack
• reference-id: video-analytics-api-<uuid> (web-api originated), behavior-analytics-<uuid> (bootstrap reply), or the source-type literal (kafka / redis / mqtt) for direct-publisher upserts.

Body: {"status": ..., "config": <patch>, "error": ...}.

The listener validates each message at the envelope layer (rejects unknown keys, missing config, malformed status/error) and at the per-payload layer (rejects forbidden sections, bad item shapes). Successful upserts are persisted to disk, applied to every worker, and ACK'd back over the topic. Because every worker applies the change, confirm each upsert or upsert-all with the operator before publishing it.

Full wire contract + ack semantics: references/dynamic-config.md.

Dynamic calibration

Publish to the same topic with Kafka key calibration and headers:

• event.type: upsert-all (full snapshot) | upsert (per-sensor merge) | delete (per-sensor removal)
• timestamp: ISO-8601 UTC (YYYY-MM-DDTHH:MM:SS.fffZ).

Body: JSON sensor list (and ROIs / tripwires / homographies for upsert-all).

Calibration updates need the same authenticated, write-restricted broker. Get the operator's explicit confirmation before publishing upsert-all or delete, save the current calibration before each change, and check the container logs afterward. Schema validation checks the shape of a message, not who sent it.

The listener validates against the vendored AJV schema before persisting. Schema violations log a calibration schema violation warning and are dropped — the previously-good calibration stays loaded.

Full wire contract + per-action validation policy: references/dynamic-calibration.md.

Both flows live entirely on the broker — the producer can be video-analytics-api or another producer the operator has approved. They're the recommended way to change configuration after the container is running, so the operator doesn't have to redeploy.

Routing rules

• If the user wants "the full stack" (UI / agent / perception): hand off to vss-deploy-profile with profile warehouse (or alerts). Don't run this skill in parallel.
• If the user wants to publish a runtime config / calibration update to an already-running container: walk the Dynamic updates section. Both flows need a reachable, authenticated broker and operator confirmation.
• If the user describes a behavior-analytics behavior change they want to validate (new incident type, new ROI rule, new sensor): point them at references/configuration.md, references/dynamic-config.md, or references/dynamic-calibration.md before editing the JSON.