Construct RTVI VSS CV Service
Scaffolds a deployable custom perception microservice that:
- runs a DeepStream pipeline with YOLO26 primary inference + tracker,
- converts detection metadata to the VSS protobuf schema and publishes it
to the
mdx-raw Kafka topic, and
- drops into the existing VSS compose stack via the
bp_developer_search_2d and bp_developer_alerts_2d_cv profile flags so
the downstream Search Workflow, Alert Verification, and Behavior
Analytics services consume it without further changes.
The scaffolded output is a runnable repo, not a design document.
Scope boundaries
This skill name describes the service type (a VSS-bound RTVI CV
microservice), not a model family. What is generic vs YOLO26-specific:
| Layer |
Scope |
| VSS integration |
Generic — compose profiles, host networking, mdx-raw, protobuf-2 payload, tests, smoketest |
| Scaffold script output |
YOLO26 reference — pgie-yolo26-config.txt, YOLO26_* mount paths, NvDsInferParseYolo26 |
| Other ONNX detectors |
Adapt the scaffold manually, or use rtvi-cv-customize-model to swap the model inside the stock vss-rt-cv perception container |
| Segmentation frame masks |
Documented in integration-contract.md; not auto-generated by the scaffold — extend msgconv/wrapper after scaffolding |
Do not treat the scaffold as a model-agnostic generator. Agents should either
run the YOLO26 scaffold as-is or consciously edit pgie/compose paths for
another detector while keeping the VSS contract fixed.
When to use
Use this skill when the user wants to:
- replace VSS's default perception service (RT-DETR / GDINO / YOLOv11) with
a custom YOLO26-based detector,
- add new object classes or domain-specific tracking logic while keeping
the VSS Search / Alerts / Behavior Analytics workflows intact,
- ship a perception microservice on a customer's hardware that integrates
with a VSS deployment they manage.
Do not use this skill to:
- deploy or operate VSS itself (use VSS deployment runbooks),
- swap the detector in the default
vss-rt-cv container without a new
microservice (use rtvi-cv-customize-model).
This skill assumes a target VSS deployment already exists or will be brought
up separately.
Instructions
- Read references/integration-contract.md first and keep
mdx-raw, msg-conv-payload-type=2, broker reachability, and the protobuf-2 contract fixed unless the user explicitly wants to break VSS compatibility.
- Treat all VSS deployment paths as relative to a separate checkout of the public VSS Blueprint repository, not the DeepStream repository. Clone or reuse a VSS checkout that is v3.2.1 or compatible, then deploy that release (see VSS Quickstart).
- If the user does not have the YOLO26 ONNX, labels file, or custom parser
.so, say so plainly: scaffolding and unit tests can proceed with placeholders, but the live DeepStream app cannot run yet. Point them at Ultralytics/Hugging Face for pretrained weights and ONNX export (see references/yolo26-deepstream.md).
- When assets are missing, stop the "live validation" path at scaffold generation plus host-only unit tests. Do not imply that
docker compose up, deepstream-app, or kafka_smoketest.py can succeed without the customer-supplied ONNX, labels matching num-detected-classes, and a parser exposing NvDsInferParseYolo26.
- Start the generated service only after the VSS Kafka topic initializer has completed. Keep it as a separate Compose application using host networking. Set
KAFKA_BOOTSTRAP to Kafka's host-reachable advertised listener (default: localhost:9092). Compose cannot resolve depends_on across separate invocations.
Examples
- "Create a custom RTVI CV microservice that runs YOLO26 in DeepStream and publishes object metadata so VSS Search and Alerts can consume it."
- "Validate the generated RTVI VSS service scaffold locally, then explain how to verify the live integration on a GPU host with a deployed VSS stack."
- "I do not have a trained YOLO26 ONNX, labels file, or parser
.so yet. Can the live VSS integration still run?"
VSS source location
This skill ships the scaffold generator, but not the VSS deployment. Clone the
public VSS Blueprint repository separately or reuse an existing checkout, then
set VSS_ROOT to that checkout explicitly. Do not search for or clone VSS
relative to the generated service directory:
# Customer-specific path to an existing VSS v3.2.1-compatible checkout.
export VSS_ROOT=/absolute/path/to/video-search-and-summarization
VSS_DEPLOY_DIR="${VSS_ROOT}/deploy/docker"
test -f "${VSS_DEPLOY_DIR}/compose.yml" || {
echo "Missing VSS compose file: ${VSS_DEPLOY_DIR}/compose.yml" >&2
exit 1
}
echo "Using VSS deployment: ${VSS_DEPLOY_DIR}"
Relevant customer-accessible VSS locations include:
The custom service generated by this skill remains in <target-dir> and runs as a separate, host-networked Compose application alongside VSS. Set KAFKA_BOOTSTRAP to Kafka's host-reachable advertised listener (default: localhost:9092). Do not look for generated YOLO26 files inside either the DeepStream or stock VSS checkout.
Required reads
Read these before generating code so the implementation matches the
documented VSS data path rather than a generic Kafka producer:
- references/integration-contract.md — the exact mdx-raw protobuf contract. For segmentation/frame-mask services, read its segmentation frame-mask payload section before implementing msgconv, wrapper, Kafka, or protobuf changes.
- references/yolo26-deepstream.md — DeepStream nvinfer config for YOLO26.
- references/vss-profile-integration.md — how the service plugs into Search / Alerts / Behavior Analytics.
- VSS Object Detection and Tracking —
https://docs.nvidia.com/vss/latest/object-detection-tracking.html
- VSS Behavior Analytics —
https://docs.nvidia.com/vss/latest/behavior-analytics.html
- VSS Search Workflow —
https://docs.nvidia.com/vss/latest/agent-workflow-search.html
- DeepStream
Gst-nvmsgconv — https://docs.nvidia.com/metropolis/deepstream/9.1/text/DS_plugin_gst-nvmsgconv.html
- DeepStream
Gst-nvmsgbroker — https://docs.nvidia.com/metropolis/deepstream/9.1/text/DS_plugin_gst-nvmsgbroker.html
Inputs to confirm
Ask the user for these. Use placeholders if not provided — do not block.
service-name (slug; becomes container name and python package)
yolo26-onnx-path (host path to the YOLO26 ONNX export — not .pt)
yolo26-labels-path (host path to a one-class-per-line labels file)
yolo26-parser-lib (host path to the YOLO26 custom-parser .so, or the
parser function name if compiled into the customer image)
num-classes (integer; must match the labels file)
target-vss-profiles — any subset of:
bp_developer_search_2d (Search Profile)
bp_developer_alerts_2d_cv (Alerts Profile + Behavior Analytics consumer)
kafka-bootstrap (Kafka's host-reachable advertised listener; default localhost:9092)
kafka-topic (default mdx-raw — VSS consumers expect this name)
input-rtsp-uri or input video file path
Workflow
Read references/integration-contract.md. The fixed parts of the
contract (topic name, payload type, schema library) are not negotiable
if the goal is to plug into an existing VSS deployment.
For segmentation/frame-mask services, follow the segmentation payload
contract in that reference before changing msgconv or wrapper code.
Scaffold the YOLO26 reference service (do not generalize pgie paths unless
the user explicitly needs another detector):
python3 scripts/scaffold_rtvi_vss_service.py \
--service-name <service-name> \
--output-dir <target-dir> \
--num-classes <N> \
--vss-profiles bp_developer_search_2d bp_developer_alerts_2d_cv
Drop the customer's YOLO26 ONNX, labels file, and custom-parser library
into the paths the generated service_config.json references.
If those artifacts do not exist yet, stop after scaffolding and host-only
unit tests; the live DeepStream service cannot start correctly without
them.
Build the image:
docker build -t <service-name>:dev <target-dir>
From the separate VSS checkout, bring up the matching Search or Alerts
profile using the VSS Quickstart and deploy/docker/scripts/dev-profile.sh.
Confirm that VSS and its one-shot Kafka topic initializer are ready, then
start the generated service as a separate Compose application:
For Search or Alerts, find the matching one-shot initializer without
assuming a Compose project or container name:
docker ps -a \
--filter label=com.docker.compose.service=kafka-topic-init-container \
--format 'table {{.Names}}\t{{.Status}}'
Identify the selected deployment's initializer and confirm it is
Exited (0), then start the generated service with the matching gate:
cd <target-dir>
docker compose -f compose/service.compose.yml \
--profile bp_developer_search_2d up -d
# Or for Alerts:
docker compose -f compose/service.compose.yml \
--profile bp_developer_alerts_2d_cv up -d
Do not add a cross-file depends_on entry. The generated service uses
network_mode: host. Set KAFKA_BOOTSTRAP to Kafka's host-reachable
advertised listener (default: localhost:9092). The readiness check
enforces startup order.
Verify the metadata flow:
cd <target-dir>
python3 tools/kafka_smoketest.py --describe-only
python3 tools/kafka_smoketest.py --timeout 120
The smoke test auto-detects Kafka only when exactly one matching container
is running. If multiple deployments are active, pass the selected running
name with --kafka-container. Its --bootstrap-server is resolved inside
that Kafka container and normally remains localhost:9092, even when the
detector's host-facing KAFKA_BOOTSTRAP uses a different port.
A successful consume confirms at least one non-empty message arrived on
mdx-raw within the timeout. It does not decode the protobuf payload or
validate sensorId, objects, or bbox fields.
Confirm downstream pickup:
- Search Profile: query the Video Analytics API for ingested events,
run an embed query and an attribute query against the search workflow.
- Alerts Profile: watch
mdx-incidents for behavior-analytics
output; the alert-bridge service should generate VLM-verified
incidents.
- Behavior Analytics: the selected VSS Search or Alerts deployment starts its own behavior consumer. This is part of the VSS stack, not another profile for the generated service. It consumes
mdx-raw and emits behavior windows to mdx-incidents.
Service shape (generated)
The scaffolder emits this layout:
<service-name>/
├── Dockerfile DeepStream 9.1 + custom parser hook
├── README.md customer-facing build/run/plug-in guide
├── service_config.json declarative config (topic, profile flags, paths)
├── compose/
│ └── service.compose.yml service def with profiles for VSS plug-in
├── pipeline/
│ ├── ds-app-config.txt deepstream-test5 derived; msgconv→msgbroker→mdx-raw
│ ├── ds-start.sh container entrypoint
│ └── configs/
│ ├── pgie-yolo26-config.txt nvinfer config skeleton for YOLO26
│ ├── tracker-nvdcf.yml NvDCF tracker config
│ ├── cfg_kafka.txt librdkafka producer overrides
│ ├── msgconv_config.txt mega2d sensor context
│ └── labels.txt class labels placeholder
├── app/
│ ├── __init__.py
│ ├── contracts.py NvDsEventMsgMeta-aligned event envelope
│ ├── pipeline_plan.py declarative stage list (used by tests)
│ └── service.py adapter helpers for extension/derived events
├── tools/
│ └── kafka_smoketest.py consumes one mdx-raw message and asserts it is non-empty
└── tests/
├── test_pipeline_config.py asserts the Kafka adapter contract and msgconv→msgbroker→mdx-raw wiring
├── test_service.py exercises the python adapter without GPU
└── test_compose.py asserts profile gates, host networking, and liveness healthcheck
Non-negotiable contract elements
The customer can change almost everything except these — they're what
the VSS stack consumes:
- Kafka topic
mdx-raw, using the host-reachable advertised listener selected by KAFKA_BOOTSTRAP (default: localhost:9092).
msg-conv-payload-type=2 (NVDS_PAYLOAD_DEEPSTREAM_PROTOBUF) with msg-conv-msg2p-new-api=1 so the generated deepstream-app serializes frame/object metadata directly: protobuf serialized by
msg-conv-msg2p-lib (libnvds_msgconv_mega2d.so, or libnvds_msgconv.so
on DGX-SPARK/THOR); libnvds_kafka_proto.so is the msg-broker-proto-lib
Kafka transport adapter only.
- A protobuf
Frame payload with sensorId, timestamp, and objects[]
carrying id, bbox, type, confidence. This is what
vss-search-analytics-*, vss-behavior-analytics-*, and
vss-video-analytics-api-* deserialize.
network_mode: host.
- An explicit deployment precondition that the VSS
kafka-topic-init-container
completed successfully before this separate Compose application starts.
If any of these change, the customer is no longer plugging into VSS — they
are running an isolated CV service.
Validation
Run unit tests on any host (no GPU required):
cd <target-dir>
python3 -m unittest discover -v -s tests -p 'test_*.py'
Run end-to-end on a host with GPU + a deployed VSS stack:
cd <target-dir>
python3 tools/kafka_smoketest.py --describe-only
python3 tools/kafka_smoketest.py --timeout 120
A successful smoke test confirms non-empty bytes arrived on mdx-raw within the timeout. It does not decode the protobuf payload or prove the message came from this service specifically. To verify downstream pickup, check the Search / Alerts / Behavior Analytics services via their own APIs.
Do not present local unit-test success as proof that live VSS integration is
ready. Without the customer ONNX, labels file, and parser library, the live
DeepStream path remains blocked even if scaffolding and unit tests succeed.
Implementation guardrails
- Do not invent topic names.
mdx-raw is the single perception ingress.
Per-service prefixes break the existing VSS consumers.
- Do not switch to
msg-conv-payload-type=0 or =1. VSS deserializers
expect type 2.
- Do not bridge through a custom Python Kafka producer. The DeepStream
nvmsgconv → nvmsgbroker boundary is what produces correctly-framed
protobuf with timestamps in nanoseconds. A Python producer drift will
silently degrade Behavior Analytics.
- Keep
track_id stable across frames. Behavior Analytics derives dwell
and direction from track continuity; a per-frame regenerated id makes
every frame look like a new object.
- Do not embed credentials, NGC tokens, or absolute customer paths in the
scaffolded files. The generated tree must be portable.
1---2name: rtvi-cv-scaffold-vss-service3description: >4 Scaffold a standalone RTVI CV microservice that plugs into VSS Search and5 Alerts profiles via Kafka mdx-raw. The shipped scaffold script is a YOLO266 reference implementation (ONNX, labels, custom parser required). Use when7 building a new perception microservice repo, validating the VSS integration8 contract, extending that scaffold for segmentation frame-mask payloads, or9 scaffolding with placeholders before customer YOLO26 assets exist. For10 swapping the detector in the stock vss-rt-cv container, use11 rtvi-cv-customize-model instead. Live DeepStream integration cannot run12 until the customer-supplied ONNX, labels file, and parser library exist.13metadata:14 source: https://skillmd.com/skills/nvidia/rtvi-cv-scaffold-vss-service15 author: "NVIDIA CORPORATION <info@nvidia.com>"16 tags:17 - rtvi-cv18 - vss19 - deepstream20 - yolo2621 - kafka22 - perception23 - custom-microservice24 - segmentation25 - frame-mask26 languages:27 - python28 - bash29 domain: accelerated-microservices30 team: team-mind-hub31 owner: "merylm"32 service: "rtvi-cv"33 version: "2.0.0"34 reviewed: "2026-05-07"35 compatibility: >36 Scaffolding requires Python 3.10+. The generated microservice runs on a37 Linux host with NVIDIA GPU, Docker with the NVIDIA container runtime, and38 DeepStream 9.1 (image nvcr.io/nvidia/deepstream:9.1-triton-multiarch).39 Plugging into VSS requires a working VSS deployment -- Search Profile,40 Alerts Profile, or both -- with Kafka reachable through its standard host41 listener.42 data_classification: "internal"43license: "NVIDIA Proprietary"44---4546# Construct RTVI VSS CV Service4748Scaffolds a deployable custom perception microservice that:49501. runs a DeepStream pipeline with **YOLO26** primary inference + tracker,512. converts detection metadata to the VSS protobuf schema and publishes it52 to the **`mdx-raw`** Kafka topic, and533. drops into the existing VSS compose stack via the54 `bp_developer_search_2d` and `bp_developer_alerts_2d_cv` profile flags so55 the downstream Search Workflow, Alert Verification, and Behavior56 Analytics services consume it without further changes.5758The scaffolded output is a runnable repo, not a design document.5960## Scope boundaries6162This skill name describes the **service type** (a VSS-bound RTVI CV63microservice), not a model family. What is generic vs YOLO26-specific:6465| Layer | Scope |66|-------|-------|67| VSS integration | Generic — compose profiles, host networking, `mdx-raw`, protobuf-2 payload, tests, smoketest |68| Scaffold script output | **YOLO26 reference** — `pgie-yolo26-config.txt`, `YOLO26_*` mount paths, `NvDsInferParseYolo26` |69| Other ONNX detectors | Adapt the scaffold manually, or use `rtvi-cv-customize-model` to swap the model inside the stock `vss-rt-cv` perception container |70| Segmentation frame masks | Documented in `integration-contract.md`; not auto-generated by the scaffold — extend msgconv/wrapper after scaffolding |7172Do not treat the scaffold as a model-agnostic generator. Agents should either73run the YOLO26 scaffold as-is or consciously edit pgie/compose paths for74another detector while keeping the VSS contract fixed.7576## When to use7778Use this skill when the user wants to:7980- replace VSS's default perception service (RT-DETR / GDINO / YOLOv11) with81 a custom YOLO26-based detector,82- add new object classes or domain-specific tracking logic while keeping83 the VSS Search / Alerts / Behavior Analytics workflows intact,84- ship a perception microservice on a customer's hardware that integrates85 with a VSS deployment they manage.8687Do **not** use this skill to:8889- deploy or operate VSS itself (use VSS deployment runbooks),90- swap the detector in the default `vss-rt-cv` container without a new91 microservice (use `rtvi-cv-customize-model`).9293This skill assumes a target VSS deployment already exists or will be brought94up separately.9596## Instructions9798- Read [references/integration-contract.md](references/integration-contract.md) first and keep `mdx-raw`, `msg-conv-payload-type=2`, broker reachability, and the protobuf-2 contract fixed unless the user explicitly wants to break VSS compatibility.99- Treat all VSS deployment paths as relative to a separate checkout of the public [VSS Blueprint repository](https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization), not the DeepStream repository. Clone or reuse a VSS checkout that is **v3.2.1 or compatible**, then deploy that release (see [VSS Quickstart](https://docs.nvidia.com/vss/latest/quickstart.html#download-the-deployment-package)).100- If the user does **not** have the YOLO26 ONNX, labels file, or custom parser `.so`, say so plainly: scaffolding and unit tests can proceed with placeholders, but the live DeepStream app cannot run yet. Point them at Ultralytics/Hugging Face for pretrained weights and ONNX export (see [references/yolo26-deepstream.md](references/yolo26-deepstream.md)).101- When assets are missing, stop the "live validation" path at scaffold generation plus host-only unit tests. Do not imply that `docker compose up`, `deepstream-app`, or `kafka_smoketest.py` can succeed without the customer-supplied ONNX, labels matching `num-detected-classes`, and a parser exposing `NvDsInferParseYolo26`.102- Start the generated service only after the VSS Kafka topic initializer has completed. Keep it as a separate Compose application using host networking. Set `KAFKA_BOOTSTRAP` to Kafka's host-reachable advertised listener (default: `localhost:9092`). Compose cannot resolve `depends_on` across separate invocations.103104## Examples105106- "Create a custom RTVI CV microservice that runs YOLO26 in DeepStream and publishes object metadata so VSS Search and Alerts can consume it."107- "Validate the generated RTVI VSS service scaffold locally, then explain how to verify the live integration on a GPU host with a deployed VSS stack."108- "I do not have a trained YOLO26 ONNX, labels file, or parser `.so` yet. Can the live VSS integration still run?"109110## VSS source location111112This skill ships the scaffold generator, but not the VSS deployment. Clone the113public VSS Blueprint repository separately or reuse an existing checkout, then114set `VSS_ROOT` to that checkout explicitly. Do not search for or clone VSS115relative to the generated service directory:116117```bash118# Customer-specific path to an existing VSS v3.2.1-compatible checkout.119export VSS_ROOT=/absolute/path/to/video-search-and-summarization120VSS_DEPLOY_DIR="${VSS_ROOT}/deploy/docker"121test -f "${VSS_DEPLOY_DIR}/compose.yml" || {122 echo "Missing VSS compose file: ${VSS_DEPLOY_DIR}/compose.yml" >&2123 exit 1124}125echo "Using VSS deployment: ${VSS_DEPLOY_DIR}"126```127128Relevant customer-accessible VSS locations include:129130- [`deploy/docker/scripts/dev-profile.sh`](https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization/blob/v3.2.1/deploy/docker/scripts/dev-profile.sh) — brings up Search or Alerts using the documented Quickstart flow131- [`deploy/docker/developer-profiles/dev-profile-search/`](https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization/tree/v3.2.1/deploy/docker/developer-profiles/dev-profile-search)132- [`deploy/docker/developer-profiles/dev-profile-alerts/`](https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization/tree/v3.2.1/deploy/docker/developer-profiles/dev-profile-alerts)133- [`deploy/docker/services/rtvi/rtvi-cv/`](https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization/tree/v3.2.1/deploy/docker/services/rtvi/rtvi-cv) — stock RTVI-CV service definition134135The custom service generated by this skill remains in `<target-dir>` and runs as a separate, host-networked Compose application alongside VSS. Set `KAFKA_BOOTSTRAP` to Kafka's host-reachable advertised listener (default: `localhost:9092`). Do not look for generated YOLO26 files inside either the DeepStream or stock VSS checkout.136137## Required reads138139Read these before generating code so the implementation matches the140documented VSS data path rather than a generic Kafka producer:1411421. [references/integration-contract.md](references/integration-contract.md) — the exact mdx-raw protobuf contract. For segmentation/frame-mask services, read its segmentation frame-mask payload section before implementing msgconv, wrapper, Kafka, or protobuf changes.1432. [references/yolo26-deepstream.md](references/yolo26-deepstream.md) — DeepStream nvinfer config for YOLO26.1443. [references/vss-profile-integration.md](references/vss-profile-integration.md) — how the service plugs into Search / Alerts / Behavior Analytics.1454. VSS Object Detection and Tracking — `https://docs.nvidia.com/vss/latest/object-detection-tracking.html`1465. VSS Behavior Analytics — `https://docs.nvidia.com/vss/latest/behavior-analytics.html`1476. VSS Search Workflow — `https://docs.nvidia.com/vss/latest/agent-workflow-search.html`1487. DeepStream `Gst-nvmsgconv` — `https://docs.nvidia.com/metropolis/deepstream/9.1/text/DS_plugin_gst-nvmsgconv.html`1498. DeepStream `Gst-nvmsgbroker` — `https://docs.nvidia.com/metropolis/deepstream/9.1/text/DS_plugin_gst-nvmsgbroker.html`150151## Inputs to confirm152153Ask the user for these. Use placeholders if not provided — do not block.154155- `service-name` (slug; becomes container name and python package)156- `yolo26-onnx-path` (host path to the YOLO26 ONNX export — not `.pt`)157- `yolo26-labels-path` (host path to a one-class-per-line labels file)158- `yolo26-parser-lib` (host path to the YOLO26 custom-parser `.so`, or the159 parser function name if compiled into the customer image)160- `num-classes` (integer; must match the labels file)161- `target-vss-profiles` — any subset of:162 - `bp_developer_search_2d` (Search Profile)163 - `bp_developer_alerts_2d_cv` (Alerts Profile + Behavior Analytics consumer)164- `kafka-bootstrap` (Kafka's host-reachable advertised listener; default `localhost:9092`)165- `kafka-topic` (default `mdx-raw` — VSS consumers expect this name)166- `input-rtsp-uri` or input video file path167168## Workflow1691701. Read [references/integration-contract.md](references/integration-contract.md). The fixed parts of the171 contract (topic name, payload type, schema library) are not negotiable172 if the goal is to plug into an existing VSS deployment.173 For segmentation/frame-mask services, follow the segmentation payload174 contract in that reference before changing msgconv or wrapper code.1752. Scaffold the **YOLO26 reference** service (do not generalize pgie paths unless176 the user explicitly needs another detector):177178 ```bash179 python3 scripts/scaffold_rtvi_vss_service.py \180 --service-name <service-name> \181 --output-dir <target-dir> \182 --num-classes <N> \183 --vss-profiles bp_developer_search_2d bp_developer_alerts_2d_cv184 ```1851863. Drop the customer's YOLO26 ONNX, labels file, and custom-parser library187 into the paths the generated `service_config.json` references.188 If those artifacts do not exist yet, stop after scaffolding and host-only189 unit tests; the live DeepStream service cannot start correctly without190 them.1914. Build the image:192193 ```bash194 docker build -t <service-name>:dev <target-dir>195 ```1961975. From the separate VSS checkout, bring up the matching Search or Alerts198 profile using the VSS Quickstart and `deploy/docker/scripts/dev-profile.sh`.199 Confirm that VSS and its one-shot Kafka topic initializer are ready, then200 start the generated service as a separate Compose application:201202 For Search or Alerts, find the matching one-shot initializer without203 assuming a Compose project or container name:204205 ```bash206 docker ps -a \207 --filter label=com.docker.compose.service=kafka-topic-init-container \208 --format 'table {{.Names}}\t{{.Status}}'209 ```210211 Identify the selected deployment's initializer and confirm it is212 `Exited (0)`, then start the generated service with the matching gate:213214 ```bash215 cd <target-dir>216 docker compose -f compose/service.compose.yml \217 --profile bp_developer_search_2d up -d218219 # Or for Alerts:220 docker compose -f compose/service.compose.yml \221 --profile bp_developer_alerts_2d_cv up -d222 ```223224 Do not add a cross-file `depends_on` entry. The generated service uses225 `network_mode: host`. Set `KAFKA_BOOTSTRAP` to Kafka's host-reachable226 advertised listener (default: `localhost:9092`). The readiness check227 enforces startup order.2282296. Verify the metadata flow:230231 ```bash232 cd <target-dir>233 python3 tools/kafka_smoketest.py --describe-only234 python3 tools/kafka_smoketest.py --timeout 120235 ```236237 The smoke test auto-detects Kafka only when exactly one matching container238 is running. If multiple deployments are active, pass the selected running239 name with `--kafka-container`. Its `--bootstrap-server` is resolved inside240 that Kafka container and normally remains `localhost:9092`, even when the241 detector's host-facing `KAFKA_BOOTSTRAP` uses a different port.242243 A successful consume confirms at least one non-empty message arrived on244 `mdx-raw` within the timeout. It does not decode the protobuf payload or245 validate sensorId, objects, or bbox fields.2462477. Confirm downstream pickup:248 - **Search Profile**: query the Video Analytics API for ingested events,249 run an embed query and an attribute query against the search workflow.250 - **Alerts Profile**: watch `mdx-incidents` for behavior-analytics251 output; the `alert-bridge` service should generate VLM-verified252 incidents.253 - **Behavior Analytics**: the selected VSS Search or Alerts deployment starts its own behavior consumer. This is part of the VSS stack, not another profile for the generated service. It consumes `mdx-raw` and emits behavior windows to `mdx-incidents`.254255## Service shape (generated)256257The scaffolder emits this layout:258259```260<service-name>/261├── Dockerfile DeepStream 9.1 + custom parser hook262├── README.md customer-facing build/run/plug-in guide263├── service_config.json declarative config (topic, profile flags, paths)264├── compose/265│ └── service.compose.yml service def with profiles for VSS plug-in266├── pipeline/267│ ├── ds-app-config.txt deepstream-test5 derived; msgconv→msgbroker→mdx-raw268│ ├── ds-start.sh container entrypoint269│ └── configs/270│ ├── pgie-yolo26-config.txt nvinfer config skeleton for YOLO26271│ ├── tracker-nvdcf.yml NvDCF tracker config272│ ├── cfg_kafka.txt librdkafka producer overrides273│ ├── msgconv_config.txt mega2d sensor context274│ └── labels.txt class labels placeholder275├── app/276│ ├── __init__.py277│ ├── contracts.py NvDsEventMsgMeta-aligned event envelope278│ ├── pipeline_plan.py declarative stage list (used by tests)279│ └── service.py adapter helpers for extension/derived events280├── tools/281│ └── kafka_smoketest.py consumes one mdx-raw message and asserts it is non-empty282└── tests/283 ├── test_pipeline_config.py asserts the Kafka adapter contract and msgconv→msgbroker→mdx-raw wiring284 ├── test_service.py exercises the python adapter without GPU285 └── test_compose.py asserts profile gates, host networking, and liveness healthcheck286```287288## Non-negotiable contract elements289290The customer can change almost everything *except* these — they're what291the VSS stack consumes:292293- Kafka topic `mdx-raw`, using the host-reachable advertised listener selected by `KAFKA_BOOTSTRAP` (default: `localhost:9092`).294- `msg-conv-payload-type=2` (`NVDS_PAYLOAD_DEEPSTREAM_PROTOBUF`) with `msg-conv-msg2p-new-api=1` so the generated `deepstream-app` serializes frame/object metadata directly: protobuf serialized by295 `msg-conv-msg2p-lib` (`libnvds_msgconv_mega2d.so`, or `libnvds_msgconv.so`296 on DGX-SPARK/THOR); `libnvds_kafka_proto.so` is the `msg-broker-proto-lib`297 Kafka transport adapter only.298- A protobuf `Frame` payload with `sensorId`, `timestamp`, and `objects[]`299 carrying `id`, `bbox`, `type`, `confidence`. This is what300 `vss-search-analytics-*`, `vss-behavior-analytics-*`, and301 `vss-video-analytics-api-*` deserialize.302- `network_mode: host`.303- An explicit deployment precondition that the VSS `kafka-topic-init-container`304 completed successfully before this separate Compose application starts.305306If any of these change, the customer is no longer plugging into VSS — they307are running an isolated CV service.308309## Validation310311Run unit tests on any host (no GPU required):312313```bash314cd <target-dir>315python3 -m unittest discover -v -s tests -p 'test_*.py'316```317318Run end-to-end on a host with GPU + a deployed VSS stack:319320```bash321cd <target-dir>322python3 tools/kafka_smoketest.py --describe-only323python3 tools/kafka_smoketest.py --timeout 120324```325326A successful smoke test confirms non-empty bytes arrived on `mdx-raw` within the timeout. It does not decode the protobuf payload or prove the message came from this service specifically. To verify downstream pickup, check the Search / Alerts / Behavior Analytics services via their own APIs.327328Do not present local unit-test success as proof that live VSS integration is329ready. Without the customer ONNX, labels file, and parser library, the live330DeepStream path remains blocked even if scaffolding and unit tests succeed.331332## Implementation guardrails333334- Do not invent topic names. `mdx-raw` is the single perception ingress.335 Per-service prefixes break the existing VSS consumers.336- Do not switch to `msg-conv-payload-type=0` or `=1`. VSS deserializers337 expect type 2.338- Do not bridge through a custom Python Kafka producer. The DeepStream339 `nvmsgconv → nvmsgbroker` boundary is what produces correctly-framed340 protobuf with timestamps in nanoseconds. A Python producer drift will341 silently degrade Behavior Analytics.342- Keep `track_id` stable across frames. Behavior Analytics derives dwell343 and direction from track continuity; a per-frame regenerated id makes344 every frame look like a new object.345- Do not embed credentials, NGC tokens, or absolute customer paths in the346 scaffolded files. The generated tree must be portable.