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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/provider",
-  "version": "3.0.8",
+  "version": "4.0.0-beta.0",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",

package/src/embedding-model/index.ts

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

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

@@ -0,0 +1,26 @@
+import { SharedV4Headers, SharedV4ProviderOptions } from '../../shared';
+
+export type EmbeddingModelV4CallOptions = {
+  /**
+   * List of text values to generate embeddings for.
+   */
+  values: Array<string>;
+
+  /**
+   * 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?: SharedV4ProviderOptions;
+
+  /**
+   * Additional HTTP headers to be sent with the request.
+   * Only applicable for HTTP-based providers.
+   */
+  headers?: SharedV4Headers;
+};

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

@@ -0,0 +1,5 @@
+/**
+ * An embedding is a vector, i.e. an array of numbers.
+ * It is e.g. used to represent a text as a vector of word embeddings.
+ */
+export type EmbeddingModelV4Embedding = Array<number>;

package/src/embedding-model/v4/embedding-model-v4-result.ts

@@ -0,0 +1,48 @@
+import {
+  SharedV4Headers,
+  SharedV4ProviderMetadata,
+  SharedV4Warning,
+} from '../../shared';
+import { EmbeddingModelV4Embedding } from './embedding-model-v4-embedding';
+
+/**
+ * The result of a embedding model doEmbed call.
+ */
+export type EmbeddingModelV4Result = {
+  /**
+   * Generated embeddings. They are in the same order as the input values.
+   */
+  embeddings: Array<EmbeddingModelV4Embedding>;
+
+  /**
+   * Token usage. We only have input tokens for embeddings.
+   */
+  usage?: { tokens: number };
+
+  /**
+   * 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?: SharedV4ProviderMetadata;
+
+  /**
+   * Optional response information for debugging purposes.
+   */
+  response?: {
+    /**
+     * Response headers.
+     */
+    headers?: SharedV4Headers;
+
+    /**
+     * The response body.
+     */
+    body?: unknown;
+  };
+
+  /**
+   * Warnings for the call, e.g. unsupported settings.
+   */
+  warnings: Array<SharedV4Warning>;
+};

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

@@ -0,0 +1,54 @@
+import { EmbeddingModelV4CallOptions } from './embedding-model-v4-call-options';
+import { EmbeddingModelV4Result } from './embedding-model-v4-result';
+
+/**
+ * Specification for an embedding model that implements the embedding model
+ * interface version 3.
+ *
+ * It is specific to text embeddings.
+ */
+export type EmbeddingModelV4 = {
+  /**
+   * The embedding model must specify which embedding model interface
+   * version it implements. This will allow us to evolve the embedding
+   * 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 embeddings can be generated in a single API call.
+   *
+   * Use Infinity for models that do not have a limit.
+   */
+  readonly maxEmbeddingsPerCall:
+    | PromiseLike<number | undefined>
+    | number
+    | undefined;
+
+  /**
+   * True if the model can handle multiple embedding calls in parallel.
+   */
+  readonly supportsParallelCalls: PromiseLike<boolean> | boolean;
+
+  /**
+   * Generates a list of embeddings for the given input text.
+   *
+   * Naming: "do" prefix to prevent accidental direct usage of the method
+   * by the user.
+   */
+  doEmbed(
+    options: EmbeddingModelV4CallOptions,
+  ): PromiseLike<EmbeddingModelV4Result>;
+};

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

@@ -0,0 +1,4 @@
+export * from './embedding-model-v4';
+export * from './embedding-model-v4-call-options';
+export * from './embedding-model-v4-embedding';
+export * from './embedding-model-v4-result';

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

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

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

