feat: add Perplexity Search integration

docs/adapters/perplexity.md

@@ -0,0 +1,115 @@
+---
+title: Perplexity
+id: perplexity-adapter
+order: 10
+description: "Use the Perplexity Search API and OpenAI-compatible chat completions with TanStack AI via @tanstack/ai-perplexity."
+keywords:
+  - tanstack ai
+  - perplexity
+  - search api
+  - web search
+  - adapter
+---
+
+`@tanstack/ai-perplexity` integrates [Perplexity](https://www.perplexity.ai) with TanStack AI:
+
+- A **Search API tool** that grounds your agent on the live web (`POST https://api.perplexity.ai/search`).
+- An **OpenAI-compatible chat client** that points the `openai` SDK at Perplexity's chat-completions endpoint, so existing OpenAI code can target Perplexity by swapping the base URL.
+
+## Installation
+
+```bash
+npm install @tanstack/ai-perplexity
+```
+
+Set your API key (get one at <https://www.perplexity.ai/account/api/keys>):
+
+```bash
+export PERPLEXITY_API_KEY=...
+# PPLX_API_KEY is also accepted
+```
+
+## Search tool
+
+Wrap the Search API as a TanStack AI tool and pass it to a chat agent so the model can fetch up-to-date web results:
+
+```ts
+import { chat } from '@tanstack/ai'
+import { perplexitySearchTool } from '@tanstack/ai-perplexity'
+
+const search = perplexitySearchTool({
+  // optional: applied when the model omits max_results
+  defaultMaxResults: 5,
+})
+
+const stream = chat({
+  // ... your text adapter ...
+  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 API default (10), or `defaultMaxResults` if configured.|
+| `search_domain_filter`      | `string[]`                                        | 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.                     |
+
+Each result is `{ title, url, snippet, date? }`.
+
+### Direct client
+
+If you want to call the Search API outside an agent loop:
+
+```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 (OpenAI-compatible)
+
+Perplexity exposes `POST /v1/chat/completions` with the standard OpenAI Chat Completions shape. `createPerplexityChatClient` returns an `openai` SDK instance pointed at `https://api.perplexity.ai`:
+
+```ts
+import { createPerplexityChatClient } from '@tanstack/ai-perplexity/chat'
+
+const client = createPerplexityChatClient()
+const completion = await client.chat.completions.create({
+  model: 'sonar',
+  messages: [
+    { role: 'user', content: 'What is the latest on the Mars rover?' },
+  ],
+})
+```
+
+## Configuration
+
+```ts
+import { PerplexitySearchClient } from '@tanstack/ai-perplexity'
+
+const client = new PerplexitySearchClient({
+  apiKey: process.env.PERPLEXITY_API_KEY,   // explicit key (optional)
+  baseURL: 'https://api.perplexity.ai',     // override (optional)
+  fetch: globalThis.fetch,                  // custom fetch (optional)
+})
+```
+
+## References
+
+- 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>

docs/config.json

@@ -314,6 +314,10 @@
         {
           "label": "OpenRouter Adapter",
           "to": "adapters/openrouter"
+        },
+        {
+          "label": "Perplexity",
+          "to": "adapters/perplexity"
         }
       ]
     },

packages/typescript/ai-perplexity/README.md

@@ -0,0 +1,91 @@
+# @tanstack/ai-perplexity
+
+[Perplexity](https://www.perplexity.ai) integration for [TanStack AI](https://tanstack.com/ai):
+
+- **Search API tool** — call `POST https://api.perplexity.ai/search` from an LLM agent loop and get back ranked web results (`title`, `url`, `snippet`, `date?`) suitable for grounding/citation.
+- **OpenAI-compatible chat client** — a thin factory that points the `openai` SDK at Perplexity's chat-completions endpoint so you can reuse existing OpenAI code paths.
+
+## Install
+
+```bash
+pnpm add @tanstack/ai-perplexity
+```
+
+Set your API key (get one at <https://www.perplexity.ai/account/api/keys>):
+
+```bash
+export PERPLEXITY_API_KEY=...
+# PPLX_API_KEY is also accepted
+```
+
+## Search tool
+
+Wrap the Search API as a TanStack AI tool and pass it to a chat agent:
+
+```ts
+import { perplexitySearchTool } from '@tanstack/ai-perplexity'
+
+const search = perplexitySearchTool({
+  // optional defaults
+  defaultMaxResults: 5,
+})
+
+// Use directly with chat()
+chat({
+  tools: [search],
+  // ...
+})
+```
+
+The tool input schema accepts:
+
+| field                       | type                                                | notes                                                              |
+| --------------------------- | --------------------------------------------------- | ------------------------------------------------------------------ |
+| `query`                     | `string` (required)                                 | The search query.                                                  |
+| `max_results`               | `integer` (1–20)                                    | Defaults to API default (10), or `defaultMaxResults` if configured.|
+| `search_domain_filter`      | `string[]`                                          | 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? }> }`.
+
+### Direct client usage
+
+If you don't need the tool wrapping, call the Search API directly:
+
+```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 (OpenAI-compatible)
+
+Perplexity's chat completions endpoint is OpenAI-compatible, so you can target it by swapping the `baseURL`:
+
+```ts
+import { createPerplexityChatClient } from '@tanstack/ai-perplexity/chat'
+
+const client = createPerplexityChatClient()
+const completion = await client.chat.completions.create({
+  model: 'sonar',
+  messages: [
+    { role: 'user', content: 'What is the latest on the Mars rover?' },
+  ],
+})
+```
+
+Env vars: `PERPLEXITY_API_KEY` (preferred) or `PPLX_API_KEY`.
+
+## 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>

