@ai-sdk/provider 3.0.2 → 3.0.4

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

@@ -0,0 +1,422 @@
+import { JSONValue } from '../../json-value/json-value';
+import { SharedV3ProviderOptions } from '../../shared/v3/shared-v3-provider-options';
+import { LanguageModelV3DataContent } from './language-model-v3-data-content';
+
+/**
+A prompt is a list of messages.
+
+Note: Not all models and prompt formats support multi-modal inputs and
+tool calls. The validation happens at runtime.
+
+Note: This is not a user-facing prompt. The AI SDK methods will map the
+user-facing prompt types such as chat or instruction prompts to this format.
+ */
+export type LanguageModelV3Prompt = Array<LanguageModelV3Message>;
+
+export type LanguageModelV3Message =
+  // Note: there could be additional parts for each role in the future,
+  // e.g. when the assistant can return images or the user can share files
+  // such as PDFs.
+  (
+    | {
+        role: 'system';
+        content: string;
+      }
+    | {
+        role: 'user';
+        content: Array<LanguageModelV3TextPart | LanguageModelV3FilePart>;
+      }
+    | {
+        role: 'assistant';
+        content: Array<
+          | LanguageModelV3TextPart
+          | LanguageModelV3FilePart
+          | LanguageModelV3ReasoningPart
+          | LanguageModelV3ToolCallPart
+          | LanguageModelV3ToolResultPart
+        >;
+      }
+    | {
+        role: 'tool';
+        content: Array<
+          | LanguageModelV3ToolResultPart
+          | LanguageModelV3ToolApprovalResponsePart
+        >;
+      }
+  ) & {
+    /**
+     * 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;
+  };
+
+/**
+Text content part of a prompt. It contains a string of text.
+ */
+export interface LanguageModelV3TextPart {
+  type: 'text';
+
+  /**
+The text content.
+   */
+  text: string;
+
+  /**
+   * 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;
+}
+
+/**
+Reasoning content part of a prompt. It contains a string of reasoning text.
+ */
+export interface LanguageModelV3ReasoningPart {
+  type: 'reasoning';
+
+  /**
+The reasoning text.
+   */
+  text: string;
+
+  /**
+   * 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;
+}
+
+/**
+File content part of a prompt. It contains a file.
+ */
+export interface LanguageModelV3FilePart {
+  type: 'file';
+
+  /**
+   * Optional filename of the file.
+   */
+  filename?: string;
+
+  /**
+File data. Can be a Uint8Array, base64 encoded data as a string or a URL.
+*/
+  data: LanguageModelV3DataContent;
+
+  /**
+IANA media type of the file.
+
+Can support wildcards, e.g. `image/*` (in which case the provider needs to take appropriate action).
+
+@see https://www.iana.org/assignments/media-types/media-types.xhtml
+   */
+  mediaType: string;
+
+  /**
+   * 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;
+}
+
+/**
+Tool call content part of a prompt. It contains a tool call (usually generated by the AI model).
+ */
+export interface LanguageModelV3ToolCallPart {
+  type: 'tool-call';
+
+  /**
+ID of the tool call. This ID is used to match the tool call with the tool result.
+ */
+  toolCallId: string;
+
+  /**
+Name of the tool that is being called.
+ */
+  toolName: string;
+
+  /**
+Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.
+   */
+  input: unknown;
+
+  /**
+   * 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;
+
+  /**
+   * 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;
+}
+
+/**
+Tool result content part of a prompt. It contains the result of the tool call with the matching ID.
+ */
+export interface LanguageModelV3ToolResultPart {
+  type: 'tool-result';
+
+  /**
+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.
+   */
+  output: LanguageModelV3ToolResultOutput;
+
+  /**
+   * 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;
+}
+
+/**
+ * Tool approval response content part of a prompt. It contains the user's
+ * decision to approve or deny a provider-executed tool call.
+ */
+export interface LanguageModelV3ToolApprovalResponsePart {
+  type: 'tool-approval-response';
+
+  /**
+   * ID of the approval request that this response refers to.
+   */
+  approvalId: string;
+
+  /**
+   * Whether the approval was granted (true) or denied (false).
+   */
+  approved: boolean;
+
+  /**
+   * Optional reason for approval or denial.
+   */
+  reason?: string;
+
+  /**
+   * 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;
+}
+
+/**
+ * Result of a tool call.
+ */
+export type LanguageModelV3ToolResultOutput =
+  | {
+      /**
+       * Text tool output that should be directly sent to the API.
+       */
+      type: 'text';
+      value: string;
+
+      /**
+       * Provider-specific options.
+       */
+      providerOptions?: SharedV3ProviderOptions;
+    }
+  | {
+      type: 'json';
+      value: JSONValue;
+
+      /**
+       * Provider-specific options.
+       */
+      providerOptions?: SharedV3ProviderOptions;
+    }
+  | {
+      /**
+       * Type when the user has denied the execution of the tool call.
+       */
+      type: 'execution-denied';
+
+      /**
+       * Optional reason for the execution denial.
+       */
+      reason?: string;
+
+      /**
+       * Provider-specific options.
+       */
+      providerOptions?: SharedV3ProviderOptions;
+    }
+  | {
+      type: 'error-text';
+      value: string;
+
+      /**
+       * Provider-specific options.
+       */
+      providerOptions?: SharedV3ProviderOptions;
+    }
+  | {
+      type: 'error-json';
+      value: JSONValue;
+
+      /**
+       * Provider-specific options.
+       */
+      providerOptions?: SharedV3ProviderOptions;
+    }
+  | {
+      type: 'content';
+      value: Array<
+        | {
+            type: 'text';
+
+            /**
+Text content.
+*/
+            text: string;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: SharedV3ProviderOptions;
+          }
+        | {
+            type: 'file-data';
+
+            /**
+Base-64 encoded media data.
+*/
+            data: string;
+
+            /**
+IANA media type.
+@see https://www.iana.org/assignments/media-types/media-types.xhtml
+*/
+            mediaType: string;
+
+            /**
+             * Optional filename of the file.
+             */
+            filename?: string;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: SharedV3ProviderOptions;
+          }
+        | {
+            type: 'file-url';
+
+            /**
+             * URL of the file.
+             */
+            url: string;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: SharedV3ProviderOptions;
+          }
+        | {
+            type: 'file-id';
+
+            /**
+             * ID of the file.
+             *
+             * If you use multiple providers, you need to
+             * specify the provider specific ids using
+             * the Record option. The key is the provider
+             * name, e.g. 'openai' or 'anthropic'.
+             */
+            fileId: string | Record<string, string>;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: SharedV3ProviderOptions;
+          }
+        | {
+            /**
+             * Images that are referenced using base64 encoded data.
+             */
+            type: 'image-data';
+
+            /**
+Base-64 encoded image data.
+*/
+            data: string;
+
+            /**
+IANA media type.
+@see https://www.iana.org/assignments/media-types/media-types.xhtml
+*/
+            mediaType: string;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: SharedV3ProviderOptions;
+          }
+        | {
+            /**
+             * Images that are referenced using a URL.
+             */
+            type: 'image-url';
+
+            /**
+             * URL of the image.
+             */
+            url: string;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: SharedV3ProviderOptions;
+          }
+        | {
+            /**
+             * Images that are referenced using a provider file id.
+             */
+            type: 'image-file-id';
+
+            /**
+             * Image that is referenced using a provider file id.
+             *
+             * If you use multiple providers, you need to
+             * specify the provider specific ids using
+             * the Record option. The key is the provider
+             * name, e.g. 'openai' or 'anthropic'.
+             */
+            fileId: string | Record<string, string>;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: SharedV3ProviderOptions;
+          }
+        | {
+            /**
+             * Custom content part. This can be used to implement
+             * provider-specific content parts.
+             */
+            type: 'custom';
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: SharedV3ProviderOptions;
+          }
+      >;
+    };

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

@@ -0,0 +1,28 @@
+/**
+ * The configuration of a provider tool.
+ *
+ * Provider tools are tools that are specific to a certain provider.
+ * The input and output schemas are defined be the provider, and
+ * some of the tools are also executed on the provider systems.
+ */
+export type LanguageModelV3ProviderTool = {
+  /**
+   * The type of the tool (always 'provider').
+   */
+  type: 'provider';
+
+  /**
+   * The ID of the tool. Should follow the format `<provider-id>.<unique-tool-name>`.
+   */
+  id: `${string}.${string}`;
+
+  /**
+   * The name of the tool. Unique within this model call.
+   */
+  name: string;
+
+  /**
+   * The arguments for configuring the tool. Must match the expected arguments defined by the provider for this tool.
+   */
+  args: Record<string, unknown>;
+};

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

@@ -0,0 +1,14 @@
+import { SharedV3ProviderMetadata } from '../../shared';
+
+/**
+Reasoning that the model has generated.
+ */
+export type LanguageModelV3Reasoning = {
+  type: 'reasoning';
+  text: string;
+
+  /**
+   * Optional provider-specific metadata for the reasoning part.
+   */
+  providerMetadata?: SharedV3ProviderMetadata;
+};

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

@@ -0,0 +1,16 @@
+export interface LanguageModelV3ResponseMetadata {
+  /**
+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;
+}

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

@@ -0,0 +1,67 @@
+import { SharedV3ProviderMetadata } from '../../shared/v3/shared-v3-provider-metadata';
+
+/**
+A source that has been used as input to generate the response.
+ */
+export type LanguageModelV3Source =
+  | {
+      type: 'source';
+
+      /**
+       * The type of source - URL sources reference web content.
+       */
+      sourceType: 'url';
+
+      /**
+       * The ID of the source.
+       */
+      id: string;
+
+      /**
+       * The URL of the source.
+       */
+      url: string;
+
+      /**
+       * The title of the source.
+       */
+      title?: string;
+
+      /**
+       * Additional provider metadata for the source.
+       */
+      providerMetadata?: SharedV3ProviderMetadata;
+    }
+  | {
+      type: 'source';
+
+      /**
+       * The type of source - document sources reference files/documents.
+       */
+      sourceType: 'document';
+
+      /**
+       * The ID of the source.
+       */
+      id: string;
+
+      /**
+       * IANA media type of the document (e.g., 'application/pdf').
+       */
+      mediaType: string;
+
+      /**
+       * The title of the document.
+       */
+      title: string;
+
+      /**
+       * Optional filename of the document.
+       */
+      filename?: string;
+
+      /**
+       * Additional provider metadata for the source.
+       */
+      providerMetadata?: SharedV3ProviderMetadata;
+    };

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

@@ -0,0 +1,106 @@
+import { SharedV3ProviderMetadata } from '../../shared/v3/shared-v3-provider-metadata';
+import { SharedV3Warning } from '../../shared/v3/shared-v3-warning';
+import { LanguageModelV3File } from './language-model-v3-file';
+import { LanguageModelV3FinishReason } from './language-model-v3-finish-reason';
+import { LanguageModelV3ResponseMetadata } from './language-model-v3-response-metadata';
+import { LanguageModelV3Source } from './language-model-v3-source';
+import { LanguageModelV3ToolApprovalRequest } from './language-model-v3-tool-approval-request';
+import { LanguageModelV3ToolCall } from './language-model-v3-tool-call';
+import { LanguageModelV3ToolResult } from './language-model-v3-tool-result';
+import { LanguageModelV3Usage } from './language-model-v3-usage';
+
+export type LanguageModelV3StreamPart =
+  // Text blocks:
+  | {
+      type: 'text-start';
+      providerMetadata?: SharedV3ProviderMetadata;
+      id: string;
+    }
+  | {
+      type: 'text-delta';
+      id: string;
+      providerMetadata?: SharedV3ProviderMetadata;
+      delta: string;
+    }
+  | {
+      type: 'text-end';
+      providerMetadata?: SharedV3ProviderMetadata;
+      id: string;
+    }
+
+  // Reasoning blocks:
+  | {
+      type: 'reasoning-start';
+      providerMetadata?: SharedV3ProviderMetadata;
+      id: string;
+    }
+  | {
+      type: 'reasoning-delta';
+      id: string;
+      providerMetadata?: SharedV3ProviderMetadata;
+      delta: string;
+    }
+  | {
+      type: 'reasoning-end';
+      id: string;
+      providerMetadata?: SharedV3ProviderMetadata;
+    }
+
+  // Tool calls and results:
+  | {
+      type: 'tool-input-start';
+      id: string;
+      toolName: string;
+      providerMetadata?: SharedV3ProviderMetadata;
+      providerExecuted?: boolean;
+      dynamic?: boolean;
+      title?: string;
+    }
+  | {
+      type: 'tool-input-delta';
+      id: string;
+      delta: string;
+      providerMetadata?: SharedV3ProviderMetadata;
+    }
+  | {
+      type: 'tool-input-end';
+      id: string;
+      providerMetadata?: SharedV3ProviderMetadata;
+    }
+  | LanguageModelV3ToolApprovalRequest
+  | LanguageModelV3ToolCall
+  | LanguageModelV3ToolResult
+
+  // Files and sources:
+  | LanguageModelV3File
+  | LanguageModelV3Source
+
+  // stream start event with warnings for the call, e.g. unsupported settings:
+  | {
+      type: 'stream-start';
+      warnings: Array<SharedV3Warning>;
+    }
+
+  // metadata for the response.
+  // separate stream part so it can be sent once it is available.
+  | ({ type: 'response-metadata' } & LanguageModelV3ResponseMetadata)
+
+  // metadata that is available after the stream is finished:
+  | {
+      type: 'finish';
+      usage: LanguageModelV3Usage;
+      finishReason: LanguageModelV3FinishReason;
+      providerMetadata?: SharedV3ProviderMetadata;
+    }
+
+  // raw chunks if enabled
+  | {
+      type: 'raw';
+      rawValue: unknown;
+    }
+
+  // error parts are streamed, allowing for multiple errors
+  | {
+      type: 'error';
+      error: unknown;
+    };

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

@@ -0,0 +1,32 @@
+import { SharedV3Headers } from '../../shared';
+import { LanguageModelV3StreamPart } from './language-model-v3-stream-part';
+
+/**
+ * The result of a language model doStream call.
+ */
+export type LanguageModelV3StreamResult = {
+  /**
+   * The stream.
+   */
+  stream: ReadableStream<LanguageModelV3StreamPart>;
+
+  /**
+   * Optional request information for telemetry and debugging purposes.
+   */
+  request?: {
+    /**
+     * Request HTTP body that was sent to the provider API.
+     */
+    body?: unknown;
+  };
+
+  /**
+   * Optional response data.
+   */
+  response?: {
+    /**
+     * Response headers.
+     */
+    headers?: SharedV3Headers;
+  };
+};

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

@@ -0,0 +1,15 @@
+import { SharedV3ProviderMetadata } from '../../shared/v3/shared-v3-provider-metadata';
+
+/**
+Text that the model has generated.
+ */
+export type LanguageModelV3Text = {
+  type: 'text';
+
+  /**
+The text content.
+   */
+  text: string;
+
+  providerMetadata?: SharedV3ProviderMetadata;
+};