ai 3.0.14 → 3.0.16

package/dist/index.d.mts

@@ -198,6 +198,10 @@ type LanguageModelV1FunctionToolCall = {
     args: string;
 };
 
+/**
+ * Experimental: Specification for a language model that implements the language model
+ * interface version 1.
+ */
 type LanguageModelV1 = {
     /**
      * The language model must specify which language model interface
@@ -328,140 +332,277 @@ type TokenUsage = {
 
 type CallSettings = {
     /**
-     * Maximum number of tokens to generate.
+  Maximum number of tokens to generate.
      */
     maxTokens?: number;
     /**
-     * Temperature setting. This is a number between 0 (almost no randomness) and
-     * 1 (very random).
-     *
-     * It is recommended to set either `temperature` or `topP`, but not both.
-     *
-     * @default 0
+  Temperature setting. This is a number between 0 (almost no randomness) and
+  1 (very random).
+  
+  It is recommended to set either `temperature` or `topP`, but not both.
+  
+  @default 0
      */
     temperature?: number;
     /**
-     * Nucleus sampling. This is a number between 0 and 1.
-     *
-     * E.g. 0.1 would mean that only tokens with the top 10% probability mass
-     * are considered.
-     *
-     * It is recommended to set either `temperature` or `topP`, but not both.
+  Nucleus sampling. This is a number between 0 and 1.
+  
+  E.g. 0.1 would mean that only tokens with the top 10% probability mass
+  are considered.
+  
+  It is recommended to set either `temperature` or `topP`, but not both.
      */
     topP?: number;
     /**
-     * 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.
-     *
-     * @default 0
+  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.
+  
+  @default 0
      */
     presencePenalty?: number;
     /**
-     * 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.
-     *
-     * @default 0
+  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.
+  
+  @default 0
      */
     frequencyPenalty?: number;
     /**
-     * The seed (integer) 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 2
+  Maximum number of retries. Set to 0 to disable retries.
+  
+  @default 2
      */
     maxRetries?: number;
     /**
-     * Abort signal.
+  Abort signal.
      */
     abortSignal?: AbortSignal;
 };
 
 /**
- * Data content. Can either be a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer.
+Data content. Can either be a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer.
  */
 type DataContent = string | Uint8Array | ArrayBuffer | Buffer;
+/**
+Converts data content to a base64-encoded string.
+
+@param content - Data content to convert.
+@returns Base64-encoded string.
+*/
 declare function convertDataContentToBase64String(content: DataContent): string;
+/**
+Converts data content to a Uint8Array.
+
+@param content - Data content to convert.
+@returns Uint8Array.
+ */
 declare function convertDataContentToUint8Array(content: DataContent): Uint8Array;
 
+/**
+Text content part of a prompt. It contains a string of text.
+ */
 interface TextPart$1 {
     type: 'text';
     /**
-     * The text content.
+  The text content.
      */
     text: string;
 }
+/**
+Image content part of a prompt. It contains an image.
+ */
 interface ImagePart {
     type: 'image';
     /**
-     * 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 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 | URL;
     /**
-     * Optional mime type of the image.
+  Optional mime type of the image.
      */
     mimeType?: string;
 }
+/**
+Tool call content part of a prompt. It contains a tool call (usually generated by the AI model).
+ */
 interface ToolCallPart {
     type: 'tool-call';
+    /**
+  ID of the tool call. This ID is used to match the tool call with the tool result.
+   */
     toolCallId: string;
+    /**
+  Name of the tool that is being called.
+   */
     toolName: string;
+    /**
+  Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.
+     */
     args: unknown;
 }
+/**
+Tool result content part of a prompt. It contains the result of the tool call with the matching ID.
+ */
 interface ToolResultPart {
     type: 'tool-result';
+    /**
+  ID of the tool call that this result is associated with.
+   */
     toolCallId: string;
+    /**
+  Name of the tool that generated this result.
+    */
     toolName: string;
+    /**
+  Result of the tool call. This is a JSON-serializable object.
+     */
     result: unknown;
 }
 
