### Setup Virtual Environment and Dependencies

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/tests/unit/ci-unittest.md

Commands to create a virtual environment and install project dependencies using either uv or pip. This is the recommended starting point for new developers.

```bash
uv venv
source .venv/bin/activate  # On Linux/Mac
.venv\Scripts\activate     # On Windows
uv pip install -r tests/unit/requirements-dev.txt
pytest tests/unit/ -v
```

--------------------------------

### Step-by-Step Environment Configuration

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/tests/unit/ci-unittest.md

Detailed commands for manual environment setup, including virtual environment creation, editable package installation with all dependencies, and test-specific requirement installation.

```bash
# Create environment
python3 -m venv .venv
source .venv/bin/activate

# Install package and test dependencies
pip install -e .[all]
pip install -r tests/unit/requirements-test.txt

# Run tests
pytest tests/unit -v
```

--------------------------------

### Start Ingestion Server (Bash)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/docs/retrieval-only-deployment.md

Starts the ingestion server using Docker Compose for document ingestion. This command assumes you have Docker and Docker Compose installed and configured.

```bash
docker compose -f deploy/compose/docker-compose-ingestor-server.yaml up -d ingestor-server
```

--------------------------------

### Start Required NIMs using Docker Compose (Bash)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/docs/deploy-docker-self-hosted.md

Initiates all necessary NIM (Nvidia Inference Microservices) containers defined in the `nims.yaml` file. This command should only be run after completing the preceding setup steps.

```bash
USERID=$(id -u) docker compose -f deploy/compose/nims.yaml up -d
```

--------------------------------

### Setup RAG API Environment and Configuration

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/retriever_api_usage.ipynb

Initializes the required libraries and defines the base URL and helper functions for interacting with the RAG server API.

```python
!pip install aiohttp
import json
import os
import aiohttp

IPADDRESS = ("rag-server" if os.environ.get("AI_WORKBENCH", "false") == "true" else "localhost")
RAG_SERVER_PORT = "8081"
BASE_URL = f"http://{IPADDRESS}:{RAG_SERVER_PORT}"

async def print_response(response):
    """Helper to print API response."""
    try:
        response_json = await response.json()
        print(json.dumps(response_json, indent=2))
    except aiohttp.ClientResponseError:
        print(await response.text())
```

--------------------------------

### Deploy All RAG Blueprint Services (Python)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/launchable.ipynb

Starts all necessary services for the RAG Blueprint using Docker Compose. It sequentially pulls images and brings up services for NIM, Vector Database, Ingestor Server, and RAG Server. Provides status updates during the deployment process.

```python
def deploy_all():
    """Start all RAG Blueprint services."""
    print("=" * 60)
    print("DEPLOYING NVIDIA RAG BLUEPRINT")
    print("=" * 60)
   
    print("\n[1/4] NIM Microservices (no local LLM/VLM)...")
    docker_compose("deploy/compose/nims.yaml", "pull", f"-q {NIM_SERVICES}")
    docker_compose("deploy/compose/nims.yaml", "up", f"-d {NIM_SERVICES}")
    print("-" * 60)
    print("\n[2/4] Vector Database...")
    docker_compose("deploy/compose/vectordb.yaml", "pull", "-q")
    docker_compose("deploy/compose/vectordb.yaml", "up", "-d")
    print("-" * 60)
    print("\n[3/4] Ingestor Server...")
    docker_compose("deploy/compose/docker-compose-ingestor-server.yaml", "pull", "-q")
    docker_compose("deploy/compose/docker-compose-ingestor-server.yaml", "up", "-d")
    print("-" * 60)
    print("\n[4/4] RAG Server...")
    docker_compose("deploy/compose/docker-compose-rag-server.yaml", "pull", "-q")
    docker_compose("deploy/compose/docker-compose-rag-server.yaml", "up", "-d")
    
    print("\n" + "=" * 60)
    print("DEPLOYMENT COMPLETE")
    print("Wait 2-5 minutes for services to become healthy.")
    print("=" * 60)
```

--------------------------------

### Configure Summarization Parameters and Start Containers

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/summarization.ipynb

