nemoguardrails.guardrails.guardrails | NVIDIA NeMo Guardrails Library Developer Guide

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`	Top-level interface for NeMo Guardrails functionality.

Data

log

API

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

Top-level interface for NeMo Guardrails functionality.

_rails_engine

= IORails(config)

events_history_cache

dict

Per-session events history cache. Only supported for LLMRails.

Used by the server to persist conversation state across requests. Stored by reference; assigning replaces the dict object, not its contents.

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

nemoguardrails.guardrails.guardrails.Guardrails.__aenter__()

async

Async context manager entry.

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

async

Async context manager exit.

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).

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.

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}].

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

async

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

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.

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.

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

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

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

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

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

Synchronous version of generate_events_async. Only supported for LLMRails.

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.

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.

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.

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

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

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

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

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

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.

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.

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

async

Lifecycle method to stop the rails engine.

Idempotent: safe to call multiple times.

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().

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.

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

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