ai 6.0.31 → 6.0.33

package/docs/04-ai-sdk-ui/20-streaming-data.mdx

@@ -0,0 +1,397 @@
+---
+title: Streaming Custom Data
+description: Learn how to stream custom data from the server to the client.
+---
+
+# Streaming Custom Data
+
+It is often useful to send additional data alongside the model's response.
+For example, you may want to send status information, the message ids after storing them,
+or references to content that the language model is referring to.
+
+The AI SDK provides several helpers that allows you to stream additional data to the client
+and attach it to the `UIMessage` parts array:
+
+- `createUIMessageStream`: creates a data stream
+- `createUIMessageStreamResponse`: creates a response object that streams data
+- `pipeUIMessageStreamToResponse`: pipes a data stream to a server response object
+
+The data is streamed as part of the response stream using Server-Sent Events.
+
+## Setting Up Type-Safe Data Streaming
+
+First, define your custom message type with data part schemas for type safety:
+
+```tsx filename="ai/types.ts"
+import { UIMessage } from 'ai';
+
+// Define your custom message type with data part schemas
+export type MyUIMessage = UIMessage<
+  never, // metadata type
+  {
+    weather: {
+      city: string;
+      weather?: string;
+      status: 'loading' | 'success';
+    };
+    notification: {
+      message: string;
+      level: 'info' | 'warning' | 'error';
+    };
+  } // data parts type
+>;
+```
+
+## Streaming Data from the Server
+
+In your server-side route handler, you can create a `UIMessageStream` and then pass it to `createUIMessageStreamResponse`:
+
+```tsx filename="route.ts"
+import { openai } from '@ai-sdk/openai';
+import {
+  createUIMessageStream,
+  createUIMessageStreamResponse,
+  streamText,
+  convertToModelMessages,
+} from 'ai';
+__PROVIDER_IMPORT__;
+import type { MyUIMessage } from '@/ai/types';
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const stream = createUIMessageStream<MyUIMessage>({
+    execute: ({ writer }) => {
+      // 1. Send initial status (transient - won't be added to message history)
+      writer.write({
+        type: 'data-notification',
+        data: { message: 'Processing your request...', level: 'info' },
+        transient: true, // This part won't be added to message history
+      });
+
+      // 2. Send sources (useful for RAG use cases)
+      writer.write({
+        type: 'source',
+        value: {
+          type: 'source',
+          sourceType: 'url',
+          id: 'source-1',
+          url: 'https://weather.com',
+          title: 'Weather Data Source',
+        },
+      });
+
+      // 3. Send data parts with loading state
+      writer.write({
+        type: 'data-weather',
+        id: 'weather-1',
+        data: { city: 'San Francisco', status: 'loading' },
+      });
+
+      const result = streamText({
+        model: __MODEL__,
+        messages: await convertToModelMessages(messages),
+        onFinish() {
+          // 4. Update the same data part (reconciliation)
+          writer.write({
+            type: 'data-weather',
+            id: 'weather-1', // Same ID = update existing part
+            data: {
+              city: 'San Francisco',
+              weather: 'sunny',
+              status: 'success',
+            },
+          });
+
+          // 5. Send completion notification (transient)
+          writer.write({
+            type: 'data-notification',
+            data: { message: 'Request completed', level: 'info' },
+            transient: true, // Won't be added to message history
+          });
+        },
+      });
+
+      writer.merge(result.toUIMessageStream());
+    },
+  });
+
+  return createUIMessageStreamResponse({ stream });
+}
+```
+
+<Note>
+  You can also send stream data from custom backends, e.g. Python / FastAPI,
+  using the [UI Message Stream
+  Protocol](/docs/ai-sdk-ui/stream-protocol#ui-message-stream-protocol).
+</Note>
+
+## Types of Streamable Data
+
+### Data Parts (Persistent)
+
+Regular data parts are added to the message history and appear in `message.parts`:
+
+```tsx
+writer.write({
+  type: 'data-weather',
+  id: 'weather-1', // Optional: enables reconciliation
+  data: { city: 'San Francisco', status: 'loading' },
+});
+```
+
+### Sources
+
+Sources are useful for RAG implementations where you want to show which documents or URLs were referenced:
+
+```tsx
+writer.write({
+  type: 'source',
+  value: {
+    type: 'source',
+    sourceType: 'url',
+    id: 'source-1',
+    url: 'https://example.com',
+    title: 'Example Source',
+  },
+});
+```
+
+### Transient Data Parts (Ephemeral)
+
+Transient parts are sent to the client but not added to the message history. They are only accessible via the `onData` useChat handler:
+
+```tsx
+// server
+writer.write({
+  type: 'data-notification',
+  data: { message: 'Processing...', level: 'info' },
+  transient: true, // Won't be added to message history
+});
+
+// client
+const [notification, setNotification] = useState();
+
+const { messages } = useChat({
+  onData: ({ data, type }) => {
+    if (type === 'data-notification') {
+      setNotification({ message: data.message, level: data.level });
+    }
+  },
+});
+```
+
+## Data Part Reconciliation
+
+When you write to a data part with the same ID, the client automatically reconciles and updates that part. This enables powerful dynamic experiences like:
+
+- **Collaborative artifacts** - Update code, documents, or designs in real-time
+- **Progressive data loading** - Show loading states that transform into final results
+- **Live status updates** - Update progress bars, counters, or status indicators
+- **Interactive components** - Build UI elements that evolve based on user interaction
+
+The reconciliation happens automatically - simply use the same `id` when writing to the stream.
+
+## Processing Data on the Client
+
+### Using the onData Callback
+
+The `onData` callback is essential for handling streaming data, especially transient parts:
+
+```tsx filename="page.tsx"
+import { useChat } from '@ai-sdk/react';
+import type { MyUIMessage } from '@/ai/types';
+
+const { messages } = useChat<MyUIMessage>({
+  api: '/api/chat',
+  onData: dataPart => {
+    // Handle all data parts as they arrive (including transient parts)
+    console.log('Received data part:', dataPart);
+
+    // Handle different data part types
+    if (dataPart.type === 'data-weather') {
+      console.log('Weather update:', dataPart.data);
+    }
+
+    // Handle transient notifications (ONLY available here, not in message.parts)
+    if (dataPart.type === 'data-notification') {
+      showToast(dataPart.data.message, dataPart.data.level);
+    }
+  },
+});
+```
+
+**Important:** Transient data parts are **only** available through the `onData` callback. They will not appear in the `message.parts` array since they're not added to message history.
+
+### Rendering Persistent Data Parts
+
+You can filter and render data parts from the message parts array:
+
+```tsx filename="page.tsx"
+const result = (
+  <>
+    {messages?.map(message => (
+      <div key={message.id}>
+        {/* Render weather data parts */}
+        {message.parts
+          .filter(part => part.type === 'data-weather')
+          .map((part, index) => (
+            <div key={index} className="weather-widget">
+              {part.data.status === 'loading' ? (
+                <>Getting weather for {part.data.city}...</>
+              ) : (
+                <>
+                  Weather in {part.data.city}: {part.data.weather}
+                </>
+              )}
+            </div>
+          ))}
+
+        {/* Render text content */}
+        {message.parts
+          .filter(part => part.type === 'text')
+          .map((part, index) => (
+            <div key={index}>{part.text}</div>
+          ))}
+
+        {/* Render sources */}
+        {message.parts
+          .filter(part => part.type === 'source')
+          .map((part, index) => (
+            <div key={index} className="source">
+              Source: <a href={part.url}>{part.title}</a>
+            </div>
+          ))}
+      </div>
+    ))}
+  </>
+);
+```
+
+### Complete Example
+
+```tsx filename="page.tsx"
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import { useState } from 'react';
+import type { MyUIMessage } from '@/ai/types';
+
+export default function Chat() {
+  const [input, setInput] = useState('');
+
+  const { messages, sendMessage } = useChat<MyUIMessage>({
+    api: '/api/chat',
+    onData: dataPart => {
+      // Handle transient notifications
+      if (dataPart.type === 'data-notification') {
+        console.log('Notification:', dataPart.data.message);
+      }
+    },
+  });
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    sendMessage({ text: input });
+    setInput('');
+  };
+
+  return (
+    <>
+      {messages?.map(message => (
+        <div key={message.id}>
+          {message.role === 'user' ? 'User: ' : 'AI: '}
+
+          {/* Render weather data */}
+          {message.parts
+            .filter(part => part.type === 'data-weather')
+            .map((part, index) => (
+              <span key={index} className="weather-update">
+                {part.data.status === 'loading' ? (
+                  <>Getting weather for {part.data.city}...</>
+                ) : (
+                  <>
+                    Weather in {part.data.city}: {part.data.weather}
+                  </>
+                )}
+              </span>
+            ))}
+
+          {/* Render text content */}
+          {message.parts
+            .filter(part => part.type === 'text')
+            .map((part, index) => (
+              <div key={index}>{part.text}</div>
+            ))}
+        </div>
+      ))}
+
+      <form onSubmit={handleSubmit}>
+        <input
+          value={input}
+          onChange={e => setInput(e.target.value)}
+          placeholder="Ask about the weather..."
+        />
+        <button type="submit">Send</button>
+      </form>
+    </>
+  );
+}
+```
+
+## Use Cases
+
+- **RAG Applications** - Stream sources and retrieved documents
+- **Real-time Status** - Show loading states and progress updates
+- **Collaborative Tools** - Stream live updates to shared artifacts
+- **Analytics** - Send usage data without cluttering message history
+- **Notifications** - Display temporary alerts and status messages
+
+## Message Metadata vs Data Parts
+
+Both [message metadata](/docs/ai-sdk-ui/message-metadata) and data parts allow you to send additional information alongside messages, but they serve different purposes:
+
+### Message Metadata
+
+Message metadata is best for **message-level information** that describes the message as a whole:
+
+- Attached at the message level via `message.metadata`
+- Sent using the `messageMetadata` callback in `toUIMessageStreamResponse`
+- Ideal for: timestamps, model info, token usage, user context
+- Type-safe with custom metadata types
+
+```ts
+// Server: Send metadata about the message
+return result.toUIMessageStreamResponse({
+  messageMetadata: ({ part }) => {
+    if (part.type === 'finish') {
+      return {
+        model: part.response.modelId,
+        totalTokens: part.totalUsage.totalTokens,
+        createdAt: Date.now(),
+      };
+    }
+  },
+});
+```
+
+### Data Parts
+
+Data parts are best for streaming **dynamic arbitrary data**:
+
+- Added to the message parts array via `message.parts`
+- Streamed using `createUIMessageStream` and `writer.write()`
+- Can be reconciled/updated using the same ID
+- Support transient parts that don't persist
+- Ideal for: dynamic content, loading states, interactive components
+
+```ts
+// Server: Stream data as part of message content
+writer.write({
+  type: 'data-weather',
+  id: 'weather-1',
+  data: { city: 'San Francisco', status: 'loading' },
+});
+```
+
+For more details on message metadata, see the [Message Metadata documentation](/docs/ai-sdk-ui/message-metadata).

package/docs/04-ai-sdk-ui/21-error-handling.mdx

@@ -0,0 +1,190 @@
+---
+title: Error Handling
+description: Learn how to handle errors in the AI SDK UI
+---
+
+# Error Handling and warnings
+
+## Warnings
+
+The AI SDK shows warnings when something might not work as expected.
+These warnings help you fix problems before they cause errors.
+
+### When Warnings Appear
+
+Warnings are shown in the browser console when:
+
+- **Unsupported features**: You use a feature or setting that is not supported by the AI model (e.g., certain options or parameters).
+- **Compatibility warnings**: A feature is used in a compatibility mode, which might work differently or less optimally than intended.
+- **Other warnings**: The AI model reports another type of issue, such as general problems or advisory messages.
+
+### Warning Messages
+
+All warnings start with "AI SDK Warning:" so you can easily find them. For example:
+
+```
+AI SDK Warning: The feature "temperature" is not supported by this model
+```
+
+### Turning Off Warnings
+
+By default, warnings are shown in the console. You can control this behavior:
+
+#### Turn Off All Warnings
+
+Set a global variable to turn off warnings completely:
+
+```ts
+globalThis.AI_SDK_LOG_WARNINGS = false;
+```
+
+#### Custom Warning Handler
+
+You can also provide your own function to handle warnings.
+It receives provider id, model id, and a list of warnings.
+
+```ts
+globalThis.AI_SDK_LOG_WARNINGS = ({ warnings, provider, model }) => {
+  // Handle warnings your own way
+};
+```
+
+## Error Handling
+
+### Error Helper Object
+
+Each AI SDK UI hook also returns an [error](/docs/reference/ai-sdk-ui/use-chat#error) object that you can use to render the error in your UI.
+You can use the error object to show an error message, disable the submit button, or show a retry button.
+
+<Note>
+  We recommend showing a generic error message to the user, such as "Something
+  went wrong." This is a good practice to avoid leaking information from the
+  server.
+</Note>
+
+```tsx file="app/page.tsx" highlight="7,18-25,31"
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import { useState } from 'react';
+
+export default function Chat() {
+  const [input, setInput] = useState('');
+  const { messages, sendMessage, error, regenerate } = useChat();
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    sendMessage({ text: input });
+    setInput('');
+  };
+
+  return (
+    <div>
+      {messages.map(m => (
+        <div key={m.id}>
+          {m.role}:{' '}
+          {m.parts
+            .filter(part => part.type === 'text')
+            .map(part => part.text)
+            .join('')}
+        </div>
+      ))}
+
+      {error && (
+        <>
+          <div>An error occurred.</div>
+          <button type="button" onClick={() => regenerate()}>
+            Retry
+          </button>
+        </>
+      )}
+
+      <form onSubmit={handleSubmit}>
+        <input
+          value={input}
+          onChange={e => setInput(e.target.value)}
+          disabled={error != null}
+        />
+      </form>
+    </div>
+  );
+}
+```
+
+#### Alternative: replace last message
+
+Alternatively you can write a custom submit handler that replaces the last message when an error is present.
+
+```tsx file="app/page.tsx" highlight="17-23,35"
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import { useState } from 'react';
+
+export default function Chat() {
+  const [input, setInput] = useState('');
+  const { sendMessage, error, messages, setMessages } = useChat();
+
+  function customSubmit(event: React.FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+
+    if (error != null) {
+      setMessages(messages.slice(0, -1)); // remove last message
+    }
+
+    sendMessage({ text: input });
+    setInput('');
+  }
+
+  return (
+    <div>
+      {messages.map(m => (
+        <div key={m.id}>
+          {m.role}:{' '}
+          {m.parts
+            .filter(part => part.type === 'text')
+            .map(part => part.text)
+            .join('')}
+        </div>
+      ))}
+
+      {error && <div>An error occurred.</div>}
+
+      <form onSubmit={customSubmit}>
+        <input value={input} onChange={e => setInput(e.target.value)} />
+      </form>
+    </div>
+  );
+}
+```
+
+### Error Handling Callback
+
+Errors can be processed by passing an [`onError`](/docs/reference/ai-sdk-ui/use-chat#on-error) callback function as an option to the [`useChat`](/docs/reference/ai-sdk-ui/use-chat) or [`useCompletion`](/docs/reference/ai-sdk-ui/use-completion) hooks.
+The callback function receives an error object as an argument.
+
+```tsx file="app/page.tsx" highlight="6-9"
+import { useChat } from '@ai-sdk/react';
+
+export default function Page() {
+  const {
+    /* ... */
+  } = useChat({
+    // handle error:
+    onError: error => {
+      console.error(error);
+    },
+  });
+}
+```
+
+### Injecting Errors for Testing
+
+You might want to create errors for testing.
+You can easily do so by throwing an error in your route handler:
+
+```ts file="app/api/chat/route.ts"
+export async function POST(req: Request) {
+  throw new Error('This is a test error');
+}
+```