Exports environment variables to define LLM behavior for summarization tasks and initializes the RAG infrastructure using Docker Compose.

```bash
export SUMMARY_LLM="meta/llama-3.1-70b-instruct"
export SUMMARY_LLM_TEMPERATURE=0.2
export SUMMARY_LLM_TOP_P=0.7
export SUMMARY_LLM_MAX_CHUNK_LENGTH=9000
export SUMMARY_CHUNK_OVERLAP=400
export SUMMARY_MAX_PARALLELIZATION=20

docker compose -f ../deploy/compose/docker-compose-ingestor-server.yaml up -d ingestor-server
docker compose -f ../deploy/compose/docker-compose-rag-server.yaml up -d rag-server
```

--------------------------------

### Deploy RAG Services

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/launchable.ipynb

Executes the deployment function to launch all configured RAG services.

```python
deploy_all()
```

--------------------------------

### Install MCP Dependencies

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/mcp_server_usage.ipynb

Installs the required Python packages including the MCP SDK, FastMCP, and HTTP clients necessary for communication.

```python
%pip install -qq -r ../examples/nvidia_rag_mcp/requirements.txt
```

--------------------------------

### Define Docker and Configuration Helpers

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/launchable.ipynb

Configures environment variables for RAG services and provides utility functions to execute Docker Compose commands and monitor container status.

```python
import os
import sys
import json
import subprocess
import asyncio
import aiohttp
import base64
from typing import List, Optional
from pathlib import Path
from IPython.display import display, Image as IPImage

IPADDRESS = "0.0.0.0"
RAG_SERVER_PORT = "8081"
INGESTOR_SERVER_PORT = "8082"
MILVUS_ENDPOINT = "http://milvus:19530"

RAG_BASE_URL = f"http://{IPADDRESS}:{RAG_SERVER_PORT}"
INGESTOR_BASE_URL = f"http://{IPADDRESS}:{INGESTOR_SERVER_PORT}"

def docker_compose(yaml_file: str, action: str, args: str = "", profile: str = "") -> bool:
    profile_arg = f"--profile {profile}" if profile else ""
    cmd = f"docker compose -f {yaml_file} {profile_arg} {action} {args}".strip()
    cmd = " ".join(cmd.split())
    QUIET_ACTIONS = {"pull", "up"}
    print_prefix = "Pulling images" if action == "pull" else "Running"
    if action in QUIET_ACTIONS:
        print(f"{print_prefix} from {yaml_file}...", flush=True)
        result = subprocess.run(cmd, shell=True, env=os.environ, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
        if result.returncode == 0:
            print(f"✅ {action} complete", flush=True)
            return True
        print(f"❌ {action} failed", flush=True)
        return False
    print(f"$ {cmd}", flush=True)
    result = subprocess.run(cmd, shell=True, env=os.environ)
    if result.returncode == 0:
        print(f"✅ {action} succeeded", flush=True)
        return True
    print(f"❌ {action} failed (exit code {result.returncode})", flush=True)
    return False

def check_containers():
    subprocess.run('docker ps --format "table {{.Names}}\t{{.Status}}"', shell=True)
```

--------------------------------

### Install REST API Dependencies

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/summarization.ipynb

Installs the aiohttp library required for making asynchronous HTTP requests to the RAG ingestor server.

```python
!uv pip install aiohttp
```

--------------------------------

### Verify RAG Configuration

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/launchable.ipynb

Loads environment variables and inspects the prompt.yaml file to report the current status of VLM inferencing, image extraction, and reasoning modes.

```python
from dotenv import load_dotenv
import os
from pathlib import Path

load_dotenv("deploy/compose/.env")
prompt_yaml_path = Path("src/nvidia_rag/rag_server/prompt.yaml")
vlm_enabled = os.environ.get("ENABLE_VLM_INFERENCE") == "true"

if prompt_yaml_path.exists():
    content = prompt_yaml_path.read_text()
    # Logic to parse and print status follows...
```

--------------------------------

### Install python-dotenv and Setup NGC API Key

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/image_input.ipynb

Installs the 'python-dotenv' library for managing environment variables and prompts the user to enter their NGC API key if it's not already set. It then logs into the NVIDIA Container Registry using the provided API key.

