Repository navigation
docs: fix v2.2.0 documentation defects - #359
rapids-bot[bot] merged 5 commits into
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. |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Enterprise Run ID: 📒 Files selected for processing (1)
📜 Recent review details🧰 Additional context used📓 Path-based instructions (2)docs/source/**/*📄 CodeRabbit inference engine (AGENTS.md)
Files:
{docs/**,README.md,CONTRIBUTING.md,SECURITY.md,CODE-OF-CONDUCT.md}⚙️ CodeRabbit configuration file
Files:
🧠 Learnings (1)📓 Common learnings🔇 Additional comments (1)
WalkthroughThe pull request adds environment examples for frontier models and content encryption, expands Guardrails and MCP OAuth documentation, updates deployment and research skill compatibility guidance to Blueprint 2.2.0, and refreshes the secrets baseline metadata. ChangesConfiguration guidance
Customization documentation
Skill compatibility documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
tanleach
changed the title
Correct documentation defects found during v2.2.0 QA: - guardrails: make the Configuration Shape example self-contained by adding each middleware's workflow_functions field selection (matching config_web_default_guardrails.yml), so a config copied from the docs actually guards fields instead of resolving to zero guarded targets. Note that failure mode in the surrounding prose. - mcp-tools: stop implying config_web_frag_mcp_auth.yml declares a per_user_mcp_client function group; it deliberately omits it and builds the per-user MCP client in code per job. - mcp-tools: document per_user_auth as the nested PerUserAuthConfig object rather than a bare boolean. - .env.example: document AIQ_CONTENT_ENCRYPTION / AIQ_CONTENT_ENCRYPTION_KEY and OPENAI_API_KEY (required by config_frontier_models.yml). - skills: bump aiq-research and aiq-deploy version stamps to 2.2.0. Signed-off-by: Tanner Leach <tleach@nvidia.com>
ebdf5e3 to
6b29c60
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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/mcp-tools.md`:
- Around line 349-355: Insert a blank line immediately after the closing YAML
code fence in the per_user_auth example, before the following list item, to
satisfy the MD031 Markdown formatting requirement.
🪄 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: 4155f933-2642-4d63-96ec-d4bdda6fa4b5
📒 Files selected for processing (5)
deploy/.env.exampledocs/source/customization/guardrails.mddocs/source/customization/mcp-tools.mdskills/aiq-deploy/SKILL.mdskills/aiq-research/SKILL.md
📜 Review details
⏰ Context from checks skipped due to timeout. (2)
- GitHub Check: Run Harbor skill eval
- GitHub Check: Pytest and Coverage
🧰 Additional context used
📓 Path-based instructions (5)
skills/aiq-deploy/**/*
📄 CodeRabbit inference engine (skills/aiq-deploy/SKILL.md)
skills/aiq-deploy/**/*: Do not store credentials in chat transcripts, shell history, committed files, or example commands; usedeploy/.envor environment variables instead.
Ask for explicit user approval before destructive cleanup, including Docker volume deletion withdocker compose down -v.
After startup, run the appropriate health checks and do not claim the backend is ready if validation fails; diagnose failures using the troubleshooting guidance.
Report the verifiedAIQ_SERVER_URLtoaiq-research, usinghttp://localhost:8000for the default backend or the configured non-default port.
Do not continue into deep research or deep-research completion validation unless the user requests it or confirms the post-deployment validation prompt.
Only use a Blueprint version compatible with skill version 2.2.0: the major versions must match and the Blueprint minor version must be at least 2.2; proceed with incompatibility only after the user accepts the risk.
When no deployment mode is specified, ask the user to choose among Skill backend, CLI, UI, or Custom before starting services; do not ask this when the mode is already specified or whenaiq-researchrouted the request for backend startup.
Before acting on a selected deployment path, read its referenced documentation, such as Docker Compose, Helm, CLI, local web, validation, troubleshooting, or shutdown instructions.
Files:
skills/aiq-deploy/SKILL.md
{skills/**,.agents/skills/**,.claude/skills/**,.github/skill-eval/**}
⚙️ CodeRabbit configuration file
{skills/**,.agents/skills/**,.claude/skills/**,.github/skill-eval/**}: Review Agent Skill and skill-eval changes for valid skill metadata, deterministic eval specs, safe handling of
credentials, and clear generated-output boundaries. Do not flag SKILL.md files for missing SPDX headers when the
entrypoint intentionally starts with YAML frontmatter.
Files:
skills/aiq-deploy/SKILL.mdskills/aiq-research/SKILL.md
skills/aiq-research/**/SKILL.md
📄 CodeRabbit inference engine (skills/aiq-research/SKILL.md)
skills/aiq-research/**/SKILL.md: Use this skill for research-shaped requests, but do not use it for install, deploy, start, stop, UI, CLI, Docker, Helm, or troubleshooting requests; hand those toaiq-deploy.
Runhealthbefore sending research requests, and if no backend is reachable, ask for a backend URL or hand off toaiq-deploy.
Before sending any user query, state the exact AI-Q backend URL that will receive it; use non-local URLs only after the user explicitly confirms they are trusted.
Do not send credentials, cookies, bearer tokens, API keys, or secret values through query text orAIQ_SERVER_URL; keep backend credentials in the deployment environment.
Poll asynchronous deep-research jobs when a job ID is returned, and use the same absolute script path for polling.
Stop on failed, failure, or cancelled jobs, show the returned error, and do not retry automatically.
Present returned reports with citations and source URLs intact; do not truncate them in follow-up answers.
For report questions answerable from the report already in hand, answer directly without calling the backend again; call the backend only when new investigation is needed.
When polling is interrupted, resume the server-side job withstatus,report, orresearch_pollrather than treating it as lost.
Usereport --out-dirorartifacts --download-dirto materialize artifact links when a self-contained local report or files are required; do not expect base64 image data in the report.
This skill is compatible with Blueprint versions whose major version matches skill major version and whose minor version is equal to or greater than 2; proceed with incompatible versions only when the user accepts the compatibility risk.
The public helper does not manage authentication tokens or cookies; stop on HTTP 401 or 403 and direct the user to an authenticated skill or an appropriately configured environment.
Files:
skills/aiq-research/SKILL.md
docs/source/**/*
📄 CodeRabbit inference engine (AGENTS.md)
Update the docs under docs/source/ when behavior, configuration, or workflows change
Files:
docs/source/customization/mcp-tools.mddocs/source/customization/guardrails.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/customization/mcp-tools.mddocs/source/customization/guardrails.md
🪛 LanguageTool
skills/aiq-deploy/SKILL.md
[style] ~193-~193: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...patible with Blueprint version 2.3.0. - Skill version 2.2.0 is compatible with Bluepr...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~194-~194: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...patible with Blueprint version 2.2.5. - Skill version 2.2.0 is not compatible with Bl...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~194-~194: Consider using “incompatible” to avoid wordiness.
Context: ...version 2.2.5. - Skill version 2.2.0 is not compatible with Blueprint version 3.0.0. - Skill v...
(NOT_ABLE_PREMIUM)
[style] ~195-~195: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...patible with Blueprint version 3.0.0. - Skill version 2.2.0 is not compatible with Bl...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~195-~195: Consider using “incompatible” to avoid wordiness.
Context: ...version 3.0.0. - Skill version 2.2.0 is not compatible with Blueprint version 2.1.0. If your ...
(NOT_ABLE_PREMIUM)
skills/aiq-research/SKILL.md
[style] ~232-~232: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...patible with Blueprint version 2.3.0. - Skill version 2.2.0 is compatible with Bluepr...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~233-~233: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...patible with Blueprint version 2.2.5. - Skill version 2.2.0 is not compatible with Bl...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~233-~233: Consider using “incompatible” to avoid wordiness.
Context: ...version 2.2.5. - Skill version 2.2.0 is not compatible with Blueprint version 3.0.0. - Skill v...
(NOT_ABLE_PREMIUM)
[style] ~234-~234: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...patible with Blueprint version 3.0.0. - Skill version 2.2.0 is not compatible with Bl...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~234-~234: Consider using “incompatible” to avoid wordiness.
Context: ...version 3.0.0. - Skill version 2.2.0 is not compatible with Blueprint version 2.1.0. If your ...
(NOT_ABLE_PREMIUM)
🪛 markdownlint-cli2 (0.23.0)
docs/source/customization/mcp-tools.md
[warning] 355-355: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🔇 Additional comments (6)
deploy/.env.example (1)
19-21: LGTM!Also applies to: 75-85
skills/aiq-deploy/SKILL.md (1)
12-12: LGTM!Also applies to: 175-175, 191-195
skills/aiq-research/SKILL.md (2)
16-16: LGTM!Also applies to: 214-234
398-398: LGTM!docs/source/customization/guardrails.md (1)
43-71: LGTM!docs/source/customization/mcp-tools.md (1)
292-297: LGTM!
Signed-off-by: Tanner Leach <tleach@nvidia.com>
Signed-off-by: Tanner Leach <tleach@nvidia.com>
|
/merge |
97a920c
into
NVIDIA-AI-Blueprints:release/2.2
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'sworkflow_functionsfield selection (matchingconfigs/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 impliesconfigs/config_web_frag_mcp_auth.ymldeclares aper_user_mcp_clientfunction group (it deliberately omits it; the per-user MCP client is built in code per job). Security Guidance now showsper_user_authas the nestedPerUserAuthConfigobject instead of a bare boolean.deploy/.env.example— documentsAIQ_CONTENT_ENCRYPTION/AIQ_CONTENT_ENCRYPTION_KEY(content encryption) andOPENAI_API_KEY(required byconfigs/config_frontier_models.yml).skills/aiq-researchandskills/aiq-deploy— version stamps bumped to2.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_functionsverified byte-equal toconfig_web_default_guardrails.yml, and a config copied from the example yields non-empty guarded targets.per_user_authexample validated against the realPerUserAuthConfigfields and the shippedgdrivesource.scripts/validate_skills.py→ 11 skills OK; no stale2.1.xremains 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_authcode block renders inside its list item.git diff --checkclean; new.env.exampleentries are commented placeholders with no values.I ran the relevant local checks or explained why they are not applicable.
I added or updated tests for behavior changes. (docs-only; no behavior change, so no tests)
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.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'sworkflow_functionsmatchesconfigs/config_web_default_guardrails.ymlso a config copied from the docs actually guards the agent boundary.Related Issues
Summary by CodeRabbit
per_user_authblock structure and clearer security/token handling notes.