ai 3.1.0-canary.1 → 3.1.0-canary.3

package/core/dist/index.d.mts

@@ -1,6 +1,8 @@
 import { z } from 'zod';
 import { PartialDeep, ValueOf } from 'type-fest';
 
+type JsonSchema = Record<string, unknown>;
+
 type LanguageModelV1CallSettings = {
     /**
      * Maximum number of tokens to generate.
@@ -29,38 +31,32 @@ type LanguageModelV1CallSettings = {
      */
     topP?: number;
     /**
-     * Presence penalty setting. This is a number between 0 (no penalty)
-     * and 1 (maximum penalty). It affects the likelihood of the model to repeat
-     * information that is already in the prompt.
+     * Presence penalty setting. It affects the likelihood of the model to
+     * repeat information that is already in the prompt.
+     *
+     * The presence penalty is a number between -1 (increase repetition)
+     * and 1 (maximum penalty, decrease repetition). 0 means no penalty.
      */
     presencePenalty?: number;
     /**
-     * Frequency penalty setting. This is a number between 0 (no penalty)
-     * and 1 (maximum penalty). It affects the likelihood of the model to repeatedly
-     * use the same words or phrases.
+     * Frequency penalty setting. It affects the likelihood of the model
+     * to repeatedly use the same words or phrases.
+     *
+     * The frequency penalty is a number between -1 (increase repetition)
+     * and 1 (maximum penalty, decrease repetition). 0 means no penalty.
      */
     frequencyPenalty?: number;
     /**
-     * The seed to use for random sampling. If set and supported by the model,
-     * calls will generate deterministic results.
+     * The seed (integer) to use for random sampling. If set and supported
+     * by the model, calls will generate deterministic results.
      */
     seed?: number;
+    /**
+     * Abort signal for cancelling the operation.
+     */
+    abortSignal?: AbortSignal;
 };
 
-/**
- * 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.
- */
-type LanguageModelV1CallWarning = {
-    type: 'unsupported-setting';
-    setting: keyof LanguageModelV1CallSettings;
-} | {
-    type: 'other';
-    message: string;
-};
-
-type JsonSchema = Record<string, unknown>;
-
 /**
  * A tool has a name, a description, and a set of parameters.
  *
@@ -114,9 +110,9 @@ interface LanguageModelV1TextPart {
 interface LanguageModelV1ImagePart {
     type: 'image';
     /**
-     * Image data as a Uint8Array.
+     * Image data as a Uint8Array (e.g. from a Blob or Buffer) or a URL.
      */
-    image: Uint8Array;
+    image: Uint8Array | URL;
     /**
      * Optional mime type of the image.
      */
@@ -174,7 +170,48 @@ type LanguageModelV1CallOptions = LanguageModelV1CallSettings & {
     prompt: LanguageModelV1Prompt;
 };
 
