pi-web-providers 2.4.1 → 2.5.0

package/README.md

@@ -1,20 +1,21 @@
 # 🌍 pi-web-providers
 
 A _meta_ web extension for [pi](https://pi.dev) that routes search, content
-extraction, answers, and research through configurable per-tool providers, with
-explicit provider-specific option schemas for each managed tool.
+extraction, quick grounded answers, and research through configurable per-tool
+providers, with explicit provider-specific option schemas for each managed tool.
 
 ## Why?
 
 Most web extensions hard-wire a single backend. **pi-web-providers** lets you
 mix and match providers per tool instead, so `web_search`, `web_contents`,
 `web_answer`, and `web_research` can each use a different backend or be turned
-off entirely.
+off entirely. Treat `web_answer` as a fast path for simple grounded questions,
+not as a replacement for source inspection or deeper research.
 
 ## ✨ Features
 
 - **Multiple providers**: Claude, Cloudflare, Codex, Exa, Firecrawl,
-  Gemini, Linkup, OpenAI, Perplexity, Parallel, Serper,
+  Gemini, Linkup, Ollama, OpenAI, Perplexity, Parallel, Serper,
   [Tavily](https://tavily.com), Valyu
 - **Provider-aware tool options**: pi only exposes the provider settings that
   actually apply to the backend you selected, so tool calls are easier to
@@ -61,6 +62,7 @@ Each tool can be routed to any compatible provider:
 | **Firecrawl**  |   ✔    |    ✔     |        |          | `FIRECRAWL_API_KEY`                              |
 | **Gemini**     |   ✔    |          |   ✔    |    ✔     | `GOOGLE_API_KEY`                                 |
 | **Linkup**     |   ✔    |    ✔     |        |          | `LINKUP_API_KEY`                                 |
+| **Ollama**     |   ✔    |    ✔     |        |          | `OLLAMA_API_KEY`                                 |
 | **OpenAI**     |   ✔    |          |   ✔    |    ✔     | `OPENAI_API_KEY`                                 |
 | **Parallel**   |   ✔    |    ✔     |        |          | `PARALLEL_API_KEY`                               |
 | **Perplexity** |   ✔    |          |   ✔    |    ✔     | `PERPLEXITY_API_KEY`                             |
@@ -68,9 +70,8 @@ Each tool can be routed to any compatible provider:
 | **Tavily**     |   ✔    |    ✔     |        |          | `TAVILY_API_KEY`                                 |
 | **Valyu**      |   ✔    |    ✔     |   ✔    |    ✔     | `VALYU_API_KEY`                                  |
 
-Advanced option: `custom` is a configurable adapter provider that can route
-any managed tool through a local wrapper command using a JSON stdin/stdout
-contract.
+Advanced option: `custom` can route any managed tool through a local wrapper
+command using a JSON stdin/stdout contract.
 
 See [`example-config.json`](example-config.json) for the minimal default
 configuration.
@@ -82,7 +83,8 @@ Removing a tool mapping turns that tool off. A tool is only exposed when it is
 mapped to a compatible provider and that provider is currently available.
 Shared defaults and tool-specific settings live under `settings`; search-specific
 settings live under `settings.search`, and async research uses
-`settings.researchTimeoutMs`.
+`settings.researchTimeoutMs`. Provider option schemas are strict: only the keys
+shown for the active provider are accepted.
 
 #### `web_search`
 
@@ -94,18 +96,16 @@ results should arrive as soon as they are ready.
 <details>
 <summary><strong>Parameters and behavior</strong></summary>
 
-| Parameter    | Type     | Default  | Description                                                                                |
-| ------------ | -------- | -------- | ------------------------------------------------------------------------------------------ |
-| `queries`    | string[] | required | One or more search queries to run (max 10)                                                 |
-| `maxResults` | integer  | `5`      | Result count per query, clamped to `1–20`                                                  |
-| `options`    | object   | —        | `provider` settings exposed by the selected provider schema, plus local `runtime` settings |
+| Parameter    | Type     | Default  | Description                                                        |
+| ------------ | -------- | -------- | ------------------------------------------------------------------ |
+| `queries`    | string[] | required | One or more search queries to run (max 10)                         |
+| `maxResults` | integer  | `5`      | Result count per query, clamped to `1–20`                          |
+| `options`    | object   | —        | Provider-specific settings exposed by the selected provider schema |
 
-`web_search.options.runtime.prefetch` is local-only and is not forwarded to the
-provider SDK. It accepts `provider`, `maxUrls`, and `ttlMs`, and starts a
-background page-extraction workflow only when `prefetch.provider` is set.
-`/web-providers` can also persist default search prefetch settings under
-`settings.search`. Per-call retry and timeout overrides also live under
-`web_search.options.runtime`.
+`options` is omitted when the configured search provider has no per-call
+provider options. Runtime controls are not accepted in tool calls. Configure
+retry, timeout, and background contents prefetch under `settings` and
+`settings.search`; prefetch starts only when `settings.search.provider` is set.
 
 </details>
 
@@ -119,10 +119,10 @@ each page can be acted on independently.
 <details>
 <summary><strong>Parameters and behavior</strong></summary>
 
-| Parameter | Type     | Default  | Description                                                                                                     |
-| --------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------- |
-| `urls`    | string[] | required | One or more URLs to extract                                                                                     |
-| `options` | object   | —        | `provider` extraction settings exposed by the selected provider schema, plus optional local `runtime` overrides |
+| Parameter | Type     | Default  | Description                                                        |
+| --------- | -------- | -------- | ------------------------------------------------------------------ |
+| `urls`    | string[] | required | One or more URLs to extract                                        |
+| `options` | object   | —        | Provider-specific settings exposed by the selected provider schema |
 
 `web_contents` reuses any matching cached pages already present in the local
 in-memory cache—whether they came from prefetch or an earlier read—and only
@@ -132,18 +132,24 @@ fetches missing or stale URLs.
 
 #### `web_answer`
 
-Answer one or more questions using web-grounded evidence. When you ask more
-than one question, the response is grouped into per-question sections. Batch
-related questions when the answers belong together; split them into sibling
-calls when earlier independent answers can unblock the next step.
+Answer one or more simple factual questions using web-grounded evidence. Use it
+as a lightweight shortcut when you want a concise grounded answer without
+manually selecting and reading sources. Prefer `web_search` plus `web_contents`
+when source selection matters or you need to inspect primary sources directly;
+prefer `web_research` for open-ended, controversial, or multi-step
+investigations.
+
+When you ask more than one question, the response is grouped into per-question
+sections. Batch related questions when the answers belong together; split them
+into sibling calls when earlier independent answers can unblock the next step.
 
 <details>
 <summary><strong>Parameters and behavior</strong></summary>
 
-| Parameter | Type     | Default  | Description                                                                                          |
-| --------- | -------- | -------- | ---------------------------------------------------------------------------------------------------- |
-| `queries` | string[] | required | One or more questions to answer in one call (max 10)                                                 |
-| `options` | object   | —        | `provider` settings exposed by the selected provider schema, plus optional local `runtime` overrides |
+| Parameter | Type     | Default  | Description                                                        |
+| --------- | -------- | -------- | ------------------------------------------------------------------ |
+| `queries` | string[] | required | One or more questions to answer in one call (max 10)               |
+| `options` | object   | —        | Provider-specific settings exposed by the selected provider schema |
 
 Responses are grouped into per-question sections when more than one question is
 provided.
@@ -160,15 +166,15 @@ saved report path.
 <details>
 <summary><strong>Parameters and behavior</strong></summary>
 
-| Parameter | Type   | Default  | Description                                                                   |
-| --------- | ------ | -------- | ----------------------------------------------------------------------------- |
-| `input`   | string | required | Research brief or question                                                    |
-| `options` | object | —        | Provider-specific `provider` settings exposed by the selected provider schema |
+| Parameter | Type   | Default  | Description                                                        |
+| --------- | ------ | -------- | ------------------------------------------------------------------ |
+| `input`   | string | required | Research brief or question                                         |
+| `options` | object | —        | Provider-specific settings exposed by the selected provider schema |
 
-`options.provider` is provider-specific. Equivalent concepts can use different
-field names across SDKs—for example Perplexity uses `country`, Exa uses
-`userLocation`, and Valyu uses `countryCode`. Unlike the other managed tools,
-`web_research` does not support per-call `options.runtime` overrides.
+`options` is provider-specific. Equivalent concepts can use different field
+names across SDKs—for example Perplexity uses `country`, Exa uses
+`userLocation`, and Valyu uses `countryCode`. Runtime controls are not accepted
+in tool calls.
 
 Unlike the other managed tools, `web_research` does not accept local timeout,
 retry, polling, or resume controls. Research has one opinionated execution
@@ -179,14 +185,13 @@ report under `.pi/artifacts/research/`.
 
 ### Providers
 
-The built-in providers below are thin adapters around official SDKs.
+The built-in providers below integrate with official SDKs or documented APIs.
 
 <details>
 <summary><strong>Claude</strong></summary>
 
 - SDK: `@anthropic-ai/claude-agent-sdk`
-- Uses Claude Code's built-in `WebSearch` and `WebFetch` tools behind a
-  structured JSON adapter
+- Uses Claude Code's built-in `WebSearch` and `WebFetch` tools with structured JSON output
 - Exposes `model`, `thinking`, `effort`, `maxThinkingTokens`, `maxTurns`, and
   `maxBudgetUsd` as provider options for search and answer calls
 - Great for search plus grounded answers if you already use Claude Code locally
@@ -253,8 +258,7 @@ scope, or account ID is usually wrong.
 - Exposes search options such as `category`, `type`, date filters,
   `includeDomains`, `excludeDomains`, `userLocation`, and `contents`
 - Persisted Exa defaults are scoped under `providers.exa.options.search`
-- `web_contents`, `web_answer`, and `web_research` currently use fixed adapter
-  behavior with no extra per-call provider options
+- `web_contents`, `web_answer`, and `web_research` currently use fixed provider behavior with no extra per-call provider options
 
 </details>
 
@@ -281,8 +285,11 @@ scope, or account ID is usually wrong.
 - Google Search grounding for answers
 - Deep-research agents via Google's Gemini API
 - Exposes `model` and `generation_config` for search, `model` and `config`
-  for answers, and `agent_config`, `store`, `response_format`,
-  `response_modalities`, `system_instruction`, and `tools` for research
+  for answers, and only the conservative deep-research option
+  `agent_config.thinking_summaries` for research
+- Gemini research intentionally does not expose or send Interactions API
+  `tools`, `response_format`, `response_modalities`, or `system_instruction`
+  because the default deep-research agent rejects several of those fields
 
 </details>
 
@@ -299,6 +306,36 @@ scope, or account ID is usually wrong.
 
 </details>
 
+<details>
+<summary><strong>Ollama</strong></summary>
+
+- API: [Ollama Web Search and Fetch API](https://docs.ollama.com/capabilities/web-search)
+- Supports `web_search` via Ollama's `POST /api/web_search` endpoint
+- Supports `web_contents` via Ollama's `POST /api/web_fetch` endpoint
+- Authenticates with an Ollama API key using `OLLAMA_API_KEY` by default
+- Optional `baseUrl` overrides the default `https://ollama.com` API host for
+  proxies or compatible endpoints
+- Ollama caps search requests at 10 results, so `web_search.maxResults` is
+  clamped to `1–10` for this provider
+
+Minimal config:
+
+```json
+{
+  "tools": {
+    "search": "ollama",
+    "contents": "ollama"
+  },
+  "providers": {
+    "ollama": {
+      "apiKey": "OLLAMA_API_KEY"
+    }
+  }
+}
+```
+
+</details>
+
 <details>
 <summary><strong>OpenAI</strong></summary>
 
@@ -436,7 +473,7 @@ Minimal config:
 - Exposes answer and research options `responseLength` and `countryCode`
 - Persisted Valyu defaults are scoped under `providers.valyu.options.search`,
   `providers.valyu.options.answer`, and `providers.valyu.options.research`
-- `web_contents` currently uses fixed adapter behavior with no extra per-call
+- `web_contents` currently uses fixed provider behavior with no extra per-call
   provider options
 
 </details>
@@ -447,7 +484,7 @@ The `custom` provider lets you bring your own wrapper command for any
 managed tool. Each capability can point at a different local command under
 `providers["custom"].options`.
 
-`custom` does not expose standard per-call `options.provider` fields. Put
+`custom` does not expose standard per-call `options` fields. Put
 provider-specific behavior in the wrapper configuration or in the wrapper
 implementation.