@ai-sdk/provider 3.0.2 → 3.0.3

package/src/language-model/v3/language-model-v3-tool-approval-request.ts

@@ -0,0 +1,27 @@
+import { SharedV3ProviderMetadata } from '../../shared/v3/shared-v3-provider-metadata';
+
+/**
+ * Tool approval request emitted by a provider for a provider-executed tool call.
+ *
+ * This is used for flows where the provider executes the tool (e.g. MCP tools)
+ * but requires an explicit user approval before continuing.
+ */
+export type LanguageModelV3ToolApprovalRequest = {
+  type: 'tool-approval-request';
+
+  /**
+   * ID of the approval request. This ID is referenced by the subsequent
+   * tool-approval-response (tool message) to approve or deny execution.
+   */
+  approvalId: string;
+
+  /**
+   * The tool call ID that this approval request is for.
+   */
+  toolCallId: string;
+
+  /**
+   * Additional provider-specific metadata for the approval request.
+   */
+  providerMetadata?: SharedV3ProviderMetadata;
+};

package/src/language-model/v3/language-model-v3-tool-call.ts

@@ -0,0 +1,41 @@
+import { SharedV3ProviderMetadata } from '../../shared/v3/shared-v3-provider-metadata';
+
+/**
+ * Tool calls that the model has generated.
+ */
+export type LanguageModelV3ToolCall = {
+  type: 'tool-call';
+
+  /**
+   * The identifier of the tool call. It must be unique across all tool calls.
+   */
+  toolCallId: string;
+
+  /**
+   * The name of the tool that should be called.
+   */
+  toolName: string;
+
+  /**
+   * Stringified JSON object with the tool call arguments. Must match the
+   * parameters schema of the tool.
+   */
+  input: string;
+
+  /**
+   * Whether the tool call will be executed by the provider.
+   * If this flag is not set or is false, the tool call will be executed by the client.
+   */
+  providerExecuted?: boolean;
+
+  /**
+   * Whether the tool is dynamic, i.e. defined at runtime.
+   * For example, MCP (Model Context Protocol) tools that are executed by the provider.
+   */
+  dynamic?: boolean;
+
+  /**
+   * Additional provider-specific metadata for the tool call.
+   */
+  providerMetadata?: SharedV3ProviderMetadata;
+};

package/src/language-model/v3/language-model-v3-tool-choice.ts

@@ -0,0 +1,5 @@
+export type LanguageModelV3ToolChoice =
+  | { type: 'auto' } // the tool selection is automatic (can be no tool)
+  | { type: 'none' } // no tool must be selected
+  | { type: 'required' } // one of the available tools must be selected
+  | { type: 'tool'; toolName: string }; // a specific tool must be selected:

package/src/language-model/v3/language-model-v3-tool-result.ts

@@ -0,0 +1,51 @@
+import { JSONValue } from '../../json-value';
+import { SharedV3ProviderMetadata } from '../../shared/v3/shared-v3-provider-metadata';
+
+/**
+Result of a tool call that has been executed by the provider.
+ */
+export type LanguageModelV3ToolResult = {
+  type: 'tool-result';
+
+  /**
+   * The ID of the tool call that this result is associated with.
+   */
+  toolCallId: string;
+
+  /**
+   * Name of the tool that generated this result.
+   */
+  toolName: string;
+
+  /**
+   * Result of the tool call. This is a JSON-serializable object.
+   */
+  result: NonNullable<JSONValue>;
+
+  /**
+   * Optional flag if the result is an error or an error message.
+   */
+  isError?: boolean;
+
+  /**
+   * Whether the tool result is preliminary.
+   *
+   * Preliminary tool results replace each other, e.g. image previews.
+   * There always has to be a final, non-preliminary tool result.
+   *
+   * If this flag is set to true, the tool result is preliminary.
+   * If this flag is not set or is false, the tool result is not preliminary.
+   */
+  preliminary?: boolean;
+
+  /**
+   * Whether the tool is dynamic, i.e. defined at runtime.
+   * For example, MCP (Model Context Protocol) tools that are executed by the provider.
+   */
+  dynamic?: boolean;
+
+  /**
+   * Additional provider-specific metadata for the tool result.
+   */
+  providerMetadata?: SharedV3ProviderMetadata;
+};

