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

package/src/provider/v3/provider-v3.ts

@@ -0,0 +1,93 @@
+import { EmbeddingModelV3 } from '../../embedding-model/v3/embedding-model-v3';
+import { ImageModelV3 } from '../../image-model/v3/image-model-v3';
+import { LanguageModelV3 } from '../../language-model/v3/language-model-v3';
+import { RerankingModelV3 } from '../../reranking-model/v3/reranking-model-v3';
+import { SpeechModelV3 } from '../../speech-model/v3/speech-model-v3';
+import { TranscriptionModelV3 } from '../../transcription-model/v3/transcription-model-v3';
+
+/**
+ * Provider for language, text embedding, and image generation models.
+ */
+export interface ProviderV3 {
+  readonly specificationVersion: 'v3';
+
+  /**
+   * Returns the language model with the given id.
+   * The model id is then passed to the provider function to get the model.
+   *
+   * @param {string} modelId - The id of the model to return.
+   *
+   * @returns {LanguageModel} The language model associated with the id
+   *
+   * @throws {NoSuchModelError} If no such model exists.
+   */
+  languageModel(modelId: string): LanguageModelV3;
+
+  /**
+   * Returns the text embedding model with the given id.
+   * The model id is then passed to the provider function to get the model.
+   *
+   * @param {string} modelId - The id of the model to return.
+   *
+   * @returns {LanguageModel} The language model associated with the id
+   *
+   * @throws {NoSuchModelError} If no such model exists.
+   */
+  embeddingModel(modelId: string): EmbeddingModelV3;
+
+  /**
+   * Returns the text embedding model with the given id.
+   * The model id is then passed to the provider function to get the model.
+   *
+   * @param {string} modelId - The id of the model to return.
+   *
+   * @returns {EmbeddingModel} The embedding model associated with the id
+   *
+   * @throws {NoSuchModelError} If no such model exists.
+   *
+   * @deprecated Use `embeddingModel` instead.
+   */
+  textEmbeddingModel?(modelId: string): EmbeddingModelV3;
+
+  /**
+   * Returns the image model with the given id.
+   * The model id is then passed to the provider function to get the model.
+   *
+   * @param {string} modelId - The id of the model to return.
+   *
+   * @returns {ImageModel} The image model associated with the id
+   */
+  imageModel(modelId: string): ImageModelV3;
+
+  /**
+   * Returns the transcription model with the given id.
+   * The model id is then passed to the provider function to get the model.
+   *
+   * @param {string} modelId - The id of the model to return.
+   *
+   * @returns {TranscriptionModel} The transcription model associated with the id
+   */
+  transcriptionModel?(modelId: string): TranscriptionModelV3;
+
+  /**
+   * Returns the speech model with the given id.
+   * The model id is then passed to the provider function to get the model.
+   *
+   * @param {string} modelId - The id of the model to return.
+   *
+   * @returns {SpeechModel} The speech model associated with the id
+   */
+  speechModel?(modelId: string): SpeechModelV3;
+
+  /**
+   * Returns the reranking model with the given id.
+   * The model id is then passed to the provider function to get the model.
+   *
+   * @param {string} modelId - The id of the model to return.
+   *
+   * @returns {RerankingModel} The reranking model associated with the id
+   *
+   * @throws {NoSuchModelError} If no such model exists.
+   */
+  rerankingModel?(modelId: string): RerankingModelV3;
+}

package/src/reranking-model/index.ts

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

package/src/reranking-model/v3/index.ts

@@ -0,0 +1,2 @@
+export type { RerankingModelV3 } from './reranking-model-v3';
+export type { RerankingModelV3CallOptions } from './reranking-model-v3-call-options';

package/src/reranking-model/v3/reranking-model-v3-call-options.ts

@@ -0,0 +1,40 @@
+import { JSONObject } from '../../json-value';
+import { SharedV3Headers, SharedV3ProviderOptions } from '../../shared/v3';
+
+export type RerankingModelV3CallOptions = {
+  /**
+   * Documents to rerank.
+   * Either a list of texts or a list of JSON objects.
+   */
+  documents:
+    | { type: 'text'; values: string[] }
+    | { type: 'object'; values: JSONObject[] };
+
+  /**
+   * The query is a string that represents the query to rerank the documents against.
+   */
+  query: string;
+
+  /**
+   * Optional limit returned documents to the top n documents.
+   */
+  topN?: number;
+
+  /**
+   * Abort signal for cancelling the operation.
+   */
+  abortSignal?: AbortSignal;
+
+  /**
+   * Additional provider-specific options. They are passed through
+   * to the provider from the AI SDK and enable provider-specific
+   * functionality that can be fully encapsulated in the provider.
+   */
+  providerOptions?: SharedV3ProviderOptions;
+
+  /**
+   * Additional HTTP headers to be sent with the request.
+   * Only applicable for HTTP-based providers.
+   */
+  headers?: SharedV3Headers;
+};

