pi-web-providers 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # 🌍 pi-web-providers
 
-A *meta* web extension for [pi](https://pi.dev).
+A _meta_ web extension for [pi](https://pi.dev).
 
 ## Why?
 
@@ -18,16 +18,23 @@ only the tools that make sense. If your active provider offers search and
 content extraction but not deep research, the agent never sees a research tool.
 Switch to a provider that supports it and the tool appears automatically.
 
+The extension also separates **available tools** from the **active tool set**.
+When a session starts, it can add every available managed tool. Before each
+agent run, it removes tools that are no longer available but keeps any managed
+tools that you explicitly removed from the active set disabled. That keeps the
+tool prompt aligned with the tools that the agent can actually call.
+
 ## ✨ Features
 
 - **Provider-driven tool surface** — tools are injected based on what the active
   provider actually supports, not a fixed list
-- **Five providers**: Codex, Exa, Gemini, Parallel, Valyu — each with its own
-  SDK, strengths, and capability set
+- **Multiple providers**: Claude, Codex, Exa, Gemini, Perplexity, Parallel,
+  Valyu — each with
+  its own SDK, strengths, and capability set
 - **One config command** (`/web-providers`) with a TUI that adapts to the
   selected provider
-- **Transparent fallback** — if no provider is explicitly enabled, the extension
-  walks the list alphabetically and picks the first one that is available
+- **Transparent fallback** — search falls back to Codex when no provider is
+  explicitly enabled and the local CLI is installed and authenticated
 - **Per-provider tool toggles** — disable individual capabilities you don't need
   without switching providers
 - **Truncated output with temp-file spillover** for large results
@@ -51,8 +58,9 @@ This command edits a single global config file:
 
 The flow is provider-first: pick the active provider, then configure only that
 provider's tool toggles and settings. Each provider view surfaces the knobs that
-actually apply—Codex shows reasoning-effort and web-search-mode toggles; Exa
-shows search type and text-content flags; and so on.
+actually apply—Claude shows model/effort/turns settings; Codex shows
+reasoning-effort and web-search-mode toggles; Exa shows search type and
+text-content flags; and so on.
 
 ## 🔧 Tools
 
@@ -62,61 +70,80 @@ corresponding tool is never exposed to the agent.
 
 ### `web_search`
 
-Search the web and return titles, URLs, and snippets.
+Find likely sources on the public web and return titles, URLs, and snippets.
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `query` | string | required | What to search for |
-| `maxResults` | integer | `5` | Result count, clamped to `1–20` |
-| `provider` | string | auto | Optional override: `codex`, `exa`, `gemini`, `parallel`, or `valyu` |
+| Parameter    | Type    | Default  | Description                                                                   |
+| ------------ | ------- | -------- | ----------------------------------------------------------------------------- |
+| `query`      | string  | required | What to search for                                                            |
+| `maxResults` | integer | `5`      | Result count, clamped to `1–20`                                               |
+| `options`    | object  | —        | Provider-specific search options                                              |
+| `provider`   | string  | auto     | Optional override: `claude`, `codex`, `exa`, `gemini`, `perplexity`, `parallel`, or `valyu` |
 
 ### `web_contents`
 
-Extract contents for one or more URLs.
+Read and extract the main contents of one or more web pages.
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `urls` | string[] | required | One or more URLs to extract |
-| `options` | object | — | Provider-specific extraction options |
-| `provider` | string | auto | Optional override among providers that support contents |
+| Parameter  | Type     | Default  | Description                                             |
+| ---------- | -------- | -------- | ------------------------------------------------------- |
+| `urls`     | string[] | required | One or more URLs to extract                             |
+| `options`  | object   | —        | Provider-specific extraction options                    |
+| `provider` | string   | auto     | Optional override among providers that support contents |
 
 ### `web_answer`
 
-Get a provider-generated answer grounded in search results.
+Answer a question using web-grounded evidence.
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `query` | string | required | Question to answer |
-| `options` | object | — | Provider-specific answer options |
-| `provider` | string | auto | Optional override among providers that support answers |
+| Parameter  | Type   | Default  | Description                                            |
+| ---------- | ------ | -------- | ------------------------------------------------------ |
+| `query`    | string | required | Question to answer                                     |
+| `options`  | object | —        | Provider-specific answer options                       |
+| `provider` | string | auto     | Optional override among providers that support answers |
 
 ### `web_research`
 
-Run a longer-form research task.
+Investigate a topic across web sources and produce a longer report.
+
+| Parameter  | Type   | Default  | Description                                             |
+| ---------- | ------ | -------- | ------------------------------------------------------- |
+| `input`    | string | required | Research brief or question                              |
+| `options`  | object | —        | Provider-specific research options                      |
+| `provider` | string | auto     | Optional override among providers that support research |
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `input` | string | required | Research brief or question |
-| `options` | object | — | Provider-specific research options |
-| `provider` | string | auto | Optional override among providers that support research |
+`options` are provider-native and provider-specific. Equivalent concepts can
+use different field names across SDKs, for example Perplexity uses `country`,
+Exa uses `userLocation`, and Valyu uses `countryCode`. Runtime `options`
+override provider defaults, but managed tool inputs and tool wiring stay fixed.
 
 ## 🔌 Providers
 
 Every provider is a thin adapter around an official SDK. The table below
 summarises which capabilities each provider exposes:
 
-| Provider | search | contents | answer | research | Auth |
-|----------|:------:|:--------:|:------:|:--------:|------|
-| **Codex** | ✓ | | | | Local Codex CLI auth |
-| **Exa** | ✓ | ✓ | ✓ | ✓ | `EXA_API_KEY` |
-| **Gemini** | ✓ | | ✓ | ✓ | `GOOGLE_API_KEY` |
-| **Parallel** | ✓ | ✓ | | | `PARALLEL_API_KEY` |
-| **Valyu** | ✓ | ✓ | ✓ | ✓ | `VALYU_API_KEY` |
+| Provider     | search | contents | answer | research | Auth                   |
+| ------------ | :----: | :------: | :----: | :------: | ---------------------- |
+| **Claude**   |   ✓    |          |   ✓    |          | Local Claude Code auth |
+| **Codex**    |   ✓    |          |        |          | Local Codex CLI auth   |
+| **Exa**      |   ✓    |    ✓     |   ✓    |    ✓     | `EXA_API_KEY`          |
+| **Gemini**   |   ✓    |    ✓     |   ✓    |    ✓     | `GOOGLE_API_KEY`       |
+| **Perplexity** | ✓    |          |   ✓    |    ✓     | `PERPLEXITY_API_KEY`   |
+| **Parallel** |   ✓    |    ✓     |        |          | `PARALLEL_API_KEY`     |
+| **Valyu**    |   ✓    |    ✓     |   ✓    |    ✓     | `VALYU_API_KEY`        |
+
+### Claude
+
+- SDK: `@anthropic-ai/claude-agent-sdk`
+- Uses Claude Code's built-in `WebSearch` and `WebFetch` tools behind a
+  structured JSON adapter
+- Supports request-shaping `options` such as `model`, `thinking`, `effort`, and
+  `maxTurns`
+- Great for search plus grounded answers if you already use Claude Code locally
 
 ### Codex
 
 - SDK: `@openai/codex-sdk`
 - Runs in read-only mode with web search enabled
+- Supports request-shaping `web_search.options` such as `model`,
+  `modelReasoningEffort`, and `webSearchMode`
 - Best if you already use the local Codex CLI and auth flow
 
 ### Exa
@@ -128,18 +155,32 @@ summarises which capabilities each provider exposes:
 ### Gemini
 
 - SDK: `@google/genai`
-- Grounded answers and deep-research agents via Google's Gemini API
+- Google Search grounding for answers and URL Context extraction for page contents
+- Deep-research agents via Google's Gemini API
+- Supports provider-native request options such as `model`, `config`,
+  `generation_config`, and `agent_config` depending on the tool
+
+### Perplexity
+
+- SDK: `@perplexity-ai/perplexity_ai`
+- Uses Perplexity Search for `web_search`
+- Uses Sonar for `web_answer` and `sonar-deep-research` for `web_research`
+- Supports provider-specific `web_search.options` such as `country`,
+  `search_mode`, `search_domain_filter`, and `search_recency_filter`
 
 ### Parallel
 
 - SDK: `parallel-web`
 - Agentic and one-shot search modes
 - Page content extraction with excerpt and full-content toggles
+- Supports provider-native search and extraction options from the Parallel SDK
 
 ### Valyu
 
 - SDK: `valyu-js`
 - Web, proprietary, and news search types
+- Supports provider-native options such as `countryCode`, `responseLength`, and
+  search/source filters
 - Configurable response length for answers and research
 
 ## 📝 Config Notes
@@ -148,8 +189,15 @@ summarises which capabilities each provider exposes:
   for the selected provider and `enabled: false` for the others
 - Each provider can also enable or disable its individual tools through a `tools`
   block
-- If a config has no explicitly enabled provider, the extension falls back to the
-  first available provider alphabetically
+- Managed tools are registered from available provider capabilities, but the
+  active tool set can still be narrower if you removed a tool from the session
+- If no provider is explicitly enabled for search, the extension falls back to
+  Codex when the local CLI is installed and authenticated, unless Codex was
+  explicitly configured as disabled
+- Tools stay inactive when no provider is available for their capability, so
+  they are not injected into the LLM prompt
+- Before each agent run, the extension removes newly unavailable managed tools
+  and keeps manually pruned managed tools inactive instead of re-adding them
 - Secret-like values can be:
   - literal strings
   - environment variable names such as `EXA_API_KEY`
@@ -161,6 +209,13 @@ Example:
 {
   "version": 1,
   "providers": {
+    "claude": {
+      "enabled": false,
+      "tools": {
+        "search": true,
+        "answer": true
+      }
+    },
     "codex": {
       "enabled": true,
       "tools": {
@@ -191,16 +246,38 @@ Example:
       "enabled": false,
       "tools": {
         "search": true,
+        "contents": true,
         "answer": true,
         "research": true
       },
       "apiKey": "GOOGLE_API_KEY",
       "defaults": {
         "searchModel": "gemini-2.5-flash",
+        "contentsModel": "gemini-2.5-flash",
         "answerModel": "gemini-2.5-flash",
         "researchAgent": "deep-research-pro-preview-12-2025"
       }
     },
+    "perplexity": {
+      "enabled": false,
+      "tools": {
+        "search": true,
+        "answer": true,
+        "research": true
+      },
+      "apiKey": "PERPLEXITY_API_KEY",
+      "defaults": {
+        "search": {
+          "country": "US"
+        },
+        "answer": {
+          "model": "sonar"
+        },
+        "research": {
+          "model": "sonar-deep-research"
+        }
+      }
+    },
     "parallel": {
       "enabled": false,
       "tools": {