@ai-sdk/provider 3.0.2 → 3.0.3

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

@@ -0,0 +1,110 @@
+import { JSONArray, JSONValue } from '../../json-value';
+import { ImageModelV3Usage } from './image-model-v3-usage';
+import { ImageModelV3CallOptions } from './image-model-v3-call-options';
+import { SharedV3Warning } from '../../shared/v3/shared-v3-warning';
+
+export type ImageModelV3ProviderMetadata = Record<
+  string,
+  {
+    images: JSONArray;
+  } & JSONValue
+>;
+
+type GetMaxImagesPerCallFunction = (options: {
+  modelId: string;
+}) => PromiseLike<number | undefined> | number | undefined;
+
+/**
+Image generation model specification version 3.
+ */
+export type ImageModelV3 = {
+  /**
+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: 'v3';
+
+  /**
+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: ImageModelV3CallOptions): 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<SharedV3Warning>;
+
+    /**
+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?: ImageModelV3ProviderMetadata;
+
+    /**
+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?: ImageModelV3Usage;
+  }>;
+};

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

@@ -0,0 +1,7 @@
+export type {
+  ImageModelV3,
+  ImageModelV3ProviderMetadata,
+} from './image-model-v3';
+export type { ImageModelV3CallOptions } from './image-model-v3-call-options';
+export type { ImageModelV3Usage } from './image-model-v3-usage';
+export type { ImageModelV3File } from './image-model-v3-file';

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

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

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

@@ -0,0 +1,61 @@
+import { ImageModelV3 } from '../../image-model/v3/image-model-v3';
+import { ImageModelV3CallOptions } from '../../image-model/v3/image-model-v3-call-options';
+
+/**
+ * Middleware for ImageModelV3.
+ * This type defines the structure for middleware that can be used to modify
+ * the behavior of ImageModelV3 operations.
+ */
+export type ImageModelV3Middleware = {
+  /**
+   * Middleware specification version. Use `v3` for the current version.
+   */
+  readonly specificationVersion: 'v3';
+
+  /**
+   * Override the provider name if desired.
+   * @param options.model - The image model instance.
+   */
+  overrideProvider?: (options: { model: ImageModelV3 }) => string;
+
+  /**
+   * Override the model ID if desired.
+   * @param options.model - The image model instance.
+   */
+  overrideModelId?: (options: { model: ImageModelV3 }) => 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: ImageModelV3;
+  }) => ImageModelV3['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: ImageModelV3CallOptions;
+    model: ImageModelV3;
+  }) => PromiseLike<ImageModelV3CallOptions>;
+
+  /**
+   * 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<ImageModelV3['doGenerate']>;
+    params: ImageModelV3CallOptions;
+    model: ImageModelV3;
+  }) => Promise<Awaited<ReturnType<ImageModelV3['doGenerate']>>>;
+};

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

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

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from './embedding-model/index';
+export * from './errors/index';
+export * from './image-model/index';
+export * from './image-model-middleware/index';
+export * from './json-value/index';
+export * from './language-model-middleware/index';
+export * from './embedding-model-middleware/index';
+export * from './language-model/index';
+export * from './provider/index';
+export * from './reranking-model/index';
+export * from './shared/index';
+export * from './speech-model/index';
+export * from './transcription-model/index';
+
+export type { JSONSchema7, JSONSchema7Definition } from 'json-schema';

package/src/json-value/index.ts

@@ -0,0 +1,2 @@
+export { isJSONArray, isJSONObject, isJSONValue } from './is-json';
+export type { JSONArray, JSONObject, JSONValue } from './json-value';

package/src/json-value/is-json.ts

@@ -0,0 +1,40 @@
+import { JSONArray, JSONObject, JSONValue } from './json-value';
+
+export function isJSONValue(value: unknown): value is JSONValue {
+  if (
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return true;
+  }
+
+  if (Array.isArray(value)) {
+    return value.every(isJSONValue);
+  }
+
+  if (typeof value === 'object') {
+    return Object.entries(value).every(
+      ([key, val]) =>
+        typeof key === 'string' && (val === undefined || isJSONValue(val)),
+    );
+  }
+
+  return false;
+}
+
+export function isJSONArray(value: unknown): value is JSONArray {
+  return Array.isArray(value) && value.every(isJSONValue);
+}
+
+export function isJSONObject(value: unknown): value is JSONObject {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    Object.entries(value).every(
+      ([key, val]) =>
+        typeof key === 'string' && (val === undefined || isJSONValue(val)),
+    )
+  );
+}

package/src/json-value/json-value.ts

@@ -0,0 +1,17 @@
+/**
+A JSON value can be a string, number, boolean, object, array, or null.
+JSON values can be serialized and deserialized by the JSON.stringify and JSON.parse methods.
+ */
+export type JSONValue =
+  | null
+  | string
+  | number
+  | boolean
+  | JSONObject
+  | JSONArray;
+
+export type JSONObject = {
+  [key: string]: JSONValue | undefined;
+};
+
+export type JSONArray = JSONValue[];