@@ -0,0 +1,69 @@
+import { EmbeddingModelV4 } from '../../embedding-model/v4/embedding-model-v4';
+import { EmbeddingModelV4CallOptions } from '../../embedding-model/v4/embedding-model-v4-call-options';
+
+/**
+ * Middleware for EmbeddingModelV4.
+ * This type defines the structure for middleware that can be used to modify
+ * the behavior of EmbeddingModelV4 operations.
+ */
+export type EmbeddingModelV4Middleware = {
+  /**
+   * Middleware specification version. Use `v4` for the current version.
+   */
+  readonly specificationVersion: 'v4';
+
+  /**
+   * Override the provider name if desired.
+   * @param options.model - The embedding model instance.
+   */
+  overrideProvider?: (options: { model: EmbeddingModelV4 }) => string;
+
+  /**
+   * Override the model ID if desired.
+   * @param options.model - The embedding model instance.
+   */
+  overrideModelId?: (options: { model: EmbeddingModelV4 }) => string;
+
+  /**
+   * Override the limit of how many embeddings can be generated in a single API call if desired.
+   * @param options.model - The embedding model instance.
+   */
+  overrideMaxEmbeddingsPerCall?: (options: {
+    model: EmbeddingModelV4;
+  }) => PromiseLike<number | undefined> | number | undefined;
+
+  /**
+   * Override support for handling multiple embedding calls in parallel, if desired..
+   * @param options.model - The embedding model instance.
+   */
+  overrideSupportsParallelCalls?: (options: {
+    model: EmbeddingModelV4;
+  }) => PromiseLike<boolean> | boolean;
+
+  /**
+   * Transforms the parameters before they are passed to the embed model.
+   * @param options - Object containing the type of operation and the parameters.
+   * @param options.params - The original parameters for the embedding model call.
+   * @returns A promise that resolves to the transformed parameters.
+   */
+  transformParams?: (options: {
+    params: EmbeddingModelV4CallOptions;
+    model: EmbeddingModelV4;
+  }) => PromiseLike<EmbeddingModelV4CallOptions>;
+
+  /**
+   * Wraps the embed operation of the embedding model.
+   *
+   * @param options - Object containing the embed function, parameters, and model.
+   * @param options.doEmbed - The original embed function.
+   * @param options.params - The parameters for the embed call. If the
+   * `transformParams` middleware is used, this will be the transformed parameters.
+   * @param options.model - The embedding model instance.
+   * @returns A promise that resolves to the result of the generate operation.
+   */
+  wrapEmbed?: (options: {
+    doEmbed: () => ReturnType<EmbeddingModelV4['doEmbed']>;
+    params: EmbeddingModelV4CallOptions;
+    model: EmbeddingModelV4;
+  }) => Promise<Awaited<ReturnType<EmbeddingModelV4['doEmbed']>>>;
+};

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

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

package/src/image-model/index.ts

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

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

@@ -0,0 +1,74 @@
+import { SharedV4ProviderOptions } from '../../shared';
+import { ImageModelV4File } from './image-model-v4-file';
+
+export type ImageModelV4CallOptions = {
+  /**
+   * Prompt for the image generation. Some operations, like upscaling, may not require a prompt.
+   */
+  prompt: string | undefined;
+
+  /**
+   * Number of images to generate.
+   */
+  n: number;
+
+  /**
+   * Size of the images to generate.
+   * Must have the format `{width}x{height}`.
+   * `undefined` will use the provider's default size.
+   */
+  size: `${number}x${number}` | undefined;
+
+  /**
+   * Aspect ratio of the images to generate.
+   * Must have the format `{width}:{height}`.
+   * `undefined` will use the provider's default aspect ratio.
+   */
+  aspectRatio: `${number}:${number}` | undefined;
+
+  /**
+   * Seed for the image generation.
+   * `undefined` will use the provider's default seed.
+   */
+  seed: number | undefined;
+
+  /**
+   * Array of images for image editing or variation generation.
+   * The images should be provided as base64 encoded strings or binary data.
+   */
+  files: ImageModelV4File[] | undefined;
+
+  /**
+   * Mask image for inpainting operations.
+   * The mask should be provided as base64 encoded strings or binary data.
+   */
+  mask: ImageModelV4File | undefined;
+
+  /**
+   * 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": {
+   *     "style": "vivid"
+   *   }
+   * }
+   * ```
+   */
+  providerOptions: SharedV4ProviderOptions;
+
+  /**
+   * 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/image-model/v4/image-model-v4-file.ts

@@ -0,0 +1,44 @@
+import { SharedV4ProviderMetadata } from '../../shared';
+
+/**
+ * An image file that can be used for image editing or variation generation.
+ */
+export type ImageModelV4File =
+  | {
+      type: 'file';
+
+      /**
+       * The IANA media type of the file, e.g. `image/png`. Any string is supported.
+       *
+       * @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.
+       */
+      providerOptions?: SharedV4ProviderMetadata;
+    }
+  | {
+      type: 'url';
+
+      /**
+       * The URL of the image file.
+       */
+      url: string;
+
+      /**
+       * Optional provider-specific metadata for the file part.
+       */
+      providerOptions?: SharedV4ProviderMetadata;
+    };

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';