package/src/reranking-model/v3/reranking-model-v3.ts

@@ -0,0 +1,90 @@
+import {
+  SharedV3Headers,
+  SharedV3ProviderMetadata,
+  SharedV3Warning,
+} from '../../shared/v3/';
+import { RerankingModelV3CallOptions } from './reranking-model-v3-call-options';
+
+/**
+ * Specification for a reranking model that implements the reranking model interface version 3.
+ */
+export type RerankingModelV3 = {
+  /**
+   * The reranking model must specify which reranking model interface version it implements.
+   */
+  readonly specificationVersion: 'v3';
+
+  /**
+   * Provider ID.
+   */
+  readonly provider: string;
+
+  /**
+   * Provider-specific model ID.
+   */
+  readonly modelId: string;
+
+  /**
+   * Reranking a list of documents using the query.
+   */
+  // Naming: "do" prefix to prevent accidental direct usage of the method by the user.
+  doRerank(options: RerankingModelV3CallOptions): PromiseLike<{
+    /**
+     * Ordered list of reranked documents (via index before reranking).
+     * The documents are sorted by the descending order of relevance scores.
+     */
+    ranking: Array<{
+      /**
+       * The index of the document in the original list of documents before reranking.
+       */
+      index: number;
+
+      /**
+       * The relevance score of the document after reranking.
+       */
+      relevanceScore: number;
+    }>;
+
+    /**
+     * Additional provider-specific metadata. They are passed through
+     * to the provider from the AI SDK and enable provider-specific
+     * functionality that can be fully encapsulated in the provider.
+     */
+    providerMetadata?: SharedV3ProviderMetadata;
+
+    /**
+     * Warnings for the call, e.g. unsupported settings.
+     */
+    warnings?: Array<SharedV3Warning>;
+
+    /**
+     * Optional response information for debugging purposes.
+     */
+    response?: {
+      /**
+       * ID for the generated response, if the provider sends one.
+       */
+      id?: string;
+
+      /**
+       * Timestamp for the start of the generated response, if the provider sends one.
+       */
+      timestamp?: Date;
+
+      /**
+       * The ID of the response model that was used to generate the response, if the provider sends one.
+       */
+      modelId?: string;
+
+      /**
+       * Response headers.
+       */
+      headers?: SharedV3Headers;
+
+      /**
+       * Response body.
+       */
+      body?: unknown;
+    };
+  }>;
+};

package/src/shared/index.ts

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

package/src/shared/v2/index.ts

@@ -0,0 +1,3 @@
+export * from './shared-v2-headers';
+export * from './shared-v2-provider-metadata';
+export * from './shared-v2-provider-options';

package/src/shared/v2/shared-v2-headers.ts

@@ -0,0 +1 @@
+export type SharedV2Headers = Record<string, string>;

package/src/shared/v2/shared-v2-provider-metadata.ts

@@ -0,0 +1,27 @@
+import { JSONValue } from '../../json-value/json-value';
+
+/**
+ * Additional provider-specific metadata.
+ * Metadata are additional outputs from the provider.
+ * They are passed through to the provider from the AI SDK
+ * and enable provider-specific functionality
+ * that can be fully encapsulated in the provider.
+ *
+ * This enables us to quickly ship provider-specific functionality
+ * without affecting the core AI SDK.
+ *
+ * The outer record is keyed by the provider name, and the inner
+ * record is keyed by the provider-specific metadata key.
+ *
+ * ```ts
+ * {
+ *   "anthropic": {
+ *     "cacheControl": { "type": "ephemeral" }
+ *   }
+ * }
+ * ```
+ */
+export type SharedV2ProviderMetadata = Record<
+  string,
+  Record<string, JSONValue>
+>;

package/src/shared/v2/shared-v2-provider-options.ts

@@ -0,0 +1,24 @@
+import { JSONValue } from '../../json-value/json-value';
+
+/**
+ * Additional provider-specific options.
+ * Options are additional input to the provider.
+ * They are passed through to the provider from the AI SDK
+ * and enable provider-specific functionality
+ * that can be fully encapsulated in the provider.
+ *
+ * This enables us to quickly ship provider-specific functionality
+ * without affecting the core AI SDK.
+ *
+ * The outer record is keyed by the provider name, and the inner
+ * record is keyed by the provider-specific metadata key.
+ *
+ * ```ts
+ * {
+ *   "anthropic": {
+ *     "cacheControl": { "type": "ephemeral" }
+ *   }
+ * }
+ * ```
+ */
+export type SharedV2ProviderOptions = Record<string, Record<string, JSONValue>>;

