pi-web-providers 2.5.0 → 3.1.0

package/README.md

@@ -14,7 +14,7 @@ not as a replacement for source inspection or deeper research.
 
 ## ✨ Features
 
-- **Multiple providers**: Claude, Cloudflare, Codex, Exa, Firecrawl,
+- **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
@@ -27,13 +27,13 @@ not as a replacement for source inspection or deeper research.
   extraction from `web_search` results in the background and reuse the cached
   pages later for faster follow-up reads
 
-## 📦 Install
+## 🚀 Installation
 
-```bash
+```sh
 pi install npm:pi-web-providers
 ```
 
-## ⚙️ Configure
+## ⚙️ Configuration
 
 Run:
 
@@ -46,6 +46,12 @@ settings UI mirrors the three sections below: tools, providers, and settings.
 
 Each tool can be routed to any compatible provider:
 
+Provider credentials can be literal values, environment variable names, or
+`!command` references. pi-web-providers resolves those secrets lazily on the
+first matching tool use, not when a session starts. This avoids startup delays
+from password-manager commands such as `op`; missing or failing secrets are
+reported when the tool is actually called.
+
 **Built-in local providers**
 
 | Provider   | search | contents | answer | research | Auth                   |
@@ -57,6 +63,7 @@ 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`                              |
@@ -142,6 +149,8 @@ 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.
+Collapsed results show a short answer preview; expand the tool result to read the
+full answer.
 
 <details>
 <summary><strong>Parameters and behavior</strong></summary>
@@ -187,6 +196,44 @@ report under `.pi/artifacts/research/`.
 
 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
+- Uses the Answers API replacement for Brave's deprecated Summarizer API; answer and research search controls are sent through `web_search_options`
+- Exposes the Answers `model` option (`brave` or `brave-pro`) for answer and research calls
+- `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>
 
@@ -224,7 +271,9 @@ The built-in providers below integrate with official SDKs or documented APIs.
   },
   "providers": {
     "cloudflare": {
-      "apiToken": "CLOUDFLARE_API_TOKEN",
+      "credentials": {
+        "api": "CLOUDFLARE_API_TOKEN"
+      },
       "accountId": "CLOUDFLARE_ACCOUNT_ID"
     }
   }
@@ -273,6 +322,10 @@ scope, or account ID is usually wrong.
   `location`, `timeout`, and `scrapeOptions`
 - Exposes contents options such as `formats`, `onlyMainContent`, `includeTags`,
   `excludeTags`, `waitFor`, `headers`, `location`, `mobile`, and `proxy`
+- Optional `baseUrl` overrides are supported for self-hosted Firecrawl
+  instances, proxies, and testing. API keys are required for Firecrawl Cloud,
+  but can be omitted for self-hosted endpoints that do not enforce
+  authentication.
 
 </details>
 
@@ -328,7 +381,9 @@ Minimal config:
   },
   "providers": {
     "ollama": {
-      "apiKey": "OLLAMA_API_KEY"
+      "credentials": {
+        "api": "OLLAMA_API_KEY"
+      }
     }
   }
 }
@@ -368,7 +423,9 @@ Minimal config:
   },
   "providers": {
     "openai": {
-      "apiKey": "OPENAI_API_KEY",
+      "credentials": {
+        "api": "OPENAI_API_KEY"
+      },
       "options": {
         "search": {
           "model": "gpt-4.1"
@@ -422,9 +479,15 @@ call.
 <summary><strong>Serper</strong></summary>
 
 - API: Serper HTTP API
-- Supports `web_search` via Serper's Google search endpoint
-- Good fit for fast, straightforward Google-style organic search results
-- Exposes search options `gl`, `hl`, `location`, `page`, and `autocorrect`
+- Supports `web_search` via Serper's Google endpoints for web, image, video,
+  places, maps, reviews, news, shopping, product reviews, Lens, Scholar,
+  patents, autocomplete, and webpage results
+- Good fit for fast, straightforward Google-style search results
+- Exposes search options `mode`, `gl`, `hl`, `location`, `page`, `tbs`,
+  `autocorrect`, and mode-specific fields such as `url`, `ll`, `placeId`,
+  `cid`, `fid`, `productId`, `nextPageToken`, and webpage include flags.
+  Reviews mode uses the top-level query when no place identifier is provided.
+  `includeMarkdown` defaults to `true` for webpage scraping
 - Preserves rich metadata from Serper responses, including ranking position,
   sitelinks, attributes, and top-level response context such as
   `knowledgeGraph`, `answerBox`, `peopleAlsoAsk`, and `relatedSearches`
@@ -439,7 +502,9 @@ Minimal config:
   },
   "providers": {
     "serper": {
-      "apiKey": "SERPER_API_KEY"
+      "credentials": {
+        "api": "SERPER_API_KEY"
+      }
     }
   }
 }
@@ -575,27 +640,12 @@ providers unless overridden in a provider's own `settings` block:
 | `retryDelayMs`      | `2000`    | Initial delay before retrying                               |
 | `researchTimeoutMs` | `1800000` | Maximum total time for an async `web_research` job (30 min) |
 
-## 🔎 Live smoke tests
-
-Use the opt-in live smoke runner to validate the configured providers with the
-same config-resolution and execution path the extension uses at runtime:
-
-```bash
-npm run smoke:live
-```
-
-Optional filters:
+## 🧹 Uninstall
 
-```bash
-npm run smoke:live -- --provider gemini
-npm run smoke:live -- --tool contents
-npm run smoke:live -- --include-research
+```sh
+pi remove npm:pi-web-providers
 ```
 
-The default run exercises `search`, `contents`, and `answer`. Research probes
-are excluded unless you pass `--include-research`, because they are slower and
-may incur higher provider cost.
-
 ## 📄 License
 
 [MIT](LICENSE)