@ai-sdk/provider 3.0.7 → 4.0.0-beta.0

package/src/image-model/v4/image-model-v4-usage.ts

@@ -0,0 +1,19 @@
+/**
+ * Usage information for an image model call.
+ */
+export type ImageModelV4Usage = {
+  /**
+   * The number of input (prompt) tokens used.
+   */
+  inputTokens: number | undefined;
+
+  /**
+   * The number of output tokens used, if reported by the provider.
+   */
+  outputTokens: number | undefined;
+
+  /**
+   * The total number of tokens as reported by the provider.
+   */
+  totalTokens: number | undefined;
+};

package/src/image-model/v4/image-model-v4.ts

@@ -0,0 +1,110 @@
+import { JSONArray, JSONValue } from '../../json-value';
+import { ImageModelV4Usage } from './image-model-v4-usage';
+import { ImageModelV4CallOptions } from './image-model-v4-call-options';
+import { SharedV4Warning } from '../../shared/v4/shared-v4-warning';
+
+export type ImageModelV4ProviderMetadata = Record<
+  string,
+  {
+    images: JSONArray;
+  } & JSONValue
+>;
+
+type GetMaxImagesPerCallFunction = (options: {
+  modelId: string;
+}) => PromiseLike<number | undefined> | number | undefined;
+
+/**
+ * Image generation model specification version 3.
+ */
+export type ImageModelV4 = {
+  /**
+   * The image model must specify which image model interface
+   * version it implements. This will allow us to evolve the image
+   * model interface and retain backwards compatibility. The different
+   * implementation versions can be handled as a discriminated union
+   * on our side.
+   */
+  readonly specificationVersion: 'v4';
+
+  /**
+   * Name of the provider for logging purposes.
+   */
+  readonly provider: string;
+
+  /**
+   * Provider-specific model ID for logging purposes.
+   */
+  readonly modelId: string;
+
+  /**
+   * Limit of how many images can be generated in a single API call.
+   * Can be set to a number for a fixed limit, to undefined to use
+   * the global limit, or a function that returns a number or undefined,
+   * optionally as a promise.
+   */
+  readonly maxImagesPerCall: number | undefined | GetMaxImagesPerCallFunction;
+
+  /**
+   * Generates an array of images.
+   */
+  doGenerate(options: ImageModelV4CallOptions): PromiseLike<{
+    /**
+     * Generated images as base64 encoded strings or binary data.
+     * The images should be returned without any unnecessary conversion.
+     * If the API returns base64 encoded strings, the images should be returned
+     * as base64 encoded strings. If the API returns binary data, the images should
+     * be returned as binary data.
+     */
+    images: Array<string> | Array<Uint8Array>;
+
+    /**
+     * Warnings for the call, e.g. unsupported features.
+     */
+    warnings: Array<SharedV4Warning>;
+
+    /**
+     * 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.
+     *
+     * The outer record is keyed by the provider name, and the inner
+     * record is provider-specific metadata. It always includes an
+     * `images` key with image-specific metadata
+     *
+     * ```ts
+     * {
+     * "openai": {
+     * "images": ["revisedPrompt": "Revised prompt here."]
+     * }
+     * }
+     * ```
+     */
+    providerMetadata?: ImageModelV4ProviderMetadata;
+
+    /**
+     * 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: Record<string, string> | undefined;
+    };
+
+    /**
+     * Optional token usage for the image generation call (if the provider reports it).
+     */
+    usage?: ImageModelV4Usage;
+  }>;
+};

package/src/image-model/v4/index.ts

@@ -0,0 +1,7 @@
+export type {
+  ImageModelV4,
+  ImageModelV4ProviderMetadata,
+} from './image-model-v4';
+export type { ImageModelV4CallOptions } from './image-model-v4-call-options';
+export type { ImageModelV4Usage } from './image-model-v4-usage';
+export type { ImageModelV4File } from './image-model-v4-file';

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

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

package/src/image-model-middleware/v4/image-model-v4-middleware.ts

