[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M78DHQB68DFNW51MY9PFSQSE":3,"skill-same:01M78DHQB68DFNW51MY9PFSQSE":84},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":29,"commitSha":30,"skillDirectory":31,"forksCount":14,"repositoryHtmlUrl":32,"repositoryHomepageUrl":33,"ownerHtmlUrl":34,"ownerBlogUrl":35,"ownerDescription":36,"updatedAt":37,"install":38,"resources":51},"01M78DHQB68DFNW51MY9PFSQSE","vss-search-archive",null,"Use this skill to run top-level VSS fusion search on archived video, or to ingest video files \u002F RTSP streams for search. Do NOT use for ad-hoc visual Q&A (use vss-ask-video), live captioning (use vss-deploy-dense-captioning), or video summarization and reports (use vss-summarize-video).","Solizardking\u002Fskillhub-main","Solizardking","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F108096810?v=4","01M786KDB10AYV042N0F9BD5B5","Clawd","01M786NYYXSZK1D05WM8JQPC48",0,"Apache-2.0","https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fnvidia\u002Fvss-search-archive\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: vss-search-archive\ndescription: Use this skill to run top-level VSS fusion search on archived video, or to ingest video files \u002F RTSP streams for search. Do NOT use for ad-hoc visual Q&A (use vss-ask-video), live captioning (use vss-deploy-dense-captioning), or video summarization and reports (use vss-summarize-video).\nlicense: Apache-2.0\nmetadata:\n  author: \"NVIDIA Video Search and Summarization team\"\n  version: \"3.2.0\"\n  github-url: \"https:\u002F\u002Fgithub.com\u002FNVIDIA-AI-Blueprints\u002Fvideo-search-and-summarization\"\n  tags: \"nvidia blueprint operational\"\n---\n## Purpose\n\nRun the top-level VSS fusion search across archived video, ingest new clips \u002F RTSP streams for search, and delete search-ingested sources.\n\n## Prerequisites\n\n- Active VSS deployment reachable on `$HOST_IP` (see `vss-deploy-profile` and `references\u002F`).\n- `vss-manage-video-io-storage` skill installed (used to list and manage video sources before search).\n- NGC credentials in `$NGC_CLI_API_KEY` and `$NVIDIA_API_KEY` for any image pulls.\n- `curl`, `jq`, and Docker available on the caller.\n\n## Instructions\n\nFollow 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\u002F`.\n\n## Examples\n\nWorked end-to-end examples are kept under `evals\u002F` (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 \u003Cthis-skill-dir> --agent-eval` to replay them.\n\n## Limitations\n\n- Requires the matching VSS profile \u002F microservice to be deployed and reachable from the caller.\n- NGC-hosted models and NIMs may be subject to rate-limits, GPU memory requirements, and license restrictions.\n- Concurrency, GPU memory, and storage limits depend on the host hardware and the profile's compose file.\n\n## Troubleshooting\n\n- **Error**: REST call returns connection refused. **Cause**: target microservice not running. **Solution**: probe `\u002Fdocs` or `\u002Fhealth`; redeploy via `vss-deploy-profile` or the matching `vss-deploy-*` skill.\n- **Error**: HTTP 401\u002F403 from NGC pulls. **Cause**: missing\u002Fexpired `NGC_CLI_API_KEY`. **Solution**: `docker login nvcr.io` and re-export the key before retrying.\n- **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`.\n\n# Video Search Workflows\n\n> **Alpha Feature** — not recommended for production use.\n\nSearch 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.\n\n## When to Use\n\n- \"Find all instances of forklifts\"\n- \"When did someone enter the restricted area?\"\n- \"Show me people near the loading dock\"\n- \"Search for vehicles between 8am and noon\"\n- Any natural-language search across video archives\n- \"Ingest `\u003Cfile>` for search\" \u002F \"upload this video for search\"\n- \"Add this RTSP stream for search\" \u002F \"register `\u003Crtsp_url>` for search\"\n- \"Delete `\u003Cfile>` from search\" \u002F \"remove this video and embeddings\"\n\n---\n\n## Deployment prerequisite\n\nThis skill requires the VSS **search** profile running on the host at `$HOST_IP`. Before any request:\n\n1. Probe the stack:\n   ```bash\n   curl -sf --max-time 5 \"http:\u002F\u002F${HOST_IP}:8000\u002Fdocs\" >\u002Fdev\u002Fnull \\\n     && curl -sf --max-time 5 \"http:\u002F\u002F${HOST_IP}:9200\u002F\" >\u002Fdev\u002Fnull\n   ```\n   (The second check confirms Elasticsearch is up — unique to the search profile.)\n\n2. **If the probe fails**, ask the user:\n   > *\"The VSS `search` profile isn't running on `$HOST_IP`. Shall I deploy it now using the `\u002Fvss-deploy-profile` skill with `-p search`?\"*\n\n   - If yes → hand off to the `\u002Fvss-deploy-profile` skill. Return here once it succeeds.\n   - If no → stop. Do not run this skill against a missing or wrong-profile stack.\n\n   (If your caller has granted explicit pre-authorization to deploy\n   autonomously — e.g. the request says \"pre-authorized to deploy\n   prerequisites\", or you are running in a non-interactive evaluation\n   harness with that permission — skip the confirmation and invoke\n   `\u002Fvss-deploy-profile` directly.)\n\n3. If the probe passes, proceed.\n\n---\n\n## Ingestion prerequisite (required before any `\u002Fgenerate`)\n\nFor 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.\n\nConfirm the source exists in VIOS first (Mandatory workflow Step 2). If it is missing, ingest it with one of the recipes below before firing `\u002Fgenerate`. After ingest succeeds, the source appears in `sensor\u002Flist` 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.\n\n### File upload — universal three-step flow\n\nUse the timestamped upload form below. The VSS agent\u002Fsearch profile uses\n`2025-01-01T00:00:00.000Z` as the uploaded `video_file` base timestamp;\nVIOS storage and embeddings must share that timeline, otherwise\nscreenshot URLs and critic frame fetches can fail.\n\n```bash\nFILENAME=\"\u003Cfilename.mp4>\"\nFILE_PATH=\"\u002Fpath\u002Fto\u002F${FILENAME}\"\n\n# 1. Ask the agent for the chunked-upload URL\nUPLOAD_URL=$(curl -s -X POST \"http:\u002F\u002F${HOST_IP}:8000\u002Fapi\u002Fv1\u002Fvideos\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d \"{\\\"filename\\\":\\\"${FILENAME}\\\"}\" | jq -r .url)\n\n# 2. Chunked POST the file to that VST URL (nvstreamer protocol).\n#    The final-chunk response carries sensorId.\nIDENTIFIER=$(uuidgen 2>\u002Fdev\u002Fnull || cat \u002Fproc\u002Fsys\u002Fkernel\u002Frandom\u002Fuuid)\nUPLOAD_RESPONSE=$(curl -s -X POST \"${UPLOAD_URL}\" \\\n  -H \"nvstreamer-chunk-number: 1\" \\\n  -H \"nvstreamer-total-chunks: 1\" \\\n  -H \"nvstreamer-is-last-chunk: true\" \\\n  -H \"nvstreamer-identifier: ${IDENTIFIER}\" \\\n  -H \"nvstreamer-file-name: ${FILENAME}\" \\\n  -F \"mediaFile=@${FILE_PATH};filename=${FILENAME}\" \\\n  -F \"filename=${FILENAME}\" \\\n  -F 'metadata={\"timestamp\":\"2025-01-01T00:00:00\"}')\n\n# 3. Tell the agent the upload finished — this fans out to RTVI-CV + RTVI-embed\nSENSOR=$(printf '%s' \"${UPLOAD_RESPONSE}\" | jq -r .sensorId)\n[ -z \"${SENSOR}\" ] || [ \"${SENSOR}\" = \"null\" ] \\\n  && { echo \"Upload failed: no sensorId in response: ${UPLOAD_RESPONSE}\"; exit 1; }\nprintf '%s' \"${UPLOAD_RESPONSE}\" \\\n  | jq --arg filename \"${FILENAME}\" '. + {filename: $filename}' \\\n  | curl -s -X POST \"http:\u002F\u002F${HOST_IP}:8000\u002Fapi\u002Fv1\u002Fvideos\u002F${SENSOR}\u002Fcomplete\" \\\n      -H \"Content-Type: application\u002Fjson\" \\\n      -d @- | jq .\n```\n\nWait for the `\u002Fcomplete` response (it returns `chunks_processed > 0` once embeddings land). Only then is the video searchable.\n\n> The deprecated `PUT \u002Fapi\u002Fv1\u002Fvideos-for-search\u002F{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.\n\n### RTSP stream — single endpoint\n\n```bash\ncurl -s -X POST \"http:\u002F\u002F${HOST_IP}:8000\u002Fapi\u002Fv1\u002Frtsp-streams\u002Fadd\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"sensorUrl\": \"rtsp:\u002F\u002F\u003Chost>:\u003Cport>\u002F\u003Cpath>\",\n    \"name\": \"\u003Csensor-name>\",\n    \"username\": \"\",\n    \"password\": \"\",\n    \"location\": \"\",\n    \"tags\": \"\"\n  }' | jq .\n```\n\nThe 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.\n\n### Delete source — agent-backed cleanup\n\nDelete through the agent backend, not bare VIOS, so VIOS storage and search embeddings are cleaned up together.\n\n```bash\n# For video files: video_id is the VIOS sensor\u002Fvideo UUID\ncurl -s -X DELETE \"http:\u002F\u002F${HOST_IP}:8000\u002Fapi\u002Fv1\u002Fvideos\u002F\u003Cvideo_id>\" | jq .\n\n# For RTSP streams: name is the registered source name\ncurl -s -X DELETE \"http:\u002F\u002F${HOST_IP}:8000\u002Fapi\u002Fv1\u002Frtsp-streams\u002Fdelete\u002F\u003Cname>\" | jq .\n```\n\n---\n\n## How Search Works\n\n1. **Ingest** — Files come in through the agent's three-step universal flow; RTSP streams through `\u002Fapi\u002Fv1\u002Frtsp-streams\u002Fadd`. Both routes hand the source to RTVI-CV (attribute detection) and RTVI-Embed (Cosmos Embed1) which generates vector embeddings for video segments.\n2. **Index** — Embeddings are stored in Elasticsearch via the Kafka pipeline.\n3. **Query** — Natural-language queries are embedded and matched against stored vectors by similarity.\n4. **Results** — Timestamped video segments ranked by relevance, with clip playback links.\n\nThis search orchestrated by VSS agent can lead to 3 behaviors:\n- Attribute-only: when the LLM decomposes the query and finds only appearance attributes with no action (e.g. \"person wearing red jacket\")\n- Embed-only: when the query has no extractable attributes (e.g. \"show me forklifts\")\n- 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\n\n---\n\n## Mandatory workflow\n\nWhen using this skill, ALWAYS follow this high-level workflow:\n1. **Resolve inputs from user instructions — HARD STOP if `$HOST_IP`\n   is not explicitly provided.** See § Input resolution below. Do NOT\n   default to `localhost`, `127.0.0.1`, the host the agent itself is\n   running on, or any other guess. Do NOT issue a\n   `POST http:\u002F\u002F...\u002Fgenerate` request until the user has supplied an\n   endpoint. Respond to the user with a single question asking for\n   `HOST_IP` \u002F the VSS agent endpoint and wait.\n2. **Resolve the source — HARD STOP before any `\u002Fgenerate` call.**\n   If the user query references a specific video \u002F sensor name\n   (e.g. \"the airport video\", \"warehouse_cam_3\", \"sample warehouse\"),\n   verify it's actually registered in VIOS **before** firing\n   `POST ...\u002Fgenerate`. List sources via the `vss-manage-video-io-storage` skill.\n\n   Then:\n   - **If the named source (or a clearly substring-matching name) IS in the list** → proceed to step 3. Forward the user's natural-language query verbatim — the agent's own search tool decomposer (`services\u002Fagent\u002Fsrc\u002Fvss_agents\u002Ftools\u002Fsearch.py`) extracts `video_sources` from the prose given the available sources, so the skill does NOT need to construct a structured `video sources` payload.\n   - **If the named source is NOT in the list** → STOP. Do NOT fire `\u002Fgenerate` as a probe. Respond to the user with the registered source names and ask whether they meant one of those, want to ingest the missing source (point them at *Ingestion prerequisite* and run the matching file or RTSP recipe through the **agent backend**, not bare VIOS), or want to abandon the query. Wait for clarification.\n   - **If the query names no specific source** (\"find forklifts in the ingested videos\", \"search across all sources\") → skip the substring check, but `sensor\u002Flist` must still return non-empty (otherwise no sources are ingested → HARD STOP).\n3. Run the search(es) via approach chosen\n4. Present the results to the user query. Format response as a professional inspection report but name it `Video Search Results`:\n   — Use clear section headers\n   - Organize findings individually with supporting detail, and close with a summary\n   - Use tables where comparisons help. Write like a technical report, not a chat message.\n   - If criteria results are non-null, then in addition to a column \"Critic result\" (\"confirmed\" | \"rejected\" | \"skipped\"), include a column \"Criteria\" with all the criteria for this search result ({criteria_n}: ✓ | ✗)\n5. CRITICAL: Verify the results and explain this to the user concisely.\n   If search fails, or returns unexpected results (i.e. videos that do not appear to match user query, zero matches, zero videos returned, error etc.), STOP. Do not proceed without reading [troubleshooting.md](references\u002Ftroubleshooting.md) to iterate with feedback loops until proper results are found and presented like a professional inspection report.\n6. Final verifications:\n   - ALWAYS inform user that final and further verifications can be run. Present this as a `Verification Step`\n   - ONLY IF user agrees, download screenshots using the `screenshot_url` of the best candidates (highest similarity scores) from the search hits (JSON results) to `\u002Ftmp`. Read them and verify if they correspond to the user query\n\n## Input resolution\n\nInfer these inputs only from the conversation or user query (no other files unless provided). If some cannot be inferred, ask the user immediately:\n- $HOST_IP: where the VSS agent backend runs\n\n---\n\n## Gotchas\n\n- ALWAYS step into the troubleshooting step of the workflow immediately if anything unexpected happens, read [troubleshooting.md](references\u002Ftroubleshooting.md)\n- Queries work best with **concrete visual descriptions** (objects, actions, locations). Augment user queries if needed to enhance the quality of the questions, expanding potential details\n- The skill assumes video sources are **already ingested through the agent backend** (see *Ingestion prerequisite*). It MAY run the agent-backed ingest recipes when the user explicitly asks (\"ingest `\u003Cfile>` for search\", \"add `\u003Crtsp_url>` for search\"); it does NOT search the local filesystem for files the user didn't name, and it does NOT use the bare-VIOS PUT path (no embeddings get generated). Workflow step 2 still makes confirming \"this source exists in VIOS\" a hard precondition before `\u002Fgenerate`.\n- Use `vss-query-analytics` skill to cross-reference search results with incident\u002Falert data\n\n---\n\n## Search via REST API\n\nDefault to using this REST API approach, unless user specifies otherwise.\n\n```bash\n# Consider only ingested video file sources by default\ncurl -s -X POST http:\u002F\u002F${HOST_IP}:8000\u002Fgenerate \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"input_message\": \"find all instances of forklifts\"}' | jq .\n```\n\n### More Examples\n\nUse the `messages` request shape when passing structured request options such as `search_source_type`; the `input_message` shortcut does not accept extra fields.\n\n```bash\n# Search by object\ncurl -s -X POST http:\u002F\u002F${HOST_IP}:8000\u002Fgenerate \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"input_message\": \"find vehicles in the parking lot\"}' | jq .\n\n# Search by action\ncurl -s -X POST http:\u002F\u002F${HOST_IP}:8000\u002Fgenerate \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"input_message\": \"show me people running\"}' | jq .\n\n# Search by time context\ncurl -s -X POST http:\u002F\u002F${HOST_IP}:8000\u002Fgenerate \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"input_message\": \"what happened at the entrance between 2pm and 3pm?\"}' | jq .\n\n# Consider only RTSP sources with `search_source_type` filter i.e. live camera streams\ncurl -s -X POST http:\u002F\u002F${HOST_IP}:8000\u002Fgenerate \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"messages\": [{\"role\": \"user\", \"content\": \"find all instances of forklifts\"}], \"search_source_type\": \"rtsp\"}' | jq .\n```\n\n### Advanced control knobs\n\nIf user query is ambiguous, user wants more guidance or when fine-grained control is needed, augment the user `input_message` by calling out explicitly certain options in plain-text and steering the agent in the desired direction. Available control axes: \n\n| Axes                 | Type      | Default | Description                                               |\n|----------------------|-----------|---------|-----------------------------------------------------------|\n| `video sources`      | string[]  | null    | Filter to specific cameras or sensor names                |\n| `top k`              | int       | 10      | Max results\n| `minimum similarity` | float     | 0.0     | Min similarity threshold; raise (e.g. 0.3) to filter noise|\n| `critic usage`       | bool      | true    | VLM verifies each result and removes false positives      |\n| `description`        | string    | null    | Filter by camera metadata (e.g. location, category) if metadata is available|\n\nPick and choose some of these tuning options. Adjust them as needed for the user’s situation and query. \nFor examples of discovery modes leveraging these, see [discovery_modes.md](references\u002Fdiscovery_modes.md).\n\n---\n\n## Search via Agent UI\n\nOpen `http:\u002F\u002F${HOST_IP}:3000\u002F` and type natural-language queries:\n\n```\nfind all instances of forklifts\nshow me people near the loading dock\nwhen did a truck arrive at the gate?\nfind someone wearing a red jacket\n```\n\nResults include timestamped clips with similarity scores.\n\nbump:2\n","## Purpose\n\nRun the top-level VSS fusion search across archived video, ingest new clips \u002F RTSP streams for search, and delete search-ingested sources.\n\n## Prerequisites\n\n- Active VSS deployment reachable on `$HOST_IP` (see `vss-deploy-profile` and `references\u002F`).\n- `vss-manage-video-io-storage` skill installed (used to list and manage video sources before search).\n- NGC credentials in `$NGC_CLI_API_KEY` and `$NVIDIA_API_KEY` for any image pulls.\n- `curl`, `jq`, and Docker available on the caller.\n\n## Instructions\n\nFollow 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\u002F`.\n\n## Examples\n\nWorked end-to-end examples are kept under `evals\u002F` (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 \u003Cthis-skill-dir> --agent-eval` to replay them.\n\n## Limitations\n\n- Requires the matching VSS profile \u002F microservice to be deployed and reachable from the caller.\n- NGC-hosted models and NIMs may be subject to rate-limits, GPU memory requirements, and license restrictions.\n- Concurrency, GPU memory, and storage limits depend on the host hardware and the profile's compose file.\n\n## Troubleshooting\n\n- **Error**: REST call returns connection refused. **Cause**: target microservice not running. **Solution**: probe `\u002Fdocs` or `\u002Fhealth`; redeploy via `vss-deploy-profile` or the matching `vss-deploy-*` skill.\n- **Error**: HTTP 401\u002F403 from NGC pulls. **Cause**: missing\u002Fexpired `NGC_CLI_API_KEY`. **Solution**: `docker login nvcr.io` and re-export the key before retrying.\n- **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`.\n\n# Video Search Workflows\n\n> **Alpha Feature** — not recommended for production use.\n\nSearch 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.\n\n## When to Use\n\n- \"Find all instances of forklifts\"\n- \"When did someone enter the restricted area?\"\n- \"Show me people near the loading dock\"\n- \"Search for vehicles between 8am and noon\"\n- Any natural-language search across video archives\n- \"Ingest `\u003Cfile>` for search\" \u002F \"upload this video for search\"\n- \"Add this RTSP stream for search\" \u002F \"register `\u003Crtsp_url>` for search\"\n- \"Delete `\u003Cfile>` from search\" \u002F \"remove this video and embeddings\"\n\n---\n\n## Deployment prerequisite\n\nThis skill requires the VSS **search** profile running on the host at `$HOST_IP`. Before any request:\n\n1. Probe the stack:\n   ```bash\n   curl -sf --max-time 5 \"http:\u002F\u002F${HOST_IP}:8000\u002Fdocs\" >\u002Fdev\u002Fnull \\\n     && curl -sf --max-time 5 \"http:\u002F\u002F${HOST_IP}:9200\u002F\" >\u002Fdev\u002Fnull\n   ```\n   (The second check confirms Elasticsearch is up — unique to the search profile.)\n\n2. **If the probe fails**, ask the user:\n   > *\"The VSS `search` profile isn't running on `$HOST_IP`. Shall I deploy it now using the `\u002Fvss-deploy-profile` skill with `-p search`?\"*\n\n   - If yes → hand off to the `\u002Fvss-deploy-profile` skill. Return here once it succeeds.\n   - If no → stop. Do not run this skill against a missing or wrong-profile stack.\n\n   (If your caller has granted explicit pre-authorization to deploy\n   autonomously — e.g. the request says \"pre-authorized to deploy\n   prerequisites\", or you are running in a non-interactive evaluation\n   harness with that permission — skip the confirmation and invoke\n   `\u002Fvss-deploy-profile` directly.)\n\n3. If the probe passes, proceed.\n\n---\n\n## Ingestion prerequisite (required before any `\u002Fgenerate`)\n\nFor 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.\n\nConfirm the source exists in VIOS first (Mandatory workflow Step 2). If it is missing, ingest it with one of the recipes below before firing `\u002Fgenerate`. After ingest succeeds, the source appears in `sensor\u002Flist` 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.\n\n### File upload — universal three-step flow\n\nUse the timestamped upload form below. The VSS agent\u002Fsearch profile uses\n`2025-01-01T00:00:00.000Z` as the uploaded `video_file` base timestamp;\nVIOS storage and embeddings must share that timeline, otherwise\nscreenshot URLs and critic frame fetches can fail.\n\n```bash\nFILENAME=\"\u003Cfilename.mp4>\"\nFILE_PATH=\"\u002Fpath\u002Fto\u002F${FILENAME}\"\n\n# 1. Ask the agent for the chunked-upload URL\nUPLOAD_URL=$(curl -s -X POST \"http:\u002F\u002F${HOST_IP}:8000\u002Fapi\u002Fv1\u002Fvideos\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d \"{\\\"filename\\\":\\\"${FILENAME}\\\"}\" | jq -r .url)\n\n# 2. Chunked POST the file to that VST URL (nvstreamer protocol).\n#    The final-chunk response carries sensorId.\nIDENTIFIER=$(uuidgen 2>\u002Fdev\u002Fnull || cat \u002Fproc\u002Fsys\u002Fkernel\u002Frandom\u002Fuuid)\nUPLOAD_RESPONSE=$(curl -s -X POST \"${UPLOAD_URL}\" \\\n  -H \"nvstreamer-chunk-number: 1\" \\\n  -H \"nvstreamer-total-chunks: 1\" \\\n  -H \"nvstreamer-is-last-chunk: true\" \\\n  -H \"nvstreamer-identifier: ${IDENTIFIER}\" \\\n  -H \"nvstreamer-file-name: ${FILENAME}\" \\\n  -F \"mediaFile=@${FILE_PATH};filename=${FILENAME}\" \\\n  -F \"filename=${FILENAME}\" \\\n  -F 'metadata={\"timestamp\":\"2025-01-01T00:00:00\"}')\n\n# 3. Tell the agent the upload finished — this fans out to RTVI-CV + RTVI-embed\nSENSOR=$(printf '%s' \"${UPLOAD_RESPONSE}\" | jq -r .sensorId)\n[ -z \"${SENSOR}\" ] || [ \"${SENSOR}\" = \"null\" ] \\\n  && { echo \"Upload failed: no sensorId in response: ${UPLOAD_RESPONSE}\"; exit 1; }\nprintf '%s' \"${UPLOAD_RESPONSE}\" \\\n  | jq --arg filename \"${FILENAME}\" '. + {filename: $filename}' \\\n  | curl -s -X POST \"http:\u002F\u002F${HOST_IP}:8000\u002Fapi\u002Fv1\u002Fvideos\u002F${SENSOR}\u002Fcomplete\" \\\n      -H \"Content-Type: application\u002Fjson\" \\\n      -d @- | jq .\n```\n\nWait for the `\u002Fcomplete` response (it returns `chunks_processed > 0` once embeddings land). Only then is the video searchable.\n\n> The deprecated `PUT \u002Fapi\u002Fv1\u002Fvideos-for-search\u002F{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.\n\n### RTSP stream — single endpoint\n\n```bash\ncurl -s -X POST \"http:\u002F\u002F${HOST_IP}:8000\u002Fapi\u002Fv1\u002Frtsp-streams\u002Fadd\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"sensorUrl\": \"rtsp:\u002F\u002F\u003Chost>:\u003Cport>\u002F\u003Cpath>\",\n    \"name\": \"\u003Csensor-name>\",\n    \"username\": \"\",\n    \"password\": \"\",\n    \"location\": \"\",\n    \"tags\": \"\"\n  }' | jq .\n```\n\nThe 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.\n\n### Delete source — agent-backed cleanup\n\nDelete through the agent backend, not bare VIOS, so VIOS storage and search embeddings are cleaned up together.\n\n```bash\n# For video files: video_id is the VIOS sensor\u002Fvideo UUID\ncurl -s -X DELETE \"http:\u002F\u002F${HOST_IP}:8000\u002Fapi\u002Fv1\u002Fvideos\u002F\u003Cvideo_id>\" | jq .\n\n# For RTSP streams: name is the registered source name\ncurl -s -X DELETE \"http:\u002F\u002F${HOST_IP}:8000\u002Fapi\u002Fv1\u002Frtsp-streams\u002Fdelete\u002F\u003Cname>\" | jq .\n```\n\n---\n\n## How Search Works\n\n1. **Ingest** — Files come in through the agent's three-step universal flow; RTSP streams through `\u002Fapi\u002Fv1\u002Frtsp-streams\u002Fadd`. Both routes hand the source to RTVI-CV (attribute detection) and RTVI-Embed (Cosmos Embed1) which generates vector embeddings for video segments.\n2. **Index** — Embeddings are stored in Elasticsearch via the Kafka pipeline.\n3. **Query** — Natural-language queries are embedded and matched against stored vectors by similarity.\n4. **Results** — Timestamped video segments ranked by relevance, with clip playback links.\n\nThis search orchestrated by VSS agent can lead to 3 behaviors:\n- Attribute-only: when the LLM decomposes the query and finds only appearance attributes with no action (e.g. \"person wearing red jacket\")\n- Embed-only: when the query has no extractable attributes (e.g. \"show me forklifts\")\n- 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\n\n---\n\n## Mandatory workflow\n\nWhen using this skill, ALWAYS follow this high-level workflow:\n1. **Resolve inputs from user instructions — HARD STOP if `$HOST_IP`\n   is not explicitly provided.** See § Input resolution below. Do NOT\n   default to `localhost`, `127.0.0.1`, the host the agent itself is\n   running on, or any other guess. Do NOT issue a\n   `POST http:\u002F\u002F...\u002Fgenerate` request until the user has supplied an\n   endpoint. Respond to the user with a single question asking for\n   `HOST_IP` \u002F the VSS agent endpoint and wait.\n2. **Resolve the source — HARD STOP before any `\u002Fgenerate` call.**\n   If the user query references a specific video \u002F sensor name\n   (e.g. \"the airport video\", \"warehouse_cam_3\", \"sample warehouse\"),\n   verify it's actually registered in VIOS **before** firing\n   `POST ...\u002Fgenerate`. List sources via the `vss-manage-video-io-storage` skill.\n\n   Then:\n   - **If the named source (or a clearly substring-matching name) IS in the list** → proceed to step 3. Forward the user's natural-language query verbatim — the agent's own search tool decomposer (`services\u002Fagent\u002Fsrc\u002Fvss_agents\u002Ftools\u002Fsearch.py`) extracts `video_sources` from the prose given the available sources, so the skill does NOT need to construct a structured `video sources` payload.\n   - **If the named source is NOT in the list** → STOP. Do NOT fire `\u002Fgenerate` as a probe. Respond to the user with the registered source names and ask whether they meant one of those, want to ingest the missing source (point them at *Ingestion prerequisite* and run the matching file or RTSP recipe through the **agent backend**, not bare VIOS), or want to abandon the query. Wait for clarification.\n   - **If the query names no specific source** (\"find forklifts in the ingested videos\", \"search across all sources\") → skip the substring check, but `sensor\u002Flist` must still return non-empty (otherwise no sources are ingested → HARD STOP).\n3. Run the search(es) via approach chosen\n4. Present the results to the user query. Format response as a professional inspection report but name it `Video Search Results`:\n   — Use clear section headers\n   - Organize findings individually with supporting detail, and close with a summary\n   - Use tables where comparisons help. Write like a technical report, not a chat message.\n   - If criteria results are non-null, then in addition to a column \"Critic result\" (\"confirmed\" | \"rejected\" | \"skipped\"), include a column \"Criteria\" with all the criteria for this search result ({criteria_n}: ✓ | ✗)\n5. CRITICAL: Verify the results and explain this to the user concisely.\n   If search fails, or returns unexpected results (i.e. videos that do not appear to match user query, zero matches, zero videos returned, error etc.), STOP. Do not proceed without reading [troubleshooting.md](references\u002Ftroubleshooting.md) to iterate with feedback loops until proper results are found and presented like a professional inspection report.\n6. Final verifications:\n   - ALWAYS inform user that final and further verifications can be run. Present this as a `Verification Step`\n   - ONLY IF user agrees, download screenshots using the `screenshot_url` of the best candidates (highest similarity scores) from the search hits (JSON results) to `\u002Ftmp`. Read them and verify if they correspond to the user query\n\n## Input resolution\n\nInfer these inputs only from the conversation or user query (no other files unless provided). If some cannot be inferred, ask the user immediately:\n- $HOST_IP: where the VSS agent backend runs\n\n---\n\n## Gotchas\n\n- ALWAYS step into the troubleshooting step of the workflow immediately if anything unexpected happens, read [troubleshooting.md](references\u002Ftroubleshooting.md)\n- Queries work best with **concrete visual descriptions** (objects, actions, locations). Augment user queries if needed to enhance the quality of the questions, expanding potential details\n- The skill assumes video sources are **already ingested through the agent backend** (see *Ingestion prerequisite*). It MAY run the agent-backed ingest recipes when the user explicitly asks (\"ingest `\u003Cfile>` for search\", \"add `\u003Crtsp_url>` for search\"); it does NOT search the local filesystem for files the user didn't name, and it does NOT use the bare-VIOS PUT path (no embeddings get generated). Workflow step 2 still makes confirming \"this source exists in VIOS\" a hard precondition before `\u002Fgenerate`.\n- Use `vss-query-analytics` skill to cross-reference search results with incident\u002Falert data\n\n---\n\n## Search via REST API\n\nDefault to using this REST API approach, unless user specifies otherwise.\n\n```bash\n# Consider only ingested video file sources by default\ncurl -s -X POST http:\u002F\u002F${HOST_IP}:8000\u002Fgenerate \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"input_message\": \"find all instances of forklifts\"}' | jq .\n```\n\n### More Examples\n\nUse the `messages` request shape when passing structured request options such as `search_source_type`; the `input_message` shortcut does not accept extra fields.\n\n```bash\n# Search by object\ncurl -s -X POST http:\u002F\u002F${HOST_IP}:8000\u002Fgenerate \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"input_message\": \"find vehicles in the parking lot\"}' | jq .\n\n# Search by action\ncurl -s -X POST http:\u002F\u002F${HOST_IP}:8000\u002Fgenerate \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"input_message\": \"show me people running\"}' | jq .\n\n# Search by time context\ncurl -s -X POST http:\u002F\u002F${HOST_IP}:8000\u002Fgenerate \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"input_message\": \"what happened at the entrance between 2pm and 3pm?\"}' | jq .\n\n# Consider only RTSP sources with `search_source_type` filter i.e. live camera streams\ncurl -s -X POST http:\u002F\u002F${HOST_IP}:8000\u002Fgenerate \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"messages\": [{\"role\": \"user\", \"content\": \"find all instances of forklifts\"}], \"search_source_type\": \"rtsp\"}' | jq .\n```\n\n### Advanced control knobs\n\nIf user query is ambiguous, user wants more guidance or when fine-grained control is needed, augment the user `input_message` by calling out explicitly certain options in plain-text and steering the agent in the desired direction. Available control axes: \n\n| Axes                 | Type      | Default | Description                                               |\n|----------------------|-----------|---------|-----------------------------------------------------------|\n| `video sources`      | string[]  | null    | Filter to specific cameras or sensor names                |\n| `top k`              | int       | 10      | Max results\n| `minimum similarity` | float     | 0.0     | Min similarity threshold; raise (e.g. 0.3) to filter noise|\n| `critic usage`       | bool      | true    | VLM verifies each result and removes false positives      |\n| `description`        | string    | null    | Filter by camera metadata (e.g. location, category) if metadata is available|\n\nPick and choose some of these tuning options. Adjust them as needed for the user’s situation and query. \nFor examples of discovery modes leveraging these, see [discovery_modes.md](references\u002Fdiscovery_modes.md).\n\n---\n\n## Search via Agent UI\n\nOpen `http:\u002F\u002F${HOST_IP}:3000\u002F` and type natural-language queries:\n\n```\nfind all instances of forklifts\nshow me people near the loading dock\nwhen did a truck arrive at the gate?\nfind someone wearing a red jacket\n```\n\nResults include timestamped clips with similarity scores.\n\nbump:2\n",{"name":5,"license":15,"metadata":24,"description":7},{"tags":25,"author":26,"version":27,"github-url":28},"nvidia blueprint operational","NVIDIA Video Search and Summarization team","3.2.0","https:\u002F\u002Fgithub.com\u002FNVIDIA-AI-Blueprints\u002Fvideo-search-and-summarization","main","be3de0244dc1a57e323d8160787ebb40fb64930e","skills\u002Fnvidia\u002Fvss-search-archive","https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main","https:\u002F\u002Fskills.x402.wtf","https:\u002F\u002Fgithub.com\u002FSolizardking","https:\u002F\u002Fmusebook.trade","Got a mile high and never came down","2026-10-08 23:20:13",{"source":8,"skillName":5,"commands":39,"prompt":49,"zipAvailable":50},[40,43,46],{"tool":41,"command":42},"npx","npx skills add Solizardking\u002Fskillhub-main --skill vss-search-archive",{"tool":44,"command":45},"bunx","bunx skills add Solizardking\u002Fskillhub-main --skill vss-search-archive",{"tool":47,"command":48},"pnpm","pnpm dlx skills add Solizardking\u002Fskillhub-main --skill vss-search-archive","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fnvidia\u002Fvss-search-archive\u002FSKILL.md",true,[52,58,62,66,70,74,78],{"path":53,"resourceType":54,"resourceTypeDesc":55,"sizeBytes":56,"sourceHtmlUrl":57},"BENCHMARK.md","REFERENCE","参考文档",3567,"https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fnvidia\u002Fvss-search-archive\u002FBENCHMARK.md",{"path":59,"resourceType":54,"resourceTypeDesc":55,"sizeBytes":60,"sourceHtmlUrl":61},"evals\u002Fevals.json",645,"https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fnvidia\u002Fvss-search-archive\u002Fevals\u002Fevals.json",{"path":63,"resourceType":54,"resourceTypeDesc":55,"sizeBytes":64,"sourceHtmlUrl":65},"evals\u002Fsearch.json",9752,"https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fnvidia\u002Fvss-search-archive\u002Fevals\u002Fsearch.json",{"path":67,"resourceType":54,"resourceTypeDesc":55,"sizeBytes":68,"sourceHtmlUrl":69},"references\u002Fdiscovery_modes.md",3108,"https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fnvidia\u002Fvss-search-archive\u002Freferences\u002Fdiscovery_modes.md",{"path":71,"resourceType":54,"resourceTypeDesc":55,"sizeBytes":72,"sourceHtmlUrl":73},"references\u002Ftroubleshooting.md",5395,"https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fnvidia\u002Fvss-search-archive\u002Freferences\u002Ftroubleshooting.md",{"path":75,"resourceType":54,"resourceTypeDesc":55,"sizeBytes":76,"sourceHtmlUrl":77},"skill-card.md",3795,"https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fnvidia\u002Fvss-search-archive\u002Fskill-card.md",{"path":79,"resourceType":80,"resourceTypeDesc":81,"sizeBytes":82,"sourceHtmlUrl":83},"skill.oms.sig","OTHER","其他",5305,"https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fnvidia\u002Fvss-search-archive\u002Fskill.oms.sig",[85,93,100,107,114,122],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":89,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":19},"01M78E0TGCAMNPS207BA3G07S7","zkrouter","Self-hosted OpenAI-compatible LLM router — smart tier-based routing, ZK-stamped routing decisions, mode overrides, free OpenRouter at install via the Birth bot. Save 60-80% on inference costs by routing to the cheapest capable model across 12+ OpenRouter models.","MIT","https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fzkrouter\u002FSKILL.md",[],[],{"skillNo":94,"name":95,"nameZh":6,"description":96,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":89,"licenseFileUrl":6,"sourceHtmlUrl":97,"categories":98,"keywords":99,"publishedAt":19},"01M78E0R1Z8BDT6EDTHY17MTNB","zk","For custom ZK Solana programs and privacy-preserving applications to prevent double spending. Guide to integrate rent-free nullifier PDAs for double-spend prevention.","https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fzk\u002FSKILL.md",[],[],{"skillNo":101,"name":102,"nameZh":6,"description":103,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":89,"licenseFileUrl":6,"sourceHtmlUrl":104,"categories":105,"keywords":106,"publishedAt":19},"01M78E0P3ZTZ1YWF8MD5MM23QE","zk-omni-messaging","Zero-knowledge omnichain messaging between Robinhood Chain and Solana using CheshireZkOmniMessenger (msgType 4) with nullifier anti-replay and the zk-omni-relayer service.","https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fzk-omni-messaging\u002FSKILL.md",[],[],{"skillNo":108,"name":109,"nameZh":6,"description":110,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":89,"licenseFileUrl":6,"sourceHtmlUrl":111,"categories":112,"keywords":113,"publishedAt":19},"01M78E0JXZ2PNB1896VXAGDBWD","zerion-wallet-data","Use when the user asks to check a wallet's portfolio, token balances, DeFi positions, PnL, transaction history, or NFTs. Provides interpreted on-chain data across 40+ EVM chains and Solana via x402 pay-per-request or API key — no raw RPC decoding needed.","https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fzerion-wallet-data\u002FSKILL.md",[],[],{"skillNo":115,"name":116,"nameZh":6,"description":117,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":89,"licenseFileUrl":118,"sourceHtmlUrl":119,"categories":120,"keywords":121,"publishedAt":19},"01M78E0G14FH9GRRTQYMKD5E59","youtube-clipper","YouTube 视频智能剪辑工具。下载视频和字幕，AI 分析生成精细章节（几分钟级别）， 用户选择片段后自动剪辑、翻译字幕为中英双语、烧录字幕到视频，并生成总结文案。 使用场景：当用户需要剪辑 YouTube 视频、生成短视频片段、制作双语字幕版本时。 关键词：视频剪辑、YouTube、字幕翻译、双语字幕、视频下载、clip video","https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fyoutube-clipper\u002FLICENSE","https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fyoutube-clipper\u002FSKILL.md",[],[],{"skillNo":123,"name":124,"nameZh":6,"description":125,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":89,"licenseFileUrl":6,"sourceHtmlUrl":126,"categories":127,"keywords":128,"publishedAt":19},"01M78E0C2ZYA99CFFDNB7ZMK5S","yield-optimization","Multi-chain yield optimization via yield.xyz (StakeKit). Discover 2,988+ yield opportunities across 75+ blockchains, build deposit\u002Fwithdrawal transactions with shell scripts, and sign them with a MoonPay wallet. Use when the user wants to earn yield, find the best lending or staking rate, enter\u002Fexit a position, or check portfolio balances.","https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fyield-optimization\u002FSKILL.md",[],[]]