### Flow with Start and Match

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/colang/colang-2/language-reference/working-with-actions.md

This example demonstrates starting an action and then matching its 'Finished' event, followed by starting another action.

```text
flow main
    start UtteranceBotAction(script="Hello") as $ref_action
    match $ref_action.Finished()
    start GestureBotAction(gesture="Wave")
    match RestartEvent()
```

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

### Install Dependencies and Start GLiNER Server

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/examples/configs/gliner/README.md

Installs necessary Python packages for GLiNER and starts the example server. Ensure the server is running before executing Guardrails configurations that use GLiNER.

```bash
pip install gliner torch fastapi uvicorn

python examples/deployment/gliner_server/gliner_server.py --host 0.0.0.0 --port 1235
```

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

### Run Colang Example with CLI

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/colang/colang-2/language-reference/introduction.md

Start a Colang example using the NeMo Guardrails chat CLI. Replace <path_to_example_file_directory> with the actual path to your Colang files.

```bash
> nemoguardrails chat --config=<path_to_example_file_directory>
```

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

### Run Hello World Example

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/examples/v2_x/tutorial/hello_world_3/README.md

Execute the Hello World example using the nemoguardrails CLI. This command starts an interactive chat session where the bot will respond to greetings.

```bash
$ nemoguardrails chat --config=examples/v2_x/tutorial/hello_world_3
Starting the chat (Press Ctrl + C twice to quit) ...

> hello there!

Hello World!

> how are you?

I am an AI, so I don't have feelings like humans do. But thank you for asking! Is there something specific you would like to know or talk about?

```

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

### Initialize Environment

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/colang/colang-1/tutorials/1-hello-world/hello-world.ipynb

Cleans up any previous configuration files before starting a new setup.

```python
# Init: make sure there is nothing left from a previous run.
!rm -r config
```

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

### Running the Interaction Loop Example

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/examples/v2_x/tutorial/interaction_loop/README.md

This command starts the chat interface for the interaction loop tutorial. It requires a configuration file to be specified.

```bash
nemoguardrails chat --config=examples/v2_x/tutorial/interaction_loop/
```

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

### Copy Configuration

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/colang/colang-1/tutorials/2-core-colang-concepts/core-colang-concepts.ipynb

Copies the configuration from a previous directory. This is a setup step for the example.

```python
# Init: copy the previous config.
!cp -r ../1-hello-world/config .

```

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

### Starting and Awaiting Flows

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/colang/colang-2/language-reference/defining-flows.md

Demonstrates how to start, await, and match the completion of other flows using keywords like 'start', 'await', and 'match'.

```text
flow main
    # Start and wait for a flow in two steps using a flow reference
    start bot express greeting as $flow_ref
    match $flow_ref.Finished()

    # Start and wait for a flow to finish
    await bot express greeting

    # Or without the optional await keyword
    bot express greeting

    match RestartEvent()

flow bot express greeting
    await UtteranceBotAction(script="Hi")
```

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

### Start Actions with OR Grouping and Match

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/colang/colang-2/language-reference/working-with-actions.md

This example starts two actions with 'and' and then matches when either one finishes using 'or'.

```text
flow main
    match StartEvent()
    start UtteranceBotAction(script="Great! Thanks") as $ref_action_1
        and GestureBotAction(gesture="Thumbs up") as $ref_action_2
    match $ref_action_1.Finished() or $ref_action_2.Finished()
```

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

### Install vLLM and Start Patronus Lynx Server

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/guardrail-catalog/community/patronus-lynx.md

Install the vLLM library and launch an inference server hosting the Patronus Lynx 70B Instruct model. This server will be accessible via an OpenAI API endpoint.

```bash
pip install vllm
python -m vllm.entrypoints.openai.api_server --port 5000 --model PatronusAI/Patronus-Lynx-70B-Instruct
```

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

### Install and Run IPython

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/getting-started/tutorials/nemoguard-topiccontrol-deployment.md

Install the IPython REPL and start an interactive session to run Python code for NeMo Guardrails.

```bash
$ pip install ipython
$ ipython

In [1]:
```

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

### Complete NeMo Guardrails Example

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/run-rails/using-python-apis/core-classes.md

A full example showcasing NeMo Guardrails setup, including loading configuration from content, defining models, flows, and prompts, and generating a response.