```python
# Install python-dotenv for environment variable management
! uv pip install python-dotenv

import os
from getpass import getpass

# Check if NGC_API_KEY is already set, otherwise prompt for it
# Uncomment the line below to reset your API key
# del os.environ['NGC_API_KEY']

if os.environ.get("NGC_API_KEY", "").startswith("nvapi-"):
    print("Valid NGC_API_KEY already in environment. Delete to reset")
else:
    candidate_api_key = getpass("NVAPI Key (starts with nvapi-):")
    assert candidate_api_key.startswith("nvapi-"), \
        (f"{candidate_api_key[:5]}... is not a valid key")
    os.environ["NGC_API_KEY"] = candidate_api_key

# Login to NVIDIA Container Registry (nvcr.io) to pull required containers
!echo "${NGC_API_KEY}" | docker login nvcr.io -u '$oauthtoken' --password-stdin
```

--------------------------------

### Setup Ingest Runtime and Redis (Docker Compose)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/docs/python-client.md

Starts the NVIDIA Ingest Runtime and Redis service using Docker Compose. This is a prerequisite for data ingestion and management within the RAG system.

```bash
docker compose -f ../deploy/compose/docker-compose-ingestor-server.yaml up nv-ingest-ms-runtime redis -d
```

--------------------------------

### Load Optional Environment Profiles

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/summarization.ipynb

This section shows commented-out examples for loading environment profiles using `load_dotenv`. You can uncomment and use either the 'accuracy_profile.env' or 'perf_profile.env' to adjust settings for accuracy or performance.

```python
# Load accuracy profile
# load_dotenv(dotenv_path='../deploy/compose/accuracy_profile.env', override=True)

# OR load perf profile
# load_dotenv(dotenv_path='../deploy/compose/perf_profile.env', override=True)
```

--------------------------------

### Check Docker Version (>= 26.0)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/launchable.ipynb

Verifies the Docker installation and version, requiring at least 26.0. It uses `shutil.which` to check for Docker's presence and `docker --version` to get the version string. Regex is used to extract the major version number for comparison.

```python
# ─────────────────────────────────────────────────────────────────────────────
# [5] Docker Version (need 26.0+)
# ─────────────────────────────────────────────────────────────────────────────
print("\n[5] Docker Version (need 26.0+):")
if shutil.which("docker"):
    result = subprocess.run(["docker", "--version"], capture_output=True, text=True)
    if result.returncode == 0:
        print(f"    {result.stdout.strip()}")
        match = re.search(r"(\d+)\.\d+", result.stdout)
        if match:
            docker_major = int(match.group(1))
            if docker_major >= 26:
                print("    ✅ PASS")
            else:
                errors.append(f"Docker version {docker_major} < 26 required")
                print(f"    ❌ FAIL: Major version {docker_major} < 26")
else:
    errors.append("Docker not installed")
    print("    ❌ FAIL: Docker not installed")
```

--------------------------------

### Install Python Dependencies for RAG

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/launchable.ipynb

Installs the necessary Python packages including dotenv, aiohttp, and requests to support the RAG system environment.

```python
# Install dependencies (run once)
import sys
try:
    import pip  # noqa
except ImportError:
    !{sys.executable} -m ensurepip --upgrade

!{sys.executable} -m pip install -q python-dotenv aiohttp requests
```

--------------------------------

### Setup Model Cache Directory and Export Path (Bash)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/docs/deploy-docker-self-hosted.md

Creates a directory for caching models and exports its path as an environment variable. This is a prerequisite for using self-hosted models.

```bash
mkdir -p ~/.cache/model-cache
export MODEL_DIRECTORY=~/.cache/model-cache
```

--------------------------------

### Unset NGC API Key (Python)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/launchable.ipynb

Optionally unsets the NGC_API_KEY environment variable if it exists. This is useful for clearing a previously set API key and starting over.

```python
import os

os.environ.pop("NGC_API_KEY", None)
print("✅ NGC_API_KEY unset (if it existed)")
```

--------------------------------

### Make Async GET Request

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/launchable.ipynb

