@tanstack/ai-perplexity 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# @tanstack/ai-perplexity
+
+[Perplexity](https://www.perplexity.ai) Search API for [TanStack AI](https://tanstack.com/ai).
+
+Wraps `POST https://api.perplexity.ai/search` as a tool (and a low-level HTTP client) so an agent can fetch ranked web results (`title`, `url`, `snippet`, `date?`, `last_updated?`) for grounding.
+
+This package does **not** ship a TanStack text adapter. Pair the search tool with a function-calling adapter such as `openaiText`. For Sonar `chat()`, use [`openaiCompatible`](https://tanstack.com/ai/latest/docs/adapters/openai-compatible) from `@tanstack/ai-openai/compatible` — Sonar already searches the web and does not accept custom tools.
+
+## Install
+
+```bash
+pnpm add @tanstack/ai @tanstack/ai-openai @tanstack/ai-perplexity
+```
+
+Set your API key (get one at <https://console.perplexity.ai/group/keys>):
+
+```bash
+export PERPLEXITY_API_KEY=...
+# PPLX_API_KEY is also accepted
+```
+
+## Search tool
+
+```ts
+import { chat } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { perplexitySearchTool } from '@tanstack/ai-perplexity'
+
+const search = perplexitySearchTool({
+  defaultMaxResults: 5,
+})
+
+const stream = chat({
+  adapter: openaiText('gpt-5.2'),
+  tools: [search],
+  messages: [
+    { role: 'user', content: 'What were the top AI papers this week?' },
+  ],
+})
+```
+
+The tool input schema accepts:
+
+| field                       | type                                             | notes                                                                                  |
+| --------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| `query`                     | `string` (required)                              | The search query.                                                                      |
+| `max_results`               | `integer` (1–20)                                 | Defaults to `defaultMaxResults` when set, otherwise the API default (10).              |
+| `search_domain_filter`      | `string[]`                                       | Max 20. Allowlist (`"nytimes.com"`) **or** denylist (`"-pinterest.com"`) — never both. |
+| `search_recency_filter`     | `"hour" \| "day" \| "week" \| "month" \| "year"` | Recency window.                                                                        |
+| `search_after_date_filter`  | `string`                                         | `m/d/yyyy` — only results on/after this date.                                          |
+| `search_before_date_filter` | `string`                                         | `m/d/yyyy` — only results on/before this date.                                         |
+
+Output: `{ results: Array<{ title, url, snippet, date?, last_updated? }> }`.
+
+### Direct client usage
+
+```ts
+import { PerplexitySearchClient } from '@tanstack/ai-perplexity'
+
+const client = new PerplexitySearchClient()
+const { results } = await client.search({
+  query: 'mars sample return mission',
+  max_results: 5,
+  search_recency_filter: 'month',
+})
+```
+
+## Chat (Sonar)
+
+Use `openaiCompatible` from `@tanstack/ai-openai/compatible`. Do not pass `perplexitySearchTool` here. Pass `getPerplexityIntegrationHeaders()` if you want the same `X-Pplx-Integration` attribution header the Search client sends automatically.
+
+```ts
+import { chat } from '@tanstack/ai'
+import { openaiCompatible } from '@tanstack/ai-openai/compatible'
+import { getPerplexityIntegrationHeaders } from '@tanstack/ai-perplexity'
+
+const perplexity = openaiCompatible({
+  name: 'perplexity',
+  baseURL: 'https://api.perplexity.ai',
+  apiKey: process.env.PERPLEXITY_API_KEY!,
+  models: ['sonar', 'sonar-pro'],
+  defaultHeaders: getPerplexityIntegrationHeaders(),
+})
+
+const stream = chat({
+  adapter: perplexity('sonar'),
+  messages: [
+    { role: 'user', content: 'What is the latest on the Mars rover?' },
+  ],
+})
+```
+
+## Docs
+
+- Search quickstart: <https://docs.perplexity.ai/docs/search/quickstart>
+- Search API reference: <https://docs.perplexity.ai/api-reference/search-post>
+- Domain filters: <https://docs.perplexity.ai/docs/search/filters/domain-filter>
+- Date / recency filters: <https://docs.perplexity.ai/docs/search/filters/date-time-filters>

package/dist/esm/index.d.ts

@@ -0,0 +1,3 @@
+export { PerplexitySearchClient, perplexitySearchTool, type PerplexitySearchClientConfig, type PerplexitySearchRequest, type PerplexitySearchResponse, type PerplexitySearchResult, } from './search/index.js';
+export { getPerplexityApiKeyFromEnv } from './utils/api-key.js';
+export { getPerplexityIntegrationHeaders, PERPLEXITY_INTEGRATION_HEADER, PERPLEXITY_INTEGRATION_HEADER_VALUE, } from './utils/attribution.js';

package/dist/esm/index.js

@@ -0,0 +1,6 @@
+import { getPerplexityApiKeyFromEnv } from "./utils/api-key.js";
+import { PERPLEXITY_INTEGRATION_HEADER, PERPLEXITY_INTEGRATION_HEADER_VALUE, getPerplexityIntegrationHeaders } from "./utils/attribution.js";
+import { PerplexitySearchClient } from "./search/client.js";
+import { perplexitySearchTool } from "./search/tool.js";
+import "./search/index.js";
+export { PERPLEXITY_INTEGRATION_HEADER, PERPLEXITY_INTEGRATION_HEADER_VALUE, PerplexitySearchClient, getPerplexityApiKeyFromEnv, getPerplexityIntegrationHeaders, perplexitySearchTool };

package/dist/esm/search/client.d.ts

@@ -0,0 +1,55 @@
+export interface PerplexitySearchClientConfig {
+    /** Perplexity API key. Falls back to `PERPLEXITY_API_KEY` / `PPLX_API_KEY` env vars. */
+    apiKey?: string;
+    /** Override the API base URL (defaults to https://api.perplexity.ai). */
+    baseURL?: string;
+    /** Optional `fetch` implementation; defaults to globalThis.fetch. */
+    fetch?: typeof fetch;
+}
+export interface PerplexitySearchRequest {
+    /** The search query, or up to 5 queries. */
+    query: string | ReadonlyArray<string>;
+    /** Maximum number of results to return (1–20). Defaults to the API default (10). */
+    max_results?: number;
+    /** Maximum tokens of content to return per page. */
+    max_tokens_per_page?: number;
+    /**
+     * Restrict (or exclude) results by domain (max 20 entries).
+     *
+     * Hostnames, optional paths, or TLDs. Use bare entries to allowlist
+     * (`["nytimes.com"]`) or `-` prefixed entries to denylist
+     * (`["-pinterest.com"]`). Allow and deny entries must NOT be mixed.
+     */
+    search_domain_filter?: Array<string>;
+    /** Restrict results by recency: `hour | day | week | month | year`. */
+    search_recency_filter?: 'hour' | 'day' | 'week' | 'month' | 'year';
+    /** Only include results published on or after this date (m/d/yyyy). */
+    search_after_date_filter?: string;
+    /** Only include results published on or before this date (m/d/yyyy). */
+    search_before_date_filter?: string;
+}
+export interface PerplexitySearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+    date?: string;
+    last_updated?: string;
+}
+export interface PerplexitySearchResponse {
+    id?: string;
+    results: Array<PerplexitySearchResult>;
+}
+/**
+ * Low-level HTTP client for the Perplexity Search API.
+ *
+ * Calls `POST {baseURL}/search` with bearer auth.
+ */
+export declare class PerplexitySearchClient {
+    private readonly apiKey;
+    private readonly baseURL;
+    private readonly fetchImpl;
+    constructor(config?: PerplexitySearchClientConfig);
+    search(request: PerplexitySearchRequest, init?: {
+        signal?: AbortSignal;
+    }): Promise<PerplexitySearchResponse>;
+}

package/dist/esm/search/client.js

@@ -0,0 +1,110 @@
+import { getPerplexityApiKeyFromEnv } from "../utils/api-key.js";
+import { getPerplexityIntegrationHeaders } from "../utils/attribution.js";
+//#region src/search/client.ts
+var DEFAULT_BASE_URL = "https://api.perplexity.ai";
+var MAX_QUERY_BATCH = 5;
+var MAX_DOMAIN_FILTER = 20;
+/**
+* Low-level HTTP client for the Perplexity Search API.
+*
+* Calls `POST {baseURL}/search` with bearer auth.
+*/
+var PerplexitySearchClient = class {
+	apiKey;
+	baseURL;
+	fetchImpl;
+	constructor(config = {}) {
+		const { apiKey } = config;
+		const resolvedApiKey = typeof apiKey === "string" && apiKey.trim().length > 0 ? apiKey : getPerplexityApiKeyFromEnv();
+		this.apiKey = resolvedApiKey;
+		this.baseURL = (config.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+		this.fetchImpl = config.fetch ?? globalThis.fetch;
+	}
+	async search(request, init = {}) {
+		const query = normalizeQuery(request.query);
+		validateDomainFilter(request.search_domain_filter);
+		const body = { query };
+		if (request.max_results !== void 0) body.max_results = requireMaxResults(request.max_results);
+		if (request.max_tokens_per_page !== void 0) body.max_tokens_per_page = request.max_tokens_per_page;
+		if (request.search_domain_filter) body.search_domain_filter = request.search_domain_filter;
+		if (request.search_recency_filter) body.search_recency_filter = request.search_recency_filter;
+		if (request.search_after_date_filter) body.search_after_date_filter = request.search_after_date_filter;
+		if (request.search_before_date_filter) body.search_before_date_filter = request.search_before_date_filter;
+		const response = await this.fetchImpl(`${this.baseURL}/search`, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${this.apiKey}`,
+				"Content-Type": "application/json",
+				Accept: "application/json",
+				...getPerplexityIntegrationHeaders()
+			},
+			body: JSON.stringify(body),
+			signal: init.signal
+		});
+		if (!response.ok) {
+			const text = await safeReadText(response);
+			throw new Error(`Perplexity Search API request failed: ${response.status} ${response.statusText}${text ? ` — ${text}` : ""}`);
+		}
+		return parseSearchResponse(await response.json());
+	}
+};
+function normalizeQuery(query) {
+	if (typeof query === "string") {
+		const trimmed = query.trim();
+		if (trimmed.length === 0) throw new Error("PerplexitySearchClient.search requires a non-empty `query`.");
+		return trimmed;
+	}
+	if (query.length === 0) throw new Error("PerplexitySearchClient.search requires a non-empty `query`.");
+	if (query.length > MAX_QUERY_BATCH) throw new Error(`query array must contain at most ${MAX_QUERY_BATCH} entries.`);
+	return query.map((entry) => {
+		if (typeof entry !== "string" || entry.trim().length === 0) throw new Error("PerplexitySearchClient.search requires a non-empty `query`.");
+		return entry.trim();
+	});
+}
+function requireMaxResults(maxResults) {
+	if (!Number.isInteger(maxResults) || maxResults < 1 || maxResults > 20) throw new Error("max_results must be an integer between 1 and 20.");
+	return maxResults;
+}
+function validateDomainFilter(filter) {
+	if (!filter || filter.length === 0) return;
+	if (filter.length > MAX_DOMAIN_FILTER) throw new Error(`search_domain_filter must contain at most ${MAX_DOMAIN_FILTER} entries.`);
+	let hasAllow = false;
+	let hasDeny = false;
+	for (const entry of filter) {
+		if (typeof entry !== "string" || entry.length === 0) continue;
+		if (entry.startsWith("-")) hasDeny = true;
+		else hasAllow = true;
+	}
+	if (hasAllow && hasDeny) throw new Error("search_domain_filter cannot mix allowlist and denylist entries. Use only `-domain.com` for negation, or only bare domains for allowlist.");
+}
+function isSearchResult(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const result = value;
+	return typeof result.title === "string" && typeof result.url === "string" && typeof result.snippet === "string" && (result.date === void 0 || result.date === null || typeof result.date === "string") && (result.last_updated === void 0 || result.last_updated === null || typeof result.last_updated === "string");
+}
+function parseSearchResponse(value) {
+	if (typeof value !== "object" || value === null) throw new Error("Perplexity Search API returned an invalid response.");
+	const data = value;
+	if (!Array.isArray(data.results) || !data.results.every(isSearchResult)) throw new Error("Perplexity Search API returned an invalid response.");
+	return {
+		...typeof data.id === "string" ? { id: data.id } : {},
+		results: data.results.map((result) => ({
+			title: result.title,
+			url: result.url,
+			snippet: result.snippet,
+			...result.date ? { date: result.date } : {},
+			...result.last_updated ? { last_updated: result.last_updated } : {}
+		}))
+	};
+}
+async function safeReadText(response) {
+	try {
+		return await response.text();
+	} catch {
+		return "";
+	}
+}
+//#endregion
+export { PerplexitySearchClient };
+
+//# sourceMappingURL=client.js.map

package/dist/esm/search/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":[],"sources":["../../../src/search/client.ts"],"sourcesContent":["import { getPerplexityApiKeyFromEnv } from '../utils/api-key'\nimport { getPerplexityIntegrationHeaders } from '../utils/attribution'\n\nexport interface PerplexitySearchClientConfig {\n  /** Perplexity API key. Falls back to `PERPLEXITY_API_KEY` / `PPLX_API_KEY` env vars. */\n  apiKey?: string\n  /** Override the API base URL (defaults to https://api.perplexity.ai). */\n  baseURL?: string\n  /** Optional `fetch` implementation; defaults to globalThis.fetch. */\n  fetch?: typeof fetch\n}\n\nexport interface PerplexitySearchRequest {\n  /** The search query, or up to 5 queries. */\n  query: string | ReadonlyArray<string>\n  /** Maximum number of results to return (1–20). Defaults to the API default (10). */\n  max_results?: number\n  /** Maximum tokens of content to return per page. */\n  max_tokens_per_page?: number\n  /**\n   * Restrict (or exclude) results by domain (max 20 entries).\n   *\n   * Hostnames, optional paths, or TLDs. Use bare entries to allowlist\n   * (`[\"nytimes.com\"]`) or `-` prefixed entries to denylist\n   * (`[\"-pinterest.com\"]`). Allow and deny entries must NOT be mixed.\n   */\n  search_domain_filter?: Array<string>\n  /** Restrict results by recency: `hour | day | week | month | year`. */\n  search_recency_filter?: 'hour' | 'day' | 'week' | 'month' | 'year'\n  /** Only include results published on or after this date (m/d/yyyy). */\n  search_after_date_filter?: string\n  /** Only include results published on or before this date (m/d/yyyy). */\n  search_before_date_filter?: string\n}\n\nexport interface PerplexitySearchResult {\n  title: string\n  url: string\n  snippet: string\n  date?: string\n  last_updated?: string\n}\n\nexport interface PerplexitySearchResponse {\n  id?: string\n  results: Array<PerplexitySearchResult>\n}\n\nconst DEFAULT_BASE_URL = 'https://api.perplexity.ai'\nconst MAX_QUERY_BATCH = 5\nconst MAX_DOMAIN_FILTER = 20\n\n/**\n * Low-level HTTP client for the Perplexity Search API.\n *\n * Calls `POST {baseURL}/search` with bearer auth.\n */\nexport class PerplexitySearchClient {\n  private readonly apiKey: string\n  private readonly baseURL: string\n  private readonly fetchImpl: typeof fetch\n\n  constructor(config: PerplexitySearchClientConfig = {}) {\n    const { apiKey } = config\n    const resolvedApiKey =\n      typeof apiKey === 'string' && apiKey.trim().length > 0\n        ? apiKey\n        : getPerplexityApiKeyFromEnv()\n\n    this.apiKey = resolvedApiKey\n    this.baseURL = (config.baseURL ?? DEFAULT_BASE_URL).replace(/\\/$/, '')\n    this.fetchImpl = config.fetch ?? globalThis.fetch\n  }\n\n  async search(\n    request: PerplexitySearchRequest,\n    init: { signal?: AbortSignal } = {},\n  ): Promise<PerplexitySearchResponse> {\n    const query = normalizeQuery(request.query)\n    validateDomainFilter(request.search_domain_filter)\n\n    const body: Record<string, unknown> = { query }\n    if (request.max_results !== undefined)\n      body.max_results = requireMaxResults(request.max_results)\n    if (request.max_tokens_per_page !== undefined)\n      body.max_tokens_per_page = request.max_tokens_per_page\n    if (request.search_domain_filter)\n      body.search_domain_filter = request.search_domain_filter\n    if (request.search_recency_filter)\n      body.search_recency_filter = request.search_recency_filter\n    if (request.search_after_date_filter)\n      body.search_after_date_filter = request.search_after_date_filter\n    if (request.search_before_date_filter)\n      body.search_before_date_filter = request.search_before_date_filter\n\n    const response = await this.fetchImpl(`${this.baseURL}/search`, {\n      method: 'POST',\n      headers: {\n        Authorization: `Bearer ${this.apiKey}`,\n        'Content-Type': 'application/json',\n        Accept: 'application/json',\n        ...getPerplexityIntegrationHeaders(),\n      },\n      body: JSON.stringify(body),\n      signal: init.signal,\n    })\n\n    if (!response.ok) {\n      const text = await safeReadText(response)\n      throw new Error(\n        `Perplexity Search API request failed: ${response.status} ${response.statusText}${\n          text ? ` — ${text}` : ''\n        }`,\n      )\n    }\n\n    return parseSearchResponse(await response.json())\n  }\n}\n\nfunction normalizeQuery(\n  query: string | ReadonlyArray<string>,\n): string | Array<string> {\n  if (typeof query === 'string') {\n    const trimmed = query.trim()\n    if (trimmed.length === 0) {\n      throw new Error(\n        'PerplexitySearchClient.search requires a non-empty `query`.',\n      )\n    }\n    return trimmed\n  }\n\n  if (query.length === 0) {\n    throw new Error(\n      'PerplexitySearchClient.search requires a non-empty `query`.',\n    )\n  }\n  if (query.length > MAX_QUERY_BATCH) {\n    throw new Error(\n      `query array must contain at most ${MAX_QUERY_BATCH} entries.`,\n    )\n  }\n\n  return query.map((entry) => {\n    if (typeof entry !== 'string' || entry.trim().length === 0) {\n      throw new Error(\n        'PerplexitySearchClient.search requires a non-empty `query`.',\n      )\n    }\n    return entry.trim()\n  })\n}\n\nfunction requireMaxResults(maxResults: number): number {\n  if (!Number.isInteger(maxResults) || maxResults < 1 || maxResults > 20) {\n    throw new Error('max_results must be an integer between 1 and 20.')\n  }\n  return maxResults\n}\n\nfunction validateDomainFilter(filter: Array<string> | undefined): void {\n  if (!filter || filter.length === 0) return\n  if (filter.length > MAX_DOMAIN_FILTER) {\n    throw new Error(\n      `search_domain_filter must contain at most ${MAX_DOMAIN_FILTER} entries.`,\n    )\n  }\n  let hasAllow = false\n  let hasDeny = false\n  for (const entry of filter) {\n    if (typeof entry !== 'string' || entry.length === 0) continue\n    if (entry.startsWith('-')) hasDeny = true\n    else hasAllow = true\n  }\n  if (hasAllow && hasDeny) {\n    throw new Error(\n      'search_domain_filter cannot mix allowlist and denylist entries. Use only `-domain.com` for negation, or only bare domains for allowlist.',\n    )\n  }\n}\n\nfunction isSearchResult(value: unknown): value is PerplexitySearchResult {\n  if (typeof value !== 'object' || value === null) return false\n  const result = value as {\n    title?: unknown\n    url?: unknown\n    snippet?: unknown\n    date?: unknown\n    last_updated?: unknown\n  }\n  return (\n    typeof result.title === 'string' &&\n    typeof result.url === 'string' &&\n    typeof result.snippet === 'string' &&\n    (result.date === undefined ||\n      result.date === null ||\n      typeof result.date === 'string') &&\n    (result.last_updated === undefined ||\n      result.last_updated === null ||\n      typeof result.last_updated === 'string')\n  )\n}\n\nfunction parseSearchResponse(value: unknown): PerplexitySearchResponse {\n  if (typeof value !== 'object' || value === null) {\n    throw new Error('Perplexity Search API returned an invalid response.')\n  }\n  const data = value as { id?: unknown; results?: unknown }\n  if (!Array.isArray(data.results) || !data.results.every(isSearchResult)) {\n    throw new Error('Perplexity Search API returned an invalid response.')\n  }\n  return {\n    ...(typeof data.id === 'string' ? { id: data.id } : {}),\n    results: data.results.map((result) => ({\n      title: result.title,\n      url: result.url,\n      snippet: result.snippet,\n      ...(result.date ? { date: result.date } : {}),\n      ...(result.last_updated ? { last_updated: result.last_updated } : {}),\n    })),\n  }\n}\n\nasync function safeReadText(response: Response): Promise<string> {\n  try {\n    return await response.text()\n  } catch {\n    return ''\n  }\n}\n"],"mappings":"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"}

package/dist/esm/search/index.d.ts

@@ -0,0 +1,2 @@
+export { PerplexitySearchClient, type PerplexitySearchClientConfig, type PerplexitySearchRequest, type PerplexitySearchResponse, type PerplexitySearchResult, } from './client.js';
+export { perplexitySearchTool } from './tool.js';

package/dist/esm/search/index.js

@@ -0,0 +1,3 @@
+import { PerplexitySearchClient } from "./client.js";
+import { perplexitySearchTool } from "./tool.js";
+export { PerplexitySearchClient, perplexitySearchTool };

package/dist/esm/search/tool.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { PerplexitySearchClientConfig } from './client.js';
+/**
+ * Build a TanStack AI tool that performs real-time web search via Perplexity.
+ *
+ * Returns `{ results: Array<{ title, url, snippet, date?, last_updated? }> }`
+ * for citation/grounding in an LLM agent loop.
+ *
+ * @example
+ * ```ts
+ * import { chat } from '@tanstack/ai'
+ * import { openaiText } from '@tanstack/ai-openai'
+ * import { perplexitySearchTool } from '@tanstack/ai-perplexity'
+ *
+ * const search = perplexitySearchTool({ defaultMaxResults: 5 })
+ * chat({ adapter: openaiText('gpt-5.2'), tools: [search], messages })
+ * ```
+ */
+export declare function perplexitySearchTool(config?: PerplexitySearchClientConfig & {
+    /** Override the tool name (defaults to `perplexity_search`). */
+    name?: string;
+    /** Override the tool description shown to the model. */
+    description?: string;
+    /** Default max_results applied when the model does not provide one. */
+    defaultMaxResults?: number;
+}): import('@tanstack/ai').ServerTool<z.ZodObject<{
+    query: z.ZodString;
+    max_results: z.ZodOptional<z.ZodNumber>;
+    search_domain_filter: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    search_recency_filter: z.ZodOptional<z.ZodEnum<{
+        hour: "hour";
+        day: "day";
+        week: "week";
+        month: "month";
+        year: "year";
+    }>>;
+    search_after_date_filter: z.ZodOptional<z.ZodString>;
+    search_before_date_filter: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        url: z.ZodString;
+        snippet: z.ZodString;
+        date: z.ZodOptional<z.ZodString>;
+        last_updated: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, string, unknown, false, undefined> & {
+    inputSchema: z.ZodObject<{
+        query: z.ZodString;
+        max_results: z.ZodOptional<z.ZodNumber>;
+        search_domain_filter: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        search_recency_filter: z.ZodOptional<z.ZodEnum<{
+            hour: "hour";
+            day: "day";
+            week: "week";
+            month: "month";
+            year: "year";
+        }>>;
+        search_after_date_filter: z.ZodOptional<z.ZodString>;
+        search_before_date_filter: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    outputSchema: z.ZodObject<{
+        results: z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            url: z.ZodString;
+            snippet: z.ZodString;
+            date: z.ZodOptional<z.ZodString>;
+            last_updated: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    approvalSchema: undefined;
+};

package/dist/esm/search/tool.js

@@ -0,0 +1,76 @@
+import { PerplexitySearchClient } from "./client.js";
+import { toolDefinition } from "@tanstack/ai";
+import { z } from "zod";
+//#region src/search/tool.ts
+var searchRecency = z.enum([
+	"hour",
+	"day",
+	"week",
+	"month",
+	"year"
+]);
+var inputSchema = z.object({
+	query: z.string().min(1).describe("The search query string."),
+	max_results: z.number().int().min(1).max(20).optional().describe("Maximum number of results to return. Defaults to defaultMaxResults when configured, otherwise the API default (10)."),
+	search_domain_filter: z.array(z.string()).max(20).optional().describe("Restrict results by domain (max 20). Use bare hostnames to allowlist (e.g. [\"nytimes.com\"]) or \"-domain.com\" to denylist. Allow and deny entries must NOT be mixed."),
+	search_recency_filter: searchRecency.optional().describe("Only include results from the given recency window."),
+	search_after_date_filter: z.string().optional().describe("Only include results published on or after this date (m/d/yyyy)."),
+	search_before_date_filter: z.string().optional().describe("Only include results published on or before this date (m/d/yyyy).")
+});
+var outputSchema = z.object({ results: z.array(z.object({
+	title: z.string(),
+	url: z.string(),
+	snippet: z.string(),
+	date: z.string().optional(),
+	last_updated: z.string().optional()
+})) });
+/**
+* Build a TanStack AI tool that performs real-time web search via Perplexity.
+*
+* Returns `{ results: Array<{ title, url, snippet, date?, last_updated? }> }`
+* for citation/grounding in an LLM agent loop.
+*
+* @example
+* ```ts
+* import { chat } from '@tanstack/ai'
+* import { openaiText } from '@tanstack/ai-openai'
+* import { perplexitySearchTool } from '@tanstack/ai-perplexity'
+*
+* const search = perplexitySearchTool({ defaultMaxResults: 5 })
+* chat({ adapter: openaiText('gpt-5.2'), tools: [search], messages })
+* ```
+*/
+function perplexitySearchTool(config = {}) {
+	const { name, description, defaultMaxResults, ...clientConfig } = config;
+	if (defaultMaxResults !== void 0 && (!Number.isInteger(defaultMaxResults) || defaultMaxResults < 1 || defaultMaxResults > 20)) throw new Error("defaultMaxResults must be an integer between 1 and 20.");
+	let client = null;
+	const getClient = () => {
+		if (!client) client = new PerplexitySearchClient(clientConfig);
+		return client;
+	};
+	return toolDefinition({
+		name: name ?? "perplexity_search",
+		description: description ?? "Search the web for up-to-date information using the Perplexity Search API. Returns a ranked list of web results with titles, URLs, snippets, and optional publication dates.",
+		inputSchema,
+		outputSchema
+	}).server(async (args, ctx) => {
+		return { results: (await getClient().search({
+			query: args.query,
+			max_results: args.max_results ?? defaultMaxResults,
+			search_domain_filter: args.search_domain_filter,
+			search_recency_filter: args.search_recency_filter,
+			search_after_date_filter: args.search_after_date_filter,
+			search_before_date_filter: args.search_before_date_filter
+		}, { signal: ctx?.abortSignal })).results.map((result) => ({
+			title: result.title,
+			url: result.url,
+			snippet: result.snippet,
+			...result.date ? { date: result.date } : {},
+			...result.last_updated ? { last_updated: result.last_updated } : {}
+		})) };
+	});
+}
+//#endregion
+export { perplexitySearchTool };
+
+//# sourceMappingURL=tool.js.map

package/dist/esm/search/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","names":[],"sources":["../../../src/search/tool.ts"],"sourcesContent":["import { toolDefinition } from '@tanstack/ai'\nimport { z } from 'zod'\nimport { PerplexitySearchClient } from './client'\nimport type { PerplexitySearchClientConfig } from './client'\n\nconst searchRecency = z.enum(['hour', 'day', 'week', 'month', 'year'])\n\nconst inputSchema = z.object({\n  query: z.string().min(1).describe('The search query string.'),\n  max_results: z\n    .number()\n    .int()\n    .min(1)\n    .max(20)\n    .optional()\n    .describe(\n      'Maximum number of results to return. Defaults to defaultMaxResults when configured, otherwise the API default (10).',\n    ),\n  search_domain_filter: z\n    .array(z.string())\n    .max(20)\n    .optional()\n    .describe(\n      'Restrict results by domain (max 20). Use bare hostnames to allowlist (e.g. [\"nytimes.com\"]) or \"-domain.com\" to denylist. Allow and deny entries must NOT be mixed.',\n    ),\n  search_recency_filter: searchRecency\n    .optional()\n    .describe('Only include results from the given recency window.'),\n  search_after_date_filter: z\n    .string()\n    .optional()\n    .describe(\n      'Only include results published on or after this date (m/d/yyyy).',\n    ),\n  search_before_date_filter: z\n    .string()\n    .optional()\n    .describe(\n      'Only include results published on or before this date (m/d/yyyy).',\n    ),\n})\n\nconst outputSchema = z.object({\n  results: z.array(\n    z.object({\n      title: z.string(),\n      url: z.string(),\n      snippet: z.string(),\n      date: z.string().optional(),\n      last_updated: z.string().optional(),\n    }),\n  ),\n})\n\n/**\n * Build a TanStack AI tool that performs real-time web search via Perplexity.\n *\n * Returns `{ results: Array<{ title, url, snippet, date?, last_updated? }> }`\n * for citation/grounding in an LLM agent loop.\n *\n * @example\n * ```ts\n * import { chat } from '@tanstack/ai'\n * import { openaiText } from '@tanstack/ai-openai'\n * import { perplexitySearchTool } from '@tanstack/ai-perplexity'\n *\n * const search = perplexitySearchTool({ defaultMaxResults: 5 })\n * chat({ adapter: openaiText('gpt-5.2'), tools: [search], messages })\n * ```\n */\nexport function perplexitySearchTool(\n  config: PerplexitySearchClientConfig & {\n    /** Override the tool name (defaults to `perplexity_search`). */\n    name?: string\n    /** Override the tool description shown to the model. */\n    description?: string\n    /** Default max_results applied when the model does not provide one. */\n    defaultMaxResults?: number\n  } = {},\n) {\n  const { name, description, defaultMaxResults, ...clientConfig } = config\n  if (\n    defaultMaxResults !== undefined &&\n    (!Number.isInteger(defaultMaxResults) ||\n      defaultMaxResults < 1 ||\n      defaultMaxResults > 20)\n  ) {\n    throw new Error('defaultMaxResults must be an integer between 1 and 20.')\n  }\n\n  // Lazily construct the client so missing API keys don't blow up at import\n  // time (e.g. on bundlers that statically evaluate module top-level).\n  let client: PerplexitySearchClient | null = null\n  const getClient = () => {\n    if (!client) client = new PerplexitySearchClient(clientConfig)\n    return client\n  }\n\n  return toolDefinition({\n    name: name ?? 'perplexity_search',\n    description:\n      description ??\n      'Search the web for up-to-date information using the Perplexity Search API. Returns a ranked list of web results with titles, URLs, snippets, and optional publication dates.',\n    inputSchema,\n    outputSchema,\n  }).server(async (args, ctx) => {\n    const response = await getClient().search(\n      {\n        query: args.query,\n        max_results: args.max_results ?? defaultMaxResults,\n        search_domain_filter: args.search_domain_filter,\n        search_recency_filter: args.search_recency_filter,\n        search_after_date_filter: args.search_after_date_filter,\n        search_before_date_filter: args.search_before_date_filter,\n      },\n      { signal: ctx?.abortSignal },\n    )\n\n    return {\n      results: response.results.map((result) => ({\n        title: result.title,\n        url: result.url,\n        snippet: result.snippet,\n        ...(result.date ? { date: result.date } : {}),\n        ...(result.last_updated ? { last_updated: result.last_updated } : {}),\n      })),\n    }\n  })\n}\n"],"mappings":";;;;AAKA,IAAM,gBAAgB,EAAE,KAAK;CAAC;CAAQ;CAAO;CAAQ;CAAS;AAAM,CAAC;AAErE,IAAM,cAAc,EAAE,OAAO;CAC3B,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,0BAA0B;CAC5D,aAAa,EACV,OAAO,CAAC,CACR,IAAI,CAAC,CACL,IAAI,CAAC,CAAC,CACN,IAAI,EAAE,CAAC,CACP,SAAS,CAAC,CACV,SACC,qHACF;CACF,sBAAsB,EACnB,MAAM,EAAE,OAAO,CAAC,CAAC,CACjB,IAAI,EAAE,CAAC,CACP,SAAS,CAAC,CACV,SACC,yKACF;CACF,uBAAuB,cACpB,SAAS,CAAC,CACV,SAAS,qDAAqD;CACjE,0BAA0B,EACvB,OAAO,CAAC,CACR,SAAS,CAAC,CACV,SACC,kEACF;CACF,2BAA2B,EACxB,OAAO,CAAC,CACR,SAAS,CAAC,CACV,SACC,mEACF;AACJ,CAAC;AAED,IAAM,eAAe,EAAE,OAAO,EAC5B,SAAS,EAAE,MACT,EAAE,OAAO;CACP,OAAO,EAAE,OAAO;CAChB,KAAK,EAAE,OAAO;CACd,SAAS,EAAE,OAAO;CAClB,MAAM,EAAE,OAAO,CAAC,CAAC,SAAS;CAC1B,cAAc,EAAE,OAAO,CAAC,CAAC,SAAS;AACpC,CAAC,CACH,EACF,CAAC;;;;;;;;;;;;;;;;;AAkBD,SAAgB,qBACd,SAOI,CAAC,GACL;CACA,MAAM,EAAE,MAAM,aAAa,mBAAmB,GAAG,iBAAiB;CAClE,IACE,sBAAsB,KAAA,MACrB,CAAC,OAAO,UAAU,iBAAiB,KAClC,oBAAoB,KACpB,oBAAoB,KAEtB,MAAM,IAAI,MAAM,wDAAwD;CAK1E,IAAI,SAAwC;CAC5C,MAAM,kBAAkB;EACtB,IAAI,CAAC,QAAQ,SAAS,IAAI,uBAAuB,YAAY;EAC7D,OAAO;CACT;CAEA,OAAO,eAAe;EACpB,MAAM,QAAQ;EACd,aACE,eACA;EACF;EACA;CACF,CAAC,CAAC,CAAC,OAAO,OAAO,MAAM,QAAQ;EAa7B,OAAO,EACL,UAAS,MAbY,UAAU,CAAC,CAAC,OACjC;GACE,OAAO,KAAK;GACZ,aAAa,KAAK,eAAe;GACjC,sBAAsB,KAAK;GAC3B,uBAAuB,KAAK;GAC5B,0BAA0B,KAAK;GAC/B,2BAA2B,KAAK;EAClC,GACA,EAAE,QAAQ,KAAK,YAAY,CAC7B,EAAA,CAGoB,QAAQ,KAAK,YAAY;GACzC,OAAO,OAAO;GACd,KAAK,OAAO;GACZ,SAAS,OAAO;GAChB,GAAI,OAAO,OAAO,EAAE,MAAM,OAAO,KAAK,IAAI,CAAC;GAC3C,GAAI,OAAO,eAAe,EAAE,cAAc,OAAO,aAAa,IAAI,CAAC;EACrE,EAAE,EACJ;CACF,CAAC;AACH"}

package/dist/esm/utils/api-key.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolve a Perplexity API key from environment variables.
+ *
+ * Honors `PERPLEXITY_API_KEY` first, then falls back to `PPLX_API_KEY`.
+ * Throws if neither is set.
+ */
+export declare function getPerplexityApiKeyFromEnv(): string;

package/dist/esm/utils/api-key.js

@@ -0,0 +1,24 @@
+//#region src/utils/api-key.ts
+/**
+* Resolve a Perplexity API key from environment variables.
+*
+* Honors `PERPLEXITY_API_KEY` first, then falls back to `PPLX_API_KEY`.
+* Throws if neither is set.
+*/
+function getPerplexityApiKeyFromEnv() {
+	const env = getEnvironment();
+	const key = [env?.PERPLEXITY_API_KEY, env?.PPLX_API_KEY].find((value) => typeof value === "string" && value.trim().length > 0)?.trim();
+	if (!key) throw new Error("PERPLEXITY_API_KEY (or PPLX_API_KEY) is required. Set it in your environment or pass an explicit apiKey.");
+	return key;
+}
+function getEnvironment() {
+	if (typeof globalThis !== "undefined") {
+		const win = globalThis.window;
+		if (win?.env) return win.env;
+	}
+	if (typeof process !== "undefined") return process.env;
+}
+//#endregion
+export { getPerplexityApiKeyFromEnv };
+
+//# sourceMappingURL=api-key.js.map

package/dist/esm/utils/api-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.js","names":[],"sources":["../../../src/utils/api-key.ts"],"sourcesContent":["/**\n * Resolve a Perplexity API key from environment variables.\n *\n * Honors `PERPLEXITY_API_KEY` first, then falls back to `PPLX_API_KEY`.\n * Throws if neither is set.\n */\nexport function getPerplexityApiKeyFromEnv(): string {\n  const env = getEnvironment()\n  const key = [env?.PERPLEXITY_API_KEY, env?.PPLX_API_KEY]\n    .find(\n      (value): value is string =>\n        typeof value === 'string' && value.trim().length > 0,\n    )\n    ?.trim()\n\n  if (!key) {\n    throw new Error(\n      'PERPLEXITY_API_KEY (or PPLX_API_KEY) is required. Set it in your environment or pass an explicit apiKey.',\n    )\n  }\n\n  return key\n}\n\ninterface WindowWithEnv {\n  env?: Record<string, string | undefined>\n}\n\nfunction getEnvironment(): Record<string, string | undefined> | undefined {\n  if (typeof globalThis !== 'undefined') {\n    const win = (globalThis as { window?: WindowWithEnv }).window\n    if (win?.env) return win.env\n  }\n  if (typeof process !== 'undefined') {\n    return process.env\n  }\n  return undefined\n}\n"],"mappings":";;;;;;;AAMA,SAAgB,6BAAqC;CACnD,MAAM,MAAM,eAAe;CAC3B,MAAM,MAAM,CAAC,KAAK,oBAAoB,KAAK,YAAY,CAAC,CACrD,MACE,UACC,OAAO,UAAU,YAAY,MAAM,KAAK,CAAC,CAAC,SAAS,CACvD,CAAC,EACC,KAAK;CAET,IAAI,CAAC,KACH,MAAM,IAAI,MACR,0GACF;CAGF,OAAO;AACT;AAMA,SAAS,iBAAiE;CACxE,IAAI,OAAO,eAAe,aAAa;EACrC,MAAM,MAAO,WAA0C;EACvD,IAAI,KAAK,KAAK,OAAO,IAAI;CAC3B;CACA,IAAI,OAAO,YAAY,aACrB,OAAO,QAAQ;AAGnB"}

package/dist/esm/utils/attribution.d.ts

@@ -0,0 +1,11 @@
+export declare const PERPLEXITY_INTEGRATION_HEADER = "X-Pplx-Integration";
+export declare const PERPLEXITY_INTEGRATION_HEADER_VALUE: string;
+/**
+ * Attribution header Perplexity uses to identify TanStack AI traffic
+ * (`X-Pplx-Integration: tanstack/<package-version>`).
+ *
+ * The Search client sends this automatically. Pass it as
+ * `openaiCompatible({ defaultHeaders })` if you want the same header on
+ * Sonar chat requests.
+ */
+export declare function getPerplexityIntegrationHeaders(): Record<string, string>;

package/dist/esm/utils/attribution.js

@@ -0,0 +1,18 @@
+//#region src/utils/attribution.ts
+var PERPLEXITY_INTEGRATION_HEADER = "X-Pplx-Integration";
+var PERPLEXITY_INTEGRATION_HEADER_VALUE = `tanstack/0.1.0`;
+/**
+* Attribution header Perplexity uses to identify TanStack AI traffic
+* (`X-Pplx-Integration: tanstack/<package-version>`).
+*
+* The Search client sends this automatically. Pass it as
+* `openaiCompatible({ defaultHeaders })` if you want the same header on
+* Sonar chat requests.
+*/
+function getPerplexityIntegrationHeaders() {
+	return { [PERPLEXITY_INTEGRATION_HEADER]: PERPLEXITY_INTEGRATION_HEADER_VALUE };
+}
+//#endregion
+export { PERPLEXITY_INTEGRATION_HEADER, PERPLEXITY_INTEGRATION_HEADER_VALUE, getPerplexityIntegrationHeaders };
+
+//# sourceMappingURL=attribution.js.map

package/dist/esm/utils/attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.js","names":[],"sources":["../../../src/utils/attribution.ts"],"sourcesContent":["export const PERPLEXITY_INTEGRATION_HEADER = 'X-Pplx-Integration'\nexport const PERPLEXITY_INTEGRATION_HEADER_VALUE = `tanstack/${__PACKAGE_VERSION__}`\n\n/**\n * Attribution header Perplexity uses to identify TanStack AI traffic\n * (`X-Pplx-Integration: tanstack/<package-version>`).\n *\n * The Search client sends this automatically. Pass it as\n * `openaiCompatible({ defaultHeaders })` if you want the same header on\n * Sonar chat requests.\n */\nexport function getPerplexityIntegrationHeaders(): Record<string, string> {\n  return {\n    [PERPLEXITY_INTEGRATION_HEADER]: PERPLEXITY_INTEGRATION_HEADER_VALUE,\n  }\n}\n\ndeclare const __PACKAGE_VERSION__: string\n"],"mappings":";AAAA,IAAa,gCAAgC;AAC7C,IAAa,sCAAsC;;;;;;;;;AAUnD,SAAgB,kCAA0D;CACxE,OAAO,GACJ,gCAAgC,oCACnC;AACF"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@tanstack/ai-perplexity",
+  "version": "0.1.0",
+  "description": "Perplexity Search API client and tool for TanStack AI",
+  "author": "Tanner Linsley",
+  "license": "MIT",
+  "homepage": "https://tanstack.com/ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-perplexity"
+  },
+  "bugs": {
+    "url": "https://github.com/TanStack/ai/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./search": {
+      "types": "./dist/esm/search/index.d.ts",
+      "import": "./dist/esm/search/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "typescript",
+    "tanstack",
+    "perplexity",
+    "search"
+  ],
+  "devDependencies": {
+    "@vitest/coverage-v8": "4.0.14",
+    "vite": "^8.1.4",
+    "zod": "^4.2.0"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0",
+    "@tanstack/ai": "^0.44.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "oxlint src --type-aware --fix",
+    "test:build": "publint --strict",
+    "test:oxlint": "oxlint src --type-aware",
+    "test:lib": "vitest run",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  }
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export {
+  PerplexitySearchClient,
+  perplexitySearchTool,
+  type PerplexitySearchClientConfig,
+  type PerplexitySearchRequest,
+  type PerplexitySearchResponse,
+  type PerplexitySearchResult,
+} from './search/index'
+
+export { getPerplexityApiKeyFromEnv } from './utils/api-key'
+export {
+  getPerplexityIntegrationHeaders,
+  PERPLEXITY_INTEGRATION_HEADER,
+  PERPLEXITY_INTEGRATION_HEADER_VALUE,
+} from './utils/attribution'

package/src/search/client.ts

@@ -0,0 +1,231 @@
+import { getPerplexityApiKeyFromEnv } from '../utils/api-key'
+import { getPerplexityIntegrationHeaders } from '../utils/attribution'
+
+export interface PerplexitySearchClientConfig {
+  /** Perplexity API key. Falls back to `PERPLEXITY_API_KEY` / `PPLX_API_KEY` env vars. */
+  apiKey?: string
+  /** Override the API base URL (defaults to https://api.perplexity.ai). */
+  baseURL?: string
+  /** Optional `fetch` implementation; defaults to globalThis.fetch. */
+  fetch?: typeof fetch
+}
+
+export interface PerplexitySearchRequest {
+  /** The search query, or up to 5 queries. */
+  query: string | ReadonlyArray<string>
+  /** Maximum number of results to return (1–20). Defaults to the API default (10). */
+  max_results?: number
+  /** Maximum tokens of content to return per page. */
+  max_tokens_per_page?: number
+  /**
+   * Restrict (or exclude) results by domain (max 20 entries).
+   *
+   * Hostnames, optional paths, or TLDs. Use bare entries to allowlist
+   * (`["nytimes.com"]`) or `-` prefixed entries to denylist
+   * (`["-pinterest.com"]`). Allow and deny entries must NOT be mixed.
+   */
+  search_domain_filter?: Array<string>
+  /** Restrict results by recency: `hour | day | week | month | year`. */
+  search_recency_filter?: 'hour' | 'day' | 'week' | 'month' | 'year'
+  /** Only include results published on or after this date (m/d/yyyy). */
+  search_after_date_filter?: string
+  /** Only include results published on or before this date (m/d/yyyy). */
+  search_before_date_filter?: string
+}
+
+export interface PerplexitySearchResult {
+  title: string
+  url: string
+  snippet: string
+  date?: string
+  last_updated?: string
+}
+
+export interface PerplexitySearchResponse {
+  id?: string
+  results: Array<PerplexitySearchResult>
+}
+
+const DEFAULT_BASE_URL = 'https://api.perplexity.ai'
+const MAX_QUERY_BATCH = 5
+const MAX_DOMAIN_FILTER = 20
+
+/**
+ * Low-level HTTP client for the Perplexity Search API.
+ *
+ * Calls `POST {baseURL}/search` with bearer auth.
+ */
+export class PerplexitySearchClient {
+  private readonly apiKey: string
+  private readonly baseURL: string
+  private readonly fetchImpl: typeof fetch
+
+  constructor(config: PerplexitySearchClientConfig = {}) {
+    const { apiKey } = config
+    const resolvedApiKey =
+      typeof apiKey === 'string' && apiKey.trim().length > 0
+        ? apiKey
+        : getPerplexityApiKeyFromEnv()
+
+    this.apiKey = resolvedApiKey
+    this.baseURL = (config.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, '')
+    this.fetchImpl = config.fetch ?? globalThis.fetch
+  }
+
+  async search(
+    request: PerplexitySearchRequest,
+    init: { signal?: AbortSignal } = {},
+  ): Promise<PerplexitySearchResponse> {
+    const query = normalizeQuery(request.query)
+    validateDomainFilter(request.search_domain_filter)
+
+    const body: Record<string, unknown> = { query }
+    if (request.max_results !== undefined)
+      body.max_results = requireMaxResults(request.max_results)
+    if (request.max_tokens_per_page !== undefined)
+      body.max_tokens_per_page = request.max_tokens_per_page
+    if (request.search_domain_filter)
+      body.search_domain_filter = request.search_domain_filter
+    if (request.search_recency_filter)
+      body.search_recency_filter = request.search_recency_filter
+    if (request.search_after_date_filter)
+      body.search_after_date_filter = request.search_after_date_filter
+    if (request.search_before_date_filter)
+      body.search_before_date_filter = request.search_before_date_filter
+
+    const response = await this.fetchImpl(`${this.baseURL}/search`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        ...getPerplexityIntegrationHeaders(),
+      },
+      body: JSON.stringify(body),
+      signal: init.signal,
+    })
+
+    if (!response.ok) {
+      const text = await safeReadText(response)
+      throw new Error(
+        `Perplexity Search API request failed: ${response.status} ${response.statusText}${
+          text ? ` — ${text}` : ''
+        }`,
+      )
+    }
+
+    return parseSearchResponse(await response.json())
+  }
+}
+
+function normalizeQuery(
+  query: string | ReadonlyArray<string>,
+): string | Array<string> {
+  if (typeof query === 'string') {
+    const trimmed = query.trim()
+    if (trimmed.length === 0) {
+      throw new Error(
+        'PerplexitySearchClient.search requires a non-empty `query`.',
+      )
+    }
+    return trimmed
+  }
+
+  if (query.length === 0) {
+    throw new Error(
+      'PerplexitySearchClient.search requires a non-empty `query`.',
+    )
+  }
+  if (query.length > MAX_QUERY_BATCH) {
+    throw new Error(
+      `query array must contain at most ${MAX_QUERY_BATCH} entries.`,
+    )
+  }
+
+  return query.map((entry) => {
+    if (typeof entry !== 'string' || entry.trim().length === 0) {
+      throw new Error(
+        'PerplexitySearchClient.search requires a non-empty `query`.',
+      )
+    }
+    return entry.trim()
+  })
+}
+
+function requireMaxResults(maxResults: number): number {
+  if (!Number.isInteger(maxResults) || maxResults < 1 || maxResults > 20) {
+    throw new Error('max_results must be an integer between 1 and 20.')
+  }
+  return maxResults
+}
+
+function validateDomainFilter(filter: Array<string> | undefined): void {
+  if (!filter || filter.length === 0) return
+  if (filter.length > MAX_DOMAIN_FILTER) {
+    throw new Error(
+      `search_domain_filter must contain at most ${MAX_DOMAIN_FILTER} entries.`,
+    )
+  }
+  let hasAllow = false
+  let hasDeny = false
+  for (const entry of filter) {
+    if (typeof entry !== 'string' || entry.length === 0) continue
+    if (entry.startsWith('-')) hasDeny = true
+    else hasAllow = true
+  }
+  if (hasAllow && hasDeny) {
+    throw new Error(
+      'search_domain_filter cannot mix allowlist and denylist entries. Use only `-domain.com` for negation, or only bare domains for allowlist.',
+    )
+  }
+}
+
+function isSearchResult(value: unknown): value is PerplexitySearchResult {
+  if (typeof value !== 'object' || value === null) return false
+  const result = value as {
+    title?: unknown
+    url?: unknown
+    snippet?: unknown
+    date?: unknown
+    last_updated?: unknown
+  }
+  return (
+    typeof result.title === 'string' &&
+    typeof result.url === 'string' &&
+    typeof result.snippet === 'string' &&
+    (result.date === undefined ||
+      result.date === null ||
+      typeof result.date === 'string') &&
+    (result.last_updated === undefined ||
+      result.last_updated === null ||
+      typeof result.last_updated === 'string')
+  )
+}
+
+function parseSearchResponse(value: unknown): PerplexitySearchResponse {
+  if (typeof value !== 'object' || value === null) {
+    throw new Error('Perplexity Search API returned an invalid response.')
+  }
+  const data = value as { id?: unknown; results?: unknown }
+  if (!Array.isArray(data.results) || !data.results.every(isSearchResult)) {
+    throw new Error('Perplexity Search API returned an invalid response.')
+  }
+  return {
+    ...(typeof data.id === 'string' ? { id: data.id } : {}),
+    results: data.results.map((result) => ({
+      title: result.title,
+      url: result.url,
+      snippet: result.snippet,
+      ...(result.date ? { date: result.date } : {}),
+      ...(result.last_updated ? { last_updated: result.last_updated } : {}),
+    })),
+  }
+}
+
+async function safeReadText(response: Response): Promise<string> {
+  try {
+    return await response.text()
+  } catch {
+    return ''
+  }
+}

package/src/search/index.ts

@@ -0,0 +1,8 @@
+export {
+  PerplexitySearchClient,
+  type PerplexitySearchClientConfig,
+  type PerplexitySearchRequest,
+  type PerplexitySearchResponse,
+  type PerplexitySearchResult,
+} from './client'
+export { perplexitySearchTool } from './tool'

package/src/search/tool.ts

@@ -0,0 +1,129 @@
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+import { PerplexitySearchClient } from './client'
+import type { PerplexitySearchClientConfig } from './client'
+
+const searchRecency = z.enum(['hour', 'day', 'week', 'month', 'year'])
+
+const inputSchema = z.object({
+  query: z.string().min(1).describe('The search query string.'),
+  max_results: z
+    .number()
+    .int()
+    .min(1)
+    .max(20)
+    .optional()
+    .describe(
+      'Maximum number of results to return. Defaults to defaultMaxResults when configured, otherwise the API default (10).',
+    ),
+  search_domain_filter: z
+    .array(z.string())
+    .max(20)
+    .optional()
+    .describe(
+      'Restrict results by domain (max 20). Use bare hostnames to allowlist (e.g. ["nytimes.com"]) or "-domain.com" to denylist. Allow and deny entries must NOT be mixed.',
+    ),
+  search_recency_filter: searchRecency
+    .optional()
+    .describe('Only include results from the given recency window.'),
+  search_after_date_filter: z
+    .string()
+    .optional()
+    .describe(
+      'Only include results published on or after this date (m/d/yyyy).',
+    ),
+  search_before_date_filter: z
+    .string()
+    .optional()
+    .describe(
+      'Only include results published on or before this date (m/d/yyyy).',
+    ),
+})
+
+const outputSchema = z.object({
+  results: z.array(
+    z.object({
+      title: z.string(),
+      url: z.string(),
+      snippet: z.string(),
+      date: z.string().optional(),
+      last_updated: z.string().optional(),
+    }),
+  ),
+})
+
+/**
+ * Build a TanStack AI tool that performs real-time web search via Perplexity.
+ *
+ * Returns `{ results: Array<{ title, url, snippet, date?, last_updated? }> }`
+ * for citation/grounding in an LLM agent loop.
+ *
+ * @example
+ * ```ts
+ * import { chat } from '@tanstack/ai'
+ * import { openaiText } from '@tanstack/ai-openai'
+ * import { perplexitySearchTool } from '@tanstack/ai-perplexity'
+ *
+ * const search = perplexitySearchTool({ defaultMaxResults: 5 })
+ * chat({ adapter: openaiText('gpt-5.2'), tools: [search], messages })
+ * ```
+ */
+export function perplexitySearchTool(
+  config: PerplexitySearchClientConfig & {
+    /** Override the tool name (defaults to `perplexity_search`). */
+    name?: string
+    /** Override the tool description shown to the model. */
+    description?: string
+    /** Default max_results applied when the model does not provide one. */
+    defaultMaxResults?: number
+  } = {},
+) {
+  const { name, description, defaultMaxResults, ...clientConfig } = config
+  if (
+    defaultMaxResults !== undefined &&
+    (!Number.isInteger(defaultMaxResults) ||
+      defaultMaxResults < 1 ||
+      defaultMaxResults > 20)
+  ) {
+    throw new Error('defaultMaxResults must be an integer between 1 and 20.')
+  }
+
+  // Lazily construct the client so missing API keys don't blow up at import
+  // time (e.g. on bundlers that statically evaluate module top-level).
+  let client: PerplexitySearchClient | null = null
+  const getClient = () => {
+    if (!client) client = new PerplexitySearchClient(clientConfig)
+    return client
+  }
+
+  return toolDefinition({
+    name: name ?? 'perplexity_search',
+    description:
+      description ??
+      'Search the web for up-to-date information using the Perplexity Search API. Returns a ranked list of web results with titles, URLs, snippets, and optional publication dates.',
+    inputSchema,
+    outputSchema,
+  }).server(async (args, ctx) => {
+    const response = await getClient().search(
+      {
+        query: args.query,
+        max_results: args.max_results ?? defaultMaxResults,
+        search_domain_filter: args.search_domain_filter,
+        search_recency_filter: args.search_recency_filter,
+        search_after_date_filter: args.search_after_date_filter,
+        search_before_date_filter: args.search_before_date_filter,
+      },
+      { signal: ctx?.abortSignal },
+    )
+
+    return {
+      results: response.results.map((result) => ({
+        title: result.title,
+        url: result.url,
+        snippet: result.snippet,
+        ...(result.date ? { date: result.date } : {}),
+        ...(result.last_updated ? { last_updated: result.last_updated } : {}),
+      })),
+    }
+  })
+}

package/src/utils/api-key.ts

@@ -0,0 +1,38 @@
+/**
+ * Resolve a Perplexity API key from environment variables.
+ *
+ * Honors `PERPLEXITY_API_KEY` first, then falls back to `PPLX_API_KEY`.
+ * Throws if neither is set.
+ */
+export function getPerplexityApiKeyFromEnv(): string {
+  const env = getEnvironment()
+  const key = [env?.PERPLEXITY_API_KEY, env?.PPLX_API_KEY]
+    .find(
+      (value): value is string =>
+        typeof value === 'string' && value.trim().length > 0,
+    )
+    ?.trim()
+
+  if (!key) {
+    throw new Error(
+      'PERPLEXITY_API_KEY (or PPLX_API_KEY) is required. Set it in your environment or pass an explicit apiKey.',
+    )
+  }
+
+  return key
+}
+
+interface WindowWithEnv {
+  env?: Record<string, string | undefined>
+}
+
+function getEnvironment(): Record<string, string | undefined> | undefined {
+  if (typeof globalThis !== 'undefined') {
+    const win = (globalThis as { window?: WindowWithEnv }).window
+    if (win?.env) return win.env
+  }
+  if (typeof process !== 'undefined') {
+    return process.env
+  }
+  return undefined
+}

package/src/utils/attribution.ts

@@ -0,0 +1,18 @@
+export const PERPLEXITY_INTEGRATION_HEADER = 'X-Pplx-Integration'
+export const PERPLEXITY_INTEGRATION_HEADER_VALUE = `tanstack/${__PACKAGE_VERSION__}`
+
+/**
+ * Attribution header Perplexity uses to identify TanStack AI traffic
+ * (`X-Pplx-Integration: tanstack/<package-version>`).
+ *
+ * The Search client sends this automatically. Pass it as
+ * `openaiCompatible({ defaultHeaders })` if you want the same header on
+ * Sonar chat requests.
+ */
+export function getPerplexityIntegrationHeaders(): Record<string, string> {
+  return {
+    [PERPLEXITY_INTEGRATION_HEADER]: PERPLEXITY_INTEGRATION_HEADER_VALUE,
+  }
+}
+
+declare const __PACKAGE_VERSION__: string