@ai-sdk/provider 3.0.2 → 3.0.4

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

@@ -0,0 +1,218 @@
+import { JSONValue } from '../../json-value/json-value';
+import { SharedV2ProviderOptions } from '../../shared/v2/shared-v2-provider-options';
+import { LanguageModelV2DataContent } from './language-model-v2-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 LanguageModelV2Prompt = Array<LanguageModelV2Message>;
+
+export type LanguageModelV2Message =
+  // 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<LanguageModelV2TextPart | LanguageModelV2FilePart>;
+      }
+    | {
+        role: 'assistant';
+        content: Array<
+          | LanguageModelV2TextPart
+          | LanguageModelV2FilePart
+          | LanguageModelV2ReasoningPart
+          | LanguageModelV2ToolCallPart
+          | LanguageModelV2ToolResultPart
+        >;
+      }
+    | {
+        role: 'tool';
+        content: Array<LanguageModelV2ToolResultPart>;
+      }
+  ) & {
+    /**
+     * 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?: SharedV2ProviderOptions;
+  };
+
+/**
+Text content part of a prompt. It contains a string of text.
+ */
+export interface LanguageModelV2TextPart {
+  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?: SharedV2ProviderOptions;
+}
+
+/**
+Reasoning content part of a prompt. It contains a string of reasoning text.
+ */
+export interface LanguageModelV2ReasoningPart {
+  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?: SharedV2ProviderOptions;
+}
+
+/**
+File content part of a prompt. It contains a file.
+ */
+export interface LanguageModelV2FilePart {
+  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: LanguageModelV2DataContent;
+
+  /**
+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?: SharedV2ProviderOptions;
+}
+
+/**
+Tool call content part of a prompt. It contains a tool call (usually generated by the AI model).
+ */
+export interface LanguageModelV2ToolCallPart {
+  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?: SharedV2ProviderOptions;
+}
+
+/**
+Tool result content part of a prompt. It contains the result of the tool call with the matching ID.
+ */
+export interface LanguageModelV2ToolResultPart {
+  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: LanguageModelV2ToolResultOutput;
+
+  /**
+   * 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?: SharedV2ProviderOptions;
+}
+
+export type LanguageModelV2ToolResultOutput =
+  | { type: 'text'; value: string }
+  | { type: 'json'; value: JSONValue }
+  | { type: 'error-text'; value: string }
+  | { type: 'error-json'; value: JSONValue }
+  | {
+      type: 'content';
+      value: Array<
+        | {
+            type: 'text';
+
+            /**
+Text content.
+*/
+            text: string;
+          }
+        | {
+            type: 'media';
+
+            /**
+Base-64 encoded media data.
+*/
+            data: string;
+
+            /**
+IANA media type.
+@see https://www.iana.org/assignments/media-types/media-types.xhtml
+*/
+            mediaType: string;
+          }
+      >;
+    };

package/src/language-model/v2/language-model-v2-provider-defined-tool.ts

@@ -0,0 +1,24 @@
+/**
+The configuration of a tool that is defined by the provider.
+ */
+export type LanguageModelV2ProviderDefinedTool = {
+  /**
+The type of the tool (always 'provider-defined').
+   */
+  type: 'provider-defined';
+
+  /**
+The ID of the tool. Should follow the format `<provider-name>.<unique-tool-name>`.
+   */
+  id: `${string}.${string}`;
+
+  /**
+The name of the tool that the user must use in the tool set.
+   */
+  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/v2/language-model-v2-reasoning.ts

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

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

@@ -0,0 +1,16 @@
+export interface LanguageModelV2ResponseMetadata {
+  /**
+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/v2/language-model-v2-source.ts

@@ -0,0 +1,67 @@
+import { SharedV2ProviderMetadata } from '../../shared/v2/shared-v2-provider-metadata';
+
+/**
+A source that has been used as input to generate the response.
+ */
+export type LanguageModelV2Source =
+  | {
+      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?: SharedV2ProviderMetadata;
+    }
+  | {
+      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?: SharedV2ProviderMetadata;
+    };

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

@@ -0,0 +1,102 @@
+import { SharedV2ProviderMetadata } from '../../shared/v2/shared-v2-provider-metadata';
+import { LanguageModelV2CallWarning } from './language-model-v2-call-warning';
+import { LanguageModelV2File } from './language-model-v2-file';
+import { LanguageModelV2FinishReason } from './language-model-v2-finish-reason';
+import { LanguageModelV2ResponseMetadata } from './language-model-v2-response-metadata';
+import { LanguageModelV2Source } from './language-model-v2-source';
+import { LanguageModelV2ToolCall } from './language-model-v2-tool-call';
+import { LanguageModelV2ToolResult } from './language-model-v2-tool-result';
+import { LanguageModelV2Usage } from './language-model-v2-usage';
+
+export type LanguageModelV2StreamPart =
+  // Text blocks:
+  | {
+      type: 'text-start';
+      providerMetadata?: SharedV2ProviderMetadata;
+      id: string;
+    }
+  | {
+      type: 'text-delta';
+      id: string;
+      providerMetadata?: SharedV2ProviderMetadata;
+      delta: string;
+    }
+  | {
+      type: 'text-end';
+      providerMetadata?: SharedV2ProviderMetadata;
+      id: string;
+    }
+
+  // Reasoning blocks:
+  | {
+      type: 'reasoning-start';
+      providerMetadata?: SharedV2ProviderMetadata;
+      id: string;
+    }
+  | {
+      type: 'reasoning-delta';
+      id: string;
+      providerMetadata?: SharedV2ProviderMetadata;
+      delta: string;
+    }
+  | {
+      type: 'reasoning-end';
+      id: string;
+      providerMetadata?: SharedV2ProviderMetadata;
+    }
+
+  // Tool calls and results:
+  | {
+      type: 'tool-input-start';
+      id: string;
+      toolName: string;
+      providerMetadata?: SharedV2ProviderMetadata;
+      providerExecuted?: boolean;
+    }
+  | {
+      type: 'tool-input-delta';
+      id: string;
+      delta: string;
+      providerMetadata?: SharedV2ProviderMetadata;
+    }
+  | {
+      type: 'tool-input-end';
+      id: string;
+      providerMetadata?: SharedV2ProviderMetadata;
+    }
+  | LanguageModelV2ToolCall
+  | LanguageModelV2ToolResult
+
+  // Files and sources:
+  | LanguageModelV2File
+  | LanguageModelV2Source
+
+  // stream start event with warnings for the call, e.g. unsupported settings:
+  | {
+      type: 'stream-start';
+      warnings: Array<LanguageModelV2CallWarning>;
+    }
+
+  // metadata for the response.
+  // separate stream part so it can be sent once it is available.
+  | ({ type: 'response-metadata' } & LanguageModelV2ResponseMetadata)
+
+  // metadata that is available after the stream is finished:
+  | {
+      type: 'finish';
+      usage: LanguageModelV2Usage;
+      finishReason: LanguageModelV2FinishReason;
+      providerMetadata?: SharedV2ProviderMetadata;
+    }
+
+  // raw chunks if enabled
+  | {
+      type: 'raw';
+      rawValue: unknown;
+    }
+
+  // error parts are streamed, allowing for multiple errors
+  | {
+      type: 'error';
+      error: unknown;
+    };

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

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

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

@@ -0,0 +1,35 @@
+import { SharedV2ProviderMetadata } from '../../shared/v2/shared-v2-provider-metadata';
+
+/**
+ * Tool calls that the model has generated.
+ */
+export type LanguageModelV2ToolCall = {
+  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;
+
+  /**
+   * Additional provider-specific metadata for the tool call.
+   */
+  providerMetadata?: SharedV2ProviderMetadata;
+};

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

@@ -0,0 +1,5 @@
+export type LanguageModelV2ToolChoice =
+  | { 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/v2/language-model-v2-tool-result.ts

@@ -0,0 +1,40 @@
+import { SharedV2ProviderMetadata } from '../../shared/v2/shared-v2-provider-metadata';
+
+/**
+Result of a tool call that has been executed by the provider.
+ */
+export type LanguageModelV2ToolResult = {
+  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: unknown;
+
+  /**
+   * Optional flag if the result is an error or an error message.
+   */
+  isError?: boolean;
+
+  /**
+   * Whether the tool result was generated by the provider.
+   * If this flag is set to true, the tool result was generated by the provider.
+   * If this flag is not set or is false, the tool result was generated by the client.
+   */
+  providerExecuted?: boolean;
+
+  /**
+   * Additional provider-specific metadata for the tool result.
+   */
+  providerMetadata?: SharedV2ProviderMetadata;
+};

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

@@ -0,0 +1,34 @@
+/**
+Usage information for a language model call.
+
+If your API return additional usage information, you can add it to the
+provider metadata under your provider's key.
+ */
+export type LanguageModelV2Usage = {
+  /**
+The number of input (prompt) tokens used.
+   */
+  inputTokens: number | undefined;
+
+  /**
+The number of output (completion) tokens used.
+   */
+  outputTokens: number | undefined;
+
+  /**
+The total number of tokens as reported by the provider.
+This number might be different from the sum of `inputTokens` and `outputTokens`
+and e.g. include reasoning tokens or other overhead.
+   */
+  totalTokens: number | undefined;
+
+  /**
+The number of reasoning tokens used.
+   */
+  reasoningTokens?: number | undefined;
+
+  /**
+The number of cached input tokens.
+   */
+  cachedInputTokens?: number | undefined;
+};