Performs an asynchronous GET request to a specified URL with optional parameters. It handles potential API errors by printing the status and a truncated error message, and attempts to return JSON, falling back to raw text if JSON parsing fails.

```python
async def api_get(url: str, params: dict = None) -> dict:
    """Make async GET request."""
    async with aiohttp.ClientSession() as session:
        async with session.get(url, params=params) as resp:
            if resp.status != 200:
                text = await resp.text()
                print(f"❌ API error {resp.status}: {text[:200]}")
                return {"error": text, "status": resp.status}
            try:
                return await resp.json()
            except:
                text = await resp.text()
                return {"error": text, "raw": True}
```

--------------------------------

### Start Vector Database Containers (Bash)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/docs/deploy-docker-self-hosted.md

Launches the Docker containers for the vector database using the `vectordb.yaml` compose file. This is essential for storing and retrieving embeddings.

```bash
docker compose -f deploy/compose/vectordb.yaml up -d
```

--------------------------------

### Configure and Start RAG Services

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/docs/deploy-docker-nvidia-hosted.md

Commands to initialize environment variables and launch the vector database, ingestion, and RAG server containers using Docker Compose.

```bash
source deploy/compose/.env
docker compose -f deploy/compose/vectordb.yaml up -d
docker compose -f deploy/compose/docker-compose-ingestor-server.yaml up -d
docker compose -f deploy/compose/docker-compose-rag-server.yaml up -d
```

--------------------------------

### Setup Dependencies for NVIDIA RAG

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/summarization.ipynb

Installs the 'python-dotenv' package and imports necessary modules for loading environment variables. This is a prerequisite for setting up default configurations, likely for services and NIMs.

```python
!uv pip install python-dotenv
import os
from getpass import getpass

from dotenv import load_dotenv
```

--------------------------------

### List Vector Database Collections

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/launchable.ipynb

Asynchronously lists all available collections in the vector database using a GET request. It retrieves the collection names, prints them to the console, and returns them as a list. It depends on the `api_get` function.

```python
async def list_collections() -> list:
    """List all vector database collections."""
    result = await api_get(
        f"{INGESTOR_BASE_URL}/v1/collections",
        {"vdb_endpoint": MILVUS_ENDPOINT}
    )
    collections = result.get("collections", [])
    print(f"Collections ({len(collections)}):")
    for c in collections:
        print(f"  • {c.get('collection_name', c)}")
    return collections
```

--------------------------------

### Initialize sample document for RAG workflow

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/deploy/workbench/quickstart.ipynb

Creates a temporary text document to demonstrate the full document management lifecycle including creation, upload, verification, and deletion.

```python
import tempfile

sample_text = """This is a sample text document.
It contains multiple lines of text.
This will be uploaded to the vector store for retrieval."""
```

--------------------------------

### Set NGC API Key (Python)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/launchable.ipynb

Prompts the user to enter their NGC API key and sets it as an environment variable 'NGC_API_KEY'. It validates that the key starts with 'nvapi-'. If the key is already set and valid, it confirms.

```python
import getpass
import os

if os.environ.get("NGC_API_KEY", "").startswith("nvapi-"):
    print("✅ NGC_API_KEY already set")
else:
    key = getpass.getpass("Enter NGC API key (starts with 'nvapi-'): ")
    if key.startswith("nvapi-"):
        os.environ["NGC_API_KEY"] = key
        print("✅ API key set")
    else:
        print("❌ Invalid key format - must start with 'nvapi-'")
```

--------------------------------

### Check Service Health

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/launchable.ipynb

Asynchronously checks if a service is healthy by making a GET request to its '/v1/health' endpoint. It prints a success or failure message and returns a boolean indicating the service's status. Relies on the `api_get` function.

```python
async def check_health(base_url: str, name: str) -> bool:
    """Check if service is healthy."""
    try:
        await api_get(f"{base_url}/v1/health")
        print(f"✅ {name} is healthy")
        return True
    except Exception as e:
        print(f"❌ {name} not responding: {e}")
        return False
```

--------------------------------

### Check Operating System (Ubuntu 22.04+)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/launchable.ipynb

