@fondation-io/ai 7.0.0-beta.45

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' | Array<{ type: 'all' | 'before-last-message' | 'before-last-\${number}-messages'; tools?: string[] }>`,
+      description:
+        'How to prune tool call/results/approval content. Can specify a strategy string or an array for per-tool fine control. Default: [] (empty array, equivalent to "none").',
+    },
+    {
+      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. Default is an empty array (no pruning). 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, e.g., `[{ type: 'before-last-message', tools: ['search', 'calculator'] }]` to prune only specific tools.
+- **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,162 @@
+---
+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; isAborted: boolean; responseMessage: UIMessage; finishReason?: FinishReason }) => PromiseLike<void> | void',
+      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: 'isAborted',
+              type: 'boolean',
+              description: 'Indicates whether the stream was aborted.',
+            },
+            {
+              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: 'finishReason',
+              type: 'FinishReason | undefined',
+              description:
+                "The reason why the generation finished. One of: 'stop', 'length', 'content-filter', 'tool-calls', 'error', or 'other'.",
+            },
+          ],
+        },
+      ],
+    },
+    {
+      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.

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

@@ -0,0 +1,119 @@
+---
+title: createUIMessageStreamResponse
+description: API Reference for createUIMessageStreamResponse.
+---
+
+# `createUIMessageStreamResponse`
+
+The `createUIMessageStreamResponse` function creates a Response object that streams UI messages to the client.
+
+## Import
+
+<Snippet
+  text={`import { createUIMessageStreamResponse } from "ai"`}
+  prompt={false}
+/>
+
+## Example
+
+```tsx
+import {
+  createUIMessageStream,
+  createUIMessageStreamResponse,
+  streamText,
+} from 'ai';
+__PROVIDER_IMPORT__;
+
+const response = createUIMessageStreamResponse({
+  status: 200,
+  statusText: 'OK',
+  headers: {
+    'Custom-Header': 'value',
+  },
+  stream: createUIMessageStream({
+    execute({ writer }) {
+      // Write custom data (type must be 'data-<name>')
+      writer.write({
+        type: 'data-message',
+        data: { content: 'Hello' },
+      });
+
+      // Write text content using start/delta/end pattern
+      writer.write({
+        type: 'text-start',
+        id: 'greeting-text',
+      });
+      writer.write({
+        type: 'text-delta',
+        id: 'greeting-text',
+        delta: 'Hello, world!',
+      });
+      writer.write({
+        type: 'text-end',
+        id: 'greeting-text',
+      });
+
+      // Write source information (flat properties, not nested)
+      writer.write({
+        type: 'source-url',
+        sourceId: 'source-1',
+        url: 'https://example.com',
+        title: 'Example Source',
+      });
+
+      // Merge with LLM stream
+      const result = streamText({
+        model: __MODEL__,
+        prompt: 'Say hello',
+      });
+
+      writer.merge(result.toUIMessageStream());
+    },
+  }),
+});
+```
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'stream',
+      type: 'ReadableStream<UIMessageChunk>',
+      description: 'The UI message stream to send to the client.',
+    },
+    {
+      name: 'status',
+      type: 'number',
+      isOptional: true,
+      description: 'The status code for the response. Defaults to 200.',
+    },
+    {
+      name: 'statusText',
+      type: 'string',
+      isOptional: true,
+      description: 'The status text for the response.',
+    },
+    {
+      name: 'headers',
+      type: 'Headers | Record<string, string>',
+      isOptional: true,
+      description: 'Additional headers for the response.',
+    },
+    {
+      name: 'consumeSseStream',
+      type: '(options: { stream: ReadableStream<string> }) => PromiseLike<void> | void',
+      isOptional: true,
+      description:
+        'Optional callback to consume the Server-Sent Events stream.',
+    },
+  ]}
+/>
+
+### Returns
+
+`Response`
+
+A Response object that streams UI message chunks with the specified status, headers, and content.

package/docs/07-reference/02-ai-sdk-ui/42-pipe-ui-message-stream-to-response.mdx

