deepstream-generate-pipeline

# DeepStream Pipeline Builder

Generate ready-to-run `gst-launch-1.0` pipelines for NVIDIA DeepStream SDK by collecting pipeline requirements through an interactive questionnaire, then assembling the pipeline using a standalone BM25 retrieval backend with structural metadata boosting (similarity search over 270+ verified pipelines, zero external dependencies).

## Prerequisites

- **Python:** 3.8+ (stdlib only — no pip packages required)
- **DeepStream SDK:** Installed at `/opt/nvidia/deepstream/deepstream/` (for `gst-inspect-1.0` validation and element verification)
- **GStreamer:** `gst-launch-1.0` and `gst-inspect-1.0` on `PATH` (installed with DeepStream)
- **Platform:** x86 dGPU (T4, A100, L40, RTX, etc.) or aarch64 — Jetson (Orin, Xavier, Nano) / SBSA (Grace, GH200)

## Usage Examples

```text
# Fully specified — skips most questions
detect and track on 4 rtsp streams and display on jetson

# Partially specified — asks remaining questions
give me a pipeline to infer on an image

# Minimal — asks all 7 questions
build a pipeline
```

## Supported Configurations

| Parameter | Options |
| --- | --- |
| **Input** | Local video (.mp4/.h264/.h265), local image (.jpg/.png), RTSP stream, USB camera, test pattern |
| **Inference** | None, primary (nvinfer), primary+secondary, with preprocessor, Triton (nvinferserver) |
| **Tracker** | None, NvDCF, IOU, NvSORT, DeepSORT |
| **Sink** | Display (dGPU/Jetson), save (JPG/PNG/MP4/H264), RTSP out, fakesink |
| **Platform** | x86 dGPU (T4, A100, L40, RTX, etc.) or aarch64 — Jetson (Orin, Xavier, Nano) / SBSA (Grace, GH200) |
| **Extras** | Resize, rotate/flip, crop, color format conversion |

## Scripts

| Script | Purpose |
| --- | --- |
| `scripts/generate_pipeline.py` | BM25 retrieval engine — scores and ranks pipelines from `data/data.csv`. Supports `--format {json,compact,summary}` (default `json`) |
| `scripts/validate_pipeline.py` | 4-stage validator: syntax, elements, properties, live parse. Supports `--format {json,summary}` (default `json`) |
| `scripts/lint_data.py` | Data quality linter for the pipeline CSV (`--fix` to auto-repair) |

## Workflow

### Step 1 — Collect Pipeline Requirements

> **You MUST `Read references/requirement-extraction.md` before doing this step.**
> It contains the query-inference table, compound-extraction examples, the full
> `AskUserQuestion` question bank (with the default-first ordering contract), the
> automatic-OSD and extras/flip-method rules, and the dynamic question-reduction
> examples that this step depends on. Apply them exactly.

**Order of operations:**

1. **Infer everything you can from the query** using the inference table in `references/requirement-extraction.md`. The goal is to identify which of the 7 parameters (input source, num sources, inference, tracker, sink, platform, extras) the user has already specified.
2. **Ask the user about the unknowns via `AskUserQuestion` in a single call.** Do **not** silently default tracker/sink/platform/extras — these are real choices the user should make explicitly (display vs save, no tracker vs NvDCF, x86 dGPU vs aarch64 Jetson/SBSA, etc.). Skip only the questions whose answer is already clear from the query.
3. **Quote the inferred parameters back to the user** in the lead-in to the question call so they can see what you already extracted. Example: *"From your query I have: 3 mp4 videos, primary inference. Just need a few more details:"*

Follow the inference table, question bank, and OSD/extras rules in
`references/requirement-extraction.md` to decide which questions to ask and how to
place transform elements, then proceed to Step 2.

### Step 2 — Build the Natural Language Query

From the user's answers, construct a single descriptive query string. Follow this pattern:

```text
Please provide a GStreamer pipeline that [operation] on [num_sources] [input_type] [input_detail] [tracker_detail] and [output_action] [platform_detail]
```

**Examples of constructed queries:**

| User Selections | Constructed Query |
| --- | --- |
| Local video, 1 source, Primary detector, No tracker, Display, dGPU | "Please provide a GStreamer pipeline that performs primary inference on a single mp4 video and displays the output" |
| RTSP, 4 sources, Primary+Secondary, NvDCF, Save MP4, dGPU | "Please provide a GStreamer pipeline that performs primary and secondary inference with NvDCF tracker on 4 RTSP streams and saves output to MP4 file" |
| Local video, 2 sources, Primary with preprocessor, IOU, Display, Jetson | "Please provide a GStreamer pipeline that performs preprocessing before primary inference with IOU tracker on 2 mp4 streams and displays the output on Jetson" |
| Local image, 1 source, None, No tracker, Save file, dGPU, Rotate 90° cw | "Please provide a GStreamer pipeline that rotates a single jpg image 90° clockwise before processing and saves it to a file" |
| Local video, 3 sources, Primary detector, NvDCF, Save MP4, dGPU, Rotate 180° | "Please provide a GStreamer pipeline that rotates 3 mp4 videos 180° before primary inference with NvDCF tracker and saves output to MP4 file" |

### Step 3 — Run the Pipeline Generator Script

Execute the backend script with the constructed query and user parameters:

```bash
python3 <skill-path>/scripts/generate_pipeline.py \
  --query "<constructed_query>" \
  --source-type "<Local video file|Local image file|RTSP stream|USB camera|Test pattern>" \
  --num-sources <N> \
  --inference "<None|primary|primary+secondary|primary+preprocess|primary+secondary+preprocess|primary-triton|primary+secondary-triton>" \
  --tracker "<none|NvDCF|IOU|NvSORT|DeepSORT>" \
  --sink "<display|display-jetson|save-jpg|save-png|save-mp4|save-h264|rtsp-out|fakesink>" \
  --platform "<dGPU|Jetson|SBSA>" \
  --extras "<none|resize|rotate|crop|color-convert|osd>" \
  --format compact
```

> **Always pass `--format compact`.** The `compact` mode returns only confidence + the top retrieved pipeline (~25 lines), instead of dumping all 10 retrievals a