+/**
+A message that can be used in the `messages` field of a prompt.
+It can be a user message, an assistant message, or a tool message.
+ */
 type ExperimentalMessage = ExperimentalUserMessage | ExperimentalAssistantMessage | ExperimentalToolMessage;
+/**
+A user message. It can contain text or a combination of text and images.
+ */
 type ExperimentalUserMessage = {
     role: 'user';
     content: UserContent;
 };
+/**
+Content of a user message. It can be a string or an array of text and image parts.
+ */
+type UserContent = string | Array<TextPart$1 | ImagePart>;
+/**
+An assistant message. It can contain text, tool calls, or a combination of text and tool calls.
+ */
 type ExperimentalAssistantMessage = {
     role: 'assistant';
     content: AssistantContent;
 };
+/**
+Content of an assistant message. It can be a string or an array of text and tool call parts.
+ */
+type AssistantContent = string | Array<TextPart$1 | ToolCallPart>;
+/**
+A tool message. It contains the result of one or more tool calls.
+ */
 type ExperimentalToolMessage = {
     role: 'tool';
     content: ToolContent;
 };
-type UserContent = string | Array<TextPart$1 | ImagePart>;
-type AssistantContent = string | Array<TextPart$1 | ToolCallPart>;
+/**
+Content of a tool message. It is an array of tool result parts.
+ */
 type ToolContent = Array<ToolResultPart>;
 
+/**
+Prompt part of the AI function options. It contains a system message, a simple text prompt, or a list of messages.
+ */
 type Prompt = {
+    /**
+  System message to include in the prompt. Can be used with `prompt` or `messages`.
+     */
     system?: string;
+    /**
+  A simple text prompt. You can either use `prompt` or `messages` but not both.
+   */
     prompt?: string;
+    /**
+  A list of messsages. You can either use `prompt` or `messages` but not both.
+     */
     messages?: Array<ExperimentalMessage>;
 };
 
 /**
- * Generate a structured, typed object using a language model.
+Generate a structured, typed object for a given prompt and schema using a language model.
+
+This function does not stream the output. If you want to stream the output, use `experimental_streamObject` instead.
+
+@param model - The language model to use.
+
+@param schema - The schema of the object that the model should generate.
+@param mode - The mode to use for object generation. Not all models support all modes. Defaults to 'auto'.
+
+@param system - A system message that will be part of the prompt.
+@param prompt - A simple text prompt. You can either use `prompt` or `messages` but not both.
+@param messages - A list of messages. You can either use `prompt` or `messages` but not both.
+
+@param maxTokens - Maximum number of tokens to generate.
+@param temperature - Temperature setting.
+This is a number between 0 (almost no randomness) and 1 (very random).
+It is recommended to set either `temperature` or `topP`, but not both.
+@param topP - Nucleus sampling. This is a number between 0 and 1.
+E.g. 0.1 would mean that only tokens with the top 10% probability mass are considered.
+It is recommended to set either `temperature` or `topP`, but not both.
+@param presencePenalty - 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.
+@param frequencyPenalty - 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.
+@param seed - The seed (integer) to use for random sampling.
+If set and supported by the model, calls will generate deterministic results.
+
+@param maxRetries - Maximum number of retries. Set to 0 to disable retries. Default: 2.
+@param abortSignal - An optional abort signal that can be used to cancel the call.
+
+@returns
+A result object that contains the generated object, the finish reason, the token usage, and additional information.
  */
 declare function experimental_generateObject<T>({ model, schema, mode, system, prompt, messages, maxRetries, abortSignal, ...settings }: CallSettings & Prompt & {
+    /**
+The language model to use.
+     */
     model: LanguageModelV1;
+    /**
+The schema of the object that the model should generate.
+     */
     schema: z.Schema<T>;
+    /**
+The mode to use for object generation. Not all models support all modes.
+
+Default and recommended: 'auto' (best mode for the model).
+     */
     mode?: 'auto' | 'json' | 'tool' | 'grammar';
 }): Promise<GenerateObjectResult<T>>;
