@ai-sdk/provider 3.0.1 → 3.0.3

package/src/embedding-model-middleware/v3/embedding-model-v3-middleware.ts

@@ -0,0 +1,69 @@
+import { EmbeddingModelV3 } from '../../embedding-model/v3/embedding-model-v3';
+import { EmbeddingModelV3CallOptions } from '../../embedding-model/v3/embedding-model-v3-call-options';
+
+/**
+ * Middleware for EmbeddingModelV3.
+ * This type defines the structure for middleware that can be used to modify
+ * the behavior of EmbeddingModelV3 operations.
+ */
+export type EmbeddingModelV3Middleware = {
+  /**
+   * Middleware specification version. Use `v3` for the current version.
+   */
+  readonly specificationVersion: 'v3';
+
+  /**
+   * Override the provider name if desired.
+   * @param options.model - The embedding model instance.
+   */
+  overrideProvider?: (options: { model: EmbeddingModelV3 }) => string;
+
+  /**
+   * Override the model ID if desired.
+   * @param options.model - The embedding model instance.
+   */
+  overrideModelId?: (options: { model: EmbeddingModelV3 }) => string;
+
+  /**
+   * Override the limit of how many embeddings can be generated in a single API call if desired.
+   * @param options.model - The embedding model instance.
+   */
+  overrideMaxEmbeddingsPerCall?: (options: {
+    model: EmbeddingModelV3;
+  }) => PromiseLike<number | undefined> | number | undefined;
+
+  /**
+   * Override support for handling multiple embedding calls in parallel, if desired..
+   * @param options.model - The embedding model instance.
+   */
+  overrideSupportsParallelCalls?: (options: {
+    model: EmbeddingModelV3;
+  }) => PromiseLike<boolean> | boolean;
+
+  /**
+   * Transforms the parameters before they are passed to the embed model.
+   * @param options - Object containing the type of operation and the parameters.
+   * @param options.params - The original parameters for the embedding model call.
+   * @returns A promise that resolves to the transformed parameters.
+   */
+  transformParams?: (options: {
+    params: EmbeddingModelV3CallOptions;
+    model: EmbeddingModelV3;
+  }) => PromiseLike<EmbeddingModelV3CallOptions>;
+
+  /**
+   * Wraps the embed operation of the embedding model.
+   *
+   * @param options - Object containing the embed function, parameters, and model.
+   * @param options.doEmbed - The original embed function.
+   * @param options.params - The parameters for the embed call. If the
+   * `transformParams` middleware is used, this will be the transformed parameters.
+   * @param options.model - The embedding model instance.
+   * @returns A promise that resolves to the result of the generate operation.
+   */
+  wrapEmbed?: (options: {
+    doEmbed: () => ReturnType<EmbeddingModelV3['doEmbed']>;
+    params: EmbeddingModelV3CallOptions;
+    model: EmbeddingModelV3;
+  }) => Promise<Awaited<ReturnType<EmbeddingModelV3['doEmbed']>>>;
+};

package/src/embedding-model-middleware/v3/index.ts

@@ -0,0 +1 @@
+export * from './embedding-model-v3-middleware';

package/src/errors/ai-sdk-error.ts

@@ -0,0 +1,62 @@
+/**
+ * Symbol used for identifying AI SDK Error instances.
+ * Enables checking if an error is an instance of AISDKError across package versions.
+ */
+const marker = 'vercel.ai.error';
+const symbol = Symbol.for(marker);
+
+/**
+ * Custom error class for AI SDK related errors.
+ * @extends Error
+ */
+export class AISDKError extends Error {
+  private readonly [symbol] = true; // used in isInstance
+
+  /**
+   * The underlying cause of the error, if any.
+   */
+  readonly cause?: unknown;
+
+  /**
+   * Creates an AI SDK Error.
+   *
+   * @param {Object} params - The parameters for creating the error.
+   * @param {string} params.name - The name of the error.
+   * @param {string} params.message - The error message.
+   * @param {unknown} [params.cause] - The underlying cause of the error.
+   */
+  constructor({
+    name,
+    message,
+    cause,
+  }: {
+    name: string;
+    message: string;
+    cause?: unknown;
+  }) {
+    super(message);
+
+    this.name = name;
+    this.cause = cause;
+  }
+
+  /**
+   * Checks if the given error is an AI SDK Error.
+   * @param {unknown} error - The error to check.
+   * @returns {boolean} True if the error is an AI SDK Error, false otherwise.
+   */
+  static isInstance(error: unknown): error is AISDKError {
+    return AISDKError.hasMarker(error, marker);
+  }
+
+  protected static hasMarker(error: unknown, marker: string): boolean {
+    const markerSymbol = Symbol.for(marker);
+    return (
+      error != null &&
+      typeof error === 'object' &&
+      markerSymbol in error &&
+      typeof error[markerSymbol] === 'boolean' &&
+      error[markerSymbol] === true
+    );
+  }
+}

