Vss Manage Alerts

Purpose

Operate the VSS alert pipeline (mode detection, Alert-Bridge subscriptions, Slack notifications, queries, camera onboarding, verifier-prompt customization).

Prerequisites

• Active VSS deployment reachable on $HOST_IP (see vss-deploy-profile and references/).
• NGC credentials in $NGC_CLI_API_KEY and $NVIDIA_API_KEY for any image pulls.
• curl, jq, and Docker available on the caller.

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/ and helper scripts live in scripts/ — call them via run_script when the skill points to a script by name.

Examples

Runnable end-to-end scenarios live under evals/ (each *.json manifest); inline curl blocks appear in each workflow below. Replay with nv-base validate <this-skill-dir> --agent-eval.

Limitations

Requires the matching VSS profile/microservice deployed and reachable. NGC-hosted models/NIMs are subject to rate-limits, GPU-memory needs, and license terms; concurrency and storage limits depend on host hardware and the profile's compose file.

Troubleshooting

• Connection refused → microservice not running: probe /docs or /health, redeploy via vss-deploy-profile.
• HTTP 401/403 on NGC pulls → missing/expired NGC_CLI_API_KEY: docker login nvcr.io and re-export the key.
• OOM / model load failure → insufficient GPU memory: use a smaller variant or docker compose down to free GPUs.

VSS Alert Management

The alerts profile runs in one of two modes (chosen at /vss-deploy-profile -p alerts -m {verification,real-time}) — see The Two Modes table below. This skill routes by deployed mode + user intent (monitoring vs subscription CRUD vs Slack webhook).

When to Use

• Start/stop a real-time alert on a sensor ("Start real-time alert for boxes dropped on warehouse_sample")
• Create/list/stop realtime subscription rules on Alert Bridge
• Set up or manage Slack incident notifications
• List or query detected incidents / alerts; check verdicts (confirmed/rejected/unverified)
• Add a new camera to the alerts pipeline; customize VLM-verifier prompts (CV mode)

Deployment prerequisite

Requires the VSS alerts profile on $HOST_IP in either verification (CV) or real-time (VLM) mode.

# Either vss-rtvi-cv (CV mode) OR vss-rtvi-vlm (VLM mode) must be present.
curl -sf --max-time 5 "http://${HOST_IP}:8000/docs" >/dev/null \
  && docker ps --format '{{.Names}}' \
     | grep -qE '^(vss-rtvi-cv|vss-rtvi-vlm)$'

If the probe fails, ask which mode to deploy and hand off to /vss-deploy-profile -p alerts -m <mode> (decline → stop; pre-authorized autonomous deploy → run directly with verification by default). If it passes, detect the mode per Step 1.

The Two Modes (Deploy-Time Choice)

Switching modes uses the vss-deploy-profile teardown + deploy flow with the other -m flag (VLM → CV adds the CV pipeline; CV → VLM tears it down). rtvi-vlm runs in both modes.

Step 1 — Detect the Currently Deployed Mode

Before running any alert workflow, check which mode is live. Use CV-only containers as the signal — vss-rtvi-vlm is not a reliable mode signal because it runs in both modes.

# CV verification mode (vss-behavior-analytics + vss-rtvi-cv are CV-only)
docker ps --format '{{.Names}}' | grep -qx vss-behavior-analytics && echo "mode=CV"

# VLM real-time mode (no CV pipeline; vss-rtvi-vlm still runs)
docker ps --format '{{.Names}}' | grep -qx vss-behavior-analytics || \
  docker ps --format '{{.Names}}' | grep -qx vss-rtvi-vlm && echo "mode=VLM"

If vss-behavior-analytics is present → CV mode (which also has vss-rtvi-vlm). If only vss-rtvi-vlm is present (and no CV pipeline) → VLM mode. If neither matches, the alerts profile is not deployed — direct the user to the vss-deploy-profile skill.

