docs: document AI-Q 2.2 candidate scope - #322
Conversation
|
Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually. Contributors can view more details about this message here. |
WalkthroughThis documentation-only PR aligns AI-Q materials with the v2.2 candidate scope, covering deep research, durable artifacts, OpenSearch, guardrails, MCP, deployment, integrations, examples, observability, and release navigation. ChangesRelease metadata and navigation
Deep research workflow and prompt contracts
Sandbox artifacts and REST event contracts
Knowledge layer and OpenSearch backend
Policy, MCP, and agent skills guidance
Deployment, examples, and observability
Estimated code review effort: 3 (Moderate) | ~25 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
AjayThorve
added
documentation
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 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/source/customization/knowledge-layer.md`:
- Around line 167-168: The Markdown section before the OpenSearch YAML block is
missing the required blank line separator, which will trigger MD031. Update the
content around the OpenSearch heading so there is an empty line between the
bolded text and the YAML fenced block, keeping the surrounding docs formatting
consistent.
In `@docs/source/customization/prompts.md`:
- Around line 124-130: Move the `parent_report_context_available` entry out of
the orchestrator prompt table and into the writer prompt table in the docs,
since `factory.py` sends this flag to the writer subagent rather than the
orchestrator. Update the surrounding table entries in `prompts.md` so the
orchestrator inventory only lists fields actually used there, and ensure the
writer section includes `parent_report_context_available` alongside the other
writer-specific inputs.
In `@docs/source/customization/tools-and-sources.md`:
- Around line 91-103: The no-catalog fallback prose is inaccurate and should
match the behavior in source_routing.py. Update the documentation around the
domain table and fallback paragraph to describe the actual default path in the
source-routing logic: when no catalog file is configured, the router builds the
general_research route, filters preferred sources against the active tool set,
and selects web_search or the first available mapped source as fallback. Also
remove the mention of an unconfigured domain so the description aligns with the
routing behavior implemented in the source_routing flow.
🪄 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: ASSERTIVE
Plan: Enterprise
Run ID: ac475c55-842e-44c6-bdbf-ad4a337d2a4e
📒 Files selected for processing (30)
.secrets.baselineCHANGELOG.mdREADME.mddocs/source/architecture/agents/deep-researcher.mddocs/source/architecture/agents/index.mddocs/source/architecture/agents/sandbox.mddocs/source/architecture/data-flow.mddocs/source/architecture/index.mddocs/source/architecture/overview.mddocs/source/customization/configuration-reference.mddocs/source/customization/guardrails.mddocs/source/customization/index.mddocs/source/customization/knowledge-layer.mddocs/source/customization/mcp-tools.mddocs/source/customization/prompts.mddocs/source/customization/tools-and-sources.mddocs/source/deployment/aws-opensearch-serverless.mddocs/source/examples/cli-with-local-nims.mddocs/source/examples/index.mddocs/source/examples/skills-sandbox/index.mddocs/source/get-started/installation.mddocs/source/get-started/quick-start.mddocs/source/index.mddocs/source/integration/agent-skills.mddocs/source/integration/rest-api.mddocs/source/profiling/index.mddocs/source/resources/changelog.mddocs/source/resources/faq.mddocs/source/resources/release-notes.mdsrc/aiq_agent/agents/deep_researcher/README.md
📜 Review details
⚠️ CI failures not shown inline (2)
GitHub Actions: AIQ CI / Script Validation: docs: correct durable artifact event shape
Conclusion: failure
##[group]Run . .venv/bin/activate
�[36;1m. .venv/bin/activate�[0m
�[36;1mchmod +x ci/scripts/test_scripts.sh�[0m
�[36;1mci/scripts/test_scripts.sh --skip-setup�[0m
shell: /usr/bin/bash -e {0}
env:
pythonLocation: /opt/hostedtoolcache/Python/3.13.14/x64
PKG_CONFIG_PATH: /opt/hostedtoolcache/Python/3.13.14/x64/lib/pkgconfig
Python_ROOT_DIR: /opt/hostedtoolcache/Python/3.13.14/x64
Python2_ROOT_DIR: /opt/hostedtoolcache/Python/3.13.14/x64
Python3_ROOT_DIR: /opt/hostedtoolcache/Python/3.13.14/x64
LD_LIBRARY_PATH: /opt/hostedtoolcache/Python/3.13.14/x64/lib
UV_CACHE_DIR: /home/runner/work/_temp/setup-uv-cache
##[endgroup]
================================================
AI-Q Blueprint - Script Tests
================================================
Repository: /home/runner/work/aiq/aiq
Scripts: /home/runner/work/aiq/aiq/scripts
============================================
Testing Bash Syntax
============================================
�[0;32m✅ PASS�[0m: dev.sh - valid bash syntax
�[0;32m✅ PASS�[0m: setup.sh - valid bash syntax
�[0;32m✅ PASS�[0m: setup_openshell.sh - valid bash syntax
�[0;32m✅ PASS�[0m: start_as_skill.sh - valid bash syntax
�[0;32m✅ PASS�[0m: start_cli.sh - valid bash syntax
�[0;32m✅ PASS�[0m: start_e2e.sh - valid bash syntax
�[0;32m✅ PASS�[0m: start_server_in_debug_mode.sh - valid bash syntax
�[1;33m⏭️ SKIP�[0m: setup.sh - skipped (--skip-setup flag)
============================================
Testing --help Flags
============================================
�[0;32m✅ PASS�[0m: start_cli.sh --help
�[0;32m✅ PASS�[0m: start_server_in_debug_mode.sh --help
============================================
Testing Virtual Environment Checks
============================================
�[0;32m✅ PASS�[0m: start_cli.sh - venv check works
�[0;32m✅ PASS�[0m: start_server_in_debug_mode.sh - venv check works
============================================
Testing Pytest Integration
=====================...
GitHub Actions: AIQ CI / 3_Script Validation.txt: docs: correct durable artifact event shape
Conclusion: failure
Current runner version: '2.335.1'
##[group]Runner Image Provisioner
Hosted Compute Agent
Version: 20260624.560
Commit: 925d229a51159bc391ae97e54a2dd1fe20af789d
Build Date:
Worker ID: {e3ffda1b-55cd-4a33-a728-f5de9568e34b}
Azure Region: eastus
##[endgroup]
##[group]Operating System
Ubuntu
24.04.4
LTS
##[endgroup]
##[group]Runner Image
Image: ubuntu-24.04
Version: 20260628.225.1
Included Software: https://github.com/actions/runner-images/blob/ubuntu24/20260628.225/images/ubuntu/Ubuntu2404-Readme.md
Image Release: https://github.com/actions/runner-images/releases/tag/ubuntu24%2F20260628.225
##[endgroup]
##[group]GITHUB_TOKEN Permissions
Contents: read
Metadata: read
##[endgroup]
Secret source: Actions
Prepare workflow directory
Prepare all required actions
Getting action download info
Download action repository 'actions/checkout@v4' (SHA:34e114876b0b11c390a56381ad16ebd13914f8d5)
Download action repository 'actions/setup-python@v5' (SHA:a26af69be951a213d495a4c3e4e4022e16d87065)
Download action repository 'astral-sh/setup-uv@v4' (SHA:38f3f104447c67c051c4a08e39b64a148898af3a)
Complete job name: Script Validation
Node 20 is being deprecated. This workflow is running with Node 24 by default. If you need to temporarily use Node 20, you can set the ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION=true environment variable. For more information see: https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/
##[group]Run actions/checkout@v4
with:
repository: NVIDIA-AI-Blueprints/aiq
***REDACTED***
ssh-strict: true
ssh-user: git
persist-credentials: true
clean: true
sparse-checkout-cone-mode: true
fetch-depth: 1
fetch-tags: false
show-progress: true
lfs: false
submodules: false
set-safe-directory: true
##[endgroup]
Syncing repository: NVIDIA-AI-Blueprints/aiq
##[group]Getting Git version info
Working directory is '/home/runner/work/aiq/aiq'
[command]/usr/bin/git version
git v...
🧰 Additional context used
📓 Path-based instructions (4)
docs/source/**/*
📄 CodeRabbit inference engine (AGENTS.md)
Update the docs under docs/source/ when behavior, configuration, or workflows change
Files:
docs/source/examples/index.mddocs/source/architecture/index.mddocs/source/customization/index.mddocs/source/examples/cli-with-local-nims.mddocs/source/resources/release-notes.mddocs/source/architecture/agents/sandbox.mddocs/source/architecture/agents/index.mddocs/source/resources/changelog.mddocs/source/get-started/quick-start.mddocs/source/deployment/aws-opensearch-serverless.mddocs/source/index.mddocs/source/resources/faq.mddocs/source/get-started/installation.mddocs/source/customization/tools-and-sources.mddocs/source/examples/skills-sandbox/index.mddocs/source/profiling/index.mddocs/source/integration/agent-skills.mddocs/source/customization/prompts.mddocs/source/customization/guardrails.mddocs/source/architecture/overview.mddocs/source/customization/knowledge-layer.mddocs/source/integration/rest-api.mddocs/source/customization/mcp-tools.mddocs/source/architecture/agents/deep-researcher.mddocs/source/architecture/data-flow.mddocs/source/customization/configuration-reference.md
**
⚙️ CodeRabbit configuration file
**:AI-Q Agent Guidance
Repository-global instructions for coding agents and for humans reviewing
agent-authored changes. These rules apply to every task in this repository.
Task-specific runbooks live in.agents/skills/— load the
relevant skill before starting a workflow it covers.Project overview
AI-Q is an NVIDIA AI Blueprint: an enterprise research agent built on the
NeMo Agent Toolkit (NAT). The deployed product is a research blueprint, not
a general skill runtime. New retrieval sources and tools are NAT functions;
agent behavior is driven by workflow YAML, Jinja2 prompts, and a data-source
registry — not by hard-coded logic.Primary boundaries:
- Backend Python package:
src/aiq_agent/.- Data-source and tool packages:
sources/(each is its own package).- Frontends and tooling:
frontends/(web UI infrontends/ui/, eval harnesses
infrontends/benchmarks/).- Configs, deployment, docs:
configs/,deploy/,docs/.Stay inside this repository. If your workspace also contains adjacent repos
(for example a sibling NeMo-Relay checkout), do not edit them as part of an AI-Q
change. Treatsources/*as independent packages: prefer the smallest change
scoped to the package you are touching.Repository structure
Path Purpose src/aiq_agent/Backend agent, FastAPI extensions, auth, observability, knowledge sources/Data-source / tool packages (e.g. tavily_web_search,google_scholar_paper_search)configs/Workflow YAML configs (e.g. config_cli_default.yml)frontends/ui/Next.js / React / TypeScript / Tailwind / KUI web UI frontends/benchmarks/Eval harnesses: freshqa,deepsearch_qa,deepresearch_benchdeploy/Docker Compose and Helm/Kubernetes assets; deploy/.envfor secretsdocs/source/...
Files:
docs/source/examples/index.mddocs/source/architecture/index.mddocs/source/customization/index.mdsrc/aiq_agent/agents/deep_researcher/README.mddocs/source/examples/cli-with-local-nims.mdCHANGELOG.mddocs/source/resources/release-notes.mddocs/source/architecture/agents/sandbox.mddocs/source/architecture/agents/index.mddocs/source/resources/changelog.mddocs/source/get-started/quick-start.mddocs/source/deployment/aws-opensearch-serverless.mddocs/source/index.mddocs/source/resources/faq.mddocs/source/get-started/installation.mddocs/source/customization/tools-and-sources.mddocs/source/examples/skills-sandbox/index.mddocs/source/profiling/index.mddocs/source/integration/agent-skills.mddocs/source/customization/prompts.mddocs/source/customization/guardrails.mddocs/source/architecture/overview.mddocs/source/customization/knowledge-layer.mddocs/source/integration/rest-api.mdREADME.mddocs/source/customization/mcp-tools.mddocs/source/architecture/agents/deep-researcher.mddocs/source/architecture/data-flow.mddocs/source/customization/configuration-reference.md
{docs/**,README.md,CONTRIBUTING.md,SECURITY.md,CODE-OF-CONDUCT.md}
⚙️ CodeRabbit configuration file
{docs/**,README.md,CONTRIBUTING.md,SECURITY.md,CODE-OF-CONDUCT.md}: Review documentation for command accuracy, branch-name consistency, current CI and copy-pr-bot behavior, public
vs internal boundary clarity, stale examples, and links that no longer match the repository layout.
Files:
docs/source/examples/index.mddocs/source/architecture/index.mddocs/source/customization/index.mddocs/source/examples/cli-with-local-nims.mddocs/source/resources/release-notes.mddocs/source/architecture/agents/sandbox.mddocs/source/architecture/agents/index.mddocs/source/resources/changelog.mddocs/source/get-started/quick-start.mddocs/source/deployment/aws-opensearch-serverless.mddocs/source/index.mddocs/source/resources/faq.mddocs/source/get-started/installation.mddocs/source/customization/tools-and-sources.mddocs/source/examples/skills-sandbox/index.mddocs/source/profiling/index.mddocs/source/integration/agent-skills.mddocs/source/customization/prompts.mddocs/source/customization/guardrails.mddocs/source/architecture/overview.mddocs/source/customization/knowledge-layer.mddocs/source/integration/rest-api.mdREADME.mddocs/source/customization/mcp-tools.mddocs/source/architecture/agents/deep-researcher.mddocs/source/architecture/data-flow.mddocs/source/customization/configuration-reference.md
src/aiq_agent/agents/**/*
⚙️ CodeRabbit configuration file
src/aiq_agent/agents/**/*: Review agent changes for research workflow correctness, graph state transitions, prompt/tool contracts,
HITL behavior, and failure handling. Flag changes that weaken source attribution, report generation,
async cancellation, checkpointing, or data-source selection without focused tests and docs.
Files:
src/aiq_agent/agents/deep_researcher/README.md
🪛 LanguageTool
src/aiq_agent/agents/deep_researcher/README.md
[style] ~27-~27: Consider a different adjective to strengthen your wording.
Context: ...is path. - Clarification happens before deep research only when request scope or out...
(DEEP_PROFOUND)
CHANGELOG.md
[style] ~7-~7: Consider a different adjective to strengthen your wording.
Context: ...ed) Research and reports - Routed deep research now uses explicit source-route...
(DEEP_PROFOUND)
docs/source/resources/faq.md
[grammar] ~29-~29: Ensure spelling is correct
Context: ...ies. - Deep research is thorough (2-10min). An orchestrator coordinates an option...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~43-~43: Consider a different adjective to strengthen your wording.
Context: ... it escalates to the clarifier and then deep research. The clarifier asks only for m...
(DEEP_PROFOUND)
[style] ~45-~45: Consider a different adjective to strengthen your wording.
Context: .../architecture/overview.md). How does deep research choose data sources? The re...
(DEEP_PROFOUND)
docs/source/customization/tools-and-sources.md
[style] ~51-~51: Consider a different adjective to strengthen your wording.
Context: ... the UI | ## Automatic Source Routing Deep research can run an optional source-rou...
(DEEP_PROFOUND)
docs/source/examples/skills-sandbox/index.md
[style] ~8-~8: Consider a different adjective to strengthen your wording.
Context: ...box This example shows how to run AI-Q deep research with DeepAgents skills and a p...
(DEEP_PROFOUND)
docs/source/profiling/index.md
[style] ~128-~128: ‘at a discount’ might be wordy. Consider a shorter alternative.
Context: ...tion path. - Cached tokens are billed at a discount. Without explicit tracking, you canno...
(EN_WORDINESS_PREMIUM_AT_A_DISCOUNT)
docs/source/customization/guardrails.md
[style] ~71-~71: Consider a different adjective to strengthen your wording.
Context: ...ent in the reference profile. For async deep research, the worker does not invoke th...
(DEEP_PROFOUND)
docs/source/architecture/overview.md
[style] ~88-~88: Consider a different adjective to strengthen your wording.
Context: ...rorNone| Preserved user query for deep research | |available_documents|l...
(DEEP_PROFOUND)
[style] ~94-~94: Consider a different adjective to strengthen your wording.
Context: ...ing loop) while reserving multi-stage deep research for complex cases. The intent ...
(DEEP_PROFOUND)
docs/source/architecture/agents/deep-researcher.md
[grammar] ~162-~162: Ensure spelling is correct
Context: ...ries concurrently. ## State Model ### DeepResearchAgentState | Field | Type | Default | Description |...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/source/customization/configuration-reference.md
[style] ~425-~425: Consider using “incompatible” to avoid wordiness.
Context: ...only when the active source formats are not compatible with verification. | | skills | objec...
(NOT_ABLE_PREMIUM)
🪛 markdownlint-cli2 (0.22.1)
docs/source/resources/changelog.md
[warning] 6-6: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
docs/source/customization/knowledge-layer.md
[warning] 168-168: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🔇 Additional comments (31)
docs/source/architecture/agents/sandbox.md (1)
18-20: 📐 Maintainability & Code Quality | ⚡ Quick winUse a repo-relative link here.
This hard-coded
developURL will drift with branch changes and is less portable than a canonical docs/source link. As per path instructions, review docs for links that no longer match repository layout.Source: Path instructions
docs/source/architecture/index.md (1)
13-13: LGTM!docs/source/architecture/data-flow.md (1)
26-26: LGTM!Also applies to: 46-52, 90-93, 106-108, 118-118, 134-178, 228-241
docs/source/integration/rest-api.md (2)
17-17: LGTM!Also applies to: 36-38, 238-242
283-362: 🎯 Functional CorrectnessVerify the new artifact lifecycle claims against the implementation.
This section now asserts server-wide retention independent of
expiry_secondsand extension-based MIME fallback, but the server-side snippet we have only confirms auth-scoped reads,Content-Dispositionselection, andnosniff. Please confirm the extra lifecycle/classification details before treating them as API guarantees.docs/source/examples/index.md (1)
17-17: LGTM!docs/source/examples/skills-sandbox/index.md (2)
8-11: LGTM!Also applies to: 23-23, 90-95, 140-141, 202-209
71-88: 🎯 Functional CorrectnessConfirm the published sandbox profile still matches the supported example runtime.
Switching the container image to
python:3.13-slimand settingenable_citation_verification: falseboth change the executable walkthrough. Please confirm those are intentional and still match the repo’s supported/tested deep-research setup.Source: Coding guidelines
docs/source/customization/guardrails.md (1)
10-23: LGTM!Also applies to: 37-45, 71-82, 121-135
docs/source/customization/mcp-tools.md (1)
34-35: LGTM!Also applies to: 217-218, 305-307, 384-385
docs/source/integration/agent-skills.md (1)
14-14: LGTM!Also applies to: 69-86, 145-145
docs/source/profiling/index.md (1)
118-132: LGTM!Also applies to: 194-196, 205-208, 226-226, 243-257
CHANGELOG.md (1)
3-36: LGTM!docs/source/resources/release-notes.md (1)
6-109: LGTM!docs/source/index.md (1)
16-16: LGTM!Also applies to: 25-29, 137-137
docs/source/get-started/quick-start.md (1)
140-141: LGTM!README.md (1)
27-27: LGTM!Also applies to: 64-102, 134-135, 251-259, 318-319, 406-418, 419-426
.secrets.baseline (1)
136-136: LGTM!Also applies to: 358-358
docs/source/resources/changelog.md (1)
6-7: 📐 Maintainability & Code QualityNo MD041 suppression needed. This repo doesn’t run markdownlint/MD041 on docs; CI and pre-commit only include
markdown-link-checkfor this file.> Likely an incorrect or invalid review comment.docs/source/architecture/agents/deep-researcher.md (1)
8-143: LGTM!Also applies to: 144-202, 213-218, 232-296, 297-353
docs/source/architecture/agents/index.md (1)
13-15: LGTM!docs/source/architecture/overview.md (1)
30-32: LGTM!Also applies to: 69-72, 82-128
docs/source/resources/faq.md (1)
29-67: LGTM!Also applies to: 81-85
docs/source/customization/prompts.md (1)
12-22: LGTM!Also applies to: 36-40, 49-49, 106-106, 132-182, 207-212, 274-281
docs/source/customization/tools-and-sources.md (1)
50-90: LGTM!Also applies to: 105-108
src/aiq_agent/agents/deep_researcher/README.md (1)
1-30: LGTM!Also applies to: 31-45, 46-57
docs/source/examples/cli-with-local-nims.md (1)
183-186: LGTM!docs/source/customization/index.md (1)
19-19: LGTM!docs/source/deployment/aws-opensearch-serverless.md (1)
10-16: LGTM!Also applies to: 69-74
docs/source/get-started/installation.md (1)
28-33: LGTM!Also applies to: 54-54, 99-104, 139-150
docs/source/customization/configuration-reference.md (1)
262-309: 🎯 Functional CorrectnessNo change needed. The example shows the shipped OpenSearch profile (
auto), while the config default remainslocal.> Likely an incorrect or invalid review comment.
347afe7 to
d4707dc
Compare
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 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/source/integration/rest-api.md`:
- Around line 343-347: Document and address the anonymous artifact-read behavior
for the durable artifact endpoints: when REQUIRE_AUTH is false, the artifact
content path remains reachable without ownership checks, so callers with a valid
job ID can read bytes. Update the REST API docs near the durable artifact
endpoint description to call out this exposure clearly, and if the
implementation should be tightened, require authentication or a signed artifact
token in the artifact-serving flow before returning content.
In `@docs/source/profiling/index.md`:
- Around line 118-132: The Tavily cost example in the profiling docs uses exact
call-count and dollar figures as if they were generally applicable, which makes
the guidance look like a fixed benchmark. Update the example in the profiling
section to either include the run/date/source for those numbers or rewrite it as
an illustrative estimate without exact figures, keeping the surrounding
explanation in docs/source/profiling/index.md consistent with the tokenomics
report wording.
In `@docs/source/resources/changelog.md`:
- Around line 6-7: The include-only changelog page is triggering MD041 because
it has no top-level heading. Update the changelog page by either adding a short
page title before the existing include directive in the changelog document, or
by disabling MD041 for that file if that is the intended pattern. Use the
changelog page content and the existing include directive as the location cues.
🪄 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: ASSERTIVE
Plan: Enterprise
Run ID: b73a18c4-b6b0-4023-94a1-d8270887db3a
📒 Files selected for processing (30)
.secrets.baselineCHANGELOG.mdREADME.mddocs/source/architecture/agents/deep-researcher.mddocs/source/architecture/agents/index.mddocs/source/architecture/agents/sandbox.mddocs/source/architecture/data-flow.mddocs/source/architecture/index.mddocs/source/architecture/overview.mddocs/source/customization/configuration-reference.mddocs/source/customization/guardrails.mddocs/source/customization/index.mddocs/source/customization/knowledge-layer.mddocs/source/customization/mcp-tools.mddocs/source/customization/prompts.mddocs/source/customization/tools-and-sources.mddocs/source/deployment/aws-opensearch-serverless.mddocs/source/examples/cli-with-local-nims.mddocs/source/examples/index.mddocs/source/examples/skills-sandbox/index.mddocs/source/get-started/installation.mddocs/source/get-started/quick-start.mddocs/source/index.mddocs/source/integration/agent-skills.mddocs/source/integration/rest-api.mddocs/source/profiling/index.mddocs/source/resources/changelog.mddocs/source/resources/faq.mddocs/source/resources/release-notes.mdsrc/aiq_agent/agents/deep_researcher/README.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (4)
docs/source/**/*
📄 CodeRabbit inference engine (AGENTS.md)
Update the docs under docs/source/ when behavior, configuration, or workflows change
Files:
docs/source/architecture/agents/sandbox.mddocs/source/architecture/agents/index.mddocs/source/examples/cli-with-local-nims.mddocs/source/examples/index.mddocs/source/resources/changelog.mddocs/source/index.mddocs/source/customization/index.mddocs/source/architecture/index.mddocs/source/get-started/quick-start.mddocs/source/resources/faq.mddocs/source/customization/tools-and-sources.mddocs/source/resources/release-notes.mddocs/source/integration/agent-skills.mddocs/source/examples/skills-sandbox/index.mddocs/source/deployment/aws-opensearch-serverless.mddocs/source/integration/rest-api.mddocs/source/architecture/overview.mddocs/source/profiling/index.mddocs/source/customization/guardrails.mddocs/source/customization/prompts.mddocs/source/architecture/data-flow.mddocs/source/get-started/installation.mddocs/source/customization/mcp-tools.mddocs/source/customization/knowledge-layer.mddocs/source/architecture/agents/deep-researcher.mddocs/source/customization/configuration-reference.md
**
⚙️ CodeRabbit configuration file
**:AI-Q Agent Guidance
Repository-global instructions for coding agents and for humans reviewing
agent-authored changes. These rules apply to every task in this repository.
Task-specific runbooks live in.agents/skills/— load the
relevant skill before starting a workflow it covers.Project overview
AI-Q is an NVIDIA AI Blueprint: an enterprise research agent built on the
NeMo Agent Toolkit (NAT). The deployed product is a research blueprint, not
a general skill runtime. New retrieval sources and tools are NAT functions;
agent behavior is driven by workflow YAML, Jinja2 prompts, and a data-source
registry — not by hard-coded logic.Primary boundaries:
- Backend Python package:
src/aiq_agent/.- Data-source and tool packages:
sources/(each is its own package).- Frontends and tooling:
frontends/(web UI infrontends/ui/, eval harnesses
infrontends/benchmarks/).- Configs, deployment, docs:
configs/,deploy/,docs/.Stay inside this repository. If your workspace also contains adjacent repos
(for example a sibling NeMo-Relay checkout), do not edit them as part of an AI-Q
change. Treatsources/*as independent packages: prefer the smallest change
scoped to the package you are touching.Repository structure
Path Purpose src/aiq_agent/Backend agent, FastAPI extensions, auth, observability, knowledge sources/Data-source / tool packages (e.g. tavily_web_search,google_scholar_paper_search)configs/Workflow YAML configs (e.g. config_cli_default.yml)frontends/ui/Next.js / React / TypeScript / Tailwind / KUI web UI frontends/benchmarks/Eval harnesses: freshqa,deepsearch_qa,deepresearch_benchdeploy/Docker Compose and Helm/Kubernetes assets; deploy/.envfor secretsdocs/source/...
Files:
docs/source/architecture/agents/sandbox.mddocs/source/architecture/agents/index.mddocs/source/examples/cli-with-local-nims.mddocs/source/examples/index.mddocs/source/resources/changelog.mddocs/source/index.mddocs/source/customization/index.mddocs/source/architecture/index.mddocs/source/get-started/quick-start.mddocs/source/resources/faq.mddocs/source/customization/tools-and-sources.mddocs/source/resources/release-notes.mdCHANGELOG.mddocs/source/integration/agent-skills.mddocs/source/examples/skills-sandbox/index.mddocs/source/deployment/aws-opensearch-serverless.mdsrc/aiq_agent/agents/deep_researcher/README.mddocs/source/integration/rest-api.mddocs/source/architecture/overview.mddocs/source/profiling/index.mddocs/source/customization/guardrails.mddocs/source/customization/prompts.mddocs/source/architecture/data-flow.mddocs/source/get-started/installation.mddocs/source/customization/mcp-tools.mdREADME.mddocs/source/customization/knowledge-layer.mddocs/source/architecture/agents/deep-researcher.mddocs/source/customization/configuration-reference.md
{docs/**,README.md,CONTRIBUTING.md,SECURITY.md,CODE-OF-CONDUCT.md}
⚙️ CodeRabbit configuration file
{docs/**,README.md,CONTRIBUTING.md,SECURITY.md,CODE-OF-CONDUCT.md}: Review documentation for command accuracy, branch-name consistency, current CI and copy-pr-bot behavior, public
vs internal boundary clarity, stale examples, and links that no longer match the repository layout.
Files:
docs/source/architecture/agents/sandbox.mddocs/source/architecture/agents/index.mddocs/source/examples/cli-with-local-nims.mddocs/source/examples/index.mddocs/source/resources/changelog.mddocs/source/index.mddocs/source/customization/index.mddocs/source/architecture/index.mddocs/source/get-started/quick-start.mddocs/source/resources/faq.mddocs/source/customization/tools-and-sources.mddocs/source/resources/release-notes.mddocs/source/integration/agent-skills.mddocs/source/examples/skills-sandbox/index.mddocs/source/deployment/aws-opensearch-serverless.mddocs/source/integration/rest-api.mddocs/source/architecture/overview.mddocs/source/profiling/index.mddocs/source/customization/guardrails.mddocs/source/customization/prompts.mddocs/source/architecture/data-flow.mddocs/source/get-started/installation.mddocs/source/customization/mcp-tools.mdREADME.mddocs/source/customization/knowledge-layer.mddocs/source/architecture/agents/deep-researcher.mddocs/source/customization/configuration-reference.md
src/aiq_agent/agents/**/*
⚙️ CodeRabbit configuration file
src/aiq_agent/agents/**/*: Review agent changes for research workflow correctness, graph state transitions, prompt/tool contracts,
HITL behavior, and failure handling. Flag changes that weaken source attribution, report generation,
async cancellation, checkpointing, or data-source selection without focused tests and docs.
Files:
src/aiq_agent/agents/deep_researcher/README.md
🪛 LanguageTool
docs/source/resources/faq.md
[grammar] ~29-~29: Ensure spelling is correct
Context: ...ies. - Deep research is thorough (2-10min). An orchestrator coordinates an option...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~43-~43: Consider a different adjective to strengthen your wording.
Context: ... it escalates to the clarifier and then deep research. The clarifier asks only for m...
(DEEP_PROFOUND)
[style] ~45-~45: Consider a different adjective to strengthen your wording.
Context: .../architecture/overview.md). How does deep research choose data sources? The re...
(DEEP_PROFOUND)
docs/source/customization/tools-and-sources.md
[style] ~51-~51: Consider a different adjective to strengthen your wording.
Context: ... the UI | ## Automatic Source Routing Deep research can run an optional source-rou...
(DEEP_PROFOUND)
CHANGELOG.md
[style] ~7-~7: Consider a different adjective to strengthen your wording.
Context: ...ed) Research and reports - Routed deep research now uses explicit source-route...
(DEEP_PROFOUND)
docs/source/examples/skills-sandbox/index.md
[style] ~8-~8: Consider a different adjective to strengthen your wording.
Context: ...box This example shows how to run AI-Q deep research with DeepAgents skills and a p...
(DEEP_PROFOUND)
src/aiq_agent/agents/deep_researcher/README.md
[style] ~27-~27: Consider a different adjective to strengthen your wording.
Context: ...is path. - Clarification happens before deep research only when request scope or out...
(DEEP_PROFOUND)
docs/source/architecture/overview.md
[style] ~88-~88: Consider a different adjective to strengthen your wording.
Context: ...rorNone| Preserved user query for deep research | |available_documents|l...
(DEEP_PROFOUND)
[style] ~94-~94: Consider a different adjective to strengthen your wording.
Context: ...ing loop) while reserving multi-stage deep research for complex cases. The intent ...
(DEEP_PROFOUND)
docs/source/profiling/index.md
[style] ~128-~128: ‘at a discount’ might be wordy. Consider a shorter alternative.
Context: ...tion path. - Cached tokens are billed at a discount. Without explicit tracking, you canno...
(EN_WORDINESS_PREMIUM_AT_A_DISCOUNT)
docs/source/customization/guardrails.md
[style] ~71-~71: Consider a different adjective to strengthen your wording.
Context: ...ent in the reference profile. For async deep research, the worker does not invoke th...
(DEEP_PROFOUND)
docs/source/architecture/agents/deep-researcher.md
[grammar] ~162-~162: Ensure spelling is correct
Context: ...ries concurrently. ## State Model ### DeepResearchAgentState | Field | Type | Default | Description |...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/source/customization/configuration-reference.md
[style] ~425-~425: Consider using “incompatible” to avoid wordiness.
Context: ...only when the active source formats are not compatible with verification. | | skills | objec...
(NOT_ABLE_PREMIUM)
🪛 markdownlint-cli2 (0.22.1)
docs/source/resources/changelog.md
[warning] 6-6: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
docs/source/customization/knowledge-layer.md
[warning] 168-168: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🔇 Additional comments (35)
CHANGELOG.md (1)
3-34: LGTM!docs/source/resources/release-notes.md (1)
6-110: LGTM!docs/source/index.md (1)
16-16: LGTM!Also applies to: 25-29, 137-137
docs/source/get-started/quick-start.md (1)
140-141: LGTM!README.md (1)
27-27: LGTM!Also applies to: 64-102, 134-135, 251-259, 318-319, 406-426
.secrets.baseline (1)
136-136: LGTM!Also applies to: 358-358
docs/source/customization/guardrails.md (1)
10-23: LGTM!Also applies to: 37-45, 71-82, 121-135
docs/source/customization/mcp-tools.md (1)
34-35: LGTM!Also applies to: 214-218, 305-308, 383-385
docs/source/integration/agent-skills.md (1)
14-14: LGTM!Also applies to: 69-86, 145-145
docs/source/profiling/index.md (2)
194-196: LGTM!Also applies to: 205-208, 226-226
243-257: 📐 Maintainability & Code QualityVerify the runtime-path explanation.
The supplied
src/aiq_agent/tokenomics/nat_adapter.pysnippets support the completion-time bucketing fallback, but they do not prove therun_research_batch/ direct-call behavior described here. Please confirm that against the workflow implementation, or narrow this paragraph to the adapter behavior the docs can actually observe. As per path instructions, review documentation for public vs internal boundary clarity.Source: Path instructions
docs/source/customization/knowledge-layer.md (2)
167-194: 📐 Maintainability & Code QualityAdd a blank line before the OpenSearch YAML fence.
This is the same MD031 markdownlint issue already flagged previously; the fenced block still starts immediately after the heading.
Source: Linters/SAST tools
18-18: LGTM!Also applies to: 46-59, 78-78, 118-123, 220-220, 255-259, 336-336, 442-449, 463-464, 486-486
docs/source/customization/index.md (1)
19-19: LGTM!docs/source/customization/configuration-reference.md (1)
155-169: LGTM!Also applies to: 207-228, 229-232, 262-281, 292-309, 386-388, 399-410, 421-438, 470-474, 580-594
docs/source/deployment/aws-opensearch-serverless.md (1)
10-16: LGTM!Also applies to: 69-74
docs/source/get-started/installation.md (1)
28-33: LGTM!Also applies to: 54-54, 99-104, 139-150
docs/source/architecture/agents/deep-researcher.md (1)
8-143: LGTM!Also applies to: 144-202, 213-218, 232-296, 297-353
docs/source/architecture/agents/index.md (1)
13-15: LGTM!docs/source/architecture/overview.md (1)
30-32: LGTM!Also applies to: 69-71, 82-90, 91-128
docs/source/resources/faq.md (1)
29-67: LGTM!Also applies to: 81-85
docs/source/integration/rest-api.md (1)
17-17: LGTM!Also applies to: 36-38, 238-242, 283-336, 357-361
docs/source/examples/index.md (1)
17-17: LGTM!docs/source/examples/skills-sandbox/index.md (3)
8-11: LGTM!Also applies to: 23-23, 90-95, 140-141, 202-209
75-75: 📐 Maintainability & Code QualityVerify the Python 3.13 sandbox image.
This example now pins
python:3.13-slim; please confirm the sandbox provider and dependencies are actually validated on 3.13, or the copy-paste config will drift from the supported runtime profile. As per path instructions, docs underdocs/**should keep example runtime details accurate.Source: Path instructions
85-88: 🎯 Functional CorrectnessConfirm the citation-verification opt-out is intentional.
This snippet disables
enable_citation_verificationeven though the deep-research docs describe verification as enabled by default. If this sandbox workflow truly needs the exception, call it out explicitly; otherwise keep the safer default on. As per path instructions, docs underdocs/**should keep copy-paste examples aligned with documented defaults.Source: Path instructions
docs/source/customization/prompts.md (2)
124-130: Removeparent_report_context_availablefrom the orchestrator table.This is the same contract mismatch already called out in the earlier review: the flag is passed to the writer subagent, so keeping it in the orchestrator inventory is still misleading.
12-22: LGTM!Also applies to: 36-40, 49-49, 106-106, 132-182, 207-212, 274-281
docs/source/customization/tools-and-sources.md (2)
88-103: Align the no-catalog fallback wording with the router.The text still describes a synthetic
unconfigureddomain, but the router buildsgeneral_researchand falls back toweb_searchor the first mapped source. This is the same mismatch flagged in the earlier review.
50-87: LGTM!Also applies to: 104-108
src/aiq_agent/agents/deep_researcher/README.md (1)
1-57: LGTM!docs/source/examples/cli-with-local-nims.md (1)
180-186: LGTM!docs/source/architecture/agents/sandbox.md (1)
20-20: LGTM!docs/source/architecture/index.md (1)
13-13: LGTM!docs/source/architecture/data-flow.md (1)
26-26: LGTM!Also applies to: 46-52, 90-93, 106-108, 118-118, 134-178, 228-241
lvojtku
left a comment
lvojtku
left a comment
There was a problem hiding this comment.
Please change all the "See..." to "Refer to..." when referring to users to external links. Approved with minor fixes.
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
d4707dc to
bed1fb1
Compare
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 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/source/customization/knowledge-layer.md`:
- Around line 176-181: Update the OpenSearch configuration example to explicitly
warn that opensearch_auth_type: none is only suitable for a protected local
development endpoint; instruct users to configure authentication for all remote
or production deployments and avoid presenting the unauthenticated default as
generally safe.
- Around line 187-190: Document the exact `opensearch_embedding_dim` YAML key
and corresponding environment variable in the OpenSearch configuration section
and environment-variable table, including the default value of `2048`; add a
concrete validation example showing that the embedding model output dimension
must equal the configured value before creating the index.
In `@docs/source/get-started/installation.md`:
- Around line 28-33: Update the link labels in the installation model table for
the Nemotron and GPT-OSS entries to accurately describe their destinations as
“model card” links, or replace them with actual support-matrix URLs where
available. Ensure all affected labels match the linked NVIDIA pages, including
the entries for the intent classifier, deep research researcher, and optional
orchestrator/planner models.
In `@docs/source/profiling/index.md`:
- Line 128: Update the cached-token pricing statement in the profiling
documentation to say cached tokens “may be billed at a discount” rather than
asserting a discount always applies, aligning it with the provider-dependent
pricing guidance elsewhere.
🪄 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: ASSERTIVE
Plan: Enterprise
Run ID: 17ff8bb5-d12f-4ac0-8e91-4b5acdc7c8fc
📒 Files selected for processing (34)
.secrets.baselineCHANGELOG.mdREADME.mddeploy/helm/README.mddeploy/helm/deployment-k8s/README.mddocs/source/architecture/agents/deep-researcher.mddocs/source/architecture/agents/index.mddocs/source/architecture/agents/sandbox.mddocs/source/architecture/data-flow.mddocs/source/architecture/index.mddocs/source/architecture/overview.mddocs/source/customization/configuration-reference.mddocs/source/customization/guardrails.mddocs/source/customization/index.mddocs/source/customization/knowledge-layer.mddocs/source/customization/mcp-tools.mddocs/source/customization/prompts.mddocs/source/customization/tools-and-sources.mddocs/source/deployment/aws-opensearch-serverless.mddocs/source/deployment/kubernetes.mddocs/source/deployment/observability.mddocs/source/examples/cli-with-local-nims.mddocs/source/examples/index.mddocs/source/examples/skills-sandbox/index.mddocs/source/get-started/installation.mddocs/source/get-started/quick-start.mddocs/source/index.mddocs/source/integration/agent-skills.mddocs/source/integration/rest-api.mddocs/source/profiling/index.mddocs/source/resources/changelog.mddocs/source/resources/faq.mddocs/source/resources/release-notes.mdsrc/aiq_agent/agents/deep_researcher/README.md
📜 Review details
⏰ Context from checks skipped due to timeout. (3)
- GitHub Check: UI Unit Tests
- GitHub Check: CodeRabbit / Review
- GitHub Check: Run Harbor skill eval
🧰 Additional context used
📓 Path-based instructions (5)
docs/source/**/*
📄 CodeRabbit inference engine (AGENTS.md)
Update the docs under docs/source/ when behavior, configuration, or workflows change
Files:
docs/source/architecture/index.mddocs/source/architecture/agents/index.mddocs/source/customization/index.mddocs/source/examples/index.mddocs/source/resources/release-notes.mddocs/source/index.mddocs/source/resources/changelog.mddocs/source/get-started/quick-start.mddocs/source/deployment/observability.mddocs/source/architecture/agents/sandbox.mddocs/source/integration/agent-skills.mddocs/source/resources/faq.mddocs/source/examples/skills-sandbox/index.mddocs/source/examples/cli-with-local-nims.mddocs/source/customization/tools-and-sources.mddocs/source/deployment/aws-opensearch-serverless.mddocs/source/customization/guardrails.mddocs/source/architecture/data-flow.mddocs/source/customization/mcp-tools.mddocs/source/architecture/overview.mddocs/source/profiling/index.mddocs/source/get-started/installation.mddocs/source/customization/knowledge-layer.mddocs/source/customization/configuration-reference.mddocs/source/customization/prompts.mddocs/source/deployment/kubernetes.mddocs/source/architecture/agents/deep-researcher.mddocs/source/integration/rest-api.md
**
⚙️ CodeRabbit configuration file
**:AI-Q Agent Guidance
Repository-global instructions for coding agents and for humans reviewing
agent-authored changes. These rules apply to every task in this repository.
Task-specific runbooks live in.agents/skills/— load the
relevant skill before starting a workflow it covers.Project overview
AI-Q is an NVIDIA AI Blueprint: an enterprise research agent built on the
NeMo Agent Toolkit (NAT). The deployed product is a research blueprint, not
a general skill runtime. New retrieval sources and tools are NAT functions;
agent behavior is driven by workflow YAML, Jinja2 prompts, and a data-source
registry — not by hard-coded logic.Primary boundaries:
- Backend Python package:
src/aiq_agent/.- Data-source and tool packages:
sources/(each is its own package).- Frontends and tooling:
frontends/(web UI infrontends/ui/, eval harnesses
infrontends/benchmarks/).- Configs, deployment, docs:
configs/,deploy/,docs/.Stay inside this repository. If your workspace also contains adjacent repos
(for example a sibling NeMo-Relay checkout), do not edit them as part of an AI-Q
change. Treatsources/*as independent packages: prefer the smallest change
scoped to the package you are touching.Repository structure
Path Purpose src/aiq_agent/Backend agent, FastAPI extensions, auth, observability, knowledge sources/Data-source / tool packages (e.g. tavily_web_search,google_scholar_paper_search)configs/Workflow YAML configs (e.g. config_cli_default.yml)frontends/ui/Next.js / React / TypeScript / Tailwind / KUI web UI frontends/benchmarks/Eval harnesses: freshqa,deepsearch_qa,deepresearch_benchdeploy/Docker Compose and Helm/Kubernetes assets; deploy/.envfor secretsdocs/source/...
Files:
docs/source/architecture/index.mddocs/source/architecture/agents/index.mddocs/source/customization/index.mddocs/source/examples/index.mddocs/source/resources/release-notes.mddocs/source/index.mddocs/source/resources/changelog.mddocs/source/get-started/quick-start.mddocs/source/deployment/observability.mddocs/source/architecture/agents/sandbox.mddeploy/helm/deployment-k8s/README.mdCHANGELOG.mddocs/source/integration/agent-skills.mddocs/source/resources/faq.mddocs/source/examples/skills-sandbox/index.mddocs/source/examples/cli-with-local-nims.mddocs/source/customization/tools-and-sources.mddocs/source/deployment/aws-opensearch-serverless.mddocs/source/customization/guardrails.mddeploy/helm/README.mdsrc/aiq_agent/agents/deep_researcher/README.mddocs/source/architecture/data-flow.mddocs/source/customization/mcp-tools.mddocs/source/architecture/overview.mddocs/source/profiling/index.mddocs/source/get-started/installation.mddocs/source/customization/knowledge-layer.mddocs/source/customization/configuration-reference.mddocs/source/customization/prompts.mddocs/source/deployment/kubernetes.mddocs/source/architecture/agents/deep-researcher.mddocs/source/integration/rest-api.mdREADME.md
{docs/**,README.md,CONTRIBUTING.md,SECURITY.md,CODE-OF-CONDUCT.md}
⚙️ CodeRabbit configuration file
{docs/**,README.md,CONTRIBUTING.md,SECURITY.md,CODE-OF-CONDUCT.md}: Review documentation for command accuracy, branch-name consistency, current CI and copy-pr-bot behavior, public
vs internal boundary clarity, stale examples, and links that no longer match the repository layout.
Files:
docs/source/architecture/index.mddocs/source/architecture/agents/index.mddocs/source/customization/index.mddocs/source/examples/index.mddocs/source/resources/release-notes.mddocs/source/index.mddocs/source/resources/changelog.mddocs/source/get-started/quick-start.mddocs/source/deployment/observability.mddocs/source/architecture/agents/sandbox.mddocs/source/integration/agent-skills.mddocs/source/resources/faq.mddocs/source/examples/skills-sandbox/index.mddocs/source/examples/cli-with-local-nims.mddocs/source/customization/tools-and-sources.mddocs/source/deployment/aws-opensearch-serverless.mddocs/source/customization/guardrails.mddocs/source/architecture/data-flow.mddocs/source/customization/mcp-tools.mddocs/source/architecture/overview.mddocs/source/profiling/index.mddocs/source/get-started/installation.mddocs/source/customization/knowledge-layer.mddocs/source/customization/configuration-reference.mddocs/source/customization/prompts.mddocs/source/deployment/kubernetes.mddocs/source/architecture/agents/deep-researcher.mddocs/source/integration/rest-api.mdREADME.md
{deploy/**,configs/**}
⚙️ CodeRabbit configuration file
{deploy/**,configs/**}: Review deployment and config changes for secret separation, safe defaults, local-vs-production behavior, Helm and
Docker portability, and documentation parity. Flag committed credentials, environment-specific NVIDIA internals in
public defaults, and changes that make examples diverge from CI-tested paths.
Files:
deploy/helm/deployment-k8s/README.mddeploy/helm/README.md
src/aiq_agent/agents/**/*
⚙️ CodeRabbit configuration file
src/aiq_agent/agents/**/*: Review agent changes for research workflow correctness, graph state transitions, prompt/tool contracts,
HITL behavior, and failure handling. Flag changes that weaken source attribution, report generation,
async cancellation, checkpointing, or data-source selection without focused tests and docs.
Files:
src/aiq_agent/agents/deep_researcher/README.md
🪛 LanguageTool
CHANGELOG.md
[style] ~7-~7: Consider a different adjective to strengthen your wording.
Context: ...ed) Research and reports - Routed deep research now uses explicit source-route...
(DEEP_PROFOUND)
docs/source/resources/faq.md
[grammar] ~29-~29: Ensure spelling is correct
Context: ...ies. - Deep research is thorough (2-10min). An orchestrator coordinates an option...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~43-~43: Consider a different adjective to strengthen your wording.
Context: ... it escalates to the clarifier and then deep research. The clarifier asks only for m...
(DEEP_PROFOUND)
[style] ~45-~45: Consider a different adjective to strengthen your wording.
Context: .../architecture/overview.md). How does deep research choose data sources? The re...
(DEEP_PROFOUND)
docs/source/examples/skills-sandbox/index.md
[style] ~8-~8: Consider a different adjective to strengthen your wording.
Context: ...box This example shows how to run AI-Q deep research with DeepAgents skills and a p...
(DEEP_PROFOUND)
docs/source/customization/tools-and-sources.md
[style] ~51-~51: Consider a different adjective to strengthen your wording.
Context: ... the UI | ## Automatic Source Routing Deep research can run an optional source-rou...
(DEEP_PROFOUND)
docs/source/customization/guardrails.md
[style] ~71-~71: Consider a different adjective to strengthen your wording.
Context: ...ent in the reference profile. For async deep research, the worker does not invoke th...
(DEEP_PROFOUND)
src/aiq_agent/agents/deep_researcher/README.md
[style] ~27-~27: Consider a different adjective to strengthen your wording.
Context: ...is path. - Clarification happens before deep research only when request scope or out...
(DEEP_PROFOUND)
docs/source/architecture/overview.md
[style] ~88-~88: Consider a different adjective to strengthen your wording.
Context: ...rorNone| Preserved user query for deep research | |available_documents|l...
(DEEP_PROFOUND)
[style] ~94-~94: Consider a different adjective to strengthen your wording.
Context: ...ing loop) while reserving multi-stage deep research for complex cases. The intent ...
(DEEP_PROFOUND)
docs/source/profiling/index.md
[style] ~128-~128: ‘at a discount’ might be wordy. Consider a shorter alternative.
Context: ...tion path. - Cached tokens are billed at a discount. Without explicit tracking, you canno...
(EN_WORDINESS_PREMIUM_AT_A_DISCOUNT)
docs/source/customization/configuration-reference.md
[style] ~425-~425: Consider using “incompatible” to avoid wordiness.
Context: ...only when the active source formats are not compatible with verification. | | skills | objec...
(NOT_ABLE_PREMIUM)
docs/source/architecture/agents/deep-researcher.md
[grammar] ~162-~162: Ensure spelling is correct
Context: ...ries concurrently. ## State Model ### DeepResearchAgentState | Field | Type | Default | Description |...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🪛 markdownlint-cli2 (0.22.1)
docs/source/resources/changelog.md
[warning] 6-6: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
🔇 Additional comments (39)
docs/source/architecture/index.md (1)
13-13: LGTM!docs/source/architecture/agents/index.md (1)
13-15: LGTM!docs/source/customization/index.md (1)
19-19: LGTM!docs/source/examples/index.md (1)
17-17: LGTM!docs/source/profiling/index.md (2)
118-127: LGTM!Also applies to: 129-133, 195-197, 206-209, 227-227, 244-260
165-165: 🎯 Functional Correctness
eval.general.output_diris already used by the tokenomics reportThe report CLI already reads
eval.general.output_dirfrom the pricing YAML and uses it as the defaulttokenomics_report.htmlpath when--outputis omitted.> Likely an incorrect or invalid review comment.docs/source/get-started/installation.md (1)
54-54: LGTM!Also applies to: 99-104, 139-150
docs/source/customization/knowledge-layer.md (1)
18-18: LGTM!Also applies to: 46-59, 78-78, 118-124, 167-175, 182-185, 192-194, 221-221, 256-260, 337-337, 443-450, 464-465, 487-487
docs/source/resources/changelog.md (1)
6-7: 📐 Maintainability & Code QualityThe include-only changelog still triggers MD041.
This file begins with an
{include}directive and has no top-level heading, so markdownlint will continue to fail unless you add an H1 or disable MD041 locally.Source: Linters/SAST tools
docs/source/customization/prompts.md (1)
124-128: 🎯 Functional CorrectnessVerify
parent_report_context_availableownership.The variable is documented for both the orchestrator and writer. A previous review identified it as writer-specific; confirm the current runtime passes it to both before retaining the orchestrator entry.
Also applies to: 166-169
docs/source/resources/release-notes.md (1)
1-133: LGTM!docs/source/index.md (1)
16-16: LGTM!Also applies to: 25-29, 137-137
.secrets.baseline (1)
136-136: LGTM!Also applies to: 172-172, 358-358
docs/source/get-started/quick-start.md (1)
71-71: LGTM!Also applies to: 140-141
docs/source/customization/configuration-reference.md (1)
82-82: LGTM!Also applies to: 155-169, 207-232, 262-309, 386-438, 470-474, 580-594
docs/source/deployment/observability.md (1)
18-46: LGTM!docs/source/architecture/agents/sandbox.md (1)
15-21: LGTM!Also applies to: 45-50, 59-61, 73-73
deploy/helm/deployment-k8s/README.md (1)
5-5: LGTM!Also applies to: 18-23, 111-111
CHANGELOG.md (1)
3-40: LGTM!docs/source/integration/agent-skills.md (1)
14-14: LGTM!Also applies to: 69-86, 145-145
docs/source/deployment/kubernetes.md (1)
100-112: LGTM!Also applies to: 132-132, 204-208, 261-261
docs/source/architecture/agents/deep-researcher.md (5)
8-143: LGTM!
144-202: LGTM!
213-226: LGTM!
232-296: LGTM!
297-353: LGTM!docs/source/resources/faq.md (1)
29-57: LGTM!Also applies to: 58-67, 81-85
docs/source/examples/skills-sandbox/index.md (1)
8-13: LGTM!Also applies to: 23-23, 53-53, 75-75, 85-95, 140-141, 202-210
docs/source/examples/cli-with-local-nims.md (1)
183-186: LGTM!docs/source/customization/tools-and-sources.md (1)
50-109: LGTM!Also applies to: 208-208
docs/source/deployment/aws-opensearch-serverless.md (1)
10-16: LGTM!Also applies to: 69-74, 104-104, 241-244
README.md (1)
27-27: LGTM!Also applies to: 64-84, 134-135, 231-231, 251-259, 318-319, 406-426
docs/source/integration/rest-api.md (1)
238-242: 🗄️ Data Integrity & IntegrationNo issue: the response shape already matches the docs example.
JobStateResponsecarries the reconstructed event data inartifacts;stateis anullplaceholder here, so there’s no separate canonical field for clients to deserialize.> Likely an incorrect or invalid review comment.docs/source/customization/guardrails.md (1)
10-23: LGTM!Also applies to: 37-45, 71-82, 121-136
deploy/helm/README.md (1)
30-43: LGTM!Also applies to: 175-178, 293-293, 415-415
src/aiq_agent/agents/deep_researcher/README.md (1)
1-30: LGTM!Also applies to: 31-45, 46-57
docs/source/architecture/data-flow.md (1)
26-26: LGTM!Also applies to: 44-68, 99-102, 115-116, 126-126, 142-194, 244-257
docs/source/customization/mcp-tools.md (1)
33-35: LGTM!Also applies to: 217-218, 284-284, 305-307, 330-330, 381-385
docs/source/architecture/overview.md (1)
30-32: LGTM!Also applies to: 69-71, 82-128
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/source/get-started/installation.md (1)
148-150: 🔒 Security & Privacy | 🟡 Minor | ⚡ Quick winClarify that
noneauthentication is local-only.This copy-paste installation guidance lists
nonealongside remote authentication modes without stating that it is only safe for a protected local development endpoint. Explicitly requirebasicor SigV4 for remote, shared, and production deployments.As per coding guidelines, security and authentication guidance must not weaken auth gating or encourage unsafe defaults.
🤖 Prompt for 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. In `@docs/source/get-started/installation.md` around lines 148 - 150, Update the OpenSearch authentication guidance near the `configs/config_web_opensearch.yml` reference to state that `none` is only for protected local development endpoints; explicitly require `basic` or SigV4 authentication for remote, shared, and production deployments.Source: Coding guidelines
🤖 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.
Outside diff comments:
In `@docs/source/get-started/installation.md`:
- Around line 148-150: Update the OpenSearch authentication guidance near the
`configs/config_web_opensearch.yml` reference to state that `none` is only for
protected local development endpoints; explicitly require `basic` or SigV4
authentication for remote, shared, and production deployments.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 023312a9-ee13-4ee6-a7c2-a4f37c033512
📒 Files selected for processing (3)
docs/source/customization/knowledge-layer.mddocs/source/get-started/installation.mddocs/source/profiling/index.md
📜 Review details
⏰ Context from checks skipped due to timeout. (4)
- GitHub Check: Run Harbor skill eval
- GitHub Check: CodeRabbit / Review
- GitHub Check: Lint and Hooks
- GitHub Check: Pytest and Coverage
🧰 Additional context used
📓 Path-based instructions (3)
docs/source/**/*
📄 CodeRabbit inference engine (AGENTS.md)
Update the docs under docs/source/ when behavior, configuration, or workflows change
Files:
docs/source/get-started/installation.mddocs/source/profiling/index.mddocs/source/customization/knowledge-layer.md
**
⚙️ CodeRabbit configuration file
**:AI-Q Agent Guidance
Repository-global instructions for coding agents and for humans reviewing
agent-authored changes. These rules apply to every task in this repository.
Task-specific runbooks live in.agents/skills/— load the
relevant skill before starting a workflow it covers.Project overview
AI-Q is an NVIDIA AI Blueprint: an enterprise research agent built on the
NeMo Agent Toolkit (NAT). The deployed product is a research blueprint, not
a general skill runtime. New retrieval sources and tools are NAT functions;
agent behavior is driven by workflow YAML, Jinja2 prompts, and a data-source
registry — not by hard-coded logic.Primary boundaries:
- Backend Python package:
src/aiq_agent/.- Data-source and tool packages:
sources/(each is its own package).- Frontends and tooling:
frontends/(web UI infrontends/ui/, eval harnesses
infrontends/benchmarks/).- Configs, deployment, docs:
configs/,deploy/,docs/.Stay inside this repository. If your workspace also contains adjacent repos
(for example a sibling NeMo-Relay checkout), do not edit them as part of an AI-Q
change. Treatsources/*as independent packages: prefer the smallest change
scoped to the package you are touching.Repository structure
Path Purpose src/aiq_agent/Backend agent, FastAPI extensions, auth, observability, knowledge sources/Data-source / tool packages (e.g. tavily_web_search,google_scholar_paper_search)configs/Workflow YAML configs (e.g. config_cli_default.yml)frontends/ui/Next.js / React / TypeScript / Tailwind / KUI web UI frontends/benchmarks/Eval harnesses: freshqa,deepsearch_qa,deepresearch_benchdeploy/Docker Compose and Helm/Kubernetes assets; deploy/.envfor secretsdocs/source/...
Files:
docs/source/get-started/installation.mddocs/source/profiling/index.mddocs/source/customization/knowledge-layer.md
{docs/**,README.md,CONTRIBUTING.md,SECURITY.md,CODE-OF-CONDUCT.md}
⚙️ CodeRabbit configuration file
{docs/**,README.md,CONTRIBUTING.md,SECURITY.md,CODE-OF-CONDUCT.md}: Review documentation for command accuracy, branch-name consistency, current CI and copy-pr-bot behavior, public
vs internal boundary clarity, stale examples, and links that no longer match the repository layout.
Files:
docs/source/get-started/installation.mddocs/source/profiling/index.mddocs/source/customization/knowledge-layer.md
🪛 LanguageTool
docs/source/profiling/index.md
[style] ~128-~128: ‘at a discount’ might be wordy. Consider a shorter alternative.
Context: ...n path. - Cached tokens may be billed at a discount. Without explicit tracking, you canno...
(EN_WORDINESS_PREMIUM_AT_A_DISCOUNT)
🔇 Additional comments (3)
docs/source/customization/knowledge-layer.md (1)
18-18: LGTM!Also applies to: 46-59, 78-78, 119-123, 167-204, 216-216, 231-231, 266-270, 347-347, 453-460, 474-475, 497-497
docs/source/get-started/installation.md (1)
28-33: LGTM!Also applies to: 54-54, 99-104, 139-146
docs/source/profiling/index.md (1)
118-133: LGTM!Also applies to: 165-165, 195-197, 206-209, 227-227, 244-260
|
@coderabbitai can you re-review/approve? |
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
AjayThorve
changed the title
tanleach
left a comment
tanleach
left a comment
There was a problem hiding this comment.
Thanks for doing this.
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
|
@coderabbitai can you review? |
|
✅ Action performedReview finished.
|
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
README.md (1)
271-271: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winDescribe
esandaossas SigV4 service values, not authentication modes.The configuration reference defines authentication modes as
none,basic, andsigv4;esandaossselect the SigV4 service. Reword this profile description to avoid users configuring an invalidopensearch_auth_type.🤖 Prompt for 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. In `@README.md` at line 271, Update the config_web_opensearch.yml profile description to state that it supports the SigV4 authentication mode with `es` and `aoss` as service values, rather than describing them as authentication modes; retain the self-hosted and Tavily details.
🤖 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 `@CHANGELOG.md`:
- Around line 5-6: Update the CHANGELOG introductory text to remove the
nonexistent `release/2.2` branch reference, replacing it with “a future release
branch” or omitting the branch name while preserving the candidate stabilization
context.
---
Outside diff comments:
In `@README.md`:
- Line 271: Update the config_web_opensearch.yml profile description to state
that it supports the SigV4 authentication mode with `es` and `aoss` as service
values, rather than describing them as authentication modes; retain the
self-hosted and Tavily details.
🪄 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: ASSERTIVE
Plan: Enterprise
Run ID: ac12b2cc-2514-4665-b1e8-6f59c201ec79
📒 Files selected for processing (9)
.secrets.baselineCHANGELOG.mdREADME.mddeploy/helm/README.mddocs/source/customization/configuration-reference.mddocs/source/deployment/aws-opensearch-serverless.mddocs/source/get-started/quick-start.mddocs/source/index.mddocs/source/profiling/index.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (4)
docs/source/**/*
📄 CodeRabbit inference engine (AGENTS.md)
Update the docs under docs/source/ when behavior, configuration, or workflows change
Files:
docs/source/get-started/quick-start.mddocs/source/index.mddocs/source/profiling/index.mddocs/source/deployment/aws-opensearch-serverless.mddocs/source/customization/configuration-reference.md
**
⚙️ CodeRabbit configuration file
**:AI-Q Agent Guidance
Repository-global instructions for coding agents and for humans reviewing
agent-authored changes. These rules apply to every task in this repository.
Task-specific runbooks live in.agents/skills/— load the
relevant skill before starting a workflow it covers.Project overview
AI-Q is an NVIDIA AI Blueprint: an enterprise research agent built on the
NeMo Agent Toolkit (NAT). The deployed product is a research blueprint, not
a general skill runtime. New retrieval sources and tools are NAT functions;
agent behavior is driven by workflow YAML, Jinja2 prompts, and a data-source
registry — not by hard-coded logic.Primary boundaries:
- Backend Python package:
src/aiq_agent/.- Data-source and tool packages:
sources/(each is its own package).- Frontends and tooling:
frontends/(web UI infrontends/ui/, eval harnesses
infrontends/benchmarks/).- Configs, deployment, docs:
configs/,deploy/,docs/.Stay inside this repository. If your workspace also contains adjacent repos
(for example a sibling NeMo-Relay checkout), do not edit them as part of an AI-Q
change. Treatsources/*as independent packages: prefer the smallest change
scoped to the package you are touching.Repository structure
Path Purpose src/aiq_agent/Backend agent, FastAPI extensions, auth, observability, knowledge sources/Data-source / tool packages (e.g. tavily_web_search,google_scholar_paper_search)configs/Workflow YAML configs (e.g. config_cli_default.yml)frontends/ui/Next.js / React / TypeScript / Tailwind / KUI web UI frontends/benchmarks/Eval harnesses: freshqa,deepsearch_qa,deepresearch_benchdeploy/Docker Compose and Helm/Kubernetes assets; deploy/.envfor secretsdocs/source/...
Files:
docs/source/get-started/quick-start.mddocs/source/index.mdCHANGELOG.mddocs/source/profiling/index.mddocs/source/deployment/aws-opensearch-serverless.mddeploy/helm/README.mddocs/source/customization/configuration-reference.mdREADME.md
{docs/**,README.md,CONTRIBUTING.md,SECURITY.md,CODE-OF-CONDUCT.md}
⚙️ CodeRabbit configuration file
{docs/**,README.md,CONTRIBUTING.md,SECURITY.md,CODE-OF-CONDUCT.md}: Review documentation for command accuracy, branch-name consistency, current CI and copy-pr-bot behavior, public
vs internal boundary clarity, stale examples, and links that no longer match the repository layout.
Files:
docs/source/get-started/quick-start.mddocs/source/index.mddocs/source/profiling/index.mddocs/source/deployment/aws-opensearch-serverless.mddocs/source/customization/configuration-reference.mdREADME.md
{deploy/**,configs/**}
⚙️ CodeRabbit configuration file
{deploy/**,configs/**}: Review deployment and config changes for secret separation, safe defaults, local-vs-production behavior, Helm and
Docker portability, and documentation parity. Flag committed credentials, environment-specific NVIDIA internals in
public defaults, and changes that make examples diverge from CI-tested paths.
Files:
deploy/helm/README.md
🔇 Additional comments (8)
docs/source/get-started/quick-start.md (1)
71-71: LGTM!Also applies to: 140-141
docs/source/index.md (1)
16-16: LGTM!.secrets.baseline (1)
136-136: LGTM!Also applies to: 172-172, 358-358
docs/source/customization/configuration-reference.md (1)
82-82: LGTM!Also applies to: 155-169, 207-232, 262-281, 292-309, 386-388, 399-410, 421-438, 470-474, 580-594
README.md (1)
27-27: LGTM!Also applies to: 64-76, 79-98, 103-119, 151-152, 248-248, 268-270, 272-276, 335-336, 423-438, 439-446
docs/source/profiling/index.md (1)
118-133: LGTM!Also applies to: 165-165, 195-197, 206-209, 227-227, 244-260
docs/source/deployment/aws-opensearch-serverless.md (1)
10-17: LGTM!Also applies to: 70-75, 105-105, 242-245
deploy/helm/README.md (1)
30-35: LGTM!Also applies to: 175-178, 293-293, 415-415
Signed-off-by: Ajay Thorve <athorve@nvidia.com>
cdgamarose-nv
left a comment
cdgamarose-nv
left a comment
There was a problem hiding this comment.
Looks like everything is covered and it compiles and looks good to me when hosted! Good to merge on my end
#### Overview Correct documentation defects found during v2.2.0 documentation QA. Docs-only — no code or schema changes. - **`docs/source/customization/guardrails.md`** — the *Configuration Shape* example now includes each middleware's `workflow_functions` field selection (matching `configs/config_web_default_guardrails.yml`). Previously the example attached middleware with no field selection, which resolves to **zero guarded fields** — a boundary that looks configured but is not enforced. The surrounding prose now calls out that failure mode. - **`docs/source/customization/mcp-tools.md`** — no longer implies `configs/config_web_frag_mcp_auth.yml` declares a `per_user_mcp_client` function group (it deliberately omits it; the per-user MCP client is built in code per job). Security Guidance now shows `per_user_auth` as the nested `PerUserAuthConfig` object instead of a bare boolean. - **`deploy/.env.example`** — documents `AIQ_CONTENT_ENCRYPTION` / `AIQ_CONTENT_ENCRYPTION_KEY` (content encryption) and `OPENAI_API_KEY` (required by `configs/config_frontier_models.yml`). - **`skills/aiq-research` and `skills/aiq-deploy`** — version stamps bumped to `2.2.0`. Two related QA items were already resolved by #322 (stale MCP in-worker-refresh wording; the README config table and researcher-LLM default) and need no change here. #### DCO sign-off for the squash commit Signed-off-by: Tanner Leach <tleach@nvidia.com> #### Validation - Guardrails example parsed; its `workflow_functions` verified **byte-equal** to `config_web_default_guardrails.yml`, and a config copied from the example yields non-empty guarded targets. - `per_user_auth` example validated against the real `PerUserAuthConfig` fields and the shipped `gdrive` source. - `scripts/validate_skills.py` → 11 skills OK; no stale `2.1.x` remains in the edited skills. - Both changed docs MyST-parsed with the repo's enabled extensions and diffed against their pre-edit versions → **0 new warnings/errors**; the nested `per_user_auth` code block renders inside its list item. - `git diff --check` clean; new `.env.example` entries are commented placeholders with no values. - [x] I ran the relevant local checks or explained why they are not applicable. - [x] I added or updated tests for behavior changes. *(docs-only; no behavior change, so no tests)* - [x] I updated documentation for user-facing or contributor-facing changes. - [x] I confirmed this PR does not include secrets, credentials, or internal-only data. - [x] I certify this contribution under the Developer Certificate of Origin (DCO) and signed my commits with `git commit -s` or an equivalent sign-off. - [x] I replaced the DCO sign-off placeholder with my GitHub commit identity and kept the required angle brackets around the email address. #### Where should reviewers start? `docs/source/customization/guardrails.md` — the security-relevant change. Confirm the *Configuration Shape* example's `workflow_functions` matches `configs/config_web_default_guardrails.yml` so a config copied from the docs actually guards the agent boundary. #### Related Issues - N/A — found during v2.2.0 documentation QA; no public tracking issue. ## Summary by CodeRabbit * **Documentation** * Expanded the deployment environment example with optional frontier-model configuration and optional at-rest content encryption settings. * Improved NeMo Guardrails “Configuration Shape” examples, clarifying how guarded field selection is applied. * Updated per-user MCP OAuth guidance, including the required `per_user_auth` block structure and clearer security/token handling notes. * Updated deploy and research skill docs for Blueprint **2.2.0** compatibility. * **Configuration** * Documented the encryption mode and related encryption key variables, plus the frontier-model API key placeholder. Authors: - Tanner Leach (https://github.com/tanleach) Approvers: - Chantal D Gama Rose (https://github.com/cdgamarose-nv) URL: #359
4 participants
Overview
Refresh the AI-Q documentation against the live 2.2 milestone and current
developimplementation while keeping branch-facing documentation portable across future release cuts.Milestone audit as of July 10, 2026: 49 items (47 PRs and 2 issues), including 41 PRs merged to
develop, one PR merged only torelease/2.1, three open PRs (#298, #319, and this documentation PR), and two closed-unmerged PRs superseded by merged work. AI-Qv2.1.0remains the latest stable release.v2.2.0-rc1is a prerelease snapshot fromdevelop; there is no finalv2.2.0tag yet, andrelease/2.2has not been cut. These lifecycle details intentionally remain outside the develop-facing README.Validation
make -C docs SPHINXBUILD=../.venv/bin/sphinx-build SPHINXOPTS='-W --keep-going -n' htmlmake -C docs SPHINXBUILD=../.venv/bin/sphinx-build linkcheckpre-commit run --all-filesgit diff --check origin/develop...HEADindependent release-lifecycle, version-free wording, milestone, review-thread, and semantic whole-diff reviews found no remaining Critical or Important issues
I ran the relevant local checks or explained why they are not applicable.
I added or updated tests for behavior changes. Not applicable: this PR changes documentation only.
I updated documentation for user-facing or contributor-facing changes.
I confirmed this PR does not include secrets, credentials, or internal-only data.
I certify this contribution under the Developer Certificate of Origin (DCO) and signed my commits with
git commit -sor an equivalent sign-off.Where should reviewers start?
README.mdfor the version-free “What’s New” highlights and current-branch roadmap semantics.CHANGELOG.mdfor the detailed unreleased 2.2 ledger and release lifecycle.docs/source/architecture/agents/deep-researcher.mdfor the routed planner/researcher/writer contract.docs/source/architecture/data-flow.mdanddocs/source/integration/rest-api.mdfor artifact checkpoint, SSE, replay, and authorization semantics.docs/source/deployment/kubernetes.mdanddocs/source/deployment/observability.mdfor the newly merged namespace and trace-hierarchy behavior.Related Issues
Summary by CodeRabbit