pi-web-providers 3.0.0 → 3.2.0

package/README.md

@@ -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                   |
@@ -62,7 +68,7 @@ Each tool can be routed to any compatible provider:
 | **Exa**        |   ✔    |    ✔     |   ✔    |    ✔     | `EXA_API_KEY`                                    |
 | **Firecrawl**  |   ✔    |    ✔     |        |          | `FIRECRAWL_API_KEY`                              |
 | **Gemini**     |   ✔    |          |   ✔    |    ✔     | `GOOGLE_API_KEY`                                 |
-| **Linkup**     |   ✔    |    ✔     |        |          | `LINKUP_API_KEY`                                 |
+| **Linkup**     |   ✔    |    ✔     |        |    ✔     | `LINKUP_API_KEY`                                 |
 | **Ollama**     |   ✔    |    ✔     |        |          | `OLLAMA_API_KEY`                                 |
 | **OpenAI**     |   ✔    |          |   ✔    |    ✔     | `OPENAI_API_KEY`                                 |
 | **Parallel**   |   ✔    |    ✔     |        |          | `PARALLEL_API_KEY`                               |
@@ -143,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>
@@ -194,6 +202,8 @@ The built-in providers below integrate with official SDKs or documented APIs.
 - 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
 
@@ -312,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>
 
@@ -338,10 +352,17 @@ scope, or account ID is usually wrong.
 - SDK: `linkup-sdk`
 - Supports `web_search` via Linkup Search with fixed `searchResults` output
 - Supports `web_contents` via Linkup Fetch and always returns markdown
+- Supports `web_research` via Linkup's async Research API
 - Exposes search options `depth`, `includeImages`, `includeDomains`,
   `excludeDomains`, `fromDate`, and `toDate`
 - Exposes contents options `renderJs`, `includeRawHtml`, and `extractImages`
-- Good fit for a simple search-plus-markdown setup without extra provider wiring
+- Exposes research options `outputType`, `mode`, `reasoningDepth`,
+  `includeDomains`, `excludeDomains`, `fromDate`, `toDate`, and
+  `structuredOutputSchema`
+- Research defaults to `sourcedAnswer`; provide `structuredOutputSchema` for
+  structured output
+- Good fit for search, markdown extraction, and long-running sourced research
+  without extra provider wiring
 
 </details>
 
@@ -465,9 +486,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`
@@ -620,27 +647,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)