ai 6.0.31 → 6.0.32

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

@@ -0,0 +1,113 @@
+---
+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
+      writer.write({
+        type: 'data',
+        value: { message: 'Hello' },
+      });
+
+      // Write text content
+      writer.write({
+        type: 'text',
+        value: 'Hello, world!',
+      });
+
+      // Write source information
+      writer.write({
+        type: 'source-url',
+        value: {
+          type: 'source',
+          id: '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,73 @@
+---
+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',
+      description: 'The status code for the response.',
+    },
+    {
+      name: 'statusText',
+      type: 'string',
+      description: 'The status text for the response.',
+    },
+    {
+      name: 'headers',
+      type: 'Headers | Record<string, string>',
+      description: 'Additional headers for the response.',
+    },
+    {
+      name: 'consumeSseStream',
+      type: '({ stream }: { stream: ReadableStream }) => void',
+      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',
+    parameters: 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',
+    parameters: 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',
+  parameters: 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-ui/tool-ui-part) - Tool part type for UI messages