From 8f9f4370752222cf23c7471ef60882a485cf60fb Mon Sep 17 00:00:00 2001 From: Ajay Thorve Date: Wed, 15 Jul 2026 12:58:28 -0700 Subject: [PATCH 1/3] fix docs release version and coverage Signed-off-by: Ajay Thorve --- .secrets.baseline | 4 +- CHANGELOG.md | 10 +- README.md | 17 ++- ci/markdown-link-check-config.json | 3 + docs/README.md | 13 ++ docs/source/conf.py | 18 ++- .../customization/configuration-reference.md | 6 +- docs/source/customization/index.md | 3 +- .../source/customization/tools-and-sources.md | 7 ++ docs/source/customization/you-com.md | 114 ++++++++++++++++++ docs/source/index.md | 1 + docs/source/project.json | 2 +- docs/source/resources/faq.md | 2 + docs/source/resources/troubleshooting.md | 3 +- docs/source/versions1.json | 6 - 15 files changed, 186 insertions(+), 23 deletions(-) create mode 100644 docs/source/customization/you-com.md delete mode 100644 docs/source/versions1.json diff --git a/.secrets.baseline b/.secrets.baseline index 4d61ca811..a564ade05 100644 --- a/.secrets.baseline +++ b/.secrets.baseline @@ -133,7 +133,7 @@ "filename": "README.md", "hashed_secret": "73140b88094aaf220a03532196b27b58a03c9b09", "is_verified": false, - "line_number": 373 + "line_number": 384 } ], "deploy/.env.example": [ @@ -355,5 +355,5 @@ } ] }, - "generated_at": "2026-07-15T20:43:32Z" + "generated_at": "2026-07-15T21:41:56Z" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 74d83186e..e5e791408 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ Unreleased changes targeting AI-Q v2.2.0 -These entries track candidate work merged to `develop`. AI-Q `v2.1.0` remains the latest stable +These entries track candidate work on `release/2.2`. AI-Q `v2.1.0` remains the latest stable release; the candidate will be stabilized before the final `v2.2.0` release. **Research and reports** @@ -14,8 +14,12 @@ release; the candidate will be stabilized before the final `v2.2.0` release. **Sources and integrations** - OpenSearch is a first-class knowledge backend for self-hosted, Amazon OpenSearch Service, and Amazon OpenSearch Serverless deployments +- Azure AI Search is a managed knowledge backend with API-key or Azure identity authentication, namespaced index ownership, and hybrid retrieval - Paper search adds SerpAPI and SearchAPI providers alongside Serper; the routed-research profile adds DuckDuckGo news and Polymarket sources +- You.com adds configurable web search, page-content extraction, cited open-domain research, and finance-focused research tools +- Nimble adds configurable web search with lite and deep modes, plus an Enterprise-only fast mode and optional focus, country, and locale controls - Per-user MCP OAuth adds status, connect, callback, and reconnect flows backed by a token store shared by the API and workers; disconnect and in-worker token refresh are not included +- A standalone public MCP server exposes stateless submit, poll, and final-report tools over Streamable HTTP with PostgreSQL-backed job state **Sandboxes, artifacts, and policy** @@ -33,12 +37,12 @@ release; the candidate will be stabilized before the final `v2.2.0` release. **Agent Skills, UX, and developer workflow** -- Consumer Agent Skills now include `aiq-deploy` and `aiq-research`; maintainer skills cover data sources, tools, release QA, PR preparation, prompt/model customization, and CI maintenance +- Consumer Agent Skills now include `aiq-deploy` and `aiq-research`; maintainer skills cover workflow configuration, data sources, tools, release QA, PR preparation, prompt/model customization, and CI maintenance - The UI surfaces batched researcher activity and improves research-session recovery, expiry handling, and WebSocket delivery reliability - Contributor governance and product-level Agent Skill evaluation checks expand release and contribution tooling - Pinned to NeMo Agent Toolkit (NAT) v1.8.0 -The nine checked-in workflow configurations are focused profiles; no single profile enables every 2.2 capability. +The eleven checked-in workflow configurations are focused profiles; no single profile enables every 2.2 capability. Release v2.1.0 diff --git a/README.md b/README.md index 86257460e..effd96368 100644 --- a/README.md +++ b/README.md @@ -69,8 +69,8 @@ The NVIDIA AI-Q Blueprint is an enterprise-grade research agent built on the [NV - **Skills, sandbox execution, and durable outputs** — Built-in research/synthesis skills run code through a provider-neutral sandbox contract. Modal is fresh per job; the experimental OpenShell profile uses one shared, pre-provisioned sandbox and is not a multi-tenant isolation boundary. Opt-in rich-file capture checkpoints manifest-declared files after successful sandbox commands, finalizes on success/failure, stores bytes in SQL or S3-compatible storage, and delivers metadata to the Files tab live and on replay. - **Portable Agent Skills** — `aiq-deploy` selects, starts, and validates an AI-Q deployment; `aiq-research` calls routed chat and async research from compatible coding harnesses. - **Data source registry** — UI toggles and request payloads can select web, paper, enterprise, collaboration, and knowledge-layer sources per message. -- **Expanded sources** — Paper search supports Serper, SerpAPI, and SearchAPI; focused profiles demonstrate DuckDuckGo news, Polymarket, and OpenSearch knowledge retrieval. -- **Production API and auth** — REST endpoints, async job ownership, per-user OAuth-protected MCP sources, token validator entry points, and provider lifecycle hooks support authenticated deployments. +- **Expanded sources** — Paper search supports Serper, SerpAPI, and SearchAPI; You.com adds web, contents, general-research, and finance-research tools; Nimble adds configurable web search; focused profiles demonstrate DuckDuckGo news, Polymarket, OpenSearch, and Azure AI Search knowledge retrieval. +- **Production API and auth** — REST endpoints, async job ownership, per-user OAuth-protected MCP sources, token validator entry points, and provider lifecycle hooks support authenticated deployments; a separate public MCP server exposes stateless research tools for trusted networks. - **Opt-in policy controls** — NeMo Guardrails middleware covers selected workflow and agent boundaries, and narrow application-level encryption can protect final async output plus selected artifact-event content. - **Observability, profiling, and cost analysis** — NAT-exported async traces preserve task, named-agent, and model/tool hierarchy across concurrent researchers. Tokenomics reports combine profiler traces with pricing configuration for cost, latency, and cache analysis. - **Evaluation harnesses** — Built-in benchmarks (for example, FreshQA, DeepResearch) and evaluation scripts to measure quality and iterate on prompts and agent architecture. @@ -90,7 +90,8 @@ Recent changes include: the new `aiq-deploy` skill, expanded `aiq-research` workflows, opt-in artifact capture, SQL or S3-compatible storage, and live or replayed Files-tab access turn generated files into durable outputs. -- **Enterprise data and policy controls** — OpenSearch joins the knowledge backends; per-user MCP +- **Sources, integrations, and policy controls** — OpenSearch and Azure AI Search join the knowledge backends; + You.com adds four search and research tools, Nimble adds configurable web search, and the standalone public MCP server exposes submit/poll/report operations; per-user MCP OAuth, opt-in NeMo Guardrails middleware, and narrowly scoped async-content encryption add deployment controls without making them universal defaults. - **Operations and user experience** — Async traces preserve the agent hierarchy, the source Helm @@ -212,6 +213,8 @@ uv pip install -e ./frontends/benchmarks/freshqa # Install data sources (pick what you need) uv pip install -e ./sources/tavily_web_search uv pip install -e ./sources/google_scholar_paper_search +uv pip install -e ./sources/nimble_web_search +uv pip install -e ./sources/you_com uv pip install -e "./sources/knowledge_layer[llamaindex,foundational_rag]" ``` @@ -222,6 +225,8 @@ uv pip install -e "./sources/knowledge_layer[llamaindex,foundational_rag]" | ---------- | -------------------- | ------------------------- | ----------------------------------------------------------- | | NVIDIA API | `NVIDIA_API_KEY` | LLM inference through NIM | Yes | | Tavily | `TAVILY_API_KEY` | Web search | No (if not specified, agent continues without web search) | +| Nimble | `NIMBLE_API_KEY` | Configurable web search | No (required only when Nimble search is configured) | +| You.com | `YDC_API_KEY` | Web, contents, and research APIs | No (required only when You.com tools are configured) | | Serper | `SERPER_API_KEY` | Academic paper search | No (if not specified, agent continues without paper search) | @@ -236,6 +241,11 @@ uv pip install -e "./sources/knowledge_layer[llamaindex,foundational_rag]" 2. Navigate to your dashboard 3. Generate an API key +#### Obtain a You.com API Key + +Follow the [You.com quickstart](https://you.com/docs/quickstart) to create an API key and add it to `deploy/.env` as +`YDC_API_KEY`. Refer to [You.com API Suite](docs/source/customization/you-com.md) for tool configuration. + #### Obtain a Paper Search API Key Paper search supports three interchangeable providers. Set the `provider` field on the `paper_search` function in your workflow config (defaults to `serper`): @@ -270,6 +280,7 @@ The `configs/` directory holds YAML workflow configs that define agents, tools, | `config_web_default_llamaindex.yml` | Nemotron 3 Super; Nemotron Mini summary | Default web/API chat pipeline with LlamaIndex/ChromaDB and Tavily. Paper search is commented out. | | `config_web_frag.yml` | Nemotron 3 Super | Web/API and Helm base with Foundational RAG plus Tavily. Requires separately deployed RAG query and ingestion services. | | `config_web_opensearch.yml` | Nemotron 3 Super; NVIDIA embedding model | Web/API with built-in OpenSearch knowledge retrieval plus Tavily; supports self-hosted, `es`, and `aoss` authentication modes. | +| `config_web_azure_ai_search.yml` | Nemotron 3 Super; NVIDIA embedding model | Web/API with Azure AI Search knowledge retrieval plus Tavily; supports API-key and Azure identity authentication. | | `config_frontier_models.yml` | GPT-5.2; Nemotron 3 Super; Nemotron Mini summary | LlamaIndex profile using GPT-5.2 for orchestration/planning/writing and Nemotron Super for routing/research. Requires `OPENAI_API_KEY`. | | `config_web_default_guardrails.yml` | GPT-OSS-120B; Nemotron 3 Super; Nemotron Mini summary | LlamaIndex profile with workflow Guardrails attached and async deep-agent Guardrails selected; shallow middleware is defined but not attached. | | `config_web_frag_mcp_auth.yml` | Nemotron 3 Super | Foundational RAG plus an opt-in protected per-user OAuth MCP source example. Requires a real MCP endpoint and shared token store. | diff --git a/ci/markdown-link-check-config.json b/ci/markdown-link-check-config.json index 500699897..35c6eed54 100644 --- a/ci/markdown-link-check-config.json +++ b/ci/markdown-link-check-config.json @@ -24,6 +24,9 @@ { "pattern": "^https?://modal\\.com/docs/reference/modal\\.config$" }, + { + "pattern": "^https://(?:www\\.|docs\\.)?nimbleway\\.com(?:/.*)?$" + }, { "pattern": "^https?://huggingface\\.co/spaces/muset-ai/DeepResearch-Bench-Leaderboard$" } diff --git a/docs/README.md b/docs/README.md index 4ca14f93b..5cc05be79 100644 --- a/docs/README.md +++ b/docs/README.md @@ -25,3 +25,16 @@ python -m http.server --directory docs/build/html 8080 ```bash make -C docs linkcheck ``` + +## Release Metadata + +[`source/project.json`](source/project.json) is the single source of truth for the published documentation version. +The Sphinx configuration reads its `name` and `version` fields, and the NVIDIA Docs publisher uses the same file to +select the deployment directory. + +Use the exact release artifact version, without a leading `v`. For example, the `v2.2.0-rc1` Git tag uses +`2.2.0-rc1`. Update only `source/project.json` when advancing the documentation version. + +The version switcher reads the publisher-managed index at +`https://docs.nvidia.com/aiq-blueprint/versions1.json`. Do not add a per-build `versions1.json`; a copied index becomes +stale and relative switcher URLs resolve differently on top-level and nested pages. diff --git a/docs/source/conf.py b/docs/source/conf.py index 0444c8535..7ffe5acef 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,10 +1,17 @@ # SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 -project = "NVIDIA AI-Q Blueprint" +import json +from pathlib import Path + +_DOCS_SOURCE_DIR = Path(__file__).resolve().parent +_PROJECT_METADATA = json.loads((_DOCS_SOURCE_DIR / "project.json").read_text(encoding="utf-8")) +_PUBLISHED_DOCS_URL = "https://docs.nvidia.com/aiq-blueprint" + +project = _PROJECT_METADATA["name"] copyright = "2025-%Y, NVIDIA Corporation" author = "NVIDIA Corporation" -release = "1.2.1" +release = _PROJECT_METADATA["version"] # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration @@ -48,7 +55,7 @@ html_theme = "nvidia_sphinx_theme" html_theme_options = { - "switcher": {"json_url": "../versions1.json", "version_match": release}, + "switcher": {"json_url": f"{_PUBLISHED_DOCS_URL}/versions1.json", "version_match": release}, "public_docs_features": True, "icon_links": [ { @@ -62,7 +69,7 @@ "show_nav_level": 1, } -html_extra_path = ["project.json", "versions1.json"] +html_extra_path = ["project.json"] html_static_path = ["_static"] html_favicon = "_static/favicon.ico" html_css_files = ["css/custom.css"] @@ -78,4 +85,7 @@ r"http://127\.0\.0\.1.*", r".*github\.com.*", r".*githubusercontent\.com.*", + # Nimble's certificate chain is not accepted by Python/OpenSSL linkcheck, + # although the official site and docs remain browser-accessible. + r"https://(?:www\.|docs\.)?nimbleway\.com.*", ] diff --git a/docs/source/customization/configuration-reference.md b/docs/source/customization/configuration-reference.md index cee0c5ffb..ff23599aa 100644 --- a/docs/source/customization/configuration-reference.md +++ b/docs/source/customization/configuration-reference.md @@ -204,7 +204,8 @@ functions: ### `nimble_web_search` -Web search powered by the [Nimble API](https://nimbleway.com/) via `langchain-nimble`. +Web search powered by the [Nimble Search API](https://docs.nimbleway.com/nimble-sdk/web-tools/search) via +`langchain-nimble`. ```yaml functions: @@ -636,7 +637,7 @@ workflow: ## Provided Config Files -The repository includes nine top-level workflow configurations. They are focused reference profiles, not cumulative +The repository includes eleven top-level workflow configurations. They are focused reference profiles, not cumulative layers, and no single profile enables every capability. Start from the profile closest to the deployment and merge only the additional sections you need. @@ -652,6 +653,7 @@ only the additional sections you need. | `configs/config_web_frag_mcp_auth.yml` | Web API | Foundational RAG plus a protected per-user OAuth MCP source example. Requires a real protected MCP endpoint and shared token-store configuration; it is not a zero-config default. | | `configs/config_domain_routing_and_skills.yml` | Direct deep-research workflow | Automatic domain routing, Tavily, DuckDuckGo news, Polymarket, LlamaIndex, enabled Serper paper search, built-in skills, and a Modal sandbox. Requires the corresponding service credentials and Modal setup. | | `configs/config_openshell.yml` | Web API, experimental | Skills and artifact capture over one pre-provisioned named OpenShell sandbox. Intended for trusted single-operator use; per-job directories are not multi-tenant isolation. | +| `configs/config_mcp.yml` | Standalone MCP server | Public NIM and Tavily research over stateless submit, poll, and final-report tools with PostgreSQL-backed job state. Requires `NVIDIA_API_KEY`, `TAVILY_API_KEY`, and `AIQ_CHECKPOINT_DB`. | ## Related diff --git a/docs/source/customization/index.md b/docs/source/customization/index.md index 511c3056e..48209704e 100644 --- a/docs/source/customization/index.md +++ b/docs/source/customization/index.md @@ -14,8 +14,9 @@ SPDX-License-Identifier: Apache-2.0 - **[Configuration Reference](./configuration-reference.md)** — Complete YAML schema with all parameters - **[Swapping Models](./swapping-models.md)** — Use different LLMs (hosted NIM, self-hosted NIM, mixing models) - **[Tools and Sources](./tools-and-sources.md)** — Enable, disable, and configure search tools +- **[You.com API Suite](./you-com.md)** — Configure web search, contents extraction, general research, and finance research - **[MCP Tools](./mcp-tools.md)** — Add external tools through Model Context Protocol - **[Guardrails](./guardrails.md)** — Configure NeMo Guardrails at workflow and agent boundaries -- **[Knowledge Layer](./knowledge-layer.md)** — Add document retrieval with LlamaIndex, Foundational RAG, or OpenSearch +- **[Knowledge Layer](./knowledge-layer.md)** — Add document retrieval with LlamaIndex, Foundational RAG, OpenSearch, or Azure AI Search - **[Prompts](./prompts.md)** — Modify agent behavior through Jinja2 prompt templates - **[Human-in-the-Loop](./hitl.md)** — Configure the clarifier diff --git a/docs/source/customization/tools-and-sources.md b/docs/source/customization/tools-and-sources.md index 2efd4713c..e0412b604 100644 --- a/docs/source/customization/tools-and-sources.md +++ b/docs/source/customization/tools-and-sources.md @@ -4,6 +4,13 @@ SPDX-License-Identifier: Apache-2.0 --> # Tools and Sources +AI-Q ships provider integrations for Tavily, Google Scholar search providers, Exa, DuckDuckGo News, Polymarket, and +the [You.com API Suite](./you-com.md). Knowledge retrieval is configured separately through the +[Knowledge Layer](./knowledge-layer.md). + +Nimble provides configurable web search with lite and deep modes, plus an Enterprise-only fast mode. Refer to the +[configuration reference](./configuration-reference.md) for its focus, country, and locale controls. + ## Data Source Registry The `data_source_registry` function is the **single source of truth** for which tools exist and which data source they belong to. It controls the UI toggles, per-message filtering, and -- by default -- which tools each agent receives. diff --git a/docs/source/customization/you-com.md b/docs/source/customization/you-com.md new file mode 100644 index 000000000..61fd2003e --- /dev/null +++ b/docs/source/customization/you-com.md @@ -0,0 +1,114 @@ + + +# You.com API Suite + +AI-Q includes four NeMo Agent Toolkit functions backed by the You.com API. They can be enabled independently or +grouped into one entry in the [data source registry](./tools-and-sources.md#data-source-registry). + +| Function type | Purpose | +|---|---| +| `you_web_search` | Return LLM-ready web results with optional live-crawled content, freshness filters, and news results. | +| `you_contents` | Extract Markdown, HTML, or metadata from up to 10 URLs. | +| `you_research` | Run multi-search, cited open-domain research with a configurable effort level. | +| `you_finance_research` | Run cited research over finance-focused sources such as filings, earnings, and market data. | + +## Prerequisites + +The standard `./scripts/setup.sh` flow installs the `sources/you_com` plugin. For an existing environment, install it +directly: + +```bash +uv pip install -e ./sources/you_com +``` + +Create a key using the [You.com API quickstart](https://you.com/docs/quickstart), then add it to `deploy/.env`: + +```text +YDC_API_KEY= +``` + +Do not commit `deploy/.env`. Each function also accepts an `api_key` field, but the environment variable keeps the +secret out of workflow YAML. + +## Configure the Tools + +Add only the functions your workflow needs. The following example registers all four under one user-selectable data +source: + +```yaml +functions: + you_web_search: + _type: you_web_search + max_results: 10 + safesearch: moderate + livecrawl_mode: web + livecrawl_format: markdown + freshness: off + include_news_results: false + + you_contents: + _type: you_contents + formats: [markdown, metadata] + crawl_timeout: 30 + + you_research: + _type: you_research + research_effort: standard + + you_finance_research: + _type: you_finance_research + research_effort: deep + + data_sources: + _type: data_source_registry + sources: + - id: you_com + name: You.com + description: Web search, content extraction, and cited research. + tools: + - you_web_search + - you_contents + - you_research + - you_finance_research +``` + +Agents with no explicit `tools` list inherit these functions from the registry. Request clients can then select the +source with `data_sources: ["you_com"]`. Refer to [Tools and Sources](./tools-and-sources.md) for filtering and +per-agent specialization. + +## Configuration Reference + +All four functions accept these shared fields: + +| Field | Default | Description | +|---|---|---| +| `api_key` | `null` | Optional inline API key. Prefer `YDC_API_KEY`. | +| `max_retries` | `3` | Maximum attempts for a failed request. | +| `timeout` | `null` | Per-attempt timeout in seconds. `null` uses the provider default. | + +`you_web_search` also accepts: + +| Field | Default | Allowed values or behavior | +|---|---|---| +| `max_results` | `10` | 1–100 results. | +| `safesearch` | `moderate` | `off`, `moderate`, or `strict`. | +| `livecrawl_mode` | `web` | `off`, `web`, `news`, or `all`. | +| `livecrawl_format` | `markdown` | `off`, `markdown`, or `html`. | +| `freshness` | `off` | `off`, `day`, `week`, `month`, or `year`. | +| `max_content_length` | `50000` | Maximum live-crawled characters per result; `null` is unbounded. | +| `include_news_results` | `false` | Include results classified as news. | + +Research and contents functions accept these fields: + +| Function | Field | Default | Allowed values or behavior | +|---|---|---|---| +| `you_research` | `research_effort` | `standard` | `lite`, `standard`, `deep`, or `exhaustive`. | +| `you_finance_research` | `research_effort` | `deep` | `deep` or `exhaustive`. | +| `you_contents` | `formats` | `[markdown, metadata]` | Any combination of `markdown`, `html`, and `metadata`. | +| `you_contents` | `crawl_timeout` | `null` | Per-URL crawl timeout from 1 to 60 seconds. | + +When `YDC_API_KEY` and `api_key` are both absent, AI-Q still starts and registers diagnostic stubs for the configured +functions. Calls return an actionable missing-key error instead of failing workflow initialization. diff --git a/docs/source/index.md b/docs/source/index.md index dc4f741dc..d6c9ce3dc 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -51,6 +51,7 @@ Overview <./customization/index.md> Configuration Reference <./customization/configuration-reference.md> Swapping Models <./customization/swapping-models.md> Tools and Sources <./customization/tools-and-sources.md> +You.com API Suite <./customization/you-com.md> MCP Tools <./customization/mcp-tools.md> Guardrails <./customization/guardrails.md> Knowledge Layer <./customization/knowledge-layer.md> diff --git a/docs/source/project.json b/docs/source/project.json index c62013bb1..da158a78a 100644 --- a/docs/source/project.json +++ b/docs/source/project.json @@ -1,4 +1,4 @@ { "name": "NVIDIA AI-Q Blueprint", - "version": "1.2.1" + "version": "2.2.0-rc1" } diff --git a/docs/source/resources/faq.md b/docs/source/resources/faq.md index 0051eec1f..13c55a269 100644 --- a/docs/source/resources/faq.md +++ b/docs/source/resources/faq.md @@ -60,6 +60,7 @@ prompted to follow the recorded order. **What search tools are available?** - **Tavily Web Search** — General web search (requires `TAVILY_API_KEY`) +- **You.com APIs** — Web search, page contents, cited general research, and finance research (requires `YDC_API_KEY`) - **Exa Web Search** — General web search via Exa (requires `EXA_API_KEY`) - **Nimble Web Search** — General web search via Nimble (requires `NIMBLE_API_KEY`) - **DuckDuckGo News Search** — Recent news search (no API key) @@ -81,6 +82,7 @@ Yes. Refer to [Adding a Tool](../extending/adding-a-tool.md) for an end-to-end g - **Foundational RAG** for production — connects to NVIDIA RAG Blueprint, supports multi-user with Milvus - **OpenSearch** for an existing OpenSearch deployment or AWS-managed vector retrieval — supports self-hosted/basic auth, Amazon OpenSearch Service, and Amazon OpenSearch Serverless with SigV4 +- **Azure AI Search** for managed hybrid retrieval — supports API-key authentication or Azure managed identity Refer to [Knowledge Layer](../customization/knowledge-layer.md). For AOSS on EKS, use the [Amazon OpenSearch Serverless guide](../deployment/aws-opensearch-serverless.md). diff --git a/docs/source/resources/troubleshooting.md b/docs/source/resources/troubleshooting.md index f898eaa73..1398e31b6 100644 --- a/docs/source/resources/troubleshooting.md +++ b/docs/source/resources/troubleshooting.md @@ -24,8 +24,9 @@ Common issues and solutions for the AI-Q blueprint. | `[404] Not found for account` | Invalid or expired NVIDIA API key | Regenerate key at [build.nvidia.com](https://build.nvidia.com) | | `Gateway timeout (504)` | Model endpoint overloaded or unavailable | Retry, or switch to a different model in config | | Tavily search returns empty | Invalid `TAVILY_API_KEY` | Verify key at [tavily.com](https://tavily.com) | +| You.com tools return an unavailable or 401 error | Missing or invalid `YDC_API_KEY` | Create or verify the key using the [You.com quickstart](https://you.com/docs/quickstart) and restart AI-Q | | Exa search returns empty or 401 | Invalid or missing `EXA_API_KEY` | Verify key at [exa.ai](https://exa.ai) | -| Nimble search returns empty or 401 | Invalid or missing `NIMBLE_API_KEY` | Verify key at [nimbleway.com](https://nimbleway.com) | +| Nimble search returns empty or 401 | Invalid or missing `NIMBLE_API_KEY` | Verify the key using the [Nimble quickstart](https://docs.nimbleway.com/nimble-sdk/getting-started/quickstart) | | Nimble search returns 403 with "enterprise" | `search_depth: fast` requires an Enterprise plan | Switch to `search_depth: lite` (default) or `deep`, or upgrade your Nimble plan | | Serper search fails | Missing `SERPER_API_KEY` | Set key or remove `paper_search_tool` from config | diff --git a/docs/source/versions1.json b/docs/source/versions1.json deleted file mode 100644 index 06f4dcadd..000000000 --- a/docs/source/versions1.json +++ /dev/null @@ -1,6 +0,0 @@ -[ - { - "version": "1.2.1", - "url": "https://docs.nvidia.com/ai-blueprint/1.2.1/" - } -] From 07fc6c2aca8ef2334e24321bface0b0984359751 Mon Sep 17 00:00:00 2001 From: Ajay Thorve Date: Wed, 15 Jul 2026 14:54:47 -0700 Subject: [PATCH 2/3] docs: address release documentation review Signed-off-by: Ajay Thorve --- ci/markdown-link-check-config.json | 8 +++++++- docs/source/conf.py | 8 +++++--- docs/source/customization/you-com.md | 2 +- docs/source/resources/faq.md | 3 ++- 4 files changed, 15 insertions(+), 6 deletions(-) diff --git a/ci/markdown-link-check-config.json b/ci/markdown-link-check-config.json index 35c6eed54..20e12822b 100644 --- a/ci/markdown-link-check-config.json +++ b/ci/markdown-link-check-config.json @@ -25,7 +25,13 @@ "pattern": "^https?://modal\\.com/docs/reference/modal\\.config$" }, { - "pattern": "^https://(?:www\\.|docs\\.)?nimbleway\\.com(?:/.*)?$" + "pattern": "^https://nimbleway\\.com/?$" + }, + { + "pattern": "^https://docs\\.nimbleway\\.com/nimble-sdk/getting-started/quickstart/?$" + }, + { + "pattern": "^https://docs\\.nimbleway\\.com/nimble-sdk/web-tools/search/?$" }, { "pattern": "^https?://huggingface\\.co/spaces/muset-ai/DeepResearch-Bench-Leaderboard$" diff --git a/docs/source/conf.py b/docs/source/conf.py index 7ffe5acef..0839436aa 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -85,7 +85,9 @@ r"http://127\.0\.0\.1.*", r".*github\.com.*", r".*githubusercontent\.com.*", - # Nimble's certificate chain is not accepted by Python/OpenSSL linkcheck, - # although the official site and docs remain browser-accessible. - r"https://(?:www\.|docs\.)?nimbleway\.com.*", + # These specific Nimble URLs have a certificate chain that Python/OpenSSL + # linkcheck cannot validate, although they remain browser-accessible. + r"^https://nimbleway\.com/?$", + r"^https://docs\.nimbleway\.com/nimble-sdk/getting-started/quickstart/?$", + r"^https://docs\.nimbleway\.com/nimble-sdk/web-tools/search/?$", ] diff --git a/docs/source/customization/you-com.md b/docs/source/customization/you-com.md index 61fd2003e..f9b034bd1 100644 --- a/docs/source/customization/you-com.md +++ b/docs/source/customization/you-com.md @@ -87,7 +87,7 @@ All four functions accept these shared fields: |---|---|---| | `api_key` | `null` | Optional inline API key. Prefer `YDC_API_KEY`. | | `max_retries` | `3` | Maximum attempts for a failed request. | -| `timeout` | `null` | Per-attempt timeout in seconds. `null` uses the provider default. | +| `timeout` | `null` | Per-attempt timeout in seconds. `null` disables the timeout. | `you_web_search` also accepts: diff --git a/docs/source/resources/faq.md b/docs/source/resources/faq.md index 13c55a269..28e6948d8 100644 --- a/docs/source/resources/faq.md +++ b/docs/source/resources/faq.md @@ -60,7 +60,8 @@ prompted to follow the recorded order. **What search tools are available?** - **Tavily Web Search** — General web search (requires `TAVILY_API_KEY`) -- **You.com APIs** — Web search, page contents, cited general research, and finance research (requires `YDC_API_KEY`) +- **You.com APIs** — Web search, page contents, cited general research, and finance research (`YDC_API_KEY` is + required for live API calls; without it, AI-Q starts with diagnostic stubs for these tools) - **Exa Web Search** — General web search via Exa (requires `EXA_API_KEY`) - **Nimble Web Search** — General web search via Nimble (requires `NIMBLE_API_KEY`) - **DuckDuckGo News Search** — Recent news search (no API key) From 973203a8f23a4968f2a94ad3698b6e3f42a58654 Mon Sep 17 00:00:00 2001 From: Ajay Thorve Date: Wed, 15 Jul 2026 14:56:30 -0700 Subject: [PATCH 3/3] docs: align Nimble troubleshooting link Signed-off-by: Ajay Thorve --- ci/markdown-link-check-config.json | 3 --- docs/source/conf.py | 1 - docs/source/resources/troubleshooting.md | 2 +- 3 files changed, 1 insertion(+), 5 deletions(-) diff --git a/ci/markdown-link-check-config.json b/ci/markdown-link-check-config.json index 20e12822b..425125fbc 100644 --- a/ci/markdown-link-check-config.json +++ b/ci/markdown-link-check-config.json @@ -27,9 +27,6 @@ { "pattern": "^https://nimbleway\\.com/?$" }, - { - "pattern": "^https://docs\\.nimbleway\\.com/nimble-sdk/getting-started/quickstart/?$" - }, { "pattern": "^https://docs\\.nimbleway\\.com/nimble-sdk/web-tools/search/?$" }, diff --git a/docs/source/conf.py b/docs/source/conf.py index 0839436aa..554aeeec2 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -88,6 +88,5 @@ # These specific Nimble URLs have a certificate chain that Python/OpenSSL # linkcheck cannot validate, although they remain browser-accessible. r"^https://nimbleway\.com/?$", - r"^https://docs\.nimbleway\.com/nimble-sdk/getting-started/quickstart/?$", r"^https://docs\.nimbleway\.com/nimble-sdk/web-tools/search/?$", ] diff --git a/docs/source/resources/troubleshooting.md b/docs/source/resources/troubleshooting.md index 1398e31b6..d25fd06b2 100644 --- a/docs/source/resources/troubleshooting.md +++ b/docs/source/resources/troubleshooting.md @@ -26,7 +26,7 @@ Common issues and solutions for the AI-Q blueprint. | Tavily search returns empty | Invalid `TAVILY_API_KEY` | Verify key at [tavily.com](https://tavily.com) | | You.com tools return an unavailable or 401 error | Missing or invalid `YDC_API_KEY` | Create or verify the key using the [You.com quickstart](https://you.com/docs/quickstart) and restart AI-Q | | Exa search returns empty or 401 | Invalid or missing `EXA_API_KEY` | Verify key at [exa.ai](https://exa.ai) | -| Nimble search returns empty or 401 | Invalid or missing `NIMBLE_API_KEY` | Verify the key using the [Nimble quickstart](https://docs.nimbleway.com/nimble-sdk/getting-started/quickstart) | +| Nimble search returns empty or 401 | Invalid or missing `NIMBLE_API_KEY` | Verify the key through [Nimble](https://nimbleway.com/) | | Nimble search returns 403 with "enterprise" | `search_depth: fast` requires an Enterprise plan | Switch to `search_depth: lite` (default) or `deep`, or upgrade your Nimble plan | | Serper search fails | Missing `SERPER_API_KEY` | Set key or remove `paper_search_tool` from config |