refactor(clarifier): remove plan approval; keep context + output-type clarification - #303
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughThis PR removes the research-plan generation and plan-approval workflow from the Clarifier agent throughout the codebase. ChangesClarifier plan-approval removal
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related PRs
Important Pre-merge checks failedPlease resolve all errors before merging. Addressing warnings is optional. ❌ Failed checks (1 error)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![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
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
docs/notebooks/1_Deep_Researcher_Web_Search.ipynb (1)
248-252: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winDrop the last planner-era wording here.
This step still talks about
planartifacts and “reads plan and research outputs,” but the planner/plan-approval flow was removed. Rephrase it aroundrun_research_batchand generic scratch/shared artifacts only.As per path instructions, review documentation for command accuracy and stale examples.
🤖 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/notebooks/1_Deep_Researcher_Web_Search.ipynb` around lines 248 - 252, The notebook narrative still contains planner-era wording about “plan artifacts” and “reads plan and research outputs,” which no longer matches the current flow. Update the text in the section describing `agent.ainvoke(...)` so it refers only to the orchestrator, `run_research_batch`, and generic scratch/shared artifacts used by the researcher agents, and remove any mention of plan approval or plan outputs.Source: Path instructions
src/aiq_agent/agents/deep_researcher/custom_middleware.py (1)
502-504: 🩺 Stability & Availability | 🔵 Trivial | 💤 Low valueRemove or rewire
PlanPersistenceMiddlewareIt no longer appears in the deep-researcher middleware stack, soaafter_agentis dead code and the planner-specific docstring is stale.🤖 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 `@src/aiq_agent/agents/deep_researcher/custom_middleware.py` around lines 502 - 504, `PlanPersistenceMiddleware.aafter_agent` is now unused in the deep-researcher flow, so remove the dead method or reconnect it to the active middleware stack. Update the stale planner-specific docstring in `PlanPersistenceMiddleware` to match the current behavior, and keep only the persistence logic that is actually invoked from the remaining middleware path.
🤖 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/notebooks/2_Deep_Researcher_Customization.ipynb`:
- Around line 272-273: Update the notebook guidance text to remove the stale
reference to “the plan” and replace it with “workflow” or “trace” so it matches
the current behavior. Locate the instructional paragraph mentioning
paper_search_tool/paper_search in the notebook content and revise that sentence
only, keeping the rest of the tool-invocation examples unchanged.
In `@docs/source/customization/prompts.md`:
- Around line 233-239: Update the deep researcher prompt-loading example to
include the source_router prompt alongside orchestrator, researcher, and writer,
since DeepResearcherAgent also loads source_router.j2 via load_prompt in
agent.py. Make the override set explicit by naming source_router in the example
so readers see all prompts required for a complete customization.
In `@docs/source/get-started/installation.md`:
- Around line 28-30: Clarify the deep-research model table entry so only the
writer role is marked optional, since the current wording around the
installation guidance makes the whole orchestrator/writer row seem optional.
Update the documentation in the installation guide to keep the deep research
orchestrator as required and rephrase the `LLM (deep research
orchestrator/writer, optional)` entry so the optionality applies only to the
writer side. Use the existing model table entry as the place to adjust the
wording and ensure it matches the current config shape.
---
Outside diff comments:
In `@docs/notebooks/1_Deep_Researcher_Web_Search.ipynb`:
- Around line 248-252: The notebook narrative still contains planner-era wording
about “plan artifacts” and “reads plan and research outputs,” which no longer
matches the current flow. Update the text in the section describing
`agent.ainvoke(...)` so it refers only to the orchestrator,
`run_research_batch`, and generic scratch/shared artifacts used by the
researcher agents, and remove any mention of plan approval or plan outputs.
In `@src/aiq_agent/agents/deep_researcher/custom_middleware.py`:
- Around line 502-504: `PlanPersistenceMiddleware.aafter_agent` is now unused in
the deep-researcher flow, so remove the dead method or reconnect it to the
active middleware stack. Update the stale planner-specific docstring in
`PlanPersistenceMiddleware` to match the current behavior, and keep only the
persistence logic that is actually invoked from the remaining middleware path.
🪄 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: 38e7c85e-f98c-407e-b980-748bfef093a5
📒 Files selected for processing (63)
.agents/skills/aiq-customize-prompts-models/SKILL.md.agents/skills/aiq-customize-prompts-models/references/model-selection.md.agents/skills/aiq-customize-prompts-models/references/prompt-templates.mdconfigs/config_cli_default.ymlconfigs/config_domain_routing_and_skills.ymlconfigs/config_frontier_models.ymlconfigs/config_openshell.ymlconfigs/config_web_default_guardrails.ymlconfigs/config_web_default_llamaindex.ymlconfigs/config_web_frag.ymlconfigs/config_web_frag_mcp_auth.ymldocs/notebooks/0_Getting_Started_with_AIQ.ipynbdocs/notebooks/1_Deep_Researcher_Web_Search.ipynbdocs/notebooks/2_Deep_Researcher_Customization.ipynbdocs/source/architecture/agents/clarifier.mddocs/source/architecture/agents/deep-researcher.mddocs/source/architecture/overview.mddocs/source/customization/configuration-reference.mddocs/source/customization/hitl.mddocs/source/customization/index.mddocs/source/customization/prompts.mddocs/source/customization/swapping-models.mddocs/source/examples/cli-with-local-nims.mddocs/source/examples/full-pipeline-llamaindex.mddocs/source/examples/full-pipeline-web.mddocs/source/examples/hybrid-frontier-model.mddocs/source/examples/skills-sandbox/index.mddocs/source/get-started/installation.mddocs/source/profiling/index.mddocs/source/resources/faq.mddocs/source/resources/troubleshooting.mdfrontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench.ymlfrontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench_profiling.ymlfrontends/benchmarks/deepsearch_qa/configs/config_deepsearch_qa.ymlfrontends/benchmarks/freshqa/configs/config_full_workflow.ymlsrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/clarifier/agent.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/clarifier/prompts/plan_generation.j2src/aiq_agent/agents/clarifier/prompts/research_clarification.j2src/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/deep_researcher/README.mdsrc/aiq_agent/agents/deep_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pysrc/aiq_agent/agents/deep_researcher/factory.pysrc/aiq_agent/agents/deep_researcher/models/__init__.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2src/aiq_agent/agents/deep_researcher/prompts/planner.j2src/aiq_agent/agents/deep_researcher/prompts/researcher.j2src/aiq_agent/agents/deep_researcher/prompts/source_router.j2src/aiq_agent/agents/deep_researcher/prompts/writer.j2src/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pysrc/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.mdsrc/aiq_agent/agents/deep_researcher/skills/synthesis/prediction-report-writer/SKILL.mdtests/aiq_agent/agents/clarifier/models/test_state.pytests/aiq_agent/agents/clarifier/test_agent.pytests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pytests/aiq_agent/agents/deep_researcher/test_agent.pytests/aiq_agent/agents/deep_researcher/test_custom_middleware.pytests/aiq_agent/agents/deep_researcher/test_factory.pytests/aiq_agent/jobs/test_runner.py
💤 Files with no reviewable changes (20)
- frontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench.yml
- src/aiq_agent/agents/deep_researcher/prompts/planner.j2
- configs/config_domain_routing_and_skills.yml
- docs/source/examples/full-pipeline-llamaindex.md
- frontends/benchmarks/deepsearch_qa/configs/config_deepsearch_qa.yml
- docs/source/examples/hybrid-frontier-model.md
- frontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench_profiling.yml
- src/aiq_agent/agents/deep_researcher/models/init.py
- src/aiq_agent/agents/clarifier/prompts/plan_generation.j2
- configs/config_web_frag.yml
- docs/source/examples/cli-with-local-nims.md
- frontends/benchmarks/freshqa/configs/config_full_workflow.yml
- configs/config_web_default_llamaindex.yml
- configs/config_web_default_guardrails.yml
- configs/config_web_frag_mcp_auth.yml
- configs/config_frontier_models.yml
- configs/config_openshell.yml
- configs/config_cli_default.yml
- tests/aiq_agent/agents/clarifier/test_agent.py
- tests/aiq_agent/agents/deep_researcher/test_custom_middleware.py
📜 Review details
⏰ Context from checks skipped due to timeout. (1)
- GitHub Check: Lint and Hooks
🧰 Additional context used
📓 Path-based instructions (8)
docs/source/**/*
📄 CodeRabbit inference engine (AGENTS.md)
Update the docs under docs/source/ when behavior, configuration, or workflows change
Files:
docs/source/customization/index.mddocs/source/resources/troubleshooting.mddocs/source/customization/hitl.mddocs/source/examples/skills-sandbox/index.mddocs/source/architecture/overview.mddocs/source/get-started/installation.mddocs/source/customization/swapping-models.mddocs/source/resources/faq.mddocs/source/examples/full-pipeline-web.mddocs/source/profiling/index.mddocs/source/customization/prompts.mddocs/source/architecture/agents/clarifier.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/customization/index.mddocs/source/resources/troubleshooting.mdsrc/aiq_agent/agents/deep_researcher/agent.pysrc/aiq_agent/agents/chat_researcher/agent.pydocs/source/customization/hitl.mddocs/source/examples/skills-sandbox/index.mdsrc/aiq_agent/agents/clarifier/prompts/research_clarification.j2docs/source/architecture/overview.mdsrc/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pysrc/aiq_agent/agents/deep_researcher/prompts/source_router.j2docs/source/get-started/installation.mddocs/source/customization/swapping-models.mdsrc/aiq_agent/agents/deep_researcher/prompts/researcher.j2docs/source/resources/faq.mdsrc/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.mddocs/source/examples/full-pipeline-web.mdsrc/aiq_agent/agents/deep_researcher/skills/synthesis/prediction-report-writer/SKILL.mddocs/source/profiling/index.mdtests/aiq_agent/agents/clarifier/models/test_state.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pysrc/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2src/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/deep_researcher/prompts/writer.j2docs/notebooks/0_Getting_Started_with_AIQ.ipynbdocs/source/customization/prompts.mddocs/source/architecture/agents/clarifier.mdsrc/aiq_agent/agents/clarifier/register.pydocs/source/architecture/agents/deep-researcher.mddocs/source/customization/configuration-reference.mdsrc/aiq_agent/agents/deep_researcher/register.pytests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/README.mdtests/aiq_agent/jobs/test_runner.pydocs/notebooks/2_Deep_Researcher_Customization.ipynbdocs/notebooks/1_Deep_Researcher_Web_Search.ipynbsrc/aiq_agent/agents/deep_researcher/factory.pytests/aiq_agent/agents/deep_researcher/test_factory.pysrc/aiq_agent/agents/clarifier/agent.pytests/aiq_agent/agents/deep_researcher/test_agent.py
{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/index.mddocs/source/resources/troubleshooting.mddocs/source/customization/hitl.mddocs/source/examples/skills-sandbox/index.mddocs/source/architecture/overview.mddocs/source/get-started/installation.mddocs/source/customization/swapping-models.mddocs/source/resources/faq.mddocs/source/examples/full-pipeline-web.mddocs/source/profiling/index.mddocs/notebooks/0_Getting_Started_with_AIQ.ipynbdocs/source/customization/prompts.mddocs/source/architecture/agents/clarifier.mddocs/source/architecture/agents/deep-researcher.mddocs/source/customization/configuration-reference.mddocs/notebooks/2_Deep_Researcher_Customization.ipynbdocs/notebooks/1_Deep_Researcher_Web_Search.ipynb
{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:
.agents/skills/aiq-customize-prompts-models/references/prompt-templates.md.agents/skills/aiq-customize-prompts-models/SKILL.md.agents/skills/aiq-customize-prompts-models/references/model-selection.md
**/*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run ruff check and ruff format validation for Python code changes
**/*.py: Python code must be linted and formatted with Ruff using line length 120, target Python 3.11, rule sets E,F,W,I,PL,UP, and isort force-single-line configuration
Never commit secrets, tokens, or environment-specific hostnames; use environment variables and SecretStr instead, resolving API keys at runtime
Never print or log secret values, including in tool output or error messages
Missing-secret paths must degrade gracefully (stub/skip), not crash or leak
Do not hand-reformat unrelated code when making changes; match the existing import and formatting style
Files:
src/aiq_agent/agents/deep_researcher/agent.pysrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pytests/aiq_agent/agents/clarifier/models/test_state.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/deep_researcher/register.pytests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pytests/aiq_agent/jobs/test_runner.pysrc/aiq_agent/agents/deep_researcher/factory.pytests/aiq_agent/agents/deep_researcher/test_factory.pysrc/aiq_agent/agents/clarifier/agent.pytests/aiq_agent/agents/deep_researcher/test_agent.py
src/aiq_agent/**/*.py
📄 CodeRabbit inference engine (AGENTS.md)
src/aiq_agent/**/*.py: Respect authenticated data sources by honoring requires_auth, per-user token pass-through, and backend token validators; apply owner guardrails before loading protected report or artifact context into an agent
Do not weaken or bypass AuthMiddleware, validators, or auth gating without a prior design discussion
Files:
src/aiq_agent/agents/deep_researcher/agent.pysrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/factory.pysrc/aiq_agent/agents/clarifier/agent.py
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/agent.pysrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/clarifier/prompts/research_clarification.j2src/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pysrc/aiq_agent/agents/deep_researcher/prompts/source_router.j2src/aiq_agent/agents/deep_researcher/prompts/researcher.j2src/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.mdsrc/aiq_agent/agents/deep_researcher/skills/synthesis/prediction-report-writer/SKILL.mdsrc/aiq_agent/agents/deep_researcher/custom_middleware.pysrc/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2src/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/deep_researcher/prompts/writer.j2src/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/README.mdsrc/aiq_agent/agents/deep_researcher/factory.pysrc/aiq_agent/agents/clarifier/agent.py
**/*test*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run pytest for all behavior changes in Python code
Files:
tests/aiq_agent/agents/clarifier/models/test_state.pytests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pytests/aiq_agent/jobs/test_runner.pytests/aiq_agent/agents/deep_researcher/test_factory.pytests/aiq_agent/agents/deep_researcher/test_agent.py
🪛 LanguageTool
docs/source/customization/hitl.md
[style] ~7-~7: Consider a different adjective to strengthen your wording.
Context: ...in-the-loop (the clarifier) runs before deep research. The clarifier gathers context...
(DEEP_PROFOUND)
[style] ~13-~13: Consider a different adjective to strengthen your wording.
Context: ...rely No clarification step runs before deep research: ```yaml workflow: _type: c...
(DEEP_PROFOUND)
docs/source/architecture/overview.md
[style] ~101-~101: Consider a different adjective to strengthen your wording.
Context: ...tgreSQL). - Subagent architecture: Deep research uses specialized subagents (...
(DEEP_PROFOUND)
docs/source/resources/faq.md
[grammar] ~29-~29: Ensure spelling is correct
Context: ...ies. - Deep research is thorough (2-10min), uses a multi-agent pipeline (orchestr...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
src/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.md
[style] ~13-~13: Consider a different adjective to strengthen your wording.
Context: ...learly asks for a comprehensive report, deep analysis, publication-ready writeup, or...
(DEEP_PROFOUND)
[grammar] ~13-~13: Ensure spelling is correct
Context: ...eport, deep analysis, publication-ready writeup, or whitepaper-style answer. Do not us...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
src/aiq_agent/agents/deep_researcher/README.md
[style] ~239-~239: Consider a different adjective to strengthen your wording.
Context: ... user goes through the clarifier before deep research, the clarification log is pass...
(DEEP_PROFOUND)
🔇 Additional comments (37)
.agents/skills/aiq-customize-prompts-models/SKILL.md (1)
3-3: LGTM!Also applies to: 52-52, 71-71
.agents/skills/aiq-customize-prompts-models/references/model-selection.md (1)
33-33: LGTM!Also applies to: 43-50, 58-60
.agents/skills/aiq-customize-prompts-models/references/prompt-templates.md (1)
18-20: LGTM!docs/notebooks/0_Getting_Started_with_AIQ.ipynb (1)
359-361: LGTM!Also applies to: 384-384, 393-400, 624-624
docs/source/profiling/index.md (1)
118-125: LGTM!Also applies to: 199-199, 237-241
docs/source/resources/faq.md (1)
29-35: LGTM!docs/notebooks/1_Deep_Researcher_Web_Search.ipynb (1)
12-12: LGTM!Also applies to: 44-48, 238-238, 268-273, 288-288, 298-298, 342-354, 633-634, 792-793
docs/notebooks/2_Deep_Researcher_Customization.ipynb (1)
9-15: LGTM!Also applies to: 27-27, 184-184, 238-241, 299-299, 324-329, 339-339, 354-355, 387-387, 398-398, 531-534, 552-552
docs/source/architecture/agents/clarifier.md (1)
9-11: LGTM!Also applies to: 21-24, 52-56, 70-71, 79-84, 102-103, 114-116, 126-127, 140-144
docs/source/architecture/agents/deep-researcher.md (1)
30-52: LGTM!Also applies to: 54-75, 77-84, 117-122, 132-133, 146-150, 165-169, 172-199
docs/source/architecture/overview.md (1)
30-32: LGTM!Also applies to: 101-103
docs/source/resources/troubleshooting.md (1)
37-37: LGTM!src/aiq_agent/agents/deep_researcher/README.md (1)
24-32: LGTM!Also applies to: 62-62, 75-89, 103-103, 123-126, 140-141, 167-169, 229-239
src/aiq_agent/agents/clarifier/models/state.py (1)
28-35: LGTM!Also applies to: 38-66
tests/aiq_agent/agents/clarifier/models/test_state.py (1)
122-133: LGTM!src/aiq_agent/agents/clarifier/agent.py (1)
96-192: LGTM! Plan-approval removal is internally consistent — constructor, prompt loading, graph routing, andrun()return shape all line up with the simplifiedClarifierResult/ClarifierAgentStatecontract.Also applies to: 403-536
src/aiq_agent/agents/clarifier/register.py (1)
62-94: LGTM!Also applies to: 121-215
src/aiq_agent/agents/clarifier/prompts/research_clarification.j2 (1)
81-81: LGTM!Also applies to: 115-120
src/aiq_agent/agents/chat_researcher/agent.py (1)
184-190: 🎯 Functional CorrectnessStale plan-approval concern
src/aiq_agent/agents/chat_researcher/agent.pyno longer has aplan_rejected/get_approved_plan_context()path, andtests/aiq_agent/agents/chat_researcher/test_agent.pydoes not assert that behavior.> Likely an incorrect or invalid review comment.src/aiq_agent/agents/deep_researcher/models/subagent_contracts.py (1)
49-51: LGTM!Also applies to: 77-80, 134-137
tests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.py (1)
27-66: LGTM!Also applies to: 111-124, 184-216
src/aiq_agent/agents/deep_researcher/register.py (1)
80-80: LGTM!Also applies to: 199-213
src/aiq_agent/agents/deep_researcher/factory.py (1)
105-107: LGTM!Also applies to: 271-279, 420-435
src/aiq_agent/agents/deep_researcher/agent.py (1)
159-159: LGTM!src/aiq_agent/agents/deep_researcher/custom_middleware.py (1)
244-248: LGTM!src/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.py (1)
80-80: LGTM!src/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2 (1)
1-11: LGTM!Also applies to: 38-96, 123-136
src/aiq_agent/agents/deep_researcher/prompts/researcher.j2 (1)
7-11: LGTM!Also applies to: 46-46
src/aiq_agent/agents/deep_researcher/prompts/source_router.j2 (1)
1-1: LGTM!
routing_guidancenaming is used consistently across the routing-principles bullets and the finalSourceRoutingPlanschema fields.Also applies to: 26-30, 39-39
src/aiq_agent/agents/deep_researcher/prompts/writer.j2 (1)
1-9: LGTM!Verified no stray
answer_strategy/plan.jsonreferences remain in this file, and the newtarget_components/summary-based synthesis contract is self-consistent with the required-inputs section.Also applies to: 30-30, 48-57, 79-79
src/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.md (1)
4-33: LGTM!Also applies to: 98-98
src/aiq_agent/agents/deep_researcher/skills/synthesis/prediction-report-writer/SKILL.md (1)
4-19: LGTM!tests/aiq_agent/agents/deep_researcher/test_agent.py (3)
326-327: LGTM!These assertions correctly track the researcher.j2/writer.j2 content shown in this PR (no
/shared/plan.json, presence oftarget_components,self-contained ResearchQuery,requested output shape, absence ofanswer_strategyand legacy plan fields).Also applies to: 383-387, 452-453, 477-480
435-441: LGTM!Subagent-set and LLM-role assertions correctly reflect planner removal (only
source-router-agent/writer-agentsubagents,LLMRole.PLANNERno longer requested).Also applies to: 535-537, 601-601, 1040-1040, 1052-1058
414-417: 🎯 Functional CorrectnessDrop this comment: the tests match the current
orchestrator.j2prompt text, including the routing and research-query strings.> Likely an incorrect or invalid review comment.tests/aiq_agent/agents/deep_researcher/test_factory.py (1)
52-58: LGTM!Provider/prompt fixtures and subagent-set assertions are consistently updated to drop the planner role/subagent.
Also applies to: 63-67, 178-186, 186-202, 203-212, 266-272
tests/aiq_agent/jobs/test_runner.py (1)
1551-1577: LGTM!
await_count == 4and the"planner-agent" not in subagentscheck correctly reflectDeepResearchAgentConfigdroppingplanner_llm.Also applies to: 1988-1994
38a9080 to
9716f96
Compare
There was a problem hiding this comment.
Actionable comments posted: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (6)
docs/notebooks/1_Deep_Researcher_Web_Search.ipynb (2)
44-54: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winStale "planning" phase reference.
Lines 44-48 rewrite the role list to remove the planner (orchestrator/writer/researcher only), but the "Phases" list right below (lines 51-54) still lists "(1) planning" as a distinct phase, which reads as leftover planner terminology. Consider rewording to match the new model (e.g., "(1) research setup", or just drop the phase list since it's no longer a discrete planner-driven step).
🤖 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/notebooks/1_Deep_Researcher_Web_Search.ipynb` around lines 44 - 54, The notebook text still refers to a separate “planning” phase even though the role list now only describes orchestrator, writer, and researcher; update the Phases section in the notebook content to match the current deep researcher flow. Reword or remove the “(1) planning” entry so it reflects the orchestrator-led setup terminology used in the rest of the document, and keep the phase list consistent with the workflow described in the surrounding markdown cells.
244-248: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winStale "plan" filesystem reference.
Line 246 still describes the deep-agent backend as providing "an in-memory state plus a
/shared/route for plan and scratch files," but the PR removes/shared/plan.jsonper the objectives. This unchanged sentence is now inconsistent with the surrounding rewrite (line 248 already drops plan terminology in favor ofResearchQuery/run_research_batch). Update the wording to drop "plan" (e.g., "a/shared/route for scratch files").🤖 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/notebooks/1_Deep_Researcher_Web_Search.ipynb` around lines 244 - 248, The notebook text in the explanation of `agent.run(state)` still refers to a `/shared/` route for “plan and scratch files,” which is now stale and inconsistent with the updated deep-agent flow. In the prose inside the `run()` walkthrough, remove the plan reference and keep the description aligned with the current backend behavior by mentioning only the `/shared/` scratch-files route and the `run_research_batch`/`ResearchQuery` flow.docs/source/customization/configuration-reference.md (1)
303-309: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winRestore
exclude_toolsin the clarifier config reference.
src/aiq_agent/agents/clarifier/register.pystill filters tools fromconfig.exclude_tools, but this table hides that supported knob. That leaves the reference incomplete for users who need to exclude specific tools.♻️ Proposed fix
| `tools` | `list[str]` | `[]` | Tools available for gathering context during clarification. | +| `exclude_tools` | `list[str]` | `[]` | Tool names to exclude from the clarification tool set. | | `max_turns` | `int` | `3` | Maximum number of clarification Q&A turns before auto-completing. |🤖 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/customization/configuration-reference.md` around lines 303 - 309, The clarifier configuration reference is missing the supported exclude-tools knob, so update the clarifier config table to include `exclude_tools` alongside `llm`, `tools`, and `max_turns`. Make sure the new row matches the behavior in `register.py`, where the clarifier still reads `config.exclude_tools` to filter tools, so users can discover and use this option.src/aiq_agent/agents/deep_researcher/models/subagent_contracts.py (1)
32-38: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winStale "planner" references in contract docstrings.
SourceRecommendationandSourceRoutingPlandocstrings still say "for the planner" / "before planning" even though the planner subagent is removed by this PR. These class docstrings are typically emitted in the Pydantic JSON schema handed to the LLM as part of the structured-output contract, so leaving stale terminology here can confuse the router/orchestrator model about a component that no longer exists.✏️ Proposed fix
class SourceRecommendation(_StrictContract): - """A source-router recommendation for the planner.""" + """A source-router recommendation for the orchestrator.""" ... class SourceRoutingPlan(_StrictContract): - """Advisory source route produced before planning.""" + """Advisory source route produced before the orchestrator runs research."""Also applies to: 41-51
🤖 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 `@src/aiq_agent/agents/deep_researcher/models/subagent_contracts.py` around lines 32 - 38, Update the docstrings on SourceRecommendation and SourceRoutingPlan in subagent_contracts.py to remove stale “planner”/“before planning” wording and replace it with terminology that matches the current router/orchestrator flow. Keep the class names and field definitions unchanged, but rewrite the descriptive text so the Pydantic schema no longer references the removed planner subagent.docs/source/architecture/overview.md (1)
64-71: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick winStale "approve a plan" references contradict the removed plan-approval flow.
This PR removes plan generation/approval from the clarifier (it now only gathers context and may clarify output type). These two spots still describe the old behavior:
- Line 70: "so the user can review and approve a plan before deep research begins"
- Line 86:
clarifier_resultdescribed as "Clarification log and approved plan context"Both should be updated to match the new clarification-only flow (consistent with the reworded
clarifier_resultdescription indeep-researcher.md).As per AGENTS.md, "Update the docs under docs/source/ when behavior, configuration, or workflows change," and per path instructions for docs files to flag "stale examples."
📝 Proposed fix
- routes to the `clarifier` node (not directly to `deep_research`), so the - user can review and approve a plan before deep research begins. + routes to the `clarifier` node (not directly to `deep_research`) so the + user can provide additional context or clarify the requested output shape + before deep research begins. Escalation is gated by the `enable_escalation` config flag. ... -| `clarifier_result` | `str` or `None` | Clarification log and approved plan context | +| `clarifier_result` | `str` or `None` | Clarification log from the Clarifier |Also applies to: 86-86
🤖 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/architecture/overview.md` around lines 64 - 71, The docs still describe the removed plan-approval flow in the clarifier path, so update the architecture overview to match the new clarification-only behavior. In the `should_escalate` section, replace the “review and approve a plan before deep research begins” wording with the current routing/clarification behavior, and in the `clarifier_result` description remove any mention of approved plan context so it reflects only clarification output. Keep the terminology consistent with `deep-researcher.md` and the `clarifier` / `clarifier_result` symbols.Sources: Coding guidelines, Path instructions
src/aiq_agent/agents/deep_researcher/custom_middleware.py (1)
502-504: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick winRemove the stale
aafter_agentplan hook
src/aiq_agent/agents/deep_researcher/custom_middleware.py:502-504
SourceRegistryMiddlewarestill defines anaafter_agenthook that calls_persist_plan(self._plan_from_state(state)), but neither helper exists anywhere in the tree. If this lifecycle hook runs, agent teardown will fail withAttributeError; delete the hook or restore the missing implementation.🤖 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 `@src/aiq_agent/agents/deep_researcher/custom_middleware.py` around lines 502 - 504, The SourceRegistryMiddleware class still defines the async lifecycle hook aafter_agent, but it calls missing helpers (_persist_plan and _plan_from_state), so it will raise AttributeError if invoked. Remove the stale aafter_agent method from custom_middleware.py, or if it is meant to stay, restore the missing helper methods and wire them into SourceRegistryMiddleware consistently.
🤖 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/notebooks/0_Getting_Started_with_AIQ.ipynb`:
- Line 384: The notebook text in the section around llms and the clarifier
describes behavior that this example config does not implement. Update the prose
to match the actual `config_simple_researcher.yml` setup by either adding
clarifier-related entries such as `clarifier_agent` and `enable_clarifier` to
the example, or removing the clarifier-specific references from the explanatory
text near the `llms` and `workflow` descriptions. Use the existing config
symbols like `intent_classifier`, `shallow_research_agent`,
`deep_research_agent`, and `workflow` to keep the wording aligned with what is
actually wired here.
In `@docs/source/architecture/agents/deep-researcher.md`:
- Around line 165-199: The Phase 4 heading in deep-researcher documentation was
renumbered, so the cross-doc anchor in overview.md is stale. Update the link
target that references agents/deep-researcher.md from the old Phase 5 anchor to
the new auto-generated Phase 4 anchor, and verify any related markdown links
that point to the citation verification section still match the heading text in
deep-researcher.md.
In `@docs/source/customization/configuration-reference.md`:
- Line 338: Update the agent description for the multi-phase research agent to
mention the optional source-router stage in addition to the orchestrator,
researcher, and writer sub-agents. In the configuration reference text, revise
the sentence tied to this agent so it reflects that `source_router_llm` and
`enable_source_router` can enable source routing as part of the workflow.
In `@docs/source/get-started/installation.md`:
- Around line 28-30: The installation table still makes the deep research
researcher model look required, while the customization flow shows it is
optional and defaults to the orchestrator model. Update the documentation entry
for the “LLM (deep research researcher)” row in installation.md to mark it as
optional, matching the existing “LLM (deep research writer, optional)” wording
and the config symbols researcher_llm, writer_llm, and orchestrator_llm. Keep
the table consistent so only the orchestrator row reads as required, and the
researcher/writer rows are clearly optional defaults.
In `@docs/source/profiling/index.md`:
- Around line 118-125: Clarify how Writer costs appear in the phase breakdown:
the profiling intro and “Cost by Phase” description currently mention only
Orchestrator and Researcher, but the Writer subagent is now part of the flow.
Update the relevant prose in the profiling docs (around the intro and the chart
description) to state whether Writer-attributed LLM calls are grouped under
Orchestrator, shown as a separate writer-phase bucket, or otherwise handled.
Refer to the “Cost by Phase” section and the Writer role mention so readers can
reconcile the chart with the three-subagent setup.
---
Outside diff comments:
In `@docs/notebooks/1_Deep_Researcher_Web_Search.ipynb`:
- Around line 44-54: The notebook text still refers to a separate “planning”
phase even though the role list now only describes orchestrator, writer, and
researcher; update the Phases section in the notebook content to match the
current deep researcher flow. Reword or remove the “(1) planning” entry so it
reflects the orchestrator-led setup terminology used in the rest of the
document, and keep the phase list consistent with the workflow described in the
surrounding markdown cells.
- Around line 244-248: The notebook text in the explanation of
`agent.run(state)` still refers to a `/shared/` route for “plan and scratch
files,” which is now stale and inconsistent with the updated deep-agent flow. In
the prose inside the `run()` walkthrough, remove the plan reference and keep the
description aligned with the current backend behavior by mentioning only the
`/shared/` scratch-files route and the `run_research_batch`/`ResearchQuery`
flow.
In `@docs/source/architecture/overview.md`:
- Around line 64-71: The docs still describe the removed plan-approval flow in
the clarifier path, so update the architecture overview to match the new
clarification-only behavior. In the `should_escalate` section, replace the
“review and approve a plan before deep research begins” wording with the current
routing/clarification behavior, and in the `clarifier_result` description remove
any mention of approved plan context so it reflects only clarification output.
Keep the terminology consistent with `deep-researcher.md` and the `clarifier` /
`clarifier_result` symbols.
In `@docs/source/customization/configuration-reference.md`:
- Around line 303-309: The clarifier configuration reference is missing the
supported exclude-tools knob, so update the clarifier config table to include
`exclude_tools` alongside `llm`, `tools`, and `max_turns`. Make sure the new row
matches the behavior in `register.py`, where the clarifier still reads
`config.exclude_tools` to filter tools, so users can discover and use this
option.
In `@src/aiq_agent/agents/deep_researcher/custom_middleware.py`:
- Around line 502-504: The SourceRegistryMiddleware class still defines the
async lifecycle hook aafter_agent, but it calls missing helpers (_persist_plan
and _plan_from_state), so it will raise AttributeError if invoked. Remove the
stale aafter_agent method from custom_middleware.py, or if it is meant to stay,
restore the missing helper methods and wire them into SourceRegistryMiddleware
consistently.
In `@src/aiq_agent/agents/deep_researcher/models/subagent_contracts.py`:
- Around line 32-38: Update the docstrings on SourceRecommendation and
SourceRoutingPlan in subagent_contracts.py to remove stale “planner”/“before
planning” wording and replace it with terminology that matches the current
router/orchestrator flow. Keep the class names and field definitions unchanged,
but rewrite the descriptive text so the Pydantic schema no longer references the
removed planner subagent.
🪄 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: ead32110-2881-48d8-a89b-8998f1a142bb
📒 Files selected for processing (63)
.agents/skills/aiq-customize-prompts-models/SKILL.md.agents/skills/aiq-customize-prompts-models/references/model-selection.md.agents/skills/aiq-customize-prompts-models/references/prompt-templates.mdconfigs/config_cli_default.ymlconfigs/config_domain_routing_and_skills.ymlconfigs/config_frontier_models.ymlconfigs/config_openshell.ymlconfigs/config_web_default_guardrails.ymlconfigs/config_web_default_llamaindex.ymlconfigs/config_web_frag.ymlconfigs/config_web_frag_mcp_auth.ymldocs/notebooks/0_Getting_Started_with_AIQ.ipynbdocs/notebooks/1_Deep_Researcher_Web_Search.ipynbdocs/notebooks/2_Deep_Researcher_Customization.ipynbdocs/source/architecture/agents/clarifier.mddocs/source/architecture/agents/deep-researcher.mddocs/source/architecture/overview.mddocs/source/customization/configuration-reference.mddocs/source/customization/hitl.mddocs/source/customization/index.mddocs/source/customization/prompts.mddocs/source/customization/swapping-models.mddocs/source/examples/cli-with-local-nims.mddocs/source/examples/full-pipeline-llamaindex.mddocs/source/examples/full-pipeline-web.mddocs/source/examples/hybrid-frontier-model.mddocs/source/examples/skills-sandbox/index.mddocs/source/get-started/installation.mddocs/source/profiling/index.mddocs/source/resources/faq.mddocs/source/resources/troubleshooting.mdfrontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench.ymlfrontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench_profiling.ymlfrontends/benchmarks/deepsearch_qa/configs/config_deepsearch_qa.ymlfrontends/benchmarks/freshqa/configs/config_full_workflow.ymlsrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/clarifier/agent.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/clarifier/prompts/plan_generation.j2src/aiq_agent/agents/clarifier/prompts/research_clarification.j2src/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/deep_researcher/README.mdsrc/aiq_agent/agents/deep_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pysrc/aiq_agent/agents/deep_researcher/factory.pysrc/aiq_agent/agents/deep_researcher/models/__init__.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2src/aiq_agent/agents/deep_researcher/prompts/planner.j2src/aiq_agent/agents/deep_researcher/prompts/researcher.j2src/aiq_agent/agents/deep_researcher/prompts/source_router.j2src/aiq_agent/agents/deep_researcher/prompts/writer.j2src/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pysrc/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.mdsrc/aiq_agent/agents/deep_researcher/skills/synthesis/prediction-report-writer/SKILL.mdtests/aiq_agent/agents/clarifier/models/test_state.pytests/aiq_agent/agents/clarifier/test_agent.pytests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pytests/aiq_agent/agents/deep_researcher/test_agent.pytests/aiq_agent/agents/deep_researcher/test_custom_middleware.pytests/aiq_agent/agents/deep_researcher/test_factory.pytests/aiq_agent/jobs/test_runner.py
💤 Files with no reviewable changes (20)
- docs/source/examples/hybrid-frontier-model.md
- configs/config_domain_routing_and_skills.yml
- configs/config_frontier_models.yml
- configs/config_openshell.yml
- docs/source/examples/cli-with-local-nims.md
- src/aiq_agent/agents/deep_researcher/models/init.py
- frontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench.yml
- frontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench_profiling.yml
- src/aiq_agent/agents/clarifier/prompts/plan_generation.j2
- frontends/benchmarks/deepsearch_qa/configs/config_deepsearch_qa.yml
- frontends/benchmarks/freshqa/configs/config_full_workflow.yml
- src/aiq_agent/agents/deep_researcher/prompts/planner.j2
- configs/config_web_default_llamaindex.yml
- configs/config_web_default_guardrails.yml
- tests/aiq_agent/agents/clarifier/test_agent.py
- configs/config_web_frag_mcp_auth.yml
- configs/config_cli_default.yml
- docs/source/examples/full-pipeline-llamaindex.md
- configs/config_web_frag.yml
- tests/aiq_agent/agents/deep_researcher/test_custom_middleware.py
📜 Review details
⚠️ CI failures not shown inline (2)
GitHub Actions: AIQ CI / 2_Script Validation.txt: refactor(deep-research): remove planner agent and clarifier plan appr…
Conclusion: failure
Current runner version: '2.335.1'
##[group]Runner Image Provisioner
Hosted Compute Agent
Version: 20260624.560
Commit: 925d229a51159bc391ae97e54a2dd1fe20af789d
Build Date:
Worker ID: {74a74c48-5447-4228-a053-21777e9b5493}
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...
GitHub Actions: AIQ CI / Script Validation: refactor(deep-research): remove planner agent and clarifier plan appr…
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
=====================...
🧰 Additional context used
📓 Path-based instructions (8)
docs/source/**/*
📄 CodeRabbit inference engine (AGENTS.md)
Update the docs under docs/source/ when behavior, configuration, or workflows change
Files:
docs/source/resources/troubleshooting.mddocs/source/customization/swapping-models.mddocs/source/get-started/installation.mddocs/source/customization/index.mddocs/source/customization/hitl.mddocs/source/architecture/overview.mddocs/source/examples/skills-sandbox/index.mddocs/source/profiling/index.mddocs/source/resources/faq.mddocs/source/examples/full-pipeline-web.mddocs/source/architecture/agents/deep-researcher.mddocs/source/customization/configuration-reference.mddocs/source/architecture/agents/clarifier.mddocs/source/customization/prompts.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/resources/troubleshooting.mddocs/source/customization/swapping-models.mddocs/source/get-started/installation.mddocs/source/customization/index.mdsrc/aiq_agent/agents/deep_researcher/agent.pydocs/source/customization/hitl.mdsrc/aiq_agent/agents/deep_researcher/prompts/source_router.j2docs/source/architecture/overview.mdsrc/aiq_agent/agents/deep_researcher/prompts/researcher.j2tests/aiq_agent/agents/clarifier/models/test_state.pysrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/clarifier/prompts/research_clarification.j2docs/source/examples/skills-sandbox/index.mdsrc/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pydocs/source/profiling/index.mdsrc/aiq_agent/agents/clarifier/models/state.pydocs/source/resources/faq.mddocs/source/examples/full-pipeline-web.mdtests/aiq_agent/jobs/test_runner.pydocs/source/architecture/agents/deep-researcher.mdsrc/aiq_agent/agents/deep_researcher/prompts/writer.j2docs/notebooks/1_Deep_Researcher_Web_Search.ipynbtests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pydocs/source/customization/configuration-reference.mdsrc/aiq_agent/agents/deep_researcher/skills/synthesis/prediction-report-writer/SKILL.mdsrc/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.mddocs/notebooks/2_Deep_Researcher_Customization.ipynbdocs/source/architecture/agents/clarifier.mdsrc/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pydocs/notebooks/0_Getting_Started_with_AIQ.ipynbdocs/source/customization/prompts.mdtests/aiq_agent/agents/deep_researcher/test_agent.pytests/aiq_agent/agents/deep_researcher/test_factory.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2src/aiq_agent/agents/deep_researcher/factory.pysrc/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/clarifier/agent.pysrc/aiq_agent/agents/deep_researcher/README.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/resources/troubleshooting.mddocs/source/customization/swapping-models.mddocs/source/get-started/installation.mddocs/source/customization/index.mddocs/source/customization/hitl.mddocs/source/architecture/overview.mddocs/source/examples/skills-sandbox/index.mddocs/source/profiling/index.mddocs/source/resources/faq.mddocs/source/examples/full-pipeline-web.mddocs/source/architecture/agents/deep-researcher.mddocs/notebooks/1_Deep_Researcher_Web_Search.ipynbdocs/source/customization/configuration-reference.mddocs/notebooks/2_Deep_Researcher_Customization.ipynbdocs/source/architecture/agents/clarifier.mddocs/notebooks/0_Getting_Started_with_AIQ.ipynbdocs/source/customization/prompts.md
**/*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run ruff check and ruff format validation for Python code changes
**/*.py: Python code must be linted and formatted with Ruff using line length 120, target Python 3.11, rule sets E,F,W,I,PL,UP, and isort force-single-line configuration
Never commit secrets, tokens, or environment-specific hostnames; use environment variables and SecretStr instead, resolving API keys at runtime
Never print or log secret values, including in tool output or error messages
Missing-secret paths must degrade gracefully (stub/skip), not crash or leak
Do not hand-reformat unrelated code when making changes; match the existing import and formatting style
Files:
src/aiq_agent/agents/deep_researcher/agent.pytests/aiq_agent/agents/clarifier/models/test_state.pysrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pysrc/aiq_agent/agents/clarifier/models/state.pytests/aiq_agent/jobs/test_runner.pytests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pytests/aiq_agent/agents/deep_researcher/test_agent.pytests/aiq_agent/agents/deep_researcher/test_factory.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/factory.pysrc/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/clarifier/agent.py
src/aiq_agent/**/*.py
📄 CodeRabbit inference engine (AGENTS.md)
src/aiq_agent/**/*.py: Respect authenticated data sources by honoring requires_auth, per-user token pass-through, and backend token validators; apply owner guardrails before loading protected report or artifact context into an agent
Do not weaken or bypass AuthMiddleware, validators, or auth gating without a prior design discussion
Files:
src/aiq_agent/agents/deep_researcher/agent.pysrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/factory.pysrc/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/clarifier/agent.py
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/agent.pysrc/aiq_agent/agents/deep_researcher/prompts/source_router.j2src/aiq_agent/agents/deep_researcher/prompts/researcher.j2src/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/clarifier/prompts/research_clarification.j2src/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/deep_researcher/prompts/writer.j2src/aiq_agent/agents/deep_researcher/skills/synthesis/prediction-report-writer/SKILL.mdsrc/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.mdsrc/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2src/aiq_agent/agents/deep_researcher/factory.pysrc/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/clarifier/agent.pysrc/aiq_agent/agents/deep_researcher/README.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:
.agents/skills/aiq-customize-prompts-models/references/prompt-templates.md.agents/skills/aiq-customize-prompts-models/SKILL.md.agents/skills/aiq-customize-prompts-models/references/model-selection.md
**/*test*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run pytest for all behavior changes in Python code
Files:
tests/aiq_agent/agents/clarifier/models/test_state.pytests/aiq_agent/jobs/test_runner.pytests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pytests/aiq_agent/agents/deep_researcher/test_agent.pytests/aiq_agent/agents/deep_researcher/test_factory.py
🪛 LanguageTool
docs/source/customization/hitl.md
[style] ~7-~7: Consider a different adjective to strengthen your wording.
Context: ...in-the-loop (the clarifier) runs before deep research. The clarifier gathers context...
(DEEP_PROFOUND)
[style] ~13-~13: Consider a different adjective to strengthen your wording.
Context: ...rely No clarification step runs before deep research: ```yaml workflow: _type: c...
(DEEP_PROFOUND)
docs/source/architecture/overview.md
[style] ~101-~101: Consider a different adjective to strengthen your wording.
Context: ...tgreSQL). - Subagent architecture: Deep research uses specialized subagents (...
(DEEP_PROFOUND)
docs/source/resources/faq.md
[grammar] ~29-~29: Ensure spelling is correct
Context: ...ies. - Deep research is thorough (2-10min), uses a multi-agent pipeline (orchestr...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
src/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.md
[style] ~13-~13: Consider a different adjective to strengthen your wording.
Context: ...learly asks for a comprehensive report, deep analysis, publication-ready writeup, or...
(DEEP_PROFOUND)
[grammar] ~13-~13: Ensure spelling is correct
Context: ...eport, deep analysis, publication-ready writeup, or whitepaper-style answer. Do not us...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
src/aiq_agent/agents/deep_researcher/README.md
[style] ~239-~239: Consider a different adjective to strengthen your wording.
Context: ... user goes through the clarifier before deep research, the clarification log is pass...
(DEEP_PROFOUND)
🔇 Additional comments (44)
docs/notebooks/0_Getting_Started_with_AIQ.ipynb (1)
359-361: LGTM!Also applies to: 624-624
docs/source/examples/full-pipeline-web.md (1)
8-8: LGTM!Also applies to: 142-150, 186-186
tests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.py (2)
111-126: LGTM!Also applies to: 184-217
27-64: 🎯 Functional CorrectnessNo issue:
ResearchQueryincludesrationale.src/aiq_agent/agents/deep_researcher/models/subagent_contracts.pydefinesrationaleonResearchQuery, so the tests are valid as written.> Likely an incorrect or invalid review comment.tests/aiq_agent/agents/deep_researcher/test_agent.py (5)
326-331: LGTM!
383-435: Assertions align consistently with the new orchestrator prompt (source-router-agent/writer-agent only,/shared/source_routing.json, no/shared/plan.json,answer_strategyabsence). Matches the orchestrator prompt template shown in context.Also applies to: 477-485
452-453: LGTM!Also applies to: 535-537
601-635: LGTM!
1040-1058: LGTM!tests/aiq_agent/agents/deep_researcher/test_factory.py (2)
52-69: LGTM!
178-212: Consistent with the removal ofplanner-agentfrombuild_deep_research_subagents— assertions now only coversource-router-agent/writer-agent.Also applies to: 270-270
tests/aiq_agent/jobs/test_runner.py (2)
1551-1577:await_count == 4correctly reflects dropping theplanner_llmrole config (5 → 4 distinct LLM refs requested).
1989-1994: LGTM!docs/notebooks/2_Deep_Researcher_Customization.ipynb (2)
272-273: Already addressed per past review (plan → workflow wording fixed).
9-16: LGTM!Also applies to: 27-27, 184-184, 238-241, 275-329, 339-339, 354-355, 387-387, 398-398, 531-534, 552-552
.agents/skills/aiq-customize-prompts-models/SKILL.md (1)
3-3: LGTM!Also applies to: 52-52, 71-73
.agents/skills/aiq-customize-prompts-models/references/prompt-templates.md (1)
18-20: LGTM!docs/notebooks/1_Deep_Researcher_Web_Search.ipynb (1)
12-12: LGTM!Also applies to: 238-238, 248-248, 268-288, 298-298, 342-354, 465-465, 634-634, 792-793
docs/source/resources/faq.md (1)
29-35: LGTM!docs/source/resources/troubleshooting.md (1)
37-37: LGTM!docs/source/architecture/agents/clarifier.md (1)
72-74: 📐 Maintainability & Code QualityVerify the
remaining_questionsrow before documenting it.The supplied
ClarifierAgentStatedefinition only showsmax_turns,clarifier_log, anditeration. Ifremaining_questionsis not implemented elsewhere, this row should be removed or added to the model so the docs stay in sync.src/aiq_agent/agents/clarifier/models/state.py (1)
28-35: LGTM!Also applies to: 38-66
src/aiq_agent/agents/clarifier/agent.py (1)
109-112: LGTM!Also applies to: 137-193, 404-406, 497-536
src/aiq_agent/agents/clarifier/register.py (1)
62-94: LGTM!Also applies to: 121-215
src/aiq_agent/agents/clarifier/prompts/research_clarification.j2 (1)
81-81: LGTM!Also applies to: 115-120
src/aiq_agent/agents/chat_researcher/agent.py (1)
184-191: LGTM!tests/aiq_agent/agents/clarifier/models/test_state.py (1)
122-133: LGTM!.agents/skills/aiq-customize-prompts-models/references/model-selection.md (1)
31-60: LGTM!src/aiq_agent/agents/deep_researcher/models/subagent_contracts.py (1)
77-83: LGTM!Also applies to: 134-137
src/aiq_agent/agents/deep_researcher/factory.py (1)
105-107: LGTM!Also applies to: 272-275, 420-428
src/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2 (1)
1-11: LGTM!Also applies to: 38-61, 76-87, 123-136
src/aiq_agent/agents/deep_researcher/README.md (1)
24-32: LGTM!Also applies to: 62-62, 75-89, 103-103, 123-126, 140-141, 167-169, 229-239
docs/source/architecture/agents/deep-researcher.md (1)
30-84: LGTM!Also applies to: 117-122, 124-151
docs/source/architecture/overview.md (1)
30-32: LGTM!Also applies to: 101-103
src/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.py (1)
80-80: LGTM!docs/source/examples/skills-sandbox/index.md (1)
28-28: LGTM!Also applies to: 132-134
src/aiq_agent/agents/deep_researcher/register.py (1)
60-65: LGTM!Also applies to: 78-81, 198-213
src/aiq_agent/agents/deep_researcher/custom_middleware.py (1)
18-18: LGTM!Also applies to: 244-245
src/aiq_agent/agents/deep_researcher/agent.py (1)
156-164: LGTM!src/aiq_agent/agents/deep_researcher/prompts/researcher.j2 (1)
7-11: LGTM!Also applies to: 46-46
src/aiq_agent/agents/deep_researcher/prompts/source_router.j2 (1)
1-1: LGTM!Also applies to: 26-30, 39-39
src/aiq_agent/agents/deep_researcher/prompts/writer.j2 (1)
1-9: LGTM!Also applies to: 30-30, 48-57, 79-79
src/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.md (1)
4-33: LGTM!Also applies to: 98-98
src/aiq_agent/agents/deep_researcher/skills/synthesis/prediction-report-writer/SKILL.md (1)
4-14: LGTM!Also applies to: 15-19
9716f96 to
d4364a0
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (5)
src/aiq_agent/agents/deep_researcher/models/subagent_contracts.py (1)
32-38: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick winStale "planner" reference in docstring.
SourceRecommendation.__doc__still says "A source-router recommendation for the planner." but the planner role is removed in this PR (routing_guidance's description was correctly updated to say "orchestrator"). Update the docstring to match the new contract owner.📝 Proposed fix
class SourceRecommendation(_StrictContract): - """A source-router recommendation for the planner.""" + """A source-router recommendation for the orchestrator."""🤖 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 `@src/aiq_agent/agents/deep_researcher/models/subagent_contracts.py` around lines 32 - 38, Update the SourceRecommendation docstring to remove the stale planner reference and align it with the new owner terminology used elsewhere in the contract. Keep the class name SourceRecommendation and its field definitions unchanged, but revise the one-line description so it refers to the orchestrator instead of the planner.Source: Path instructions
docs/notebooks/1_Deep_Researcher_Web_Search.ipynb (1)
51-54: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winAdjacent "Phases: (1) planning" list is now stale.
Right below the freshly-updated role list (which removes the planner entirely), this unchanged list still cites "(1) planning" as a workflow phase. Since it sits directly beside content edited for this PR, it should be updated in the same pass to avoid contradicting the new architecture.
As per path instructions, review documentation for stale examples that no longer match the repository layout.
🤖 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/notebooks/1_Deep_Researcher_Web_Search.ipynb` around lines 51 - 54, The notebook’s “Phases” list is stale and still mentions planning even though the updated role list in 1_Deep_Researcher_Web_Search references only the current workflow. Update the phase text in this notebook cell to match the new architecture by removing the outdated planning reference and keeping the phase list aligned with the active roles and sequence used elsewhere in the notebook.Source: Path instructions
docs/source/architecture/overview.md (1)
64-71: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick winStale "plan approval" references left over from removed clarifier flow.
Line 69-70 still says the clarifier routes let "the user can review and approve a plan before deep research begins," and line 86 still describes
clarifier_resultas "Clarification log and approved plan context." Per the PR objective, the plan preview/approval step was removed — clarifier now only gathers context and optionally clarifies output type. These unchanged passages misrepresent current behavior.📝 Proposed fix
- 800 characters of the AI response. When escalation triggers, the graph - routes to the `clarifier` node (not directly to `deep_research`), so the - user can review and approve a plan before deep research begins. - Escalation is gated by the `enable_escalation` config flag. + 800 characters of the AI response. When escalation triggers, the graph + routes to the `clarifier` node (not directly to `deep_research`) so the + user can provide additional context before deep research begins. + Escalation is gated by the `enable_escalation` config flag.-| `clarifier_result` | `str` or `None` | Clarification log and approved plan context | +| `clarifier_result` | `str` or `None` | Clarification log and gathered context |As per path instructions, "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."
Also applies to: 86-86
🤖 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/architecture/overview.md` around lines 64 - 71, The architecture overview still describes the removed plan approval flow in the `should_escalate` section and the `clarifier_result` description. Update the prose in `should_escalate` and any related clarifier documentation to reflect the current `clarifier` behavior only gathers context and may clarify output type, without mentioning user plan review or approval before `deep_research`. Remove or rewrite the stale `clarifier_result` wording so it matches the current implementation and terminology.Source: Path instructions
docs/source/customization/configuration-reference.md (1)
340-362: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winDocument
enable_source_routerin thedeep_research_agentreference.README.md documents
enable_source_router(bool, defaulttrue) as a parameter that toggles the new source-router stage, but this reference's YAML example and parameter table omit it entirely. Since source routing is a headline feature of this refactor, users following this doc alone won't know how to disable it.📝 Proposed fix
| `writer_llm` | `str` | `None` | LLM for the final writer/synthesis sub-agent. Falls back to `orchestrator_llm` if not specified. | +| `enable_source_router` | `bool` | `true` | Enable advisory source routing before research. | | `tools` | `list[str]` | `[]` | Search tools available to the researcher sub-agent. |🤖 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/customization/configuration-reference.md` around lines 340 - 362, The deep_research_agent reference is missing the new enable_source_router option, so update the YAML example and parameter table in configuration-reference.md to include it alongside orchestrator_llm and source_router_llm. Document enable_source_router in the deep_research_agent section as a bool with default true, and note that it toggles the source-router stage so users can disable it from this doc alone.src/aiq_agent/agents/clarifier/register.py (1)
171-179: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueConsider deduplicating the two
ClarifierAgentconstruction call sites.Both blocks build with an identical argument set except
tools. A shared kwargs dict would reduce the risk of the two call sites drifting apart on future parameter changes.♻️ Proposed refactor
+ base_kwargs = dict( + llm_provider=provider, + user_prompt_callback=user_prompt_callback, + max_turns=config.max_turns, + log_response_max_chars=config.log_response_max_chars, + verbose=verbose, + callbacks=callbacks, + ) - agent = ClarifierAgent( - llm_provider=provider, - tools=tools, - user_prompt_callback=user_prompt_callback, - max_turns=config.max_turns, - log_response_max_chars=config.log_response_max_chars, - verbose=verbose, - callbacks=callbacks, - ) + agent = ClarifierAgent(tools=tools, **base_kwargs) ... - active_agent = ClarifierAgent( - llm_provider=provider, - tools=selected_tools, - user_prompt_callback=user_prompt_callback, - max_turns=config.max_turns, - log_response_max_chars=config.log_response_max_chars, - verbose=verbose, - callbacks=callbacks, - ) + active_agent = ClarifierAgent(tools=selected_tools, **base_kwargs)Also applies to: 191-203
🤖 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 `@src/aiq_agent/agents/clarifier/register.py` around lines 171 - 179, The two ClarifierAgent construction paths are duplicated and can drift over time; refactor the shared arguments into a common kwargs dict or helper used by the ClarifierAgent call sites in register.py. Keep the varying tools argument separate, but centralize the repeated llm_provider, user_prompt_callback, max_turns, log_response_max_chars, verbose, and callbacks setup so both branches stay consistent.
🤖 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/notebooks/1_Deep_Researcher_Web_Search.ipynb`:
- Line 248: Update the notebook text describing `agent.ainvoke` so it no longer
mentions a removed planning phase or says the orchestrator produces the final
report; instead, describe the orchestrator as dispatching research and tool
calls, and the `writer` subagent as the component that synthesizes the final
report. Use the surrounding workflow description in this notebook and the role
list near the top to keep the `orchestrator`, `researcher-agent`, and `writer`
references aligned with the current architecture.
In `@docs/notebooks/2_Deep_Researcher_Customization.ipynb`:
- Around line 280-290: The roles table in the notebook has a stale Orchestrator
description that conflicts with the Writer role and the current
orchestrator/writer split. Update the `orchestrator_llm` row in the roles table
so `orchestrator_llm` is described as coordinating the workflow and not writing
the final report, and keep `writer_llm` as the role that synthesizes the final
cited report. Make the wording consistent with the notebook’s
`writer_llm`/`researcher_llm` model split and the `orchestrator` delegation
pattern used elsewhere in the docs.
---
Outside diff comments:
In `@docs/notebooks/1_Deep_Researcher_Web_Search.ipynb`:
- Around line 51-54: The notebook’s “Phases” list is stale and still mentions
planning even though the updated role list in 1_Deep_Researcher_Web_Search
references only the current workflow. Update the phase text in this notebook
cell to match the new architecture by removing the outdated planning reference
and keeping the phase list aligned with the active roles and sequence used
elsewhere in the notebook.
In `@docs/source/architecture/overview.md`:
- Around line 64-71: The architecture overview still describes the removed plan
approval flow in the `should_escalate` section and the `clarifier_result`
description. Update the prose in `should_escalate` and any related clarifier
documentation to reflect the current `clarifier` behavior only gathers context
and may clarify output type, without mentioning user plan review or approval
before `deep_research`. Remove or rewrite the stale `clarifier_result` wording
so it matches the current implementation and terminology.
In `@docs/source/customization/configuration-reference.md`:
- Around line 340-362: The deep_research_agent reference is missing the new
enable_source_router option, so update the YAML example and parameter table in
configuration-reference.md to include it alongside orchestrator_llm and
source_router_llm. Document enable_source_router in the deep_research_agent
section as a bool with default true, and note that it toggles the source-router
stage so users can disable it from this doc alone.
In `@src/aiq_agent/agents/clarifier/register.py`:
- Around line 171-179: The two ClarifierAgent construction paths are duplicated
and can drift over time; refactor the shared arguments into a common kwargs dict
or helper used by the ClarifierAgent call sites in register.py. Keep the varying
tools argument separate, but centralize the repeated llm_provider,
user_prompt_callback, max_turns, log_response_max_chars, verbose, and callbacks
setup so both branches stay consistent.
In `@src/aiq_agent/agents/deep_researcher/models/subagent_contracts.py`:
- Around line 32-38: Update the SourceRecommendation docstring to remove the
stale planner reference and align it with the new owner terminology used
elsewhere in the contract. Keep the class name SourceRecommendation and its
field definitions unchanged, but revise the one-line description so it refers to
the orchestrator instead of the planner.
🪄 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: aa3ec7ba-e4f0-45ce-b553-45a8e86adfb0
📒 Files selected for processing (63)
.agents/skills/aiq-customize-prompts-models/SKILL.md.agents/skills/aiq-customize-prompts-models/references/model-selection.md.agents/skills/aiq-customize-prompts-models/references/prompt-templates.mdconfigs/config_cli_default.ymlconfigs/config_domain_routing_and_skills.ymlconfigs/config_frontier_models.ymlconfigs/config_openshell.ymlconfigs/config_web_default_guardrails.ymlconfigs/config_web_default_llamaindex.ymlconfigs/config_web_frag.ymlconfigs/config_web_frag_mcp_auth.ymldocs/notebooks/0_Getting_Started_with_AIQ.ipynbdocs/notebooks/1_Deep_Researcher_Web_Search.ipynbdocs/notebooks/2_Deep_Researcher_Customization.ipynbdocs/source/architecture/agents/clarifier.mddocs/source/architecture/agents/deep-researcher.mddocs/source/architecture/overview.mddocs/source/customization/configuration-reference.mddocs/source/customization/hitl.mddocs/source/customization/index.mddocs/source/customization/prompts.mddocs/source/customization/swapping-models.mddocs/source/examples/cli-with-local-nims.mddocs/source/examples/full-pipeline-llamaindex.mddocs/source/examples/full-pipeline-web.mddocs/source/examples/hybrid-frontier-model.mddocs/source/examples/skills-sandbox/index.mddocs/source/get-started/installation.mddocs/source/profiling/index.mddocs/source/resources/faq.mddocs/source/resources/troubleshooting.mdfrontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench.ymlfrontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench_profiling.ymlfrontends/benchmarks/deepsearch_qa/configs/config_deepsearch_qa.ymlfrontends/benchmarks/freshqa/configs/config_full_workflow.ymlsrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/clarifier/agent.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/clarifier/prompts/plan_generation.j2src/aiq_agent/agents/clarifier/prompts/research_clarification.j2src/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/deep_researcher/README.mdsrc/aiq_agent/agents/deep_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pysrc/aiq_agent/agents/deep_researcher/factory.pysrc/aiq_agent/agents/deep_researcher/models/__init__.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2src/aiq_agent/agents/deep_researcher/prompts/planner.j2src/aiq_agent/agents/deep_researcher/prompts/researcher.j2src/aiq_agent/agents/deep_researcher/prompts/source_router.j2src/aiq_agent/agents/deep_researcher/prompts/writer.j2src/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pysrc/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.mdsrc/aiq_agent/agents/deep_researcher/skills/synthesis/prediction-report-writer/SKILL.mdtests/aiq_agent/agents/clarifier/models/test_state.pytests/aiq_agent/agents/clarifier/test_agent.pytests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pytests/aiq_agent/agents/deep_researcher/test_agent.pytests/aiq_agent/agents/deep_researcher/test_custom_middleware.pytests/aiq_agent/agents/deep_researcher/test_factory.pytests/aiq_agent/jobs/test_runner.py
💤 Files with no reviewable changes (20)
- docs/source/examples/hybrid-frontier-model.md
- docs/source/examples/cli-with-local-nims.md
- frontends/benchmarks/deepsearch_qa/configs/config_deepsearch_qa.yml
- docs/source/examples/full-pipeline-llamaindex.md
- src/aiq_agent/agents/clarifier/prompts/plan_generation.j2
- frontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench.yml
- configs/config_openshell.yml
- configs/config_web_frag.yml
- configs/config_web_default_llamaindex.yml
- tests/aiq_agent/agents/clarifier/test_agent.py
- configs/config_cli_default.yml
- configs/config_domain_routing_and_skills.yml
- src/aiq_agent/agents/deep_researcher/prompts/planner.j2
- src/aiq_agent/agents/deep_researcher/models/init.py
- frontends/benchmarks/freshqa/configs/config_full_workflow.yml
- configs/config_web_frag_mcp_auth.yml
- frontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench_profiling.yml
- configs/config_frontier_models.yml
- configs/config_web_default_guardrails.yml
- tests/aiq_agent/agents/deep_researcher/test_custom_middleware.py
📜 Review details
⚠️ CI failures not shown inline (2)
GitHub Actions: AIQ CI / Script Validation: refactor(deep-research): remove planner agent and clarifier plan appr…
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 / 0_Script Validation.txt: refactor(deep-research): remove planner agent and clarifier plan appr…
Conclusion: failure
Current runner version: '2.335.1'
##[group]Runner Image Provisioner
Hosted Compute Agent
Version: 20260624.560
Commit: 925d229a51159bc391ae97e54a2dd1fe20af789d
Build Date:
Worker ID: {b5682ed2-de6d-4d0c-8668-20375efb103a}
Azure Region: northcentralus
##[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 versio...
🧰 Additional context used
📓 Path-based instructions (8)
**/*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run ruff check and ruff format validation for Python code changes
**/*.py: Python code must be linted and formatted with Ruff using line length 120, target Python 3.11, rule sets E,F,W,I,PL,UP, and isort force-single-line configuration
Never commit secrets, tokens, or environment-specific hostnames; use environment variables and SecretStr instead, resolving API keys at runtime
Never print or log secret values, including in tool output or error messages
Missing-secret paths must degrade gracefully (stub/skip), not crash or leak
Do not hand-reformat unrelated code when making changes; match the existing import and formatting style
Files:
src/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pytests/aiq_agent/agents/clarifier/models/test_state.pysrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/factory.pytests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pytests/aiq_agent/agents/deep_researcher/test_factory.pysrc/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pytests/aiq_agent/jobs/test_runner.pysrc/aiq_agent/agents/clarifier/agent.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/clarifier/register.pytests/aiq_agent/agents/deep_researcher/test_agent.py
src/aiq_agent/**/*.py
📄 CodeRabbit inference engine (AGENTS.md)
src/aiq_agent/**/*.py: Respect authenticated data sources by honoring requires_auth, per-user token pass-through, and backend token validators; apply owner guardrails before loading protected report or artifact context into an agent
Do not weaken or bypass AuthMiddleware, validators, or auth gating without a prior design discussion
Files:
src/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pysrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/factory.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pysrc/aiq_agent/agents/clarifier/agent.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/clarifier/register.py
**
⚙️ 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:
src/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pydocs/source/customization/index.mddocs/source/get-started/installation.mddocs/source/customization/swapping-models.mdtests/aiq_agent/agents/clarifier/models/test_state.pydocs/source/customization/hitl.mddocs/source/resources/faq.mdsrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/clarifier/prompts/research_clarification.j2docs/source/resources/troubleshooting.mdsrc/aiq_agent/agents/deep_researcher/prompts/researcher.j2src/aiq_agent/agents/deep_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/skills/synthesis/prediction-report-writer/SKILL.mddocs/source/architecture/overview.mdsrc/aiq_agent/agents/deep_researcher/prompts/source_router.j2src/aiq_agent/agents/deep_researcher/prompts/writer.j2src/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.mdsrc/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2docs/source/examples/full-pipeline-web.mddocs/source/examples/skills-sandbox/index.mddocs/source/architecture/agents/deep-researcher.mdsrc/aiq_agent/agents/deep_researcher/factory.pytests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pytests/aiq_agent/agents/deep_researcher/test_factory.pysrc/aiq_agent/agents/deep_researcher/register.pydocs/notebooks/0_Getting_Started_with_AIQ.ipynbdocs/source/architecture/agents/clarifier.mdsrc/aiq_agent/agents/deep_researcher/custom_middleware.pydocs/source/customization/prompts.mdtests/aiq_agent/jobs/test_runner.pydocs/source/customization/configuration-reference.mdsrc/aiq_agent/agents/clarifier/agent.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/deep_researcher/README.mdsrc/aiq_agent/agents/clarifier/register.pytests/aiq_agent/agents/deep_researcher/test_agent.pydocs/source/profiling/index.mddocs/notebooks/2_Deep_Researcher_Customization.ipynbdocs/notebooks/1_Deep_Researcher_Web_Search.ipynb
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/sandbox/artifacts/models.pysrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/clarifier/prompts/research_clarification.j2src/aiq_agent/agents/deep_researcher/prompts/researcher.j2src/aiq_agent/agents/deep_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/skills/synthesis/prediction-report-writer/SKILL.mdsrc/aiq_agent/agents/deep_researcher/prompts/source_router.j2src/aiq_agent/agents/deep_researcher/prompts/writer.j2src/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.mdsrc/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2src/aiq_agent/agents/deep_researcher/factory.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pysrc/aiq_agent/agents/clarifier/agent.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/deep_researcher/README.mdsrc/aiq_agent/agents/clarifier/register.py
docs/source/**/*
📄 CodeRabbit inference engine (AGENTS.md)
Update the docs under docs/source/ when behavior, configuration, or workflows change
Files:
docs/source/customization/index.mddocs/source/get-started/installation.mddocs/source/customization/swapping-models.mddocs/source/customization/hitl.mddocs/source/resources/faq.mddocs/source/resources/troubleshooting.mddocs/source/architecture/overview.mddocs/source/examples/full-pipeline-web.mddocs/source/examples/skills-sandbox/index.mddocs/source/architecture/agents/deep-researcher.mddocs/source/architecture/agents/clarifier.mddocs/source/customization/prompts.mddocs/source/customization/configuration-reference.mddocs/source/profiling/index.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/index.mddocs/source/get-started/installation.mddocs/source/customization/swapping-models.mddocs/source/customization/hitl.mddocs/source/resources/faq.mddocs/source/resources/troubleshooting.mddocs/source/architecture/overview.mddocs/source/examples/full-pipeline-web.mddocs/source/examples/skills-sandbox/index.mddocs/source/architecture/agents/deep-researcher.mddocs/notebooks/0_Getting_Started_with_AIQ.ipynbdocs/source/architecture/agents/clarifier.mddocs/source/customization/prompts.mddocs/source/customization/configuration-reference.mddocs/source/profiling/index.mddocs/notebooks/2_Deep_Researcher_Customization.ipynbdocs/notebooks/1_Deep_Researcher_Web_Search.ipynb
{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:
.agents/skills/aiq-customize-prompts-models/SKILL.md.agents/skills/aiq-customize-prompts-models/references/prompt-templates.md.agents/skills/aiq-customize-prompts-models/references/model-selection.md
**/*test*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run pytest for all behavior changes in Python code
Files:
tests/aiq_agent/agents/clarifier/models/test_state.pytests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pytests/aiq_agent/agents/deep_researcher/test_factory.pytests/aiq_agent/jobs/test_runner.pytests/aiq_agent/agents/deep_researcher/test_agent.py
🪛 LanguageTool
docs/source/customization/hitl.md
[style] ~7-~7: Consider a different adjective to strengthen your wording.
Context: ...in-the-loop (the clarifier) runs before deep research. The clarifier gathers context...
(DEEP_PROFOUND)
[style] ~13-~13: Consider a different adjective to strengthen your wording.
Context: ...rely No clarification step runs before deep research: ```yaml workflow: _type: c...
(DEEP_PROFOUND)
docs/source/resources/faq.md
[grammar] ~29-~29: Ensure spelling is correct
Context: ...ies. - Deep research is thorough (2-10min), uses a multi-agent pipeline (orchestr...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/source/architecture/overview.md
[style] ~101-~101: Consider a different adjective to strengthen your wording.
Context: ...tgreSQL). - Subagent architecture: Deep research uses specialized subagents (...
(DEEP_PROFOUND)
src/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.md
[style] ~13-~13: Consider a different adjective to strengthen your wording.
Context: ...learly asks for a comprehensive report, deep analysis, publication-ready writeup, or...
(DEEP_PROFOUND)
[grammar] ~13-~13: Ensure spelling is correct
Context: ...eport, deep analysis, publication-ready writeup, or whitepaper-style answer. Do not us...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
src/aiq_agent/agents/deep_researcher/README.md
[style] ~239-~239: Consider a different adjective to strengthen your wording.
Context: ... user goes through the clarifier before deep research, the clarification log is pass...
(DEEP_PROFOUND)
🔇 Additional comments (48)
src/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.py (1)
80-80: LGTM!docs/source/customization/index.md (1)
21-21: LGTM!docs/source/get-started/installation.md (1)
28-30: LGTM!.agents/skills/aiq-customize-prompts-models/SKILL.md (1)
3-3: LGTM!Also applies to: 52-52, 71-73
docs/source/customization/swapping-models.md (1)
38-38: LGTM!tests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.py (1)
21-64: LGTM!Also applies to: 111-126, 184-203
src/aiq_agent/agents/deep_researcher/models/subagent_contracts.py (1)
49-51: LGTM!Also applies to: 77-83, 134-137
docs/notebooks/0_Getting_Started_with_AIQ.ipynb (1)
384-384: 📐 Maintainability & Code QualityClarifier prose still doesn't match this notebook's config.
Text still describes clarifier wiring/behavior ("the clarifier and deep-research orchestrator",
enable_clarifier: true, "Main agents: ... clarifier", "clarification steps" in the UI), but theconfig_simple_researcher.ymlcell (lines 335-368) registers noclarifier_agentfunction and theworkflowblock never setsenable_clarifier. This mismatch was already flagged in a prior review round and remains unresolved.Also applies to: 393-400, 624-624
tests/aiq_agent/agents/clarifier/models/test_state.py (1)
129-133: LGTM!.agents/skills/aiq-customize-prompts-models/references/prompt-templates.md (1)
18-20: LGTM!docs/source/customization/hitl.md (1)
7-30: LGTM!docs/source/resources/faq.md (1)
29-35: LGTM!tests/aiq_agent/agents/deep_researcher/test_factory.py (1)
52-68: LGTM!Also applies to: 163-274
src/aiq_agent/agents/deep_researcher/register.py (1)
60-65: LGTM!Also applies to: 78-81, 198-213
docs/source/architecture/agents/deep-researcher.md (2)
165-199: Stale cross-doc anchor likely persists.Heading is still "Phase 4: Citation Verification (Post-Processing)" here; if
docs/source/architecture/overview.mdstill links toagents/deep-researcher.md#phase-5-citation-verification-post-processing, that anchor is broken since the actual anchor is#phase-4-citation-verification-post-processing. This was flagged in a prior review on this same line range and appears unresolved.
30-84: LGTM!Also applies to: 117-122, 132-133, 146-151
src/aiq_agent/agents/chat_researcher/agent.py (1)
184-191: LGTM!src/aiq_agent/agents/clarifier/prompts/research_clarification.j2 (1)
81-81: LGTM!Also applies to: 115-120
docs/source/resources/troubleshooting.md (1)
37-37: LGTM!docs/source/examples/skills-sandbox/index.md (1)
28-28: LGTM!Also applies to: 132-134
.agents/skills/aiq-customize-prompts-models/references/model-selection.md (1)
33-33: LGTM!Also applies to: 43-50, 59-60
src/aiq_agent/agents/deep_researcher/factory.py (1)
105-107: LGTM!Also applies to: 271-279, 420-435
src/aiq_agent/agents/deep_researcher/prompts/researcher.j2 (1)
7-11: LGTM!Also applies to: 46-46
docs/source/architecture/agents/clarifier.md (1)
9-11: LGTM!Also applies to: 21-24, 52-56, 70-71, 82-84, 102-103, 114-116, 126-127, 140-144
src/aiq_agent/agents/deep_researcher/custom_middleware.py (2)
244-249: LGTM!
18-18: 🗄️ Data Integrity & IntegrationNo plan persistence remains here.
SourceRegistryMiddleware.aafter_agent()is the only async hook in this file, andDeepResearchAgentStateno longer hasResearchPlan/answer_strategyfields, so this does not write/shared/plan.json.> Likely an incorrect or invalid review comment.docs/source/customization/prompts.md (1)
16-20: LGTM!Also applies to: 34-45, 121-125, 144-145, 169-172, 233-239, 288-288
docs/notebooks/1_Deep_Researcher_Web_Search.ipynb (1)
9-15: LGTM!Also applies to: 238-238, 268-273, 288-288, 298-298, 342-354, 462-467, 631-636, 792-793
tests/aiq_agent/jobs/test_runner.py (1)
1551-1577: 🎯 Functional CorrectnessNo issue with the
LLMRole.PLANNERcoverage here. The sibling test still exercises the shared-role fallback path, so the planner assertions are intentional and shouldn’t be removed.> Likely an incorrect or invalid review comment.src/aiq_agent/agents/deep_researcher/agent.py (1)
159-159: LGTM!src/aiq_agent/agents/deep_researcher/skills/synthesis/prediction-report-writer/SKILL.md (1)
4-19: LGTM!docs/source/architecture/overview.md (3)
30-32: LGTM!
101-103: LGTM!
122-122: 📐 Maintainability & Code QualityNo issue — the target heading exists.
> Likely an incorrect or invalid review comment.docs/source/profiling/index.md (1)
118-125: Writer phase still not reconciled with Cost-by-Phase bucket labels.Line 237 now calls out the Writer as a distinct subagent, but the intro (118) and "Cost by Phase" chart description (199) still only enumerate Orchestrator/Researcher, and line 239 only defines
researcher-phase— leaving readers unsure where Writer-attributed LLM calls land in the breakdown.Also applies to: 199-199, 235-241
docs/source/customization/configuration-reference.md (1)
287-310: LGTM!Also applies to: 338-338, 470-472, 507-507
src/aiq_agent/agents/clarifier/agent.py (1)
109-112: LGTM!Also applies to: 137-176, 386-519, 521-537
src/aiq_agent/agents/clarifier/models/state.py (1)
28-35: LGTM!Also applies to: 38-66
src/aiq_agent/agents/deep_researcher/README.md (1)
9-104: LGTM!Also applies to: 224-241
src/aiq_agent/agents/clarifier/register.py (1)
62-94: LGTM!Also applies to: 98-125, 181-190, 208-215
tests/aiq_agent/agents/deep_researcher/test_agent.py (1)
33-34: LGTM!Also applies to: 326-327, 383-387, 414-417, 435-441, 452-453, 477-485, 535-537, 601-601, 628-635, 1040-1040, 1052-1058
src/aiq_agent/agents/deep_researcher/prompts/source_router.j2 (2)
1-25: LGTM!Also applies to: 40-72
26-39: 🗄️ Data Integrity & IntegrationNo schema mismatch
SourceRoutingPlanalready definesrouting_guidance, so the router output field matches the parser schema.src/aiq_agent/agents/deep_researcher/prompts/writer.j2 (2)
1-9: LGTM!Also applies to: 19-46, 77-79
48-50: 🗄️ Data Integrity & IntegrationNo change needed:
ResearchNotesalready exposestarget_components,summary, andevidence_judgment.> Likely an incorrect or invalid review comment.src/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.md (1)
4-33: LGTM! Content aligns with writer.j2's new output-shape/ResearchNotes-driven contract (see verification note on writer.j2 regardingtarget_components/summary).Also applies to: 98-98
src/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2 (1)
1-181: LGTM! Removal of the planner role and the source-routing serialization guard (Lines 38-41) are consistent with the new direct-query architecture, and thetool_nameshandoff (Line 86) matches thesource_router.j2recommendation schema.docs/source/examples/full-pipeline-web.md (1)
8-8: LGTM! Consistent with removal of the planner/plan-approval flow described in the PR objectives.Also applies to: 142-152, 186-186
d4364a0 to
2521272
Compare
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
src/aiq_agent/agents/deep_researcher/prompts/writer.j2 (1)
15-17: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winKeep the no-skill fallback internal.
This paragraph can leak routing internals into the final answer if the fallback path is hit. Make the fallback silent, or explicitly constrain the note to
think/internal reasoning, so/shared/output.mdstays user-facing. As per path instructions, skill files should keep generated-output boundaries clear.🤖 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 `@src/aiq_agent/agents/deep_researcher/prompts/writer.j2` around lines 15 - 17, The fallback wording in the writer prompt leaks internal routing details into the user-facing output. Update the instructions in writer.j2 so the no-skill fallback is handled only in think/internal reasoning and does not instruct the model to state that no writer skill applies in /shared/output.md. Keep the boundary clear by making the fallback silent while still requiring the base writer prompt behavior when no applicable skill exists.Source: Path instructions
docs/source/architecture/agents/clarifier.md (1)
42-56: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winDuplicate Mermaid node ID renders wrong label on the new termination path.
Node
Lis defined twice with different labels:L[Auto-complete clarification](line 49) andL[Clarification complete](line 51), both feeding into the newL --> Nedge (line 52). Mermaid uses a single label per node ID, so the diagram will show only one of these texts for both the "no" and "max turns exceeded" paths, obscuring the distinction the change was meant to convey.As per path instructions, "Review documentation for... stale examples" for files matching
{docs/**,...}.📝 Proposed fix using a distinct node ID
H -->|no| L[Clarification complete] - L --> N[Return ClarifierResult<br/>with clarifier_log] + H -->|no| M[Clarification complete] + M --> N[Return ClarifierResult<br/>with clarifier_log]🤖 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/architecture/agents/clarifier.md` around lines 42 - 56, The Mermaid flow in clarifier.md reuses node ID L for two different termination states, so the labels collide and one path is rendered incorrectly. Update the diagram in the clarification flow to use distinct node IDs for “Auto-complete clarification” and “Clarification complete,” and keep both of them pointing to the return node N so the no-branch and max-turns branch remain visually distinct.Source: Path instructions
src/aiq_agent/agents/chat_researcher/agent.py (1)
322-324: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winStale comment references removed "approved plan" concept.
This comment still mentions feeding "the approved plan" to the deep researcher, but plan/plan-approval was removed by this PR — only the query and seeded parent-report files remain.
📝 Proposed fix
- # Mirror the async job: feed the deep researcher a clean query (plus the approved plan and any - # seeded parent-report files), NOT the prior chat history. Forwarding accumulated report + # Mirror the async job: feed the deep researcher a clean query (plus any seeded + # parent-report files), NOT the prior chat history. Forwarding accumulated report # messages bloats the writer's context and can make it fail to emit a final report.🤖 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 `@src/aiq_agent/agents/chat_researcher/agent.py` around lines 322 - 324, The inline comment in chat_researcher/agent.py is now stale because it still refers to an “approved plan” that no longer exists. Update the comment near the deep researcher handoff logic to describe only the current behavior: passing the clean query and any seeded parent-report files, not the prior chat history or any plan-related input. Keep the wording aligned with the surrounding async job flow and the relevant handoff code in the researcher path.
🤖 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/notebooks/1_Deep_Researcher_Web_Search.ipynb`:
- Around line 296-298: The notebook’s middleware description is inaccurate
because `agent.py` does not use one shared middleware list for all roles. Update
the text near the “Middleware” section to reflect that the researcher and writer
use the common middleware stack, while the orchestrator uses a separate stack,
and make sure any snippet or wording in that section matches the actual
`agent.py` role-specific middleware setup.
In `@docs/source/customization/prompts.md`:
- Around line 169-172: The “Key Sections to Customize” list is missing Source
Router even though `source_router.j2` is shown elsewhere as customizable. Update
the section that lists the Deep Research templates to include “Source Router”
with the `source_router.j2` identifier, alongside the existing
`orchestrator.j2`, `researcher.j2`, `writer.j2`, and `research_clarification.j2`
entries so the documentation stays consistent.
In `@docs/source/resources/faq.md`:
- Around line 29-35: The deep research FAQ entry is missing the default
source-routing component, so update the wording in the FAQ section to reflect
the full pipeline. In the Deep research description, reference the existing
intent-routing flow and make sure the pipeline is described as including
source-router-agent along with orchestrator, researcher, and writer so the
documentation stays accurate.
---
Outside diff comments:
In `@docs/source/architecture/agents/clarifier.md`:
- Around line 42-56: The Mermaid flow in clarifier.md reuses node ID L for two
different termination states, so the labels collide and one path is rendered
incorrectly. Update the diagram in the clarification flow to use distinct node
IDs for “Auto-complete clarification” and “Clarification complete,” and keep
both of them pointing to the return node N so the no-branch and max-turns branch
remain visually distinct.
In `@src/aiq_agent/agents/chat_researcher/agent.py`:
- Around line 322-324: The inline comment in chat_researcher/agent.py is now
stale because it still refers to an “approved plan” that no longer exists.
Update the comment near the deep researcher handoff logic to describe only the
current behavior: passing the clean query and any seeded parent-report files,
not the prior chat history or any plan-related input. Keep the wording aligned
with the surrounding async job flow and the relevant handoff code in the
researcher path.
In `@src/aiq_agent/agents/deep_researcher/prompts/writer.j2`:
- Around line 15-17: The fallback wording in the writer prompt leaks internal
routing details into the user-facing output. Update the instructions in
writer.j2 so the no-skill fallback is handled only in think/internal reasoning
and does not instruct the model to state that no writer skill applies in
/shared/output.md. Keep the boundary clear by making the fallback silent while
still requiring the base writer prompt behavior when no applicable skill exists.
🪄 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: e6f19526-24ca-471c-b9c0-49f331768020
📒 Files selected for processing (64)
.agents/skills/aiq-customize-prompts-models/SKILL.md.agents/skills/aiq-customize-prompts-models/references/model-selection.md.agents/skills/aiq-customize-prompts-models/references/prompt-templates.mdconfigs/config_cli_default.ymlconfigs/config_domain_routing_and_skills.ymlconfigs/config_frontier_models.ymlconfigs/config_openshell.ymlconfigs/config_web_default_guardrails.ymlconfigs/config_web_default_llamaindex.ymlconfigs/config_web_frag.ymlconfigs/config_web_frag_mcp_auth.ymldocs/notebooks/0_Getting_Started_with_AIQ.ipynbdocs/notebooks/1_Deep_Researcher_Web_Search.ipynbdocs/notebooks/2_Deep_Researcher_Customization.ipynbdocs/source/architecture/agents/clarifier.mddocs/source/architecture/agents/deep-researcher.mddocs/source/architecture/overview.mddocs/source/customization/configuration-reference.mddocs/source/customization/hitl.mddocs/source/customization/index.mddocs/source/customization/prompts.mddocs/source/customization/swapping-models.mddocs/source/examples/cli-with-local-nims.mddocs/source/examples/full-pipeline-llamaindex.mddocs/source/examples/full-pipeline-web.mddocs/source/examples/hybrid-frontier-model.mddocs/source/examples/skills-sandbox/index.mddocs/source/get-started/installation.mddocs/source/profiling/index.mddocs/source/resources/faq.mddocs/source/resources/troubleshooting.mdfrontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench.ymlfrontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench_profiling.ymlfrontends/benchmarks/deepsearch_qa/configs/config_deepsearch_qa.ymlfrontends/benchmarks/freshqa/configs/config_full_workflow.ymlsrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/clarifier/agent.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/clarifier/prompts/plan_generation.j2src/aiq_agent/agents/clarifier/prompts/research_clarification.j2src/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/deep_researcher/README.mdsrc/aiq_agent/agents/deep_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pysrc/aiq_agent/agents/deep_researcher/factory.pysrc/aiq_agent/agents/deep_researcher/models/__init__.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2src/aiq_agent/agents/deep_researcher/prompts/planner.j2src/aiq_agent/agents/deep_researcher/prompts/researcher.j2src/aiq_agent/agents/deep_researcher/prompts/source_router.j2src/aiq_agent/agents/deep_researcher/prompts/writer.j2src/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pysrc/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.mdsrc/aiq_agent/agents/deep_researcher/skills/synthesis/prediction-report-writer/SKILL.mdsrc/aiq_agent/agents/deep_researcher/tools/source_routing.pytests/aiq_agent/agents/clarifier/models/test_state.pytests/aiq_agent/agents/clarifier/test_agent.pytests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pytests/aiq_agent/agents/deep_researcher/test_agent.pytests/aiq_agent/agents/deep_researcher/test_custom_middleware.pytests/aiq_agent/agents/deep_researcher/test_factory.pytests/aiq_agent/jobs/test_runner.py
💤 Files with no reviewable changes (20)
- src/aiq_agent/agents/deep_researcher/models/init.py
- frontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench.yml
- configs/config_domain_routing_and_skills.yml
- configs/config_web_frag.yml
- src/aiq_agent/agents/deep_researcher/prompts/planner.j2
- configs/config_cli_default.yml
- frontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench_profiling.yml
- docs/source/examples/cli-with-local-nims.md
- src/aiq_agent/agents/clarifier/prompts/plan_generation.j2
- configs/config_frontier_models.yml
- docs/source/examples/full-pipeline-llamaindex.md
- frontends/benchmarks/freshqa/configs/config_full_workflow.yml
- configs/config_web_default_llamaindex.yml
- frontends/benchmarks/deepsearch_qa/configs/config_deepsearch_qa.yml
- docs/source/examples/hybrid-frontier-model.md
- configs/config_web_frag_mcp_auth.yml
- configs/config_openshell.yml
- configs/config_web_default_guardrails.yml
- tests/aiq_agent/agents/clarifier/test_agent.py
- tests/aiq_agent/agents/deep_researcher/test_custom_middleware.py
📜 Review details
⚠️ CI failures not shown inline (2)
GitHub Actions: AIQ CI / 2_Script Validation.txt: refactor(deep-research): remove planner agent and clarifier plan appr…
Conclusion: failure
Current runner version: '2.335.1'
##[group]Runner Image Provisioner
Hosted Compute Agent
Version: 20260624.560
Commit: 925d229a51159bc391ae97e54a2dd1fe20af789d
Build Date:
Worker ID: {8e0bd653-8aff-4c59-b87f-8869c0f84fac}
Azure Region: westcentralus
##[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...
GitHub Actions: AIQ CI / Script Validation: refactor(deep-research): remove planner agent and clarifier plan appr…
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
=====================...
🧰 Additional context used
📓 Path-based instructions (8)
docs/source/**/*
📄 CodeRabbit inference engine (AGENTS.md)
Update the docs under docs/source/ when behavior, configuration, or workflows change
Files:
docs/source/customization/swapping-models.mddocs/source/get-started/installation.mddocs/source/customization/index.mddocs/source/resources/faq.mddocs/source/examples/skills-sandbox/index.mddocs/source/resources/troubleshooting.mddocs/source/customization/hitl.mddocs/source/customization/prompts.mddocs/source/profiling/index.mddocs/source/examples/full-pipeline-web.mddocs/source/architecture/agents/deep-researcher.mddocs/source/customization/configuration-reference.mddocs/source/architecture/overview.mddocs/source/architecture/agents/clarifier.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/customization/swapping-models.mddocs/source/get-started/installation.mdsrc/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pysrc/aiq_agent/agents/deep_researcher/tools/source_routing.pydocs/source/customization/index.mddocs/source/resources/faq.mdsrc/aiq_agent/agents/deep_researcher/agent.pydocs/source/examples/skills-sandbox/index.mdtests/aiq_agent/agents/clarifier/models/test_state.pydocs/source/resources/troubleshooting.mdsrc/aiq_agent/agents/clarifier/prompts/research_clarification.j2src/aiq_agent/agents/deep_researcher/prompts/source_router.j2docs/source/customization/hitl.mdsrc/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.mdsrc/aiq_agent/agents/deep_researcher/prompts/researcher.j2docs/source/customization/prompts.mdsrc/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2src/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/prompts/writer.j2src/aiq_agent/agents/deep_researcher/register.pydocs/source/profiling/index.mdtests/aiq_agent/agents/deep_researcher/test_agent.pydocs/source/examples/full-pipeline-web.mddocs/source/architecture/agents/deep-researcher.mdtests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pydocs/source/customization/configuration-reference.mddocs/source/architecture/overview.mddocs/notebooks/0_Getting_Started_with_AIQ.ipynbsrc/aiq_agent/agents/deep_researcher/factory.pytests/aiq_agent/jobs/test_runner.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pytests/aiq_agent/agents/deep_researcher/test_factory.pysrc/aiq_agent/agents/deep_researcher/skills/synthesis/prediction-report-writer/SKILL.mddocs/source/architecture/agents/clarifier.mddocs/notebooks/2_Deep_Researcher_Customization.ipynbsrc/aiq_agent/agents/clarifier/models/state.pydocs/notebooks/1_Deep_Researcher_Web_Search.ipynbsrc/aiq_agent/agents/deep_researcher/README.mdsrc/aiq_agent/agents/deep_researcher/custom_middleware.pysrc/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/clarifier/agent.py
{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/swapping-models.mddocs/source/get-started/installation.mddocs/source/customization/index.mddocs/source/resources/faq.mddocs/source/examples/skills-sandbox/index.mddocs/source/resources/troubleshooting.mddocs/source/customization/hitl.mddocs/source/customization/prompts.mddocs/source/profiling/index.mddocs/source/examples/full-pipeline-web.mddocs/source/architecture/agents/deep-researcher.mddocs/source/customization/configuration-reference.mddocs/source/architecture/overview.mddocs/notebooks/0_Getting_Started_with_AIQ.ipynbdocs/source/architecture/agents/clarifier.mddocs/notebooks/2_Deep_Researcher_Customization.ipynbdocs/notebooks/1_Deep_Researcher_Web_Search.ipynb
**/*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run ruff check and ruff format validation for Python code changes
**/*.py: Python code must be linted and formatted with Ruff using line length 120, target Python 3.11, rule sets E,F,W,I,PL,UP, and isort force-single-line configuration
Never commit secrets, tokens, or environment-specific hostnames; use environment variables and SecretStr instead, resolving API keys at runtime
Never print or log secret values, including in tool output or error messages
Missing-secret paths must degrade gracefully (stub/skip), not crash or leak
Do not hand-reformat unrelated code when making changes; match the existing import and formatting style
Files:
src/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pysrc/aiq_agent/agents/deep_researcher/tools/source_routing.pysrc/aiq_agent/agents/deep_researcher/agent.pytests/aiq_agent/agents/clarifier/models/test_state.pysrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/register.pytests/aiq_agent/agents/deep_researcher/test_agent.pytests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/factory.pytests/aiq_agent/jobs/test_runner.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pytests/aiq_agent/agents/deep_researcher/test_factory.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pysrc/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/clarifier/agent.py
src/aiq_agent/**/*.py
📄 CodeRabbit inference engine (AGENTS.md)
src/aiq_agent/**/*.py: Respect authenticated data sources by honoring requires_auth, per-user token pass-through, and backend token validators; apply owner guardrails before loading protected report or artifact context into an agent
Do not weaken or bypass AuthMiddleware, validators, or auth gating without a prior design discussion
Files:
src/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pysrc/aiq_agent/agents/deep_researcher/tools/source_routing.pysrc/aiq_agent/agents/deep_researcher/agent.pysrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/deep_researcher/factory.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pysrc/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/clarifier/agent.py
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/sandbox/artifacts/models.pysrc/aiq_agent/agents/deep_researcher/tools/source_routing.pysrc/aiq_agent/agents/deep_researcher/agent.pysrc/aiq_agent/agents/clarifier/prompts/research_clarification.j2src/aiq_agent/agents/deep_researcher/prompts/source_router.j2src/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.mdsrc/aiq_agent/agents/deep_researcher/prompts/researcher.j2src/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2src/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/prompts/writer.j2src/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/deep_researcher/factory.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/skills/synthesis/prediction-report-writer/SKILL.mdsrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/deep_researcher/README.mdsrc/aiq_agent/agents/deep_researcher/custom_middleware.pysrc/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/clarifier/agent.py
**/*test*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run pytest for all behavior changes in Python code
Files:
tests/aiq_agent/agents/clarifier/models/test_state.pytests/aiq_agent/agents/deep_researcher/test_agent.pytests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pytests/aiq_agent/jobs/test_runner.pytests/aiq_agent/agents/deep_researcher/test_factory.py
{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:
.agents/skills/aiq-customize-prompts-models/references/prompt-templates.md.agents/skills/aiq-customize-prompts-models/SKILL.md.agents/skills/aiq-customize-prompts-models/references/model-selection.md
🪛 LanguageTool
docs/source/resources/faq.md
[grammar] ~29-~29: Ensure spelling is correct
Context: ...ies. - Deep research is thorough (2-10min), uses a multi-agent pipeline (orchestr...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/source/customization/hitl.md
[style] ~7-~7: Consider a different adjective to strengthen your wording.
Context: ...in-the-loop (the clarifier) runs before deep research. The clarifier gathers context...
(DEEP_PROFOUND)
[style] ~13-~13: Consider a different adjective to strengthen your wording.
Context: ...rely No clarification step runs before deep research: ```yaml workflow: _type: c...
(DEEP_PROFOUND)
src/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.md
[style] ~13-~13: Consider a different adjective to strengthen your wording.
Context: ...learly asks for a comprehensive report, deep analysis, publication-ready writeup, or...
(DEEP_PROFOUND)
[grammar] ~13-~13: Ensure spelling is correct
Context: ...eport, deep analysis, publication-ready writeup, or whitepaper-style answer. Do not us...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/source/architecture/overview.md
[style] ~101-~101: Consider a different adjective to strengthen your wording.
Context: ...tgreSQL). - Subagent architecture: Deep research uses specialized subagents (...
(DEEP_PROFOUND)
src/aiq_agent/agents/deep_researcher/README.md
[style] ~239-~239: Consider a different adjective to strengthen your wording.
Context: ... user goes through the clarifier before deep research, the clarification log is pass...
(DEEP_PROFOUND)
🔇 Additional comments (49)
docs/source/profiling/index.md (1)
118-125: Writer cost attribution is still ambiguous.The updated wording still leaves writer-attributed LLM calls unassigned: the chart says Orchestrator / Researcher only, while this section now says Writer is part of the flow. Readers still can't reconcile where writer costs land. As per path instructions, review documentation for command accuracy and stale examples matching current config shape.
Also applies to: 199-199, 237-237
Source: Path instructions
docs/source/customization/swapping-models.md (1)
38-38: LGTM!docs/source/get-started/installation.md (1)
28-30: LGTM!docs/source/customization/hitl.md (1)
7-13: LGTM!Also applies to: 22-30
.agents/skills/aiq-customize-prompts-models/SKILL.md (1)
3-3: LGTM!Also applies to: 52-52, 71-71
src/aiq_agent/agents/deep_researcher/register.py (1)
63-64: LGTM!Also applies to: 78-81, 208-213
src/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.py (1)
80-80: LGTM!docs/source/customization/index.md (1)
21-21: LGTM!src/aiq_agent/agents/deep_researcher/agent.py (1)
159-159: LGTM!docs/source/examples/skills-sandbox/index.md (1)
28-28: LGTM!Also applies to: 132-134
.agents/skills/aiq-customize-prompts-models/references/prompt-templates.md (1)
18-20: LGTM!src/aiq_agent/agents/deep_researcher/custom_middleware.py (1)
244-245: LGTM!src/aiq_agent/agents/deep_researcher/tools/source_routing.py (1)
231-238: LGTM!tests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.py (1)
27-65: LGTM!Also applies to: 111-126, 184-216
src/aiq_agent/agents/deep_researcher/factory.py (1)
102-107: LGTM!Also applies to: 255-279, 395-436
src/aiq_agent/agents/deep_researcher/models/subagent_contracts.py (1)
32-51: LGTM!Also applies to: 77-83, 134-137
tests/aiq_agent/agents/deep_researcher/test_factory.py (1)
52-68: LGTM!Also applies to: 184-211, 260-274
src/aiq_agent/agents/deep_researcher/skills/synthesis/prediction-report-writer/SKILL.md (1)
4-19: LGTM!docs/source/architecture/agents/clarifier.md (1)
1-41: LGTM!Also applies to: 57-145
docs/notebooks/2_Deep_Researcher_Customization.ipynb (1)
280-290: 🎯 Functional Correctness | ⚡ Quick winOrchestrator row still contradicts the Writer row.
Line 286 says the Orchestrator "writes the final report," but the Writer row (line 287) and the rest of this PR's architecture (writer-agent delegation) say the writer subagent synthesizes it. This exact contradiction was flagged previously and remains unresolved here.
📝 Proposed fix
- "| **Orchestrator** | `orchestrator_llm` | Coordinates the workflow and writes the final report (required). |\n", + "| **Orchestrator** | `orchestrator_llm` | Coordinates the workflow, builds research queries, and delegates final synthesis (required). |\n",As per path instructions, review documentation for stale examples that no longer match the repository layout.
Source: Path instructions
tests/aiq_agent/agents/clarifier/models/test_state.py (1)
129-133: LGTM!docs/source/resources/troubleshooting.md (1)
37-37: LGTM!src/aiq_agent/agents/clarifier/models/state.py (1)
28-35: LGTM!Also applies to: 38-66
docs/notebooks/1_Deep_Researcher_Web_Search.ipynb (1)
244-248: 🎯 Functional Correctness | ⚡ Quick winStale "plan" reference in the backend description.
This unchanged sentence still says the backend routes to
/shared/for "plan and scratch files," but this PR removes the planner and/shared/plan.json. Update to just "scratch files" (or similar) for consistency with the rewritten walkthrough on the next line.As per path instructions, review documentation for stale examples that no longer match the repository layout.
Source: Path instructions
src/aiq_agent/agents/deep_researcher/README.md (2)
11-44: 🎯 Functional Correctness | ⚡ Quick winArchitecture diagram omits the writer-agent subagent.
The diagram shows only
source-router-agentandresearcher workers, but this file (line 62, parameters table) documents a third subagent,writer-agent(writer_llm), that performs final synthesis. The diagram should reflect the actual three-subagent architecture.As per path instructions, review documentation for stale examples that no longer match the repository layout.
Source: Path instructions
98-104: 🎯 Functional Correctness | ⚡ Quick win"Orchestrator produces the polished report" contradicts the writer-agent delegation model.
Per
agent.py's_salvage_inline_report(only kicks in "when the orchestrator skips the writer-agent delegation"), the writer-agent normally synthesizes the final report; the orchestrator writing it inline is a fallback. Line 103 was updated to mention the writer skill, but the phase header/lead-in text (lines 100-102) still attributes report authorship to the orchestrator.📝 Proposed fix
-The **orchestrator** produces the polished report: +The **writer-agent**, delegated by the orchestrator, produces the polished report:As per path instructions, review documentation for stale examples that no longer match the repository layout.
Source: Path instructions
src/aiq_agent/agents/clarifier/register.py (1)
62-94: LGTM!Also applies to: 121-206, 208-215
src/aiq_agent/agents/clarifier/agent.py (2)
96-192: LGTM!Also applies to: 386-536
1-536: 📐 Maintainability & Code QualityNo orphaned plan-preview symbols remain;
planner_llmis legitimate role wiring. The remaining repo hit isfrontends/aiq_api/src/aiq_api/jobs/runner.py, whereLLMRole.PLANNERmaps to theplanner_llmconfig attribute. That is not a stale plan-approval reference.> Likely an incorrect or invalid review comment.src/aiq_agent/agents/clarifier/prompts/research_clarification.j2 (1)
81-81: LGTM!Also applies to: 115-120
src/aiq_agent/agents/deep_researcher/prompts/researcher.j2 (1)
7-11: LGTM!Also applies to: 46-46
.agents/skills/aiq-customize-prompts-models/references/model-selection.md (1)
33-33: LGTM!Also applies to: 43-50, 58-60
docs/source/customization/prompts.md (2)
16-20: LGTM!Also applies to: 34-45
121-127: LGTM!Also applies to: 144-145, 233-240, 288-288
src/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2 (4)
1-11: LGTM!
34-61: LGTM!
63-96: LGTM!
123-143: LGTM!src/aiq_agent/agents/deep_researcher/prompts/source_router.j2 (1)
26-30: 🗄️ Data Integrity & IntegrationNo action needed —
SourceRoutingPlanalready usesrouting_guidance, and the prompt matches that field name.src/aiq_agent/agents/chat_researcher/agent.py (1)
153-191: 🩺 Stability & Availability
plan_rejectedbranch is gone
clarifier_nodenow always routes todeep_researchand carries onlyclarifier_result; there’s no remainingplan_rejectedearly-exit path.> Likely an incorrect or invalid review comment.docs/notebooks/0_Getting_Started_with_AIQ.ipynb (2)
384-400: Keep the notebook prose aligned with the shown config.The text here still describes clarifier wiring and
enable_clarifierbehavior, but the YAML shown above does not define aclarifier_agentor any plan-approval flow. Please either add the missing config entries or remove the clarifier-specific claims from this section. As per path instructions, "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."Source: Path instructions
358-362: LGTM!Also applies to: 624-624
src/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.md (1)
4-33: LGTM!Also applies to: 98-98
tests/aiq_agent/agents/deep_researcher/test_agent.py (1)
326-327: LGTM!Also applies to: 383-387, 413-417, 435-441, 452-453, 477-485, 535-537, 601-601, 628-635, 1040-1040, 1052-1058
docs/source/examples/full-pipeline-web.md (1)
8-8: LGTM!Also applies to: 142-150, 186-186
docs/source/architecture/agents/deep-researcher.md (1)
30-84: LGTM!Also applies to: 117-123, 132-149, 165-199
docs/source/customization/configuration-reference.md (1)
338-362: LGTM!Also applies to: 470-472, 507-507
docs/source/architecture/overview.md (1)
30-32: LGTM!Also applies to: 101-103, 122-122
tests/aiq_agent/jobs/test_runner.py (1)
1545-1577: LGTM!Also applies to: 1991-1991
2521272 to
12cc157
Compare
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (6)
docs/source/architecture/overview.md (2)
86-86: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick winStale "approved plan" wording in ChatResearcherState table.
clarifier_resultis described as "Clarification log and approved plan context," but plan approval has been removed; the field now only carries the clarifier's context/log (seeClarifierResult.clarifier_loginclarifier/models/state.py).📝 Proposed fix
-| `clarifier_result` | `str` or `None` | Clarification log and approved plan context | +| `clarifier_result` | `str` or `None` | Clarification dialog log/context for deep research |As per coding guidelines, "Update the docs under docs/source/ when behavior, configuration, or workflows change."
🤖 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/architecture/overview.md` at line 86, The ChatResearcherState documentation still refers to an “approved plan” in the clarifier_result description, but that concept has been removed. Update the table entry for clarifier_result in the architecture overview docs so it matches the current ClarifierResult.clarifier_log behavior from clarifier/models/state.py and describes only the clarifier context/log.Source: Coding guidelines
64-71: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick winStale plan-approval reference left in routing logic description.
This bullet still says escalation routes to
clarifier"so the user can review and approve a plan before deep research begins." The plan-approval flow has been removed from the clarifier per this PR (the clarifier now only gathers context / optionally clarifies output type;ClarifierResultno longer carries plan fields). This description is now inaccurate.📝 Proposed fix
routes to the `clarifier` node (not directly to `deep_research`), so the - user can review and approve a plan before deep research begins. + clarifier can gather additional context (and, if the request is vague, + ask a clarifying question) before deep research begins. Escalation is gated by the `enable_escalation` config flag.As per coding guidelines, "Update the docs under docs/source/ when behavior, configuration, or workflows change."
🤖 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/architecture/overview.md` around lines 64 - 71, Update the `should_escalate` bullet in the architecture overview so it no longer mentions user review or approval of a plan before deep research, since that plan-approval flow was removed from `clarifier`. Keep the routing description accurate by stating that escalation goes to `clarifier` for context gathering or output-type clarification, and verify the wording matches the current `ClarifierResult` behavior and any related workflow docs under `docs/source/`.Source: Coding guidelines
src/aiq_agent/agents/deep_researcher/README.md (2)
165-169: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winLLM Roles table omits
ROUTERandREPORT_WRITER.The table only documents
ORCHESTRATORandRESEARCHER, butsource_router_llm/writer_llm(documented just above) map toROUTER/REPORT_WRITERroles perregister.py. Worth completing the table while this section is being touched.🤖 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 `@src/aiq_agent/agents/deep_researcher/README.md` around lines 165 - 169, The LLM Roles table in the deep_researcher README is incomplete because it only lists ORCHESTRATOR and RESEARCHER. Update the table to include the missing ROUTER and REPORT_WRITER roles, and align their “Configured By” entries with the documented source_router_llm and writer_llm settings used by register.py so the role mapping is complete and consistent.
98-104: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winPhase 3/4 description is stale and misattributes report generation to the orchestrator.
deep-researcher.md's rewritten Workflow Phases state Phase 3 is "Final Report" where "the orchestrator delegates synthesis to the writer subagent, which... produces a polished report," and citation verification is a separate deterministic Phase 4 pipeline. Here, Phase 4 still says "The orchestrator produces the polished report," contradicting the writer-delegation model this PR establishes, and there's no equivalent "Citation Management"/"Citation Verification" phase alignment between the two docs.📝 Proposed fix
-### Phase 4: Final Report -The **orchestrator** produces the polished report: -- Inline citations with numbered references -- Structure chosen by the selected writer skill and the user's requested output shape -- Publication-ready formatting +### Phase 4: Final Report +The **orchestrator** delegates synthesis to the **writer** subagent, which: +- Selects the most specific applicable writer skill for the requested output shape +- Produces a polished report with inline citations and numbered references +- Publication-ready formatting🤖 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 `@src/aiq_agent/agents/deep_researcher/README.md` around lines 98 - 104, Update the deep_researcher README workflow phase description so Phase 4 no longer says the orchestrator produces the polished report; align it with the writer-subagent model used in deep-researcher.md by describing the orchestrator as delegating synthesis to the writer skill/subagent and keeping citation handling in a separate verification/management phase. Make the phase names and responsibilities consistent across the README and the rewritten Workflow Phases section.docs/source/customization/configuration-reference.md (1)
338-362: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winDocument the
enable_source_routertoggle here.The section now says source routing is optional, but the reference still only lists the role-specific LLM refs. Readers need the actual flag that disables the stage to reproduce the runtime config.
♻️ Proposed fix
functions: deep_research_agent: _type: deep_research_agent orchestrator_llm: nemotron_super_llm + enable_source_router: false source_router_llm: nemotron_super_llm researcher_llm: nemotron_super_llm writer_llm: nemotron_super_llm @@ | `orchestrator_llm` | `str` | **required** | LLM for the orchestrator that coordinates the research workflow. | +| `enable_source_router` | `bool` | `true` | Enable or disable the optional source-router stage. | | `source_router_llm` | `str` | `None` | LLM for the source-router sub-agent. Falls back to `orchestrator_llm` if not specified. |🤖 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/customization/configuration-reference.md` around lines 338 - 362, The deep_research_agent configuration docs are missing the actual toggle for disabling the source-router stage. Update the parameter table and example around deep_research_agent to document enable_source_router, including its type/default and that it controls whether the source-router sub-agent runs, while keeping the existing orchestrator_llm, source_router_llm, researcher_llm, and writer_llm references intact.src/aiq_agent/agents/deep_researcher/models/subagent_contracts.py (1)
41-51: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueStale "before planning" reference in docstring.
The class docstring still says "produced before planning," but the planner step this class fed into has been removed by this PR (field renamed
planner_guidance→routing_guidance). Consider updating to something like "Advisory source route produced before the orchestrator writes research queries."🤖 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 `@src/aiq_agent/agents/deep_researcher/models/subagent_contracts.py` around lines 41 - 51, The SourceRoutingPlan docstring still refers to a removed planner step, so update the class description to match the current flow and new routing_guidance field. In subagent_contracts.py, revise the wording on SourceRoutingPlan to describe it as the advisory source route used before the orchestrator writes research queries, and ensure the surrounding field descriptions remain aligned with routing_guidance rather than planner_guidance.
♻️ Duplicate comments (1)
docs/notebooks/1_Deep_Researcher_Web_Search.ipynb (1)
296-298: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winMiddleware description still inaccurate (previously flagged, unresolved).
This was already flagged in an earlier review round:
agent.pydoes not use a single shared middleware list for all three roles — researcher and writer share a common stack, while the orchestrator uses its own. The role names were updated (planner → writer) but the "same middleware list" claim itself was not corrected.🤖 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/notebooks/1_Deep_Researcher_Web_Search.ipynb` around lines 296 - 298, The middleware summary is still inaccurate in the notebook’s “Middleware (from agent.py)” section. Update the description to match the actual setup in agent.py: researcher and writer share one middleware stack, while orchestrator uses a separate stack. Use the existing “Middleware” text block and the role references in that section to correct the wording so it no longer claims all agents use the same middleware list.
🤖 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/prompts.md`:
- Line 45: Update the prompt naming convention sentence in the customization
prompts documentation to include source_router.j2 alongside researcher.j2,
orchestrator.j2, and writer.j2. Keep the wording aligned with the deep-research
prompt set and ensure the example list matches the current config shape so
readers see all supported template roles.
In `@docs/source/get-started/installation.md`:
- Around line 28-30: The self-hosting model matrix in the installation guide is
missing the new source-router LLM entry exposed by the deep-research config
surface. Update the table near the existing LLM rows to either add a separate
source-router line or clearly state that source_router_llm reuses the
orchestrator model, using the same naming convention as the other entries so
self-hosters can provision the right model.
In `@src/aiq_agent/agents/deep_researcher/register.py`:
- Around line 78-81: The `DeepResearcherAgent.__init__` docstring still contains
the stale “before planning” wording for `enable_source_router`; update that
parameter description in `agent.py` to match the new “before research” phrasing
used in `register.py`, and remove any remaining planner-related wording from the
docstring.
---
Outside diff comments:
In `@docs/source/architecture/overview.md`:
- Line 86: The ChatResearcherState documentation still refers to an “approved
plan” in the clarifier_result description, but that concept has been removed.
Update the table entry for clarifier_result in the architecture overview docs so
it matches the current ClarifierResult.clarifier_log behavior from
clarifier/models/state.py and describes only the clarifier context/log.
- Around line 64-71: Update the `should_escalate` bullet in the architecture
overview so it no longer mentions user review or approval of a plan before deep
research, since that plan-approval flow was removed from `clarifier`. Keep the
routing description accurate by stating that escalation goes to `clarifier` for
context gathering or output-type clarification, and verify the wording matches
the current `ClarifierResult` behavior and any related workflow docs under
`docs/source/`.
In `@docs/source/customization/configuration-reference.md`:
- Around line 338-362: The deep_research_agent configuration docs are missing
the actual toggle for disabling the source-router stage. Update the parameter
table and example around deep_research_agent to document enable_source_router,
including its type/default and that it controls whether the source-router
sub-agent runs, while keeping the existing orchestrator_llm, source_router_llm,
researcher_llm, and writer_llm references intact.
In `@src/aiq_agent/agents/deep_researcher/models/subagent_contracts.py`:
- Around line 41-51: The SourceRoutingPlan docstring still refers to a removed
planner step, so update the class description to match the current flow and new
routing_guidance field. In subagent_contracts.py, revise the wording on
SourceRoutingPlan to describe it as the advisory source route used before the
orchestrator writes research queries, and ensure the surrounding field
descriptions remain aligned with routing_guidance rather than planner_guidance.
In `@src/aiq_agent/agents/deep_researcher/README.md`:
- Around line 165-169: The LLM Roles table in the deep_researcher README is
incomplete because it only lists ORCHESTRATOR and RESEARCHER. Update the table
to include the missing ROUTER and REPORT_WRITER roles, and align their
“Configured By” entries with the documented source_router_llm and writer_llm
settings used by register.py so the role mapping is complete and consistent.
- Around line 98-104: Update the deep_researcher README workflow phase
description so Phase 4 no longer says the orchestrator produces the polished
report; align it with the writer-subagent model used in deep-researcher.md by
describing the orchestrator as delegating synthesis to the writer skill/subagent
and keeping citation handling in a separate verification/management phase. Make
the phase names and responsibilities consistent across the README and the
rewritten Workflow Phases section.
---
Duplicate comments:
In `@docs/notebooks/1_Deep_Researcher_Web_Search.ipynb`:
- Around line 296-298: The middleware summary is still inaccurate in the
notebook’s “Middleware (from agent.py)” section. Update the description to match
the actual setup in agent.py: researcher and writer share one middleware stack,
while orchestrator uses a separate stack. Use the existing “Middleware” text
block and the role references in that section to correct the wording so it no
longer claims all agents use the same middleware list.
🪄 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: e991c39c-1bae-4e3e-b3b1-88c16bc2dca8
📒 Files selected for processing (64)
.agents/skills/aiq-customize-prompts-models/SKILL.md.agents/skills/aiq-customize-prompts-models/references/model-selection.md.agents/skills/aiq-customize-prompts-models/references/prompt-templates.mdconfigs/config_cli_default.ymlconfigs/config_domain_routing_and_skills.ymlconfigs/config_frontier_models.ymlconfigs/config_openshell.ymlconfigs/config_web_default_guardrails.ymlconfigs/config_web_default_llamaindex.ymlconfigs/config_web_frag.ymlconfigs/config_web_frag_mcp_auth.ymldocs/notebooks/0_Getting_Started_with_AIQ.ipynbdocs/notebooks/1_Deep_Researcher_Web_Search.ipynbdocs/notebooks/2_Deep_Researcher_Customization.ipynbdocs/source/architecture/agents/clarifier.mddocs/source/architecture/agents/deep-researcher.mddocs/source/architecture/overview.mddocs/source/customization/configuration-reference.mddocs/source/customization/hitl.mddocs/source/customization/index.mddocs/source/customization/prompts.mddocs/source/customization/swapping-models.mddocs/source/examples/cli-with-local-nims.mddocs/source/examples/full-pipeline-llamaindex.mddocs/source/examples/full-pipeline-web.mddocs/source/examples/hybrid-frontier-model.mddocs/source/examples/skills-sandbox/index.mddocs/source/get-started/installation.mddocs/source/profiling/index.mddocs/source/resources/faq.mddocs/source/resources/troubleshooting.mdfrontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench.ymlfrontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench_profiling.ymlfrontends/benchmarks/deepsearch_qa/configs/config_deepsearch_qa.ymlfrontends/benchmarks/freshqa/configs/config_full_workflow.ymlsrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/clarifier/agent.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/clarifier/prompts/plan_generation.j2src/aiq_agent/agents/clarifier/prompts/research_clarification.j2src/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/deep_researcher/README.mdsrc/aiq_agent/agents/deep_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pysrc/aiq_agent/agents/deep_researcher/factory.pysrc/aiq_agent/agents/deep_researcher/models/__init__.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2src/aiq_agent/agents/deep_researcher/prompts/planner.j2src/aiq_agent/agents/deep_researcher/prompts/researcher.j2src/aiq_agent/agents/deep_researcher/prompts/source_router.j2src/aiq_agent/agents/deep_researcher/prompts/writer.j2src/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pysrc/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.mdsrc/aiq_agent/agents/deep_researcher/skills/synthesis/prediction-report-writer/SKILL.mdsrc/aiq_agent/agents/deep_researcher/tools/source_routing.pytests/aiq_agent/agents/clarifier/models/test_state.pytests/aiq_agent/agents/clarifier/test_agent.pytests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pytests/aiq_agent/agents/deep_researcher/test_agent.pytests/aiq_agent/agents/deep_researcher/test_custom_middleware.pytests/aiq_agent/agents/deep_researcher/test_factory.pytests/aiq_agent/jobs/test_runner.py
💤 Files with no reviewable changes (20)
- frontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench.yml
- src/aiq_agent/agents/clarifier/prompts/plan_generation.j2
- docs/source/examples/hybrid-frontier-model.md
- configs/config_domain_routing_and_skills.yml
- src/aiq_agent/agents/deep_researcher/prompts/planner.j2
- docs/source/examples/full-pipeline-llamaindex.md
- frontends/benchmarks/freshqa/configs/config_full_workflow.yml
- frontends/benchmarks/deepresearch_bench/configs/config_deep_research_bench_profiling.yml
- docs/source/examples/cli-with-local-nims.md
- src/aiq_agent/agents/deep_researcher/models/init.py
- configs/config_cli_default.yml
- configs/config_web_default_guardrails.yml
- configs/config_web_default_llamaindex.yml
- frontends/benchmarks/deepsearch_qa/configs/config_deepsearch_qa.yml
- configs/config_frontier_models.yml
- configs/config_web_frag.yml
- configs/config_openshell.yml
- tests/aiq_agent/agents/clarifier/test_agent.py
- configs/config_web_frag_mcp_auth.yml
- tests/aiq_agent/agents/deep_researcher/test_custom_middleware.py
📜 Review details
⚠️ CI failures not shown inline (2)
GitHub Actions: AIQ CI / Script Validation: refactor(deep-research): remove planner agent and clarifier plan appr…
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: refactor(deep-research): remove planner agent and clarifier plan appr…
Conclusion: failure
Current runner version: '2.335.1'
##[group]Runner Image Provisioner
Hosted Compute Agent
Version: 20260624.560
Commit: 925d229a51159bc391ae97e54a2dd1fe20af789d
Build Date:
Worker ID: {5c5cd016-4707-4f7f-86e0-ac9c604f10bd}
Azure Region: eastus2
##[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 ...
🧰 Additional context used
📓 Path-based instructions (8)
**/*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run ruff check and ruff format validation for Python code changes
**/*.py: Python code must be linted and formatted with Ruff using line length 120, target Python 3.11, rule sets E,F,W,I,PL,UP, and isort force-single-line configuration
Never commit secrets, tokens, or environment-specific hostnames; use environment variables and SecretStr instead, resolving API keys at runtime
Never print or log secret values, including in tool output or error messages
Missing-secret paths must degrade gracefully (stub/skip), not crash or leak
Do not hand-reformat unrelated code when making changes; match the existing import and formatting style
Files:
src/aiq_agent/agents/deep_researcher/tools/source_routing.pytests/aiq_agent/agents/clarifier/models/test_state.pysrc/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pysrc/aiq_agent/agents/deep_researcher/agent.pysrc/aiq_agent/agents/chat_researcher/agent.pytests/aiq_agent/jobs/test_runner.pytests/aiq_agent/agents/deep_researcher/test_agent.pysrc/aiq_agent/agents/deep_researcher/factory.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pytests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pytests/aiq_agent/agents/deep_researcher/test_factory.pysrc/aiq_agent/agents/clarifier/agent.py
src/aiq_agent/**/*.py
📄 CodeRabbit inference engine (AGENTS.md)
src/aiq_agent/**/*.py: Respect authenticated data sources by honoring requires_auth, per-user token pass-through, and backend token validators; apply owner guardrails before loading protected report or artifact context into an agent
Do not weaken or bypass AuthMiddleware, validators, or auth gating without a prior design discussion
Files:
src/aiq_agent/agents/deep_researcher/tools/source_routing.pysrc/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pysrc/aiq_agent/agents/deep_researcher/agent.pysrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/factory.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pysrc/aiq_agent/agents/clarifier/agent.py
**
⚙️ 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:
src/aiq_agent/agents/deep_researcher/tools/source_routing.pydocs/source/customization/index.mdtests/aiq_agent/agents/clarifier/models/test_state.pysrc/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pydocs/source/resources/troubleshooting.mdsrc/aiq_agent/agents/clarifier/prompts/research_clarification.j2src/aiq_agent/agents/deep_researcher/agent.pydocs/source/customization/swapping-models.mddocs/source/resources/faq.mdsrc/aiq_agent/agents/deep_researcher/prompts/source_router.j2docs/source/customization/hitl.mddocs/source/get-started/installation.mdsrc/aiq_agent/agents/deep_researcher/prompts/researcher.j2docs/source/architecture/overview.mddocs/source/examples/skills-sandbox/index.mddocs/source/examples/full-pipeline-web.mdsrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/prompts/writer.j2tests/aiq_agent/jobs/test_runner.pysrc/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.mddocs/source/customization/configuration-reference.mdsrc/aiq_agent/agents/deep_researcher/skills/synthesis/prediction-report-writer/SKILL.mddocs/source/customization/prompts.mdtests/aiq_agent/agents/deep_researcher/test_agent.pysrc/aiq_agent/agents/deep_researcher/factory.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2docs/notebooks/0_Getting_Started_with_AIQ.ipynbtests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/deep_researcher/README.mddocs/notebooks/1_Deep_Researcher_Web_Search.ipynbsrc/aiq_agent/agents/clarifier/models/state.pydocs/source/architecture/agents/deep-researcher.mddocs/notebooks/2_Deep_Researcher_Customization.ipynbsrc/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pydocs/source/architecture/agents/clarifier.mddocs/source/profiling/index.mdtests/aiq_agent/agents/deep_researcher/test_factory.pysrc/aiq_agent/agents/clarifier/agent.py
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/tools/source_routing.pysrc/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.pysrc/aiq_agent/agents/clarifier/prompts/research_clarification.j2src/aiq_agent/agents/deep_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/prompts/source_router.j2src/aiq_agent/agents/deep_researcher/prompts/researcher.j2src/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/deep_researcher/prompts/writer.j2src/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.mdsrc/aiq_agent/agents/deep_researcher/skills/synthesis/prediction-report-writer/SKILL.mdsrc/aiq_agent/agents/deep_researcher/factory.pysrc/aiq_agent/agents/deep_researcher/models/subagent_contracts.pysrc/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2src/aiq_agent/agents/deep_researcher/register.pysrc/aiq_agent/agents/deep_researcher/README.mdsrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/deep_researcher/custom_middleware.pysrc/aiq_agent/agents/clarifier/agent.py
docs/source/**/*
📄 CodeRabbit inference engine (AGENTS.md)
Update the docs under docs/source/ when behavior, configuration, or workflows change
Files:
docs/source/customization/index.mddocs/source/resources/troubleshooting.mddocs/source/customization/swapping-models.mddocs/source/resources/faq.mddocs/source/customization/hitl.mddocs/source/get-started/installation.mddocs/source/architecture/overview.mddocs/source/examples/skills-sandbox/index.mddocs/source/examples/full-pipeline-web.mddocs/source/customization/configuration-reference.mddocs/source/customization/prompts.mddocs/source/architecture/agents/deep-researcher.mddocs/source/architecture/agents/clarifier.mddocs/source/profiling/index.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/index.mddocs/source/resources/troubleshooting.mddocs/source/customization/swapping-models.mddocs/source/resources/faq.mddocs/source/customization/hitl.mddocs/source/get-started/installation.mddocs/source/architecture/overview.mddocs/source/examples/skills-sandbox/index.mddocs/source/examples/full-pipeline-web.mddocs/source/customization/configuration-reference.mddocs/source/customization/prompts.mddocs/notebooks/0_Getting_Started_with_AIQ.ipynbdocs/notebooks/1_Deep_Researcher_Web_Search.ipynbdocs/source/architecture/agents/deep-researcher.mddocs/notebooks/2_Deep_Researcher_Customization.ipynbdocs/source/architecture/agents/clarifier.mddocs/source/profiling/index.md
**/*test*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run pytest for all behavior changes in Python code
Files:
tests/aiq_agent/agents/clarifier/models/test_state.pytests/aiq_agent/jobs/test_runner.pytests/aiq_agent/agents/deep_researcher/test_agent.pytests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.pytests/aiq_agent/agents/deep_researcher/test_factory.py
{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:
.agents/skills/aiq-customize-prompts-models/references/prompt-templates.md.agents/skills/aiq-customize-prompts-models/SKILL.md.agents/skills/aiq-customize-prompts-models/references/model-selection.md
🪛 LanguageTool
docs/source/resources/faq.md
[grammar] ~29-~29: Ensure spelling is correct
Context: ...ies. - Deep research is thorough (2-10min), uses a multi-agent pipeline (orchestr...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/source/customization/hitl.md
[style] ~7-~7: Consider a different adjective to strengthen your wording.
Context: ...in-the-loop (the clarifier) runs before deep research. The clarifier gathers context...
(DEEP_PROFOUND)
[style] ~13-~13: Consider a different adjective to strengthen your wording.
Context: ...rely No clarification step runs before deep research: ```yaml workflow: _type: c...
(DEEP_PROFOUND)
docs/source/architecture/overview.md
[style] ~101-~101: Consider a different adjective to strengthen your wording.
Context: ...tgreSQL). - Subagent architecture: Deep research uses specialized subagents (...
(DEEP_PROFOUND)
src/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.md
[style] ~13-~13: Consider a different adjective to strengthen your wording.
Context: ...learly asks for a comprehensive report, deep analysis, publication-ready writeup, or...
(DEEP_PROFOUND)
[grammar] ~13-~13: Ensure spelling is correct
Context: ...eport, deep analysis, publication-ready writeup, or whitepaper-style answer. Do not us...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
src/aiq_agent/agents/deep_researcher/README.md
[style] ~239-~239: Consider a different adjective to strengthen your wording.
Context: ... user goes through the clarifier before deep research, the clarification log is pass...
(DEEP_PROFOUND)
🔇 Additional comments (51)
src/aiq_agent/agents/deep_researcher/tools/source_routing.py (1)
231-238: LGTM!docs/source/customization/index.md (1)
21-21: LGTM!src/aiq_agent/agents/deep_researcher/sandbox/artifacts/models.py (1)
80-80: LGTM!docs/source/resources/troubleshooting.md (1)
37-37: LGTM!docs/source/architecture/overview.md (2)
30-33: LGTM!Also applies to: 101-103
122-122: LGTM!src/aiq_agent/agents/chat_researcher/agent.py (1)
169-191: LGTM!src/aiq_agent/agents/clarifier/models/state.py (1)
28-66: LGTM!src/aiq_agent/agents/clarifier/agent.py (2)
82-193: LGTM! Plan-generation/approval removal (fallback prompt, keyword constants,planner_llm, plan-preview parsing helpers, and the simplifiedrun()result) is internally consistent with the updatedClarifierResult/ClarifierAgentStatemodels and withregister.py's constructor call.Also applies to: 404-406, 521-536
496-519: 📐 Maintainability & Code QualityKeep the
__end__route key as-is.langgraph.graph.ENDis"end", not"__end__", so swapping this mapping toENDwould change the terminal branch key and break the route table.> Likely an incorrect or invalid review comment.tests/aiq_agent/agents/clarifier/models/test_state.py (1)
129-133: LGTM!src/aiq_agent/agents/clarifier/prompts/research_clarification.j2 (1)
75-82: LGTM!Also applies to: 115-120
.agents/skills/aiq-customize-prompts-models/references/prompt-templates.md (1)
16-20: LGTM!src/aiq_agent/agents/deep_researcher/agent.py (1)
156-164: LGTM!docs/source/customization/swapping-models.md (1)
38-38: LGTM!docs/source/resources/faq.md (1)
29-35: LGTM!src/aiq_agent/agents/deep_researcher/factory.py (1)
102-107: LGTM!Also applies to: 255-279, 395-436
src/aiq_agent/agents/deep_researcher/custom_middleware.py (2)
239-249: LGTM!
1-30: 🩺 Stability & AvailabilityStale
PlanPersistenceMiddlewarereference.src/aiq_agent/agents/deep_researcher/custom_middleware.pyno longer containsPlanPersistenceMiddleware; line 503 now startsToolResultPruningMiddleware, so the line-502 persistence note is outdated.> Likely an incorrect or invalid review comment.src/aiq_agent/agents/deep_researcher/prompts/source_router.j2 (1)
1-1: LGTM!Also applies to: 26-30, 39-39
docs/source/customization/hitl.md (1)
7-30: LGTM!src/aiq_agent/agents/deep_researcher/register.py (1)
63-64: LGTM!Also applies to: 208-213
src/aiq_agent/agents/deep_researcher/README.md (1)
24-32: LGTM!Also applies to: 62-62, 71-71, 126-141, 229-239
docs/notebooks/1_Deep_Researcher_Web_Search.ipynb (1)
12-12: LGTM!Also applies to: 44-52, 238-238, 248-248, 268-273, 288-288, 342-342, 354-354, 462-465, 508-508, 631-634, 792-793
docs/source/architecture/agents/deep-researcher.md (1)
30-84: LGTM!Also applies to: 117-122, 132-133, 148-149, 165-199
src/aiq_agent/agents/clarifier/register.py (1)
70-90: LGTM!Also applies to: 121-125, 166-179, 188-188, 199-214
.agents/skills/aiq-customize-prompts-models/SKILL.md (1)
3-3: LGTM!Also applies to: 52-52, 71-71
docs/source/examples/skills-sandbox/index.md (1)
28-28: LGTM!Also applies to: 132-134
docs/source/examples/full-pipeline-web.md (1)
8-8: LGTM!Also applies to: 142-150, 186-186
docs/source/customization/configuration-reference.md (1)
296-307: LGTM!Also applies to: 470-472, 507-507
src/aiq_agent/agents/deep_researcher/prompts/writer.j2 (2)
2-2: LGTM!Also applies to: 28-30, 48-57, 77-85
6-17: 🎯 Functional CorrectnessNo change needed The writer subagent is explicitly passed
skills, so theAvailable Skillsblock is part of its injected prompt.src/aiq_agent/agents/deep_researcher/skills/synthesis/long-form-report-writer/SKILL.md (1)
4-18: LGTM!Also applies to: 19-33, 98-98
tests/aiq_agent/jobs/test_runner.py (1)
1551-1577: LGTM!Also applies to: 1991-1991
docs/notebooks/0_Getting_Started_with_AIQ.ipynb (2)
384-384: Clarifier prose still doesn't match this notebook's config.Text continues to describe
enable_clarifier: trueand a wired "clarifier agent," butconfig_simple_researcher.ymlgenerated in this notebook (cell above) defines noclarifier_agentfunction and noenable_clarifiersetting inworkflow. This is the same mismatch flagged previously and still applies to the reworded text.Also applies to: 393-400
Source: Path instructions
358-361: LGTM!docs/notebooks/2_Deep_Researcher_Customization.ipynb (5)
284-290: Orchestrator row still contradicts the Writer row.Line 286 still credits the orchestrator with writing the final report, which conflicts with line 287's Writer role and the orchestrator.j2 changes in this same PR where the orchestrator delegates final synthesis to
writer-agent. This is the same contradiction flagged previously; it doesn't appear to have been fixed despite the prior "addressed" note.📝 Proposed fix
- "| **Orchestrator** | `orchestrator_llm` | Coordinates the workflow and writes the final report (required). |\n", + "| **Orchestrator** | `orchestrator_llm` | Coordinates the workflow, builds research queries, and delegates final synthesis (required). |\n",Source: Path instructions
9-16: LGTM!Also applies to: 27-27
184-184: LGTM!Also applies to: 236-240, 272-273
299-299: LGTM!Also applies to: 324-329, 339-339, 354-355, 387-387, 398-398
530-533: LGTM!Also applies to: 552-552
src/aiq_agent/agents/deep_researcher/models/subagent_contracts.py (3)
32-38: LGTM!
77-83: LGTM!
134-137: LGTM!src/aiq_agent/agents/deep_researcher/prompts/orchestrator.j2 (3)
1-11: LGTM!
38-96: LGTM!
123-143: LGTM!.agents/skills/aiq-customize-prompts-models/references/model-selection.md (1)
33-33: LGTM!Also applies to: 43-50, 58-60
tests/aiq_agent/agents/deep_researcher/models/test_subagent_contracts.py (3)
21-64: LGTM!
111-126: LGTM!
184-216: LGTM!
…ime (NVIDIA-AI-Blueprints#280) ## Overview This PR introduces a provider-neutral, fail-closed sandbox runtime for executing agent-generated code securely, alongside a durable artifact runtime that harvests generated files (such as charts and CSVs). These captured artifacts are now seamlessly rendered inline across all system surfaces, including the Web UI, PDF exports, Markdown reports, and the CLI. ## Proposed Changes ### Sandbox Runtime (src/aiq_agent/agents/deep_researcher/sandbox/) - base.py: Introduced a thin SandboxProvider Abstract Base Class (ABC). Providers only need to implement execute and capabilities. The base class handles lazy single-flight session creation, a serialization lock, idempotency-gated retries, and close() / terminate() lifecycles. - registry.py: Added a config-driven provider dispatch system utilizing aiq.sandbox_providers entry-point discovery to support out-of-tree custom providers. - capabilities.py: Implemented declared guarantees and a verify_capabilities fail-closed gate that explicitly refuses execution if a required security guarantee (e.g., network policy) is unsupported by the active provider. - config.py: Created SandboxConfig containing nested providers.<name>, normalized network policies (blocked | allowlist | open), artifact_capture settings, and a legacy flat-Modal backward-compatibility shim. - providers/modal.py & providers/openshell.py: Built two self-registering out-of-the-box providers to support both cloud (Modal) and on-premise (OpenShell) deployments. ### Artifact Manager (sandbox/artifacts/) - manager.py: Implemented the host-side harvest pipeline featuring path-traversal confinement, extension allowlists, file size caps, MIME-from-bytes/spoof rejection, user quotas, and SVG sanitization before executing a sha256 hash and store-then-emit action. - store.py / models.py / manifest.py: Established a pluggable SqlArtifactStore tied to the shared job database supporting BLOB storage and deduplication, defined the Artifact metadata record, and enforced the manifest.json schema. ### Report Post-Processing - resolve_report_references: Translates user-facing filenames into durable, unique system IDs. - ensure_inline_artifacts_embedded: Acts as a safety net ensuring that ## Figures are correctly embedded within report payloads. - append_artifact_index: Automatically appends a comprehensive ## Generated Artifacts index section to the end of the report. ### Backend Core (src/aiq_agent/agents/deep_researcher/) - agent.py: Connected the artifact harvest, resolve, and indexing pipelines directly into run() (offloaded via asyncio.to_thread) and configured the system to accept sandbox-produced files as valid, grounded outputs. - deepagents_runtime.py: Encapsulates the provider lifecycle, builds the ArtifactManager, exposes workdir and artifact_dir paths, and templates specialized skills directly to the active workspace directory. - custom_middleware.py: Integrated ArtifactHarvestMiddleware to automatically trigger file harvesting immediately following each execution step. - prompts/*.j2: Injected sandbox_artifact_dir context into agent prompts and strictly instructed models to embed figures using the markdown structure: . ### Backend API (frontends/aiq_api) - routes/jobs.py: Exposed auth-scoped endpoints GET .../artifacts and GET .../artifacts/{id}/content, added opt-in submit-path concurrency caps, and introduced artifact retention policies. - jobs/runner.py & jobs/access.py: Managed terminal-path final file harvesting alongside active-job tracking and counting metrics. ### Frontend & UI UI - MarkdownRenderer: Implemented a custom urlTransform to preserve the custom artifact:// protocol scheme and introduced a dedicated img renderer to map assets to the backend content endpoint. Centralized logic into artifact-url.ts as the single source of truth. - ReportTab / ExportFooter / store.ts: Enabled job ID resolution via selectResolvedDeepResearchJobId, ensuring access to assets survives even after a background job completes. - app/api/jobs/async/[...path]/route.ts: Configured a pure binary passthrough stream for artifact contents to bypass unnecessary JSON parsing of raw file bytes. - pages/api/generate-pdf.ts & lib/pdf/ReactPdfDocument.tsx: Implemented server-side data-URI inlining and block-figure image rendering for PDFs (supporting paragraphs, list items, and explicit widths). - hooks/use-download-pdf.ts: Properly threads active job IDs downstream to the PDF generation route. ### Skill & CLI Interface - skills/aiq-research/scripts/aiq.py: Added a --out-dir DIR flag to report commands to export completely portable report.md bundles accompanied by an artifacts/ folder with asset links rewritten to local relative paths. Added a separate --download-dir flag to the artifacts command. ### OpenShell Setup - scripts/setup_openshell.sh, configs/openshell/*, & configs/config_openshell.yml: Added a turnkey, one-command on-premise setup workflow including an environment-free file-transfer shim toggled via AIQ_OPENSHELL_ADAPTER_FILE_TRANSFER. ### Documentation - sandbox/README.md & docs/.../sandbox.md: Outlines overall architecture, provider authoring guidelines, supported rendering surfaces, and core troubleshooting workflows. Verification & Testing - Backend Unit & Integration Tests - Passed successfully via pytest: Bash ``` pytest tests/aiq_agent/agents/deep_researcher/sandbox/ \ tests/aiq_agent/agents/deep_researcher/test_agent.py \ tests/aiq_agent/jobs/test_runner.py -q ``` <!-- List the exact commands, workflows, screenshots, or manual checks used. --> - [x] I ran the relevant local checks or explained why they are not applicable. - [x] I added or updated tests for behavior changes. - [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. #### Where should reviewers start? `sandbox/base.py` + `sandbox/registry.py` (the provider contract), then `sandbox/artifacts/manager.py` (the harvest/validation pipeline) and agent.py::run() (post-processing order), then frontends/ui/.../MarkdownRenderer/artifact-url.ts + the img/urlTransform for the rendering edge. #### Related Issues Dependencies / Install note - The OpenShell path depends on the langchain-nvidia-openshell adapter with the argv file-transfer fix ([pastorsj/langchain-nvidia#1](pastorsj/langchain-nvidia#1), which targets Sam's adapter PR [langchain-ai/langchain-nvidia#303](langchain-ai/langchain-nvidia#303)). - Until NVIDIA-AI-Blueprints#1 is merged into NVIDIA-AI-Blueprints#303 (and NVIDIA-AI-Blueprints#303 published to PyPI), the adapter must be installed from the fork branch — not PyPI. Install via the git spec (or LANGCHAIN_NVIDIA_REPO override that scripts/setup_openshell.sh honors): ``` uv pip install --force-reinstall --no-deps \ 'git+https://github.com/KyleZheng1284/langchain-nvidia.git@fix/openshell-argv-file-transfer#subdirectory=libs/openshell' ``` Without that fix, OpenShell upload_files/download_files fail (the gateway strips OPENSHELL_* env), surfaced as a misleading permission_denied. Modal is unaffected. #### Action items to defer in follow up PR - Productionize the experimental OpenShell integration by providing a physically isolated sandbox per job and verifying the effective network, filesystem, and process policy before execution. - Consolidate provider configuration, preserve artifacts on failure and cancellation, align artifact events with the UI, make artifact deduplication and quota accounting concurrency-safe, enforce PDF auth parity, and pin the OpenShell setup to reproducible dependencies. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added durable artifact support for deep research jobs, including artifact content endpoints and job-scoped artifact rendering across the UI, markdown, and PDF exports (with embedded image support). * Added a sandbox-as-a-service workflow for deep research with OpenShell-backed sandbox provisioning (config, policy, and demo image) and a local setup script. * Added a sandbox concurrency cost guard for async job submissions and a “Sandbox” badge for sandboxed tool calls. * **Bug Fixes** * Improved safety for artifact image handling (sanitization, MIME/spoof resistance, and safer filenames) and better report recovery when writer output is missing. * **Documentation** * Updated sandbox architecture docs and deep-research skill/export guidance. * **Tests** * Added coverage for sandbox concurrency, sandbox runtime/provider compliance, and artifact harvesting/export behavior. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Signed-off-by: Kyle Zheng <kyzheng@nvidia.com> Co-authored-by: Chantal D Gama Rose <cdgamarose@nvidia.com>
12cc157 to
2c17e6c
Compare
ashan-nv
changed the title
cdgamarose-nv
left a comment
cdgamarose-nv
left a comment
There was a problem hiding this comment.
Docs and UI still have some stale references. Once those are cleaned up, this is good to merge
2c17e6c to
97732da
Compare
|
@coderabbitai review |
✅ Action performedReview finished.
|
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 (2)
docs/source/examples/full-pipeline-web.md (1)
142-143: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winRemove the stale plan-approval wording.
This still says the clarifier generates a research plan the user can approve or modify, but the workflow now goes straight from clarifier to
deep_research_agent. Keeping both descriptions here makes the example contradictory. As per path instructions, review docs for stale examples and links that no longer match the repository layout.Suggested fix
- # For deep research: asks clarifying questions and generates a research - # plan that the user can approve or modify before execution. + # For deep research: asks clarifying questions before handing off to the + # deep_research_agent.🤖 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/examples/full-pipeline-web.md` around lines 142 - 143, The deep-research example comment is stale and contradicts the current flow. Update the description around the clarifier/deep_research_agent sequence to remove any wording about generating a user-approvable research plan, and make sure the example matches the direct handoff behavior shown in this pipeline snippet. Keep the surrounding docs wording consistent with the current repository layout and remove any outdated path/example references if present.Source: Path instructions
docs/source/customization/configuration-reference.md (1)
296-307: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winDocument
exclude_toolsforclarifier_agent.
ClarifierConfigstill exposesexclude_toolsinsrc/aiq_agent/agents/clarifier/register.py, but this table omits it, so users can't discover how to exclude inherited tools.♻️ Proposed fix
| `tools` | `list[str]` | `[]` | Tools available for gathering context during clarification. | +| `exclude_tools` | `list[str]` | `[]` | Tool names to exclude when inheriting from the registry. | | `max_turns` | `int` | `3` | Maximum number of clarification Q&A turns before auto-completing. |🤖 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/customization/configuration-reference.md` around lines 296 - 307, The `clarifier_agent` configuration table is missing the `exclude_tools` option even though `ClarifierConfig` still supports it in `register.py`, so add a row for `exclude_tools` alongside `llm`, `tools`, and `max_turns`. Describe it as the list of inherited tools to exclude from clarification context, and ensure the docs match the actual `ClarifierConfig` fields so users can discover and use it.
🤖 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/customization/configuration-reference.md`:
- Around line 296-307: The `clarifier_agent` configuration table is missing the
`exclude_tools` option even though `ClarifierConfig` still supports it in
`register.py`, so add a row for `exclude_tools` alongside `llm`, `tools`, and
`max_turns`. Describe it as the list of inherited tools to exclude from
clarification context, and ensure the docs match the actual `ClarifierConfig`
fields so users can discover and use it.
In `@docs/source/examples/full-pipeline-web.md`:
- Around line 142-143: The deep-research example comment is stale and
contradicts the current flow. Update the description around the
clarifier/deep_research_agent sequence to remove any wording about generating a
user-approvable research plan, and make sure the example matches the direct
handoff behavior shown in this pipeline snippet. Keep the surrounding docs
wording consistent with the current repository layout and remove any outdated
path/example references if present.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: fce53f72-5b01-45e5-b6f9-4be7536d35c1
📒 Files selected for processing (36)
.agents/skills/aiq-customize-prompts-models/references/model-selection.md.agents/skills/aiq-customize-prompts-models/references/prompt-templates.mdconfigs/config_cli_default.ymlconfigs/config_frontier_models.ymlconfigs/config_openshell.ymlconfigs/config_web_default_guardrails.ymlconfigs/config_web_default_llamaindex.ymlconfigs/config_web_frag.ymlconfigs/config_web_frag_mcp_auth.ymlconfigs/config_web_opensearch.ymldocs/notebooks/0_Getting_Started_with_AIQ.ipynbdocs/source/architecture/agents/clarifier.mddocs/source/architecture/agents/index.mddocs/source/customization/configuration-reference.mddocs/source/customization/hitl.mddocs/source/customization/index.mddocs/source/customization/prompts.mddocs/source/examples/cli-with-local-nims.mddocs/source/examples/full-pipeline-llamaindex.mddocs/source/examples/full-pipeline-web.mddocs/source/examples/hybrid-frontier-model.mddocs/source/resources/faq.mddocs/source/resources/troubleshooting.mdfrontends/ui/src/features/chat/components/AgentPrompt.spec.tsxfrontends/ui/src/features/chat/components/AgentPrompt.tsxfrontends/ui/src/features/chat/hooks/use-current-session-busy.spec.tsfrontends/ui/src/features/chat/lib/session-activity.spec.tsfrontends/ui/src/features/chat/types.tssrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/clarifier/agent.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/clarifier/prompts/plan_generation.j2src/aiq_agent/agents/clarifier/prompts/research_clarification.j2src/aiq_agent/agents/clarifier/register.pytests/aiq_agent/agents/clarifier/models/test_state.pytests/aiq_agent/agents/clarifier/test_agent.py
💤 Files with no reviewable changes (14)
- configs/config_frontier_models.yml
- docs/source/examples/cli-with-local-nims.md
- configs/config_web_default_guardrails.yml
- tests/aiq_agent/agents/clarifier/test_agent.py
- docs/source/examples/full-pipeline-llamaindex.md
- configs/config_cli_default.yml
- configs/config_web_default_llamaindex.yml
- configs/config_web_frag.yml
- src/aiq_agent/agents/clarifier/prompts/plan_generation.j2
- docs/source/examples/hybrid-frontier-model.md
- frontends/ui/src/features/chat/components/AgentPrompt.spec.tsx
- configs/config_web_frag_mcp_auth.yml
- docs/source/customization/prompts.md
- configs/config_openshell.yml
📜 Review details
⚠️ CI failures not shown inline (2)
GitHub Actions: AIQ CI / Script Validation: refactor(clarifier): remove plan approval; keep context + output-type…
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 / 0_Script Validation.txt: refactor(clarifier): remove plan approval; keep context + output-type…
Conclusion: failure
Current runner version: '2.335.1'
##[group]Runner Image Provisioner
Hosted Compute Agent
Version: 20260624.560
Commit: 925d229a51159bc391ae97e54a2dd1fe20af789d
Build Date:
Worker ID: {a66460e0-f107-458b-8b92-6e9e070af46f}
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 (12)
docs/source/**/*
📄 CodeRabbit inference engine (AGENTS.md)
Update the docs under docs/source/ when behavior, configuration, or workflows change
Files:
docs/source/resources/troubleshooting.mddocs/source/customization/index.mddocs/source/architecture/agents/index.mddocs/source/customization/hitl.mddocs/source/resources/faq.mddocs/source/customization/configuration-reference.mddocs/source/examples/full-pipeline-web.mddocs/source/architecture/agents/clarifier.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/resources/troubleshooting.mddocs/source/customization/index.mddocs/source/architecture/agents/index.mdfrontends/ui/src/features/chat/lib/session-activity.spec.tsfrontends/ui/src/features/chat/types.tssrc/aiq_agent/agents/clarifier/prompts/research_clarification.j2frontends/ui/src/features/chat/hooks/use-current-session-busy.spec.tstests/aiq_agent/agents/clarifier/models/test_state.pydocs/source/customization/hitl.mddocs/source/resources/faq.mdsrc/aiq_agent/agents/chat_researcher/agent.pyconfigs/config_web_opensearch.ymldocs/source/customization/configuration-reference.mdfrontends/ui/src/features/chat/components/AgentPrompt.tsxsrc/aiq_agent/agents/clarifier/models/state.pydocs/source/examples/full-pipeline-web.mddocs/source/architecture/agents/clarifier.mdsrc/aiq_agent/agents/clarifier/register.pydocs/notebooks/0_Getting_Started_with_AIQ.ipynbsrc/aiq_agent/agents/clarifier/agent.py
{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/resources/troubleshooting.mddocs/source/customization/index.mddocs/source/architecture/agents/index.mddocs/source/customization/hitl.mddocs/source/resources/faq.mddocs/source/customization/configuration-reference.mddocs/source/examples/full-pipeline-web.mddocs/source/architecture/agents/clarifier.mddocs/notebooks/0_Getting_Started_with_AIQ.ipynb
{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:
.agents/skills/aiq-customize-prompts-models/references/prompt-templates.md.agents/skills/aiq-customize-prompts-models/references/model-selection.md
frontends/ui/**/*.{js,ts,jsx,tsx,vue}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run npm lint, type-check, and build validation for UI changes in frontends/ui
Files:
frontends/ui/src/features/chat/lib/session-activity.spec.tsfrontends/ui/src/features/chat/types.tsfrontends/ui/src/features/chat/hooks/use-current-session-busy.spec.tsfrontends/ui/src/features/chat/components/AgentPrompt.tsx
frontends/ui/**/*.{ts,tsx,jsx,js}
📄 CodeRabbit inference engine (AGENTS.md)
frontends/ui/**/*.{ts,tsx,jsx,js}: The UI is built with Next.js / React / TypeScript / Tailwind with KUI components; reuse existing KUI components and visual patterns rather than introducing new ones
Validate UI-affecting changes with npm run lint, npm run type-check, and npm run test:ci, and include a screenshot for visible changes
Files:
frontends/ui/src/features/chat/lib/session-activity.spec.tsfrontends/ui/src/features/chat/types.tsfrontends/ui/src/features/chat/hooks/use-current-session-busy.spec.tsfrontends/ui/src/features/chat/components/AgentPrompt.tsx
frontends/ui/**/*
⚙️ CodeRabbit configuration file
frontends/ui/**/*: Review UI changes for strict TypeScript behavior, API contract alignment, auth/session handling, accessible controls,
resilient loading and error states, and report/chat state consistency. Prefer existing UI patterns and require tests
for changed user-visible workflows.
Files:
frontends/ui/src/features/chat/lib/session-activity.spec.tsfrontends/ui/src/features/chat/types.tsfrontends/ui/src/features/chat/hooks/use-current-session-busy.spec.tsfrontends/ui/src/features/chat/components/AgentPrompt.tsx
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/clarifier/prompts/research_clarification.j2src/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/clarifier/agent.py
**/*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run ruff check and ruff format validation for Python code changes
**/*.py: Python code must be linted and formatted with Ruff using line length 120, target Python 3.11, rule sets E,F,W,I,PL,UP, and isort force-single-line configuration
Never commit secrets, tokens, or environment-specific hostnames; use environment variables and SecretStr instead, resolving API keys at runtime
Never print or log secret values, including in tool output or error messages
Missing-secret paths must degrade gracefully (stub/skip), not crash or leak
Do not hand-reformat unrelated code when making changes; match the existing import and formatting style
Files:
tests/aiq_agent/agents/clarifier/models/test_state.pysrc/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/clarifier/agent.py
**/*test*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run pytest for all behavior changes in Python code
Files:
tests/aiq_agent/agents/clarifier/models/test_state.py
src/aiq_agent/**/*.py
📄 CodeRabbit inference engine (AGENTS.md)
src/aiq_agent/**/*.py: Respect authenticated data sources by honoring requires_auth, per-user token pass-through, and backend token validators; apply owner guardrails before loading protected report or artifact context into an agent
Do not weaken or bypass AuthMiddleware, validators, or auth gating without a prior design discussion
Files:
src/aiq_agent/agents/chat_researcher/agent.pysrc/aiq_agent/agents/clarifier/models/state.pysrc/aiq_agent/agents/clarifier/register.pysrc/aiq_agent/agents/clarifier/agent.py
{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:
configs/config_web_opensearch.yml
🪛 LanguageTool
docs/source/customization/hitl.md
[style] ~7-~7: Consider a different adjective to strengthen your wording.
Context: ...-Loop (HITL) The clarifier runs before deep research. It gathers context and, when ...
(DEEP_PROFOUND)
[style] ~13-~13: Consider a different adjective to strengthen your wording.
Context: ... Entirely No clarification step before deep research: ```yaml workflow: _type: c...
(DEEP_PROFOUND)
🔇 Additional comments (23)
frontends/ui/src/features/chat/types.ts (1)
64-64: LGTM!frontends/ui/src/features/chat/components/AgentPrompt.tsx (2)
9-21: LGTM!
22-54: 🎯 Functional CorrectnessNo issue:
approvalprompts still route through the main response input.> Likely an incorrect or invalid review comment.frontends/ui/src/features/chat/hooks/use-current-session-busy.spec.ts (1)
156-194: LGTM!Fixtures use only
pendingInteraction !== nullsemantics per the linked hook, so swapping thetypevalue doesn't affect assertion validity.frontends/ui/src/features/chat/lib/session-activity.spec.ts (1)
247-260: LGTM!src/aiq_agent/agents/clarifier/models/state.py (1)
32-35: LGTM!Also applies to: 38-50, 52-61
tests/aiq_agent/agents/clarifier/models/test_state.py (1)
122-133: LGTM!src/aiq_agent/agents/clarifier/agent.py (1)
109-112: LGTM!Also applies to: 141-146, 156-161, 169-173, 177-193, 405-406, 497-502, 512-517, 529-536
src/aiq_agent/agents/chat_researcher/agent.py (1)
184-190: LGTM!src/aiq_agent/agents/clarifier/register.py (1)
70-74: LGTM!Also applies to: 83-90, 121-124, 170-178, 181-190, 191-203, 209-214
src/aiq_agent/agents/clarifier/prompts/research_clarification.j2 (1)
81-81: LGTM!Also applies to: 115-120
configs/config_web_opensearch.yml (1)
148-155: LGTM!docs/source/examples/full-pipeline-web.md (1)
8-8: LGTM!Also applies to: 186-186
.agents/skills/aiq-customize-prompts-models/references/prompt-templates.md (1)
19-20: LGTM!docs/source/customization/index.md (1)
21-21: LGTM!docs/source/resources/faq.md (1)
33-35: LGTM!docs/source/resources/troubleshooting.md (1)
37-37: LGTM!.agents/skills/aiq-customize-prompts-models/references/model-selection.md (1)
49-51: LGTM!docs/notebooks/0_Getting_Started_with_AIQ.ipynb (1)
394-394: LGTM!Also applies to: 625-625
docs/source/architecture/agents/clarifier.md (1)
9-10: LGTM!Also applies to: 19-21, 49-53, 61-67, 72-79, 95-97, 105-110, 118-121, 134-139
docs/source/architecture/agents/index.md (1)
13-13: LGTM!docs/source/customization/configuration-reference.md (1)
472-474: LGTM!Also applies to: 509-509
docs/source/customization/hitl.md (1)
7-13: LGTM!Also applies to: 22-30
97732da to
3602a96
Compare
… clarification The clarifier's plan preview/approval step forced coming up with a plan. The deep-research writer skills already determine the output shape, so that step is redundant. Remove the clarifier plan-approval feature: planner_llm, enable_plan_approval, max_plan_iterations, the plan_preview node, plan_* state and result fields, get_approved_plan_context, plan_generation.j2, and the approve/reject handling. The clarifier now only gathers context and, when the request is vague, optionally clarifies the type of output requested. Update chat_researcher (drop plan-rejected/approved handling), configs, tests, and docs accordingly. The deep-research planner-agent is intentionally left unchanged. Signed-off-by: Ashan Panduwawala <apanduwawala@nvidia.com>
3602a96 to
dbf516e
Compare
3 participants
What & why
The deep-research writer already picks the final output shape (report, table, comparison, prediction, brief answer) via its synthesis skills. That made the clarifier's plan preview/approval step — where it generated a plan and asked the user to approve/reject it before research — redundant. This PR removes that step.
The clarifier now only gathers context and, when the request is vague, optionally clarifies the type of output requested. Everything else about it (asking scope questions, escalation) is unchanged.
Scope
Only the clarifier's plan-approval is removed. The separate deep-research
planner-agent(which plans the actual research queries) is intentionally left unchanged.What changed
clarifier/agent.py,register.py,models/state.py,research_clarification.j2): removedplanner_llm,enable_plan_approval,max_plan_iterations, theplan_previewnode,plan_*state/result fields,get_approved_plan_context,plan_generation.j2, and the approve/reject handling; added optional output-type clarification.planner_llm/enable_plan_approval(thedeep_research_agent.planner_llmis untouched).APPROVAL_PROMPT_REApprove/Reject buttons (the backend no longer emits that prompt string) and the unused'plan_approval'PromptType. The live'approval'binary-prompt type is kept.Validation
uv run pytest(clarifier / chat_researcher / deep_researcher / jobs) — passinguv run ruff check/ruff format --check— cleantsc --noEmitclean, eslint clean, affected vitest specs passing🤖 Generated with Claude Code