ai 6.0.31 → 6.0.32

package/docs/05-ai-sdk-rsc/02-streaming-react-components.mdx

@@ -0,0 +1,209 @@
+---
+title: Streaming React Components
+description: Overview of streaming RSCs
+---
+
+import { UIPreviewCard, Card } from '@/components/home/card';
+import { EventPlanning } from '@/components/home/event-planning';
+import { Searching } from '@/components/home/searching';
+import { Weather } from '@/components/home/weather';
+
+# Streaming React Components
+
+<Note type="warning">
+  AI SDK RSC is currently experimental. We recommend using [AI SDK
+  UI](/docs/ai-sdk-ui/overview) for production. For guidance on migrating from
+  RSC to UI, see our [migration guide](/docs/ai-sdk-rsc/migrating-to-ui).
+</Note>
+
+The RSC API allows you to stream React components from the server to the client with the [`streamUI`](/docs/reference/ai-sdk-rsc/stream-ui) function. This is useful when you want to go beyond raw text and stream components to the client in real-time.
+
+Similar to [ AI SDK Core ](/docs/ai-sdk-core/overview) APIs (like [ `streamText` ](/docs/reference/ai-sdk-core/stream-text) and [ `streamObject` ](/docs/reference/ai-sdk-core/stream-object)), `streamUI` provides a single function to call a model and allow it to respond with React Server Components.
+It supports the same model interfaces as AI SDK Core APIs.
+
+### Concepts
+
+To give the model the ability to respond to a user's prompt with a React component, you can leverage [tools](/docs/ai-sdk-core/tools-and-tool-calling).
+
+<Note>
+  Remember, tools are like programs you can give to the model, and the model can
+  decide as and when to use based on the context of the conversation.
+</Note>
+
+With the `streamUI` function, **you provide tools that return React components**. With the ability to stream components, the model is akin to a dynamic router that is able to understand the user's intention and display relevant UI.
+
+At a high level, the `streamUI` works like other AI SDK Core functions: you can provide the model with a prompt or some conversation history and, optionally, some tools. If the model decides, based on the context of the conversation, to call a tool, it will generate a tool call. The `streamUI` function will then run the respective tool, returning a React component. If the model doesn't have a relevant tool to use, it will return a text generation, which will be passed to the `text` function, for you to handle (render and return as a React component).
+
+<Note>Remember, the `streamUI` function must return a React component. </Note>
+
+```tsx
+const result = await streamUI({
+  model: openai('gpt-4o'),
+  prompt: 'Get the weather for San Francisco',
+  text: ({ content }) => <div>{content}</div>,
+  tools: {},
+});
+```
+
+This example calls the `streamUI` function using OpenAI's `gpt-4o` model, passes a prompt, specifies how the model's plain text response (`content`) should be rendered, and then provides an empty object for tools. Even though this example does not define any tools, it will stream the model's response as a `div` rather than plain text.
+
+### Adding A Tool
+
+Using tools with `streamUI` is similar to how you use tools with `generateText` and `streamText`.
+A tool is an object that has:
+
+- `description`: a string telling the model what the tool does and when to use it
+- `inputSchema`: a Zod schema describing what the tool needs in order to run
+- `generate`: an asynchronous function that will be run if the model calls the tool. This must return a React component
+
+Let's expand the previous example to add a tool.
+
+```tsx highlight="6-14"
+const result = await streamUI({
+  model: openai('gpt-4o'),
+  prompt: 'Get the weather for San Francisco',
+  text: ({ content }) => <div>{content}</div>,
+  tools: {
+    getWeather: {
+      description: 'Get the weather for a location',
+      inputSchema: z.object({ location: z.string() }),
+      generate: async function* ({ location }) {
+        yield <LoadingComponent />;
+        const weather = await getWeather(location);
+        return <WeatherComponent weather={weather} location={location} />;
+      },
+    },
+  },
+});
+```
+
+This tool would be run if the user asks for the weather for their location. If the user hasn't specified a location, the model will ask for it before calling the tool. When the model calls the tool, the generate function will initially return a loading component. This component will show until the awaited call to `getWeather` is resolved, at which point, the model will stream the `<WeatherComponent />` to the user.
+
+<Note>
+  Note: This example uses a [ generator function
+  ](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*)
+  (`function*`), which allows you to pause its execution and return a value,
+  then resume from where it left off on the next call. This is useful for
+  handling data streams, as you can fetch and return data from an asynchronous
+  source like an API, then resume the function to fetch the next chunk when
+  needed. By yielding values one at a time, generator functions enable efficient
+  processing of streaming data without blocking the main thread.
+</Note>
+
+## Using `streamUI` with Next.js
+
+Let's see how you can use the example above in a Next.js application.
+
+To use `streamUI` in a Next.js application, you will need two things:
+
+1. A Server Action (where you will call `streamUI`)
+2. A page to call the Server Action and render the resulting components
+
+### Step 1: Create a Server Action
+
+<Note>
+  Server Actions are server-side functions that you can call directly from the
+  frontend. For more info, see [the
+  documentation](https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations#with-client-components).
+</Note>
+
+Create a Server Action at `app/actions.tsx` and add the following code:
+
+```tsx filename="app/actions.tsx"
+'use server';
+
+import { streamUI } from '@ai-sdk/rsc';
+import { openai } from '@ai-sdk/openai';
+import { z } from 'zod';
+
+const LoadingComponent = () => (
+  <div className="animate-pulse p-4">getting weather...</div>
+);
+
+const getWeather = async (location: string) => {
+  await new Promise(resolve => setTimeout(resolve, 2000));
+  return '82°F️ ☀️';
+};
+
+interface WeatherProps {
+  location: string;
+  weather: string;
+}
+
+const WeatherComponent = (props: WeatherProps) => (
+  <div className="border border-neutral-200 p-4 rounded-lg max-w-fit">
+    The weather in {props.location} is {props.weather}
+  </div>
+);
+
+export async function streamComponent() {
+  const result = await streamUI({
+    model: openai('gpt-4o'),
+    prompt: 'Get the weather for San Francisco',
+    text: ({ content }) => <div>{content}</div>,
+    tools: {
+      getWeather: {
+        description: 'Get the weather for a location',
+        inputSchema: z.object({
+          location: z.string(),
+        }),
+        generate: async function* ({ location }) {
+          yield <LoadingComponent />;
+          const weather = await getWeather(location);
+          return <WeatherComponent weather={weather} location={location} />;
+        },
+      },
+    },
+  });
+
+  return result.value;
+}
+```
+
+The `getWeather` tool should look familiar as it is identical to the example in the previous section. In order for this tool to work:
+
+1. First define a `LoadingComponent`, which renders a pulsing `div` that will show some loading text.
+2. Next, define a `getWeather` function that will timeout for 2 seconds (to simulate fetching the weather externally) before returning the "weather" for a `location`. Note: you could run any asynchronous TypeScript code here.
+3. Finally, define a `WeatherComponent` which takes in `location` and `weather` as props, which are then rendered within a `div`.
+
+Your Server Action is an asynchronous function called `streamComponent` that takes no inputs, and returns a `ReactNode`. Within the action, you call the `streamUI` function, specifying the model (`gpt-4o`), the prompt, the component that should be rendered if the model chooses to return text, and finally, your `getWeather` tool. Last but not least, you return the resulting component generated by the model with `result.value`.
+
+To call this Server Action and display the resulting React Component, you will need a page.
+
+### Step 2: Create a Page
+
+Create or update your root page (`app/page.tsx`) with the following code:
+
+```tsx filename="app/page.tsx"
+'use client';
+
+import { useState } from 'react';
+import { Button } from '@/components/ui/button';
+import { streamComponent } from './actions';
+
+export default function Page() {
+  const [component, setComponent] = useState<React.ReactNode>();
+
+  return (
+    <div>
+      <form
+        onSubmit={async e => {
+          e.preventDefault();
+          setComponent(await streamComponent());
+        }}
+      >
+        <Button>Stream Component</Button>
+      </form>
+      <div>{component}</div>
+    </div>
+  );
+}
+```
+
+This page is first marked as a client component with the `"use client";` directive given it will be using hooks and interactivity. On the page, you render a form. When that form is submitted, you call the `streamComponent` action created in the previous step (just like any other function). The `streamComponent` action returns a `ReactNode` that you can then render on the page using React state (`setComponent`).
+
+## Going beyond a single prompt
+
+You can now allow the model to respond to your prompt with a React component. However, this example is limited to a static prompt that is set within your Server Action. You could make this example interactive by turning it into a chatbot.
+
+Learn how to stream React components with the Next.js App Router using `streamUI` with this [example](/examples/next-app/interface/route-components).

package/docs/05-ai-sdk-rsc/03-generative-ui-state.mdx

@@ -0,0 +1,279 @@
+---
+title: Managing Generative UI State
+description: Overview of the AI and UI states
+---
+
+# Managing Generative UI State
+
+<Note type="warning">
+  AI SDK RSC is currently experimental. We recommend using [AI SDK
+  UI](/docs/ai-sdk-ui/overview) for production. For guidance on migrating from
+  RSC to UI, see our [migration guide](/docs/ai-sdk-rsc/migrating-to-ui).
+</Note>
+
+State is an essential part of any application. State is particularly important in AI applications as it is passed to large language models (LLMs) on each request to ensure they have the necessary context to produce a great generation. Traditional chatbots are text-based and have a structure that mirrors that of any chat application.
+
+For example, in a chatbot, state is an array of `messages` where each `message` has:
+
+- `id`: a unique identifier
+- `role`: who sent the message (user/assistant/system/tool)
+- `content`: the content of the message
+
+This state can be rendered in the UI and sent to the model without any modifications.
+
+With Generative UI, the model can now return a React component, rather than a plain text message. The client can render that component without issue, but that state can't be sent back to the model because React components aren't serialisable. So, what can you do?
+
+**The solution is to split the state in two, where one (AI State) becomes a proxy for the other (UI State)**.
+
+One way to understand this concept is through a Lego analogy. Imagine a 10,000 piece Lego model that, once built, cannot be easily transported because it is fragile. By taking the model apart, it can be easily transported, and then rebuilt following the steps outlined in the instructions pamphlet. In this way, the instructions pamphlet is a proxy to the physical structure. Similarly, AI State provides a serialisable (JSON) representation of your UI that can be passed back and forth to the model.
+
+## What is AI and UI State?
+
+The RSC API simplifies how you manage AI State and UI State, providing a robust way to keep them in sync between your database, server and client.
+
+### AI State
+
+AI State refers to the state of your application in a serialisable format that will be used on the server and can be shared with the language model.
+
+For a chat app, the AI State is the conversation history (messages) between the user and the assistant. Components generated by the model would be represented in a JSON format as a tool alongside any necessary props. AI State can also be used to store other values and meta information such as `createdAt` for each message and `chatId` for each conversation. The LLM reads this history so it can generate the next message. This state serves as the source of truth for the current application state.
+
+<Note>
+  **Note**: AI state can be accessed/modified from both the server and the
+  client.
+</Note>
+
+### UI State
+
+UI State refers to the state of your application that is rendered on the client. It is a fully client-side state (similar to `useState`) that can store anything from Javascript values to React elements. UI state is a list of actual UI elements that are rendered on the client.
+
+<Note>**Note**: UI State can only be accessed client-side.</Note>
+
+## Using AI / UI State
+
+### Creating the AI Context
+
+AI SDK RSC simplifies managing AI and UI state across your application by providing several hooks. These hooks are powered by [ React context ](https://react.dev/reference/react/hooks#context-hooks) under the hood.
+
+Notably, this means you do not have to pass the message history to the server explicitly for each request. You also can access and update your application state in any child component of the context provider. As you begin building [multistep generative interfaces](/docs/ai-sdk-rsc/multistep-interfaces), this will be particularly helpful.
+
+To use `@ai-sdk/rsc` to manage AI and UI State in your application, you can create a React context using [`createAI`](/docs/reference/ai-sdk-rsc/create-ai):
+
+```tsx filename='app/actions.tsx'
+// Define the AI state and UI state types
+export type ServerMessage = {
+  role: 'user' | 'assistant';
+  content: string;
+};
+
+export type ClientMessage = {
+  id: string;
+  role: 'user' | 'assistant';
+  display: ReactNode;
+};
+
+export const sendMessage = async (input: string): Promise<ClientMessage> => {
+  "use server"
+  ...
+}
+```
+
+```tsx filename='app/ai.ts'
+import { createAI } from '@ai-sdk/rsc';
+import { ClientMessage, ServerMessage, sendMessage } from './actions';
+
+export type AIState = ServerMessage[];
+export type UIState = ClientMessage[];
+
+// Create the AI provider with the initial states and allowed actions
+export const AI = createAI<AIState, UIState>({
+  initialAIState: [],
+  initialUIState: [],
+  actions: {
+    sendMessage,
+  },
+});
+```
+
+<Note>You must pass Server Actions to the `actions` object.</Note>
+
+In this example, you define types for AI State and UI State, respectively.
+
+Next, wrap your application with your newly created context. With that, you can get and set AI and UI State across your entire application.
+
+```tsx filename='app/layout.tsx'
+import { type ReactNode } from 'react';
+import { AI } from './ai';
+
+export default function RootLayout({
+  children,
+}: Readonly<{ children: ReactNode }>) {
+  return (
+    <AI>
+      <html lang="en">
+        <body>{children}</body>
+      </html>
+    </AI>
+  );
+}
+```
+
+## Reading UI State in Client
+
+The UI state can be accessed in Client Components using the [`useUIState`](/docs/reference/ai-sdk-rsc/use-ui-state) hook provided by the RSC API. The hook returns the current UI state and a function to update the UI state like React's `useState`.
+
+```tsx filename='app/page.tsx'
+'use client';
+
+import { useUIState } from '@ai-sdk/rsc';
+
+export default function Page() {
+  const [messages, setMessages] = useUIState();
+
+  return (
+    <ul>
+      {messages.map(message => (
+        <li key={message.id}>{message.display}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## Reading AI State in Client
+
+The AI state can be accessed in Client Components using the [`useAIState`](/docs/reference/ai-sdk-rsc/use-ai-state) hook provided by the RSC API. The hook returns the current AI state.
+
+```tsx filename='app/page.tsx'
+'use client';
+
+import { useAIState } from '@ai-sdk/rsc';
+
+export default function Page() {
+  const [messages, setMessages] = useAIState();
+
+  return (
+    <ul>
+      {messages.map(message => (
+        <li key={message.id}>{message.content}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## Reading AI State on Server
+
+The AI State can be accessed within any Server Action provided to the `createAI` context using the [`getAIState`](/docs/reference/ai-sdk-rsc/get-ai-state) function. It returns the current AI state as a read-only value:
+
+```tsx filename='app/actions.ts'
+import { getAIState } from '@ai-sdk/rsc';
+
+export async function sendMessage(message: string) {
+  'use server';
+
+  const history = getAIState();
+
+  const response = await generateText({
+    model: __MODEL__,
+    messages: [...history, { role: 'user', content: message }],
+  });
+
+  return response;
+}
+```
+
+<Note>
+  Remember, you can only access state within actions that have been passed to
+  the `createAI` context within the `actions` key.
+</Note>
+
+## Updating AI State on Server
+
+The AI State can also be updated from within your Server Action with the [`getMutableAIState`](/docs/reference/ai-sdk-rsc/get-mutable-ai-state) function. This function is similar to `getAIState`, but it returns the state with methods to read and update it:
+
+```tsx filename='app/actions.ts'
+import { getMutableAIState } from '@ai-sdk/rsc';
+
+export async function sendMessage(message: string) {
+  'use server';
+
+  const history = getMutableAIState();
+
+  // Update the AI state with the new user message.
+  history.update([...history.get(), { role: 'user', content: message }]);
+
+  const response = await generateText({
+    model: __MODEL__,
+    messages: history.get(),
+  });
+
+  // Update the AI state again with the response from the model.
+  history.done([...history.get(), { role: 'assistant', content: response }]);
+
+  return response;
+}
+```
+
+<Note>
+  It is important to update the AI State with new responses using `.update()`
+  and `.done()` to keep the conversation history in sync.
+</Note>
+
+## Calling Server Actions from the Client
+
+To call the `sendMessage` action from the client, you can use the [`useActions`](/docs/reference/ai-sdk-rsc/use-actions) hook. The hook returns all the available Actions that were provided to `createAI`:
+
+```tsx filename='app/page.tsx'
+'use client';
+
+import { useActions, useUIState } from '@ai-sdk/rsc';
+import { AI } from './ai';
+
+export default function Page() {
+  const { sendMessage } = useActions<typeof AI>();
+  const [messages, setMessages] = useUIState();
+
+  const handleSubmit = async event => {
+    event.preventDefault();
+
+    setMessages([
+      ...messages,
+      { id: Date.now(), role: 'user', display: event.target.message.value },
+    ]);
+
+    const response = await sendMessage(event.target.message.value);
+
+    setMessages([
+      ...messages,
+      { id: Date.now(), role: 'assistant', display: response },
+    ]);
+  };
+
+  return (
+    <>
+      <ul>
+        {messages.map(message => (
+          <li key={message.id}>{message.display}</li>
+        ))}
+      </ul>
+      <form onSubmit={handleSubmit}>
+        <input type="text" name="message" />
+        <button type="submit">Send</button>
+      </form>
+    </>
+  );
+}
+```
+
+When the user submits a message, the `sendMessage` action is called with the message content. The response from the action is then added to the UI state, updating the displayed messages.
+
+<Note>
+  Important! Don't forget to update the UI State after you call your Server
+  Action otherwise the streamed component will not show in the UI.
+</Note>
+
+To learn more, check out this [example](/examples/next-app/state-management/ai-ui-states) on managing AI and UI state using `@ai-sdk/rsc`.
+
+---
+
+Next, you will learn how you can save and restore state with `@ai-sdk/rsc`.

package/docs/05-ai-sdk-rsc/03-saving-and-restoring-states.mdx

@@ -0,0 +1,105 @@
+---
+title: Saving and Restoring States
+description: Saving and restoring AI and UI states with onGetUIState and onSetAIState
+---
+
+# Saving and Restoring States
+
+<Note type="warning">
+  AI SDK RSC is currently experimental. We recommend using [AI SDK
+  UI](/docs/ai-sdk-ui/overview) for production. For guidance on migrating from
+  RSC to UI, see our [migration guide](/docs/ai-sdk-rsc/migrating-to-ui).
+</Note>
+
+AI SDK RSC provides convenient methods for saving and restoring AI and UI state. This is useful for saving the state of your application after every model generation, and restoring it when the user revisits the generations.
+
+## AI State
+
+### Saving AI state
+
+The AI state can be saved using the [`onSetAIState`](/docs/reference/ai-sdk-rsc/create-ai#on-set-ai-state) callback, which gets called whenever the AI state is updated. In the following example, you save the chat history to a database whenever the generation is marked as done.
+
+```tsx filename='app/ai.ts'
+export const AI = createAI<ServerMessage[], ClientMessage[]>({
+  actions: {
+    continueConversation,
+  },
+  onSetAIState: async ({ state, done }) => {
+    'use server';
+
+    if (done) {
+      saveChatToDB(state);
+    }
+  },
+});
+```
+
+### Restoring AI state
+
+The AI state can be restored using the [`initialAIState`](/docs/reference/ai-sdk-rsc/create-ai#initial-ai-state) prop passed to the context provider created by the [`createAI`](/docs/reference/ai-sdk-rsc/create-ai) function. In the following example, you restore the chat history from a database when the component is mounted.
+
+```tsx file='app/layout.tsx'
+import { ReactNode } from 'react';
+import { AI } from './ai';
+
+export default async function RootLayout({
+  children,
+}: Readonly<{ children: ReactNode }>) {
+  const chat = await loadChatFromDB();
+
+  return (
+    <html lang="en">
+      <body>
+        <AI initialAIState={chat}>{children}</AI>
+      </body>
+    </html>
+  );
+}
+```
+
+## UI State
+
+### Saving UI state
+
+The UI state cannot be saved directly, since the contents aren't yet serializable. Instead, you can use the AI state as proxy to store details about the UI state and use it to restore the UI state when needed.
+
+### Restoring UI state
+
+The UI state can be restored using the AI state as a proxy. In the following example, you restore the chat history from the AI state when the component is mounted. You use the [`onGetUIState`](/docs/reference/ai-sdk-rsc/create-ai#on-get-ui-state) callback to listen for SSR events and restore the UI state.
+
+```tsx filename='app/ai.ts'
+export const AI = createAI<ServerMessage[], ClientMessage[]>({
+  actions: {
+    continueConversation,
+  },
+  onGetUIState: async () => {
+    'use server';
+
+    const historyFromDB: ServerMessage[] = await loadChatFromDB();
+    const historyFromApp: ServerMessage[] = getAIState();
+
+    // If the history from the database is different from the
+    // history in the app, they're not in sync so return the UIState
+    // based on the history from the database
+
+    if (historyFromDB.length !== historyFromApp.length) {
+      return historyFromDB.map(({ role, content }) => ({
+        id: generateId(),
+        role,
+        display:
+          role === 'function' ? (
+            <Component {...JSON.parse(content)} />
+          ) : (
+            content
+          ),
+      }));
+    }
+  },
+});
+```
+
+To learn more, check out this [example](/examples/next-app/state-management/save-and-restore-states) that persists and restores states in your Next.js application.
+
+---
+
+Next, you will learn how you can use `@ai-sdk/rsc` functions like `useActions` and `useUIState` to create interactive, multistep interfaces.