feat(nimble_web_search): optional domain/recency/date filters + output_format + result cap

.secrets.baseline

@@ -142,7 +142,7 @@
         "filename": "deploy/.env.example",
         "hashed_secret": "9d4e1e23bd5b727046a9e3b4b7db57bd8d6ee684",
         "is_verified": false,
-        "line_number": 30
+        "line_number": 32
       }
     ],
     "deploy/compose/README.md": [
@@ -290,5 +290,5 @@
       }
     ]
   },
-  "generated_at": "2026-05-22T20:01:44Z"
+  "generated_at": "2026-06-01T05:45:53Z"
 }

deploy/.env.example

@@ -17,8 +17,10 @@ AIQ_DEV_ENV=cli
 NVIDIA_API_KEY=
 
 
-# Web search (Required)
+# Web search (Required — set at least one of TAVILY_API_KEY, EXA_API_KEY, or NIMBLE_API_KEY)
 TAVILY_API_KEY=
+# EXA_API_KEY=
+# NIMBLE_API_KEY=
 
 # Paper search (Optional)
 # SERPER_API_KEY=   # to enable, set API key and update the relevant config in configs/ directory

deploy/Dockerfile

@@ -77,6 +77,8 @@ RUN uv pip install --no-deps -e . \
     && uv pip install --no-deps -e ./sources/google_scholar_paper_search \
     && uv pip install --no-deps -e ./sources/tavily_web_search \
     && uv pip install --no-deps -e ./sources/exa_web_search \
+    && uv pip install --no-deps -e ./sources/nimble_web_search \
+    && uv pip install langchain-nimble==3.0.0 nimble-python==0.18.0 \
     && uv pip install --no-deps -e "./sources/knowledge_layer[all]" \
     && uv pip install --no-deps -e ./frontends/aiq_api \
     && uv pip install "psycopg[binary]>=3.0.0"

docs/source/customization/configuration-reference.md

@@ -197,6 +197,48 @@ functions:
 - **`fast`** -- Optimized for low latency. Returns results quickly at the cost of recall and semantic depth. Use for interactive UIs, high-volume calls, or when the query is narrow and keyword-like.
 - **`deep`** -- Optimized for thoroughness. Runs a more expensive semantic search with broader retrieval. Use for research-quality queries where completeness matters more than speed.
 