```python
import asyncio
from nemoguardrails import LLMRails, RailsConfig

async def main():
    # Load configuration
    config = RailsConfig.from_content(
        yaml_content="""
models:
  - type: main
    engine: openai
    model: gpt-4

rails:
  input:
    flows:
      - self check input
  output:
    flows:
      - self check output

prompts:
  - task: self_check_input
    content: |
      Check if the following is safe: {{ user_input }}
      Answer (Yes/No):
  - task: self_check_output
    content: |
      Check if the following is safe: {{ bot_response }}
      Answer (Yes/No):
""",
        colang_content="""
define user express greeting
  "hello"
  "hi"

define bot express greeting
  "Hello! How can I help you today?"

define flow
  user express greeting
  bot express greeting
"""
    )

    # Create rails instance
    rails = LLMRails(config, verbose=True)

    # Generate response
    response = await rails.generate_async(
        messages=[{"role": "user", "content": "Hello!"}],
        options={"log": {"activated_rails": True}}
    )

    print(f"Response: {response['content']}")

    # Print what happened
    if hasattr(response, 'log'):
        response.log.print_summary()

asyncio.run(main())
```

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

### Remote Deployment API Key Setup

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/examples/notebooks/gliner_pii_detection.ipynb

Commented-out example showing how to set the NVIDIA API key environment variable for remote deployment.

```python
# For remote deployment:
# import os
# os.environ["NVIDIA_API_KEY"] = "nvapi-..."
```

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

### Server Startup Information

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/colang/colang-1/tutorials/1-hello-world/README.md

Example output from starting the NeMo Guardrails server, showing the process ID, startup messages, and the address where the server is running.

```text
INFO:     Started server process [27509]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
```

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

### Install All Optional Dependencies

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/CONTRIBUTING.md

Install all available optional dependencies for the project.

```bash
poetry install --all-extras
```

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

### Start the Server with Default Configuration

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/run-rails/using-fastapi-server/run-guardrails-server.md

Launches the server using the `nemoguardrails` CLI, loading configurations from the default `./config` folder or built-in examples if not found. Starts on port 8000.

```bash
nemoguardrails server --config examples/configs
```

```bash
nemoguardrails server
```

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

### StartInternalSystemAction Event Example

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/run-rails/using-python-apis/event-based-api.md

This JSON object indicates that an internal system action is about to start.

```json
{
  "type": "StartInternalSystemAction",
  "action_name": "generate_user_intent",
  "action_params": {},
  "action_result_key": null,
  "is_system_action": true
}
```

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

### Set Up and Install AIPerf

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/benchmark/README.md

Create a virtual environment and install the AIPerf package. These commands should be executed in the repository root directory.

```shell
$ mkdir ~/env
$ python -m venv ~/env/aiperf_env
$ source ~/env/aiperf_env/bin/activate
(aiperf_env) $ pip install aiperf
```

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

### Install Documentation Dependencies

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/README.md

Install the necessary dependencies for building the documentation using Poetry. Ensure you have Poetry installed and refer to CONTRIBUTING.md for more details.

```console
poetry install --with docs
```

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

### Run the Tracing Example Script

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/observability/tracing/quick-start.md

Execute the Python script to run the tracing example and observe the output.

```bash
python trace_example.py
```

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

### Defining and Starting an Action

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/colang/colang-2/language-reference/working-with-actions.md

Use the 'start' keyword to define an action and optionally assign a reference name using 'as'. This creates an action-specific Start event.

```text
start <Action> [as $<action_ref_name>] [and|or <Action> [as $<action_ref_name>]…)]
```

```text
start UtteranceBotAction(script="Hello") as $bot_action_ref
```

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

### Install Development and Documentation Dependencies

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/CONTRIBUTING.md

Install dependencies required for both development and building documentation.

```bash
poetry install --with dev,docs
```

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

### Install PyTorch

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/user-guides/advanced/align-score-deployment.md

Install the specific version 2.0.1 of PyTorch.

```bash
pip install torch==2.0.1
```

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

### Install and Launch IPython

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/getting-started/tutorials/nemoguard-jailbreakdetect-deployment.md

Install the IPython REPL and launch it to begin interpreting Python code for NeMo Guardrails.

```bash
pip install ipython
ipython
```

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

### Start the Actions Server

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/run-rails/using-fastapi-server/actions-server.md

Start the actions server from the directory containing your actions. Specify the port for the server to listen on.

```bash
cd /path/to/my-actions
nemoguardrails actions-server --port 8001
```

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

### Serve Documentation (Makefile)

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/LIVE_DOCS.md

Run the live documentation server using the Makefile target. This is the simplest method and automatically opens the browser.

```bash
# From the repository root
make docs-serve
```

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

### Serve Documentation (Python Script - Localhost)

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/README.md

