@ai-sdk/perplexity 0.0.0-01d6317c-20260129172110

package/docs/70-perplexity.mdx

@@ -0,0 +1,196 @@
+---
+title: Perplexity
+description: Learn how to use Perplexity's Sonar API with the AI SDK.
+---
+
+# Perplexity Provider
+
+The [Perplexity](https://sonar.perplexity.ai) provider offers access to Sonar API - a language model that uniquely combines real-time web search with natural language processing. Each response is grounded in current web data and includes detailed citations, making it ideal for research, fact-checking, and obtaining up-to-date information.
+
+API keys can be obtained from the [Perplexity Platform](https://docs.perplexity.ai).
+
+## Setup
+
+The Perplexity provider is available via the `@ai-sdk/perplexity` module. You can install it with:
+
+<Tabs items={['pnpm', 'npm', 'yarn', 'bun']}>
+  <Tab>
+    <Snippet text="pnpm add @ai-sdk/perplexity" dark />
+  </Tab>
+  <Tab>
+    <Snippet text="npm install @ai-sdk/perplexity" dark />
+  </Tab>
+  <Tab>
+    <Snippet text="yarn add @ai-sdk/perplexity" dark />
+  </Tab>
+
+  <Tab>
+    <Snippet text="bun add @ai-sdk/perplexity" dark />
+  </Tab>
+</Tabs>
+
+## Provider Instance
+
+You can import the default provider instance `perplexity` from `@ai-sdk/perplexity`:
+
+```ts
+import { perplexity } from '@ai-sdk/perplexity';
+```
+
+For custom configuration, you can import `createPerplexity` and create a provider instance with your settings:
+
+```ts
+import { createPerplexity } from '@ai-sdk/perplexity';
+
+const perplexity = createPerplexity({
+  apiKey: process.env.PERPLEXITY_API_KEY ?? '',
+});
+```
+
+You can use the following optional settings to customize the Perplexity provider instance:
+
+- **baseURL** _string_
+
+  Use a different URL prefix for API calls.
+  The default prefix is `https://api.perplexity.ai`.
+
+- **apiKey** _string_
+
+  API key that is being sent using the `Authorization` header. It defaults to
+  the `PERPLEXITY_API_KEY` environment variable.
+
+- **headers** _Record&lt;string,string&gt;_
+
+  Custom headers to include in the requests.
+
+- **fetch** _(input: RequestInfo, init?: RequestInit) => Promise&lt;Response&gt;_
+
+  Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) implementation.
+
+## Language Models
+
+You can create Perplexity models using a provider instance:
+
+```ts
+import { perplexity } from '@ai-sdk/perplexity';
+import { generateText } from 'ai';
+
+const { text } = await generateText({
+  model: perplexity('sonar-pro'),
+  prompt: 'What are the latest developments in quantum computing?',
+});
+```
+
+### Sources
+
+Websites that have been used to generate the response are included in the `sources` property of the result:
+
+```ts
+import { perplexity } from '@ai-sdk/perplexity';
+import { generateText } from 'ai';
+
+const { text, sources } = await generateText({
+  model: perplexity('sonar-pro'),
+  prompt: 'What are the latest developments in quantum computing?',
+});
+
+console.log(sources);
+```
+
+### Provider Options & Metadata
+
+The Perplexity provider includes additional metadata in the response through `providerMetadata`.
+Additional configuration options are available through `providerOptions`.
+
+```ts
+const result = await generateText({
+  model: perplexity('sonar-pro'),
+  prompt: 'What are the latest developments in quantum computing?',
+  providerOptions: {
+    perplexity: {
+      return_images: true, // Enable image responses (Tier-2 Perplexity users only)
+    },
+  },
+});
+
+console.log(result.providerMetadata);
+// Example output:
+// {
+//   perplexity: {
+//     usage: { citationTokens: 5286, numSearchQueries: 1 },
+//     images: [
+//       { imageUrl: "https://example.com/image1.jpg", originUrl: "https://elsewhere.com/page1", height: 1280, width: 720 },
+//       { imageUrl: "https://example.com/image2.jpg", originUrl: "https://elsewhere.com/page2", height: 1280, width: 720 }
+//     ]
+//   },
+// }
+```
+
+The metadata includes:
+
+- `usage`: Object containing `citationTokens` and `numSearchQueries` metrics
+- `images`: Array of image URLs when `return_images` is enabled (Tier-2 users only)
+
+You can enable image responses by setting `return_images: true` in the provider options. This feature is only available to Perplexity Tier-2 users and above.
+
+### PDF Support
+
+The Perplexity provider supports reading PDF files.
+You can pass PDF files as part of the message content using the `file` type:
+
+```ts
+const result = await generateText({
+  model: perplexity('sonar-pro'),
+  messages: [
+    {
+      role: 'user',
+      content: [
+        {
+          type: 'text',
+          text: 'What is this document about?',
+        },
+        {
+          type: 'file',
+          data: fs.readFileSync('./data/ai.pdf'),
+          mediaType: 'application/pdf',
+          filename: 'ai.pdf', // optional
+        },
+      ],
+    },
+  ],
+});
+```
+
+You can also pass the URL of a PDF:
+
+```ts
+{
+  type: 'file',
+  data: new URL('https://example.com/document.pdf'),
+  mediaType: 'application/pdf',
+  filename: 'document.pdf', // optional
+}
+```
+
+The model will have access to the contents of the PDF file and
+respond to questions about it.
+
+<Note>
+  For more details about Perplexity's capabilities, see the [Perplexity chat
+  completion docs](https://docs.perplexity.ai/api-reference/chat-completions).
+</Note>
+
+## Model Capabilities
+
+| Model                 | Image Input         | Object Generation   | Tool Usage          | Tool Streaming      |
+| --------------------- | ------------------- | ------------------- | ------------------- | ------------------- |
+| `sonar-deep-research` | <Cross size={18} /> | <Check size={18} /> | <Cross size={18} /> | <Cross size={18} /> |
+| `sonar-reasoning-pro` | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> | <Cross size={18} /> |
+| `sonar-reasoning`     | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> | <Cross size={18} /> |
+| `sonar-pro`           | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> | <Cross size={18} /> |
+| `sonar`               | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> | <Cross size={18} /> |
+
+<Note>
+  Please see the [Perplexity docs](https://docs.perplexity.ai) for detailed API
+  documentation and the latest updates.
+</Note>

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@ai-sdk/perplexity",
+  "version": "0.0.0-01d6317c-20260129172110",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*",
+    "docs/**/*",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "!src/**/__snapshots__",
+    "!src/**/__fixtures__",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "directories": {
+    "doc": "./docs"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@ai-sdk/provider": "0.0.0-01d6317c-20260129172110",
+    "@ai-sdk/provider-utils": "0.0.0-01d6317c-20260129172110"
+  },
+  "devDependencies": {
+    "@types/node": "20.17.24",
+    "tsup": "^8",
+    "typescript": "5.8.3",
+    "zod": "3.25.76",
+    "@ai-sdk/test-server": "1.0.3",
+    "@vercel/ai-tsconfig": "0.0.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.25.76 || ^4.1.8"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://ai-sdk.dev/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel/ai.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vercel/ai/issues"
+  },
+  "keywords": [
+    "ai"
+  ],
+  "scripts": {
+    "build": "pnpm clean && tsup --tsconfig tsconfig.build.json",
+    "build:watch": "pnpm clean && tsup --watch",
+    "clean": "del-cli dist docs *.tsbuildinfo",
+    "lint": "eslint \"./**/*.ts*\"",
+    "type-check": "tsc --build",
+    "prettier-check": "prettier --check \"./**/*.ts*\"",
+    "test": "pnpm test:node && pnpm test:edge",
+    "test:update": "pnpm test:node -u",
+    "test:watch": "vitest --config vitest.node.config.js",
+    "test:edge": "vitest --config vitest.edge.config.js --run",
+    "test:node": "vitest --config vitest.node.config.js --run"
+  }
+}

package/src/convert-perplexity-usage.ts

@@ -0,0 +1,48 @@
+import { LanguageModelV3Usage } from '@ai-sdk/provider';
+
+export function convertPerplexityUsage(
+  usage:
+    | {
+        prompt_tokens?: number | null | undefined;
+        completion_tokens?: number | null | undefined;
+        reasoning_tokens?: number | null | undefined;
+      }
+    | undefined
+    | null,
+): LanguageModelV3Usage {
+  if (usage == null) {
+    return {
+      inputTokens: {
+        total: undefined,
+        noCache: undefined,
+        cacheRead: undefined,
+        cacheWrite: undefined,
+      },
+      outputTokens: {
+        total: undefined,
+        text: undefined,
+        reasoning: undefined,
+      },
+      raw: undefined,
+    };
+  }
+
+  const promptTokens = usage.prompt_tokens ?? 0;
+  const completionTokens = usage.completion_tokens ?? 0;
+  const reasoningTokens = usage.reasoning_tokens ?? 0;
+
+  return {
+    inputTokens: {
+      total: promptTokens,
+      noCache: promptTokens,
+      cacheRead: undefined,
+      cacheWrite: undefined,
+    },
+    outputTokens: {
+      total: completionTokens,
+      text: completionTokens - reasoningTokens,
+      reasoning: reasoningTokens,
+    },
+    raw: usage,
+  };
+}

package/src/convert-to-perplexity-messages.ts

@@ -0,0 +1,107 @@
+import {
+  LanguageModelV3Prompt,
+  UnsupportedFunctionalityError,
+} from '@ai-sdk/provider';
+import {
+  PerplexityMessageContent,
+  PerplexityPrompt,
+} from './perplexity-language-model-prompt';
+import { convertUint8ArrayToBase64 } from '@ai-sdk/provider-utils';
+
+export function convertToPerplexityMessages(
+  prompt: LanguageModelV3Prompt,
+): PerplexityPrompt {
+  const messages: PerplexityPrompt = [];
+
+  for (const { role, content } of prompt) {
+    switch (role) {
+      case 'system': {
+        messages.push({ role: 'system', content });
+        break;
+      }
+
+      case 'user':
+      case 'assistant': {
+        const hasMultipartContent = content.some(
+          part =>
+            (part.type === 'file' && part.mediaType.startsWith('image/')) ||
+            (part.type === 'file' && part.mediaType === 'application/pdf'),
+        );
+
+        const messageContent = content
+          .map((part, index) => {
+            switch (part.type) {
+              case 'text': {
+                return {
+                  type: 'text',
+                  text: part.text,
+                };
+              }
+              case 'file': {
+                if (part.mediaType === 'application/pdf') {
+                  return part.data instanceof URL
+                    ? {
+                        type: 'file_url',
+                        file_url: {
+                          url: part.data.toString(),
+                        },
+                        file_name: part.filename,
+                      }
+                    : {
+                        type: 'file_url',
+                        file_url: {
+                          url:
+                            typeof part.data === 'string'
+                              ? part.data
+                              : convertUint8ArrayToBase64(part.data),
+                        },
+                        file_name: part.filename || `document-${index}.pdf`,
+                      };
+                } else if (part.mediaType.startsWith('image/')) {
+                  return part.data instanceof URL
+                    ? {
+                        type: 'image_url',
+                        image_url: {
+                          url: part.data.toString(),
+                        },
+                      }
+                    : {
+                        type: 'image_url',
+                        image_url: {
+                          url: `data:${part.mediaType ?? 'image/jpeg'};base64,${
+                            typeof part.data === 'string'
+                              ? part.data
+                              : convertUint8ArrayToBase64(part.data)
+                          }`,
+                        },
+                      };
+                }
+              }
+            }
+          })
+          .filter(Boolean) as PerplexityMessageContent[];
+        messages.push({
+          role,
+          content: hasMultipartContent
+            ? messageContent
+            : messageContent
+                .filter(part => part.type === 'text')
+                .map(part => part.text)
+                .join(''),
+        });
+        break;
+      }
+      case 'tool': {
+        throw new UnsupportedFunctionalityError({
+          functionality: 'Tool messages',
+        });
+      }
+      default: {
+        const _exhaustiveCheck: never = role;
+        throw new Error(`Unsupported role: ${_exhaustiveCheck}`);
+      }
+    }
+  }
+
+  return messages;
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { createPerplexity, perplexity } from './perplexity-provider';
+export type {
+  PerplexityProvider,
+  PerplexityProviderSettings,
+} from './perplexity-provider';
+export { VERSION } from './version';

package/src/map-perplexity-finish-reason.ts

@@ -0,0 +1,13 @@
+import { LanguageModelV3FinishReason } from '@ai-sdk/provider';
+
+export function mapPerplexityFinishReason(
+  finishReason: string | null | undefined,
+): LanguageModelV3FinishReason['unified'] {
+  switch (finishReason) {
+    case 'stop':
+    case 'length':
+      return finishReason;
+    default:
+      return 'other';
+  }
+}

package/src/perplexity-language-model-options.ts

@@ -0,0 +1,8 @@
+// https://docs.perplexity.ai/models/model-cards
+export type PerplexityLanguageModelId =
+  | 'sonar-deep-research'
+  | 'sonar-reasoning-pro'
+  | 'sonar-reasoning'
+  | 'sonar-pro'
+  | 'sonar'
+  | (string & {});

package/src/perplexity-language-model-prompt.ts

@@ -0,0 +1,25 @@
+export type PerplexityPrompt = Array<PerplexityMessage>;
+
+export type PerplexityMessage = {
+  role: 'system' | 'user' | 'assistant';
+  content: string | PerplexityMessageContent[];
+};
+
+export type PerplexityMessageContent =
+  | {
+      type: 'text';
+      text: string;
+    }
+  | {
+      type: 'image_url';
+      image_url: {
+        url: string;
+      };
+    }
+  | {
+      type: 'file_url';
+      file_url: {
+        url: string;
+      };
+      file_name?: string;
+    };