package/src/shared/v3/index.ts

@@ -0,0 +1,4 @@
+export * from './shared-v3-headers';
+export * from './shared-v3-provider-metadata';
+export * from './shared-v3-provider-options';
+export * from './shared-v3-warning';

package/src/shared/v3/shared-v3-headers.ts

@@ -0,0 +1 @@
+export type SharedV3Headers = Record<string, string>;

package/src/shared/v3/shared-v3-provider-metadata.ts

@@ -0,0 +1,24 @@
+import { JSONObject } from '../../json-value/json-value';
+
+/**
+ * Additional provider-specific metadata.
+ * Metadata are additional outputs from the provider.
+ * They are passed through to the provider from the AI SDK
+ * and enable provider-specific functionality
+ * that can be fully encapsulated in the provider.
+ *
+ * This enables us to quickly ship provider-specific functionality
+ * without affecting the core AI SDK.
+ *
+ * The outer record is keyed by the provider name, and the inner
+ * record is keyed by the provider-specific metadata key.
+ *
+ * ```ts
+ * {
+ *   "anthropic": {
+ *     "cacheControl": { "type": "ephemeral" }
+ *   }
+ * }
+ * ```
+ */
+export type SharedV3ProviderMetadata = Record<string, JSONObject>;

package/src/shared/v3/shared-v3-provider-options.ts

@@ -0,0 +1,24 @@
+import { JSONObject } from '../../json-value/json-value';
+
+/**
+ * Additional provider-specific options.
+ * Options are additional input to the provider.
+ * They are passed through to the provider from the AI SDK
+ * and enable provider-specific functionality
+ * that can be fully encapsulated in the provider.
+ *
+ * This enables us to quickly ship provider-specific functionality
+ * without affecting the core AI SDK.
+ *
+ * The outer record is keyed by the provider name, and the inner
+ * record is keyed by the provider-specific metadata key.
+ *
+ * ```ts
+ * {
+ *   "anthropic": {
+ *     "cacheControl": { "type": "ephemeral" }
+ *   }
+ * }
+ * ```
+ */
+export type SharedV3ProviderOptions = Record<string, JSONObject>;

package/src/shared/v3/shared-v3-warning.ts

@@ -0,0 +1,50 @@
+/**
+ * Warning from the model.
+ *
+ * For example, that certain features are unsupported or compatibility
+ * functionality is used (which might lead to suboptimal results).
+ */
+export type SharedV3Warning =
+  | {
+      /**
+       * A feature is not supported by the model.
+       */
+      type: 'unsupported';
+
+      /**
+       * The feature that is not supported.
+       */
+      feature: string;
+
+      /**
+       * Additional details about the warning.
+       */
+      details?: string;
+    }
+  | {
+      /**
+       * A compatibility feature is used that might lead to suboptimal results.
+       */
+      type: 'compatibility';
+
+      /**
+       * The feature that is used in a compatibility mode.
+       */
+      feature: string;
+
+      /**
+       * Additional details about the warning.
+       */
+      details?: string;
+    }
+  | {
+      /**
+       * Other warning.
+       */
+      type: 'other';
+
+      /**
+       * The message of the warning.
+       */
+      message: string;
+    };

package/src/speech-model/index.ts

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

package/src/speech-model/v2/index.ts

@@ -0,0 +1,3 @@
+export type { SpeechModelV2 } from './speech-model-v2';
+export type { SpeechModelV2CallOptions } from './speech-model-v2-call-options';
+export type { SpeechModelV2CallWarning } from './speech-model-v2-call-warning';

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