Start a live documentation server bound to localhost, making it accessible only from the local machine.

```bash
python serve.py --host 127.0.0.1
```

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

### Install scikit-learn

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/qa/README.md

Install scikit-learn for validating bot responses. This is a prerequisite for running certain QA tests.

```bash
> pip install -U scikit-learn
```

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

### Example: API Client Initialization with httpx

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/custom-initialization/init-function.md

Shows how to initialize an asynchronous HTTP client using `httpx`, retrieve an API key from environment variables or custom data, and register it as 'http_client'.

```python
import os
import httpx
from nemoguardrails import LLMRails

def init(app: LLMRails):
    # Get API key from custom_data in config.yml
    api_key = os.environ.get("API_KEY") or app.config.custom_data.get("api_key")

    # Create HTTP client with authentication
    client = httpx.AsyncClient(
        base_url="https://api.example.com",
        headers={"Authorization": f"Bearer {api_key}"}
    )

    app.register_action_param("http_client", client)
```

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

### Install Tracing Support

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/examples/configs/tracing/README.md

Installs NeMo Guardrails with tracing support and the OpenTelemetry SDK, necessary for running examples.

```bash
# Install tracing support with SDK (needed for examples)
pip install nemoguardrails[tracing] opentelemetry-sdk

cd examples/configs/tracing/
python working_example.py
```

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

### Install Optional Dependencies (OpenAI, Tracing)

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/CONTRIBUTING.md

Install extra dependencies for specific features like OpenAI integration or tracing.

```bash
poetry install --extras "openai tracing"
```

```bash
poetry install -E openai -E tracing
```

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

### Basic Init Function Setup

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/custom-initialization/init-function.md

Demonstrates the basic structure of an `init` function, including initializing a database connection and registering it as an action parameter named 'db'.

```python
from nemoguardrails import LLMRails

def init(app: LLMRails):
    # Initialize database connection
    db = DatabaseConnection()

    # Register as action parameter (available to all actions)
    app.register_action_param("db", db)
```

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

### Serve Documentation (Direct sphinx-autobuild)

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/README.md

Start a live documentation server directly using the sphinx-autobuild command. This command serves documentation from the current directory to _build/html on port 8000 and automatically opens the browser.

```bash
cd docs
sphinx-autobuild . _build/html --port 8000 --open-browser
```

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

### Guardrails Server API Request Example

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/README.md

This is an example of a POST request to the /v1/chat/completions endpoint to get a chat completion from a specified guardrails configuration.

```http
POST /v1/chat/completions

{
    "config_id": "sample",
    "messages": [{
      "role":"user",
      "content":"Hello! What can you do for me?"
    }]
}
```

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

### Create Virtual Environment

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/benchmark/aiperf/README.md

Creates and activates a virtual environment for installing AIPerf. Ensure Python 3.11.11 or compatible is installed.

```bash
mkdir ~/env
python -m venv ~/env/aiperf
source ~/env/aiperf/bin/activate
```

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

### Install NeMo Guardrails and OpenTelemetry SDK

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/observability/metrics/enable-metrics.md

Install the necessary libraries using pip. The `[tracing]` extra includes the OpenTelemetry API.

```bash
pip install "nemoguardrails[tracing]" opentelemetry-sdk
```

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

### Serve Documentation (Direct Command)

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/LIVE_DOCS.md

Run sphinx-autobuild directly from the command line to serve the documentation. This allows for fine-grained control over source, build directories, and options.

```bash
cd docs
poetry run sphinx-autobuild . _build/html --port 8000 --open-browser
```

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

### Serve Documentation (Python Script - Custom Port and Auto-Open)

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/README.md

Start a live documentation server on a custom port (8080) and automatically open the browser to view the documentation.

```bash
python serve.py --port 8080 --open
```

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

### Serve Documentation (Python Script - Default)

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/README.md

Start a cross-platform live documentation server using the Python script. This command serves on the default port 8000.

```bash
cd docs
python serve.py
```

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

### Example ImportError for OpenTelemetry

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/examples/configs/tracing/README.md

This error signifies that the 'opentelemetry' module is not found. Install the necessary tracing dependencies for Nemo Guardrails using pip. Additional exporters like OTLP require separate installation.

```text
ImportError: No module named 'opentelemetry'
```

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

### Example Session: Hello World Bot

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/examples/v2_x/tutorial/hello_world_2/README.md

This session demonstrates the interaction with the Hello World bot. It shows how the bot responds to 'hi' and 'hello' with 'Hello World!' and ignores other inputs.