package/src/errors/api-call-error.ts

@@ -0,0 +1,59 @@
+import { AISDKError } from './ai-sdk-error';
+
+const name = 'AI_APICallError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+export class APICallError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly url: string;
+  readonly requestBodyValues: unknown;
+  readonly statusCode?: number;
+
+  readonly responseHeaders?: Record<string, string>;
+  readonly responseBody?: string;
+
+  readonly isRetryable: boolean;
+  readonly data?: unknown;
+
+  constructor({
+    message,
+    url,
+    requestBodyValues,
+    statusCode,
+    responseHeaders,
+    responseBody,
+    cause,
+    isRetryable = statusCode != null &&
+      (statusCode === 408 || // request timeout
+        statusCode === 409 || // conflict
+        statusCode === 429 || // too many requests
+        statusCode >= 500), // server error
+    data,
+  }: {
+    message: string;
+    url: string;
+    requestBodyValues: unknown;
+    statusCode?: number;
+    responseHeaders?: Record<string, string>;
+    responseBody?: string;
+    cause?: unknown;
+    isRetryable?: boolean;
+    data?: unknown;
+  }) {
+    super({ name, message, cause });
+
+    this.url = url;
+    this.requestBodyValues = requestBodyValues;
+    this.statusCode = statusCode;
+    this.responseHeaders = responseHeaders;
+    this.responseBody = responseBody;
+    this.isRetryable = isRetryable;
+    this.data = data;
+  }
+
+  static isInstance(error: unknown): error is APICallError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/errors/empty-response-body-error.ts

@@ -0,0 +1,17 @@
+import { AISDKError } from './ai-sdk-error';
+
+const name = 'AI_EmptyResponseBodyError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+export class EmptyResponseBodyError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  constructor({ message = 'Empty response body' }: { message?: string } = {}) {
+    super({ name, message });
+  }
+
+  static isInstance(error: unknown): error is EmptyResponseBodyError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/errors/get-error-message.ts

@@ -0,0 +1,15 @@
+export function getErrorMessage(error: unknown | undefined) {
+  if (error == null) {
+    return 'unknown error';
+  }
+
+  if (typeof error === 'string') {
+    return error;
+  }
+
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return JSON.stringify(error);
+}

package/src/errors/index.ts

@@ -0,0 +1,15 @@
+export { AISDKError } from './ai-sdk-error';
+export { APICallError } from './api-call-error';
+export { EmptyResponseBodyError } from './empty-response-body-error';
+export { getErrorMessage } from './get-error-message';
+export { InvalidArgumentError } from './invalid-argument-error';
+export { InvalidPromptError } from './invalid-prompt-error';
+export { InvalidResponseDataError } from './invalid-response-data-error';
+export { JSONParseError } from './json-parse-error';
+export { LoadAPIKeyError } from './load-api-key-error';
+export { LoadSettingError } from './load-setting-error';
+export { NoContentGeneratedError } from './no-content-generated-error';
+export { NoSuchModelError } from './no-such-model-error';
+export { TooManyEmbeddingValuesForCallError } from './too-many-embedding-values-for-call-error';
+export { TypeValidationError } from './type-validation-error';
+export { UnsupportedFunctionalityError } from './unsupported-functionality-error';

package/src/errors/invalid-argument-error.ts

@@ -0,0 +1,32 @@
+import { AISDKError } from './ai-sdk-error';
+
+const name = 'AI_InvalidArgumentError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * A function argument is invalid.
+ */
+export class InvalidArgumentError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly argument: string;
+
+  constructor({
+    message,
+    cause,
+    argument,
+  }: {
+    argument: string;
+    message: string;
+    cause?: unknown;
+  }) {
+    super({ name, message, cause });
+
+    this.argument = argument;
+  }
+
+  static isInstance(error: unknown): error is InvalidArgumentError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/errors/invalid-prompt-error.ts

@@ -0,0 +1,33 @@
+import { AISDKError } from './ai-sdk-error';
+
+const name = 'AI_InvalidPromptError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * A prompt is invalid. This error should be thrown by providers when they cannot
+ * process a prompt.
+ */
+export class InvalidPromptError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly prompt: unknown;
+
+  constructor({
+    prompt,
+    message,
+    cause,
+  }: {
+    prompt: unknown;
+    message: string;
+    cause?: unknown;
+  }) {
+    super({ name, message: `Invalid prompt: ${message}`, cause });
+
+    this.prompt = prompt;
+  }
+
+  static isInstance(error: unknown): error is InvalidPromptError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/errors/invalid-response-data-error.ts

