pi-web-providers 0.2.0 → 0.3.0

package/README.md

@@ -28,7 +28,8 @@ tool prompt aligned with the tools that the agent can actually call.
 
 - **Provider-driven tool surface** — tools are injected based on what the active
   provider actually supports, not a fixed list
-- **Six providers**: Claude, Codex, Exa, Gemini, Parallel, Valyu — each with
+- **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
@@ -75,7 +76,8 @@ Find likely sources on the public web and return titles, URLs, and snippets.
 | ------------ | ------- | -------- | ----------------------------------------------------------------------------- |
 | `query`      | string  | required | What to search for                                                            |
 | `maxResults` | integer | `5`      | Result count, clamped to `1–20`                                               |
-| `provider`   | string  | auto     | Optional override: `claude`, `codex`, `exa`, `gemini`, `parallel`, or `valyu` |
+| `options`    | object  | —        | Provider-specific search options                                              |
+| `provider`   | string  | auto     | Optional override: `claude`, `codex`, `exa`, `gemini`, `perplexity`, `parallel`, or `valyu` |
 
 ### `web_contents`
 
@@ -107,6 +109,11 @@ Investigate a topic across web sources and produce a longer report.
 | `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
@@ -117,7 +124,8 @@ summarises which capabilities each provider exposes:
 | **Claude**   |   ✓    |          |   ✓    |          | Local Claude Code auth |
 | **Codex**    |   ✓    |          |        |          | Local Codex CLI auth   |
 | **Exa**      |   ✓    |    ✓     |   ✓    |    ✓     | `EXA_API_KEY`          |
-| **Gemini**   |   ✓    |          |   ✓    |    ✓     | `GOOGLE_API_KEY`       |
+| **Gemini**   |   ✓    |    ✓     |   ✓    |    ✓     | `GOOGLE_API_KEY`       |
+| **Perplexity** | ✓    |          |   ✓    |    ✓     | `PERPLEXITY_API_KEY`   |
 | **Parallel** |   ✓    |    ✓     |        |          | `PARALLEL_API_KEY`     |
 | **Valyu**    |   ✓    |    ✓     |   ✓    |    ✓     | `VALYU_API_KEY`        |
 
@@ -126,12 +134,16 @@ summarises which capabilities each provider exposes:
 - 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
@@ -143,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
@@ -220,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": {

package/dist/index.js

@@ -32,7 +32,8 @@ var PROVIDER_TOOLS = {
   claude: ["search", "answer"],
   codex: ["search"],
   exa: ["search", "contents", "answer", "research"],
-  gemini: ["search", "answer", "research"],
+  gemini: ["search", "contents", "answer", "research"],
+  perplexity: ["search", "answer", "research"],
   parallel: ["search", "contents"],
   valyu: ["search", "contents", "answer", "research"]
 };
@@ -195,6 +196,12 @@ function normalizeConfig(raw, source) {
         source
       );
     }
+    if (raw.providers.perplexity !== void 0) {
+      config.providers.perplexity = normalizePerplexityProvider(
+        raw.providers.perplexity,
+        source
+      );
+    }
     if (raw.providers.parallel !== void 0) {
       config.providers.parallel = normalizeParallelProvider(
         raw.providers.parallel,
@@ -208,7 +215,7 @@ function normalizeConfig(raw, source) {
       );
     }
     const unknownProviders = Object.keys(raw.providers).filter(
-      (key) => key !== "claude" && key !== "codex" && key !== "exa" && key !== "gemini" && key !== "parallel" && key !== "valyu"
+      (key) => key !== "claude" && key !== "codex" && key !== "exa" && key !== "gemini" && key !== "perplexity" && key !== "parallel" && key !== "valyu"
     );
     if (unknownProviders.length > 0) {
       throw new Error(
@@ -435,6 +442,11 @@ function normalizeGeminiProvider(raw, source) {
         source,
         "providers.gemini.defaults.searchModel"
       ),
+      contentsModel: parseOptionalString(
+        defaults.contentsModel,
+        source,
+        "providers.gemini.defaults.contentsModel"
+      ),
       answerModel: parseOptionalString(
         defaults.answerModel,
         source,
@@ -448,6 +460,54 @@ function normalizeGeminiProvider(raw, source) {
     }
   };
 }
+function normalizePerplexityProvider(raw, source) {
+  const provider = parseProviderObject(raw, source, "perplexity");
+  const defaults = parseOptionalJsonObject(
+    provider.defaults,
+    source,
+    "providers.perplexity.defaults"
+  );
+  return {
+    enabled: parseOptionalBoolean(
+      provider.enabled,
+      source,
+      "providers.perplexity.enabled"
+    ),
+    tools: parseOptionalProviderTools(
+      "perplexity",
+      provider.tools,
+      source,
+      "providers.perplexity.tools"
+    ),
+    apiKey: parseOptionalString(
+      provider.apiKey,
+      source,
+      "providers.perplexity.apiKey"
+    ),
+    baseUrl: parseOptionalString(
+      provider.baseUrl,
+      source,
+      "providers.perplexity.baseUrl"
+    ),
+    defaults: defaults === void 0 ? void 0 : {
+      search: parseOptionalJsonObject(
+        defaults.search,
+        source,
+        "providers.perplexity.defaults.search"
+      ),
+      answer: parseOptionalJsonObject(
+        defaults.answer,
+        source,
+        "providers.perplexity.defaults.answer"
+      ),
+      research: parseOptionalJsonObject(
+        defaults.research,
+        source,
+        "providers.perplexity.defaults.research"
+      )
+    }
+  };
+}
 function normalizeParallelProvider(raw, source) {
   const provider = parseProviderObject(raw, source, "parallel");
   const defaults = parseOptionalJsonObject(
@@ -698,7 +758,7 @@ var ClaudeProvider = class {
     }
     return { available: true, summary: "enabled" };
   }
-  async search(queryText, maxResults, config, context) {
+  async search(queryText, maxResults, options, config, context) {
     const output = parseClaudeSearchOutput(
       await this.runStructuredQuery({
         prompt: [
@@ -715,7 +775,8 @@ var ClaudeProvider = class {
         schema: SEARCH_OUTPUT_SCHEMA,
         tools: ["WebSearch"],
         config,
-        context
+        context,
+        options
       })
     );
     return {
@@ -738,13 +799,13 @@ var ClaudeProvider = class {
           "Keep the answer concise but informative.",
           "Only cite sources you actually used.",
           "",
-          `User query: ${queryText}`,
-          options ? `Additional options: ${JSON.stringify(options)}` : ""
-        ].filter(Boolean).join("\n"),
+          `User query: ${queryText}`
+        ].join("\n"),
         schema: ANSWER_OUTPUT_SCHEMA,
         tools: ["WebSearch", "WebFetch"],
         config,
-        context
+        context,
+        options
       })
     );
     const lines = [];
@@ -769,7 +830,8 @@ var ClaudeProvider = class {
     schema,
     tools,
     config,
-    context
+    context,
+    options
   }) {
     const abortController = new AbortController();
     if (context.signal?.aborted) {
@@ -785,9 +847,7 @@ var ClaudeProvider = class {
         abortController,
         allowedTools: tools,
         cwd: context.cwd,
-        effort: config.defaults?.effort,
-        maxTurns: config.defaults?.maxTurns,
-        model: config.defaults?.model,
+        ...getClaudeRuntimeOptions(config, options),
         outputFormat: {
           type: "json_schema",
           schema
@@ -939,6 +999,40 @@ function parseStructuredOutput(result) {
     return JSON.parse(match[0]);
   }
 }
+function getClaudeRuntimeOptions(config, options) {
+  const model = readNonEmptyString(options?.model) ?? config.defaults?.model;
+  const effort = readEnum(options?.effort, ["low", "medium", "high", "max"]);
+  const maxTurns = readPositiveInteger(options?.maxTurns);
+  const maxThinkingTokens = readNonNegativeInteger(options?.maxThinkingTokens);
+  const maxBudgetUsd = readPositiveNumber(options?.maxBudgetUsd);
+  const thinking = isPlainObject2(options?.thinking) ? options?.thinking : void 0;
+  return {
+    ...model ? { model } : {},
+    ...effort ?? config.defaults?.effort ? { effort: effort ?? config.defaults?.effort } : {},
+    ...maxTurns ?? config.defaults?.maxTurns ? { maxTurns: maxTurns ?? config.defaults?.maxTurns } : {},
+    ...maxThinkingTokens !== void 0 ? { maxThinkingTokens } : {},
+    ...maxBudgetUsd !== void 0 ? { maxBudgetUsd } : {},
+    ...thinking ? { thinking } : {}
+  };
+}
+function readNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function readPositiveInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : void 0;
+}
+function readNonNegativeInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : void 0;
+}
+function readPositiveNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+function readEnum(value, values) {
+  return typeof value === "string" && values.includes(value) ? value : void 0;
+}
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function parseClaudeSearchOutput(value) {
   const sources = readArray(value, "sources").map((entry) => ({
     title: readString(entry, "title"),
@@ -1042,7 +1136,7 @@ var CodexProvider = class {
     }
     return { available: true, summary: "enabled" };
   }
-  async search(query2, maxResults, config, context) {
+  async search(query2, maxResults, options, config, context) {
     const codex = new Codex({
       codexPathOverride: config.codexPath,
       baseUrl: config.baseUrl,
@@ -1050,18 +1144,9 @@ var CodexProvider = class {
       config: config.config,
       env: resolveEnvMap(config.env)
     });
-    const thread = codex.startThread({
-      additionalDirectories: config.defaults?.additionalDirectories,
-      approvalPolicy: "never",
-      model: config.defaults?.model,
-      modelReasoningEffort: config.defaults?.modelReasoningEffort,
-      networkAccessEnabled: config.defaults?.networkAccessEnabled ?? true,
-      sandboxMode: "read-only",
-      skipGitRepoCheck: true,
-      webSearchEnabled: config.defaults?.webSearchEnabled ?? true,
-      webSearchMode: config.defaults?.webSearchMode ?? "live",
-      workingDirectory: context.cwd
-    });
+    const thread = codex.startThread(
+      buildCodexSearchThreadOptions(config, context.cwd, options)
+    );
     const prompt = [
       "You are performing web research for another coding agent.",
       "Search the public web and return only a JSON object matching the provided schema.",
@@ -1098,6 +1183,50 @@ var CodexProvider = class {
     };
   }
 };
+function buildCodexSearchThreadOptions(config, cwd, options) {
+  const runtimeOptions = getCodexSearchRuntimeOptions(options);
+  return {
+    additionalDirectories: config.defaults?.additionalDirectories,
+    approvalPolicy: "never",
+    model: runtimeOptions.model ?? config.defaults?.model,
+    modelReasoningEffort: runtimeOptions.modelReasoningEffort ?? config.defaults?.modelReasoningEffort,
+    networkAccessEnabled: config.defaults?.networkAccessEnabled ?? true,
+    sandboxMode: "read-only",
+    skipGitRepoCheck: true,
+    webSearchEnabled: config.defaults?.webSearchEnabled ?? true,
+    webSearchMode: runtimeOptions.webSearchMode ?? config.defaults?.webSearchMode ?? "live",
+    workingDirectory: cwd
+  };
+}
+function getCodexSearchRuntimeOptions(options) {
+  if (!options) {
+    return {};
+  }
+  const model = readNonEmptyString2(options.model);
+  const modelReasoningEffort = readEnum2(options.modelReasoningEffort, [
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh"
+  ]);
+  const webSearchMode = readEnum2(options.webSearchMode, [
+    "disabled",
+    "cached",
+    "live"
+  ]);
+  return {
+    ...model ? { model } : {},
+    ...modelReasoningEffort ? { modelReasoningEffort } : {},
+    ...webSearchMode ? { webSearchMode } : {}
+  };
+}
+function readNonEmptyString2(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function readEnum2(value, values) {
+  return typeof value === "string" && values.includes(value) ? value : void 0;
+}
 function hasCodexCredentials(config) {
   if (hasConfiguredReference(config.apiKey)) {
     return true;
@@ -1188,7 +1317,7 @@ var ExaProvider = class {
     }
     return { available: true, summary: "enabled" };
   }
-  async search(query2, maxResults, config, context) {
+  async search(query2, maxResults, searchOptions, config, context) {
     const apiKey = resolveConfigValue(config.apiKey);
     if (!apiKey) {
       throw new Error("Exa is missing an API key.");
@@ -1196,6 +1325,7 @@ var ExaProvider = class {
     const client = new Exa(apiKey, config.baseUrl);
     const options = {
       ...asJsonObject(config.defaults),
+      ...searchOptions ?? {},
       numResults: maxResults
     };
     context.onProgress?.(`Searching Exa for: ${query2}`);
@@ -1304,6 +1434,7 @@ var ExaProvider = class {
 // src/providers/gemini.ts
 import { GoogleGenAI } from "@google/genai";
 var DEFAULT_SEARCH_MODEL = "gemini-2.5-flash";
+var DEFAULT_CONTENTS_MODEL = "gemini-2.5-flash";
 var DEFAULT_ANSWER_MODEL = "gemini-2.5-flash";
 var DEFAULT_RESEARCH_AGENT = "deep-research-pro-preview-12-2025";
 var DEFAULT_POLL_INTERVAL_MS = 3e3;
@@ -1316,12 +1447,14 @@ var GeminiProvider = class {
       enabled: false,
       tools: {
         search: true,
+        contents: true,
         answer: true,
         research: true
       },
       apiKey: "GOOGLE_API_KEY",
       defaults: {
         searchModel: DEFAULT_SEARCH_MODEL,
+        contentsModel: DEFAULT_CONTENTS_MODEL,
         answerModel: DEFAULT_ANSWER_MODEL,
         researchAgent: DEFAULT_RESEARCH_AGENT
       }
@@ -1340,11 +1473,15 @@ var GeminiProvider = class {
     }
     return { available: true, summary: "enabled" };
   }
-  async search(query2, maxResults, config, context) {
+  async search(query2, maxResults, options, config, context) {
     const ai = this.createClient(config);
-    const model = config.defaults?.searchModel ?? DEFAULT_SEARCH_MODEL;
+    const request = buildGeminiSearchRequest(
+      query2,
+      config.defaults?.searchModel ?? DEFAULT_SEARCH_MODEL,
+      options
+    );
     context.onProgress?.(`Searching Gemini for: ${query2}`);
-    const interaction = await createSearchInteraction(ai, model, query2);
+    const interaction = await createSearchInteraction(ai, request);
     const results = await Promise.all(
       extractGoogleSearchResults(interaction.outputs).slice(0, maxResults).map(async (result) => {
         const resolvedUrl = await resolveGoogleSearchUrl(result.url);
@@ -1360,17 +1497,66 @@ var GeminiProvider = class {
       results
     };
   }
+  async contents(urls, options, config, context) {
+    const ai = this.createClient(config);
+    context.onProgress?.(
+      `Fetching contents from Gemini for ${urls.length} URL(s)`
+    );
+    const urlList = urls.map((url) => `- ${url}`).join("\n");
+    const request = buildGeminiGenerateContentRequest({
+      defaultModel: config.defaults?.contentsModel ?? DEFAULT_CONTENTS_MODEL,
+      prompt: `Extract the main textual content from each of the following URLs. For each URL, return the page title followed by the cleaned body text. Preserve the original structure (headings, paragraphs, lists) but remove navigation, ads, and boilerplate.
+
+${urlList}`,
+      options,
+      toolConfig: { urlContext: {} }
+    });
+    const response = await ai.models.generateContent({
+      model: request.model,
+      contents: [request.contents],
+      config: request.config
+    });
+    const text = response.text?.trim() || "";
+    const metadata = extractUrlContextMetadata(response.candidates);
+    const lines = [];
+    if (text) {
+      lines.push(text);
+    }
+    if (metadata.length > 0) {
+      const failures = metadata.filter(
+        (entry) => entry.status !== "URL_RETRIEVAL_STATUS_SUCCESS" && entry.status !== void 0
+      );
+      if (failures.length > 0) {
+        lines.push("");
+        lines.push("Retrieval issues:");
+        for (const failure of failures) {
+          lines.push(`- ${failure.url}: ${failure.status}`);
+        }
+      }
+    }
+    const successCount = metadata.filter(
+      (entry) => entry.status === "URL_RETRIEVAL_STATUS_SUCCESS" || entry.status === void 0
+    ).length;
+    return {
+      provider: this.id,
+      text: lines.join("\n").trimEnd() || "No contents extracted.",
+      summary: `${successCount} of ${urls.length} URL(s) extracted via Gemini`,
+      itemCount: successCount
+    };
+  }
   async answer(query2, options, config, context) {
     const ai = this.createClient(config);
-    const model = config.defaults?.answerModel ?? DEFAULT_ANSWER_MODEL;
+    const request = buildGeminiGenerateContentRequest({
+      defaultModel: config.defaults?.answerModel ?? DEFAULT_ANSWER_MODEL,
+      prompt: query2,
+      options,
+      toolConfig: { googleSearch: {} }
+    });
     context.onProgress?.(`Getting Gemini answer for: ${query2}`);
     const response = await ai.models.generateContent({
-      model,
-      contents: query2,
-      config: {
-        ...options ?? {},
-        tools: [{ googleSearch: {} }]
-      }
+      model: request.model,
+      contents: request.contents,
+      config: request.config
     });
     const lines = [];
     lines.push(response.text?.trim() || "No answer returned.");
@@ -1398,7 +1584,9 @@ var GeminiProvider = class {
     const ai = this.createClient(config);
     const agent = config.defaults?.researchAgent ?? DEFAULT_RESEARCH_AGENT;
     const pollIntervalMs = getPollInterval(options);
-    const requestOptions = stripPollIntervalOption(options);
+    const requestOptions = getGeminiResearchRequestOptions(
+      stripPollIntervalOption(options)
+    );
     const startedAt = Date.now();
     let lastStatus;
     context.onProgress?.("Starting Gemini deep research");
@@ -1503,6 +1691,31 @@ function extractGroundingSources(chunks) {
   }
   return sources;
 }
+function extractUrlContextMetadata(candidates) {
+  const results = [];
+  if (!Array.isArray(candidates)) {
+    return results;
+  }
+  for (const candidate of candidates) {
+    if (typeof candidate !== "object" || candidate === null) {
+      continue;
+    }
+    const metadata = candidate.urlContextMetadata;
+    if (!metadata?.urlMetadata || !Array.isArray(metadata.urlMetadata)) {
+      continue;
+    }
+    for (const entry of metadata.urlMetadata) {
+      if (typeof entry !== "object" || entry === null) {
+        continue;
+      }
+      results.push({
+        url: typeof entry.retrievedUrl === "string" ? entry.retrievedUrl : "unknown",
+        status: typeof entry.urlRetrievalStatus === "string" ? entry.urlRetrievalStatus : void 0
+      });
+    }
+  }
+  return results;
+}
 function formatInteractionOutputs(outputs) {
   const lines = [];
   if (!Array.isArray(outputs)) {
@@ -1549,24 +1762,31 @@ function isGoogleGroundingRedirect(url) {
     return false;
   }
 }
-async function createSearchInteraction(ai, model, query2) {
-  const request = {
-    model,
-    input: query2,
-    tools: [{ type: "google_search" }]
-  };
-  try {
-    return await ai.interactions.create({
-      ...request,
+async function createSearchInteraction(ai, request) {
+  const forcedRequest = {
+    ...request,
+    ...request.generation_config ? {
       generation_config: {
+        ...request.generation_config,
         tool_choice: "any"
       }
-    });
+    } : {
+      generation_config: {
+        tool_choice: "any"
+      }
+    }
+  };
+  try {
+    return await ai.interactions.create(forcedRequest);
   } catch (error) {
     if (!isBuiltInToolChoiceError(error)) {
       throw error;
     }
-    return ai.interactions.create(request);
+    const fallbackGenerationConfig = stripToolChoice(request.generation_config);
+    return ai.interactions.create({
+      ...request,
+      ...fallbackGenerationConfig ? { generation_config: fallbackGenerationConfig } : {}
+    });
   }
 }
 function isBuiltInToolChoiceError(error) {
@@ -1639,6 +1859,244 @@ function stripPollIntervalOption(options) {
   const { pollIntervalMs: _ignored, ...rest } = options;
   return rest;
 }
+function buildGeminiSearchRequest(query2, defaultModel, options) {
+  return {
+    model: readNonEmptyString3(options?.model) ?? defaultModel,
+    input: query2,
+    tools: [{ type: "google_search" }],
+    ...isPlainObject3(options?.generation_config) ? { generation_config: options.generation_config } : {}
+  };
+}
+function buildGeminiGenerateContentRequest({
+  defaultModel,
+  prompt,
+  options,
+  toolConfig
+}) {
+  const requestOptions = isPlainObject3(options) ? options : {};
+  const explicitConfig = isPlainObject3(requestOptions.config) ? requestOptions.config : {};
+  return {
+    model: readNonEmptyString3(requestOptions.model) ?? defaultModel,
+    contents: prompt,
+    config: {
+      ...explicitConfig,
+      tools: [toolConfig]
+    }
+  };
+}
+function getGeminiResearchRequestOptions(options) {
+  if (!isPlainObject3(options)) {
+    return {};
+  }
+  return { ...options };
+}
+function stripToolChoice(generationConfig) {
+  if (!generationConfig || !Object.hasOwn(generationConfig, "tool_choice")) {
+    return generationConfig;
+  }
+  const { tool_choice: _ignored, ...rest } = generationConfig;
+  return Object.keys(rest).length > 0 ? rest : void 0;
+}
+function isPlainObject3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readNonEmptyString3(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+
+// src/providers/perplexity.ts
+import Perplexity from "@perplexity-ai/perplexity_ai";
+var DEFAULT_ANSWER_MODEL2 = "sonar";
+var DEFAULT_RESEARCH_MODEL = "sonar-deep-research";
+var PerplexityProvider = class {
+  id = "perplexity";
+  label = "Perplexity";
+  docsUrl = "https://docs.perplexity.ai/docs/sdk/overview.md";
+  createTemplate() {
+    return {
+      enabled: false,
+      tools: {
+        search: true,
+        answer: true,
+        research: true
+      },
+      apiKey: "PERPLEXITY_API_KEY",
+      defaults: {
+        answer: {
+          model: DEFAULT_ANSWER_MODEL2
+        },
+        research: {
+          model: DEFAULT_RESEARCH_MODEL
+        }
+      }
+    };
+  }
+  getStatus(config) {
+    if (!config) {
+      return { available: false, summary: "not configured" };
+    }
+    if (config.enabled === false) {
+      return { available: false, summary: "disabled" };
+    }
+    const apiKey = resolveConfigValue(config.apiKey);
+    if (!apiKey) {
+      return { available: false, summary: "missing apiKey" };
+    }
+    return { available: true, summary: "enabled" };
+  }
+  async search(query2, maxResults, options, config, context) {
+    const client = this.createClient(config);
+    const request = {
+      ...asJsonObject(config.defaults?.search),
+      ...options ?? {},
+      query: query2,
+      max_results: maxResults
+    };
+    context.onProgress?.(`Searching Perplexity for: ${query2}`);
+    const response = await client.search.create(
+      request,
+      buildRequestOptions(context)
+    );
+    return {
+      provider: this.id,
+      results: response.results.slice(0, maxResults).map((result) => ({
+        title: result.title,
+        url: result.url,
+        snippet: trimSnippet(result.snippet),
+        metadata: result.date || result.last_updated ? {
+          ...result.date ? { date: result.date } : {},
+          ...result.last_updated ? { last_updated: result.last_updated } : {}
+        } : void 0
+      }))
+    };
+  }
+  async answer(query2, options, config, context) {
+    context.onProgress?.(`Getting Perplexity answer for: ${query2}`);
+    return this.runChatTool(
+      query2,
+      options,
+      config,
+      context,
+      DEFAULT_ANSWER_MODEL2,
+      "Answer"
+    );
+  }
+  async research(input, options, config, context) {
+    context.onProgress?.("Starting Perplexity research");
+    return this.runChatTool(
+      input,
+      options,
+      config,
+      context,
+      DEFAULT_RESEARCH_MODEL,
+      "Research",
+      true
+    );
+  }
+  async runChatTool(input, options, config, context, fallbackModel, label, isResearch = false) {
+    const client = this.createClient(config);
+    const defaults = isResearch ? config.defaults?.research : config.defaults?.answer;
+    const request = {
+      ...asJsonObject(defaults),
+      ...options ?? {},
+      messages: [{ role: "user", content: input }],
+      model: resolveModel(
+        (options ?? {}).model,
+        asJsonObject(defaults).model,
+        fallbackModel
+      ) ?? fallbackModel,
+      stream: false
+    };
+    const response = await client.chat.completions.create(
+      request,
+      buildRequestOptions(context)
+    );
+    const content = extractMessageText(response.choices[0]?.message?.content);
+    const sources = dedupeSources(extractSources(response));
+    const lines = [];
+    lines.push(content || `No ${label.toLowerCase()} returned.`);
+    if (sources.length > 0) {
+      lines.push("");
+      lines.push("Sources:");
+      for (const [index, source] of sources.entries()) {
+        lines.push(`${index + 1}. ${source.title}`);
+        lines.push(`   ${source.url}`);
+      }
+    }
+    return {
+      provider: this.id,
+      text: lines.join("\n").trimEnd(),
+      summary: `${label} via Perplexity with ${sources.length} source(s)`,
+      itemCount: sources.length
+    };
+  }
+  createClient(config) {
+    const apiKey = resolveConfigValue(config.apiKey);
+    if (!apiKey) {
+      throw new Error("Perplexity is missing an API key.");
+    }
+    return new Perplexity({
+      apiKey,
+      baseURL: resolveConfigValue(config.baseUrl)
+    });
+  }
+};
+function resolveModel(optionModel, defaultModel, fallbackModel) {
+  if (typeof optionModel === "string" && optionModel.trim().length > 0) {
+    return optionModel;
+  }
+  if (typeof defaultModel === "string" && defaultModel.trim().length > 0) {
+    return defaultModel;
+  }
+  return fallbackModel;
+}
+function extractMessageText(content) {
+  if (typeof content === "string") {
+    return content.trim();
+  }
+  if (!Array.isArray(content)) {
+    return "";
+  }
+  return content.flatMap((chunk) => {
+    if (typeof chunk === "object" && chunk !== null && "type" in chunk && chunk.type === "text" && "text" in chunk && typeof chunk.text === "string") {
+      return [chunk.text.trim()];
+    }
+    return [];
+  }).filter((text) => text.length > 0).join("\n\n").trim();
+}
+function dedupeSources(sources) {
+  const seen = /* @__PURE__ */ new Set();
+  const unique = [];
+  for (const source of sources) {
+    const title = source.title.trim() || source.url.trim() || "Untitled";
+    const url = source.url.trim();
+    if (!url) continue;
+    const key = `${title.toLowerCase()}::${url.toLowerCase()}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    unique.push({ title, url });
+  }
+  return unique;
+}
+function extractSources(response) {
+  const searchResults = response.search_results?.flatMap((result) => {
+    const url = result.url?.trim() ?? "";
+    if (!url) {
+      return [];
+    }
+    return [{ title: result.title?.trim() ?? url, url }];
+  }) ?? [];
+  if (searchResults.length > 0) {
+    return searchResults;
+  }
+  return response.citations?.flatMap((citation) => {
+    const url = citation?.trim() ?? "";
+    return url ? [{ title: url, url }] : [];
+  }) ?? [];
+}
+function buildRequestOptions(context) {
+  return context.signal ? { signal: context.signal } : void 0;
+}
 
 // src/providers/parallel.ts
 import Parallel from "parallel-web";