@@ -0,0 +1,61 @@
+import { ImageModelV4 } from '../../image-model/v4/image-model-v4';
+import { ImageModelV4CallOptions } from '../../image-model/v4/image-model-v4-call-options';
+
+/**
+ * Middleware for ImageModelV4.
+ * This type defines the structure for middleware that can be used to modify
+ * the behavior of ImageModelV4 operations.
+ */
+export type ImageModelV4Middleware = {
+  /**
+   * Middleware specification version. Use `v4` for the current version.
+   */
+  readonly specificationVersion: 'v4';
+
+  /**
+   * Override the provider name if desired.
+   * @param options.model - The image model instance.
+   */
+  overrideProvider?: (options: { model: ImageModelV4 }) => string;
+
+  /**
+   * Override the model ID if desired.
+   * @param options.model - The image model instance.
+   */
+  overrideModelId?: (options: { model: ImageModelV4 }) => string;
+
+  /**
+   * Override the limit of how many images can be generated in a single API call if desired.
+   * @param options.model - The image model instance.
+   */
+  overrideMaxImagesPerCall?: (options: {
+    model: ImageModelV4;
+  }) => ImageModelV4['maxImagesPerCall'];
+
+  /**
+   * Transforms the parameters before they are passed to the image model.
+   * @param options - Object containing the parameters.
+   * @param options.params - The original parameters for the image model call.
+   * @returns A promise that resolves to the transformed parameters.
+   */
+  transformParams?: (options: {
+    params: ImageModelV4CallOptions;
+    model: ImageModelV4;
+  }) => PromiseLike<ImageModelV4CallOptions>;
+
+  /**
+   * Wraps the generate operation of the image model.
+   *
+   * @param options - Object containing the generate function, parameters, and model.
+   * @param options.doGenerate - The original generate 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 image model instance.
+   * @returns A promise that resolves to the result of the generate operation.
+   */
+  wrapGenerate?: (options: {
+    doGenerate: () => ReturnType<ImageModelV4['doGenerate']>;
+    params: ImageModelV4CallOptions;
+    model: ImageModelV4;
+  }) => Promise<Awaited<ReturnType<ImageModelV4['doGenerate']>>>;
+};

package/src/image-model-middleware/v4/index.ts

@@ -0,0 +1 @@
+export * from './image-model-v4-middleware';

package/src/language-model/index.ts

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

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

@@ -0,0 +1,21 @@
+export * from './language-model-v4';
+export * from './language-model-v4-call-options';
+export * from './language-model-v4-content';
+export * from './language-model-v4-data-content';
+export * from './language-model-v4-file';
+export * from './language-model-v4-finish-reason';
+export * from './language-model-v4-function-tool';
+export * from './language-model-v4-generate-result';
+export * from './language-model-v4-prompt';
+export * from './language-model-v4-provider-tool';
+export * from './language-model-v4-reasoning';
+export * from './language-model-v4-response-metadata';
+export * from './language-model-v4-source';
+export * from './language-model-v4-stream-part';
+export * from './language-model-v4-stream-result';
+export * from './language-model-v4-text';
+export * from './language-model-v4-tool-approval-request';
+export * from './language-model-v4-tool-call';
+export * from './language-model-v4-tool-choice';
+export * from './language-model-v4-tool-result';
+export * from './language-model-v4-usage';

package/src/language-model/v4/language-model-v4-call-options.ts

