ai 6.0.31 → 6.0.33

package/docs/07-reference/01-ai-sdk-core/30-model-message.mdx

@@ -0,0 +1,415 @@
+---
+title: ModelMessage
+description: Message types for AI SDK Core (API Reference)
+---
+
+# `ModelMessage`
+
+`ModelMessage` represents the fundamental message structure used with AI SDK Core functions.
+It encompasses various message types that can be used in the `messages` field of any AI SDK Core functions.
+
+You can access the Zod schema for `ModelMessage` with the `modelMessageSchema` export.
+
+## `ModelMessage` Types
+
+### `SystemModelMessage`
+
+A system message that can contain system information.
+
+```typescript
+type SystemModelMessage = {
+  role: 'system';
+  content: string;
+};
+```
+
+You can access the Zod schema for `SystemModelMessage` with the `systemModelMessageSchema` export.
+
+<Note>
+  Using the "system" property instead of a system message is recommended to
+  enhance resilience against prompt injection attacks.
+</Note>
+
+### `UserModelMessage`
+
+A user message that can contain text or a combination of text, images, and files.
+
+```typescript
+type UserModelMessage = {
+  role: 'user';
+  content: UserContent;
+};
+
+type UserContent = string | Array<TextPart | ImagePart | FilePart>;
+```
+
+You can access the Zod schema for `UserModelMessage` with the `userModelMessageSchema` export.
+
+### `AssistantModelMessage`
+
+An assistant message that can contain text, tool calls, or a combination of both.
+
+```typescript
+type AssistantModelMessage = {
+  role: 'assistant';
+  content: AssistantContent;
+};
+
+type AssistantContent = string | Array<TextPart | ToolCallPart>;
+```
+
+You can access the Zod schema for `AssistantModelMessage` with the `assistantModelMessageSchema` export.
+
+### `ToolModelMessage`
+
+A tool message that contains the result of one or more tool calls.
+
+```typescript
+type ToolModelMessage = {
+  role: 'tool';
+  content: ToolContent;
+};
+
+type ToolContent = Array<ToolResultPart>;
+```
+
+You can access the Zod schema for `ToolModelMessage` with the `toolModelMessageSchema` export.
+
+## `ModelMessage` Parts
+
+### `TextPart`
+
+Represents a text content part of a prompt. It contains a string of text.
+
+```typescript
+export interface TextPart {
+  type: 'text';
+  /**
+   * The text content.
+   */
+  text: string;
+}
+```
+
+### `ImagePart`
+
+Represents an image part in a user message.
+
+```typescript
+export 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: DataContent | URL;
+
+  /**
+   * Optional IANA media type of the image.
+   * We recommend leaving this out as it will be detected automatically.
+   */
+  mediaType?: string;
+}
+```
+
+### `FilePart`
+
+Represents an file part in a user message.
+
+```typescript
+export interface FilePart {
+  type: 'file';
+
+  /**
+   * File data. Can either be:
+   * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
+   * - URL: a URL that points to the file
+   */
+  data: DataContent | URL;
+
+  /**
+   * Optional filename of the file.
+   */
+  filename?: string;
+
+  /**
+   * IANA media type of the file.
+   */
+  mediaType: string;
+}
+```
+
+### `ToolCallPart`
+
+Represents a tool call content part of a prompt, typically generated by the AI model.
+
+```typescript
+export 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;
+}
+```
+
+### `ToolResultPart`
+
+Represents the result of a tool call in a tool message.
+
+```typescript
+export 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.
+   */
+  output: LanguageModelV3ToolResultOutput;
+
+  /**
+  Additional provider-specific metadata. 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?: ProviderOptions;
+}
+```
+
+### `LanguageModelV3ToolResultOutput`
+
+```ts
+/**
+ * Output of a tool result.
+ */
+export type ToolResultOutput =
+  | {
+      /**
+       * Text tool output that should be directly sent to the API.
+       */
+      type: 'text';
+      value: string;
+
+      /**
+       * Provider-specific options.
+       */
+      providerOptions?: ProviderOptions;
+    }
+  | {
+      type: 'json';
+      value: JSONValue;
+
+      /**
+       * Provider-specific options.
+       */
+      providerOptions?: ProviderOptions;
+    }
+  | {
+      /**
+       * Type when the user has denied the execution of the tool call.
+       */
+      type: 'execution-denied';
+
+      /**
+       * Optional reason for the execution denial.
+       */
+      reason?: string;
+
+      /**
+       * Provider-specific options.
+       */
+      providerOptions?: ProviderOptions;
+    }
+  | {
+      type: 'error-text';
+      value: string;
+
+      /**
+       * Provider-specific options.
+       */
+      providerOptions?: ProviderOptions;
+    }
+  | {
+      type: 'error-json';
+      value: JSONValue;
+
+      /**
+       * Provider-specific options.
+       */
+      providerOptions?: ProviderOptions;
+    }
+  | {
+      type: 'content';
+      value: Array<
+        | {
+            type: 'text';
+
+            /**
+Text content.
+*/
+            text: string;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: ProviderOptions;
+          }
+        | {
+            /**
+             * @deprecated Use image-data or file-data instead.
+             */
+            type: 'media';
+            data: string;
+            mediaType: string;
+          }
+        | {
+            type: 'file-data';
+
+            /**
+Base-64 encoded media data.
+*/
+            data: string;
+
+            /**
+IANA media type.
+@see https://www.iana.org/assignments/media-types/media-types.xhtml
+*/
+            mediaType: string;
+
+            /**
+             * Optional filename of the file.
+             */
+            filename?: string;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: ProviderOptions;
+          }
+        | {
+            type: 'file-url';
+
+            /**
+             * URL of the file.
+             */
+            url: string;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: ProviderOptions;
+          }
+        | {
+            type: 'file-id';
+
+            /**
+             * ID of the file.
+             *
+             * If you use multiple providers, you need to
+             * specify the provider specific ids using
+             * the Record option. The key is the provider
+             * name, e.g. 'openai' or 'anthropic'.
+             */
+            fileId: string | Record<string, string>;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: ProviderOptions;
+          }
+        | {
+            /**
+             * Images that are referenced using base64 encoded data.
+             */
+            type: 'image-data';
+
+            /**
+Base-64 encoded image data.
+*/
+            data: string;
+
+            /**
+IANA media type.
+@see https://www.iana.org/assignments/media-types/media-types.xhtml
+*/
+            mediaType: string;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: ProviderOptions;
+          }
+        | {
+            /**
+             * Images that are referenced using a URL.
+             */
+            type: 'image-url';
+
+            /**
+             * URL of the image.
+             */
+            url: string;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: ProviderOptions;
+          }
+        | {
+            /**
+             * Images that are referenced using a provider file id.
+             */
+            type: 'image-file-id';
+
+            /**
+             * Image that is referenced using a provider file id.
+             *
+             * If you use multiple providers, you need to
+             * specify the provider specific ids using
+             * the Record option. The key is the provider
+             * name, e.g. 'openai' or 'anthropic'.
+             */
+            fileId: string | Record<string, string>;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: ProviderOptions;
+          }
+        | {
+            /**
+             * Custom content part. This can be used to implement
+             * provider-specific content parts.
+             */
+            type: 'custom';
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: ProviderOptions;
+          }
+      >;
+    };
+```