packages/typescript/ai-perplexity/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@tanstack/ai-perplexity",
+  "version": "0.1.0",
+  "description": "Perplexity adapter for TanStack AI \u2014 Search API and OpenAI-compatible chat",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/typescript/ai-perplexity"
+  },
+  "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"
+    },
+    "./adapters/search": {
+      "types": "./dist/esm/search/index.d.ts",
+      "import": "./dist/esm/search/index.js"
+    },
+    "./adapters/chat": {
+      "types": "./dist/esm/chat/index.d.ts",
+      "import": "./dist/esm/chat/index.js"
+    },
+    "./search": {
+      "types": "./dist/esm/search/index.d.ts",
+      "import": "./dist/esm/search/index.js"
+    },
+    "./chat": {
+      "types": "./dist/esm/chat/index.d.ts",
+      "import": "./dist/esm/chat/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "eslint ./src --fix",
+    "test:build": "publint --strict",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest run",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  },
+  "keywords": [
+    "ai",
+    "perplexity",
+    "search",
+    "tanstack",
+    "adapter"
+  ],
+  "dependencies": {
+    "openai": "^6.9.1"
+  },
+  "devDependencies": {
+    "@tanstack/ai": "workspace:*",
+    "@vitest/coverage-v8": "4.0.14",
+    "vite": "^7.3.3"
+  },
+  "peerDependencies": {
+    "@tanstack/ai": "workspace:*"
+  }
+}

packages/typescript/ai-perplexity/src/chat/client.ts

@@ -0,0 +1,52 @@
+import OpenAI from 'openai'
+import { getPerplexityApiKeyFromEnv } from '../utils/api-key'
+import { getPerplexityIntegrationHeaders } from '../utils/attribution'
+import type { ClientOptions } from 'openai'
+
+export interface PerplexityChatClientConfig extends ClientOptions {
+  /** 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
+}
+
+const DEFAULT_BASE_URL = 'https://api.perplexity.ai'
+
+/**
+ * Create an OpenAI SDK client pointed at Perplexity's OpenAI-compatible
+ * chat-completions endpoint.
+ *
+ * Perplexity exposes `POST /v1/chat/completions` with the standard OpenAI
+ * Chat Completions request/response shape, so any code that consumes the
+ * `openai` SDK can target Perplexity by swapping the `baseURL`.
+ *
+ * @example
+ * ```ts
+ * import { createPerplexityChatClient } from '@tanstack/ai-perplexity/chat'
+ *
+ * const client = createPerplexityChatClient()
+ * const completion = await client.chat.completions.create({
+ *   model: 'sonar',
+ *   messages: [{ role: 'user', content: 'What is the latest on the Mars rover?' }],
+ * })
+ * ```
+ */
+export function createPerplexityChatClient(
+  config: PerplexityChatClientConfig = {},
+): OpenAI {
+  const { apiKey, baseURL, defaultHeaders, ...rest } = config
+  const resolvedApiKey =
+    typeof apiKey === 'string' && apiKey.trim().length > 0
+      ? apiKey
+      : getPerplexityApiKeyFromEnv()
+
+  return new OpenAI({
+    ...rest,
+    apiKey: resolvedApiKey,
+    baseURL: baseURL ?? DEFAULT_BASE_URL,
+    defaultHeaders: {
+      ...defaultHeaders,
+      ...getPerplexityIntegrationHeaders(),
+    },
+  })
+}

packages/typescript/ai-perplexity/src/chat/index.ts

@@ -0,0 +1,4 @@
+export {
+  createPerplexityChatClient,
+  type PerplexityChatClientConfig,
+} from './client'

packages/typescript/ai-perplexity/src/index.ts

@@ -0,0 +1,18 @@
+// Search API
+export {
+  PerplexitySearchClient,
+  perplexitySearchTool,
+  type PerplexitySearchClientConfig,
+  type PerplexitySearchRequest,
+  type PerplexitySearchResponse,
+  type PerplexitySearchResult,
+} from './search'
+
+// OpenAI-compatible chat client (Perplexity chat completions endpoint)
+export {
+  createPerplexityChatClient,
+  type PerplexityChatClientConfig,
+} from './chat'
+
+// Utilities
+export { getPerplexityApiKeyFromEnv } from './utils/api-key'