ai 6.0.31 → 6.0.32

package/docs/04-ai-sdk-ui/04-generative-user-interfaces.mdx

@@ -0,0 +1,389 @@
+---
+title: Generative User Interfaces
+description: Learn how to build Generative UI with AI SDK UI.
+---
+
+# Generative User Interfaces
+
+Generative user interfaces (generative UI) is the process of allowing a large language model (LLM) to go beyond text and "generate UI". This creates a more engaging and AI-native experience for users.
+
+<WeatherSearch />
+
+At the core of generative UI are [ tools ](/docs/ai-sdk-core/tools-and-tool-calling), which are functions you provide to the model to perform specialized tasks like getting the weather in a location. The model can decide when and how to use these tools based on the context of the conversation.
+
+Generative UI is the process of connecting the results of a tool call to a React component. Here's how it works:
+
+1. You provide the model with a prompt or conversation history, along with a set of tools.
+2. Based on the context, the model may decide to call a tool.
+3. If a tool is called, it will execute and return data.
+4. This data can then be passed to a React component for rendering.
+
+By passing the tool results to React components, you can create a generative UI experience that's more engaging and adaptive to your needs.
+
+## Build a Generative UI Chat Interface
+
+Let's create a chat interface that handles text-based conversations and incorporates dynamic UI elements based on model responses.
+
+### Basic Chat Implementation
+
+Start with a basic chat implementation using the `useChat` hook:
+
+```tsx filename="app/page.tsx"
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import { useState } from 'react';
+
+export default function Page() {
+  const [input, setInput] = useState('');
+  const { messages, sendMessage } = useChat();
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    sendMessage({ text: input });
+    setInput('');
+  };
+
+  return (
+    <div>
+      {messages.map(message => (
+        <div key={message.id}>
+          <div>{message.role === 'user' ? 'User: ' : 'AI: '}</div>
+          <div>
+            {message.parts.map((part, index) => {
+              if (part.type === 'text') {
+                return <span key={index}>{part.text}</span>;
+              }
+              return null;
+            })}
+          </div>
+        </div>
+      ))}
+
+      <form onSubmit={handleSubmit}>
+        <input
+          value={input}
+          onChange={e => setInput(e.target.value)}
+          placeholder="Type a message..."
+        />
+        <button type="submit">Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+To handle the chat requests and model responses, set up an API route:
+
+```ts filename="app/api/chat/route.ts"
+import { streamText, convertToModelMessages, UIMessage, stepCountIs } from 'ai';
+__PROVIDER_IMPORT__;
+
+export async function POST(request: Request) {
+  const { messages }: { messages: UIMessage[] } = await request.json();
+
+  const result = streamText({
+    model: __MODEL__,
+    system: 'You are a friendly assistant!',
+    messages: await convertToModelMessages(messages),
+    stopWhen: stepCountIs(5),
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+This API route uses the `streamText` function to process chat messages and stream the model's responses back to the client.
+
+### Create a Tool
+
+Before enhancing your chat interface with dynamic UI elements, you need to create a tool and corresponding React component. A tool will allow the model to perform a specific action, such as fetching weather information.
+
+Create a new file called `ai/tools.ts` with the following content:
+
+```ts filename="ai/tools.ts"
+import { tool as createTool } from 'ai';
+import { z } from 'zod';
+
+export const weatherTool = createTool({
+  description: 'Display the weather for a location',
+  inputSchema: z.object({
+    location: z.string().describe('The location to get the weather for'),
+  }),
+  execute: async function ({ location }) {
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    return { weather: 'Sunny', temperature: 75, location };
+  },
+});
+
+export const tools = {
+  displayWeather: weatherTool,
+};
+```
+
+In this file, you've created a tool called `weatherTool`. This tool simulates fetching weather information for a given location. This tool will return simulated data after a 2-second delay. In a real-world application, you would replace this simulation with an actual API call to a weather service.
+
+### Update the API Route
+
+Update the API route to include the tool you've defined:
+
+```ts filename="app/api/chat/route.ts" highlight="3,8,14"
+import { streamText, convertToModelMessages, UIMessage, stepCountIs } from 'ai';
+__PROVIDER_IMPORT__;
+import { tools } from '@/ai/tools';
+
+export async function POST(request: Request) {
+  const { messages }: { messages: UIMessage[] } = await request.json();
+
+  const result = streamText({
+    model: __MODEL__,
+    system: 'You are a friendly assistant!',
+    messages: await convertToModelMessages(messages),
+    stopWhen: stepCountIs(5),
+    tools,
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+Now that you've defined the tool and added it to your `streamText` call, let's build a React component to display the weather information it returns.
+
+### Create UI Components
+
+Create a new file called `components/weather.tsx`:
+
+```tsx filename="components/weather.tsx"
+type WeatherProps = {
+  temperature: number;
+  weather: string;
+  location: string;
+};
+
+export const Weather = ({ temperature, weather, location }: WeatherProps) => {
+  return (
+    <div>
+      <h2>Current Weather for {location}</h2>
+      <p>Condition: {weather}</p>
+      <p>Temperature: {temperature}°C</p>
+    </div>
+  );
+};
+```
+
+This component will display the weather information for a given location. It takes three props: `temperature`, `weather`, and `location` (exactly what the `weatherTool` returns).
+
+### Render the Weather Component
+
+Now that you have your tool and corresponding React component, let's integrate them into your chat interface. You'll render the Weather component when the model calls the weather tool.
+
+To check if the model has called a tool, you can check the `parts` array of the UIMessage object for tool-specific parts. In AI SDK 5.0, tool parts use typed naming: `tool-${toolName}` instead of generic types.
+
+Update your `page.tsx` file:
+
+```tsx filename="app/page.tsx" highlight="4,9,14-15,19-46"
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import { useState } from 'react';
+import { Weather } from '@/components/weather';
+
+export default function Page() {
+  const [input, setInput] = useState('');
+  const { messages, sendMessage } = useChat();
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    sendMessage({ text: input });
+    setInput('');
+  };
+
+  return (
+    <div>
+      {messages.map(message => (
+        <div key={message.id}>
+          <div>{message.role === 'user' ? 'User: ' : 'AI: '}</div>
+          <div>
+            {message.parts.map((part, index) => {
+              if (part.type === 'text') {
+                return <span key={index}>{part.text}</span>;
+              }
+
+              if (part.type === 'tool-displayWeather') {
+                switch (part.state) {
+                  case 'input-available':
+                    return <div key={index}>Loading weather...</div>;
+                  case 'output-available':
+                    return (
+                      <div key={index}>
+                        <Weather {...part.output} />
+                      </div>
+                    );
+                  case 'output-error':
+                    return <div key={index}>Error: {part.errorText}</div>;
+                  default:
+                    return null;
+                }
+              }
+
+              return null;
+            })}
+          </div>
+        </div>
+      ))}
+
+      <form onSubmit={handleSubmit}>
+        <input
+          value={input}
+          onChange={e => setInput(e.target.value)}
+          placeholder="Type a message..."
+        />
+        <button type="submit">Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+In this updated code snippet, you:
+
+1. Use manual input state management with `useState` instead of the built-in `input` and `handleInputChange`.
+2. Use `sendMessage` instead of `handleSubmit` to send messages.
+3. Check the `parts` array of each message for different content types.
+4. Handle tool parts with type `tool-displayWeather` and their different states (`input-available`, `output-available`, `output-error`).
+
+This approach allows you to dynamically render UI components based on the model's responses, creating a more interactive and context-aware chat experience.
+
+## Expanding Your Generative UI Application
+
+You can enhance your chat application by adding more tools and components, creating a richer and more versatile user experience. Here's how you can expand your application:
+
+### Adding More Tools
+
+To add more tools, simply define them in your `ai/tools.ts` file:
+
+```ts
+// Add a new stock tool
+export const stockTool = createTool({
+  description: 'Get price for a stock',
+  inputSchema: z.object({
+    symbol: z.string().describe('The stock symbol to get the price for'),
+  }),
+  execute: async function ({ symbol }) {
+    // Simulated API call
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    return { symbol, price: 100 };
+  },
+});
+
+// Update the tools object
+export const tools = {
+  displayWeather: weatherTool,
+  getStockPrice: stockTool,
+};
+```
+
+Now, create a new file called `components/stock.tsx`:
+
+```tsx
+type StockProps = {
+  price: number;
+  symbol: string;
+};
+
+export const Stock = ({ price, symbol }: StockProps) => {
+  return (
+    <div>
+      <h2>Stock Information</h2>
+      <p>Symbol: {symbol}</p>
+      <p>Price: ${price}</p>
+    </div>
+  );
+};
+```
+
+Finally, update your `page.tsx` file to include the new Stock component:
+
+```tsx
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import { useState } from 'react';
+import { Weather } from '@/components/weather';
+import { Stock } from '@/components/stock';
+
+export default function Page() {
+  const [input, setInput] = useState('');
+  const { messages, sendMessage } = useChat();
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    sendMessage({ text: input });
+    setInput('');
+  };
+
+  return (
+    <div>
+      {messages.map(message => (
+        <div key={message.id}>
+          <div>{message.role}</div>
+          <div>
+            {message.parts.map((part, index) => {
+              if (part.type === 'text') {
+                return <span key={index}>{part.text}</span>;
+              }
+
+              if (part.type === 'tool-displayWeather') {
+                switch (part.state) {
+                  case 'input-available':
+                    return <div key={index}>Loading weather...</div>;
+                  case 'output-available':
+                    return (
+                      <div key={index}>
+                        <Weather {...part.output} />
+                      </div>
+                    );
+                  case 'output-error':
+                    return <div key={index}>Error: {part.errorText}</div>;
+                  default:
+                    return null;
+                }
+              }
+
+              if (part.type === 'tool-getStockPrice') {
+                switch (part.state) {
+                  case 'input-available':
+                    return <div key={index}>Loading stock price...</div>;
+                  case 'output-available':
+                    return (
+                      <div key={index}>
+                        <Stock {...part.output} />
+                      </div>
+                    );
+                  case 'output-error':
+                    return <div key={index}>Error: {part.errorText}</div>;
+                  default:
+                    return null;
+                }
+              }
+
+              return null;
+            })}
+          </div>
+        </div>
+      ))}
+
+      <form onSubmit={handleSubmit}>
+        <input
+          type="text"
+          value={input}
+          onChange={e => setInput(e.target.value)}
+        />
+        <button type="submit">Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+By following this pattern, you can continue to add more tools and components, expanding the capabilities of your Generative UI application.

package/docs/04-ai-sdk-ui/05-completion.mdx

@@ -0,0 +1,186 @@
+---
+title: Completion
+description: Learn how to use the useCompletion hook.
+---
+
+# Completion
+
+The `useCompletion` hook allows you to create a user interface to handle text completions in your application. It enables the streaming of text completions from your AI provider, manages the state for chat input, and updates the UI automatically as new messages are received.
+
+<Note>
+  The `useCompletion` hook is now part of the `@ai-sdk/react` package.
+</Note>
+
+In this guide, you will learn how to use the `useCompletion` hook in your application to generate text completions and stream them in real-time to your users.
+
+## Example
+
+```tsx filename='app/page.tsx'
+'use client';
+
+import { useCompletion } from '@ai-sdk/react';
+
+export default function Page() {
+  const { completion, input, handleInputChange, handleSubmit } = useCompletion({
+    api: '/api/completion',
+  });
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        name="prompt"
+        value={input}
+        onChange={handleInputChange}
+        id="input"
+      />
+      <button type="submit">Submit</button>
+      <div>{completion}</div>
+    </form>
+  );
+}
+```
+
+```ts filename='app/api/completion/route.ts'
+import { streamText } from 'ai';
+__PROVIDER_IMPORT__;
+
+// Allow streaming responses up to 30 seconds
+export const maxDuration = 30;
+
+export async function POST(req: Request) {
+  const { prompt }: { prompt: string } = await req.json();
+
+  const result = streamText({
+    model: __MODEL__,
+    prompt,
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+In the `Page` component, the `useCompletion` hook will request to your AI provider endpoint whenever the user submits a message. The completion is then streamed back in real-time and displayed in the UI.
+
+This enables a seamless text completion experience where the user can see the AI response as soon as it is available, without having to wait for the entire response to be received.
+
+## Customized UI
+
+`useCompletion` also provides ways to manage the prompt via code, show loading and error states, and update messages without being triggered by user interactions.
+
+### Loading and error states
+
+To show a loading spinner while the chatbot is processing the user's message, you can use the `isLoading` state returned by the `useCompletion` hook:
+
+```tsx
+const { isLoading, ... } = useCompletion()
+
+return(
+  <>
+    {isLoading ? <Spinner /> : null}
+  </>
+)
+```
+
+Similarly, the `error` state reflects the error object thrown during the fetch request. It can be used to display an error message, or show a toast notification:
+
+```tsx
+const { error, ... } = useCompletion()
+
+useEffect(() => {
+  if (error) {
+    toast.error(error.message)
+  }
+}, [error])
+
+// Or display the error message in the UI:
+return (
+  <>
+    {error ? <div>{error.message}</div> : null}
+  </>
+)
+```
+
+### Controlled input
+
+In the initial example, we have `handleSubmit` and `handleInputChange` callbacks that manage the input changes and form submissions. These are handy for common use cases, but you can also use uncontrolled APIs for more advanced scenarios such as form validation or customized components.
+
+The following example demonstrates how to use more granular APIs like `setInput` with your custom input and submit button components:
+
+```tsx
+const { input, setInput } = useCompletion();
+
+return (
+  <>
+    <MyCustomInput value={input} onChange={value => setInput(value)} />
+  </>
+);
+```
+
+### Cancelation
+
+It's also a common use case to abort the response message while it's still streaming back from the AI provider. You can do this by calling the `stop` function returned by the `useCompletion` hook.
+
+```tsx
+const { stop, isLoading, ... } = useCompletion()
+
+return (
+  <>
+    <button onClick={stop} disabled={!isLoading}>Stop</button>
+  </>
+)
+```
+
+When the user clicks the "Stop" button, the fetch request will be aborted. This avoids consuming unnecessary resources and improves the UX of your application.
+
+### Throttling UI Updates
+
+<Note>This feature is currently only available for React.</Note>
+
+By default, the `useCompletion` hook will trigger a render every time a new chunk is received.
+You can throttle the UI updates with the `experimental_throttle` option.
+
+```tsx filename="page.tsx" highlight="2-3"
+const { completion, ... } = useCompletion({
+  // Throttle the completion and data updates to 50ms:
+  experimental_throttle: 50
+})
+```
+
+## Event Callbacks
+
+`useCompletion` also provides optional event callbacks that you can use to handle different stages of the chatbot lifecycle. These callbacks can be used to trigger additional actions, such as logging, analytics, or custom UI updates.
+
+```tsx
+const { ... } = useCompletion({
+  onResponse: (response: Response) => {
+    console.log('Received response from server:', response)
+  },
+  onFinish: (prompt: string, completion: string) => {
+    console.log('Finished streaming completion:', completion)
+  },
+  onError: (error: Error) => {
+    console.error('An error occurred:', error)
+  },
+})
+```
+
+It's worth noting that you can abort the processing by throwing an error in the `onResponse` callback. This will trigger the `onError` callback and stop the message from being appended to the chat UI. This can be useful for handling unexpected responses from the AI provider.
+
+## Configure Request Options
+
+By default, the `useCompletion` hook sends a HTTP POST request to the `/api/completion` endpoint with the prompt as part of the request body. You can customize the request by passing additional options to the `useCompletion` hook:
+
+```tsx
+const { messages, input, handleInputChange, handleSubmit } = useCompletion({
+  api: '/api/custom-completion',
+  headers: {
+    Authorization: 'your_token',
+  },
+  body: {
+    user_id: '123',
+  },
+  credentials: 'same-origin',
+});
+```
+
+In this example, the `useCompletion` hook sends a POST request to the `/api/completion` endpoint with the specified headers, additional body fields, and credentials for that fetch request. On your server side, you can handle the request with these additional information.