package/src/language-model/index.ts

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

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

@@ -0,0 +1,18 @@
+export * from './language-model-v2';
+export * from './language-model-v2-call-options';
+export * from './language-model-v2-call-warning';
+export * from './language-model-v2-content';
+export * from './language-model-v2-data-content';
+export * from './language-model-v2-file';
+export * from './language-model-v2-finish-reason';
+export * from './language-model-v2-function-tool';
+export * from './language-model-v2-prompt';
+export * from './language-model-v2-provider-defined-tool';
+export * from './language-model-v2-reasoning';
+export * from './language-model-v2-response-metadata';
+export * from './language-model-v2-source';
+export * from './language-model-v2-stream-part';
+export * from './language-model-v2-text';
+export * from './language-model-v2-tool-call';
+export * from './language-model-v2-tool-choice';
+export * from './language-model-v2-usage';

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

@@ -0,0 +1,125 @@
+import { JSONSchema7 } from 'json-schema';
+import { SharedV2ProviderOptions } from '../../shared/v2/shared-v2-provider-options';
+import { LanguageModelV2FunctionTool } from './language-model-v2-function-tool';
+import { LanguageModelV2Prompt } from './language-model-v2-prompt';
+import { LanguageModelV2ProviderTool } from './language-model-v2-provider-defined-tool';
+import { LanguageModelV2ToolChoice } from './language-model-v2-tool-choice';
+
+export type LanguageModelV2CallOptions = {
+  /**
+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: LanguageModelV2Prompt;
+
+  /**
+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<LanguageModelV2FunctionTool | LanguageModelV2ProviderTool>;
+
+  /**
+Specifies how the tool should be selected. Defaults to 'auto'.
+*/
+  toolChoice?: LanguageModelV2ToolChoice;
+
+  /**
+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?: SharedV2ProviderOptions;
+};

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

@@ -0,0 +1,23 @@
+import { LanguageModelV2CallOptions } from './language-model-v2-call-options';
+import { LanguageModelV2FunctionTool } from './language-model-v2-function-tool';
+import { LanguageModelV2ProviderTool } from './language-model-v2-provider-defined-tool';
+
+/**
+Warning from the model provider for this call. The call will proceed, but e.g.
+some settings might not be supported, which can lead to suboptimal results.
+ */
+export type LanguageModelV2CallWarning =
+  | {
+      type: 'unsupported-setting';
+      setting: Omit<keyof LanguageModelV2CallOptions, 'prompt'>;
+      details?: string;
+    }
+  | {
+      type: 'unsupported-tool';
+      tool: LanguageModelV2FunctionTool | LanguageModelV2ProviderTool;
+      details?: string;
+    }
+  | {
+      type: 'other';
+      message: string;
+    };

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

@@ -0,0 +1,14 @@
+import { LanguageModelV2File } from './language-model-v2-file';
+import { LanguageModelV2Reasoning } from './language-model-v2-reasoning';
+import { LanguageModelV2Source } from './language-model-v2-source';
+import { LanguageModelV2Text } from './language-model-v2-text';
+import { LanguageModelV2ToolCall } from './language-model-v2-tool-call';
+import { LanguageModelV2ToolResult } from './language-model-v2-tool-result';
+
+export type LanguageModelV2Content =
+  | LanguageModelV2Text
+  | LanguageModelV2Reasoning
+  | LanguageModelV2File
+  | LanguageModelV2Source
+  | LanguageModelV2ToolCall
+  | LanguageModelV2ToolResult;

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

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

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

@@ -0,0 +1,25 @@
+/**
+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 LanguageModelV2File = {
+  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;
+};

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

@@ -0,0 +1,20 @@
+/**
+Reason why a language model finished generating a response.
+
+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
+- `unknown`: the model has not transmitted a finish reason
+ */
+export type LanguageModelV2FinishReason =
+  | '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
+  | 'unknown'; // the model has not transmitted a finish reason

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

@@ -0,0 +1,37 @@
+import { JSONSchema7 } from 'json-schema';
+import { SharedV2ProviderOptions } from '../../shared';
+
+/**
+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 LanguageModelV2FunctionTool = {
+  /**
+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;
+
+  /**
+The provider-specific options for the tool.
+   */
+  providerOptions?: SharedV2ProviderOptions;
+};