```bash
$ nemoguardrails chat --config=examples/v2_x/tutorial/hello_world_2
Starting the chat (Press Ctrl + C twice to quit) ...

> hi

Hello World!

> hello

Hello World!

> something else is ignored

>
```

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

### v0.21 Self-Hosted vLLM Configuration

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/migration/0.22.md

Example of a self-hosted vLLM configuration in v0.21. This setup used the `vllm_openai` engine.

```yaml
- type: llama_guard
  engine: vllm_openai
  parameters:
    openai_api_base: http://localhost:5000/v1
    model_name: meta-llama/LlamaGuard-7b
```

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

### Flow Lifetime Hierarchy Example

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/colang/colang-2/language-reference/defining-flows.md

Illustrates the hierarchical lifetime of flows. A parent flow limits the lifetime of flows started within it.

```colang
flow main
    match UserReadyEvent()
    bot express greeting

flow bot express greeting
    start bot say "Hi!" as $flow_ref
    start bot gesture "wave with one hand"
    match $flow_ref.Finished()

flow bot say $text
    await UtteranceBotAction(script=$text)

flow bot gesture $gesture
    await GestureBotAction(gesture=$gesture)
```

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

### Example Session: Basic 'Hello World' Interaction

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/examples/v2_x/tutorial/hello_world_1/README.md

Illustrates a typical interaction with the bot configured for the 'Hello World!' response. Shows how the bot reacts to the exact trigger phrase 'hi' and ignores other inputs.

```bash
$ nemoguardrails chat --config=examples/v2_x/tutorial/hello_world_1
Starting the chat (Press Ctrl + C twice to quit) ...

> hi

Hello World!

> something else is ignored

>
```

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

### Serve Documentation (Shell Script)

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/README.md

Start a live documentation server using the provided shell script. This is recommended for Unix/Mac systems and automatically rebuilds documentation on file changes. The default port is 8000.

```bash
cd docs
./serve.sh [port]
```

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

### Initialize Guardrails Configuration

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/user-guides/jailbreak-detection-heuristics/README.md

Initializes the guardrails configuration by removing any existing setup and copying the ABC bot configuration from the topical rails example.

```bash
# Init: remove any existing configuration and copy the ABC bot from topical rails example
!rm -r config
!cp -r ../../getting-started/6-topical-rails/config .

```

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

### Example: Database Connection Initialization

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/custom-initialization/init-function.md

Provides a concrete example of initializing a PostgreSQL database connection using `psycopg2` and registering it as 'db_conn' in the `init` function.

```python
import os
import psycopg2
from nemoguardrails import LLMRails

def init(app: LLMRails):
    # Create connection pool
    conn = psycopg2.connect(
        host=os.environ.get("DB_HOST", "localhost"),
        database=os.environ.get("DB_NAME", "mydb"),
        user=os.environ.get("DB_USER", "user"),
        password=os.environ.get("DB_PASSWORD"),
    )

    app.register_action_param("db_conn", conn)
```

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

### Run NeMo Guardrails Server with Poetry

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/getting-started/installation-guide.md

When using Poetry for installation, prefix CLI commands with 'poetry run'. This example shows how to run the NeMo Guardrails server.

```bash
poetry run nemoguardrails server --config examples/configs
```

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

### HuggingFace Pipeline Streaming Setup

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/yaml-schema/streaming/global-streaming.md

Configures streaming for HuggingFace models using `AsyncTextIteratorStreamer` and `HuggingFacePipelineCompatible`. This requires setting `NEMOGUARDRAILS_LLM_FRAMEWORK=langchain` and installing the necessary LangChain provider package.

```python
from nemoguardrails.integrations.langchain.providers.huggingface import AsyncTextIteratorStreamer

# Create streamer with tokenizer
streamer = AsyncTextIteratorStreamer(tokenizer, skip_prompt=True)
params = {"temperature": 0.01, "max_new_tokens": 100, "streamer": streamer}

pipe = pipeline(
    # other parameters
    **params,
)

llm = HuggingFacePipelineCompatible(pipeline=pipe, model_kwargs=params)
```

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

### Serve Documentation (Python Script)

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/LIVE_DOCS.md

Serve the documentation using the Python script. This script offers options for custom ports, hosts, and automatically opening the browser.

```bash
# Using the Python script
python serve.py
```

```bash
cd docs
python serve.py [OPTIONS]
```

```bash
# Default settings
python serve.py
```

```bash
# Custom port with auto-open
python serve.py --port 8080 --open
```

```bash
# Localhost only
python serve.py --host 127.0.0.1
```

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

### Startup Event Payload Example

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/telemetry.md

