@ai-sdk/perplexity 5.0.14 → 5.0.16

package/src/convert-to-perplexity-decision-state.ts

@@ -0,0 +1,94 @@
+import {
+  InvalidArgumentError,
+  UnsupportedFunctionalityError,
+  type Experimental_DecisionModelV4State as DecisionModelV4State,
+  type JSONValue,
+} from '@ai-sdk/provider';
+import {
+  convertUint8ArrayToBase64,
+  detectMediaType,
+  isFullMediaType,
+} from '@ai-sdk/provider-utils';
+
+export function convertToPerplexityDecisionState(state: DecisionModelV4State) {
+  const parts = state.map((part): JSONValue => {
+    switch (part.type) {
+      case 'text':
+        return part.text;
+      case 'json':
+        return part.value;
+      case 'file': {
+        if (part.data.type !== 'data') {
+          throw new UnsupportedFunctionalityError({
+            functionality: `Perplexity decision file input: ${part.data.type}`,
+          });
+        }
+        const mediaType = isFullMediaType(part.mediaType)
+          ? part.mediaType
+          : detectMediaType({ data: part.data.data, topLevelType: 'image' });
+        if (
+          !['image/png', 'image/jpeg', 'image/webp'].includes(mediaType ?? '')
+        ) {
+          throw new UnsupportedFunctionalityError({
+            functionality: `Perplexity decision image media type: ${part.mediaType}`,
+          });
+        }
+        const data =
+          typeof part.data.data === 'string'
+            ? part.data.data
+            : convertUint8ArrayToBase64(part.data.data);
+        return {
+          type: 'image_url',
+          image_url: { url: `data:${mediaType};base64,${data}` },
+        };
+      }
+    }
+  });
+
+  if (countImages(parts) > 8) {
+    throw new InvalidArgumentError({
+      argument: 'state',
+      message:
+        'Perplexity Decisions supports at most 8 images in the shared state.',
+    });
+  }
+
+  // Preserve a single string/object/array as native state. Other JSON values
+  // must remain inside an array because the API rejects them at the top level.
+  const single = parts[0];
+  return parts.length === 1 &&
+    single !== null &&
+    (typeof single === 'string' || typeof single === 'object')
+    ? single
+    : parts;
+}
+
+function countImages(value: unknown): number {
+  if (Array.isArray(value)) {
+    return value.reduce<number>((count, item) => count + countImages(item), 0);
+  }
+  if (value === null || typeof value !== 'object') return 0;
+
+  const object = value as Record<string, unknown>;
+  if (object.type === 'image_url') {
+    const image = object.image_url as { url?: unknown } | null | undefined;
+    if (
+      image == null ||
+      typeof image !== 'object' ||
+      Array.isArray(image) ||
+      typeof image.url !== 'string' ||
+      !/^data:image\/(png|jpeg|webp);base64,/i.test(image.url)
+    ) {
+      throw new UnsupportedFunctionalityError({
+        functionality:
+          'Perplexity decision images require PNG, JPEG, or WebP base64 data URLs',
+      });
+    }
+    return 1;
+  }
+
+  return Object.values(value).reduce<number>(
+    (count, item) => count + (item === undefined ? 0 : countImages(item)),
+    0,
+  );
+}

package/src/index.ts

@@ -13,3 +13,7 @@ export type {
   PerplexityEmbeddingModelOptions,
 } from './perplexity-embedding-model-options';
 export { VERSION } from './version';
+export type {
+  PerplexityDecisionModelId,
+  PerplexityDecisionModelOptions,
+} from './perplexity-decision-model-options';

package/src/perplexity-agent-api.ts

