Skip to content

v0.25.0

Latest

Choose a tag to compare

@Pouyanpi Pouyanpi released this 19 Nov 09:28
· 1 commit to develop since this release
036b11d

What's Changed

NeMo Guardrails 0.25.0 adds checks for agent tool calls and results, a hooks server for Claude Code, Codex, and NeMo Relay, and the NeMo Guardrails Gateway for applying input and output checks around existing model APIs. New rails provide LLM-judged tool safety, CEL expressions, and language-based filtering; Zscaler AI Guard moderation is also available again.

The gateway supports buffered and streaming OpenAI Chat Completions and Responses, with explicitly selected LiteLLM dialects. Its shipped inspection profile is limited to one user text input and one assistant text output. It does not enable general conversation-history, tool, audio, or image inspection; reviewed opaque metadata is forwarded without inspection.

Upgrade notes

  • Use Python 3.11 through 3.13; Python 3.10 is no longer supported.
  • Model-based jailbreak detection blocks messages beyond 2,048 tokens, including special tokens. Keep each message within that limit and ensure tokenizers is installed. Detector outages and invalid results now stop requests with an internal-error response; check-only callers must enforce the blocked result.
  • Automatic event-loop patching requires the optional nemoguardrails[nest-asyncio] extra when enabled. Prefer async APIs inside an existing event loop. Ordinary synchronous calls outside a running loop remain supported.

Direct LLMRails use and the Colang runtimes are deprecated, with removal planned no earlier than 0.27.0. Use Guardrails with IORails where the configuration is supported. IORails does not run dialog flows or custom actions, and Colang 2.x has no replacement runtime. The release includes a migration guide and diagnostics for ignored configuration; these features continue to work in this release.

