feat: add reasoning guardrail connector

[makeshn]

Description

This PR adds a new Reasoning Guardrail Connector for the nvidia/Nemotron-Content-Safety-Reasoning-4B model.

Key Changes:

• Added a new model type content_safety_reasoning that integrates with the Nemotron Content Safety Reasoning model
• Added support for reasoning mode toggle (/think vs /no_think) via config option
• Added new output parsers (nemotron_reasoning_parse_prompt_safety, nemotron_reasoning_parse_response_safety) for parsing the model's safety classification output
• Added example configuration demonstrating content safety checks on both input and output flows as well as reasoning off and reasoning on modes.
• Tutorial showing how to serve and setup the model via vLLM with OpenAI-compatible API

Checklist

• I've read the CONTRIBUTING guidelines.
• I've updated the documentation if applicable.
• I've added tests if applicable.
• @mentions of the person or team responsible for reviewing proposed changes.

[github-actions]

Documentation preview

https://nvidia-nemo.github.io/Guardrails/review/pr-1565

[greptile-apps]

Greptile Summary

This PR adds a new Reasoning Guardrail Connector for the nvidia/Nemotron-Content-Safety-Reasoning-4B model, enabling content safety checks with optional reasoning traces.

Key changes:

• Added two new output parsers (nemotron_reasoning_parse_prompt_safety and nemotron_reasoning_parse_response_safety) to parse the model's "harmful/unharmful" output format and strip <think> tags
• Added ReasoningConfig to the configuration schema to allow toggling between reasoning on/off modes via rails.config.content_safety.reasoning.enabled
• Exposed config.rails.config in Jinja2 template rendering context (in taskmanager.py:138) to allow templates to access configuration settings
• Provided comprehensive example configuration demonstrating both input and output rails with the new model type
• Added detailed tutorial documentation explaining deployment with vLLM and configuration options

Issue found:
The example prompts.yml file uses an undefined variable reasoning_mode instead of config.content_safety.reasoning.enabled, which will cause the template rendering to fail or default incorrectly. The documentation shows the correct usage.

Confidence Score: 3/5

• This PR has a critical bug in the example configuration that will prevent the reasoning mode toggle from working correctly
• The core implementation (output parsers, config schema, taskmanager changes) is solid and well-structured. However, the example prompts.yml contains a template variable error that references an undefined variable (reasoning_mode) instead of the correct path (config.content_safety.reasoning.enabled). This inconsistency between the example and documentation will cause confusion and broken functionality for users following the example.
• examples/configs/content_safety_reasoning/prompts.yml requires fixes to use the correct template variable path

Important Files Changed

Filename	Overview
nemoguardrails/llm/output_parsers.py	Added two new output parsers (nemotron_reasoning_parse_prompt_safety and nemotron_reasoning_parse_response_safety) with helper functions for parsing Nemotron Content Safety Reasoning model outputs
nemoguardrails/llm/taskmanager.py	Registered new output parsers and exposed config.rails.config object in template rendering context to enable access to configuration settings
nemoguardrails/rails/llm/config.py	Added ReasoningConfig model to support reasoning mode toggle for content safety models
examples/configs/content_safety_reasoning/prompts.yml	Prompt templates for content safety checks - uses incorrect variable reasoning_mode instead of config.content_safety.reasoning.enabled

Sequence Diagram

sequenceDiagram
    participant User
    participant LLMRails
    participant TaskManager
    participant ContentSafetyModel as Nemotron-4B
    participant MainLLM
    
    User->>LLMRails: generate(message)
    
    Note over LLMRails,TaskManager: Input Rail Flow
    LLMRails->>TaskManager: render_task_prompt("content_safety_check_input")
    TaskManager->>TaskManager: Apply template with config.content_safety.reasoning.enabled
    TaskManager-->>LLMRails: Prompt with /think or /no_think
    
    LLMRails->>ContentSafetyModel: Check input safety
    ContentSafetyModel-->>LLMRails: "Prompt harm: harmful/unharmful"
    
    LLMRails->>TaskManager: parse_task_output(output)
    TaskManager->>TaskManager: nemotron_reasoning_parse_prompt_safety()
    TaskManager->>TaskManager: Strip <think> tags, extract harm value
    TaskManager-->>LLMRails: [True] or [False]
    
    alt Input is safe
        LLMRails->>MainLLM: Generate response
        MainLLM-->>LLMRails: Response text
        
        Note over LLMRails,TaskManager: Output Rail Flow
        LLMRails->>TaskManager: render_task_prompt("content_safety_check_output")
        TaskManager-->>LLMRails: Prompt with /think or /no_think
        
        LLMRails->>ContentSafetyModel: Check output safety
        ContentSafetyModel-->>LLMRails: "Response Harm: harmful/unharmful"
        
        LLMRails->>TaskManager: parse_task_output(output)
        TaskManager->>TaskManager: nemotron_reasoning_parse_response_safety()
        TaskManager-->>LLMRails: [True] or [False]
        
        alt Output is safe
            LLMRails-->>User: Response
        else Output is unsafe
            LLMRails-->>User: "I'm sorry, I can't respond to that."
        end
    else Input is unsafe
        LLMRails-->>User: "I'm sorry, I can't respond to that."
    end

Loading

[greptile-apps]

_{9 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[codecov]

Codecov Report

❌ Patch coverage is 96.55172% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...oguardrails/llm/providers/huggingface/streamers.py	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Pouyanpi]

Thanks a lot @makeshn , this is great 🚀

I just made a minor change based on my comment above and added tests. Let me know if you see any issues, we can revert/change.

Please look at the tests to ensure the assertions are aligned with you expectations. As I cannot run it myself, would you please to run it and pass some inputs to see everything is still working. Thanks 👍🏻

[trebedea]

Looks good, some suggestions.

[Pouyanpi]

@makeshn you're right about streamers.py (I'm going to revert this commit)

@tgasser-nv you can reproduce the type checking bug on develop :

poetry install --with dev
poetry run pip install transformers

and when you do

poetry run pyright

or

poetry run pre-commit run --all-files

you will see

WARNING: there is a new pyright version available (v1.1.405 -> v1.1.408).
Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`

//nemoguardrails-project/develop/nemoguardrails/llm/providers/huggingface/streamers.py
  //nemoguardrails-project/develop/nemoguardrails/llm/providers/huggingface/streamers.py:22:9 - error: Type "type[transformers.generation.streamers.TextStreamer]" is not assignable to declared type "type[nemoguardrails.llm.providers.huggingface.streamers.TextStreamer]"
    "transformers.generation.streamers.TextStreamer" is not assignable to "nemoguardrails.llm.providers.huggingface.streamers.TextStreamer"
    Type "type[transformers.generation.streamers.TextStreamer]" is not assignable to type "type[nemoguardrails.llm.providers.huggingface.streamers.TextStreamer]" (reportAssignmentType)
//nemoguardrails-project/develop/nemoguardrails/tracing/adapters/filesystem.py
  //nemoguardrails-project/develop/nemoguardrails/tracing/adapters/filesystem.py:63:20 - warning: Import "aiofiles" could not be resolved from source (reportMissingModuleSource)
1 error, 1 warning, 0 informations