Vss Search Archive

Purpose

Run the top-level VSS fusion search across archived video, ingest new clips / RTSP streams for search, and delete search-ingested sources.

Prerequisites

• Active VSS deployment reachable on $HOST_IP (see vss-deploy-profile and references/).
• vss-manage-video-io-storage skill installed (used to list and manage video sources before search).
• 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/.

Examples

Worked end-to-end examples are kept under evals/ (each *.json manifest contains a runnable scenario) and inline in the per-workflow curl blocks below. Run a Tier-3 evaluation with nv-base validate <this-skill-dir> --agent-eval to replay them.

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.

Video Search Workflows

Alpha Feature — not recommended for production use.

Search video archives by natural language using Cosmos Embed1 embeddings. Requires the search profile — deploy with the vss-deploy-profile skill (-p search). These videos sources can be ingested files or RTSP streams.

When to Use

• "Find all instances of forklifts"
• "When did someone enter the restricted area?"
• "Show me people near the loading dock"
• "Search for vehicles between 8am and noon"
• Any natural-language search across video archives
• "Ingest <file> for search" / "upload this video for search"
• "Add this RTSP stream for search" / "register <rtsp_url> for search"
• "Delete <file> from search" / "remove this video and embeddings"

Deployment prerequisite

This skill requires the VSS search profile running on the host at $HOST_IP. Before any request:

1. Probe the stack:

   curl -sf --max-time 5 "http://${HOST_IP}:8000/docs" >/dev/null \
     && curl -sf --max-time 5 "http://${HOST_IP}:9200/" >/dev/null

   (The second check confirms Elasticsearch is up — unique to the search profile.)

2. If the probe fails, ask the user:

   "The VSS search profile isn't running on $HOST_IP. Shall I deploy it now using the /vss-deploy-profile skill with -p search?"

   • If yes → hand off to the /vss-deploy-profile skill. Return here once it succeeds.
   • If no → stop. Do not run this skill against a missing or wrong-profile stack.

   (If your caller has granted explicit pre-authorization to deploy autonomously — e.g. the request says "pre-authorized to deploy prerequisites", or you are running in a non-interactive evaluation harness with that permission — skip the confirmation and invoke /vss-deploy-profile directly.)

3. If the probe passes, proceed.

Ingestion prerequisite (required before any /generate)

For a source to be searchable it must be ingested through the VSS agent backend, not through VIOS alone. The agent's ingest routes own the VIOS upload + RTVI-CV register + RTVI-embed pipeline as one transaction; a bare VIOS PUT only stores the bytes and never wires them into Elasticsearch.

Confirm the source exists in VIOS first (Mandatory workflow Step 2). If it is missing, ingest it with one of the recipes below before firing /generate. After ingest succeeds, the source appears in sensor/list under the name you provided and can be referenced from the natural-language query the agent forwards to its search-tool decomposer — you do NOT need to construct a structured video_sources payload yourself.

File upload — universal three-step flow

Use the timestamped upload form below. The VSS agent/search profile uses 2025-01-01T00:00:00.000Z as the uploaded video_file base timestamp; VIOS storage and embeddings must share that timeline, otherwise screenshot URLs and critic frame fetches can fail.

FILENAME="<filename.mp4>"
FILE_PATH="/path/to/${FILENAME}"

# 1. Ask the agent for the chunked-upload URL
UPLOAD_URL=$(curl -s -X POST "http://${HOST_IP}:8000/api/v1/videos" \
  -H "Content-Type: application/json" \
  -d "{\"filename\":\"${FILENAME}\"}" | jq -r .url)

# 2. Chunked POST the file to that VST URL (nvstreamer protocol).
#    The final-chunk response carries sensorId.
IDENTIFIER=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
UPLOAD_RESPONSE=$(curl -s -X POST "${UPLOAD_URL}" \
  -H "nvstreamer-chunk-number: 1" \
  -H "nvstreamer-total-chunks: 1" \
  -H "nvstreamer-is-last-chunk: true" \
  -H "nvstreamer-identifier: ${IDENTIFIER}" \
  -H "nvstreamer-file-name: ${FILENAME}" \
  -F "mediaFile=@${FILE_PATH};filename=${FILENAME}" \
  -F "filename=${FILENAME}" \
  -F 'metadata={"timestamp":"2025-01-01T00:00:00"}')

# 3. Tell the agent the upload finished — this fans out to RTVI-CV + RTVI-embed
SENSOR=$(printf '%s' "${UPLOAD_RESPONSE}" | jq -r .sensorId)
[ -z "${SENSOR}" ] || [ "${SENSOR}" = "null" ] \
  && { echo "Upload failed: no sensorId in response: ${UPLOAD_RESPONSE}"; exit 1; }
printf '%s' "${UPLOAD_RESPONSE}" \
  | jq --arg filename "${FILENAME}" '. + {filename: $filename}' \
  | curl -s -X POST "http://${HOST_IP}:8000/api/v1/videos/${SENSOR}/complete" \
      -H "Content-Type: application/json" \
      -d @- | jq .

Wait for the /complete response (it returns chunks_processed > 0 once embeddings land). Only then is the video searchable.

The deprecated PUT /api/v1/videos-for-search/{filename} route is also wired in for legacy callers (single-shot, agent-driven), but its OpenAPI entry is flagged deprecated. Prefer the three-step flow above for new work.

RTSP stream — single endpoint

curl -s -X POST "http://${HOST_IP}:8000/api/v1/rtsp-streams/add" \
  -H "Content-Type: application/json" \
  -d '{
    "sensorUrl": "rtsp://<host>:<port>/<path>",
    "name": "<sensor-name>",
    "username": "",
    "password": "",
    "location": "",
    "tags": ""
  }' | jq .

The response shape is {status, message, error} — no sensorId (the agent keys the stream by the name you provided). On any step's failure earlier steps roll back. The start_embedding_generation step is fire-and-verify: a 2xx confirms the request was accepted and the embedding pipeline is running in the background, not that the stream is searchable yet. Search hits will start appearing only after enough chunks land in Elasticsearch — poll with a low-top_k query a few seconds in if you need a readiness signal.

Delete source — agent-backed cleanup

Delete through the agent backend, not bare VIOS, so VIOS storage and search embeddings are cleaned up together.

# For video files: video_id is the VIOS sensor/video UUID
curl -s -X DELETE "http://${HOST_IP}:8000/api/v1/videos/<video_id>" | jq .

# For RTSP streams: name is the registered source name
curl -s -X DELETE "http://${HOST_IP}:8000/api/v1/rtsp-streams/delete/<name>" | jq .

How Search Works

1. Ingest — Files come in through the agent's three-step universal flow; RTSP streams through /api/v1/rtsp-streams/add. Both routes hand the source to RTVI-CV (attribute detection) and RTVI-Embed (Cosmos Embed1) which generates vector embeddings for video segments.
2. Index — Embeddings are stored in Elasticsearch via the Kafka pipeline.
3. Query — Natural-language queries are embedded and matched against stored vectors by similarity.
4. Results — Timestamped video segments ranked by relevance, with clip playback links.

This search orchestrated by VSS agent can lead to 3 behaviors:

• Attribute-only: when the LLM decomposes the query and finds only appearance attributes with no action (e.g. "person wearing red jacket")
• Embed-only: when the query has no extractable attributes (e.g. "show me forklifts")
• Fusion: when the query has both an action and attributes (e.g., "person in red jacket running"), it runs embed search first, then reranks using attribute search