docs: documentation for langchain decoupling

[Pouyanpi]

Description

Add must-ship 0.22 documentation for the LangChain decoupling: troubleshooting entry for NEMOGUARDRAILS_LLM_FRAMEWORK, 0.22-framework-transition.md migration guide, supported-llms.md routing matrix, and configuration-reference.md engine table split between DefaultFramework and LangChain-routed.

Important

Blocked on #1857.

Summary by CodeRabbit

• Documentation
  • Added routing matrix documenting DefaultFramework and LangChain behavior with installation and configuration requirements
  • Expanded configuration reference with clarified parameter forwarding between frameworks and reorganized engine listings
  • Added comprehensive upgrade guide covering LLM framework transition, migration steps, and runtime configuration controls
  • Enhanced troubleshooting section with framework selection mechanism and environment variable guidance

[github-actions]

Documentation preview

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

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation for NeMo Guardrails 0.22 explaining the new LLM framework routing model. Introduces DefaultFramework for OpenAI-compatible endpoints (httpx-based, no LangChain) and LangChain for other providers, with configuration guidance, engine mappings, runtime controls, and troubleshooting.

Changes

NeMo Guardrails 0.22 Framework Transition Documentation

Layer / File(s)	Summary
Upgrade Guide – Framework Transition docs/upgrade/0.22-framework-transition.md	Comprehensive documentation of 0.22 framework routing rules, DefaultFramework vs LangChain selection criteria, legacy vllm_openai config migration to engine: openai, framework activation via NEMOGUARDRAILS_LLM_FRAMEWORK environment variable and set_default_framework() runtime API, common error messages, and unchanged behaviors (streaming, tool calling, reasoning, custom providers).
Configuration Reference Updates docs/configure-rails/configuration-reference.md	models.parameters description expanded to explain framework-dependent parameter forwarding (DefaultFramework → OpenAI client; LangChain → provider class). "Engines" section restructured to show DefaultFramework vs LangChain-routed engines with selection guidance preferring DefaultFramework for OpenAI-compatible protocols.
Supported LLMs Routing Matrix docs/about/supported-llms.md	New "Routing matrix" section mapping engine names to frameworks with installation/config requirements, streaming, tool call, and reasoning model support notes. Explicit statement that no automatic fallback occurs between DefaultFramework and LangChain.
Troubleshooting Framework Selection docs/troubleshooting.md	New troubleshooting subsection explaining framework registry routing, NEMOGUARDRAILS_LLM_FRAMEWORK environment variable semantics (read once at init), nemoguardrails.set_default_framework(name) runtime API with KeyError behavior, usage guidance for static vs dynamic selection, and link to upgrade walkthrough.
Documentation Navigation docs/index.md	New "Upgrade" toctree block added to Reference section with link to upgrade/0.22-framework-transition.md, positioned between existing Reference entries and Troubleshooting section.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: documentation for langchain decoupling' accurately summarizes the main change—adding documentation for NeMo Guardrails 0.22's LangChain decoupling.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Test Results For Major Changes	✅ Passed	Documentation-only PR (5 markdown files modified). Documentation changes do not require code test results; review and clarity are appropriate verification. No code behavior changes introduced.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/transition-must-ship

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/configure-rails/configuration-reference.md`:
- Line 58: The docs entry for `models.parameters` incorrectly references the
`engine: langchain/<provider>` syntax; update the sentence to remove that
invalid syntax and clarify that LangChain-routed engines should use bare
provider engine names (e.g. `anthropic`, `cohere`) with framework selection
handled separately, while keeping the existing note about DefaultFramework
engines (`openai`, `nim`, `nvidia_ai_endpoints`, `ollama`) passing
OpenAI-compatible params like `temperature`, `max_tokens`, `base_url`,
`api_key`.

In `@docs/upgrade/0.22-framework-transition.md`:
- Around line 211-214: The fenced code block containing the error message is
unlabeled and triggers MD040; update the block to include a language label
(e.g., change ``` to ```text) so the block becomes a labeled fenced code block
with the error lines "ValueError: No default base_url for provider 'cohere'."
and "Set it explicitly in model parameters: parameters.base_url".

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 53463eb7-b6bf-4aca-9af7-0f5510c6caeb

📥 Commits

Reviewing files that changed from the base of the PR and between c69efe5 and 82aaebc.

📒 Files selected for processing (5)

• docs/about/supported-llms.md
• docs/configure-rails/configuration-reference.md
• docs/index.md
• docs/troubleshooting.md
• docs/upgrade/0.22-framework-transition.md

[greptile-apps]

Greptile Summary

This PR adds the must-ship 0.22 documentation set for the LangChain decoupling: a routing matrix, a migration guide, configuration-reference engine table split, troubleshooting entries, and a table-expand UI widget backed by new CSS and JavaScript.

• docs/about/supported-llms.md introduces the Inference Providers routing matrix distinguishing DefaultFramework (built-in) engines from LangChain opt-in engines; docs/migration/0.22.md provides concrete before/after YAML recipes for every migration shape; docs/troubleshooting.md gains a new LLM Framework Routing section covering NEMOGUARDRAILS_LLM_FRAMEWORK, set_default_framework, and three new error entries.
• docs/_static/js/table-expander.js and docs/_static/css/custom.css add a modal-based "Expand table" widget registered in conf.py; the modal implementation is missing an aria-labelledby association and a keyboard focus trap, which are standard WCAG requirements for role="dialog" elements.

Confidence Score: 5/5

Documentation-only PR with no runtime code changes; safe to merge.

All changed files are documentation and static assets. The routing matrix, migration guide, config reference, and troubleshooting entries are accurate and internally consistent. The two findings in the table-expander widget are accessibility gaps in the modal dialog that do not affect documentation correctness or runtime behavior.

docs/_static/js/table-expander.js — the modal dialog is missing ARIA labelling and a keyboard focus trap.

Important Files Changed

Filename	Overview
docs/_static/js/table-expander.js	New IIFE that powers the "Expand table" button feature. Functional but the modal dialog is missing aria-labelledby and a focus trap, both needed for WCAG-compliant keyboard navigation.
docs/_static/css/custom.css	Adds CSS classes for the table-expander modal and button. Styles are clean with responsive breakpoints, hover/focus states, and scroll locking via body.table-expander-modal-open.
docs/about/supported-llms.md	New routing matrix table covering DefaultFramework and LangChain-routed engines. Previously flagged issues (google_genai, azure naming, deepseek ambiguity, URL) were addressed in prior commits.
docs/migration/0.22.md	Comprehensive migration guide covering OpenAI-compatible providers, mixed-shape configs, Azure paths, custom providers, and what didn't change. Well-structured with concrete before/after YAML examples.
docs/configure-rails/configuration-reference.md	Engine section reorganized into Built-in Engines and LangChain Engines tables. google_genai is now present. Embedding Engines table (3 rows) is intentionally a short list; full mapping is deferred to supported-llms.md.
docs/troubleshooting.md	New "LLM Framework Routing" section documents NEMOGUARDRAILS_LLM_FRAMEWORK, set_default_framework, and three new error entries. Wording is accurate and links to the migration guide.
docs/conf.py	Registers the new js/table-expander.js in html_js_files. Change is minimal and correct.
docs/index.md	Adds "Migrating to 0.22" to the Reference toctree. Functional navigation change.
docs/about/release-notes.md	Adds a 0.22.0 section covering the LangChain-optional change, new extension protocols, and the public testing surface. Clean and accurate.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User sets engine in config.yml] --> B{NEMOGUARDRAILS_LLM_FRAMEWORK?}
    B -- default built-in --> C{Engine is OpenAI-compatible?}
    B -- langchain --> F[LangChain framework]
    C -- yes --> D[Built-in httpx client]
    C -- no --> E[ValueError: No default base_url]
    E --> G[Set NEMOGUARDRAILS_LLM_FRAMEWORK=langchain OR use engine: openai + parameters.base_url]
    F --> H[anthropic / azure / cohere / google_genai / vertexai / huggingface_*]
    D --> I[Inference result returned to rails]
    H --> I

Loading

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
docs/_static/js/table-expander.js:27-54
**Modal dialog missing `aria-labelledby` association**

The `createModal()` function sets `role="dialog"` and `aria-modal="true"` on the outer element, but never assigns an `id` to the title `p` element or an `aria-labelledby` attribute on the modal pointing to that `id`. WCAG 4.1.2 and the ARIA `dialog` role both require an accessible name, so screen readers will announce the dialog with no title when it opens. Adding `title.id = "table-expander-modal-title"` in `createModal` and then `modal.setAttribute("aria-labelledby", "table-expander-modal-title")` would satisfy the requirement.

### Issue 2 of 2
docs/_static/js/table-expander.js:57-112
**No focus trap — Tab key exits the open modal**

`openModal` moves initial focus to the close button (`modalParts.closeButton.focus()`), but there is no listener to cycle focus back into the dialog when the user presses Tab past the last focusable element. Keyboard users will tab through the close button and land on links in the obscured page content behind the backdrop, violating WCAG 2.1 SC 2.1.2 (No Keyboard Trap) in the inverse direction. The standard fix is a `keydown` listener that intercepts Tab/Shift-Tab while the modal is open and wraps focus to the last/first focusable descendant of the dialog respectively.

_{Reviews (6): Last reviewed commit: "docs: polish" | Re-trigger Greptile}

[miyoungc]

@Pouyanpi I made lots of changes. I hope it helps explain things with better clarity. Please let me know if anything's incorrect. Approving in case you could make final touch-ups and merge overnight my time.

[miyoungc]

@Pouyanpi -- The docs team's guidance is to put migration guide under Reference.

need to run another review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!