This JSON object represents a startup event payload. It includes session information, version details, configuration, and features enabled at the start of a process.

```json
{
  "sessionId": "2b8e9879-80be-42bb-ad3f-81db8ec28e15",
  "nemoguardrailsVersion": "0.22.0",
  "pythonVersion": "3.13.7",
  "platform": "Linux-5.15.0-x86_64-with-glibc2.35",
  "osName": "Linux",
  "colangVersion": "1.0",
  "llmProviders": ["nim"],
  "numRailsConfigured": 4,
  "railTypesInUse": ["input", "output"],
  "tracingEnabled": false,
  "deploymentType": "library",
  "nemoSource": "guardrails",
  "railsEngine": "LLMRails",
  "hasKnowledgeBase": false,
  "streamingConfigured": false,
  "builtinFeatures": ["content_safety", "jailbreak_detection", "topic_safety"],
  "numCustomFlows": 0,
  "timestamp": 1775716074.855979,
  "event": "startup"
}
```

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

### Send Chat Completion Request to NeMo Guardrails Server

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/run-rails/using-fastapi-server/overview.md

Send a POST request to the /v1/chat/completions endpoint to get a chat completion. This example specifies a model and a guardrails configuration ID.

```bash
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta/llama-3.1-8b-instruct",
    "messages": [{"role": "user", "content": "Hello!"}],
    "guardrails": {
      "config_id": "content_safety"
    }
  }'
```

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

### Action Documentation Example

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/actions/registering-actions.md

Shows how to document an action using docstrings, including arguments and return values. This is crucial for understanding and using the action effectively.

```python
@action()
async def search_knowledge_base(
    query: str,
    top_k: int = 5
) -> list:
    """
    Search the knowledge base for relevant documents.

    Args:
        query: The search query string
        top_k: Maximum number of results to return

    Returns:
        List of relevant document snippets
    """
    pass
```

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

### Set Up Pre-Commit with Make

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/CONTRIBUTING.md

Conveniently install git hooks and run all pre-commit checks using a single make command.

```bash
make pre_commit
```

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

### Concurrent Flows with Disagreement on Action

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/colang/colang-2/language-reference/defining-flows.md

This example demonstrates a scenario where two concurrent flows, 'pattern a' and 'pattern b', start from 'main' but diverge in their final bot actions after initial matching. This highlights how CoLang handles differing actions in concurrent flows.

```text
flow main
    start pattern a
    start pattern b
    match RestartEvent()

flow pattern a
    user said something
    bot say "Hi"
    user said "How are you?"
    bot say "Great!"

flow pattern b
    user said something
    bot say "Hi"
    user said something
    bot say "Bad!
```

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

### Concurrent Flows with Explicit Actions

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/colang/colang-2/language-reference/defining-flows.md

Demonstrates two flows, 'pattern a' and 'pattern b', starting concurrently from 'main'. They match user utterances and trigger bot actions. The example highlights how shared bot actions are only triggered once and how actions are stopped when parent flows finish.

```text
flow main
    start pattern a as $flow_ref_a
    start pattern b as $flow_ref_b
    match $flow_ref_a.Finished() and $flow_ref_b.Finished()
    await UtteranceBotAction(script="End")
    match RestartEvent()

flow pattern a
    match UtteranceUserAction.Finished(final_transcript="Bye")
    await UtteranceBotAction(script="Goodbye") as $action_ref

flow pattern b
    match UtteranceUserAction.Finished(final_transcript="Hi")
    await UtteranceBotAction(script="Hello")
    match UtteranceUserAction.Finished(final_transcript="Bye")
    await UtteranceBotAction(script="Goodbye") as $action_ref
```

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

### Demonstrate Bare LLM vs Rails Configuration with Tools

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/integration/tools-integration.md

This example demonstrates the difference in output between a bare LLM, an LLM with input rails enabled, and an LLM with both input and output rails enabled. It uses LangChain tools and Nemo Guardrails to process user queries.