@@ -0,0 +1,31 @@
+import { AISDKError } from './ai-sdk-error';
+
+const name = 'AI_InvalidResponseDataError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * Server returned a response with invalid data content.
+ * This should be thrown by providers when they cannot parse the response from the API.
+ */
+export class InvalidResponseDataError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly data: unknown;
+
+  constructor({
+    data,
+    message = `Invalid response data: ${JSON.stringify(data)}.`,
+  }: {
+    data: unknown;
+    message?: string;
+  }) {
+    super({ name, message });
+
+    this.data = data;
+  }
+
+  static isInstance(error: unknown): error is InvalidResponseDataError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/errors/json-parse-error.ts

@@ -0,0 +1,29 @@
+import { AISDKError } from './ai-sdk-error';
+import { getErrorMessage } from './get-error-message';
+
+const name = 'AI_JSONParseError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+export class JSONParseError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly text: string;
+
+  constructor({ text, cause }: { text: string; cause: unknown }) {
+    super({
+      name,
+      message:
+        `JSON parsing failed: ` +
+        `Text: ${text}.\n` +
+        `Error message: ${getErrorMessage(cause)}`,
+      cause,
+    });
+
+    this.text = text;
+  }
+
+  static isInstance(error: unknown): error is JSONParseError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/errors/load-api-key-error.ts

@@ -0,0 +1,17 @@
+import { AISDKError } from './ai-sdk-error';
+
+const name = 'AI_LoadAPIKeyError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+export class LoadAPIKeyError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  constructor({ message }: { message: string }) {
+    super({ name, message });
+  }
+
+  static isInstance(error: unknown): error is LoadAPIKeyError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/errors/load-setting-error.ts

@@ -0,0 +1,17 @@
+import { AISDKError } from './ai-sdk-error';
+
+const name = 'AI_LoadSettingError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+export class LoadSettingError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  constructor({ message }: { message: string }) {
+    super({ name, message });
+  }
+
+  static isInstance(error: unknown): error is LoadSettingError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/errors/no-content-generated-error.ts

@@ -0,0 +1,22 @@
+import { AISDKError } from './ai-sdk-error';
+
+const name = 'AI_NoContentGeneratedError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+Thrown when the AI provider fails to generate any content.
+ */
+export class NoContentGeneratedError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  constructor({
+    message = 'No content generated.',
+  }: { message?: string } = {}) {
+    super({ name, message });
+  }
+
+  static isInstance(error: unknown): error is NoContentGeneratedError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/errors/no-such-model-error.ts

@@ -0,0 +1,45 @@
+import { AISDKError } from './ai-sdk-error';
+
+const name = 'AI_NoSuchModelError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+export class NoSuchModelError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly modelId: string;
+  readonly modelType:
+    | 'languageModel'
+    | 'embeddingModel'
+    | 'imageModel'
+    | 'transcriptionModel'
+    | 'speechModel'
+    | 'rerankingModel';
+
+  constructor({
+    errorName = name,
+    modelId,
+    modelType,
+    message = `No such ${modelType}: ${modelId}`,
+  }: {
+    errorName?: string;
+    modelId: string;
+    modelType:
+      | 'languageModel'
+      | 'embeddingModel'
+      | 'imageModel'
+      | 'transcriptionModel'
+      | 'speechModel'
+      | 'rerankingModel';
+    message?: string;
+  }) {
+    super({ name: errorName, message });
+
+    this.modelId = modelId;
+    this.modelType = modelType;
+  }
+
+  static isInstance(error: unknown): error is NoSuchModelError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/errors/too-many-embedding-values-for-call-error.ts

@@ -0,0 +1,40 @@
+import { AISDKError } from './ai-sdk-error';
+
+const name = 'AI_TooManyEmbeddingValuesForCallError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+export class TooManyEmbeddingValuesForCallError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly provider: string;
+  readonly modelId: string;
+  readonly maxEmbeddingsPerCall: number;
+  readonly values: Array<unknown>;
+
+  constructor(options: {
+    provider: string;
+    modelId: string;
+    maxEmbeddingsPerCall: number;
+    values: Array<unknown>;
+  }) {
+    super({
+      name,
+      message:
+        `Too many values for a single embedding call. ` +
+        `The ${options.provider} model "${options.modelId}" can only embed up to ` +
+        `${options.maxEmbeddingsPerCall} values per call, but ${options.values.length} values were provided.`,
+    });
+
+    this.provider = options.provider;
+    this.modelId = options.modelId;
+    this.maxEmbeddingsPerCall = options.maxEmbeddingsPerCall;
+    this.values = options.values;
+  }
+
+  static isInstance(
+    error: unknown,
+  ): error is TooManyEmbeddingValuesForCallError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/errors/type-validation-error.ts

