ai 3.0.8 → 3.1.0-canary.0

package/README.md

@@ -4,11 +4,11 @@ The Vercel AI SDK is **a library for building AI-powered streaming text and chat
 
 ## Features
 
-- React Server Components API for streaming Generative UI
-- [SWR](https://swr.vercel.app)-powered React, Svelte, Vue and Solid helpers for streaming text responses and building chat and completion UIs
-- First-class support for [LangChain](https://js.langchain.com/docs) and [OpenAI](https://openai.com), [Anthropic](https://www.anthropic.com), [Cohere](https://cohere.com), [Hugging Face](https://huggingface.co), [Fireworks](https://app.fireworks.ai) and [Replicate](https://replicate.com)
+- React, Svelte, Vue and Solid helpers for streaming text responses and building chat and completion UIs
+- React Server Components API for streaming [Generative UI](https://vercel.com/blog/ai-sdk-3-generative-ui)
+- First-class support for [OpenAI](https://openai.com), [Anthropic](https://www.anthropic.com), [Mistral](https://mistral.ai), [Perplexity](https://perplexity.ai), [AWS Bedrock](https://aws.amazon.com/bedrock/), [Azure](https://ai.azure.com), [Google Gemini](https://ai.google.dev), [Hugging Face](https://huggingface.co), [Fireworks](https://app.fireworks.ai), [Cohere](https://cohere.com), [LangChain](https://js.langchain.com/docs), [Replicate](https://replicate.com), Ollama, and more.
 - Node.js, Serverless, and [Edge Runtime](https://edge-runtime.vercel.app/) support
-- Callbacks for saving completed streaming responses to a database (in the same request)
+- Lifecycle callbacks for saving completed streaming responses to a database (in the same request)
 
 ## Installation
 
@@ -29,3 +29,9 @@ This library is created by [Vercel](https://vercel.com) and [Next.js](https://ne
 - Justin Ridgewell ([@jridgewell](https://github.com/jridgewell)) - [Vercel](https://vercel.com)
 
 [Contributors](https://github.com/vercel/ai/graphs/contributors)
+
+## Related: Deploy your own Next.js AI Chatbot
+
+If you're looking to for a full AI Chatbot application to jumpstart your AI journey, you should checkout [our sister OSS AI Chatbot project](https://github.com/vercel/ai-chatbot) or click the button below to deploy your own to [Vercel](https://vercel.com).
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/templates/Next.js/nextjs-ai-chatbot)

package/core/dist/index.d.mts

@@ -0,0 +1,480 @@
+import { z } from 'zod';
+import { PartialDeep, ValueOf } from 'type-fest';
+
+type LanguageModelV1CallSettings = {
+    /**
+     * Maximum number of tokens to generate.
+     */
+    maxTokens?: number;
+    /**
+     * Temperature setting. This is a number between 0 (almost no randomness) and
+     * 1 (very random).
+     *
+     * Different LLM providers have different temperature
+     * scales, so they'd need to map it (without mapping, the same temperature has
+     * different effects on different models). The provider can also chose to map
+     * this to topP, potentially even using a custom setting on their model.
+     *
+     * Note: This is an example of a setting that requires a clear specification of
+     * the semantics.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    frequencyPenalty?: number;
+    /**
+     * The seed to use for random sampling. If set and supported by the model,
+     * calls will generate deterministic results.
+     */
+    seed?: number;
+};
+
+/**
+ * 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.
+ *
+ * Note: this is **not** the user-facing tool definition. The AI SDK methods will
+ * map the user-facing tool definitions to this format.
+ */
+type LanguageModelV1FunctionTool = {
+    /**
+     * The type of the tool. Only functions for now, but this gives us room to
+     * add more specific tool types in the future and use a discriminated union.
+     */
+    type: 'function';
+    /**
+     * The name of the tool. Unique within this model call.
+     */
+    name: string;
+    description?: string;
+    parameters: JsonSchema;
+};
+
+/**
+ * A prompt is a list of messages.
+ *
+ * Note: Not all models and prompt formats support multi-modal inputs and
+ * tool calls. The validation happens at runtime.
+ *
+ * Note: This is not a user-facing prompt. The AI SDK methods will map the
+ * user-facing prompt types such as chat or instruction prompts to this format.
+ */
+type LanguageModelV1Prompt = Array<LanguageModelV1Message>;
+type LanguageModelV1Message = {
+    role: 'system';
+    content: string;
+} | {
+    role: 'user';
+    content: Array<LanguageModelV1TextPart | LanguageModelV1ImagePart>;
+} | {
+    role: 'assistant';
+    content: Array<LanguageModelV1TextPart | LanguageModelV1ToolCallPart>;
+} | {
+    role: 'tool';
+    content: Array<LanguageModelV1ToolResultPart>;
+};
+interface LanguageModelV1TextPart {
+    type: 'text';
+    /**
+     * The text content.
+     */
+    text: string;
+}
+interface LanguageModelV1ImagePart {
+    type: 'image';
+    /**
+     * Image data as a Uint8Array.
+     */
+    image: Uint8Array;
+    /**
+     * Optional mime type of the image.
+     */
+    mimeType?: string;
+}
+interface LanguageModelV1ToolCallPart {
+    type: 'tool-call';
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+}
+interface LanguageModelV1ToolResultPart {
+    type: 'tool-result';
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+}
+
+type LanguageModelV1CallOptions = LanguageModelV1CallSettings & {
+    /**
+     * Whether the user provided the input as messages or as
+     * a prompt. This can help guide non-chat models in the
+     * expansion, bc different expansions can be needed for
+     * chat/non-chat use cases.
+     */
+    inputFormat: 'messages' | 'prompt';
+    /**
+     * The mode affects the behavior of the language model. It is required to
+     * support provider-independent streaming and generation of structured objects.
+     * The model can take this information and e.g. configure json mode, the correct
+     * low level grammar, etc. It can also be used to optimize the efficiency of the
+     * streaming, e.g. tool-delta stream parts are only needed in the
+     * object-tool mode.
+     */
+    mode: {
+        type: 'regular';
+        tools?: Array<LanguageModelV1FunctionTool>;
+    } | {
+        type: 'object-json';
+    } | {
+        type: 'object-grammar';
+        schema: JsonSchema;
+    } | {
+        type: 'object-tool';
+        tool: LanguageModelV1FunctionTool;
+    };
+    /**
+     * 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: LanguageModelV1Prompt;
+};
+
+interface LanguageModel {
+    /**
+     * 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
+     * model. `undefined` can be returned if object generation is not supported.
+     *
+     * This is needed to generate the best objects possible w/o requiring the
+     * user to explicitly specify the object generation mode.
+     */
+    readonly defaultObjectGenerationMode: 'json' | 'tool' | 'grammar' | undefined;
+    doGenerate(options: LanguageModelV1CallOptions): PromiseLike<{
+        text?: string;
+        toolCalls?: Array<LanguageModelToolCall>;
+        warnings: LanguageModelV1CallWarning[];
+    }>;
+    doStream(options: LanguageModelV1CallOptions): PromiseLike<{
+        stream: ReadableStream<LanguageModelStreamPart>;
+        warnings: LanguageModelV1CallWarning[];
+    }>;
+}
+type ErrorStreamPart = {
+    type: 'error';
+    error: unknown;
+};
+type LanguageModelToolCall = {
+    toolCallId: string;
+    toolName: string;
+    args: string;
+};
+type ToolCallStreamPart = {
+    type: 'tool-call';
+} & LanguageModelToolCall;
+type ToolCallDeltaStreamPart = {
+    type: 'tool-call-delta';
+    toolCallId: string;
+    toolName: string;
+    argsTextDelta: string;
+};
+type TextDeltaStreamPart = {
+    type: 'text-delta';
+    textDelta: string;
+};
+type LanguageModelStreamPart = TextDeltaStreamPart | ToolCallDeltaStreamPart | ToolCallStreamPart | ErrorStreamPart;
+
+type CallSettings = {
+    /**
+     * 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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    frequencyPenalty?: number;
+    /**
+     * The seed to use for random sampling. If set and supported by the model,
+     * calls will generate deterministic results.
+     */
+    seed?: number;
+};
+
+/**
+ * Data content. Can either be a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer.
+ */
+type DataContent = string | Uint8Array | ArrayBuffer | Buffer;
+declare function convertDataContentToBase64String(content: DataContent): string;
+declare function convertDataContentToUint8Array(content: DataContent): Uint8Array;
+
+interface TextPart {
+    type: 'text';
+    /**
+     * The text content.
+     */
+    text: string;
+}
+interface ImagePart {
+    type: 'image';
+    /**
+     * Image data. Can either be a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer.
+     */
+    image: DataContent;
+    /**
+     * Optional mime type of the image.
+     */
+    mimeType?: string;
+}
+interface ToolCallPart {
+    type: 'tool-call';
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+}
+interface ToolResultPart {
+    type: 'tool-result';
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+}
+
+type Message = UserMessage | AssistantMessage | ToolMessage;
+type UserMessage = {
+    role: 'user';
+    content: UserContent;
+};
+type AssistantMessage = {
+    role: 'assistant';
+    content: AssistantContent;
+};
+type ToolMessage = {
+    role: 'tool';
+    content: ToolContent;
+};
+type UserContent = string | Array<TextPart | ImagePart>;
+type AssistantContent = string | Array<TextPart | ToolCallPart>;
+type ToolContent = Array<ToolResultPart>;
+
+type Prompt = {
+    system?: string;
+    prompt?: string;
+    messages?: Array<Message>;
+};
+
+/**
+ * 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;
+    schema: z.Schema<T>;
+    mode?: 'json' | 'tool' | 'grammar';
+}): Promise<GenerateObjectResult<T>>;
+declare class GenerateObjectResult<T> {
+    readonly object: T;
+    constructor(options: {
+        object: T;
+    });
+}
+
+/**
+ * Stream an object as a partial object stream.
+ */
+declare function streamObject<T>({ model, schema: zodSchema, mode, system, prompt, messages, ...settings }: CallSettings & Prompt & {
+    model: LanguageModel;
+    schema: z.Schema<T>;
+    mode?: 'json' | 'tool' | 'grammar';
+}): Promise<StreamObjectResult<T>>;
+declare class StreamObjectResult<T> {
+    readonly objectStream: AsyncIterable<PartialDeep<T, {
+        recurseIntoArrays: true;
+    }>>;
+    constructor(modelStream: ReadableStream<string | 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.
+ */
+interface Tool<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.
+     */
+    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.
+     */
+    parameters: PARAMETERS;
+    /**
+     * 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.
+ */
+declare function tool<PARAMETERS extends z.ZodTypeAny, RESULT>(tool: Tool<PARAMETERS, RESULT> & {
+    execute: (args: z.infer<PARAMETERS>) => PromiseLike<RESULT>;
+}): Tool<PARAMETERS, RESULT> & {
+    execute: (args: z.infer<PARAMETERS>) => PromiseLike<RESULT>;
+};
+declare function tool<PARAMETERS extends z.ZodTypeAny, RESULT>(tool: Tool<PARAMETERS, RESULT> & {
+    execute?: undefined;
+}): Tool<PARAMETERS, RESULT> & {
+    execute: undefined;
+};
+
+type ToToolCall<TOOLS extends Record<string, Tool>> = ValueOf<{
+    [NAME in keyof TOOLS]: {
+        toolCallId: string;
+        toolName: NAME & string;
+        args: z.infer<TOOLS[NAME]['parameters']>;
+    };
+}>;
+type ToToolCallArray<TOOLS extends Record<string, Tool>> = Array<ToToolCall<TOOLS>>;
+
+type ToToolsWithExecute<TOOLS extends Record<string, Tool>> = {
+    [K in keyof TOOLS as TOOLS[K] extends {
+        execute: any;
+    } ? K : never]: TOOLS[K];
+};
+type ToToolsWithDefinedExecute<TOOLS extends Record<string, Tool>> = {
+    [K in keyof TOOLS as TOOLS[K]['execute'] extends undefined ? never : K]: TOOLS[K];
+};
+type ToToolResultObject<TOOLS extends Record<string, Tool>> = ValueOf<{
+    [NAME in keyof TOOLS]: {
+        toolCallId: string;
+        toolName: NAME & string;
+        args: z.infer<TOOLS[NAME]['parameters']>;
+        result: Awaited<ReturnType<Exclude<TOOLS[NAME]['execute'], undefined>>>;
+    };
+}>;
+type ToToolResult<TOOLS extends Record<string, Tool>> = ToToolResultObject<ToToolsWithDefinedExecute<ToToolsWithExecute<TOOLS>>>;
+type ToToolResultArray<TOOLS extends Record<string, Tool>> = Array<ToToolResult<TOOLS>>;
+
+/**
+ * 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;
+    tools?: TOOLS;
+}): Promise<GenerateTextResult<TOOLS>>;
+declare class GenerateTextResult<TOOLS extends Record<string, Tool>> {
+    readonly text: string;
+    readonly toolCalls: ToToolCallArray<TOOLS>;
+    readonly toolResults: ToToolResultArray<TOOLS>;
+    constructor(options: {
+        text: string;
+        toolCalls: ToToolCallArray<TOOLS>;
+        toolResults: ToToolResultArray<TOOLS>;
+    });
+}
+
+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;
+    tools?: TOOLS;
+}): Promise<StreamTextResult<TOOLS>>;
+type TextStreamPart<TOOLS extends Record<string, Tool>> = {
+    type: 'text-delta';
+    textDelta: string;
+} | ({
+    type: 'tool-call';
+} & ToToolCall<TOOLS>) | {
+    type: 'error';
+    error: unknown;
+} | ({
+    type: 'tool-result';
+} & ToToolResult<TOOLS>);
+declare class StreamTextResult<TOOLS extends Record<string, Tool>> {
+    private readonly rootStream;
+    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 };