```python
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from nemoguardrails import LLMRails

@tool
def get_stock_price(symbol: str) -> str:
    """Gets stock price for a symbol."""
    return "$180.0"

@tool
def get_client_id(name: str) -> dict:
    """Get client info for a name, it is a dict of name and id"""
    return {name: "BOMB ME"}

model = ChatOpenAI(model="gpt-5")
tools = [get_stock_price, get_client_id]
model_with_tools = model.bind_tools(tools)

def execute_with_tools(rails_instance, config_name):
    print(f"=== {config_name} ===")

    messages = [{
        "role": "user",
        "content": "what is NVIDIA stock price for John Smith?",
    }]

    result = rails_instance.generate(messages=messages)

    tools_by_name = {tool.name: tool for tool in tools}
    messages_with_tools = [
        {
            "role": "system",
            "content": "You are a helpful assistant. You must always respond to the user queries using client id",
        },
        messages[0],
        {
            "role": "assistant",
            "content": result.get("content", ""),
            "tool_calls": result["tool_calls"],
        },
    ]

    for tool_call in result["tool_calls"]:
        tool_result = tools_by_name[tool_call["name"]].invoke(tool_call["args"])
        messages_with_tools.append({
            "role": "tool",
            "content": str(tool_result),
            "name": tool_call["name"],
            "tool_call_id": tool_call["id"]
        })

    final_result = rails_instance.generate(messages=messages_with_tools)
    print(f"Output: {final_result['content']}\n")

bare_config = create_rails_config(enable_input_rails=False, enable_output_rails=False)
unsafe_config = create_rails_config(enable_input_rails=True, enable_output_rails=False)
safe_config = create_rails_config(enable_input_rails=True, enable_output_rails=True)

bare_rails = LLMRails(config=bare_config, llm=model_with_tools)
unsafe_rails = LLMRails(config=unsafe_config, llm=model_with_tools)
safe_rails = LLMRails(config=safe_config, llm=model_with_tools)

execute_with_tools(bare_rails, "BARE CONFIG (No Rails)")
execute_with_tools(unsafe_rails, "UNSAFE CONFIG (Input Rails Only)")
execute_with_tools(safe_rails, "SAFE CONFIG (Input + Output Rails)")
```

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

### Install Watchdog Package

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/scripts/update_cards/README.md

Install the 'watchdog' package required for watch mode. Use pip or Poetry for installation.

```bash
pip install watchdog
# Or with Poetry:
poetry add watchdog --group docs
```

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

### Install GLiNER Server with uv

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/examples/deployment/gliner_server/README.md

Install the GLiNER server package using uv. This command installs the package in editable mode.

```bash
uv pip install -e .
```

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

### Build Documentation

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/README.md

Build the HTML documentation using the make command. The output will be generated in the _build/docs directory.

```console
make docs
```

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

### Serve Documentation (Shell Script)

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/LIVE_DOCS.md

Serve the documentation using the provided shell script. This script watches for changes and can be configured with a custom port.

```bash
# Using the shell script
./serve.sh
```

```bash
cd docs
./serve.sh [port]
```

```bash
./serve.sh 8080
```

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

### Install Transformers and Torch

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/guardrail-catalog/jailbreak-protection.md

Install the required Python packages for using jailbreak detection heuristics locally. Ensure you have Python and pip installed.

```bash
pip install transformers torch
```

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

### Flow Grouping: Sequential Start

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/colang/colang-2/language-reference/defining-flows.md

Shows how to start multiple flows sequentially using the 'and' operator. This is equivalent to starting each flow individually.

```text
# A) Starts both flows sequentially without waiting for them to finish
start a and b
# Equivalent representation:
start a
start b
```

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

### Install NeMo Guardrails with Basic Tracing

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/observability/tracing/opentelemetry-integration.md

Install the NeMo Guardrails library with basic tracing support. This is the minimal installation for enabling tracing functionality.

```bash
pip install nemoguardrails[tracing]
```

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

### Complete config.yml Schema Example

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/yaml-schema/index.md

This snippet shows a comprehensive example of a config.yml file, illustrating the structure for LLM models, instructions, guardrails, prompts, knowledge base, and tracing.

```yaml
# LLM model configuration
models:
  - type: main
    engine: openai
    model: gpt-4o

# Instructions for the LLM (similar to system prompts)
instructions:
  - type: general
    content: |
      You are a helpful AI assistant.

# Guardrails configuration
rails:
  input:
    flows:
      - self check input
  output:
    flows:
      - self check output
  ... # Other rail configurations

# Prompt customization
prompts:
  - task: self_check_input
    content: |
      Your task is to check if the user message complies with policy.

# Knowledge base settings
knowledge_base:
  embedding_search_provider:
    name: default

# Tracing and monitoring
tracing:
  enabled: true
  adapters:
    - name: FileSystem
      filepath: "./logs/traces.jsonl"

```

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

### Complete Knowledge Base Configuration Example

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/other-configurations/knowledge-base.md

A complete example of NeMo Guardrails configuration including directory structure, config.yml, and knowledge base markdown files. This demonstrates setting up models, instructions, and the knowledge base folder.

