About NeMo Guardrails Library

Release Notes

View as Markdown

The following sections summarize and highlight the changes for the current release. For a complete record of changes in a release, refer to the CHANGELOG.md in the GitHub repository.

0.24.0

Key Features

  • Rail actions can use RailOutcome to return explicit allow, block, and transform decisions. Built-in rails now use declarative rail manifests to describe their configuration, actions, flows, supported surfaces, dependencies, and privacy behavior. For more information, refer to Rail Outcomes and Rail Manifests.

  • IORails adds check() and check_async() for running input and output rails without generating a model response. For non-streaming generation, it returns a structured GenerationResponse when you pass GenerationOptions or an options dictionary; when you omit generation options, it continues to return a role-content message dictionary. For more information, refer to Check Messages, Generation Options, and Engine Feature Support.

  • IORails can run all built-in rail actions whose manifests do not require Colang-specific context variables. For the complete per-rail compatibility matrix, refer to Rail Engine Support.

  • OpenAI-compatible model configurations can set per-model custom headers and query parameters with parameters.default_headers and parameters.default_query. The settings apply to both IORails and LLMRails. For more information, refer to Custom HTTP Headers and Model-Level Query Parameters.

  • You can configure multiple self-check input and output rails, each with its own prompt and model selection. The rails run in configuration order and stop when a rail blocks the content. For more information, refer to LLM Self-Check.

  • Actions and built-in integrations can use a canonical asynchronous HTTP boundary with shared client ownership, retries, metrics, tracing, and deterministic testing support. For more information, refer to Outbound HTTP in Actions.

  • The Guardrails server adds GET /v1/health and GET /healthz liveness endpoints. The /v1/checks endpoint can also validate assistant messages against output rails without running generation. For more information, refer to Run the Guardrails Server and Check Messages.

  • The guardrail catalog adds an F5 AI Guardrails integration for scanning input and output content. It supports configurable retry behavior and fail-open or fail-closed handling for provider errors.

Breaking Changes

  • The output_mapping parameter and its implicit boolean and numeric mappings have been removed from @action. Passing output_mapping now raises TypeError. Return a RailOutcome from rail actions and inspect the outcome explicitly in the consuming flow. For migration examples, refer to Rail Outcomes.

  • When you pass GenerationOptions or an options dictionary to non-streaming IORails.generate() or IORails.generate_async(), the methods return a GenerationResponse. When you omit generation options, they continue to return a role-content message dictionary. Their signatures now accept prompt as the first parameter. Pass message lists with the messages= keyword instead of as the first positional argument.

  • The /v1/checks endpoint no longer accepts inline configurations. Select a server-loaded configuration with config_id, or omit config_id to use the server default.

  • The Chat Completions endpoint now validates role-specific messages at the HTTP boundary. It rejects internal event messages, unexpected fields, unsupported audio requests, and invalid role or content combinations before loading a configuration or dispatching an action. For more information, refer to Chat Completions.

  • Custom Colang 1.0 flows that call the previous space-separated Cleanlab, Fiddler, or GCP action names must use the corresponding snake_case action names. The packaged flows have already been updated for both Colang 1.0 and Colang 2.x.

  • The hf-classifier installation extra has been removed, and its packages are no longer included in the all extra. Install transformers and torch directly to use the local classifier backend. For more information, refer to HuggingFace Classifier Integration.

Enhancements

  • IORails generation logs include activated rails, model calls, timing, token usage, and provider metadata when requested. Streaming responses preserve usage metadata on the final chunk, and the default logger no longer emits verbose operational output.

  • Server responses use OpenAI-compatible error envelopes more consistently, preserve configured main-model fields when a request selects a model, and support developer, multimodal, tool, refusal, context, and function messages where the Chat Completions contract allows them.

  • The documentation site adds immutable, Git-ref-backed versions so you can switch between the latest documentation and stable release snapshots.

Documentation and Behavior Fixes

  • IORails now distinguishes a policy block from a rail execution failure, and streaming output rails fail closed when an action fails. Content-safety response parsing errors are surfaced instead of being treated as successful checks.

  • The /v1/checks endpoint returns HTTP 422 when the requested rail types cannot run for the supplied messages instead of silently returning a passing result.

  • Reasoning-only non-streaming responses are handled correctly, reasoning content is inlined consistently for server responses, and model-level query parameters propagate through IORails requests.

  • Colang argument parsing now raises ValueError for an unbalanced closing bracket instead of accepting malformed input.

Previous Releases