@@ -168,7 +168,7 @@ export const perplexityErrorSchema = z.looseObject({
     .union([
       z.string(),
       z.looseObject({
-        code: z.union([z.string(), z.number()]).optional(),
+        code: z.union([z.string(), z.number()]).nullish(),
         message: z.string().nullish(),
         type: z.string().nullish(),
       }),

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

@@ -0,0 +1,13 @@
+export type PerplexityDecisionModelId =
+  | 'pplx-decider-v1.2'
+  | 'pplx-decider-flash-v1.2'
+  | 'pplx-decider-latest'
+  | 'pplx-decider-flash-latest'
+  | 'perplexity/pplx-decider-latest'
+  | 'perplexity/pplx-decider-flash-latest'
+  | 'pplx-decider-v1.1-27b'
+  | 'pplx-decider-v1-27b'
+  | (string & {});
+
+/** Perplexity decision models do not support provider-specific options. */
+export type PerplexityDecisionModelOptions = Record<string, never>;

package/src/perplexity-decision-model.ts

@@ -0,0 +1,282 @@
+import {
+  Experimental_DecisionUnsupportedQuestionTypeError as DecisionUnsupportedQuestionTypeError,
+  InvalidArgumentError,
+  InvalidResponseDataError,
+  type Experimental_DecisionModelV4 as DecisionModelV4,
+  type Experimental_DecisionModelV4Answer as DecisionModelV4Answer,
+} from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  createJsonErrorResponseHandler,
+  createJsonResponseHandler,
+  postJsonToApi,
+  resolve,
+  serializeModelOptions,
+  WORKFLOW_DESERIALIZE,
+  WORKFLOW_SERIALIZE,
+  type FetchFunction,
+  type Resolvable,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { convertToPerplexityDecisionState } from './convert-to-perplexity-decision-state';
+import {
+  perplexityErrorSchema,
+  perplexityErrorToMessage,
+} from './perplexity-agent-api';
+
+import type { PerplexityDecisionModelId } from './perplexity-decision-model-options';
+
+type PerplexityDecisionConfig = {
+  provider: string;
+  baseURL: string;
+  headers: Resolvable<Record<string, string | undefined>>;
+  fetch?: FetchFunction;
+};
+
+export class DecisionPerplexityModel implements DecisionModelV4 {
+  readonly specificationVersion = 'v4';
+  readonly supportedQuestionTypes = ['choice', 'score', 'boolean'] as const;
+
+  constructor(
+    readonly modelId: PerplexityDecisionModelId,
+    private readonly config: PerplexityDecisionConfig,
+  ) {}
+
+  get provider() {
+    return this.config.provider;
+  }
+
+  static [WORKFLOW_SERIALIZE](model: DecisionPerplexityModel) {
+    return serializeModelOptions({
+      modelId: model.modelId,
+      config: model.config,
+    });
+  }
+
+  static [WORKFLOW_DESERIALIZE](options: {
+    modelId: PerplexityDecisionModelId;
+    config: PerplexityDecisionConfig;
+  }) {
+    return new DecisionPerplexityModel(options.modelId, options.config);
+  }
+
+  async doDecide({
+    state,
+    questions,
+    maxOutputTokens,
+    reasoning,
+    headers,
+    abortSignal,
+    providerOptions,
+  }: Parameters<DecisionModelV4['doDecide']>[0]): Promise<
+    Awaited<ReturnType<DecisionModelV4['doDecide']>>
+  > {
+    const entries = Object.entries(questions);
+    if (entries.length === 0 || entries.length > 128) {
+      throw new InvalidArgumentError({
+        argument: 'questions',
+        message:
+          'Perplexity Decisions supports 1 to 128 questions per request.',
+      });
+    }
+    const nativeQuestions = Object.fromEntries(
+      entries.map(([id, question]) => {
+        if (id.length === 0) {
+          throw new InvalidArgumentError({
+            argument: 'questions',
+            message: 'Perplexity Decisions requires non-empty question names.',
+          });
+        }
+        switch (question.type) {
+          case 'boolean':
+            return [
+              id,
+              {
+                type: 'noul',
+                instructions: question.instructions,
+                criteria: question.criteria,
+              },
+            ];
+          case 'choice': {
+            const count = Object.keys(question.criteria).length;
+            if (count === 0 || count > 255) {
+              throw new InvalidArgumentError({
+                argument: `questions.${id}.criteria`,
+                message:
+                  'Perplexity Choice questions support 1 to 255 options.',
+              });
+            }
+            return [
+              id,
+              {
+                type: 'choice',
+                instructions: question.instructions,
+                criteria: question.criteria,
+              },
+            ];
+          }
+          case 'score':
+            if (
+              question.criteria.length === 0 ||
+              question.criteria.length > 10 ||
+              question.criteria.some(level => level === null)
+            ) {
+              throw new InvalidArgumentError({
+                argument: `questions.${id}.criteria`,
+                message:
+                  'Perplexity Score questions require 1 to 10 non-null levels.',
+              });
+            }
+            return [
+              id,
+              {
+                type: 'score',
+                instructions: question.instructions,
+                criteria: question.criteria,
+              },
+            ];
+          default:
+            throw new DecisionUnsupportedQuestionTypeError({
+              questionId: id,
+              questionType: question.type,
+              provider: this.provider,
+              modelId: this.modelId,
+            });
+        }
+      }),
+    );
+
+    const {
+      value: response,
+      rawValue,
+      responseHeaders,
+    } = await postJsonToApi({
+      url: `${this.config.baseURL}/v1/decisions`,
+      headers: combineHeaders(await resolve(this.config.headers), headers),
+      body: {
+        model: this.modelId,
+        state: convertToPerplexityDecisionState(state),
+        questions: nativeQuestions,
+      },
+      abortSignal,
+      fetch: this.config.fetch,
+      failedResponseHandler: createJsonErrorResponseHandler({
+        errorSchema: perplexityErrorSchema,
+        errorToMessage: perplexityErrorToMessage,
+      }),
+      successfulResponseHandler: createJsonResponseHandler(
+        perplexityDecisionResponseSchema,
+      ),
+    });
+
+    if (
+      Object.keys(response.answers).length !== entries.length ||
+      entries.some(
+        ([id]) => !Object.prototype.hasOwnProperty.call(response.answers, id),
+      )
+    ) {
+      throw new InvalidResponseDataError({
+        data: rawValue,
+        message:
+          'Perplexity Decisions must return exactly one answer for every question.',
+      });
+    }
+
+    return {
+      answers: Object.fromEntries(
+        Object.entries(response.answers).map(
+          ([id, answer]): [string, DecisionModelV4Answer] => [
+            id,
+            answer.type === 'noul'
+              ? { type: 'boolean', probability: answer.noul }
+              : answer.type === 'choice'
+                ? {
+                    type: 'choice',
+                    choice: answer.choice,
+                    probabilities: answer.probabilities,
+                  }
+                : {
+                    type: 'score',
+                    score: answer.score,
+                    probabilities: answer.probabilities,
+                  },
+          ],
+        ),
+      ),
+      usage:
+        response.usage == null
+          ? undefined
+          : {
+              inputTokens: response.usage.input_tokens ?? undefined,
+              outputTokens: response.usage.output_tokens ?? undefined,
+            },
+      // Perplexity returns full-precision probabilities; no rounding allowance.
+      warnings: [
+        ...(maxOutputTokens != null
+          ? [{ type: 'unsupported' as const, feature: 'maxOutputTokens' }]
+          : []),
+        ...(reasoning != null
+          ? [{ type: 'unsupported' as const, feature: 'reasoning' }]
+          : []),
+        ...Object.keys(providerOptions?.perplexity ?? {}).map(option => ({
+          type: 'unsupported' as const,
+          feature: `providerOptions.perplexity.${option}`,
+        })),
+      ],
+      providerMetadata: {
+        perplexity: {
+          confidence: Object.fromEntries(
+            Object.entries(response.answers).flatMap(([id, answer]) =>
+              answer.type !== 'noul' && answer.confidence != null
+                ? [[id, answer.confidence]]
+                : [],
+            ),
+          ),
+          legend: Object.fromEntries(
+            Object.entries(response.answers).flatMap(([id, answer]) =>
+              answer.type === 'score' && answer.legend != null
+                ? [[id, answer.legend]]
+                : [],
+            ),
+          ),
+        },
+      },
+      response: {
+        id: responseHeaders?.['x-request-id'],
+        modelId: response.model ?? this.modelId,
+        headers: responseHeaders,
+        body: rawValue,
+      },
+    };
+  }
+}
+
+const probability = z.number().min(0).max(1);
+const perplexityDecisionResponseSchema = z.object({
+  model: z.string().nullish(),
+  answers: z.record(
+    z.string(),
+    z.discriminatedUnion('type', [
+      z.object({ type: z.literal('noul'), noul: probability }),
+      z.object({
+        type: z.literal('choice'),
+        choice: z.string(),
+        probabilities: z.record(z.string(), probability),
+        confidence: probability.nullish(),
+      }),
+      z.object({
+        type: z.literal('score'),
+        score: z.number(),
+        probabilities: z.record(z.string(), probability),
+        confidence: probability.nullish(),
+        legend: z.record(z.string(), z.json()).nullish(),
+      }),
+    ]),
+  ),
+  usage: z
+    .object({
+      input_tokens: z.number().nullish(),
+      output_tokens: z.number().nullish(),
+    })
+    .nullish(),
+});

package/src/perplexity-provider.ts

@@ -1,5 +1,6 @@
 import {
   NoSuchModelError,
+  type Experimental_DecisionModelV4 as DecisionModelV4,
   type LanguageModelV4,
   type EmbeddingModelV4,
   type ProviderV4,
@@ -12,12 +13,17 @@ import {
   type FetchFunction,
 } from '@ai-sdk/provider-utils';
 import { PerplexityEmbeddingModel } from './perplexity-embedding-model';
+import { DecisionPerplexityModel } from './perplexity-decision-model';
+import type { PerplexityDecisionModelId } from './perplexity-decision-model-options';
 import type { PerplexityEmbeddingModelId } from './perplexity-embedding-model-options';
 import { PerplexityLanguageModel } from './perplexity-language-model';
 import type { PerplexityLanguageModelId } from './perplexity-options';
 import { VERSION } from './version';
 
 export interface PerplexityProvider extends ProviderV4 {
+  /** Creates an experimental decision model using the Perplexity Decisions API. */
+  decisionModel(modelId: PerplexityDecisionModelId): DecisionModelV4;
+
   /**
    * Creates a Perplexity Agent API model or preset for text generation.
    */
@@ -110,6 +116,13 @@ export function createPerplexity(
 
   provider.specificationVersion = 'v4' as const;
   provider.languageModel = createLanguageModel;
+  provider.decisionModel = (modelId: PerplexityDecisionModelId) =>
+    new DecisionPerplexityModel(modelId, {
+      provider: 'perplexity.decision',
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
 
   provider.embedding = createEmbeddingModel;
   provider.embeddingModel = createEmbeddingModel;