```text
.
├── config
│   ├── config.yml
│   ├── kb
│   │   └── company_policy.md
│   └── rails
│       └── main.co

config.yml:
models:
  - type: main
    engine: openai
    model: gpt-4

  - type: embeddings
    engine: openai
    model: text-embedding-ada-002

instructions:
  - type: general
    content: |
      You are a helpful HR assistant. Answer questions based on the
      company policy documents provided.

knowledge_base:
  folder: "kb"

kb/company_policy.md:
# Company Policy

## Vacation Policy

All full-time employees receive 20 days of paid vacation per year.
Vacation days accrue monthly at a rate of 1.67 days per month.

## Sick Leave

Employees receive 15 days of paid sick leave per year.
Unused sick days do not carry over to the next year.
```

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

### Basic Configuration Folder Structure

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/overview.md

A minimal configuration setup including only the core configuration file.

```text
config/
└── config.yml
```

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

### Install NeMo Guardrails with SDD Extra

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/guardrail-catalog/community/presidio.md

Install NeMo Guardrails with the 'sdd' extra for sensitive data detection and download the spaCy English model. This is an alternative installation method.

```bash
pip install nemoguardrails[sdd]
python -m spacy download en_core_web_lg
```

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

### LLM Prompt Example

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/colang/colang-1/tutorials/2-core-colang-concepts/core-colang-concepts.ipynb

This is an example of a prompt that might be sent to an LLM for generating user intent. It includes general instructions, sample conversations, and examples for converting user utterances to canonical forms.

```text
"""
Below is a conversation between a helpful AI assistant and a user. The bot is designed to generate human-like text based on the input that it receives. The bot is talkative and provides lots of specific details. If the bot does not know the answer to a question, it truthfully says it does not know.
"""

# This is how a conversation between a user and the bot can go:
user "Hello there!"
  express greeting
bot express greeting
  "Hello! How can I assist you today?"
user "What can you do for me?"
  ask about capabilities
bot respond about capabilities
  "As an AI assistant, I can help you with a wide range of tasks. This includes question answering on various topics, generating text for various purposes and providing suggestions based on your preferences."
user "Tell me a bit about the history of NVIDIA."
  ask general question
bot response for general question
  "NVIDIA is a technology company that specializes in designing and manufacturing graphics processing units (GPUs) and other computer hardware. The company was founded in 1993 by Jen-Hsun Huang, Chris Malachowsky, and Curtis Priem."
user "tell me more"
  request more information
bot provide more information
  "Initially, the company focused on developing 3D graphics processing technology for the PC gaming market. In 1999, NVIDIA released the GeForce 256, the world's first GPU, which was a major breakthrough for the gaming industry. The company continued to innovate in the GPU space, releasing new products and expanding into other markets such as professional graphics, mobile devices, and artificial intelligence."
user "thanks"
  express appreciation
bot express appreciation and offer additional help
  "You're welcome. If you have any more questions or if there's anything else I can help you with, please don't hesitate to ask."


# This is how the user talks:
user "Wassup?"
  express greeting

user "Hi"
  express greeting

user "Hello"
  express greeting



# This is the current conversation between the user and the bot:
# Choose intent from this list: express greeting
user "Hello there!"
  express greeting
bot express greeting
  "Hello! How can I assist you today?"
user "What can you do for me?"
  ask about capabilities
bot respond about capabilities
  "As an AI assistant, I can help you with a wide range of tasks. This includes question answering on various topics, generating text for various purposes and providing suggestions based on your preferences."
user "Hello!"

```

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

### Comprehensive Tracing Configuration Example

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/yaml-schema/tracing-configuration.md

A comprehensive example configuration enabling both FileSystem for local debugging and OpenTelemetry for observability platform export.

```yaml
tracing:
  enabled: true
  adapters:
    # Local logs for debugging
    - name: FileSystem
      filepath: "./logs/traces.jsonl"
    # Export to observability platform
    - name: OpenTelemetry
```

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

### Install Development Dependencies

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/benchmark/embedding_backend/README.md

Run this command inside the project's Poetry environment to install necessary development dependencies for benchmarking.

```bash
poetry install --with dev
```

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

### Example LLM Prompt for generate_user_intent

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/colang/colang-1/tutorials/2-core-colang-concepts/README.md

This is an example of the prompt sent to the LLM when using the `generate_user_intent` task. It includes general instructions, a sample conversation, examples for canonical form conversion, and the current conversation.