@@ -0,0 +1,77 @@
+---
+title: pipeUIMessageStreamToResponse
+description: Learn to use pipeUIMessageStreamToResponse helper function to pipe streaming data to a ServerResponse object.
+---
+
+# `pipeUIMessageStreamToResponse`
+
+The `pipeUIMessageStreamToResponse` function pipes streaming data to a Node.js ServerResponse object (see [Streaming Data](/docs/ai-sdk-ui/streaming-data)).
+
+## Import
+
+<Snippet
+  text={`import { pipeUIMessageStreamToResponse } from "ai"`}
+  prompt={false}
+/>
+
+## Example
+
+```tsx
+pipeUIMessageStreamToResponse({
+  response: serverResponse,
+  status: 200,
+  statusText: 'OK',
+  headers: {
+    'Custom-Header': 'value',
+  },
+  stream: myUIMessageStream,
+  consumeSseStream: ({ stream }) => {
+    // Optional: consume the SSE stream independently
+    console.log('Consuming SSE stream:', stream);
+  },
+});
+```
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'response',
+      type: 'ServerResponse',
+      description: 'The Node.js ServerResponse object to pipe the data to.',
+    },
+    {
+      name: 'stream',
+      type: 'ReadableStream<UIMessageChunk>',
+      description: 'The UI message stream to pipe to the response.',
+    },
+    {
+      name: 'status',
+      type: 'number',
+      isOptional: true,
+      description: 'The status code for the response.',
+    },
+    {
+      name: 'statusText',
+      type: 'string',
+      isOptional: true,
+      description: 'The status text for the response.',
+    },
+    {
+      name: 'headers',
+      type: 'Headers | Record<string, string>',
+      isOptional: true,
+      description: 'Additional headers for the response.',
+    },
+    {
+      name: 'consumeSseStream',
+      type: '({ stream }: { stream: ReadableStream<string> }) => PromiseLike<void> | void',
+      isOptional: true,
+      description:
+        'Optional function to consume the SSE stream independently. The stream is teed and this function receives a copy.',
+    },
+  ]}
+/>

package/docs/07-reference/02-ai-sdk-ui/43-read-ui-message-stream.mdx

@@ -0,0 +1,57 @@
+---
+title: readUIMessageStream
+description: API Reference for readUIMessageStream.
+---
+
+# readUIMessageStream
+
+Transforms a stream of `UIMessageChunk`s into an `AsyncIterableStream` of `UIMessage`s.
+
+UI message streams are useful outside of Chat use cases, e.g. for terminal UIs, custom stream consumption on the client, or RSC (React Server Components).
+
+## Import
+
+```tsx
+import { readUIMessageStream } from 'ai';
+```
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'message',
+      type: 'UIMessage',
+      isOptional: true,
+      description:
+        'The last assistant message to use as a starting point when the conversation is resumed. Otherwise undefined.',
+    },
+    {
+      name: 'stream',
+      type: 'ReadableStream<UIMessageChunk>',
+      description: 'The stream of UIMessageChunk objects to read.',
+    },
+    {
+      name: 'onError',
+      type: '(error: unknown) => void',
+      isOptional: true,
+      description:
+        'A function that is called when an error occurs during stream processing.',
+    },
+    {
+      name: 'terminateOnError',
+      type: 'boolean',
+      isOptional: true,
+      description:
+        'Whether to terminate the stream if an error occurs. Defaults to false.',
+    },
+  ]}
+/>
+
+### Returns
+
+An `AsyncIterableStream` of `UIMessage`s. Each stream part represents a different state of the same message as it is being completed.
+
+For comprehensive examples and use cases, see [Reading UI Message Streams](/docs/ai-sdk-ui/reading-ui-message-streams).

package/docs/07-reference/02-ai-sdk-ui/46-infer-ui-tools.mdx