@@ -0,0 +1,125 @@
+import { JSONSchema7 } from 'json-schema';
+import { SharedV3ProviderOptions } from '../../shared/v3/shared-v3-provider-options';
+import { LanguageModelV4FunctionTool } from './language-model-v4-function-tool';
+import { LanguageModelV4Prompt } from './language-model-v4-prompt';
+import { LanguageModelV4ProviderTool } from './language-model-v4-provider-tool';
+import { LanguageModelV4ToolChoice } from './language-model-v4-tool-choice';
+
+export type LanguageModelV4CallOptions = {
+  /**
+   * A language mode prompt is a standardized prompt type.
+   *
+   * Note: This is **not** the user-facing prompt. The AI SDK methods will map the
+   * user-facing prompt types such as chat or instruction prompts to this format.
+   * That approach allows us to evolve the user  facing prompts without breaking
+   * the language model interface.
+   */
+  prompt: LanguageModelV4Prompt;
+
+  /**
+   * Maximum number of tokens to generate.
+   */
+  maxOutputTokens?: number;
+
+  /**
+   * Temperature setting. The range depends on the provider and model.
+   */
+  temperature?: number;
+
+  /**
+   * Stop sequences.
+   * If set, the model will stop generating text when one of the stop sequences is generated.
+   * Providers may have limits on the number of stop sequences.
+   */
+  stopSequences?: string[];
+
+  /**
+   * Nucleus sampling.
+   */
+  topP?: number;
+
+  /**
+   * Only sample from the top K options for each subsequent token.
+   *
+   * Used to remove "long tail" low probability responses.
+   * Recommended for advanced use cases only. You usually only need to use temperature.
+   */
+  topK?: number;
+
+  /**
+   * Presence penalty setting. It affects the likelihood of the model to
+   * repeat information that is already in the prompt.
+   */
+  presencePenalty?: number;
+
+  /**
+   * Frequency penalty setting. It affects the likelihood of the model
+   * to repeatedly use the same words or phrases.
+   */
+  frequencyPenalty?: number;
+
+  /**
+   * Response format. The output can either be text or JSON. Default is text.
+   *
+   * If JSON is selected, a schema can optionally be provided to guide the LLM.
+   */
+  responseFormat?:
+    | { type: 'text' }
+    | {
+        type: 'json';
+
+        /**
+         * JSON schema that the generated output should conform to.
+         */
+        schema?: JSONSchema7;
+
+        /**
+         * Name of output that should be generated. Used by some providers for additional LLM guidance.
+         */
+        name?: string;
+
+        /**
+         * Description of the output that should be generated. Used by some providers for additional LLM guidance.
+         */
+        description?: string;
+      };
+
+  /**
+   * The seed (integer) to use for random sampling. If set and supported
+   * by the model, calls will generate deterministic results.
+   */
+  seed?: number;
+
+  /**
+   * The tools that are available for the model.
+   */
+  tools?: Array<LanguageModelV4FunctionTool | LanguageModelV4ProviderTool>;
+
+  /**
+   * Specifies how the tool should be selected. Defaults to 'auto'.
+   */
+  toolChoice?: LanguageModelV4ToolChoice;
+
+  /**
+   * Include raw chunks in the stream. Only applicable for streaming calls.
+   */
+  includeRawChunks?: boolean;
+
+  /**
+   * 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>;
+
+  /**
+   * 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;
+};

package/src/language-model/v4/language-model-v4-content.ts

@@ -0,0 +1,16 @@
+import { LanguageModelV4File } from './language-model-v4-file';
+import { LanguageModelV4Reasoning } from './language-model-v4-reasoning';
+import { LanguageModelV4Source } from './language-model-v4-source';
+import { LanguageModelV4Text } from './language-model-v4-text';
+import { LanguageModelV4ToolApprovalRequest } from './language-model-v4-tool-approval-request';
+import { LanguageModelV4ToolCall } from './language-model-v4-tool-call';
+import { LanguageModelV4ToolResult } from './language-model-v4-tool-result';
+
+export type LanguageModelV4Content =
+  | LanguageModelV4Text
+  | LanguageModelV4Reasoning
+  | LanguageModelV4File
+  | LanguageModelV4ToolApprovalRequest
+  | LanguageModelV4Source
+  | LanguageModelV4ToolCall
+  | LanguageModelV4ToolResult;

package/src/language-model/v4/language-model-v4-data-content.ts

@@ -0,0 +1,4 @@
+/**
+ * Data content. Can be a Uint8Array, base64 encoded data as a string or a URL.
+ */
+export type LanguageModelV4DataContent = Uint8Array | string | URL;

package/src/language-model/v4/language-model-v4-file.ts

@@ -0,0 +1,32 @@
+import { SharedV3ProviderMetadata } from '../../shared';
+
+/**
+ * A file that has been generated by the model.
+ * Generated files as base64 encoded strings or binary data.
+ * The files should be returned without any unnecessary conversion.
+ */
+export type LanguageModelV4File = {
+  type: 'file';
+
+  /**
+   * The IANA media type of the file, e.g. `image/png` or `audio/mp3`.
+   *
+   * @see https://www.iana.org/assignments/media-types/media-types.xhtml
+   */
+  mediaType: string;
+
+  /**
+   * Generated file data as base64 encoded strings or binary data.
+   *
+   * The file data should be returned without any unnecessary conversion.
+   * If the API returns base64 encoded strings, the file data should be returned
+   * as base64 encoded strings. If the API returns binary data, the file data should
+   * be returned as binary data.
+   */
+  data: string | Uint8Array;
+
+  /**
+   * Optional provider-specific metadata for the file part.
+   */
+  providerMetadata?: SharedV3ProviderMetadata;
+};

package/src/language-model/v4/language-model-v4-finish-reason.ts

@@ -0,0 +1,33 @@
+/**
+ * Reason why a language model finished generating a response.
+ *
+ * Contains both a unified finish reason and a raw finish reason from the provider.
+ * The unified finish reason is used to provide a consistent finish reason across different providers.
+ * The raw finish reason is used to provide the original finish reason from the provider.
+ */
+export type LanguageModelV4FinishReason = {
+  /**
+   * Unified finish reason. This enables using the same finish reason across different providers.
+   *
+   * Can be one of the following:
+   * - `stop`: model generated stop sequence
+   * - `length`: model generated maximum number of tokens
+   * - `content-filter`: content filter violation stopped the model
+   * - `tool-calls`: model triggered tool calls
+   * - `error`: model stopped because of an error
+   * - `other`: model stopped for other reasons
+   */
+  unified:
+    | 'stop'
+    | 'length'
+    | 'content-filter'
+    | 'tool-calls'
+    | 'error'
+    | 'other';
+
+  /**
+   * Raw finish reason from the provider.
+   * This is the original finish reason from the provider.
+   */
+  raw: string | undefined;
+};

package/src/language-model/v4/language-model-v4-function-tool.ts

@@ -0,0 +1,53 @@
+import { JSONSchema7 } from 'json-schema';
+import { SharedV3ProviderOptions } from '../../shared';
+import { JSONObject } from '../../json-value';
+
+/**
+ * A tool has a name, a description, and a set of parameters.
+ *
+ * Note: this is **not** the user-facing tool definition. The AI SDK methods will
+ * map the user-facing tool definitions to this format.
+ */
+export type LanguageModelV4FunctionTool = {
+  /**
+   * The type of the tool (always 'function').
+   */
+  type: 'function';
+
+  /**
+   * The name of the tool. Unique within this model call.
+   */
+  name: string;
+
+  /**
+   * A description of the tool. The language model uses this to understand the
+   * tool's purpose and to provide better completion suggestions.
+   */
+  description?: string;
+
+  /**
+   * The parameters that the tool expects. The language model uses this to
+   * understand the tool's input requirements and to provide matching suggestions.
+   */
+  inputSchema: JSONSchema7;
+
+  /**
+   * An optional list of input examples that show the language
+   * model what the input should look like.
+   */
+  inputExamples?: Array<{ input: JSONObject }>;
+
+  /**
+   * Strict mode setting for the tool.
+   *
+   * Providers that support strict mode will use this setting to determine
+   * how the input should be generated. Strict mode will always produce
+   * valid inputs, but it might limit what input schemas are supported.
+   */
+  strict?: boolean;
+
+  /**
+   * The provider-specific options for the tool.
+   */
+  providerOptions?: SharedV3ProviderOptions;
+};

package/src/language-model/v4/language-model-v4-generate-result.ts

@@ -0,0 +1,63 @@
+import { SharedV3Headers, SharedV3Warning } from '../../shared';
+import { SharedV3ProviderMetadata } from '../../shared/v3/shared-v3-provider-metadata';
+import { LanguageModelV4Content } from './language-model-v4-content';
+import { LanguageModelV4FinishReason } from './language-model-v4-finish-reason';
+import { LanguageModelV4ResponseMetadata } from './language-model-v4-response-metadata';
+import { LanguageModelV4Usage } from './language-model-v4-usage';
+
+/**
+ * The result of a language model doGenerate call.
+ */
+export type LanguageModelV4GenerateResult = {
+  /**
+   * Ordered content that the model has generated.
+   */
+  content: Array<LanguageModelV4Content>;
+
+  /**
+   * The finish reason.
+   */
+  finishReason: LanguageModelV4FinishReason;
+
+  /**
+   * The usage information.
+   */
+  usage: LanguageModelV4Usage;
+
+  /**
+   * 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?: SharedV3ProviderMetadata;
+
+  /**
+   * Optional request information for telemetry and debugging purposes.
+   */
+  request?: {
+    /**
+     * Request HTTP body that was sent to the provider API.
+     */
+    body?: unknown;
+  };
+
+  /**
+   * Optional response information for telemetry and debugging purposes.
+   */
+  response?: LanguageModelV4ResponseMetadata & {
+    /**
+     * Response headers.
+     */
+    headers?: SharedV3Headers;
+
+    /**
+     * Response HTTP body.
+     */
+    body?: unknown;
+  };
+
+  /**
+   * Warnings for the call, e.g. unsupported settings.
+   */
+  warnings: Array<SharedV3Warning>;
+};