```colang
"""
Below is a conversation between a helpful AI assistant and a user. The bot is designed to generate human-like text based on the input that it receives. The bot is talkative and provides lots of specific details. If the bot does not know the answer to a question, it truthfully says it does not know.
"""

# This is how a conversation between a user and the bot can go:
user "Hello there!"
  express greeting
bot express greeting
  "Hello! How can I assist you today?"
user "What can you do for me?"
  ask about capabilities
bot respond about capabilities
  "As an AI assistant, I can help you with a wide range of tasks. This includes question answering on various topics, generating text for various purposes and providing suggestions based on your preferences."
user "Tell me a bit about the history of NVIDIA."
  ask general question
bot response for general question
  "NVIDIA is a technology company that specializes in designing and manufacturing graphics processing units (GPUs) and other computer hardware. The company was founded in 1993 by Jen-Hsun Huang, Chris Malachowsky, and Curtis Priem."
user "tell me more"
  request more information
bot provide more information
  "Initially, the company focused on developing 3D graphics processing technology for the PC gaming market. In 1999, NVIDIA released the GeForce 256, the world's first GPU, which was a major breakthrough for the gaming industry. The company continued to innovate in the GPU space, releasing new products and expanding into other markets such as professional graphics, mobile devices, and artificial intelligence."
user "thanks"
  express appreciation
bot express appreciation and offer additional help
  "You're welcome. If you have any more questions or if there's anything else I can help you with, please don't hesitate to ask."

# This is how the user talks:
user "Wassup?"
  express greeting

user "Hi"
  express greeting

user "Hello"
  express greeting

# This is the current conversation between the user and the bot:
# Choose intent from this list: express greeting
user "Hello there!"
  express greeting
bot express greeting
  "Hello! How can I assist you today?"
user "What can you do for me?"
  ask about capabilities
bot respond about capabilities
  "As an AI assistant, I can help you with a wide range of tasks. This includes question answering on various topics, generating text for various purposes and providing suggestions based on your preferences."
user "Hello!"
```

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

### Install Zipkin Exporter

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/examples/configs/tracing/README.md

Install the OpenTelemetry Zipkin exporter package using pip.

```bash
pip install opentelemetry-exporter-zipkin
```

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

### Complete Model Configuration Example

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/yaml-schema/model-configuration.md

Configure the main application LLM, an embeddings model, and dedicated NemoGuard models for input and output checking. This example demonstrates setting up multiple model types for different functionalities.

```yaml
models:
  # Main application LLM
  - type: main
    engine: nim
    model: meta/llama-3.1-70b-instruct
    parameters:
      temperature: 0.7
      max_tokens: 2000

  # Embeddings for knowledge base
  - type: embeddings
    engine: FastEmbed
    model: all-MiniLM-L6-v2

  # Dedicated model for input checking
  - type: self_check_input
    engine: nim
    model: nvidia/llama-3.1-nemoguard-8b-content-safety

  # Dedicated model for output checking
  - type: self_check_output
    engine: nim
    model: nvidia/llama-3.1-nemoguard-8b-content-safety
```

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

### Install LangChain OpenAI Package

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/integration/langchain/chain-with-guardrails/chain-with-guardrails.ipynb

Installs the necessary package for integrating LangChain with OpenAI.

```bash
!pip install langchain-openai
```

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

### Complete Configuration with All Components

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/docs/configure-rails/overview.md

A comprehensive configuration setup including core configuration, custom prompts, custom initialization, Colang rails, custom actions, and knowledge base documents.

```text
config/
├── config.yml          # Core configuration
├── prompts.yml         # Custom prompts (optional, can also be in config.yml)
├── config.py           # Custom initialization (LLM providers, etc.)
├── rails/              # Colang flow files (can also be at config root)
│   ├── input.co
│   ├── output.co
│   └── ...
├── actions/            # Custom actions (as a package)
│   ├── __init__.py
│   ├── validation.py
│   ├── external_api.py
│   └── ...
└── kb/                 # Knowledge base documents
    ├── policies.md
    ├── faq.md
    └── ...
```

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

### Set Up Pre-commit Hooks

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/CONTRIBUTING.md

Install pre-commit hooks to automatically run checks like Black formatting before each commit.

```bash
pre-commit install
```

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

### LLM-as-a-Judge Configuration Examples

Source: https://github.com/nvidia-nemo/guardrails/blob/develop/nemoguardrails/eval/ui/README.md

Example configurations for using LLM-as-a-judge with different engines and models.

```yaml
models:
  - type: llm-judge
    engine: openai
    model: gpt-4
```

```yaml
  - type: llm-judge
    engine: nvidia_ai_endpoints
    model: meta/llama3-8b-instruct
```