package/src/language-model/v3/language-model-v3-usage.ts

@@ -0,0 +1,59 @@
+import { JSONObject } from '../../json-value';
+
+/**
+ * Usage information for a language model call.
+ */
+export type LanguageModelV3Usage = {
+  /**
+   * Information about the input tokens.
+   */
+  inputTokens: {
+    /**
+     *The total number of input (prompt) tokens used.
+     */
+    total: number | undefined;
+
+    /**
+     * The number of non-cached input (prompt) tokens used.
+     */
+    noCache: number | undefined;
+
+    /**
+     * The number of cached input (prompt) tokens read.
+     */
+    cacheRead: number | undefined;
+
+    /**
+     * The number of cached input (prompt) tokens written.
+     */
+    cacheWrite: number | undefined;
+  };
+
+  /**
+   * Information about the output tokens.
+   */
+  outputTokens: {
+    /**
+     * The total number of output (completion) tokens used.
+     */
+    total: number | undefined;
+
+    /**
+     * The number of text tokens used.
+     */
+    text: number | undefined;
+
+    /**
+     * The number of reasoning tokens used.
+     */
+    reasoning: number | undefined;
+  };
+
+  /**
+   * Raw usage information from the provider.
+   *
+   * This is the usage information in the shape that the provider returns.
+   * It can include additional information that is not part of the standard usage information.
+   */
+  raw?: JSONObject;
+};

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

@@ -0,0 +1,61 @@
+import { LanguageModelV3CallOptions } from './language-model-v3-call-options';
+import { LanguageModelV3GenerateResult } from './language-model-v3-generate-result';
+import { LanguageModelV3StreamResult } from './language-model-v3-stream-result';
+
+/**
+ * Specification for a language model that implements the language model interface version 3.
+ */
+export type LanguageModelV3 = {
+  /**
+   * The language model must specify which language model interface version it implements.
+   */
+  readonly specificationVersion: 'v3';
+
+  /**
+   * Provider ID.
+   */
+  readonly provider: string;
+
+  /**
+   * Provider-specific model ID.
+   */
+  readonly modelId: string;
+
+  /**
+   * Supported URL patterns by media type for the provider.
+   *
+   * The keys are media type patterns or full media types (e.g. `*\/*` for everything, `audio/*`, `video/*`, or `application/pdf`).
+   * and the values are arrays of regular expressions that match the URL paths.
+   *
+   * The matching should be against lower-case URLs.
+   *
+   * Matched URLs are supported natively by the model and are not downloaded.
+   *
+   * @returns A map of supported URL patterns by media type (as a promise or a plain object).
+   */
+  supportedUrls:
+    | PromiseLike<Record<string, RegExp[]>>
+    | Record<string, RegExp[]>;
+
+  /**
+   * Generates a language model output (non-streaming).
+
+   * Naming: "do" prefix to prevent accidental direct usage of the method
+   * by the user.
+   */
+  doGenerate(
+    options: LanguageModelV3CallOptions,
+  ): PromiseLike<LanguageModelV3GenerateResult>;
+
+  /**
+   * Generates a language model output (streaming).
+   *
+   * Naming: "do" prefix to prevent accidental direct usage of the method
+   * by the user.
+   *
+   * @return A stream of higher-level language model output parts.
+   */
+  doStream(
+    options: LanguageModelV3CallOptions,
+  ): PromiseLike<LanguageModelV3StreamResult>;
+};

package/src/language-model-middleware/index.ts

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

package/src/language-model-middleware/v2/index.ts

@@ -0,0 +1 @@
+export * from './language-model-v2-middleware';

package/src/language-model-middleware/v2/language-model-v2-middleware.ts

