docs: update LLM reasoning traces config guidance

[Pouyanpi]

Refactor documentation for reasoning traces in LLM configuration guide:

• Remove deprecated reasoning_config and apply_to_reasoning_traces fields.
• Add warning about breaking changes in v0.18.0.
• Explain new approach using output rails for reasoning traces.
• Provide updated YAML and Python usage examples.
• Clarify how to access reasoning traces in API responses.
• Remove outdated configuration and prompt samples.

[github-actions]

Documentation preview

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

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Overview

Greptile Summary

This PR refactors the reasoning traces documentation in the LLM configuration guide to reflect v0.18.0 breaking changes. The deprecated reasoning_config and apply_to_reasoning_traces fields are removed in favor of a simpler output-rails-based approach. The framework now auto-extracts reasoning traces from supported models and exposes them via $bot_thinking (Colang context) and bot_thinking (Python/Jinja2), eliminating complex configuration tables (~50 lines) in favor of focused examples. Two API access patterns are documented: structured access via GenerationOptions/GenerationResponse.reasoning_content for new code, and backward-compatible tagged-string access with <think> tags. This aligns with the broader NeMo Guardrails architecture where guardrails are applied uniformly through rails configurations rather than model-specific flags.

Important Files Changed

Filename	Score	Overview
docs/user-guides/configuration-guide/llm-configuration.md	4/5	Refactored reasoning traces section, removed deprecated config fields, added breaking change warning, and provided two clear API access patterns with YAML/Python examples.

Confidence score: 4/5

• This PR is safe to merge with minimal risk once the cross-reference is verified.
• Score reflects clear documentation improvements and proper deprecation warnings, but deducted one point because the referenced guide ../../advanced/bot-thinking-guardrails.md should be confirmed to exist, and variable naming consistency between $bot_thinking (Colang) and bot_thinking (Python/Jinja2) contexts should be validated.
• Pay close attention to verifying that the cross-referenced file path ../../advanced/bot-thinking-guardrails.md exists in the repository structure and that the variable naming convention is consistent across Colang and Python contexts throughout the codebase.

Sequence Diagram

sequenceDiagram
    participant User
    participant RailsConfig
    participant LLMRails
    participant ReasoningLLM as Reasoning LLM<br/>(e.g., DeepSeek-R1)
    participant OutputRails as Output Rails<br/>(self_check_output)
    participant API as API Response

    User->>RailsConfig: "Load config with<br/>reasoning-capable model"
    RailsConfig->>LLMRails: "Initialize with<br/>nim engine + model"
    
    User->>LLMRails: "generate_async(messages,<br/>options=GenerationOptions())"
    LLMRails->>ReasoningLLM: "Send user query"
    ReasoningLLM->>ReasoningLLM: "Generate response with<br/><think>reasoning</think>"
    ReasoningLLM->>LLMRails: "Return response +<br/>reasoning traces"
    
    LLMRails->>LLMRails: "Extract reasoning to<br/>$bot_thinking variable"
    LLMRails->>OutputRails: "Check output with<br/>bot_response + bot_thinking"
    OutputRails->>OutputRails: "Evaluate reasoning traces<br/>against policy"
    
    alt Reasoning or output blocked
        OutputRails->>LLMRails: "Block response"
        LLMRails->>API: "Return blocked message"
    else Passes guardrails
        OutputRails->>LLMRails: "Approve response"
        LLMRails->>API: "Return GenerationResponse<br/>(reasoning_content, response)"
    end
    
    API->>User: "Structured response with<br/>separate reasoning field"
    
    Note over User,API: Alternative: Without GenerationOptions<br/>returns response with inline <think> tags

Loading

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[miyoungc]

Please review and merge the doc edit PR: #1489

[greptile-apps]

Greptile Overview

Greptile Summary

This PR refactors the LLM reasoning traces documentation to reflect breaking changes in v0.18.0. The deprecated reasoning_config and apply_to_reasoning_traces fields are clearly marked with deprecation warnings, and the documentation now explains the new approach using output rails with $bot_thinking/bot_thinking variables.

Key changes:

• Added clear deprecation notice for v0.18.0 breaking changes
• Replaced complex configuration tables with straightforward output rails examples
• Added comprehensive examples for accessing reasoning traces with and without GenerationOptions
• Provided guidance on when to use each approach based on use case
• Updated YAML and Python code examples to match current implementation
• Removed outdated prompt samples and configuration details

The documentation now provides a clearer migration path for users and better explains how to work with reasoning-capable LLMs like DeepSeek-R1 and Nemotron Ultra.

Confidence Score: 4/5

• Safe to merge with one broken link that needs fixing
• Documentation is well-structured and accurate based on code verification, but contains a broken reference link to a non-existent file
• Line 120 references a non-existent file that must be fixed before merge

Important Files Changed

File Analysis

Filename	Score	Overview
docs/user-guides/configuration-guide/llm-configuration.md	5/5	Updated reasoning traces documentation to reflect v0.18.0 changes - deprecated old config fields, added new output rails approach with clear examples

Sequence Diagram

sequenceDiagram
    participant User
    participant LLMRails
    participant ReasoningLLM
    participant OutputRails
    participant Response
    
    User->>LLMRails: generate_async(messages, options)
    LLMRails->>ReasoningLLM: Send user query
    ReasoningLLM-->>LLMRails: Response with <think>reasoning</think>content
    LLMRails->>LLMRails: Extract reasoning traces
    LLMRails->>LLMRails: Set $bot_thinking variable
    LLMRails->>OutputRails: Check output (bot_response + bot_thinking)
    OutputRails-->>LLMRails: Approval/Block decision
    alt With GenerationOptions
        LLMRails->>Response: GenerationResponse object
        Response-->>User: {reasoning_content, response}
    else Without GenerationOptions
        LLMRails->>Response: String with tags
        Response-->>User: <think>reasoning</think>content
    end

Loading

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}