docs/pages/docs/api-reference/_meta.json

@@ -1,18 +1,10 @@
 {
+  "generative-ui": "Generative UI",
+  "providers": "Providers",
   "use-assistant": "experimental_useAssistant",
   "use-chat": "useChat",
   "use-completion": "useCompletion",
   "ai-stream": "AIStream",
-  "anthropic-stream": "AnthropicStream",
-  "aws-bedrock-stream": "AWSBedrock*Stream",
-  "cohere-stream": "CohereStream",
-  "google-generative-ai-stream": "GoogleGenerativeAIStream",
-  "huggingface-stream": "HuggingFaceStream",
-  "langchain-stream": "LangChainStream",
-  "openai-stream": "OpenAIStream",
-  "mistral-stream": "MistralStream",
-  "replicate-stream": "ReplicateStream",
-  "inkeep-stream": "InkeepStream",
   "stream-data": "experimental_StreamData",
   "streaming-text-response": "StreamingTextResponse",
   "stream-to-response": "streamToResponse",

docs/pages/docs/api-reference/generative-ui/_meta.json

@@ -0,0 +1,2 @@
+{
+}

docs/pages/docs/api-reference/create-ai.mdx → docs/pages/docs/api-reference/generative-ui/create-ai.mdx

@@ -10,21 +10,24 @@ import { Tabs, Tab } from 'nextra-theme-docs';
 
 ## `createAI`
 
-`createAI` is a function that creates a new `ai/rsc` instance.
+`createAI` creates a new `ai/rsc` instance.
 
 ## Parameters
 
-### `AIState`
+### `initialAIState`: [`AIState`](/docs/concepts/ai-rsc#aistate)
 
-`AIState` is a JSON representation of all the context the LLM needs to read. Usually for a chat app, `AIState` contains the textual conversation history between the user and the assistant. In practice, it can also be used to store other values and meta information such as `createdAt` of each message. `AIState` by default, can be accessed/modified on both Server and Client.
+`AIState` is a JSON representation of all the context the LLM needs to read. Usually for a chat app, `AIState` contains the textual conversation history between the user and the assistant. It can also be used to store other values and information such as a `createdAt` field for each message, or a `chatId` field besides all the messages.
+`AIState` by default, can be accessed/modified on both Server and Client, so the values must be serializable.
 
-### `UIState`
+### `initialUIState`: [`UIState`](/docs/concepts/ai-rsc#uistate)
 
-`UIState` is what the application uses to display the UI. It is a fully client-side state (very similar to `useState`) and can keep data and UI elements returned by the LLM. This state can be anything, but can't be accessed on the server.
+`UIState` is what the application uses to display the UI. It is a client-side state (very similar to `useState`) and contains data and UI elements returned by the LLM and your Server Actions. Unlike `AIState`, `UIState` can only be accessed on the client,
+but this means that it can contain non-serializable values such as functions and React nodes.
 
 ## Returns
 
-The method returns an `<AI>` instance, which is a provider component that is used to wrap a part of your component tree and pass the context value down the tree. Any component that needs the context value can access it, no matter how deep it is in the component tree.
+The method returns an `<AI>` context provider that can be used to wrap the parts of your tree that use
+the client-side hooks [`useAIState`](/docs/api-reference/use-ai-state) and [`useUIState`](/docs/api-reference/use-ui-state).
 
 ## Example
 

docs/pages/docs/api-reference/get-ai-state.mdx → docs/pages/docs/api-reference/generative-ui/get-ai-state.mdx

@@ -10,7 +10,7 @@ import { Tabs, Tab } from 'nextra-theme-docs';
 
 ## `getAIState`
 
-`getAIState` is called within a Server Action to get the current [AI state](../concepts/ai-rsc#ai-state). If `key` is provided, it will return the value of the specified key in the AI state if it's an object. If it's not an object, it will throw an error.
+`getAIState` is called within a Server Action to get the current [AI state](/docs/concepts/ai-rsc#ai-state). If `key` is provided, it will return the value of the specified key in the AI state if it's an object. If it's not an object, it will throw an error.
 
 The AI state returned is read-only so if you want to make updates to it, you should use [getMutableAIState](./get-mutable-ai-state).
 

docs/pages/docs/api-reference/get-mutable-ai-state.mdx → docs/pages/docs/api-reference/generative-ui/get-mutable-ai-state.mdx

@@ -10,7 +10,7 @@ import { Tabs, Tab } from 'nextra-theme-docs';
 
 ## `getMutableAIState`
 
-`getMutableAIState` is called within a Server Action to make updates to the [AI state](../concepts/ai-rsc#aistate).
+`getMutableAIState` is called within a Server Action to make updates to the [AI state](/docs/concepts/ai-rsc#aistate).
 
 ## Methods
 
@@ -24,7 +24,7 @@ The `update` method updates the AI state with a new value.
 
 ### `done`
 
-You must call `.done()` when you're finished updating the AI state.
+You must call `.done()` when you're finished updating the AI state. This "seals" the AI state and marks it ready to be synced with the client as well as external storage.
 
 ## Examples
 

docs/pages/docs/api-reference/generative-ui/render.mdx

@@ -0,0 +1,221 @@
+---
+title: render
+---
+
+import { Callout, Tabs, Tab, Steps } from 'nextra-theme-docs';
+import { UIPreviewCard, Card } from '@/components/home/card';
+import { Browser } from '@/components/home/browser';
+import { EventPlanning } from '@/components/home/event-planning';
+import { Searching } from '@/components/home/searching';
+
+# render()
+
+The `render` function is a powerful helper function to create a streamable UIs from an LLM response.
+
+Note: this function only supports OpenAI SDK-compatible models/providers.
+
+## Streaming Text
+
+By default, `render` will stream the text content of the LLM response wrapped with a React Fragment `<>` tag.
+
+<Tabs items={['Next.js (App Router)']}>
+    <Tab>
+    ```tsx filename="app/actions.tsx"
+    import { OpenAI } from "openai";
+    import { render } from "ai/rsc";
+
+    const openai = new OpenAI();
+
+    async function submitUserMessage(content: string) {
+      "use server";
+
+      const aiState = getMutableAIState();
+
+      // Update AI state with new message.
+      aiState.update([
+        ...aiState.get(),
+        {
+          role: "user",
+          content,
+        },
+      ]);
+
+      // render() returns a stream of UI components
+      const ui = render({
+        model: 'gpt-4-turbo',
+        provider: openai,
+        // You may want to construct messages from your AI state
+        messages: [
+          { role: 'system', content: 'You are a flight assistant' },
+          { role: 'user', content: userInput }
+        ],
+      })
+
+      return {
+        id: Date.now(),
+        // You can render ui on the client with something like `{message.display}`
+        display: ui
+      };
+    }
+    ```
+    </Tab>
+
+</Tabs>
+
+You can also customize the React component streamed for text responses by using the `text` key.
+
+<Tabs items={['Next.js (App Router)']}>
+    <Tab>
+    ```tsx filename="app/actions.tsx"
+    async function submitUserMessage(content: string) {
+      "use server";
+
+      // ... same as above
+
+      const ui = render({
+
+        // ... same as above
+
+        // `text` is called when an AI returns a text response (as opposed to a tool call)
+        text: ({ content, done }) => {
+          // text can be streamed from the LLM, but we only want to close the stream with .done() when its completed.
+          // done() marks the state as available for the client to access
+          if (done) {
+            aiState.done({
+              ...aiState.get(),
+              {
+                role: "assistant",
+                content
+              }
+            })
+          }
+
+          return <div>{content}</div>
+        }
+      })
+
+      return {
+        id: Date.now(),
+        // You can render UI on the client with something like `{message.display}` and the
+        // result yielded in`text` will be displayed on the client and streamed
+        // in as it is returned from the model.
+        display: ui
+      };
+    }
+    ```
+    </Tab>
+
+</Tabs>
+
+## Tools and Function Calls with React Server Components
+
+The `render` function allows you to map [OpenAI-compatible model/providers with Function Calls and Assistants Tools](https://platform.openai.com/docs/guides/function-calling) to [React Server Components](https://vercel.com/blog/understanding-react-server-components) using the `tools` key.
+Note that both `text` and `render` can be specified at the same time, with `text` being the fallback for when no function is called by the model.
+
+If you use other models, you can [prompt engineer](docs/concepts/prompt-engineering) them
+into returning structured data and manually handle the streaming UI with [`createStreamableUI`](./create-streamable-ui) and [`createStreamableValue`](./create-streamable-value).
+
+Tool/Function Schema definitions use [Zod](https://zod.dev/) schemas to specify the function parameters and return values. `render` will automatically validate the schemas and throw an error if the function call is invalid.
+
+To install Zod, run:
+
+```sh
+pnpm install zod
+```
+
+Each tool specified also accepts a nested `render` function for returning React components. There are a few different signatures you can use:
+
+- `() => ReactNode` - a function that returns a React Node
+- `async () => ReactNode` - an async function that returns a React Node
+- `function* () {}` - an generator function that returns a React Node.
+- `async function* () {}` - an async generator function that returns a React Node.
+
+If you use a generator signature, you can `yield` React Nodes and they will be sent as distinct updates to the client. This is very powerful for loading states and agentic, multi-step behaviors.
+
+<Tabs items={['Next.js (App Router)']}>
+    <Tab>
+    ```tsx filename="app/actions.tsx"
+    import { OpenAI } from "openai";
+    import { render } from "ai/rsc";
+    import { z } from "zod";
+
+    const openai = new OpenAI();
+
+    async function submitUserMessage(content: string) {
+      "use server";
+
+      const aiState = getMutableAIState();
+
+      // Update AI state with new message.
+      aiState.update([
+        ...aiState.get(),
+        {
+          role: "user",
+          content,
+        },
+      ]);
+
+      // render() returns a stream of UI components
+      const ui = render({
+        model: 'gpt-4-turbo',
+        provider: openai,
+        // You may want to construct messages from your AI state
+        messages: [
+          { role: 'system', content: 'You are a flight assistant' },
+          { role: 'user', content: userInput }
+        ],
+        // `text` is called when an AI returns a text response (as opposed to a tool call)
+        text: ({ content, done }) => {
+          // text can be streamed from the LLM, but we only want to close the stream with .done() when its completed.
+          // done() marks the state as available for the client to access
+          if (done) {
+            aiState.done({
+              ...aiState.get(),
+              {
+                role: "assistant",
+                content
+              }
+            })
+          }
+
+          return <div>{content}</div>
+        }
+        tools: {
+          get_flight_info: {
+            description: 'Get the information for a flight',
+            parameters: z.object({
+              flightNumber: z.string().describe('the number of the flight')
+            }).required(),
+            // flightNumber is inferred from the parameters passed above
+            render: async function* ({ flightNumber }) {
+              yield <Spinner/>
+              const flightInfo = await getFlightInfo(flightNumber)
+
+              aiState.done([
+                ...aiState.get(),
+                {
+                  role: "function",
+                  name: "get_flight_info",
+                  // Content can be any string to provide context to the LLM in the rest of the conversation
+                  content: JSON.stringify(flightInfo),
+                }
+              ]);
+
+              return <FlightCard flightInfo={flightInfo} />
+            }
+          }
+        }
+      })
+
+      return {
+        id: Date.now(),
+        // You can render UI on the client with something like `{message.display}` and the
+        // result yielded in `render` or `text` will be displayed on the client and streamed
+        // in as it is returned from the model.
+        display: ui
+      };
+    }
+    ```
+    </Tab>
+
+</Tabs>

docs/pages/docs/api-reference/generative-ui/use-actions.mdx

@@ -0,0 +1,58 @@
+---
+title: useActions
+layout:
+  toc: false
+---
+
+import { Tabs, Tab } from 'nextra-theme-docs';
+
+# useActions
+
+## `useActions`
+
+`useActions` is a hook to help you access your Server Actions from the client. It’s required to access these server actions via this hook (because we patched these actions when they’re passing through this context), and if you directly import the actions instead of using useActions, you might run into the current issue of “cannot find client component.”
+This is particularly useful for building interfaces that require user interactions with the server.
+
+<Tabs items={['Next.js (App Router)']}>
+  <Tab>
+    ```tsx filename="app/action.tsx"
+    async function viewStock(symbol: string) {
+      "use server"
+
+      const price = getStockPrice(symbol);
+      const uiStream = createUIStream();
+
+      uiStream.close(
+        <div>
+          {symbol}: {price}
+        </div>
+      );
+
+      return {
+        id: Date.now(),
+        display: uiStream.value,
+      };
+    }
+    ```
+
+```tsx filename="app/components/button.tsx"
+export function Button({ setMessages }) {
+  const { viewStock } = useActions();
+  const [messages, setMessages] = useUIState();
+
+  return (
+    <button
+      onClick={async () => {
+        const newMessage = await viewStock('NVDA');
+
+        setMessages((currentMessages: any) => [...currentMessages, newMessage]);
+      }}
+    >
+      Purchase
+    </button>
+  );
+}
+```
+
+</Tab>
+</Tabs>