package/docs/07-reference/01-ai-sdk-core/31-ui-message.mdx

@@ -0,0 +1,246 @@
+---
+title: UIMessage
+description: API Reference for UIMessage
+---
+
+# `UIMessage`
+
+`UIMessage` serves as the source of truth for your application's state, representing the complete message history including metadata, data parts, and all contextual information. In contrast to `ModelMessage`, which represents the state or context passed to the model, `UIMessage` contains the full application state needed for UI rendering and client-side functionality.
+
+## Type Safety
+
+`UIMessage` is designed to be type-safe and accepts three generic parameters to ensure proper typing throughout your application:
+
+1. **`METADATA`** - Custom metadata type for additional message information
+2. **`DATA_PARTS`** - Custom data part types for structured data components
+3. **`TOOLS`** - Tool definitions for type-safe tool interactions
+
+## Creating Your Own UIMessage Type
+
+Here's an example of how to create a custom typed UIMessage for your application:
+
+```typescript
+import { InferUITools, ToolSet, UIMessage, tool } from 'ai';
+import z from 'zod';
+
+const metadataSchema = z.object({
+  someMetadata: z.string().datetime(),
+});
+
+type MyMetadata = z.infer<typeof metadataSchema>;
+
+const dataPartSchema = z.object({
+  someDataPart: z.object({}),
+  anotherDataPart: z.object({}),
+});
+
+type MyDataPart = z.infer<typeof dataPartSchema>;
+
+const tools = {
+  someTool: tool({}),
+} satisfies ToolSet;
+
+type MyTools = InferUITools<typeof tools>;
+
+export type MyUIMessage = UIMessage<MyMetadata, MyDataPart, MyTools>;
+```
+
+## `UIMessage` Interface
+
+```typescript
+interface UIMessage<
+  METADATA = unknown,
+  DATA_PARTS extends UIDataTypes = UIDataTypes,
+  TOOLS extends UITools = UITools,
+> {
+  /**
+   * A unique identifier for the message.
+   */
+  id: string;
+
+  /**
+   * The role of the message.
+   */
+  role: 'system' | 'user' | 'assistant';
+
+  /**
+   * The metadata of the message.
+   */
+  metadata?: METADATA;
+
+  /**
+   * The parts of the message. Use this for rendering the message in the UI.
+   */
+  parts: Array<UIMessagePart<DATA_PARTS, TOOLS>>;
+}
+```
+
+## `UIMessagePart` Types
+
+### `TextUIPart`
+
+A text part of a message.
+
+```typescript
+type TextUIPart = {
+  type: 'text';
+  /**
+   * The text content.
+   */
+  text: string;
+  /**
+   * The state of the text part.
+   */
+  state?: 'streaming' | 'done';
+};
+```
+
+### `ReasoningUIPart`
+
+A reasoning part of a message.
+
+```typescript
+type ReasoningUIPart = {
+  type: 'reasoning';
+  /**
+   * The reasoning text.
+   */
+  text: string;
+  /**
+   * The state of the reasoning part.
+   */
+  state?: 'streaming' | 'done';
+  /**
+   * The provider metadata.
+   */
+  providerMetadata?: Record<string, any>;
+};
+```
+
+### `ToolUIPart`
+
+A tool part of a message that represents tool invocations and their results.
+
+<Note>
+  The type is based on the name of the tool (e.g., `tool-someTool` for a tool
+  named `someTool`).
+</Note>
+
+```typescript
+type ToolUIPart<TOOLS extends UITools = UITools> = ValueOf<{
+  [NAME in keyof TOOLS & string]: {
+    type: `tool-${NAME}`;
+    toolCallId: string;
+  } & (
+    | {
+        state: 'input-streaming';
+        input: DeepPartial<TOOLS[NAME]['input']> | undefined;
+        providerExecuted?: boolean;
+        output?: never;
+        errorText?: never;
+      }
+    | {
+        state: 'input-available';
+        input: TOOLS[NAME]['input'];
+        providerExecuted?: boolean;
+        output?: never;
+        errorText?: never;
+      }
+    | {
+        state: 'output-available';
+        input: TOOLS[NAME]['input'];
+        output: TOOLS[NAME]['output'];
+        errorText?: never;
+        providerExecuted?: boolean;
+      }
+    | {
+        state: 'output-error';
+        input: TOOLS[NAME]['input'];
+        output?: never;
+        errorText: string;
+        providerExecuted?: boolean;
+      }
+  );
+}>;
+```
+
+### `SourceUrlUIPart`
+
+A source URL part of a message.
+
+```typescript
+type SourceUrlUIPart = {
+  type: 'source-url';
+  sourceId: string;
+  url: string;
+  title?: string;
+  providerMetadata?: Record<string, any>;
+};
+```
+
+### `SourceDocumentUIPart`
+
+A document source part of a message.
+
+```typescript
+type SourceDocumentUIPart = {
+  type: 'source-document';
+  sourceId: string;
+  mediaType: string;
+  title: string;
+  filename?: string;
+  providerMetadata?: Record<string, any>;
+};
+```
+
+### `FileUIPart`
+
+A file part of a message.
+
+```typescript
+type FileUIPart = {
+  type: 'file';
+  /**
+   * IANA media type of the file.
+   */
+  mediaType: string;
+  /**
+   * Optional filename of the file.
+   */
+  filename?: string;
+  /**
+   * The URL of the file.
+   * It can either be a URL to a hosted file or a Data URL.
+   */
+  url: string;
+};
+```
+
+### `DataUIPart`
+
+A data part of a message for custom data types.
+
+<Note>
+  The type is based on the name of the data part (e.g., `data-someDataPart` for
+  a data part named `someDataPart`).
+</Note>
+
+```typescript
+type DataUIPart<DATA_TYPES extends UIDataTypes> = ValueOf<{
+  [NAME in keyof DATA_TYPES & string]: {
+    type: `data-${NAME}`;
+    id?: string;
+    data: DATA_TYPES[NAME];
+  };
+}>;
+```
+
+### `StepStartUIPart`
+
+A step boundary part of a message.
+
+```typescript
+type StepStartUIPart = {
+  type: 'step-start';
+};
+```