🚀 Features

  • (gateway) Add the experimental NeMo Guardrails Gateway for buffered OpenAI Chat Completions, preserving accepted provider payloads while inspecting one user text input and one assistant text output (#2404, #2405, #2406, #2407, #2413, #2414, #2453)
  • (gateway) Describe provider inspection boundaries in exportable guard contracts (#2411)
  • (gateway) Guard OpenAI Chat Completions streams through windowed text inspection while preserving accepted SSE bytes (#2434, #2435, #2436, #2437)
  • (gateway) Add an explicitly selected LiteLLM Chat Completions dialect for reviewed provider extensions (#2454)
  • (gateway) Compose multiple provider instances with distinct routes and upstreams (#2456)
  • (gateway) Allow applications to supply gateway HTTP transports and local routes (#2457)
  • (gateway) Preload declared Rails configurations and select them through trusted request-context resolution (#2458)
  • (gateway) Add buffered and streaming OpenAI Responses inspection for the supported single-text profile (#2465)
  • (gateway) Add an explicitly selected LiteLLM Responses dialect with reviewed streaming metadata (#2466)
  • (gateway) Compose gateway providers, operations, dialects, and Rails configurations through typed Python declarations (#2467)
  • (gateway) Validate, inspect, and serve gateway applications from YAML manifests (#2468)
  • (hooks) Add a hooks server for pre-tool-use checks through configured Claude Code and Codex hooks, and NeMo Relay plugins (#2472, #2473)
  • (hooks) Add tool and argument allowlists and blocklists, with model-free policy and per-tool checks (#2482)
  • (hooks) Export hooks-server admission-queue metrics through Prometheus (#2483)
  • (relay) Add a native NeMo Relay plugin that checks Relay-managed tool calls through the hooks server (#2489, #2493)
  • (cel) Add CEL expressions for per-tool argument and result checks (#2430)
  • (checks) Return IORails block reasons from /v1/checks (#2418)
  • (checks) Add explicit tool-call and tool-result checks with structured tool_violations from /v1/checks on IORails (#2420)
  • (config) Validate model references in global and per-tool rails when loading configuration (#2460)
  • (iorails) Scope tool-call and tool-result rails to individual tools, including regex-based checks (#2377)
  • (iorails) Honor parallel execution settings for per-tool call and result rails (#2393)
  • (language-detector) Add an input rail that allows or blocks detected languages and supports localized refusals (#2470)
  • (library) Restore Zscaler AI Guard input and output moderation through the shared rail contract (#2376)
  • (llmrails) Support tool-call round trips without passthrough mode (#2188)
  • (server) Expose IORails non-streaming admission-queue metrics through a Prometheus scrape endpoint (#2366)
  • (streaming) Add completed and incremental structured tool-call events; LLMRails supports incremental delivery, but rejects streamed tool calls when output or tool-call rails are enabled (#2278)
  • (tool-safety-check) Add LLM-judged checks for individual tools' arguments and results (#2386)

🐛 Bug Fixes

  • (gateway) Preserve reviewed LiteLLM translated metadata and encrypted reasoning items in Chat Completions responses and streams (#2529)
  • (gateway) Accept reviewed response image metadata without enabling image inspection, and reject unsupported prompt-cache prewarming before dispatch (#2561)
  • (gateway) Preserve reviewed input_transformations response metadata in Responses and LiteLLM contracts (#2603)
  • (hooks) Keep LLM-judge tool arguments out of hooks-server default logs (#2556)
  • (hooks) Refuse hooks-server allowlists without an explicit allow_unlisted_tools choice; set it to false to deny unlisted tools or true to allow them (#2592)
  • (relay) Require NeMo Relay 0.11.0-rc.1 or later 0.x releases for the native plugin so permission prompts do not trigger duplicate checks (#2538)
  • (checks) Record transformed check messages on the OpenTelemetry request span (#2440)
  • (config) Warn about unsupported configuration keys and suggest supported names (#2587)
  • (dependencies) [breaking] Make nest-asyncio an optional compatibility extra; install nemoguardrails[nest-asyncio] when enabling automatic event-loop patching, or use async APIs inside a running loop (#2557)
  • (generation-log) Handle missing durations when printing generation summaries (#2338)
  • (hf-classifier) Evaluate oversized local text-classification inputs through overlapping token windows when truncation is not configured (#2545)
  • (injection-detection) Block injection detections when configured omission cannot safely remove all matches (#2558)
  • (injection-detection) Prevent occurrence-order bypasses in Python, Jinja, and XSS detection and recheck omitted text before allowing it (#2559)
  • (iorails) Accept tool results without a name when their call ID links to the original tool call (#2417)
  • (iorails) Retain resources for retryable cleanup after interrupted startup or shutdown (#2459)
  • (iorails) [breaking] Emit completed streaming tool calls as ToolCallChunk objects instead of JSON text; update stream consumers to handle structured events (#2512)
  • (iorails) Honor explicitly configured model parameters.api_key values (#2531)
  • (jailbreak) [breaking] Reject model-detector inputs over 2,048 tokens including special tokens; keep messages within this limit and provide tokenizers for coverage validation (#2560)
  • (jailbreak) [breaking] Stop requests with an internal-error response when jailbreak detection is unavailable or returns invalid results; handle detector failures instead of continuing unchecked (#2588)
  • (llmrails) Terminate streaming when parallel output rails fail to execute (#2562)
  • (llmrails) Report unchanged content lists as passed rather than modified in check results (#2604)
  • (sensitive-data-detection) Run blocking Presidio detection work outside the async event loop (#2400)
  • (server) Support streaming tool-call requests with rail validation before SSE delivery (#2507)
  • (server) Emit terminal SSE error frames when rail execution fails (#2513)
  • (server) Forward max_completion_tokens to the main LLM (#2551)

💼 Other

  • (dependencies) [breaking] Drop Python 3.10 support; upgrade to a supported Python version from 3.11 through 3.13 (#2573)
  • (llmrails) Deprecate direct LLMRails use and Colang 2.x with removal no earlier than 0.27.0, and warn about configuration that IORails ignores (#2593)

🚜 Refactor

  • (rails) Rename tool_output and tool_input configuration and generation-option fields to tool_call and tool_result, retaining deprecated aliases (#2312)

📚 Documentation

  • (gateway) Document gateway setup, supported provider profiles, and deployment boundaries (#2508)
  • (hooks) Document hooks-server configuration, agent integration, and tool-policy enforcement (#2488)
  • (relay) Document installation and configuration of the native NeMo Relay plugin (#2523)
  • (checks) Document /v1/checks tool-call and tool-result requests and structured violations (#2548)
  • (examples) Update content-safety tutorials and notebooks for Nemotron 3.5 Content Safety, including text and image examples (#2442)
  • (llmrails) Document the 0.25 migration to Guardrails and IORails, including LLMRails and Colang runtime deprecations and unsupported capabilities (#2595)

New Contributors

Full Changelog: v0.24.1...v0.25.0