-interface LanguageModel {
+/**
+ * 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.
+ */
+type LanguageModelV1CallWarning = {
+    type: 'unsupported-setting';
+    setting: keyof LanguageModelV1CallSettings;
+} | {
+    type: 'other';
+    message: string;
+};
+
+type LanguageModelV1FinishReason = 'stop' | 'length' | 'content-filter' | 'tool-calls' | 'error' | 'other';
+
+type LanguageModelV1FunctionToolCall = {
+    toolCallType: 'function';
+    toolCallId: string;
+    toolName: string;
+    /**
+     * Stringified JSON object with the tool call arguments. Must match the
+     * parameters schema of the tool.
+     */
+    args: string;
+};
+
+type LanguageModelV1 = {
+    /**
+     * The language model must specify which language model interface
+     * version it implements. This will allow us to evolve the language
+     * model interface and retain backwards compatibility. The different
+     * implementation versions can be handled as a discriminated union
+     * on our side.
+     */
+    readonly specificationVersion: 'v1';
+    /**
+     * Name of the provider for logging purposes.
+     */
+    readonly provider: string;
+    /**
+     * Provider-specific model ID for logging purposes.
+     */
+    readonly modelId: string;
     /**
      * Default object generation mode that should be used with this model when
      * no mode is specified. Should be the mode with the best results for this
@@ -184,39 +221,106 @@ interface LanguageModel {
      * user to explicitly specify the object generation mode.
      */
     readonly defaultObjectGenerationMode: 'json' | 'tool' | 'grammar' | undefined;
+    /**
+     * Generates a language model output (non-streaming).
+     *
+     * Naming: "do" prefix to prevent accidental direct usage of the method
+     * by the user.
+     */
     doGenerate(options: LanguageModelV1CallOptions): PromiseLike<{
+        /**
+         * Text that the model has generated. Can be undefined if the model
+         * has only generated tool calls.
+         */
         text?: string;
-        toolCalls?: Array<LanguageModelToolCall>;
-        warnings: LanguageModelV1CallWarning[];
+        /**
+         * Tool calls that the model has generated. Can be undefined if the
+         * model has only generated text.
+         */
+        toolCalls?: Array<LanguageModelV1FunctionToolCall>;
+        /**
+         * Finish reason.
+         */
+        finishReason: LanguageModelV1FinishReason;
+        /**
+         * Usage information.
+         */
+        usage: {
+            promptTokens: number;
+            completionTokens: number;
+        };
+        /**
+         * Raw prompt and setting information for observability provider integration.
+         */
+        rawCall: {
+            /**
+             * Raw prompt after expansion and conversion to the format that the
+             * provider uses to send the information to their API.
+             */
+            rawPrompt: unknown;
+            /**
+             * Raw settings that are used for the API call. Includes provider-specific
+             * settings.
+             */
+            rawSettings: Record<string, unknown>;
+        };
+        warnings?: LanguageModelV1CallWarning[];
     }>;
+    /**
+     * 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: LanguageModelV1CallOptions): PromiseLike<{
-        stream: ReadableStream<LanguageModelStreamPart>;
-        warnings: LanguageModelV1CallWarning[];
+        stream: ReadableStream<LanguageModelV1StreamPart>;
+        /**
+         * Raw prompt and setting information for observability provider integration.
+         */
+        rawCall: {
+            /**
+             * Raw prompt after expansion and conversion to the format that the
+             * provider uses to send the information to their API.
+             */
+            rawPrompt: unknown;
+            /**
+             * Raw settings that are used for the API call. Includes provider-specific
+             * settings.
+             */
+            rawSettings: Record<string, unknown>;
+        };
+        warnings?: LanguageModelV1CallWarning[];
     }>;
-}
-type ErrorStreamPart = {
-    type: 'error';
-    error: unknown;
 };