Verifies if the operating system is Ubuntu 22.04 or later. It uses `lsb_release -d` to get OS information and `re.search` to extract the version. Warnings are issued for older Ubuntu versions or non-Ubuntu systems.

```python
import subprocess
import re
import shutil

# ... (previous code)

print("\n[1] Operating System (Ubuntu 22.04+ recommended):")
try:
    result = subprocess.run(["lsb_release", "-d"], capture_output=True, text=True)
    if result.returncode == 0:
        os_info = result.stdout.strip()
        print(f"    {os_info}")
        if "Ubuntu" in os_info:
            # Extract version number
            match = re.search(r"(\d+\.\d+)", os_info)
            if match:
                version = float(match.group(1))
                if version >= 22.04:
                    print("    ✅ PASS")
                else:
                    warnings.append(f"Ubuntu {version} detected, 22.04+ recommended")
                    print(f"    ⚠️  WARNING: Ubuntu {version} < 22.04")
        else:
            warnings.append("Non-Ubuntu OS detected")
            print("    ⚠️  WARNING: Non-Ubuntu OS")
    else:
        print("    Unable to determine OS")
except FileNotFoundError:
    print("    Non-Linux system (macOS/Windows)")
    warnings.append("Non-Linux system detected")
```

--------------------------------

### Install Dependencies (Bash)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/examples/rag_react_agent/README.md

Installs necessary packages and activates the virtual environment for the RAG agent. This is a prerequisite for running the tools and resolving 'Function type not found' errors.

```bash
# From examples/rag_react_agent/ directory
uv sync
source .venv/bin/activate

```

--------------------------------

### Install Development Dependencies

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/LINTING.md

Installs the necessary project dependencies for development and linting purposes using pip.

```bash
pip install -r requirements-dev.txt
```

--------------------------------

### Check System Memory (Python)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/launchable.ipynb

Checks if the system has at least 32GB of RAM. It runs the 'free -g' command to get memory information and parses the output to determine the total available memory. Warnings or errors are generated based on the available RAM.

```python
import subprocess
import re

errors = []
warnings = []
print("\n[7] System Memory (need 32GB+):")
try:
    result = subprocess.run(["free", "-g"], capture_output=True, text=True)
    if result.returncode == 0:
        lines = result.stdout.strip().split("\n")
        for line in lines[:2]:
            print(f"    {line}")
        # Parse total memory
        match = re.search(r"Mem:\s+(\d+)", result.stdout)
        if match:
            total_gb = int(match.group(1))
            if total_gb >= 32:
                print(f"    ✅ PASS ({total_gb}GB available)")
            elif total_gb >= 16:
                warnings.append(f"Only {total_gb}GB RAM, 32GB+ recommended")
                print(f"    ⚠️  WARNING: {total_gb}GB < 32GB recommended")
            else:
                errors.append(f"Only {total_gb}GB RAM, need 32GB+ for full deployment")
                print(f"    ❌ FAIL: {total_gb}GB < 32GB minimum")
except FileNotFoundError:
    print("    Unable to check (non-Linux system)")
```

--------------------------------

### Integrate with External LLM (Python)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/docs/retrieval-only-deployment.md

Demonstrates a three-step process for integrating retrieved documents with an external LLM. First, it retrieves documents using the search API. Second, it formats the retrieved content into a context string. Third, it constructs a prompt including the context and question to send to an external LLM client for generation.

```python
import requests

# Step 1: Retrieve relevant documents
search_url = "http://localhost:8081/v1/search"
search_payload = {
    "query": "What are the key features of the product?",
    "reranker_top_k": 5,
    "collection_names": ["my_collection"],
    "enable_reranker": True
}
search_response = requests.post(search_url, json=search_payload)
citations = search_response.json().get("citations", [])

# Step 2: Format context from retrieved documents
context = "\n\n".join([
    f"[Source: {doc['source']}]\n{doc['content']}"
    for doc in citations
])

# Step 3: Send to your LLM
prompt = f"""Based on the following context, answer the question.

Context:
{context}

Question: Tell me more about the feature XYZ of the product?

Answer:"""

# Use your preferred LLM API (OpenAI, Claude, local model, etc.)
llm_response = your_llm_client.generate(prompt)
```

