pi-web-providers 2.4.2 → 3.0.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,
+- **Multiple providers**: Brave, Claude, Cloudflare, Codex, Exa, Firecrawl,
+  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
@@ -56,11 +57,13 @@ Each tool can be routed to any compatible provider:
 
 | Provider       | search | contents | answer | research | Auth                                             |
 | -------------- | :----: | :------: | :----: | :------: | ------------------------------------------------ |
+| **Brave**      |   ✔    |          |   ✔    |    ✔     | `BRAVE_SEARCH_API_KEY` / `BRAVE_ANSWERS_API_KEY` |
 | **Cloudflare** |        |    ✔     |        |          | `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` |
 | **Exa**        |   ✔    |    ✔     |   ✔    |    ✔     | `EXA_API_KEY`                                    |
 | **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 +71,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 +84,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 +97,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 +120,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 +133,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 +167,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 +186,49 @@ 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>Brave</strong></summary>
+
+- API: Brave Search API and Brave Answers API
+- Supports `web_search` via Web Search, plus optional `llm_context`, `news`, `videos`, `images`, and `places` search modes
+- Supports `web_answer` and `web_research` via Brave Answers streaming chat completions
+- `web_contents` stays routed to URL-fetch providers; Brave LLM Context is query-based retrieval and is exposed as a search mode instead
+- Brave Answers may require a different key or plan than Brave Search
+
+**Setup**
+
+```json
+{
+  "tools": {
+    "search": "brave",
+    "answer": "brave",
+    "research": "brave"
+  },
+  "providers": {
+    "brave": {
+      "credentials": {
+        "search": "BRAVE_SEARCH_API_KEY",
+        "answers": "BRAVE_ANSWERS_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Use `providers.brave.options.search.mode` or per-call search options to select
+`llm_context`, `news`, `videos`, `images`, or `places`. Places details and
+descriptions are opt-in because they can add calls, latency, and place-specific
+semantics.
+
+</details>
 
 <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
@@ -219,7 +261,9 @@ The built-in providers below are thin adapters around official SDKs.
   },
   "providers": {
     "cloudflare": {
-      "apiToken": "CLOUDFLARE_API_TOKEN",
+      "credentials": {
+        "api": "CLOUDFLARE_API_TOKEN"
+      },
       "accountId": "CLOUDFLARE_ACCOUNT_ID"
     }
   }
@@ -253,8 +297,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>
 
@@ -302,6 +345,38 @@ 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": {
+      "credentials": {
+        "api": "OLLAMA_API_KEY"
+      }
+    }
+  }
+}
+```
+
+</details>
+
 <details>
 <summary><strong>OpenAI</strong></summary>
 
@@ -334,7 +409,9 @@ scope, or account ID is usually wrong.
   },
   "providers": {
     "openai": {
-      "apiKey": "OPENAI_API_KEY",
+      "credentials": {
+        "api": "OPENAI_API_KEY"
+      },
       "options": {
         "search": {
           "model": "gpt-4.1"
@@ -405,7 +482,9 @@ Minimal config:
   },
   "providers": {
     "serper": {
-      "apiKey": "SERPER_API_KEY"
+      "credentials": {
+        "api": "SERPER_API_KEY"
+      }
     }
   }
 }
@@ -439,7 +518,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>
@@ -450,7 +529,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.