@@ -0,0 +1,99 @@
+---
+title: InferUITools
+description: API Reference for InferUITools.
+---
+
+# InferUITools
+
+Infers the input and output types of a `ToolSet`.
+
+This type helper is useful when working with tools in TypeScript to ensure type safety for your tool inputs and outputs in `UIMessage`s.
+
+## Import
+
+```tsx
+import { InferUITools } from 'ai';
+```
+
+## API Signature
+
+### Type Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'TOOLS',
+      type: 'ToolSet',
+      description: 'The tool set to infer types from.',
+    },
+  ]}
+/>
+
+### Returns
+
+A type that maps each tool in the tool set to its inferred input and output types.
+
+The resulting type has the shape:
+
+```typescript
+{
+  [NAME in keyof TOOLS & string]: {
+    input: InferToolInput<TOOLS[NAME]>;
+    output: InferToolOutput<TOOLS[NAME]>;
+  };
+}
+```
+
+## Examples
+
+### Basic Usage
+
+```tsx
+import { InferUITools } from 'ai';
+import { z } from 'zod';
+
+const tools = {
+  weather: {
+    description: 'Get the current weather',
+    inputSchema: z.object({
+      location: z.string().describe('The city and state'),
+    }),
+    execute: async ({ location }) => {
+      return `The weather in ${location} is sunny.`;
+    },
+  },
+  calculator: {
+    description: 'Perform basic arithmetic',
+    inputSchema: z.object({
+      operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
+      a: z.number(),
+      b: z.number(),
+    }),
+    execute: async ({ operation, a, b }) => {
+      switch (operation) {
+        case 'add':
+          return a + b;
+        case 'subtract':
+          return a - b;
+        case 'multiply':
+          return a * b;
+        case 'divide':
+          return a / b;
+      }
+    },
+  },
+};
+
+// Infer the types from the tool set
+type MyUITools = InferUITools<typeof tools>;
+// This creates a type with:
+// {
+//   weather: { input: { location: string }; output: string };
+//   calculator: { input: { operation: 'add' | 'subtract' | 'multiply' | 'divide'; a: number; b: number }; output: number };
+// }
+```
+
+## Related
+
+- [`InferUITool`](/docs/reference/ai-sdk-ui/infer-ui-tool) - Infer types for a single tool
+- [`useChat`](/docs/reference/ai-sdk-ui/use-chat) - Chat hook that supports typed tools

package/docs/07-reference/02-ai-sdk-ui/47-infer-ui-tool.mdx

@@ -0,0 +1,75 @@
+---
+title: InferUITool
+description: API Reference for InferUITool.
+---
+
+# InferUITool
+
+Infers the input and output types of a tool.
+
+This type helper is useful when working with individual tools to ensure type safety for your tool inputs and outputs in `UIMessage`s.
+
+## Import
+
+```tsx
+import { InferUITool } from 'ai';
+```
+
+## API Signature
+
+### Type Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'TOOL',
+      type: 'Tool',
+      description: 'The tool to infer types from.',
+    },
+  ]}
+/>
+
+### Returns
+
+A type that contains the inferred input and output types of the tool.
+
+The resulting type has the shape:
+
+```typescript
+{
+  input: InferToolInput<TOOL>;
+  output: InferToolOutput<TOOL>;
+}
+```
+
+## Examples
+
+### Basic Usage
+
+```tsx
+import { InferUITool } from 'ai';
+import { z } from 'zod';
+
+const weatherTool = {
+  description: 'Get the current weather',
+  inputSchema: z.object({
+    location: z.string().describe('The city and state'),
+  }),
+  execute: async ({ location }) => {
+    return `The weather in ${location} is sunny.`;
+  },
+};
+
+// Infer the types from the tool
+type WeatherUITool = InferUITool<typeof weatherTool>;
+// This creates a type with:
+// {
+//   input: { location: string };
+//   output: string;
+// }
+```
+
+## Related
+
+- [`InferUITools`](/docs/reference/ai-sdk-ui/infer-ui-tools) - Infer types for a tool set
+- [`ToolUIPart`](/docs/reference/ai-sdk-core/ui-message#tooluipart) - Tool part type for UI messages