--------------------------------

### Check Docker Compose Version (>= 2.29.1)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/launchable.ipynb

Checks for the installation and version of Docker Compose, requiring at least 2.29.1. This snippet is incomplete in the provided text but would typically involve running `docker-compose --version` or `docker compose version` and parsing the output.

```python
# ─────────────────────────────────────────────────────────────────────────────
# [6] Docker Compose Version (need 2.29.1+)

```

--------------------------------

### Install Dependencies and Services

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/docs/python-client.md

Command-line instructions for installing Python dependencies and deploying infrastructure services using Docker Compose.

```bash
uv pip install python-dotenv
docker compose -f ../deploy/compose/vectordb.yaml up -d
```

--------------------------------

### Setup RAG Server Configuration and Helper Function (Python)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/deploy/workbench/quickstart.ipynb

Sets up the base configuration for the RAG server, including IP address and port, and defines a helper function to print API responses. This is essential for making subsequent API calls and interpreting their results.

```python
import json
import os

import aiohttp
import requests

# Name for the compose service
IPADDRESS = "rag-server"

# Port number for the service
rag_server_port = "8081"

# Base URL constructed from IP and port for making API requests
RAG_BASE_URL = f"http://{IPADDRESS}:{rag_server_port}"


async def print_raw_response(response):
    """Helper function to print API responses."""
    try:
        response_json = await response.json()
        print(json.dumps(response_json, indent=2))
    except aiohttp.ClientResponseError:
        print(await response.text())
```

--------------------------------

### Install uv Package Manager

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/summarization.ipynb

Checks if the 'uv' package manager is installed and installs it using the official script if it's not found. Requires a restart of the terminal or kernel after installation.

```python
import subprocess
import shutil

# Check if uv is installed
if shutil.which("uv"):
    result = subprocess.run(["uv", "--version"], capture_output=True, text=True)
    print(f"✅ uv is already installed: {result.stdout.strip()}")
else:
    print("⚠️ uv is not installed. Installing now...")
    # Install uv using the official installer
    !curl -LsSf https://astral.sh/uv/install.sh | sh
    print("\n✅ uv installed! Please restart your terminal/kernel and re-run this notebook.")
```

--------------------------------

### Check Docker Compose Version (Python)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/launchable.ipynb

Verifies if the installed Docker Compose version is at least 2.29.1. It captures the output of 'docker compose version' and uses regular expressions to parse the version number. Errors are appended to a list if the version is insufficient or Docker Compose is not available.

```python
import subprocess
import re

errors = []
print("\n[6] Docker Compose Version (need 2.29.1+):")
result = subprocess.run(["docker", "compose", "version"], capture_output=True, text=True)
if result.returncode == 0:
    print(f"    {result.stdout.strip()}")
    match = re.search(r"v?(\d+)\.(\d+)", result.stdout)
    if match:
        major, minor = int(match.group(1)), int(match.group(2))
        if major > 2 or (major == 2 and minor >= 29):
            print("    ✅ PASS")
        else:
            errors.append(f"Docker Compose {major}.{minor} < 2.29.1 required")
            print(f"    ❌ FAIL: Version {major}.{minor} < 2.29.1")
else:
    errors.append("Docker Compose not available")
    print("    ❌ FAIL: Docker Compose not available")
```

--------------------------------

### CLI Script for Search Operations (Bash)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/docs/retrieval-only-deployment.md

Demonstrates how to use the provided CLI script (`scripts/retriever_api_usage.py`) for various search operations, including basic search, searching within specific collections, and saving results to a file.

```bash
# Basic search
python scripts/retriever_api_usage.py --mode search "Tell me about the product features"

# Search with specific collection
python scripts/retriever_api_usage.py \
    --mode search \
    --payload-json '{"collection_names":["my_collection"], "reranker_top_k": 5}' \
    "What is the return policy?"

# Save results to file
python scripts/retriever_api_usage.py \
    --mode search \
    --output-json results.json \
    "Technical specifications"
```

--------------------------------