@@ -0,0 +1,82 @@
+import { LanguageModelV2 } from '../../language-model/v2/language-model-v2';
+import { LanguageModelV2CallOptions } from '../../language-model/v2/language-model-v2-call-options';
+
+/**
+ * Experimental middleware for LanguageModelV2.
+ * This type defines the structure for middleware that can be used to modify
+ * the behavior of LanguageModelV2 operations.
+ */
+export type LanguageModelV2Middleware = {
+  /**
+   * Middleware specification version. Use `v2` for the current version.
+   */
+  middlewareVersion?: 'v2' | undefined; // backwards compatibility
+
+  /**
+   * Override the provider name if desired.
+   * @param options.model - The language model instance.
+   */
+  overrideProvider?: (options: { model: LanguageModelV2 }) => string;
+
+  /**
+   * Override the model ID if desired.
+   * @param options.model - The language model instance.
+   */
+  overrideModelId?: (options: { model: LanguageModelV2 }) => string;
+
+  /**
+   * Override the supported URLs if desired.
+   * @param options.model - The language model instance.
+   */
+  overrideSupportedUrls?: (options: {
+    model: LanguageModelV2;
+  }) => PromiseLike<Record<string, RegExp[]>> | Record<string, RegExp[]>;
+
+  /**
+   * Transforms the parameters before they are passed to the language model.
+   * @param options - Object containing the type of operation and the parameters.
+   * @param options.type - The type of operation ('generate' or 'stream').
+   * @param options.params - The original parameters for the language model call.
+   * @returns A promise that resolves to the transformed parameters.
+   */
+  transformParams?: (options: {
+    type: 'generate' | 'stream';
+    params: LanguageModelV2CallOptions;
+    model: LanguageModelV2;
+  }) => PromiseLike<LanguageModelV2CallOptions>;
+
+  /**
+   * Wraps the generate operation of the language model.
+   * @param options - Object containing the generate function, parameters, and model.
+   * @param options.doGenerate - The original generate function.
+   * @param options.doStream - The original stream function.
+   * @param options.params - The parameters for the generate call. If the
+   * `transformParams` middleware is used, this will be the transformed parameters.
+   * @param options.model - The language model instance.
+   * @returns A promise that resolves to the result of the generate operation.
+   */
+  wrapGenerate?: (options: {
+    doGenerate: () => ReturnType<LanguageModelV2['doGenerate']>;
+    doStream: () => ReturnType<LanguageModelV2['doStream']>;
+    params: LanguageModelV2CallOptions;
+    model: LanguageModelV2;
+  }) => Promise<Awaited<ReturnType<LanguageModelV2['doGenerate']>>>;
+
+  /**
+   * Wraps the stream operation of the language model.
+   *
+   * @param options - Object containing the stream function, parameters, and model.
+   * @param options.doGenerate - The original generate function.
+   * @param options.doStream - The original stream function.
+   * @param options.params - The parameters for the stream call. If the
+   * `transformParams` middleware is used, this will be the transformed parameters.
+   * @param options.model - The language model instance.
+   * @returns A promise that resolves to the result of the stream operation.
+   */
+  wrapStream?: (options: {
+    doGenerate: () => ReturnType<LanguageModelV2['doGenerate']>;
+    doStream: () => ReturnType<LanguageModelV2['doStream']>;
+    params: LanguageModelV2CallOptions;
+    model: LanguageModelV2;
+  }) => PromiseLike<Awaited<ReturnType<LanguageModelV2['doStream']>>>;
+};

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

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

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

