Overview of the NeMo Guardrails Python APIs
The NeMo Guardrails library Python API provides two core classes for running guardrails:
RailsConfig: Loads and manages guardrails configuration from files or content.Guardrails: The main interface for generating responses with guardrails applied. It runs the IORails engine when that engine supports the configuration; otherwise it falls back to the deprecatedLLMRails, unless you passrequire_iorails=Trueor the configuration has per-tool rails, in which case it raisesValueError.
Upon initializing the core classes (RailsConfig and Guardrails), the library loads the configuration files you created in the previous chapter About Configuring Guardrails.
LLMRails, the earlier main interface, is deprecated in 0.25.0; removal is planned no earlier than 0.27.0.
Replace LLMRails(config) with Guardrails(config).
For the steps, refer to Migrating to 0.25.
Quick Start
The following steps show how to run a sample guardrailed chat request using the NeMo Guardrails library Python API.
Prerequisites
Meet the following prerequisites to use the NeMo Guardrails library Python API.
-
If you haven’t already, install the NeMo Guardrails library with the
nvidiaextra, following the instructions in Installation. -
Set up an environment variable for your NVIDIA API key.
This is required to access NVIDIA-hosted models on build.nvidia.com. The provided example configurations (examples/configs) and code examples throughout the documentation use NVIDIA-hosted models.
Run a Sample Guardrailed Chat Request
The following example shows the minimal code to load the content safety example configuration and generate a response using the Guardrails class.
Lifetime and Performance
Construct Guardrails once per process and reuse it across requests.
Construction validates the configuration and compiles the configured rails.
The synchronous generate() and check() methods start a short-lived engine for every call, with tracing and metrics turned off.
They suit scripts.
In a service, start the engine once and call the asynchronous methods.
Starting the engine opens an HTTP session for each configured model and starts the request queue, and later generate_async(), stream_async(), and check_async() calls reuse them.
If your application has its own startup and shutdown hooks, call await rails.startup() and await rails.shutdown() from them instead of using async with.
For serverless or FaaS handlers, create the Guardrails instance in module scope so that warm invocations skip loading and validating the configuration:
The synchronous generate() still starts a short-lived engine for each invocation.
If your platform keeps one event loop running across invocations, make the handler asynchronous and call await _rails.generate_async(...) instead, so that warm invocations reuse the running engine.
When to Use Each API
Synchronous vs Asynchronous
The NeMo Guardrails library provides both synchronous and asynchronous methods:
Use asynchronous methods (generate_async(), stream_async(), check_async()) in async contexts for better performance. The synchronous generate() and check() methods cannot be called from within an async context.