+/**
+The result of a `generateObject` call.
+ */
 declare class GenerateObjectResult<T> {
+    /**
+  The generated object (typed according to the schema).
+     */
     readonly object: T;
+    /**
+  The reason why the generation finished.
+     */
     readonly finishReason: LanguageModelV1FinishReason;
+    /**
+  The token usage of the generated text.
+     */
     readonly usage: TokenUsage;
+    /**
+  Warnings from the model provider (e.g. unsupported settings)
+     */
     readonly warnings: LanguageModelV1CallWarning[] | undefined;
     constructor(options: {
         object: T;
@@ -490,15 +631,67 @@ type PartialObject<ObjectType extends object> = {
 };
 
 /**
- * Stream an object as a partial object stream.
+Generate a structured, typed object for a given prompt and schema using a language model.
+
+This function streams the output. If you do not want to stream the output, use `experimental_generateObject` instead.
+
+@param model - The language model to use.
+
+@param schema - The schema of the object that the model should generate.
+@param mode - The mode to use for object generation. Not all models support all modes. Defaults to 'auto'.
+
+@param system - A system message that will be part of the prompt.
+@param prompt - A simple text prompt. You can either use `prompt` or `messages` but not both.
+@param messages - A list of messages. You can either use `prompt` or `messages` but not both.
+
+@param maxTokens - Maximum number of tokens to generate.
+@param temperature - Temperature setting.
+This is a number between 0 (almost no randomness) and 1 (very random).
+It is recommended to set either `temperature` or `topP`, but not both.
+@param topP - Nucleus sampling. This is a number between 0 and 1.
+E.g. 0.1 would mean that only tokens with the top 10% probability mass are considered.
+It is recommended to set either `temperature` or `topP`, but not both.
+@param presencePenalty - 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.
+@param frequencyPenalty - 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.
+@param seed - The seed (integer) to use for random sampling.
+If set and supported by the model, calls will generate deterministic results.
+
+@param maxRetries - Maximum number of retries. Set to 0 to disable retries. Default: 2.
+@param abortSignal - An optional abort signal that can be used to cancel the call.
+
+@return
+A result object for accessing the partial object stream and additional information.
  */
 declare function experimental_streamObject<T>({ model, schema, mode, system, prompt, messages, maxRetries, abortSignal, ...settings }: CallSettings & Prompt & {
+    /**
+The language model to use.
+     */
     model: LanguageModelV1;
+    /**
+The schema of the object that the model should generate.
+ */
     schema: z.Schema<T>;
+    /**
+The mode to use for object generation. Not all models support all modes.
+
+Default and recommended: 'auto' (best mode for the model).
+ */
     mode?: 'auto' | 'json' | 'tool' | 'grammar';
 }): Promise<StreamObjectResult<T>>;
+/**
+The result of a `streamObject` call that contains the partial object stream and additional information.
+ */
 declare class StreamObjectResult<T> {
     private readonly originalStream;
+    /**
+  Warnings from the model provider (e.g. unsupported settings)
+     */
     readonly warnings: LanguageModelV1CallWarning[] | undefined;
     constructor({ stream, warnings, }: {
         stream: ReadableStream<string | ErrorStreamPart>;
@@ -512,29 +705,29 @@ type ErrorStreamPart = {
 };
 
 /**
- * A tool contains the description and the schema of the input that the tool expects.
- * This enables the language model to generate the input.
- *
- * The tool can also contain an optional execute function for the actual execution function of the tool.
+A tool contains the description and the schema of the input that the tool expects.
+This enables the language model to generate the input.
+
+The tool can also contain an optional execute function for the actual execution function of the tool.
  */
 interface ExperimentalTool<PARAMETERS extends z.ZodTypeAny = any, RESULT = any> {
     /**
-     * A optional description of what the tool does. Will be used by the language model to decide whether to use the tool.
+  An optional description of what the tool does. Will be used by the language model to decide whether to use the tool.
      */
     description?: string;
     /**
-     * The schema of the input that the tool expects. The language model will use this to generate the input.
-     * Use descriptions to make the input understandable for the language model.
+  The schema of the input that the tool expects. The language model will use this to generate the input.
+  Use descriptions to make the input understandable for the language model.
      */
     parameters: PARAMETERS;
     /**
-     * An optional execute function for the actual execution function of the tool.
-     * If not provided, the tool will not be executed automatically.
+  An optional execute function for the actual execution function of the tool.
+  If not provided, the tool will not be executed automatically.
      */
     execute?: (args: z.infer<PARAMETERS>) => PromiseLike<RESULT>;
 }
 /**
- * Helper function for inferring the execute args of a tool.
+Helper function for inferring the execute args of a tool.
  */
 declare function tool<PARAMETERS extends z.ZodTypeAny, RESULT>(tool: ExperimentalTool<PARAMETERS, RESULT> & {
     execute: (args: z.infer<PARAMETERS>) => PromiseLike<RESULT>;
@@ -618,18 +811,79 @@ type ToToolResult<TOOLS extends Record<string, ExperimentalTool>> = ToToolResult
 type ToToolResultArray<TOOLS extends Record<string, ExperimentalTool>> = Array<ToToolResult<TOOLS>>;
 
 /**
- * Generate a text and call tools using a language model.
+Generate a text and call tools for a given prompt using a language model.
+
+This function does not stream the output. If you want to stream the output, use `experimental_streamText` instead.
+
+@param model - The language model to use.
+@param tools - The tools that the model can call. The model needs to support calling tools.
+
+@param system - A system message that will be part of the prompt.
+@param prompt - A simple text prompt. You can either use `prompt` or `messages` but not both.
+@param messages - A list of messages. You can either use `prompt` or `messages` but not both.
+
+@param maxTokens - Maximum number of tokens to generate.
+@param temperature - Temperature setting.
+This is a number between 0 (almost no randomness) and 1 (very random).
+It is recommended to set either `temperature` or `topP`, but not both.
+@param topP - Nucleus sampling. This is a number between 0 and 1.
+E.g. 0.1 would mean that only tokens with the top 10% probability mass are considered.
+It is recommended to set either `temperature` or `topP`, but not both.
+@param presencePenalty - 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.
+@param frequencyPenalty - 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.
+@param seed - The seed (integer) to use for random sampling.
+If set and supported by the model, calls will generate deterministic results.
+
+@param maxRetries - Maximum number of retries. Set to 0 to disable retries. Default: 2.
+@param abortSignal - An optional abort signal that can be used to cancel the call.
+
+@returns
+A result object that contains the generated text, the results of the tool calls, and additional information.
  */
 declare function experimental_generateText<TOOLS extends Record<string, ExperimentalTool>>({ model, tools, system, prompt, messages, maxRetries, abortSignal, ...settings }: CallSettings & Prompt & {
+    /**
+The language model to use.
+     */
     model: LanguageModelV1;
+    /**
+The tools that the model can call. The model needs to support calling tools.
+*/
     tools?: TOOLS;
 }): Promise<GenerateTextResult<TOOLS>>;
+/**
+The result of a `generateText` call.
+It contains the generated text, the tool calls that were made during the generation, and the results of the tool calls.
+ */
 declare class GenerateTextResult<TOOLS extends Record<string, ExperimentalTool>> {
+    /**
+  The generated text.
+     */
     readonly text: string;
+    /**
+  The tool calls that were made during the generation.
+     */
     readonly toolCalls: ToToolCallArray<TOOLS>;
+    /**
+  The results of the tool calls.
+     */
     readonly toolResults: ToToolResultArray<TOOLS>;
+    /**
+  The reason why the generation finished.
+     */
     readonly finishReason: LanguageModelV1FinishReason;
+    /**
+  The token usage of the generated text.
+     */
     readonly usage: TokenUsage;
+    /**
+  Warnings from the model provider (e.g. unsupported settings)
+     */
     readonly warnings: LanguageModelV1CallWarning[] | undefined;
     constructor(options: {
         text: string;
@@ -642,10 +896,49 @@ declare class GenerateTextResult<TOOLS extends Record<string, ExperimentalTool>>
 }
 
 /**
- * Stream text generated by a language model.
+Generate a text and call tools for a given prompt using a language model.
+
+This function streams the output. If you do not want to stream the output, use `experimental_generateText` instead.
+
+@param model - The language model to use.
+@param tools - The tools that the model can call. The model needs to support calling tools.
+
+@param system - A system message that will be part of the prompt.
+@param prompt - A simple text prompt. You can either use `prompt` or `messages` but not both.
+@param messages - A list of messages. You can either use `prompt` or `messages` but not both.
+
+@param maxTokens - Maximum number of tokens to generate.
+@param temperature - Temperature setting.
+This is a number between 0 (almost no randomness) and 1 (very random).
+It is recommended to set either `temperature` or `topP`, but not both.
+@param topP - Nucleus sampling. This is a number between 0 and 1.
+E.g. 0.1 would mean that only tokens with the top 10% probability mass are considered.
+It is recommended to set either `temperature` or `topP`, but not both.
+@param presencePenalty - 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.
+@param frequencyPenalty - 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.
+@param seed - The seed (integer) to use for random sampling.
+If set and supported by the model, calls will generate deterministic results.
+
+@param maxRetries - Maximum number of retries. Set to 0 to disable retries. Default: 2.
+@param abortSignal - An optional abort signal that can be used to cancel the call.
+
+@return
+A result object for accessing different stream types and additional information.
  */
 declare function experimental_streamText<TOOLS extends Record<string, ExperimentalTool>>({ model, tools, system, prompt, messages, maxRetries, abortSignal, ...settings }: CallSettings & Prompt & {
+    /**
+The language model to use.
+     */
     model: LanguageModelV1;
+    /**
+The tools that the model can call. The model needs to support calling tools.
+    */
     tools?: TOOLS;
 }): Promise<StreamTextResult<TOOLS>>;
 type TextStreamPart<TOOLS extends Record<string, ExperimentalTool>> = {
@@ -667,15 +960,41 @@ type TextStreamPart<TOOLS extends Record<string, ExperimentalTool>> = {
         totalTokens: number;
     };
 };
+/**
+A result object for accessing different stream types and additional information.
+ */
 declare class StreamTextResult<TOOLS extends Record<string, ExperimentalTool>> {
     private readonly originalStream;
+    /**
+  Warnings from the model provider (e.g. unsupported settings)
+     */
     readonly warnings: LanguageModelV1CallWarning[] | undefined;
     constructor({ stream, warnings, }: {
         stream: ReadableStream<TextStreamPart<TOOLS>>;
         warnings: LanguageModelV1CallWarning[] | undefined;
     });
+    /**
+  A text stream that returns only the generated text deltas. You can use it
+  as either an AsyncIterable or a ReadableStream. When an error occurs, the
+  stream will throw the error.
+     */
     get textStream(): AsyncIterableStream<string>;
+    /**
+  A stream with all events, including text deltas, tool calls, tool results, and
+  errors.
+  You can use it as either an AsyncIterable or a ReadableStream. When an error occurs, the
+  stream will throw the error.
+     */
     get fullStream(): AsyncIterableStream<TextStreamPart<TOOLS>>;
+    /**
+  Converts the result to an `AIStream` object that is compatible with `StreamingTextResponse`.
+  It can be used with the `useChat` and `useCompletion` hooks.
+  
+  @param callbacks
+  Stream callbacks that will be called when the stream emits events.
+  
+  @returns an `AIStream` object.
+     */
     toAIStream(callbacks?: AIStreamCallbacksAndOptions): ReadableStream<any>;
 }