@@ -0,0 +1,62 @@
+import { JSONValue } from '../../json-value/json-value';
+
+type SpeechModelV2ProviderOptions = Record<string, Record<string, JSONValue>>;
+
+export type SpeechModelV2CallOptions = {
+  /**
+   * Text to convert to speech.
+   */
+  text: string;
+
+  /**
+   * The voice to use for speech synthesis.
+   * This is provider-specific and may be a voice ID, name, or other identifier.
+   */
+  voice?: string;
+
+  /**
+   * The desired output format for the audio e.g. "mp3", "wav", etc.
+   */
+  outputFormat?: string;
+
+  /**
+   * Instructions for the speech generation e.g. "Speak in a slow and steady tone".
+   */
+  instructions?: string;
+
+  /**
+   * The speed of the speech generation.
+   */
+  speed?: number;
+
+  /**
+   * The language for speech generation. This should be an ISO 639-1 language code (e.g. "en", "es", "fr")
+   * or "auto" for automatic language detection. Provider support varies.
+   */
+  language?: string;
+
+  /**
+   * 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": {}
+   * }
+   * ```
+   */
+  providerOptions?: SpeechModelV2ProviderOptions;
+
+  /**
+   * 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/speech-model/v2/speech-model-v2-call-warning.ts

@@ -0,0 +1,16 @@
+import { SpeechModelV2CallOptions } from './speech-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 SpeechModelV2CallWarning =
+  | {
+      type: 'unsupported-setting';
+      setting: keyof SpeechModelV2CallOptions;
+      details?: string;
+    }
+  | {
+      type: 'other';
+      message: string;
+    };

package/src/speech-model/v2/speech-model-v2.ts

@@ -0,0 +1,89 @@
+import { JSONValue } from '../../json-value';
+import { SharedV2Headers } from '../../shared';
+import { SpeechModelV2CallOptions } from './speech-model-v2-call-options';
+import { SpeechModelV2CallWarning } from './speech-model-v2-call-warning';
+
+/**
+ * Speech model specification version 2.
+ */
+export type SpeechModelV2 = {
+  /**
+   * The speech model must specify which speech model interface
+   * version it implements. This will allow us to evolve the speech
+   * model interface and retain backwards compatibility. The different
+   * implementation versions can be handled as a discriminated union
+   * on our side.
+   */
+  readonly specificationVersion: 'v2';
+
+  /**
+   * Name of the provider for logging purposes.
+   */
+  readonly provider: string;
+
+  /**
+   * Provider-specific model ID for logging purposes.
+   */
+  readonly modelId: string;
+
+  /**
+   * Generates speech audio from text.
+   */
+  doGenerate(options: SpeechModelV2CallOptions): PromiseLike<{
+    /**
+     * Generated audio as an ArrayBuffer.
+     * The audio should be returned without any unnecessary conversion.
+     * If the API returns base64 encoded strings, the audio should be returned
+     * as base64 encoded strings. If the API returns binary data, the audio
+     * should be returned as binary data.
+     */
+    audio: string | Uint8Array;
+
+    /**
+     * Warnings for the call, e.g. unsupported settings.
+     */
+    warnings: Array<SpeechModelV2CallWarning>;
+
+    /**
+     * Optional request information for telemetry and debugging purposes.
+     */
+    request?: {
+      /**
+       * Response body (available only for providers that use HTTP requests).
+       */
+      body?: unknown;
+    };
+
+    /**
+     * Response information for telemetry and debugging purposes.
+     */
+    response: {
+      /**
+       * Timestamp for the start of the generated response.
+       */
+      timestamp: Date;
+
+      /**
+       * The ID of the response model that was used to generate the response.
+       */
+      modelId: string;
+
+      /**
+       * Response headers.
+       */
+      headers?: SharedV2Headers;
+
+      /**
+       * Response body.
+       */
+      body?: unknown;
+    };
+
+    /**
+     * Additional provider-specific metadata. They are passed through
+     * from the provider to the AI SDK and enable provider-specific
+     * results that can be fully encapsulated in the provider.
+     */
+    providerMetadata?: Record<string, Record<string, JSONValue>>;
+  }>;
+};

package/src/speech-model/v3/index.ts

@@ -0,0 +1,2 @@
+export type { SpeechModelV3 } from './speech-model-v3';
+export type { SpeechModelV3CallOptions } from './speech-model-v3-call-options';

package/src/speech-model/v3/speech-model-v3-call-options.ts

@@ -0,0 +1,62 @@
+import { JSONObject } from '../../json-value/json-value';
+
+type SpeechModelV3ProviderOptions = Record<string, JSONObject>;
+
+export type SpeechModelV3CallOptions = {
+  /**
+   * Text to convert to speech.
+   */
+  text: string;
+
+  /**
+   * The voice to use for speech synthesis.
+   * This is provider-specific and may be a voice ID, name, or other identifier.
+   */
+  voice?: string;
+
+  /**
+   * The desired output format for the audio e.g. "mp3", "wav", etc.
+   */
+  outputFormat?: string;
+
+  /**
+   * Instructions for the speech generation e.g. "Speak in a slow and steady tone".
+   */
+  instructions?: string;
+
+  /**
+   * The speed of the speech generation.
+   */
+  speed?: number;
+
+  /**
+   * The language for speech generation. This should be an ISO 639-1 language code (e.g. "en", "es", "fr")
+   * or "auto" for automatic language detection. Provider support varies.
+   */
+  language?: string;
+
+  /**
+   * 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": {}
+   * }
+   * ```
+   */
+  providerOptions?: SpeechModelV3ProviderOptions;
+
+  /**
+   * 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>;
+};