@ai-sdk/perplexity 4.0.52 → 5.0.0

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

@@ -1,13 +1,32 @@
 import type { LanguageModelV4FinishReason } from '@ai-sdk/provider';
 
-export function mapPerplexityFinishReason(
-  finishReason: string | null | undefined,
-): LanguageModelV4FinishReason['unified'] {
-  switch (finishReason) {
-    case 'stop':
-    case 'length':
-      return finishReason;
+export function mapPerplexityFinishReason({
+  status,
+  incompleteReason,
+  hasFunctionCall,
+}: {
+  status: string | null | undefined;
+  incompleteReason: string | null | undefined;
+  hasFunctionCall: boolean;
+}): LanguageModelV4FinishReason['unified'] {
+  switch (incompleteReason) {
+    case 'max_output_tokens':
+      return 'length';
+    case 'content_filter':
+      return 'content-filter';
+  }
+
+  switch (status) {
+    case 'completed':
+      return hasFunctionCall ? 'tool-calls' : 'stop';
+    case 'requires_action':
+      return 'tool-calls';
+    case 'failed':
+      return 'error';
+    case 'cancelled':
+    case 'queued':
+    case 'in_progress':
     default:
-      return 'other';
+      return hasFunctionCall ? 'tool-calls' : 'other';
   }
 }

package/src/perplexity-agent-api.ts

@@ -0,0 +1,206 @@
+import type { JSONSchema7 } from '@ai-sdk/provider';
+import { z } from 'zod/v4';
+
+export type PerplexityAgentTool =
+  | {
+      type: 'function';
+      name: string;
+      description?: string;
+      parameters: JSONSchema7;
+      strict?: boolean;
+    }
+  | ({ type: string } & Record<string, unknown>);
+
+export const perplexitySearchResultSchema = z.looseObject({
+  id: z.number().optional(),
+  title: z.string(),
+  url: z.string(),
+  snippet: z.string().optional(),
+  date: z.string().nullish(),
+  last_updated: z.string().nullish(),
+  source: z.string().optional(),
+});
+
+const perplexityFetchedContentSchema = z.looseObject({
+  title: z.string(),
+  url: z.string(),
+  snippet: z.string().optional(),
+});
+
+const perplexityContentPartSchema = z.looseObject({
+  type: z.string(),
+  text: z.string().optional(),
+  annotations: z
+    .array(
+      z.looseObject({
+        type: z.string().optional(),
+        url: z.string().optional(),
+        title: z.string().optional(),
+      }),
+    )
+    .nullish(),
+});
+
+const handledOutputTypes = [
+  'message',
+  'search_results',
+  'fetch_url_results',
+  'function_call',
+];
+
+export const perplexityOutputItemSchema = z.union([
+  z.looseObject({
+    type: z.literal('message'),
+    id: z.string().nullish(),
+    content: z.array(perplexityContentPartSchema).nullish(),
+  }),
+  z.looseObject({
+    type: z.literal('search_results'),
+    results: z.array(perplexitySearchResultSchema).nullish(),
+  }),
+  z.looseObject({
+    type: z.literal('fetch_url_results'),
+    contents: z.array(perplexityFetchedContentSchema).nullish(),
+  }),
+  z.looseObject({
+    type: z.literal('function_call'),
+    id: z.string().nullish(),
+    call_id: z.string().nullish(),
+    name: z.string().nullish(),
+    arguments: z.string().nullish(),
+    thought_signature: z.string().nullish(),
+  }),
+  // Native tool traces remain available in raw responses and raw stream chunks.
+  // Their fields (e.g. finance_results.results) have different shapes. Do not
+  // validate them as search results, or let malformed handled items fall back.
+  z
+    .object({
+      type: z.string().refine(type => !handledOutputTypes.includes(type)),
+    })
+    .transform(() => ({ type: 'unhandled' as const })),
+]);
+
+const perplexityCostSchema = z.looseObject({
+  currency: z.string().optional(),
+  input_cost: z.number().optional(),
+  output_cost: z.number().optional(),
+  total_cost: z.number().optional(),
+  cache_creation_cost: z.number().nullish(),
+  cache_read_cost: z.number().nullish(),
+  tool_calls_cost: z.number().nullish(),
+});
+
+export const perplexityUsageSchema = z.looseObject({
+  input_tokens: z.number(),
+  output_tokens: z.number(),
+  total_tokens: z.number(),
+  input_tokens_details: z
+    .looseObject({
+      cached_tokens: z.number().optional(),
+      cache_creation_input_tokens: z.number().optional(),
+      cache_read_input_tokens: z.number().optional(),
+    })
+    .nullish(),
+  output_tokens_details: z
+    .looseObject({
+      reasoning_tokens: z.number().optional(),
+    })
+    .nullish(),
+  tool_calls_details: z
+    .record(
+      z.string(),
+      z.looseObject({
+        invocation: z.number().optional(),
+      }),
+    )
+    .nullish(),
+  cost: perplexityCostSchema.nullish(),
+});
+
+export const perplexityAgentResponseSchema = z.looseObject({
+  id: z.string(),
+  created_at: z.number(),
+  model: z.string(),
+  object: z.literal('response'),
+  output: z.array(perplexityOutputItemSchema),
+  status: z.string(),
+  incomplete_details: z
+    .looseObject({
+      reason: z.string(),
+    })
+    .nullish(),
+  error: z
+    .looseObject({
+      code: z.string().optional(),
+      message: z.string(),
+      type: z.string().optional(),
+    })
+    .nullish(),
+  usage: perplexityUsageSchema.nullish(),
+});
+
+export const perplexityAgentChunkSchema = z.looseObject({
+  type: z.string(),
+  sequence_number: z.number().optional(),
+  response: perplexityAgentResponseSchema.optional(),
+  item: perplexityOutputItemSchema.optional(),
+  output_index: z.number().optional(),
+  item_id: z.string().optional(),
+  content_index: z.number().optional(),
+  delta: z.string().optional(),
+  text: z.string().optional(),
+  thought: z.string().optional(),
+  queries: z.array(z.string()).optional(),
+  urls: z.array(z.string()).optional(),
+  results: z.array(perplexitySearchResultSchema).optional(),
+  contents: z.array(perplexityFetchedContentSchema).optional(),
+  error: z
+    .looseObject({
+      code: z.string().optional(),
+      message: z.string(),
+      type: z.string().optional(),
+    })
+    .optional(),
+});
+
+export const perplexityErrorSchema = z.looseObject({
+  error: z
+    .union([
+      z.string(),
+      z.looseObject({
+        code: z.union([z.string(), z.number()]).optional(),
+        message: z.string().nullish(),
+        type: z.string().nullish(),
+      }),
+    ])
+    .optional(),
+  detail: z
+    .union([
+      z.string(),
+      z.array(
+        z.looseObject({
+          msg: z.string(),
+        }),
+      ),
+    ])
+    .optional(),
+  message: z.string().optional(),
+});
+
+export type PerplexityErrorData = z.infer<typeof perplexityErrorSchema>;
+
+export function perplexityErrorToMessage(data: PerplexityErrorData): string {
+  if (typeof data.error === 'string') {
+    return data.error;
+  }
+  if (data.error != null) {
+    return data.error.message ?? data.error.type ?? 'unknown error';
+  }
+  if (typeof data.detail === 'string') {
+    return data.detail;
+  }
+  if (Array.isArray(data.detail)) {
+    return data.detail.map(detail => detail.msg).join(', ');
+  }
+  return data.message ?? 'unknown error';
+}

package/src/perplexity-embedding-model.ts

@@ -19,7 +19,10 @@ import {
   perplexityEmbeddingModelOptions,
   type PerplexityEmbeddingModelId,
 } from './perplexity-embedding-model-options';
-import { perplexityErrorSchema } from './perplexity-language-model';
+import {
+  perplexityErrorSchema,
+  perplexityErrorToMessage,
+} from './perplexity-language-model';
 
 type PerplexityEmbeddingConfig = {
   provider: string;
@@ -105,7 +108,7 @@ export class PerplexityEmbeddingModel implements EmbeddingModelV4 {
       },
       failedResponseHandler: createJsonErrorResponseHandler({
         errorSchema: perplexityErrorSchema,
-        errorToMessage: data => data.error.message ?? 'Unknown error',
+        errorToMessage: perplexityErrorToMessage,
       }),
       successfulResponseHandler: createJsonResponseHandler(
         perplexityEmbeddingResponseSchema,

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

@@ -1,146 +1,122 @@
 import { z } from 'zod/v4';
 
-export const perplexityLanguageModelOptions = z.looseObject({
-  /**
-   * Filters search results to those published within the specified time window.
-   * Cannot be combined with other date filters.
-   */
+const userLocationSchema = z.looseObject({
+  latitude: z.number().optional(),
+  longitude: z.number().optional(),
+  country: z.string().optional(),
+  city: z.string().optional(),
+  region: z.string().optional(),
+});
+
+const webSearchFiltersSchema = z.looseObject({
+  search_domain_filter: z.array(z.string()).optional(),
   search_recency_filter: z
     .enum(['hour', 'day', 'week', 'month', 'year'])
     .optional(),
-
-  /**
-   * Restrict web search results to specific domains or URLs.
-   * Prefix a domain with "-" to exclude it.
-   */
-  search_domain_filter: z.array(z.string()).optional(),
-
-  /**
-   * Filter search results by language using ISO 639-1 codes.
-   */
-  search_language_filter: z.array(z.string()).optional(),
-
-  /**
-   * Return search results published after this date.
-   */
   search_after_date_filter: z.string().optional(),
-
-  /**
-   * Return search results published before this date.
-   */
   search_before_date_filter: z.string().optional(),
-
-  /**
-   * Return search results last updated after this date.
-   */
   last_updated_after_filter: z.string().optional(),
-
-  /**
-   * Return search results last updated before this date.
-   */
   last_updated_before_filter: z.string().optional(),
+});
 
-  /**
-   * Source of search results.
-   */
-  search_mode: z.enum(['web', 'academic', 'sec']).optional(),
-
-  /**
-   * If true, the model decides whether web search is needed.
-   */
-  enable_search_classifier: z.boolean().optional(),
+const webSearchToolSchema = z.looseObject({
+  type: z.literal('web_search'),
+  filters: webSearchFiltersSchema.optional(),
+  max_results: z.number().int().positive().optional(),
+  max_tokens: z.number().optional(),
+  max_tokens_per_page: z.number().optional(),
+  search_context_size: z.enum(['low', 'medium', 'high']).optional(),
+  user_location: userLocationSchema.optional(),
+});
 
-  /**
-   * If true, disables web search.
-   */
-  disable_search: z.boolean().optional(),
+const nativeToolSchema = z.union([
+  webSearchToolSchema,
+  z.looseObject({
+    type: z.literal('fetch_url'),
+    max_urls: z.number().optional(),
+  }),
+  z.looseObject({ type: z.literal('people_search') }),
+  z.looseObject({ type: z.literal('finance_search') }),
+  z.looseObject({ type: z.literal('sandbox') }),
+  z.looseObject({
+    type: z.literal('mcp'),
+    server_label: z.string(),
+    server_url: z.string(),
+    allowed_tools: z.array(z.string()).optional(),
+    authorization: z.string().optional(),
+    defer_loading: z.boolean().optional(),
+    headers: z.record(z.string(), z.string()).optional(),
+  }),
+  z.looseObject({
+    type: z.literal('connector'),
+    id: z.string(),
+    server_label: z.string(),
+    server_description: z.string().optional(),
+    allowed_tools: z.array(z.string()).optional(),
+  }),
+]);
 
-  /**
-   * If true, a list of related questions is included in the response.
-   */
-  return_related_questions: z.boolean().optional(),
+export const perplexityLanguageModelOptions = z.looseObject({
+  /** Top-level Agent API instructions. */
+  instructions: z.string().optional(),
 
   /**
-   * If true, image search results are included in the response.
+   * Native Agent API tools. AI SDK function tools can also be supplied through
+   * the top-level `tools` option on `generateText` and `streamText`.
    */
-  return_images: z.boolean().optional(),
+  tools: z.array(nativeToolSchema).optional(),
 
-  /**
-   * Restrict image results to specific domains.
-   * Prefix a domain with "-" to exclude it.
-   */
-  image_domain_filter: z.array(z.string()).optional(),
+  /** A fallback model list for Agent API routing. */
+  models: z.array(z.string()).optional(),
 
-  /**
-   * Restrict image results to specific file formats.
-   */
-  image_format_filter: z.array(z.string()).optional(),
+  /** Maximum number of agentic steps. */
+  max_steps: z.number().int().positive().optional(),
 
-  /**
-   * Additional media response configuration.
-   */
-  media_response: z
-    .looseObject({
-      overrides: z
-        .looseObject({
-          /**
-           * If true, video results are included in the response.
-           */
-          return_videos: z.boolean().optional(),
-        })
-        .optional(),
-    })
-    .optional(),
+  /** Maximum number of native tool calls. */
+  max_tool_calls: z.number().int().nonnegative().optional(),
 
-  /**
-   * Controls the format of streaming events.
-   */
-  stream_mode: z.enum(['full', 'concise']).optional(),
+  /** Continue a conversation from an earlier Agent API response. */
+  previous_response_id: z.string().optional(),
 
   /**
-   * Controls how much effort the model spends on reasoning.
+   * Whether the response can be retrieved later. Setting this to false does
+   * not disable persistence or prevent previous_response_id continuations.
    */
-  reasoning_effort: z.enum(['minimal', 'low', 'medium', 'high']).optional(),
+  store: z.boolean().optional(),
 
-  /**
-   * Preferred response language as an ISO 639-1 language code.
-   */
+  /** Preferred response language as an ISO 639-1 language code. */
   language_preference: z.string().optional(),
 
-  /**
-   * Additional web search configuration.
-   */
-  web_search_options: z
+  /** Agent API reasoning configuration. */
+  reasoning: z
     .looseObject({
-      /**
-       * Controls the size of search context injected into the model.
-       */
-      search_context_size: z.enum(['low', 'medium', 'high']).optional(),
-
-      /**
-       * Controls whether to use fast search, pro search, or automatic routing.
-       */
-      search_type: z.enum(['fast', 'pro', 'auto']).optional(),
-
-      /**
-       * User location for search result personalization.
-       */
-      user_location: z
-        .looseObject({
-          latitude: z.number().optional(),
-          longitude: z.number().optional(),
-          country: z.string().optional(),
-          city: z.string().optional(),
-          region: z.string().optional(),
-        })
-        .optional(),
-
-      /**
-       * If true, applies enhanced relevance filtering to image results.
-       */
-      image_results_enhanced_relevance: z.boolean().optional(),
+      effort: z.enum(['minimal', 'low', 'medium', 'high', 'xhigh']).optional(),
     })
     .optional(),
+
+  /** Agent API skill configuration. */
+  skills: z
+    .array(
+      z.union([
+        z.looseObject({
+          type: z.literal('builtin'),
+          name: z.enum([
+            'office',
+            'office/docx',
+            'office/pdf',
+            'office/pptx',
+            'office/xlsx',
+          ]),
+        }),
+        z.looseObject({
+          type: z.literal('inline'),
+          name: z.string(),
+          description: z.string(),
+          instructions: z.string(),
+        }),
+      ]),
+    )
+    .optional(),
 });
 
 export type PerplexityLanguageModelOptions = z.infer<

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

@@ -1,25 +1,32 @@
-export type PerplexityPrompt = Array<PerplexityMessage>;
+export type PerplexityAgentInput = Array<PerplexityAgentInputItem>;
 
-export type PerplexityMessage = {
-  role: 'system' | 'user' | 'assistant';
-  content: string | PerplexityMessageContent[];
-};
-
-export type PerplexityMessageContent =
+export type PerplexityAgentInputItem =
   | {
-      type: 'text';
-      text: string;
+      type: 'message';
+      role: 'system' | 'developer' | 'user' | 'assistant';
+      content: string | PerplexityAgentInputContent[];
+    }
+  | {
+      type: 'function_call';
+      call_id: string;
+      name: string;
+      arguments: string;
+      thought_signature?: string;
     }
   | {
-      type: 'image_url';
-      image_url: {
-        url: string;
-      };
+      type: 'function_call_output';
+      call_id: string;
+      name?: string;
+      output: string;
+      thought_signature?: string;
+    };
+
+export type PerplexityAgentInputContent =
+  | {
+      type: 'input_text';
+      text: string;
     }
   | {
-      type: 'file_url';
-      file_url: {
-        url: string;
-      };
-      file_name?: string;
+      type: 'input_image';
+      image_url: string;
     };