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/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

• 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: docker login nvcr.io and re-export the key before retrying.
• 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 via docker compose down.

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.
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.
5. Optional config / calibration files on disk if the user is bringing their own.

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.