@@ -0,0 +1,84 @@
+import { LanguageModelV3 } from '../../language-model/v3/language-model-v3';
+import { LanguageModelV3CallOptions } from '../../language-model/v3/language-model-v3-call-options';
+import { LanguageModelV3GenerateResult } from '../../language-model/v3/language-model-v3-generate-result';
+import { LanguageModelV3StreamResult } from '../../language-model/v3/language-model-v3-stream-result';
+
+/**
+ * Experimental middleware for LanguageModelV3.
+ * This type defines the structure for middleware that can be used to modify
+ * the behavior of LanguageModelV3 operations.
+ */
+export type LanguageModelV3Middleware = {
+  /**
+   * Middleware specification version. Use `v3` for the current version.
+   */
+  readonly specificationVersion: 'v3';
+
+  /**
+   * Override the provider name if desired.
+   * @param options.model - The language model instance.
+   */
+  overrideProvider?: (options: { model: LanguageModelV3 }) => string;
+
+  /**
+   * Override the model ID if desired.
+   * @param options.model - The language model instance.
+   */
+  overrideModelId?: (options: { model: LanguageModelV3 }) => string;
+
+  /**
+   * Override the supported URLs if desired.
+   * @param options.model - The language model instance.
+   */
+  overrideSupportedUrls?: (options: {
+    model: LanguageModelV3;
+  }) => PromiseLike<Record<string, RegExp[]>> | Record<string, RegExp[]>;
+
+  /**
+   * Transforms the parameters before they are passed to the language model.
+   * @param options - Object containing the type of operation and the parameters.
+   * @param options.type - The type of operation ('generate' or 'stream').
+   * @param options.params - The original parameters for the language model call.
+   * @returns A promise that resolves to the transformed parameters.
+   */
+  transformParams?: (options: {
+    type: 'generate' | 'stream';
+    params: LanguageModelV3CallOptions;
+    model: LanguageModelV3;
+  }) => PromiseLike<LanguageModelV3CallOptions>;
+
+  /**
+   * Wraps the generate operation of the language model.
+   * @param options - Object containing the generate function, parameters, and model.
+   * @param options.doGenerate - The original generate function.
+   * @param options.doStream - The original stream function.
+   * @param options.params - The parameters for the generate call. If the
+   * `transformParams` middleware is used, this will be the transformed parameters.
+   * @param options.model - The language model instance.
+   * @returns A promise that resolves to the result of the generate operation.
+   */
+  wrapGenerate?: (options: {
+    doGenerate: () => PromiseLike<LanguageModelV3GenerateResult>;
+    doStream: () => PromiseLike<LanguageModelV3StreamResult>;
+    params: LanguageModelV3CallOptions;
+    model: LanguageModelV3;
+  }) => PromiseLike<LanguageModelV3GenerateResult>;
+
+  /**
+   * Wraps the stream operation of the language model.
+   *
+   * @param options - Object containing the stream function, parameters, and model.
+   * @param options.doGenerate - The original generate function.
+   * @param options.doStream - The original stream function.
+   * @param options.params - The parameters for the stream call. If the
+   * `transformParams` middleware is used, this will be the transformed parameters.
+   * @param options.model - The language model instance.
+   * @returns A promise that resolves to the result of the stream operation.
+   */
+  wrapStream?: (options: {
+    doGenerate: () => PromiseLike<LanguageModelV3GenerateResult>;
+    doStream: () => PromiseLike<LanguageModelV3StreamResult>;
+    params: LanguageModelV3CallOptions;
+    model: LanguageModelV3;
+  }) => PromiseLike<LanguageModelV3StreamResult>;
+};

package/src/provider/index.ts

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

package/src/provider/v2/index.ts

@@ -0,0 +1 @@
+export type { ProviderV2 } from './provider-v2';

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

@@ -0,0 +1,64 @@
+import { EmbeddingModelV2 } from '../../embedding-model/v2/embedding-model-v2';
+import { ImageModelV2 } from '../../image-model/v2/image-model-v2';
+import { LanguageModelV2 } from '../../language-model/v2/language-model-v2';
+import { SpeechModelV2 } from '../../speech-model/v2/speech-model-v2';
+import { TranscriptionModelV2 } from '../../transcription-model/v2/transcription-model-v2';
+
+/**
+ * Provider for language, text embedding, and image generation models.
+ */
+export interface ProviderV2 {
+  /**
+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): LanguageModelV2;
+
+  /**
+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.
+   */
+  textEmbeddingModel(modelId: string): EmbeddingModelV2<string>;
+
+  /**
+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): ImageModelV2;
+
+  /**
+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): TranscriptionModelV2;
+
+  /**
+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): SpeechModelV2;
+}

package/src/provider/v3/index.ts

@@ -0,0 +1 @@
+export type { ProviderV3 } from './provider-v3';

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;
+};