### Start NeMo Guardrails Service (Bash)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/docs/nemo-guardrails.md

Starts the NeMo Guardrails microservice, content safety model, and topic control model using Docker Compose. This command requires the RAG server to be running and appropriate GPU IDs to be configured.

```bash
USERID=$(id -u) docker compose -f deploy/compose/docker-compose-nemo-guardrails.yaml up -d
```

--------------------------------

### Execute Tests with Coverage

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/tests/unit/ci-unittest.md

Command to run the unit test suite while generating a coverage report in both terminal output and HTML format.

```bash
pytest tests/unit -v --cov=src --cov-report=term-missing --cov-report=html:coverage_report
```

--------------------------------

### Deploy VLM Services with Docker Compose

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/docs/vlm.md

Commands to start the VLM microservice with specific GPU assignments and profiles. These commands replace the standard LLM deployment with VLM-based generation.

```bash
export VLM_MS_GPU_ID=1
USERID=$(id -u) docker compose -f deploy/compose/nims.yaml --profile vlm-generation up -d
```

```bash
export VLM_MS_GPU_ID=3
USERID=$(id -u) docker compose -f deploy/compose/nims.yaml --profile vlm-generation up -d
```

--------------------------------

### Generate PDF from Extracted Content (Python)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/launchable.ipynb

This script generates a PDF document containing extracted text and images from a specified result file. It handles loading data from gzipped JSONL files, processes different document types, and uses the `fpdf2` library to create a formatted PDF report. It includes installation instructions for `fpdf2`.

```python
import gzip
import json
from pathlib import Path
import base64
import os
import sys

# Install fpdf2 in the correct environment
import subprocess
subprocess.check_call([sys.executable, "-m", "pip", "install", "fpdf2", "-q"])

from fpdf import FPDF

# Create results_study folder
RESULTS_STUDY_DIR = Path("results_study")
RESULTS_STUDY_DIR.mkdir(exist_ok=True)

# Path to the specific result file (adjust path as needed)
RESULT_FILE = Path("deploy/compose/volumes/ingestor-server/nv-ingest-results") / COLLECTION_NAME / "sample_ai_article.pdf.results.jsonl.gz"

# Load the file
extracted_content = []
try:
    with gzip.open(RESULT_FILE, 'rt', encoding='utf-8') as f:
        for line in f:
            if line.strip():
                extracted_content.append(json.loads(line))
except gzip.BadGzipFile:
    with open(str(RESULT_FILE).replace('.gz', ''), 'r', encoding='utf-8') as f:
        for line in f:
            if line.strip():
                extracted_content.append(json.loads(line))

print(f"Loaded {len(extracted_content)} items from {RESULT_FILE.name}")

# Save full JSON results
output_json = RESULTS_STUDY_DIR / "sample_ai_article_extracted.json"
with open(output_json, 'w', encoding='utf-8') as f:
    json.dump(extracted_content, f, indent=2)

# Create PDF with extracted content
class PDF(FPDF):
    def header(self):
        self.set_font('Helvetica', 'B', 12)
        self.cell(0, 10, 'Extracted Content: sample_ai_article.pdf', border=False, ln=True, align='C')
        self.ln(5)
    
    def footer(self):
        self.set_y(-15)
        self.set_font('Helvetica', 'I', 8)
        self.cell(0, 10, f'Page {self.page_no()}', align='C')

pdf = PDF()
pdf.set_auto_page_break(auto=True, margin=15)
pdf.add_page()

# Content breakdown
content_types = {}
for item in extracted_content:
    doc_type = item.get('document_type', 'unknown')
    content_types[doc_type] = content_types.get(doc_type, 0) + 1

pdf.set_font('Helvetica', 'B', 11)
pdf.cell(0, 8, f'Total extracted items: {len(extracted_content)}', ln=True)
pdf.ln(3)
pdf.set_font('Helvetica', '', 10)
for doc_type, count in sorted(content_types.items()):
    pdf.cell(0, 6, f'  - {doc_type}: {count}', ln=True)
pdf.ln(5)
pdf.cell(0, 0, '', border='T', ln=True)
pdf.ln(10)

```

--------------------------------