+### `nimble_web_search`
+
+Web search powered by the [Nimble API](https://nimbleway.com/) via `langchain-nimble`.
+
+```yaml
+functions:
+  web_search_tool:
+    _type: nimble_web_search
+    max_results: 5
+    max_content_length: 10000
+
+  deep_web_search_tool:
+    _type: nimble_web_search
+    max_results: 5
+    search_depth: deep
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `max_results` | `int` | `5` | Maximum number of search results to return. |
+| `api_key` | `str` | `None` | Nimble API key. Falls back to `NIMBLE_API_KEY` environment variable. |
+| `max_retries` | `int` | `3` | Number of retry attempts on search failure. |
+| `search_depth` | `str` | `"lite"` | Nimble search depth. See options below. |
+| `focus` | `str` | `"general"` | Nimble focus mode. See options below. |
+| `country` | `str` | `"US"` | ISO country code passed to Nimble (e.g. `US`, `UK`, `FR`). |
+| `locale` | `str` | `"en"` | Language/locale passed to Nimble (e.g. `en`, `fr`, `es`). |
+| `max_content_length` | `int` | `10000` | Max characters per result's page content. Set to `None` to disable truncation. |
+
+**`search_depth` options:**
+
+- **`lite`** (default) -- Returns metadata only (title, URL, description). Fastest, lowest token cost, safe default for general lookups.
+- **`fast`** -- Returns rich content at low latency. **Enterprise-tier only**; non-enterprise accounts receive a 403 with a clear entitlement message.
+- **`deep`** -- Returns full page content for each result. Use for research workflows that need the body text, not just URLs.
+
+**`focus` options:**
+
+- **`general`** (default) -- Broad web/research queries. The right choice for almost all agent use.
+- **`news`** -- Restricts results to news-publisher sources, ordered by recency. There is no recency threshold -- older articles still appear; it changes the source mix, not the time window. (Recency windowing is a separate Nimble `time_range` capability that also works with `focus=general`; not exposed in this initial integration.)
+- **`location`**, **`shopping`**, **`geo`**, **`social`** -- Domain-specific routing; set only when the tool targets that domain.
+
+`focus` is a workflow-config setting, not an agent-chosen parameter -- the model only passes a query, so general research queries cannot silently switch to `news`. Answer generation (`include_answer`) is **not exposed** in this initial integration.
+
 ### `paper_search`
 
 Academic paper search through Google Scholar (using the [Serper API](https://serper.dev/)).

docs/source/deployment/docker-build.md

@@ -48,6 +48,7 @@ The builder stage handles all compilation and package installation:
    - `sources/google_scholar_paper_search` -- Google Scholar search
    - `sources/tavily_web_search` -- Tavily web search
    - `sources/exa_web_search` -- Exa web search
+   - `sources/nimble_web_search` -- Nimble web search
    - `sources/knowledge_layer[all]` -- Knowledge layer with all extras
    - `frontends/aiq_api` -- [FastAPI](https://fastapi.tiangolo.com/) frontend
    - `psycopg[binary]>=3.0.0` -- PostgreSQL driver (psycopg v3, installed non-editable)

docs/source/deployment/docker-compose.md

@@ -44,6 +44,7 @@ The sections below explain each group of variables.
 | `NVIDIA_API_KEY` | Yes | NVIDIA API key for NIM model access. |
 | `TAVILY_API_KEY` | Conditional | Web search provider key (required if using `tavily_web_search`). |
 | `EXA_API_KEY` | Conditional | Web search provider key (required if using `exa_web_search`). |
+| `NIMBLE_API_KEY` | Conditional | Web search provider key (required if using `nimble_web_search`). |
 | `SERPER_API_KEY` | No | Google Scholar paper search key (optional). |
 
 ### API keys (optional)

docs/source/deployment/kubernetes.md

@@ -263,6 +263,7 @@ For complete examples with NGC-specific flags, see `deploy/helm/README.md` in th
 | Key | Description |
 |-----|-------------|
 | `EXA_API_KEY` | Exa API key for web search |
+| `NIMBLE_API_KEY` | Nimble API key for web search |
 | `SERPER_API_KEY` | Serper API key for Google search |
 | `JINA_API_KEY` | Jina API key |
 | `WANDB_API_KEY` | Weights & Biases API key |

docs/source/extending/adding-a-data-source.md

@@ -460,6 +460,7 @@ async def search(self, query: str) -> str:
 |---|---|---|---|
 | Tavily Web Search | `tavily_web_search` | `sources/tavily_web_search` | General web search through Tavily API |
 | Exa Web Search | `exa_web_search` | `sources/exa_web_search` | General web search through Exa API |
+| Nimble Web Search | `nimble_web_search` | `sources/nimble_web_search` | General web search through Nimble API (`langchain-nimble`) |
 | Google Scholar | `paper_search` | `sources/google_scholar_paper_search` | Academic papers through Serper/Google Scholar |
 | Knowledge Layer | `knowledge_retrieval` | `sources/knowledge_layer` | Document retrieval through pluggable backends |
 

docs/source/extending/adding-a-tool.md

@@ -420,6 +420,7 @@ f'<Document href="{url}">\n<title>\n{title}\n</title>\n{content}\n</Document>'
 |---|---|---|---|
 | Tavily Web Search | `tavily_web_search` | `sources/tavily_web_search` | `TAVILY_API_KEY` |
 | Exa Web Search | `exa_web_search` | `sources/exa_web_search` | `EXA_API_KEY` |
+| Nimble Web Search | `nimble_web_search` | `sources/nimble_web_search` | `NIMBLE_API_KEY` |
 | Google Scholar | `paper_search` | `sources/google_scholar_paper_search` | `SERPER_API_KEY` |
 | Knowledge Layer | `knowledge_retrieval` | `sources/knowledge_layer` | (varies by backend) |
 

docs/source/get-started/installation.md

@@ -51,7 +51,7 @@ The script performs the following steps:
 3. Installs the core package with dev dependencies
 4. Installs all frontends (CLI, debug console, API server)
 5. Installs benchmark packages (freshqa, deepsearch_qa)
-6. Installs all data source plugins (Tavily, Exa, Google Scholar, knowledge layer)
+6. Installs all data source plugins (Tavily, Exa, Nimble, Google Scholar, knowledge layer)
 7. Sets up pre-commit hooks
 8. Copies `deploy/.env.example` to `deploy/.env` if no `.env` file exists
 9. Installs UI npm dependencies (if Node.js is available)
@@ -96,6 +96,7 @@ uv pip install -e ./frontends/aiq_api      # Unified API server (includes debug)
 # Data sources (pick what you need)
 uv pip install -e ./sources/tavily_web_search
 uv pip install -e ./sources/exa_web_search
+uv pip install -e ./sources/nimble_web_search
 uv pip install -e ./sources/google_scholar_paper_search
 uv pip install -e "./sources/knowledge_layer[llamaindex,foundational_rag]"
 
@@ -132,9 +133,10 @@ Then edit `deploy/.env` and fill in your keys.
 |----------|----------|---------|
 | `TAVILY_API_KEY` | [Tavily](https://tavily.com/) | Web search (Tavily provider) |
 | `EXA_API_KEY` | [Exa](https://exa.ai/) | Web search (Exa provider) |
+| `NIMBLE_API_KEY` | [Nimble](https://nimbleway.com/) | Web search (Nimble provider) |
 | `SERPER_API_KEY` | [Serper](https://serper.dev/) | Academic paper search (Google Scholar). To enable, uncomment `paper_search_tool` in your config file |
 
-At minimum, you need `NVIDIA_API_KEY` for LLM inference and one of `TAVILY_API_KEY` or `EXA_API_KEY` for web search. Paper search (`SERPER_API_KEY`) is disabled by default in the shipped configs -- refer to the comments in your config file to enable it.
+At minimum, you need `NVIDIA_API_KEY` for LLM inference and one of `TAVILY_API_KEY`, `EXA_API_KEY`, or `NIMBLE_API_KEY` for web search. Paper search (`SERPER_API_KEY`) is disabled by default in the shipped configs -- refer to the comments in your config file to enable it.
 
 ## Verify Installation
 

docs/source/get-started/quick-start.md

@@ -22,6 +22,8 @@ NVIDIA_API_KEY=nvapi-...
 TAVILY_API_KEY=tvly-...
 # Or, to use Exa instead of Tavily for web search:
 # EXA_API_KEY=...
+# Or, to use Nimble instead of Tavily for web search:
+# NIMBLE_API_KEY=...
 ```
 
 ## Step 2: Choose a Mode

docs/source/resources/faq.md

@@ -44,6 +44,7 @@ If `enable_escalation: true` in the workflow config, the orchestrator evaluates
 
 - **Tavily Web Search** — General web search (requires `TAVILY_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`)
 - **Google Scholar Paper Search** — Academic paper search (requires `SERPER_API_KEY`)
 - **Knowledge Layer** — Document retrieval from local or hosted vector stores
 

docs/source/resources/troubleshooting.md

@@ -25,6 +25,8 @@ Common issues and solutions for the AI-Q blueprint.
 | `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) |
 | 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 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 |
 
 ## Runtime Issues

pyproject.toml

@@ -190,6 +190,7 @@ dev = [
     "google-scholar-paper-search",
     "tavily-web-search",
     "exa-web-search",
+    "nimble-web-search",
     "knowledge-layer[all]",
     "aiq-api",
     "aiq-research-cli",
@@ -231,6 +232,7 @@ aiq-agent = { workspace = true }
 google-scholar-paper-search = { workspace = true }
 tavily-web-search = { workspace = true }
 exa-web-search = { workspace = true }
+nimble-web-search = { workspace = true }
 knowledge-layer = { workspace = true }
 aiq-api = { workspace = true }
 aiq-research-cli = { workspace = true }

scripts/setup.sh

@@ -66,6 +66,7 @@ echo ""
 echo "Installing data sources..."
 "${UV_BIN}" pip install -e ./sources/tavily_web_search
 "${UV_BIN}" pip install -e ./sources/exa_web_search
+"${UV_BIN}" pip install -e ./sources/nimble_web_search
 "${UV_BIN}" pip install -e ./sources/google_scholar_paper_search
 "${UV_BIN}" pip install -e "./sources/knowledge_layer[llamaindex,foundational_rag]"
 echo "Data Sources installed"