ai 6.0.31 → 6.0.33

package/docs/07-reference/02-ai-sdk-ui/03-use-object.mdx

@@ -0,0 +1,178 @@
+---
+title: useObject
+description: API reference for the useObject hook.
+---
+
+# `experimental_useObject()`
+
+<Note>
+  `useObject` is an experimental feature and only available in React, Svelte,
+  and Vue.
+</Note>
+
+Allows you to consume text streams that represent a JSON object and parse them into a complete object based on a schema.
+You can use it together with [`streamText`](/docs/reference/ai-sdk-core/stream-text) and [`Output.object()`](/docs/reference/ai-sdk-core/output#output-object) in the backend.
+
+```tsx
+'use client';
+
+import { experimental_useObject as useObject } from '@ai-sdk/react';
+
+export default function Page() {
+  const { object, submit } = useObject({
+    api: '/api/use-object',
+    schema: z.object({ content: z.string() }),
+  });
+
+  return (
+    <div>
+      <button onClick={() => submit('example input')}>Generate</button>
+      {object?.content && <p>{object.content}</p>}
+    </div>
+  );
+}
+```
+
+## Import
+
+<Snippet
+  text="import { experimental_useObject as useObject } from '@ai-sdk/react'"
+  dark
+  prompt={false}
+/>
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'api',
+      type: 'string',
+      description:
+        'The API endpoint that is called to generate objects. It should stream JSON that matches the schema as chunked text. It can be a relative path (starting with `/`) or an absolute URL.',
+    },
+    {
+      name: 'schema',
+      type: 'Zod Schema | JSON Schema',
+      description:
+        'A schema that defines the shape of the complete object. You can either pass in a Zod schema or a JSON schema (using the `jsonSchema` function).',
+    },
+    {
+      name: 'id?',
+      type: 'string',
+      description:
+        'A unique identifier. If not provided, a random one will be generated. When provided, the `useObject` hook with the same `id` will have shared states across components.',
+    },
+    {
+      name: 'initialValue',
+      type: 'DeepPartial<RESULT> | undefined',
+      isOptional: true,
+      description: 'An value for the initial object. Optional.',
+    },
+    {
+      name: 'fetch',
+      type: 'FetchFunction',
+      isOptional: true,
+      description:
+        'A custom fetch function to be used for the API call. Defaults to the global fetch function. Optional.',
+    },
+    {
+      name: 'headers',
+      type: 'Record<string, string> | Headers',
+      isOptional: true,
+      description:
+        'A headers object to be passed to the API endpoint. Optional.',
+    },
+    {
+      name: 'credentials',
+      type: 'RequestCredentials',
+      isOptional: true,
+      description:
+        'The credentials mode to be used for the fetch request. Possible values are: "omit", "same-origin", "include". Optional.',
+    },
+    {
+      name: 'onError',
+      type: '(error: Error) => void',
+      isOptional: true,
+      description:
+        'Callback function to be called when an error is encountered. Optional.',
+    },
+    {
+      name: 'onFinish',
+      type: '(result: OnFinishResult) => void',
+      isOptional: true,
+      description: 'Called when the streaming response has finished.',
+      properties: [
+        {
+          type: 'OnFinishResult',
+          parameters: [
+            {
+              name: 'object',
+              type: 'T | undefined',
+              description:
+                'The generated object (typed according to the schema). Can be undefined if the final object does not match the schema.',
+            },
+            {
+              name: 'error',
+              type: 'unknown | undefined',
+              description:
+                'Optional error object. This is e.g. a TypeValidationError when the final object does not match the schema.',
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: 'submit',
+      type: '(input: INPUT) => void',
+      description: 'Calls the API with the provided input as JSON body.',
+    },
+    {
+      name: 'object',
+      type: 'DeepPartial<RESULT> | undefined',
+      description:
+        'The current value for the generated object. Updated as the API streams JSON chunks.',
+    },
+    {
+      name: 'error',
+      type: 'Error | unknown',
+      description: 'The error object if the API call fails.',
+    },
+    {
+      name: 'isLoading',
+      type: 'boolean',
+      description:
+        'Boolean flag indicating whether a request is currently in progress.',
+    },
+    {
+      name: 'stop',
+      type: '() => void',
+      description: 'Function to abort the current API request.',
+    },
+    {
+      name: 'clear',
+      type: '() => void',
+      description: 'Function to clear the object state.',
+    },
+  ]}
+/>
+
+## Examples
+
+<ExampleLinks
+  examples={[
+    {
+      title: 'Streaming Object Generation with useObject',
+      link: '/examples/next-pages/basics/streaming-object-generation',
+    },
+  ]}
+/>

package/docs/07-reference/02-ai-sdk-ui/31-convert-to-model-messages.mdx

@@ -0,0 +1,230 @@
+---
+title: convertToModelMessages
+description: Convert useChat messages to ModelMessages for AI functions (API Reference)
+---
+
+# `convertToModelMessages()`
+
+The `convertToModelMessages` function is used to transform an array of UI messages from the `useChat` hook into an array of `ModelMessage` objects. These `ModelMessage` objects are compatible with AI core functions like `streamText`.
+
+```ts filename="app/api/chat/route.ts"
+import { convertToModelMessages, streamText } from 'ai';
+__PROVIDER_IMPORT__;
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: __MODEL__,
+    messages: await convertToModelMessages(messages),
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+## Import
+
+<Snippet text={`import { convertToModelMessages } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'messages',
+      type: 'Message[]',
+      description:
+        'An array of UI messages from the useChat hook to be converted',
+    },
+    {
+      name: 'options',
+      type: '{ tools?: ToolSet, convertDataPart?: (part: DataUIPart) => TextPart | FilePart | null }',
+      description:
+        'Optional configuration object. Provide tools to enable multi-modal tool responses, and convertDataPart to transform custom data parts into model-compatible content.',
+    },
+  ]}
+/>
+
+### Returns
+
+An array of [`ModelMessage`](/docs/reference/ai-sdk-core/model-message) objects.
+
+<PropertiesTable
+  content={[
+    {
+      name: 'ModelMessage[]',
+      type: 'Array',
+      description: 'An array of ModelMessage objects',
+    },
+  ]}
+/>
+
+## Multi-modal Tool Responses
+
+The `convertToModelMessages` function supports tools that can return multi-modal content. This is useful when tools need to return non-text content like images.
+
+```ts
+import { tool } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+const screenshotTool = tool({
+  inputSchema: z.object({}),
+  execute: async () => 'imgbase64',
+  toModelOutput: ({ output }) => [{ type: 'image', data: output }],
+});
+
+const result = streamText({
+  model: __MODEL__,
+  messages: convertToModelMessages(messages, {
+    tools: {
+      screenshot: screenshotTool,
+    },
+  }),
+});
+```
+
+Tools can implement the optional `toModelOutput` method to transform their results into multi-modal content. The content is an array of content parts, where each part has a `type` (e.g., 'text', 'image') and corresponding data.
+
+## Custom Data Part Conversion
+
+The `convertToModelMessages` function supports converting custom data parts attached to user messages. This is useful when users need to include additional context (URLs, code files, JSON configs) with their messages.
+
+### Basic Usage
+
+By default, data parts in user messages are filtered out during conversion. To include them, provide a `convertDataPart` callback that transforms data parts into text or file parts that the model can understand:
+
+```ts filename="app/api/chat/route.ts"
+import { convertToModelMessages, streamText } from 'ai';
+
+type CustomUIMessage = UIMessage<
+  never,
+  {
+    url: { url: string; title: string; content: string };
+    'code-file': { filename: string; code: string; language: string };
+  }
+>;
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: __MODEL__,
+    messages: convertToModelMessages<CustomUIMessage>(messages, {
+      convertDataPart: part => {
+        // Convert URL attachments to text
+        if (part.type === 'data-url') {
+          return {
+            type: 'text',
+            text: `[Reference: ${part.data.title}](${part.data.url})\n\n${part.data.content}`,
+          };
+        }
+
+        // Convert code file attachments
+        if (part.type === 'data-code-file') {
+          return {
+            type: 'text',
+            text: `\`\`\`${part.data.language}\n// ${part.data.filename}\n${part.data.code}\n\`\`\``,
+          };
+        }
+
+        // Other data parts are ignored
+      },
+    }),
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+### Use Cases
+
+**Attaching URL Content**
+Allow users to attach URLs to their messages, with the content fetched and formatted for the model:
+
+```ts
+// Client side
+sendMessage({
+  parts: [
+    { type: 'text', text: 'Analyze this article' },
+    {
+      type: 'data-url',
+      data: {
+        url: 'https://example.com/article',
+        title: 'Important Article',
+        content: '...',
+      },
+    },
+  ],
+});
+```
+
+**Including Code Files as Context**
+Let users reference code files in their conversations:
+
+```ts
+convertDataPart: part => {
+  if (part.type === 'data-code-file') {
+    return {
+      type: 'text',
+      text: `\`\`\`${part.data.language}\n${part.data.code}\n\`\`\``,
+    };
+  }
+};
+```
+
+**Selective Inclusion**
+Only data parts for which you return a text or file model message part are included,
+all other data parts are ignored.
+
+```ts
+const result = convertToModelMessages<
+  UIMessage<
+    unknown,
+    {
+      url: { url: string; title: string };
+      code: { code: string; language: string };
+      note: { text: string };
+    }
+  >
+>(messages, {
+  convertDataPart: part => {
+    if (part.type === 'data-url') {
+      return {
+        type: 'text',
+        text: `[${part.data.title}](${part.data.url})`,
+      };
+    }
+
+    // data-code and data-node are ignored
+  },
+});
+```
+
+### Type Safety
+
+The generic parameter ensures full type safety for your custom data parts:
+
+```ts
+type MyUIMessage = UIMessage<
+  unknown,
+  {
+    url: { url: string; content: string };
+    config: { key: string; value: string };
+  }
+>;
+
+// TypeScript knows the exact shape of part.data
+convertToModelMessages<MyUIMessage>(messages, {
+  convertDataPart: part => {
+    if (part.type === 'data-url') {
+      // part.data is typed as { url: string; content: string }
+      return { type: 'text', text: part.data.url };
+    }
+    return null;
+  },
+});
+```

package/docs/07-reference/02-ai-sdk-ui/32-prune-messages.mdx

@@ -0,0 +1,108 @@
+---
+title: pruneMessages
+description: API Reference for pruneMessages.
+---
+
+# `pruneMessages()`
+
+The `pruneMessages` function is used to prune or filter an array of `ModelMessage` objects. This is useful for reducing message context (to save tokens), removing intermediate reasoning, or trimming tool calls and empty messages before sending to an LLM.
+
+```ts filename="app/api/chat/route.ts"
+import { pruneMessages, streamText } from 'ai';
+__PROVIDER_IMPORT__;
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const prunedMessages = pruneMessages({
+    messages,
+    reasoning: 'before-last-message',
+    toolCalls: 'before-last-2-messages',
+    emptyMessages: 'remove',
+  });
+
+  const result = streamText({
+    model: __MODEL__,
+    messages: prunedMessages,
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+## Import
+
+<Snippet text={`import { pruneMessages } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'messages',
+      type: 'ModelMessage[]',
+      description: 'An array of ModelMessage objects to prune.',
+    },
+    {
+      name: 'reasoning',
+      type: `'all' | 'before-last-message' | 'none'`,
+      description:
+        'How to remove reasoning content from assistant messages. Default: "none".',
+    },
+    {
+      name: 'toolCalls',
+      type: `'all' | 'before-last-message' | 'before-last-\${number}-messages\' | 'none' | PruneToolCallsOption[]`,
+      description:
+        'How to prune tool call/results/approval content. Can specify strategy or a list with tools.',
+    },
+    {
+      name: 'emptyMessages',
+      type: `'keep' | 'remove'`,
+      description:
+        'Whether to keep or remove messages whose content is empty after pruning. Default: "remove".',
+    },
+  ]}
+/>
+
+### Returns
+
+An array of [`ModelMessage`](/docs/reference/ai-sdk-core/model-message) objects, pruned according to the provided options.
+
+<PropertiesTable
+  content={[
+    {
+      name: 'ModelMessage[]',
+      type: 'Array',
+      description: 'The pruned list of ModelMessage objects',
+    },
+  ]}
+/>
+
+## Example Usage
+
+```ts
+import { pruneMessages } from 'ai';
+
+const pruned = pruneMessages({
+  messages,
+  reasoning: 'all', // Remove all reasoning parts
+  toolCalls: 'before-last-message', // Remove tool calls except those in the last message
+});
+```
+
+## Pruning Options
+
+- **reasoning:** Removes reasoning parts from assistant messages. Use `'all'` to remove all, `'before-last-message'` to keep reasoning in the last message, or `'none'` to retain all reasoning.
+- **toolCalls:** Prune tool-call, tool-result, and tool-approval chunks from assistant/tool messages. Options include:
+  - `'all'`: Prune all such content.
+  - `'before-last-message'`: Prune except in the last message.
+  - `before-last-N-messages`: Prune except in the last N messages.
+  - `'none'`: Do not prune.
+  - Or provide an array for per-tool fine control.
+- **emptyMessages:** Set to `'remove'` (default) to exclude messages that have no content after pruning.
+
+> **Tip**: `pruneMessages` is typically used prior to sending a context window to an LLM to reduce message/token count, especially after a series of tool-calls and approvals.
+
+For advanced usage and the full list of possible message parts, see [`ModelMessage`](/docs/reference/ai-sdk-core/model-message) and [`pruneMessages` implementation](https://github.com/vercel/ai/blob/main/packages/ai/src/generate-text/prune-messages.ts).

package/docs/07-reference/02-ai-sdk-ui/40-create-ui-message-stream.mdx

@@ -0,0 +1,151 @@
+---
+title: createUIMessageStream
+description: API Reference for createUIMessageStream.
+---
+
+# `createUIMessageStream`
+
+The `createUIMessageStream` function allows you to create a readable stream for UI messages with advanced features like message merging, error handling, and finish callbacks.
+
+## Import
+
+<Snippet text={`import { createUIMessageStream } from "ai"`} prompt={false} />
+
+## Example
+
+```tsx
+const existingMessages: UIMessage[] = [
+  /* ... */
+];
+
+const stream = createUIMessageStream({
+  async execute({ writer }) {
+    // Start a text message
+    // Note: The id must be consistent across text-start, text-delta, and text-end steps
+    // This allows the system to correctly identify they belong to the same text block
+    writer.write({
+      type: 'text-start',
+      id: 'example-text',
+    });
+
+    // Write a message chunk
+    writer.write({
+      type: 'text-delta',
+      id: 'example-text',
+      delta: 'Hello',
+    });
+
+    // End the text message
+    writer.write({
+      type: 'text-end',
+      id: 'example-text',
+    });
+
+    // Merge another stream from streamText
+    const result = streamText({
+      model: __MODEL__,
+      prompt: 'Write a haiku about AI',
+    });
+
+    writer.merge(result.toUIMessageStream());
+  },
+  onError: error => `Custom error: ${error.message}`,
+  originalMessages: existingMessages,
+  onFinish: ({ messages, isContinuation, responseMessage }) => {
+    console.log('Stream finished with messages:', messages);
+  },
+});
+```
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'execute',
+      type: '(options: { writer: UIMessageStreamWriter }) => Promise<void> | void',
+      description:
+        'A function that receives a writer instance and can use it to write UI message chunks to the stream.',
+      properties: [
+        {
+          type: 'UIMessageStreamWriter',
+          parameters: [
+            {
+              name: 'write',
+              type: '(part: UIMessageChunk) => void',
+              description: 'Writes a UI message chunk to the stream.',
+            },
+            {
+              name: 'merge',
+              type: '(stream: ReadableStream<UIMessageChunk>) => void',
+              description:
+                'Merges the contents of another UI message stream into this stream.',
+            },
+            {
+              name: 'onError',
+              type: '(error: unknown) => string',
+              description:
+                'Error handler that is used by the stream writer for handling errors in merged streams.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'onError',
+      type: '(error: unknown) => string',
+      description:
+        'A function that handles errors and returns an error message string. By default, it returns the error message.',
+    },
+    {
+      name: 'originalMessages',
+      type: 'UIMessage[] | undefined',
+      description:
+        'The original messages. If provided, persistence mode is assumed and a message ID is provided for the response message.',
+    },
+    {
+      name: 'onFinish',
+      type: '(options: { messages: UIMessage[]; isContinuation: boolean; responseMessage: UIMessage }) => void | undefined',
+      description:
+        'A callback function that is called when the stream finishes.',
+      properties: [
+        {
+          type: 'FinishOptions',
+          parameters: [
+            {
+              name: 'messages',
+              type: 'UIMessage[]',
+              description: 'The updated list of UI messages.',
+            },
+            {
+              name: 'isContinuation',
+              type: 'boolean',
+              description:
+                'Indicates whether the response message is a continuation of the last original message, or if a new message was created.',
+            },
+            {
+              name: 'responseMessage',
+              type: 'UIMessage',
+              description:
+                'The message that was sent to the client as a response (including the original message if it was extended).',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'generateId',
+      type: 'IdGenerator | undefined',
+      description:
+        'A function to generate unique IDs for messages. Uses the default ID generator if not provided.',
+    },
+  ]}
+/>
+
+### Returns
+
+`ReadableStream<UIMessageChunk>`
+
+A readable stream that emits UI message chunks. The stream automatically handles error propagation, merging of multiple streams, and proper cleanup when all operations are complete.