@ai-sdk/provider 3.0.1 → 3.0.3

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

@@ -0,0 +1,137 @@
+import { SharedV2Headers } from '../../shared';
+import { SharedV2ProviderMetadata } from '../../shared/v2/shared-v2-provider-metadata';
+import { LanguageModelV2CallOptions } from './language-model-v2-call-options';
+import { LanguageModelV2CallWarning } from './language-model-v2-call-warning';
+import { LanguageModelV2Content } from './language-model-v2-content';
+import { LanguageModelV2FinishReason } from './language-model-v2-finish-reason';
+import { LanguageModelV2ResponseMetadata } from './language-model-v2-response-metadata';
+import { LanguageModelV2StreamPart } from './language-model-v2-stream-part';
+import { LanguageModelV2Usage } from './language-model-v2-usage';
+
+/**
+Specification for a language model that implements the language model interface version 2.
+ */
+export type LanguageModelV2 = {
+  /**
+The language model must specify which language model interface version it implements.
+   */
+  readonly specificationVersion: 'v2';
+
+  /**
+Name of the provider for logging purposes.
+   */
+  readonly provider: string;
+
+  /**
+Provider-specific model ID for logging purposes.
+   */
+  readonly modelId: string;
+
+  /**
+Supported URL patterns by media type for the provider.
+
+The keys are media type patterns or full media types (e.g. `*\/*` for everything, `audio/*`, `video/*`, or `application/pdf`).
+and the values are arrays of regular expressions that match the URL paths.
+
+The matching should be against lower-case URLs.
+
+Matched URLs are supported natively by the model and are not downloaded.
+
+@returns A map of supported URL patterns by media type (as a promise or a plain object).
+   */
+  supportedUrls:
+    | PromiseLike<Record<string, RegExp[]>>
+    | Record<string, RegExp[]>;
+
+  /**
+Generates a language model output (non-streaming).
+
+Naming: "do" prefix to prevent accidental direct usage of the method
+by the user.
+   */
+  doGenerate(options: LanguageModelV2CallOptions): PromiseLike<{
+    /**
+Ordered content that the model has generated.
+     */
+    content: Array<LanguageModelV2Content>;
+
+    /**
+Finish reason.
+     */
+    finishReason: LanguageModelV2FinishReason;
+
+    /**
+  Usage information.
+     */
+    usage: LanguageModelV2Usage;
+
+    /**
+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?: SharedV2ProviderMetadata;
+
+    /**
+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?: LanguageModelV2ResponseMetadata & {
+      /**
+Response headers.
+      */
+      headers?: SharedV2Headers;
+
+      /**
+Response HTTP body.
+*/
+      body?: unknown;
+    };
+
+    /**
+Warnings for the call, e.g. unsupported settings.
+     */
+    warnings: Array<LanguageModelV2CallWarning>;
+  }>;
+
+  /**
+Generates a language model output (streaming).
+
+Naming: "do" prefix to prevent accidental direct usage of the method
+by the user.
+   *
+@return A stream of higher-level language model output parts.
+   */
+  doStream(options: LanguageModelV2CallOptions): PromiseLike<{
+    stream: ReadableStream<LanguageModelV2StreamPart>;
+
+    /**
+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?: SharedV2Headers;
+    };
+  }>;
+};

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

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

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

@@ -0,0 +1,125 @@
+import { JSONSchema7 } from 'json-schema';
+import { SharedV3ProviderOptions } from '../../shared/v3/shared-v3-provider-options';
+import { LanguageModelV3FunctionTool } from './language-model-v3-function-tool';
+import { LanguageModelV3Prompt } from './language-model-v3-prompt';
+import { LanguageModelV3ProviderTool } from './language-model-v3-provider-tool';
+import { LanguageModelV3ToolChoice } from './language-model-v3-tool-choice';
+
+export type LanguageModelV3CallOptions = {
+  /**
+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: LanguageModelV3Prompt;
+
+  /**
+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<LanguageModelV3FunctionTool | LanguageModelV3ProviderTool>;
+
+  /**
+Specifies how the tool should be selected. Defaults to 'auto'.
+*/
+  toolChoice?: LanguageModelV3ToolChoice;
+
+  /**
+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/v3/language-model-v3-content.ts

@@ -0,0 +1,16 @@
+import { LanguageModelV3File } from './language-model-v3-file';
+import { LanguageModelV3Reasoning } from './language-model-v3-reasoning';
+import { LanguageModelV3Source } from './language-model-v3-source';
+import { LanguageModelV3Text } from './language-model-v3-text';
+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';
+
+export type LanguageModelV3Content =
+  | LanguageModelV3Text
+  | LanguageModelV3Reasoning
+  | LanguageModelV3File
+  | LanguageModelV3ToolApprovalRequest
+  | LanguageModelV3Source
+  | LanguageModelV3ToolCall
+  | LanguageModelV3ToolResult;

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

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

package/src/language-model/v3/language-model-v3-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 LanguageModelV3File = {
+  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/v3/language-model-v3-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 LanguageModelV3FinishReason = {
+  /**
+   * 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/v3/language-model-v3-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 LanguageModelV3FunctionTool = {
+  /**
+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/v3/language-model-v3-generate-result.ts

@@ -0,0 +1,63 @@
+import { SharedV3Headers, SharedV3Warning } from '../../shared';
+import { SharedV3ProviderMetadata } from '../../shared/v3/shared-v3-provider-metadata';
+import { LanguageModelV3Content } from './language-model-v3-content';
+import { LanguageModelV3FinishReason } from './language-model-v3-finish-reason';
+import { LanguageModelV3ResponseMetadata } from './language-model-v3-response-metadata';
+import { LanguageModelV3Usage } from './language-model-v3-usage';
+
+/**
+ * The result of a language model doGenerate call.
+ */
+export type LanguageModelV3GenerateResult = {
+  /**
+   * Ordered content that the model has generated.
+   */
+  content: Array<LanguageModelV3Content>;
+
+  /**
+   * The finish reason.
+   */
+  finishReason: LanguageModelV3FinishReason;
+
+  /**
+   * The usage information.
+   */
+  usage: LanguageModelV3Usage;
+
+  /**
+   * 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?: LanguageModelV3ResponseMetadata & {
+    /**
+     * Response headers.
+     */
+    headers?: SharedV3Headers;
+
+    /**
+     * Response HTTP body.
+     */
+    body?: unknown;
+  };
+
+  /**
+   * Warnings for the call, e.g. unsupported settings.
+   */
+  warnings: Array<SharedV3Warning>;
+};