> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/guardrails/_mcp/server.

# nemoguardrails.guardrails.guardrails

Top-level Guardrails interface module.

This module provides a simplified, user-friendly interface for interacting with
NeMo Guardrails. The Guardrails class wraps either IORails or LLMRails (chosen
automatically based on config) and provides a streamlined API for generating
LLM responses with programmable guardrails.

## Module Contents

### Classes

| Name                                                             | Description                                            |
| ---------------------------------------------------------------- | ------------------------------------------------------ |
| [`Guardrails`](#nemoguardrails-guardrails-guardrails-Guardrails) | Top-level interface for NeMo Guardrails functionality. |

### Data

[`log`](#nemoguardrails-guardrails-guardrails-log)

### API

```python
class nemoguardrails.guardrails.guardrails.Guardrails(
    config: nemoguardrails.rails.llm.config.RailsConfig,
    llm: typing.Optional[nemoguardrails.types.LLMModel] = None,
    verbose: bool = False,
    use_iorails: bool = True,
    require_iorails: bool = False
)
```

**Bases:** [BaseGuardrails](/guardrails-python-sdk/nemoguardrails/base_guardrails#nemoguardrails-base_guardrails-BaseGuardrails)

Top-level interface for NeMo Guardrails functionality.

**`_rails_engine`** `= IORails(config)`

---

**`events_history_cache`** `dict`

Per-session events history cache.

Used by the server to persist conversation state across requests.
For LLMRails this is stored by reference; assigning replaces the dict
object, not its contents.

IORails is stateless, return empty cache and drop cache-store writes

---

**`explain_info`** `Optional[ExplainInfo]`

Deprecated. Use `explain()` instead.

Direct access can return `None` for an uninitialized accumulator;
`explain()` guarantees a non-None ExplainInfo. Only supported for LLMRails.

---

**`llm`** `Optional[LLMModel]`

The main LLM in use. Only supported for LLMRails.
Read-only; use `update_llm()` to replace it.

---

**`passthrough_fn`** `Optional[Callable]`

The optional passthrough function that bypasses LLM generation.

Only supported for LLMRails. When set, the rails pipeline calls this
function instead of the main LLM for generating responses.

---

**`rails_engine`** `IORails | LLMRails`

Get immutable LLMRails object

---

**`runtime`** `Runtime`

The Colang runtime backing the rails engine. Only supported for LLMRails.

---

**`use_iorails_engine`** `bool`

---

```python
nemoguardrails.guardrails.guardrails.Guardrails.__aenter__()
```

async

Async context manager entry.

```python
nemoguardrails.guardrails.guardrails.Guardrails.__aexit__(
    exc_type,
    exc_val,
    exc_tb
)
```

async

Async context manager exit.

```python
nemoguardrails.guardrails.guardrails.Guardrails.__getstate__()
```

Pickle support: preserve config, verbose, and use\_iorails so the rebuilt
instance lands on the same engine. The llm is dropped (matches LLMRails).

```python
nemoguardrails.guardrails.guardrails.Guardrails.__setstate__(
    state
)
```

Pickle support: rebuild from config + verbose + use\_iorails. Older
pickles missing these keys default to False/True respectively for
backwards compatibility.

```python
nemoguardrails.guardrails.guardrails.Guardrails._convert_to_messages(
    prompt: str | None = None,
    messages: nemoguardrails.guardrails.guardrails_types.LLMMessages | None = None
) -> nemoguardrails.guardrails.guardrails_types.LLMMessages
```

staticmethod

Return messages in standard format, converting a prompt string if needed.

If messages is provided, returns it as-is.
If prompt is provided, wraps it as \[\{"role": "user", "content": prompt}].

```python
nemoguardrails.guardrails.guardrails.Guardrails._ensure_started() -> None
```

async

Lazy initialization: call startup() on first use if not already started.

```python
nemoguardrails.guardrails.guardrails.Guardrails.check(
    messages: typing.List[dict],
    rail_types: typing.Optional[typing.List[nemoguardrails.rails.llm.options.RailType]] = None
) -> nemoguardrails.rails.llm.options.RailsResult
```

Synchronous version of check\_async.
Only supported for LLMRails.

```python
nemoguardrails.guardrails.guardrails.Guardrails.check_async(
    messages: typing.List[dict],
    rail_types: typing.Optional[typing.List[nemoguardrails.rails.llm.options.RailType]] = None
) -> nemoguardrails.rails.llm.options.RailsResult
```

async

Run rails on messages based on their content (asynchronous).
Only supported for LLMRails.

```python
nemoguardrails.guardrails.guardrails.Guardrails.explain() -> nemoguardrails.logging.explain.ExplainInfo
```

Get the latest ExplainInfo object for debugging.
Only supported for LLMRails

```python
nemoguardrails.guardrails.guardrails.Guardrails.generate(
    prompt: str | None = None,
    messages: nemoguardrails.guardrails.guardrails_types.LLMMessages | None = None,
    kwargs = {}
) -> typing.Union[str, dict, nemoguardrails.rails.llm.options.GenerationResponse, typing.Tuple[dict, dict]]
```

Generate an LLM response synchronously with guardrails applied.
Supported in both IORails and LLMRails

```python
nemoguardrails.guardrails.guardrails.Guardrails.generate_async(
    prompt: str | None = None,
    messages: nemoguardrails.guardrails.guardrails_types.LLMMessages | None = None,
    kwargs = {}
) -> str | dict | nemoguardrails.rails.llm.options.GenerationResponse | tuple[dict, dict]
```

async

Generate an LLM response asynchronously with guardrails applied.
Supported by both LLMRails and IORails

```python
nemoguardrails.guardrails.guardrails.Guardrails.generate_events(
    events: typing.List[dict]
) -> typing.List[dict]
```

Synchronous version of generate\_events\_async.
Only supported for LLMRails.

```python
nemoguardrails.guardrails.guardrails.Guardrails.generate_events_async(
    events: typing.List[dict]
) -> typing.List[dict]
```

async

Generate the next events based on the provided history.
Only supported for LLMRails.

```python
nemoguardrails.guardrails.guardrails.Guardrails.process_events(
    events: typing.List[dict],
    state: typing.Union[typing.Optional[dict], nemoguardrails.colang.v2_x.runtime.flows.State] = None,
    blocking: bool = False
) -> typing.Tuple[typing.List[dict], typing.Union[dict, nemoguardrails.colang.v2_x.runtime.flows.State]]
```

Synchronous version of process\_events\_async.
Only supported for LLMRails.

```python
nemoguardrails.guardrails.guardrails.Guardrails.process_events_async(
    events: typing.List[dict],
    state: typing.Union[typing.Optional[dict], nemoguardrails.colang.v2_x.runtime.flows.State] = None,
    blocking: bool = False
) -> typing.Tuple[typing.List[dict], typing.Union[dict, nemoguardrails.colang.v2_x.runtime.flows.State]]
```

async

Process a sequence of events in a given state.
Only supported for LLMRails.

```python
nemoguardrails.guardrails.guardrails.Guardrails.register_action(
    action: typing.Callable,
    name: typing.Optional[str] = None
) -> typing_extensions.Self
```

Register a custom action for the rails configuration.
Only supported for LLMRails. Returns self so calls can be chained.

```python
nemoguardrails.guardrails.guardrails.Guardrails.register_action_param(
    name: str,
    value: typing.Any
) -> typing_extensions.Self
```

Register a custom action parameter.
Only supported for LLMRails. Returns self so calls can be chained.

```python
nemoguardrails.guardrails.guardrails.Guardrails.register_embedding_provider(
    name: typing.Optional[str] = None
) -> typing_extensions.Self
```

Register a custom embedding provider.
Only supported for LLMRails. Returns self so calls can be chained.

```python
nemoguardrails.guardrails.guardrails.Guardrails.register_embedding_search_provider(
    name: str
) -> typing_extensions.Self
```

Register a new embedding search provider.
Only supported for LLMRails. Returns self so calls can be chained.

```python
nemoguardrails.guardrails.guardrails.Guardrails.register_filter(
    filter_fn: typing.Callable,
    name: typing.Optional[str] = None
) -> typing_extensions.Self
```

Register a custom filter for the rails configuration.
Only supported for LLMRails. Returns self so calls can be chained.

```python
nemoguardrails.guardrails.guardrails.Guardrails.register_output_parser(
    output_parser: typing.Callable,
    name: str
) -> typing_extensions.Self
```

Register a custom output parser for the rails configuration.
Only supported for LLMRails. Returns self so calls can be chained.

```python
nemoguardrails.guardrails.guardrails.Guardrails.register_prompt_context(
    name: str,
    value_or_fn: typing.Any
) -> typing_extensions.Self
```

Register a value to be included in the prompt context.
Only supported for LLMRails. Returns self so calls can be chained.

```python
nemoguardrails.guardrails.guardrails.Guardrails.shutdown() -> None
```

async

Lifecycle method to stop the rails engine.

Idempotent: safe to call multiple times.

```python
nemoguardrails.guardrails.guardrails.Guardrails.startup() -> None
```

async

Lifecycle method to start the rails engine.

Idempotent: safe to call multiple times.  Also called automatically
on first `generate_async()` if not called explicitly, so callers
are not required to manage the lifecycle.

The non-streaming admission queue is owned by `IORails` and is
started/stopped as part of `IORails.start()` / `stop()`.

```python
nemoguardrails.guardrails.guardrails.Guardrails.stream_async(
    prompt: str | None = None,
    messages: nemoguardrails.guardrails.guardrails_types.LLMMessages | None = None,
    kwargs = {}
) -> typing.AsyncIterator[str | dict]
```

Generate an LLM response asynchronously with streaming support.

```python
nemoguardrails.guardrails.guardrails.Guardrails.update_llm(
    llm: nemoguardrails.types.LLMModel
) -> None
```

Replace the main LLM with a new one.
Only supported for LLMRails, since IORails doesn't take LLM as argument

```python
nemoguardrails.guardrails.guardrails.log = logging.getLogger(__name__)
```