docs: add guide for bot reasoning guardrails

[Pouyanpi]

Related Issue(s)

#1427
#1431
#1432
#1434

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-1479

[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 adds documentation for a new feature that allows developers to access and guardrail bot reasoning traces (exposed via the bot_thinking variable). The documentation covers three access methods - Colang flows, Python actions, and prompt templates - with examples ranging from simple pattern matching to complete self-check output implementations. The guide fits naturally into the advanced user guides section alongside other specialized guardrail features like bot-message-instructions and tools-integration, following the established pattern of documenting complex features with progressive examples and reference implementations.

PR Description Notes:

• The description, related issues, and checklist are all empty/unchecked. Consider adding a brief explanation of what bot thinking/reasoning guardrails are and why this documentation was added.

Important Files Changed

Filename	Score	Overview
docs/index.md	1/5	Adds new bot-thinking-guardrails page to TOC but contains critical typo: 'advaced' instead of 'advanced' in file path
docs/user-guides/advanced/bot-thinking-guardrails.md	4/5	Comprehensive new documentation guide explaining bot_thinking variable access patterns with examples and reference implementations

Confidence score: 1/5

• This PR contains a critical typo that will break the documentation build and must be fixed before merging.
• Score reflects a single-character typo in the TOC file path ('advaced' vs 'advanced') that will prevent Sphinx/MkDocs from locating the new documentation file, causing build failures.
• The docs/index.md file requires immediate attention to correct line 71 from user-guides/advaced/bot-thinking-guardrails to user-guides/advanced/bot-thinking-guardrails to match the actual file location.

Sequence Diagram

sequenceDiagram
    participant User
    participant LLMRails
    participant ReasoningLLM as Reasoning LLM<br/>(Main Model)
    participant OutputRails as Output Rails
    participant ColangFlow as Colang Flow<br/>(check_reasoning)
    participant CustomAction as Custom Action<br/>(check_reasoning_quality)
    participant SelfCheckLLM as Self-Check LLM<br/>(Moderation)
    participant PromptTemplate as Prompt Template

    User->>LLMRails: Send user message
    LLMRails->>ReasoningLLM: Generate response with reasoning
    ReasoningLLM-->>LLMRails: Return response + reasoning trace
    LLMRails->>LLMRails: Extract reasoning to $bot_thinking variable
    
    alt Output Rails with Colang Flow
        LLMRails->>OutputRails: Trigger output rails
        OutputRails->>ColangFlow: Execute flow with $bot_thinking
        ColangFlow->>ColangFlow: Check if "confidential" in $bot_thinking
        alt Contains sensitive content
            ColangFlow-->>OutputRails: Block response
            OutputRails-->>LLMRails: bot refuse to respond
        else Safe content
            ColangFlow-->>OutputRails: Allow response
        end
    end
    
    alt Output Rails with Custom Action
        LLMRails->>OutputRails: Trigger output rails
        OutputRails->>CustomAction: execute check_reasoning_quality(context)
        CustomAction->>CustomAction: Get context.get("bot_thinking")
        CustomAction->>CustomAction: Check forbidden patterns
        alt Forbidden pattern found
            CustomAction-->>OutputRails: Return False
            OutputRails-->>LLMRails: bot refuse to respond
        else Safe reasoning
            CustomAction-->>OutputRails: Return True
        end
    end
    
    alt Self-Check Output with Reasoning
        LLMRails->>OutputRails: Trigger self check output
        OutputRails->>PromptTemplate: Render prompt with {{ bot_thinking }}
        PromptTemplate-->>OutputRails: Prompt includes bot_response and bot_thinking
        OutputRails->>SelfCheckLLM: Send prompt for moderation
        SelfCheckLLM->>SelfCheckLLM: Evaluate response and reasoning
        alt Should block
            SelfCheckLLM-->>OutputRails: "Yes"
            OutputRails-->>LLMRails: Block response
        else Should allow
            SelfCheckLLM-->>OutputRails: "No"
            OutputRails-->>LLMRails: Allow response
        end
    end
    
    LLMRails-->>User: Return final response or refusal

Loading

_{2 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Greptile Overview

Greptile Summary

This review covers only the changes made since the last review, not the entire PR. A critical syntax error was introduced on line 10 of docs/index.md where an HTML comment closing tag is malformed (<!-- end-documentation-reuse -- missing the closing >). This will almost certainly break the documentation build process. The previously identified typo on line 71 (path correction from 'advaced' to 'advanced') appears to remain unfixed. No other files were modified in this iteration.

Important Files Changed

Filename	Score	Overview
docs/index.md	1/5	Introduced a malformed HTML comment tag on line 10 that will likely break documentation builds; typo fix on line 71 may still be pending

Confidence score: 0/5

• This PR will almost certainly cause immediate documentation build failures and should not be merged in its current state.
• Score reflects a critical syntax error (malformed HTML comment on line 10) that will break the Sphinx/MkDocs build pipeline, making the documentation generation fail completely.
• Pay immediate attention to docs/index.md line 10—the comment tag must be properly closed as <!-- end-documentation-reuse --> before this can be merged.

Additional Comments (1)

1. docs/index.md, line 10 (link)

   syntax: incomplete closing comment tag: missing closing >

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Greptile Overview

Greptile Summary

This review covers only the changes made since the last review, not the entire PR. The developer has addressed previous feedback by updating GitHub repository links from commit-specific URLs to branch-based URLs (develop). Specifically, the links on lines 146 and 200 were changed to match the branch-based format already used on line 194, ensuring consistency and maintainability across all three reference links in the documentation. This change ensures that all documentation links point to the current codebase rather than historical snapshots.

Important Files Changed

Filename	Score	Overview
docs/user-guides/advanced/bot-thinking-guardrails.md	5/5	Updated two GitHub links from commit-specific to branch-based URLs for consistency

Confidence score: 5/5

• This PR is safe to merge with minimal risk
• All previous style and consistency issues have been resolved; the changes are purely documentation link updates with no code impact
• No files require special attention

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[miyoungc]

Doc edit PR: #1484