@@ -0,0 +1,51 @@
+import { AISDKError } from './ai-sdk-error';
+import { getErrorMessage } from './get-error-message';
+
+const name = 'AI_TypeValidationError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+export class TypeValidationError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly value: unknown;
+
+  constructor({ value, cause }: { value: unknown; cause: unknown }) {
+    super({
+      name,
+      message:
+        `Type validation failed: ` +
+        `Value: ${JSON.stringify(value)}.\n` +
+        `Error message: ${getErrorMessage(cause)}`,
+      cause,
+    });
+
+    this.value = value;
+  }
+
+  static isInstance(error: unknown): error is TypeValidationError {
+    return AISDKError.hasMarker(error, marker);
+  }
+
+  /**
+   * Wraps an error into a TypeValidationError.
+   * If the cause is already a TypeValidationError with the same value, it returns the cause.
+   * Otherwise, it creates a new TypeValidationError.
+   *
+   * @param {Object} params - The parameters for wrapping the error.
+   * @param {unknown} params.value - The value that failed validation.
+   * @param {unknown} params.cause - The original error or cause of the validation failure.
+   * @returns {TypeValidationError} A TypeValidationError instance.
+   */
+  static wrap({
+    value,
+    cause,
+  }: {
+    value: unknown;
+    cause: unknown;
+  }): TypeValidationError {
+    return TypeValidationError.isInstance(cause) && cause.value === value
+      ? cause
+      : new TypeValidationError({ value, cause });
+  }
+}

package/src/errors/unsupported-functionality-error.ts

@@ -0,0 +1,26 @@
+import { AISDKError } from './ai-sdk-error';
+
+const name = 'AI_UnsupportedFunctionalityError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+export class UnsupportedFunctionalityError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly functionality: string;
+
+  constructor({
+    functionality,
+    message = `'${functionality}' functionality not supported.`,
+  }: {
+    functionality: string;
+    message?: string;
+  }) {
+    super({ name, message });
+    this.functionality = functionality;
+  }
+
+  static isInstance(error: unknown): error is UnsupportedFunctionalityError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/image-model/index.ts

@@ -0,0 +1,2 @@
+export * from './v3/index';
+export * from './v2/index';

package/src/image-model/v2/image-model-v2-call-options.ts

@@ -0,0 +1,60 @@
+import { SharedV2ProviderOptions } from '../../shared';
+
+export type ImageModelV2CallOptions = {
+  /**
+Prompt for the image generation.
+     */
+  prompt: string;
+
+  /**
+Number of images to generate.
+ */
+  n: number;
+
+  /**
+Size of the images to generate.
+Must have the format `{width}x{height}`.
+`undefined` will use the provider's default size.
+ */
+  size: `${number}x${number}` | undefined;
+
+  /**
+Aspect ratio of the images to generate.
+Must have the format `{width}:{height}`.
+`undefined` will use the provider's default aspect ratio.
+ */
+  aspectRatio: `${number}:${number}` | undefined;
+
+  /**
+Seed for the image generation.
+`undefined` will use the provider's default seed.
+ */
+  seed: number | undefined;
+
+  /**
+Additional provider-specific options that are passed through to the provider
+as body parameters.
+
+The outer record is keyed by the provider name, and the inner
+record is keyed by the provider-specific metadata key.
+```ts
+{
+  "openai": {
+    "style": "vivid"
+  }
+}
+```
+ */
+  providerOptions: SharedV2ProviderOptions;
+
+  /**
+Abort signal for cancelling the operation.
+ */
+  abortSignal?: AbortSignal;
+
+  /**
+Additional HTTP headers to be sent with the request.
+Only applicable for HTTP-based providers.
+ */
+  headers?: Record<string, string | undefined>;
+};

package/src/image-model/v2/image-model-v2-call-warning.ts

@@ -0,0 +1,16 @@
+import { ImageModelV2CallOptions } from './image-model-v2-call-options';
+
+/**
+Warning from the model provider for this call. The call will proceed, but e.g.
+some settings might not be supported, which can lead to suboptimal results.
+ */
+export type ImageModelV2CallWarning =
+  | {
+      type: 'unsupported-setting';
+      setting: keyof ImageModelV2CallOptions;
+      details?: string;
+    }
+  | {
+      type: 'other';
+      message: string;
+    };