### Download Sample Document (Shell)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/deploy/workbench/quickstart.ipynb

This command-line instruction uses wget to download a PDF document containing FIFA World Cup winners from a specified URL and saves it locally as 'fifa_world_cup_winners.pdf'. This is a preparatory step for ingesting the document into a knowledge base.

```shell
!wget -O fifa_world_cup_winners.pdf https://s3-ap-south-1.amazonaws.com/adda247jobs-wp-assets-adda247/jobs/wp-content/uploads/sites/2/2022/12/20155949/FIFA-World-Cup-Winners-List-From-1930-to-2022.pdf
```

--------------------------------

### Start RAG Server Containers (Bash)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/docs/deploy-docker-self-hosted.md

Launches the RAG (Retrieval-Augmented Generation) server containers, pulling necessary images from NGC. This component handles the core RAG functionality.

```bash
docker compose -f deploy/compose/docker-compose-rag-server.yaml up -d
```

--------------------------------

### Verify NVIDIA RAG Package Installation Location

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/summarization.ipynb

Shows the installation location of the 'nvidia_rag' package within the virtual environment using 'uv pip show'. This helps confirm the package is correctly installed in the expected path.

```bash
!uv pip show nvidia_rag | grep Location
```

--------------------------------

### Start Cloud Guardrails Microservice (Bash)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/docs/nemo-guardrails.md

Starts only the NeMo Guardrails microservice for cloud deployment using Docker Compose. The --no-deps flag prevents dependent services from starting, and --no-deps ensures only the specified service is managed.

```bash
docker compose -f deploy/compose/docker-compose-nemo-guardrails.yaml up -d --no-deps nemo-guardrails-microservice
```

--------------------------------

### Install and Verify uv Package Manager

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/rag_library_usage.ipynb

Checks for the existence of the uv package manager and installs it if missing. This is a prerequisite for managing Python dependencies in the RAG project.

```python
import subprocess
import shutil

if shutil.which("uv"):
    result = subprocess.run(["uv", "--version"], capture_output=True, text=True)
    print(f"✅ uv is already installed: {result.stdout.strip()}")
else:
    print("⚠️ uv is not installed. Installing now...")
    !curl -LsSf https://astral.sh/uv/install.sh | sh
    print("\n✅ uv installed! Please restart your terminal/kernel and re-run this notebook.")
```

--------------------------------

### Start Ingestor Runtime and Redis Service (Shell)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/rag_library_usage.ipynb

Starts the Nvidia Ingest runtime and Redis service using Docker Compose. This is a prerequisite for using the ingestor functionalities.

```bash
!docker compose -f ../deploy/compose/docker-compose-ingestor-server.yaml up nv-ingest-ms-runtime redis -d
```

--------------------------------

### Install NVIDIA RAG Package

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/notebooks/rag_library_usage.ipynb

Provides options to install the nvidia-rag package via PyPI or from source in development mode. Development mode allows for live code edits.

```bash
# Option A: !uv pip install nvidia-rag[all]
!uv pip install -e "..[all]"
# Option C: !cd .. && uv build && uv pip install ../dist/nvidia_rag-*-py3-none-any.whl[all]
```

--------------------------------

### Run Specific Tests

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/tests/unit/ci-unittest.md

Commands to execute specific test files, classes, or individual test methods to isolate functionality during development.

```bash
# Run specific test file
pytest tests/unit/test_server.py -v

# Run specific test class
pytest tests/unit/test_ingestor_server/test_ingestor_server.py::TestHealthEndpoint -v

# Run specific test method
pytest tests/unit/test_ingestor_server/test_ingestor_server.py::TestHealthEndpoint::test_health_check -v
```

--------------------------------

### Start Ingestor and RAG Servers (Bash)

Source: https://github.com/nvidia-ai-blueprints/rag/blob/main/docs/multimodal-query.md

Commands to start the ingestor and RAG servers using Docker Compose. It includes building the images and running the containers in detached mode.

```bash
docker compose -f deploy/compose/docker-compose-ingestor-server.yaml up -d --build
docker compose -f deploy/compose/docker-compose-rag-server.yaml up -d --build
```