@@ -1678,12 +2136,13 @@ var ParallelProvider = class {
     }
     return { available: true, summary: "enabled" };
   }
-  async search(query2, maxResults, config, context) {
+  async search(query2, maxResults, options, config, context) {
     const client = this.createClient(config);
     const defaults = asJsonObject(config.defaults?.search);
     context.onProgress?.(`Searching Parallel for: ${query2}`);
     const response = await client.beta.search({
       ...defaults,
+      ...options ?? {},
       objective: query2,
       max_results: maxResults
     });
@@ -1781,7 +2240,7 @@ var ValyuProvider = class {
     }
     return { available: true, summary: "enabled" };
   }
-  async search(query2, maxResults, config, context) {
+  async search(query2, maxResults, searchOptions, config, context) {
     const apiKey = resolveConfigValue(config.apiKey);
     if (!apiKey) {
       throw new Error("Valyu is missing an API key.");
@@ -1789,6 +2248,7 @@ var ValyuProvider = class {
     const client = new Valyu(apiKey, config.baseUrl);
     const options = {
       ...asJsonObject(config.defaults),
+      ...searchOptions ?? {},
       maxNumResults: maxResults
     };
     context.onProgress?.(`Searching Valyu for: ${query2}`);
@@ -1938,6 +2398,7 @@ var PROVIDERS = [
   new CodexProvider(),
   new ExaProvider(),
   new GeminiProvider(),
+  new PerplexityProvider(),
   new ParallelProvider(),
   new ValyuProvider()
 ];
@@ -1946,8 +2407,9 @@ var PROVIDER_MAP = {
   codex: PROVIDERS[1],
   exa: PROVIDERS[2],
   gemini: PROVIDERS[3],
-  parallel: PROVIDERS[4],
-  valyu: PROVIDERS[5]
+  perplexity: PROVIDERS[4],
+  parallel: PROVIDERS[5],
+  valyu: PROVIDERS[6]
 };
 
 // src/provider-resolution.ts
@@ -2025,6 +2487,7 @@ var PROVIDER_IDS = [
   "codex",
   "exa",
   "gemini",
+  "perplexity",
   "parallel",
   "valyu"
 ];
@@ -2093,6 +2556,7 @@ function registerWebSearchTool(pi, providerIds) {
           description: `Maximum number of results to return (default: ${DEFAULT_MAX_RESULTS})`
         })
       ),
+      options: jsonOptionsSchema("Provider-specific search options."),
       provider: providerEnum(
         visibleProviderIds,
         "Provider override. If omitted, uses the active configured provider or falls back to Codex for search when it is not explicitly disabled."
@@ -2109,6 +2573,7 @@ function registerWebSearchTool(pi, providerIds) {
       const response = await provider.search(
         params.query,
         maxResults,
+        normalizeOptions(params.options),
         providerConfig,
         {
           cwd: ctx.cwd,
@@ -2671,6 +3136,11 @@ function buildProviderMenuOptions(providerId) {
       "Search model",
       "Model used for Gemini search interactions."
     );
+    pushText(
+      "geminiContentsModel",
+      "Contents model",
+      "Model used for Gemini URL content extraction via URL Context."
+    );
     pushText(
       "geminiAnswerModel",
       "Answer model",
@@ -2683,6 +3153,9 @@ function buildProviderMenuOptions(providerId) {
     );
     return options;
   }
+  if (providerId === "perplexity") {
+    return options;
+  }
   if (providerId === "parallel") {
     pushValues(
       "parallelSearchMode",
@@ -2862,7 +3335,7 @@ var WebProvidersSettingsView = class {
       ) : key === "model" || key === "additionalDirectories" ? getCodexTextSettingValue(
         providerConfig,
         key
-      ) : key === "geminiSearchModel" || key === "geminiAnswerModel" || key === "geminiResearchAgent" ? getGeminiTextSettingValue(
+      ) : key === "geminiSearchModel" || key === "geminiContentsModel" || key === "geminiAnswerModel" || key === "geminiResearchAgent" ? getGeminiTextSettingValue(
         providerConfig,
         key
       ) : getProviderStringValue(
@@ -3002,7 +3475,7 @@ var WebProvidersSettingsView = class {
         id
       );
     }
-    if (id === "geminiSearchModel" || id === "geminiAnswerModel" || id === "geminiResearchAgent") {
+    if (id === "geminiSearchModel" || id === "geminiContentsModel" || id === "geminiAnswerModel" || id === "geminiResearchAgent") {
       return getGeminiTextSettingValue(
         providerConfig,
         id
@@ -3271,6 +3744,7 @@ function getGeminiTextSettingValue(config, key) {
   const defaults = config?.defaults;
   if (!defaults) return void 0;
   if (key === "geminiSearchModel") return defaults.searchModel;
+  if (key === "geminiContentsModel") return defaults.contentsModel;
   if (key === "geminiAnswerModel") return defaults.answerModel;
   return defaults.researchAgent;
 }
@@ -3442,6 +3916,14 @@ function applyGeminiSettingChange(target, key, value) {
       );
       cleanupGeminiDefaults(target);
       return true;
+    case "geminiContentsModel":
+      assignOptionalString(
+        target.defaults,
+        "contentsModel",
+        value
+      );
+      cleanupGeminiDefaults(target);
+      return true;
     case "geminiAnswerModel":
       assignOptionalString(
         target.defaults,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-web-providers",
-  "version": "0.2.0",
-  "description": "Configurable web access extension for pi that routes search, contents, answers, and research across Claude, Codex, Exa, Gemini, Parallel, and Valyu providers.",
+  "version": "0.3.0",
+  "description": "Configurable web access extension for pi that routes search, contents, answers, and research across Claude, Codex, Exa, Gemini, Perplexity, Parallel, and Valyu providers.",
   "type": "module",
   "files": [
     "dist",
@@ -17,6 +17,7 @@
     "codex",
     "exa",
     "gemini",
+    "perplexity",
     "parallel",
     "valyu"
   ],
@@ -38,7 +39,7 @@
     ]
   },
   "scripts": {
-    "build": "rm -rf dist && esbuild src/index.ts --bundle --format=esm --platform=node --outfile=dist/index.js --external:@mariozechner/pi-coding-agent --external:@mariozechner/pi-ai --external:@mariozechner/pi-tui --external:@sinclair/typebox --external:@anthropic-ai/claude-agent-sdk --external:@google/genai --external:@openai/codex-sdk --external:exa-js --external:parallel-web --external:valyu-js",
+    "build": "rm -rf dist && esbuild src/index.ts --bundle --format=esm --platform=node --outfile=dist/index.js --external:@mariozechner/pi-coding-agent --external:@mariozechner/pi-ai --external:@mariozechner/pi-tui --external:@sinclair/typebox --external:@anthropic-ai/claude-agent-sdk --external:@google/genai --external:@openai/codex-sdk --external:@perplexity-ai/perplexity_ai --external:exa-js --external:parallel-web --external:valyu-js",
     "prepare": "npm run build",
     "prepack": "npm run build",
     "check": "tsc --noEmit",
@@ -51,6 +52,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.2.71",
     "@google/genai": "^1.44.0",
     "@openai/codex-sdk": "^0.111.0",
+    "@perplexity-ai/perplexity_ai": "^0.26.1",
     "exa-js": "^2.7.0",
     "parallel-web": "^0.3.1",
     "valyu-js": "^2.5.9",