-type LanguageModelToolCall = {
-    toolCallId: string;
-    toolName: string;
-    args: string;
-};
-type ToolCallStreamPart = {
+type LanguageModelV1StreamPart = {
+    type: 'text-delta';
+    textDelta: string;
+} | ({
     type: 'tool-call';
-} & LanguageModelToolCall;
-type ToolCallDeltaStreamPart = {
+} & LanguageModelV1FunctionToolCall) | {
     type: 'tool-call-delta';
     toolCallId: string;
     toolName: string;
     argsTextDelta: string;
+} | {
+    type: 'finish-metadata';
+    finishReason: LanguageModelV1FinishReason;
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+} | {
+    type: 'error';
+    error: unknown;
 };
-type TextDeltaStreamPart = {
-    type: 'text-delta';
-    textDelta: string;
+
+type TokenUsage = {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
 };
-type LanguageModelStreamPart = TextDeltaStreamPart | ToolCallDeltaStreamPart | ToolCallStreamPart | ErrorStreamPart;
 
 type CallSettings = {
     /**
@@ -240,22 +344,34 @@ type CallSettings = {
      */
     topP?: number;
     /**
-     * Presence penalty setting. This is a number between 0 (no penalty)
-     * and 1 (maximum penalty). It affects the likelihood of the model to repeat
-     * information that is already in the prompt.
+     * Presence penalty setting. It affects the likelihood of the model to
+     * repeat information that is already in the prompt.
+     *
+     * The presence penalty is a number between -1 (increase repetition)
+     * and 1 (maximum penalty, decrease repetition). 0 means no penalty.
      */
     presencePenalty?: number;
     /**
-     * Frequency penalty setting. This is a number between 0 (no penalty)
-     * and 1 (maximum penalty). It affects the likelihood of the model to
-     * repeatedly use the same words or phrases.
+     * Frequency penalty setting. It affects the likelihood of the model
+     * to repeatedly use the same words or phrases.
+     *
+     * The frequency penalty is a number between -1 (increase repetition)
+     * and 1 (maximum penalty, decrease repetition). 0 means no penalty.
      */
     frequencyPenalty?: number;
     /**
-     * The seed to use for random sampling. If set and supported by the model,
-     * calls will generate deterministic results.
+     * The seed (integer) to use for random sampling. If set and supported
+     * by the model, calls will generate deterministic results.
      */
     seed?: number;
+    /**
+     * Maximum number of retries. Set to 0 to disable retries. Default is 2.
+     */
+    maxRetries?: number;
+    /**
+     * Abort signal.
+     */
+    abortSignal?: AbortSignal;
 };
 
 /**
@@ -275,9 +391,12 @@ interface TextPart {
 interface ImagePart {
     type: 'image';
     /**
-     * Image data. Can either be a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer.
+     * Image data. Can either be:
+     *
+     * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
+     * - URL: a URL that points to the image
      */
-    image: DataContent;
+    image: DataContent | URL;
     /**
      * Optional mime type of the image.
      */
@@ -322,23 +441,27 @@ type Prompt = {
 /**
  * Generate a structured, typed object using a language model.
  */
-declare function generateObject<T>({ model, schema: zodSchema, mode, system, prompt, messages, ...settings }: CallSettings & Prompt & {
-    model: LanguageModel;
+declare function generateObject<T>({ model, schema, mode, system, prompt, messages, maxRetries, abortSignal, ...settings }: CallSettings & Prompt & {
+    model: LanguageModelV1;
     schema: z.Schema<T>;
     mode?: 'auto' | 'json' | 'tool' | 'grammar';
 }): Promise<GenerateObjectResult<T>>;
 declare class GenerateObjectResult<T> {
     readonly object: T;
+    readonly finishReason: LanguageModelV1FinishReason;
+    readonly usage: TokenUsage;
     constructor(options: {
         object: T;
+        finishReason: LanguageModelV1FinishReason;
+        usage: TokenUsage;
     });
 }
 
 /**
  * Stream an object as a partial object stream.
  */
-declare function streamObject<T>({ model, schema: zodSchema, mode, system, prompt, messages, ...settings }: CallSettings & Prompt & {
-    model: LanguageModel;
+declare function streamObject<T>({ model, schema, mode, system, prompt, messages, maxRetries, abortSignal, ...settings }: CallSettings & Prompt & {
+    model: LanguageModelV1;
     schema: z.Schema<T>;
     mode?: 'auto' | 'json' | 'tool' | 'grammar';
 }): Promise<StreamObjectResult<T>>;
@@ -348,6 +471,10 @@ declare class StreamObjectResult<T> {
     }>>;
     constructor(modelStream: ReadableStream<string | ErrorStreamPart>);
 }
+type ErrorStreamPart = {
+    type: 'error';
+    error: unknown;
+};
 
 /**
  * A tool contains the description and the schema of the input that the tool expects.
@@ -416,30 +543,30 @@ type ToToolResultArray<TOOLS extends Record<string, Tool>> = Array<ToToolResult<
 /**
  * Generate a text and call tools using a language model.
  */
-declare function generateText<TOOLS extends Record<string, Tool>>({ model, tools, system, prompt, messages, ...settings }: CallSettings & Prompt & {
-    model: LanguageModel;
+declare function generateText<TOOLS extends Record<string, Tool>>({ model, tools, system, prompt, messages, maxRetries, abortSignal, ...settings }: CallSettings & Prompt & {
+    model: LanguageModelV1;
     tools?: TOOLS;
 }): Promise<GenerateTextResult<TOOLS>>;
 declare class GenerateTextResult<TOOLS extends Record<string, Tool>> {
     readonly text: string;
     readonly toolCalls: ToToolCallArray<TOOLS>;
     readonly toolResults: ToToolResultArray<TOOLS>;
+    readonly finishReason: LanguageModelV1FinishReason;
+    readonly usage: TokenUsage;
     constructor(options: {
         text: string;
         toolCalls: ToToolCallArray<TOOLS>;
         toolResults: ToToolResultArray<TOOLS>;
+        finishReason: LanguageModelV1FinishReason;
+        usage: TokenUsage;
     });
 }
 
-declare class StreamTextHttpResponse extends Response {
-    constructor(messageStream: ReadableStream<TextStreamPart<any>>);
-}
-
 /**
  * Stream text generated by a language model.
  */
-declare function streamText<TOOLS extends Record<string, Tool>>({ model, tools, system, prompt, messages, ...settings }: CallSettings & Prompt & {
-    model: LanguageModel;
+declare function streamText<TOOLS extends Record<string, Tool>>({ model, tools, system, prompt, messages, maxRetries, abortSignal, ...settings }: CallSettings & Prompt & {
+    model: LanguageModelV1;
     tools?: TOOLS;
 }): Promise<StreamTextResult<TOOLS>>;
 type TextStreamPart<TOOLS extends Record<string, Tool>> = {
@@ -458,23 +585,6 @@ declare class StreamTextResult<TOOLS extends Record<string, Tool>> {
     readonly textStream: AsyncIterable<string>;
     readonly fullStream: AsyncIterable<TextStreamPart<TOOLS>>;
     constructor(stream: ReadableStream<TextStreamPart<TOOLS>>);
-    toResponse(): StreamTextHttpResponse;
-}
-
-declare class UnsupportedFunctionalityError extends Error {
-    readonly functionality: string;
-    readonly provider: string;
-    constructor({ provider, functionality, }: {
-        provider: string;
-        functionality: string;
-    });
-    toJSON(): {
-        name: string;
-        message: string;
-        stack: string | undefined;
-        provider: string;
-        functionality: string;
-    };
 }
 
-export { AssistantContent, AssistantMessage, DataContent, ErrorStreamPart, GenerateObjectResult, GenerateTextResult, ImagePart, LanguageModel, LanguageModelStreamPart, LanguageModelToolCall, LanguageModelV1ImagePart, LanguageModelV1Message, LanguageModelV1Prompt, LanguageModelV1TextPart, LanguageModelV1ToolCallPart, LanguageModelV1ToolResultPart, Message, StreamObjectResult, StreamTextHttpResponse, StreamTextResult, TextPart, TextStreamPart, Tool, ToolCallPart, ToolContent, ToolMessage, ToolResultPart, UnsupportedFunctionalityError, UserContent, UserMessage, convertDataContentToBase64String, convertDataContentToUint8Array, generateObject, generateText, streamObject, streamText, tool };
+export { AssistantContent, AssistantMessage, DataContent, ErrorStreamPart, GenerateObjectResult, GenerateTextResult, ImagePart, Message, StreamObjectResult, StreamTextResult, TextPart, TextStreamPart, Tool, ToolCallPart, ToolContent, ToolMessage, ToolResultPart, UserContent, UserMessage, convertDataContentToBase64String, convertDataContentToUint8Array, generateObject, generateText, streamObject, streamText, tool };