Alternative signal (preferred when docker ps isn't accessible): check the profile's generated.env:

grep -E '^MODE=' deploy/docker/developer-profiles/dev-profile-alerts/generated.env
# MODE=2d_cv   → CV mode (full superset)
# MODE=2d_vlm  → VLM real-time mode (vss-rtvi-vlm only; no vss-rtvi-cv)

Step 2 — Route by Deployed Mode

Always confirm before triggering a redeploy. A mode switch stops all currently-running monitoring and restarts services.

Intent precedence (first match wins)

1. Workflow E (Slack) — Slack-specific keywords (slack, webhook + slack, bot token, slack channel). notify alone is not sufficient.
2. Workflow D (Subscriptions) — sensor plus a detection condition, rule CRUD keywords (rule, subscription, rule ID), or stopping/deleting a named alert by type/condition ("stop the PPE alert", "delete the collision rule"). A named alert_type/condition = an existing rule → D's two-step stop protocol (GET /api/v1/realtime → yes/no confirm → delete), never Workflow B.
3. Workflow B (VLM monitoring) — generic start/stop on a sensor with no detection condition and no alert-type qualifier ("start/stop real-time alert for sensor X"). A stop that names a type ("stop the PPE alert") is a rule stop → Workflow D.
4. Workflow C (Query) — incident lookup / what happened (show/list incidents, recent alerts, time-range queries, and casual "any alerts…?" / "any alerts so far today?" / "what's been triggered?" phrasings). Bare alerts (without rule/subscription/active rules) means incidents → Workflow C, never Workflow D.
5. Workflow A (CV) — CV deployment handling for anything not matched above.

alerts vs alert rules (C vs D) — pick exactly one, never both: what happened / has been triggered (incidents) → Workflow C (POST /generate). What rules/subscriptions are configured or active → Workflow D (the bare GET /api/v1/realtime, no /incidents). Bare alerts = incidents (C); alert rules / subscriptions / active rules = inventory (D). Never answer from memory; run the one correct call — full endpoint detail in Workflow C below.

Disambiguation (B vs D): if a sensor is named with start/monitor language but the detection condition is unclear, ask:

"Do you want me to (a) create a persistent alert rule on Alert Bridge that keeps running until you delete it, or (b) start a one-time monitoring session via the VSS Agent?"

Stop routing (B vs D): "Stop the <type> alert" (names an alert_type/condition like PPE, collision, fire) = stop a subscription rule → Workflow D (find via GET /api/v1/realtime, then the two-step stop/confirm protocol in references/alert-subscriptions.md; do not call POST /generate). A bare "stop real-time alert / stop monitoring on <sensor>" with no type qualifier = Workflow B.

If a prompt mixes workflows ("start monitoring and send to Slack"), ask one clarifying question to split execution order.

CV-mode refusal text for D and E intents

When the deployed mode is CV verification and the user asks for an alert-subscription or Slack/notification intent, refuse with this message verbatim:

"Alert subscriptions and Slack notifications are only supported in VLM real-time mode. Your current deployment is <CV verification | not deployed>. To use these features, redeploy with /vss-deploy-profile -p alerts -m real-time (note: switching tears down current CV monitoring)."

No auto-redeploy. The user decides whether to switch modes.

Prereq for Either Mode: Sensor Must Be in VIOS

Both modes require the camera registered in VIOS first (via the vss-manage-video-io-storage skill):

• RTSP URL / IP camera → add it with POST /sensor/add (that skill's Section 6); record the sensorId / name.
• Named existing sensor → confirm it appears in GET /sensor/list before proceeding.

On CV, adding the RTSP is the entire onboarding step (pipeline auto-picks it up). On VLM, it is a prerequisite to Workflow B.

The Agent /generate Endpoint

All VLM-flow actions and all query actions go through the VSS Agent's natural-language endpoint:

AGENT="http://<AGENT_ENDPOINT>"   # default http://localhost:8000 on the alerts profile

curl -s -X POST "$AGENT/generate" \
  -H "Content-Type: application/json" \
  -d '{"input_message": "<natural-language request>"}' | jq .

Endpoint resolution: use the agent endpoint from the active VSS deployment context. If unavailable, ask the user. Do not discover via filesystem.

Availability check: curl -sf --connect-timeout 5 "$AGENT/docs".

Do not call the rtvi-vlm microservice endpoints directly — always go through the agent. The agent internally dispatches to rtvi_vlm_alert, rtvi_prompt_gen, and video_analytics_mcp.get_incidents.