ai 6.0.30 → 6.0.32

package/docs/06-advanced/05-multiple-streamables.mdx

@@ -0,0 +1,68 @@
+---
+title: Multiple Streamables
+description: Learn to handle multiple streamables in your application.
+---
+
+# Multiple Streams
+
+## Multiple Streamable UIs
+
+The AI SDK RSC APIs allow you to compose and return any number of streamable UIs, along with other data, in a single request. This can be useful when you want to decouple the UI into smaller components and stream them separately.
+
+```tsx file='app/actions.tsx'
+'use server';
+
+import { createStreamableUI } from '@ai-sdk/rsc';
+
+export async function getWeather() {
+  const weatherUI = createStreamableUI();
+  const forecastUI = createStreamableUI();
+
+  weatherUI.update(<div>Loading weather...</div>);
+  forecastUI.update(<div>Loading forecast...</div>);
+
+  getWeatherData().then(weatherData => {
+    weatherUI.done(<div>{weatherData}</div>);
+  });
+
+  getForecastData().then(forecastData => {
+    forecastUI.done(<div>{forecastData}</div>);
+  });
+
+  // Return both streamable UIs and other data fields.
+  return {
+    requestedAt: Date.now(),
+    weather: weatherUI.value,
+    forecast: forecastUI.value,
+  };
+}
+```
+
+The client side code is similar to the previous example, but the [tool call](/docs/ai-sdk-core/tools-and-tool-calling) will return the new data structure with the weather and forecast UIs. Depending on the speed of getting weather and forecast data, these two components might be updated independently.
+
+## Nested Streamable UIs
+
+You can stream UI components within other UI components. This allows you to create complex UIs that are built up from smaller, reusable components. In the example below, we pass a `historyChart` streamable as a prop to a `StockCard` component. The StockCard can render the `historyChart` streamable, and it will automatically update as the server responds with new data.
+
+```tsx file='app/actions.tsx'
+async function getStockHistoryChart({ symbol: string }) {
+  'use server';
+
+  const ui = createStreamableUI(<Spinner />);
+
+  // We need to wrap this in an async IIFE to avoid blocking.
+  (async () => {
+    const price = await getStockPrice({ symbol });
+
+    // Show a spinner as the history chart for now.
+    const historyChart = createStreamableUI(<Spinner />);
+    ui.done(<StockCard historyChart={historyChart.value} price={price} />);
+
+    // Getting the history data and then update that part of the UI.
+    const historyData = await fetch('https://my-stock-data-api.com');
+    historyChart.done(<HistoryChart data={historyData} />);
+  })();
+
+  return ui;
+}
+```

package/docs/06-advanced/06-rate-limiting.mdx

@@ -0,0 +1,60 @@
+---
+title: Rate Limiting
+description: Learn how to rate limit your application.
+---
+
+# Rate Limiting
+
+Rate limiting helps you protect your APIs from abuse. It involves setting a
+maximum threshold on the number of requests a client can make within a
+specified timeframe. This simple technique acts as a gatekeeper,
+preventing excessive usage that can degrade service performance and incur
+unnecessary costs.
+
+## Rate Limiting with Vercel KV and Upstash Ratelimit
+
+In this example, you will protect an API endpoint using [Vercel KV](https://vercel.com/storage/kv)
+and [Upstash Ratelimit](https://github.com/upstash/ratelimit).
+
+```tsx filename='app/api/generate/route.ts'
+import kv from '@vercel/kv';
+import { streamText } from 'ai';
+__PROVIDER_IMPORT__;
+import { Ratelimit } from '@upstash/ratelimit';
+import { NextRequest } from 'next/server';
+
+// Allow streaming responses up to 30 seconds
+export const maxDuration = 30;
+
+// Create Rate limit
+const ratelimit = new Ratelimit({
+  redis: kv,
+  limiter: Ratelimit.fixedWindow(5, '30s'),
+});
+
+export async function POST(req: NextRequest) {
+  // call ratelimit with request ip
+  const ip = req.ip ?? 'ip';
+  const { success, remaining } = await ratelimit.limit(ip);
+
+  // block the request if unsuccessfull
+  if (!success) {
+    return new Response('Ratelimited!', { status: 429 });
+  }
+
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: __MODEL__,
+    messages,
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+## Simplify API Protection
+
+With Vercel KV and Upstash Ratelimit, it is possible to protect your APIs
+from such attacks with ease. To learn more about how Ratelimit works and
+how it can be configured to your needs, see [Ratelimit Documentation](https://upstash.com/docs/oss/sdks/ts/ratelimit/overview).

package/docs/06-advanced/07-rendering-ui-with-language-models.mdx

@@ -0,0 +1,213 @@
+---
+title: Rendering UI with Language Models
+description: Rendering UI with Language Models
+---
+
+# Rendering User Interfaces with Language Models
+
+Language models generate text, so at first it may seem like you would only need to render text in your application.
+
+```tsx highlight="16" filename="app/actions.tsx"
+const text = generateText({
+  model: __MODEL__,
+  system: 'You are a friendly assistant',
+  prompt: 'What is the weather in SF?',
+  tools: {
+    getWeather: {
+      description: 'Get the weather for a location',
+      parameters: z.object({
+        city: z.string().describe('The city to get the weather for'),
+        unit: z
+          .enum(['C', 'F'])
+          .describe('The unit to display the temperature in'),
+      }),
+      execute: async ({ city, unit }) => {
+        const weather = getWeather({ city, unit });
+        return `It is currently ${weather.value}°${unit} and ${weather.description} in ${city}!`;
+      },
+    },
+  },
+});
+```
+
+Above, the language model is passed a [tool](/docs/ai-sdk-core/tools-and-tool-calling) called `getWeather` that returns the weather information as text. However, instead of returning text, if you return a JSON object that represents the weather information, you can use it to render a React component instead.
+
+```tsx highlight="18-23" filename="app/action.ts"
+const text = generateText({
+  model: __MODEL__,
+  system: 'You are a friendly assistant',
+  prompt: 'What is the weather in SF?',
+  tools: {
+    getWeather: {
+      description: 'Get the weather for a location',
+      parameters: z.object({
+        city: z.string().describe('The city to get the weather for'),
+        unit: z
+          .enum(['C', 'F'])
+          .describe('The unit to display the temperature in'),
+      }),
+      execute: async ({ city, unit }) => {
+        const weather = getWeather({ city, unit });
+        const { temperature, unit, description, forecast } = weather;
+
+        return {
+          temperature,
+          unit,
+          description,
+          forecast,
+        };
+      },
+    },
+  },
+});
+```
+
+Now you can use the object returned by the `getWeather` function to conditionally render a React component `<WeatherCard/>` that displays the weather information by passing the object as props.
+
+```tsx filename="app/page.tsx"
+return (
+  <div>
+    {messages.map(message => {
+      if (message.role === 'function') {
+        const { name, content } = message
+        const { temperature, unit, description, forecast } = content;
+
+        return (
+          <WeatherCard
+            weather={{
+              temperature: 47,
+              unit: 'F',
+              description: 'sunny'
+              forecast,
+            }}
+          />
+        )
+      }
+    })}
+  </div>
+)
+```
+
+Here's a little preview of what that might look like.
+
+<div className="not-prose flex flex-col2">
+  <CardPlayer
+    type="weather"
+    title="Weather"
+    description="An example of an assistant that renders the weather information in a streamed component."
+  />
+</div>
+
+Rendering interfaces as part of language model generations elevates the user experience of your application, allowing people to interact with language models beyond text.
+
+They also make it easier for you to interpret [sequential tool calls](/docs/ai-sdk-rsc/multistep-interfaces) that take place in multiple steps and help identify and debug where the model reasoned incorrectly.
+
+## Rendering Multiple User Interfaces
+
+To recap, an application has to go through the following steps to render user interfaces as part of model generations:
+
+1. The user prompts the language model.
+2. The language model generates a response that includes a tool call.
+3. The tool call returns a JSON object that represents the user interface.
+4. The response is sent to the client.
+5. The client receives the response and checks if the latest message was a tool call.
+6. If it was a tool call, the client renders the user interface based on the JSON object returned by the tool call.
+
+Most applications have multiple tools that are called by the language model, and each tool can return a different user interface.
+
+For example, a tool that searches for courses can return a list of courses, while a tool that searches for people can return a list of people. As this list grows, the complexity of your application will grow as well and it can become increasingly difficult to manage these user interfaces.
+
+```tsx filename='app/page.tsx'
+{
+  message.role === 'tool' ? (
+    message.name === 'api-search-course' ? (
+      <Courses courses={message.content} />
+    ) : message.name === 'api-search-profile' ? (
+      <People people={message.content} />
+    ) : message.name === 'api-meetings' ? (
+      <Meetings meetings={message.content} />
+    ) : message.name === 'api-search-building' ? (
+      <Buildings buildings={message.content} />
+    ) : message.name === 'api-events' ? (
+      <Events events={message.content} />
+    ) : message.name === 'api-meals' ? (
+      <Meals meals={message.content} />
+    ) : null
+  ) : (
+    <div>{message.content}</div>
+  );
+}
+```
+
+## Rendering User Interfaces on the Server
+
+The **AI SDK RSC (`@ai-sdk/rsc`)** takes advantage of RSCs to solve the problem of managing all your React components on the client side, allowing you to render React components on the server and stream them to the client.
+
+Rather than conditionally rendering user interfaces on the client based on the data returned by the language model, you can directly stream them from the server during a model generation.
+
+```tsx highlight="3,22-31,38" filename="app/action.ts"
+import { createStreamableUI } from '@ai-sdk/rsc'
+
+const uiStream = createStreamableUI();
+
+const text = generateText({
+  model: __MODEL__,
+  system: 'you are a friendly assistant'
+  prompt: 'what is the weather in SF?'
+  tools: {
+    getWeather: {
+      description: 'Get the weather for a location',
+      parameters: z.object({
+        city: z.string().describe('The city to get the weather for'),
+        unit: z
+          .enum(['C', 'F'])
+          .describe('The unit to display the temperature in')
+      }),
+      execute: async ({ city, unit }) => {
+        const weather = getWeather({ city, unit })
+        const { temperature, unit, description, forecast } = weather
+
+        uiStream.done(
+          <WeatherCard
+            weather={{
+              temperature: 47,
+              unit: 'F',
+              description: 'sunny'
+              forecast,
+            }}
+          />
+        )
+      }
+    }
+  }
+})
+
+return {
+  display: uiStream.value
+}
+```
+
+The [`createStreamableUI`](/docs/reference/ai-sdk-rsc/create-streamable-ui) function belongs to the `@ai-sdk/rsc` module and creates a stream that can send React components to the client.
+
+On the server, you render the `<WeatherCard/>` component with the props passed to it, and then stream it to the client. On the client side, you only need to render the UI that is streamed from the server.
+
+```tsx filename="app/page.tsx" highlight="4"
+return (
+  <div>
+    {messages.map(message => (
+      <div>{message.display}</div>
+    ))}
+  </div>
+);
+```
+
+Now the steps involved are simplified:
+
+1. The user prompts the language model.
+2. The language model generates a response that includes a tool call.
+3. The tool call renders a React component along with relevant props that represent the user interface.
+4. The response is streamed to the client and rendered directly.
+
+> **Note:** You can also render text on the server and stream it to the client using React Server Components. This way, all operations from language model generation to UI rendering can be done on the server, while the client only needs to render the UI that is streamed from the server.
+
+Check out this [example](/examples/next-app/interface/stream-component-updates) for a full illustration of how to stream component updates with React Server Components in Next.js App Router.

package/docs/06-advanced/08-model-as-router.mdx

@@ -0,0 +1,120 @@
+---
+title: Language Models as Routers
+description: Generative User Interfaces and Language Models as Routers
+---
+
+# Generative User Interfaces
+
+Since language models can render user interfaces as part of their generations, the resulting model generations are referred to as generative user interfaces.
+
+In this section we will learn more about generative user interfaces and their impact on the way AI applications are built.
+
+## Deterministic Routes and Probabilistic Routing
+
+Generative user interfaces are not deterministic in nature because they depend on the model's generation output. Since these generations are probabilistic in nature, it is possible for every user query to result in a different user interface.
+
+Users expect their experience using your application to be predictable, so non-deterministic user interfaces can sound like a bad idea at first. However, language models can be set up to limit their generations to a particular set of outputs using their ability to call functions.
+
+When language models are provided with a set of function definitions and instructed to execute any of them based on user query, they do either one of the following things:
+
+- Execute a function that is most relevant to the user query.
+- Not execute any function if the user query is out of bounds of the set of functions available to them.
+
+```tsx filename='app/actions.ts'
+const sendMessage = (prompt: string) =>
+  generateText({
+    model: __MODEL__,
+    system: 'you are a friendly weather assistant!',
+    prompt,
+    tools: {
+      getWeather: {
+        description: 'Get the weather in a location',
+        parameters: z.object({
+          location: z.string().describe('The location to get the weather for'),
+        }),
+        execute: async ({ location }: { location: string }) => ({
+          location,
+          temperature: 72 + Math.floor(Math.random() * 21) - 10,
+        }),
+      },
+    },
+  });
+
+sendMessage('What is the weather in San Francisco?'); // getWeather is called
+sendMessage('What is the weather in New York?'); // getWeather is called
+sendMessage('What events are happening in London?'); // No function is called
+```
+
+This way, it is possible to ensure that the generations result in deterministic outputs, while the choice a model makes still remains to be probabilistic.
+
+This emergent ability exhibited by a language model to choose whether a function needs to be executed or not based on a user query is believed to be models emulating "reasoning".
+
+As a result, the combination of language models being able to reason which function to execute as well as render user interfaces at the same time gives you the ability to build applications where language models can be used as a router.
+
+## Language Models as Routers
+
+Historically, developers had to write routing logic that connected different parts of an application to be navigable by a user and complete a specific task.
+
+In web applications today, most of the routing logic takes place in the form of routes:
+
+- `/login` would navigate you to a page with a login form.
+- `/user/john` would navigate you to a page with profile details about John.
+- `/api/events?limit=5` would display the five most recent events from an events database.
+
+While routes help you build web applications that connect different parts of an application into a seamless user experience, it can also be a burden to manage them as the complexity of applications grow.
+
+Next.js has helped reduce complexity in developing with routes by introducing:
+
+- File-based routing system
+- Dynamic routing
+- API routes
+- Middleware
+- App router, and so on...
+
+With language models becoming better at reasoning, we believe that there is a future where developers only write core application specific components while models take care of routing them based on the user's state in an application.
+
+With generative user interfaces, the language model decides which user interface to render based on the user's state in the application, giving users the flexibility to interact with your application in a conversational manner instead of navigating through a series of predefined routes.
+
+### Routing by parameters
+
+For routes like:
+
+- `/profile/[username]`
+- `/search?q=[query]`
+- `/media/[id]`
+
+that have segments dependent on dynamic data, the language model can generate the correct parameters and render the user interface.
+
+For example, when you're in a search application, you can ask the language model to search for artworks from different artists. The language model will call the search function with the artist's name as a parameter and render the search results.
+
+<div className="not-prose">
+  <CardPlayer
+    type="media-search"
+    title="Media Search"
+    description="Let your users see more than words can say by rendering components directly within your search experience."
+  />
+</div>
+
+### Routing by sequence
+
+For actions that require a sequence of steps to be completed by navigating through different routes, the language model can generate the correct sequence of routes to complete in order to fulfill the user's request.
+
+For example, when you're in a calendar application, you can ask the language model to schedule a happy hour evening with your friends. The language model will then understand your request and will perform the right sequence of [tool calls](/docs/ai-sdk-core/tools-and-tool-calling) to:
+
+1. Lookup your calendar
+2. Lookup your friends' calendars
+3. Determine the best time for everyone
+4. Search for nearby happy hour spots
+5. Create an event and send out invites to your friends
+
+<div className="not-prose">
+  <CardPlayer
+    type="event-planning"
+    title="Planning an Event"
+    description="The model calls functions and generates interfaces based on user intent, acting like a router."
+  />
+</div>
+
+Just by defining functions to lookup contacts, pull events from a calendar, and search for nearby locations, the model is able to sequentially navigate the routes for you.
+
+To learn more, check out these [examples](/examples/next-app/interface) using the `streamUI` function to stream generative user interfaces to the client based on the response from the language model.

package/docs/06-advanced/09-multistep-interfaces.mdx

@@ -0,0 +1,115 @@
+---
+title: Multistep Interfaces
+description: Concepts behind building multistep interfaces
+---
+
+# Multistep Interfaces
+
+Multistep interfaces refer to user interfaces that require multiple independent steps to be executed in order to complete a specific task.
+
+In order to understand multistep interfaces, it is important to understand two concepts:
+
+- Tool composition
+- Application context
+
+**Tool composition** is the process of combining multiple [tools](/docs/ai-sdk-core/tools-and-tool-calling) to create a new tool. This is a powerful concept that allows you to break down complex tasks into smaller, more manageable steps.
+
+**Application context** refers to the state of the application at any given point in time. This includes the user's input, the output of the language model, and any other relevant information.
+
+When designing multistep interfaces, you need to consider how the tools in your application can be composed together to form a coherent user experience as well as how the application context changes as the user progresses through the interface.
+
+## Application Context
+
+The application context can be thought of as the conversation history between the user and the language model. The richer the context, the more information the model has to generate relevant responses.
+
+In the context of multistep interfaces, the application context becomes even more important. This is because **the user's input in one step may affect the output of the model in the next step**.
+
+For example, consider a meal logging application that helps users track their daily food intake. The language model is provided with the following tools:
+
+- `log_meal` takes in parameters like the name of the food, the quantity, and the time of consumption to log a meal.
+- `delete_meal` takes in the name of the meal to be deleted.
+
+When the user logs a meal, the model generates a response confirming the meal has been logged.
+
+```txt highlight="2"
+User: Log a chicken shawarma for lunch.
+Tool: log_meal("chicken shawarma", "250g", "12:00 PM")
+Model: Chicken shawarma has been logged for lunch.
+```
+
+Now when the user decides to delete the meal, the model should be able to reference the previous step to identify the meal to be deleted.
+
+```txt highlight="7"
+User: Log a chicken shawarma for lunch.
+Tool: log_meal("chicken shawarma", "250g", "12:00 PM")
+Model: Chicken shawarma has been logged for lunch.
+...
+...
+User: I skipped lunch today, can you update my log?
+Tool: delete_meal("chicken shawarma")
+Model: Chicken shawarma has been deleted from your log.
+```
+
+In this example, managing the application context is important for the model to generate the correct response. The model needs to have information about the previous actions in order for it to use generate the parameters for the `delete_meal` tool.
+
+## Tool Composition
+
+Tool composition is the process of combining multiple tools to create a new tool. This involves defining the inputs and outputs of each tool, as well as how they interact with each other.
+
+The design of how these tools can be composed together to form a multistep interface is crucial to both the user experience of your application and the model's ability to generate the correct output.
+
+For example, consider a flight booking assistant that can help users book flights. The assistant can be designed to have the following tools:
+
+- `searchFlights`: Searches for flights based on the user's query.
+- `lookupFlight`: Looks up details of a specific flight based on the flight number.
+- `bookFlight`: Books a flight based on the user's selection.
+
+The `searchFlights` tool is called when the user wants to lookup flights for a specific route. This would typically mean the tool should be able to take in parameters like the origin and destination of the flight.
+
+The `lookupFlight` tool is called when the user wants to get more details about a specific flight. This would typically mean the tool should be able to take in parameters like the flight number and return information about seat availability.
+
+The `bookFlight` tool is called when the user decides to book a flight. In order to identify the flight to book, the tool should be able to take in parameters like the flight number, trip date, and passenger details.
+
+So the conversation between the user and the model could look like this:
+
+```txt highlight="8"
+User: I want to book a flight from New York to London.
+Tool: searchFlights("New York", "London")
+Model: Here are the available flights from New York to London.
+User: I want to book flight number BA123 on 12th December for myself and my wife.
+Tool: lookupFlight("BA123") -> "4 seats available"
+Model: Sure, there are seats available! Can you provide the names of the passengers?
+User: John Doe and Jane Doe.
+Tool: bookFlight("BA123", "12th December", ["John Doe", "Jane Doe"])
+Model: Your flight has been booked!
+```
+
+In the last tool call, the `bookFlight` tool does not include passenger details as it is not available in the application context. As a result, it requests the user to provide the passenger details before proceeding with the booking.
+
+Looking up passenger information could've been another tool that the model could've called before calling the `bookFlight` tool assuming that the user is logged into the application. This way, the model does not have to ask the user for the passenger details and can proceed with the booking.
+
+```txt highlight="5,6"
+User: I want to book a flight from New York to London.
+Tool: searchFlights("New York", "London")
+Model: Here are the available flights from New York to London.
+User: I want to book flight number BA123 on 12th December for myself an my wife.
+Tool: lookupContacts() -> ["John Doe", "Jane Doe"]
+Tool: bookFlight("BA123", "12th December", ["John Doe", "Jane Doe"])
+Model: Your flight has been booked!
+```
+
+The `lookupContacts` tool is called before the `bookFlight` tool to ensure that the passenger details are available in the application context when booking the flight. This way, the model can reduce the number of steps required from the user and use its ability to call tools that populate its context and use that information to complete the booking process.
+
+Now, let's introduce another tool called `lookupBooking` that can be used to show booking details by taking in the name of the passenger as parameter. This tool can be composed with the existing tools to provide a more complete user experience.
+
+```txt highlight="2-4"
+User: What's the status of my wife's upcoming flight?
+Tool: lookupContacts() -> ["John Doe", "Jane Doe"]
+Tool: lookupBooking("Jane Doe") -> "BA123 confirmed"
+Tool: lookupFlight("BA123") -> "Flight BA123 is scheduled to depart on 12th December."
+Model: Your wife's flight BA123 is confirmed and scheduled to depart on 12th December.
+```
+
+In this example, the `lookupBooking` tool is used to provide the user with the status of their wife's upcoming flight. By composing this tool with the existing tools, the model is able to generate a response that includes the booking status and the departure date of the flight without requiring the user to provide additional information.
+
+As a result, the more tools you design that can be composed together, the more complex and powerful your application can become.

package/docs/06-advanced/09-sequential-generations.mdx

@@ -0,0 +1,55 @@
+---
+title: Sequential Generations
+description: Learn how to implement sequential generations ("chains") with the AI SDK
+---
+
+# Sequential Generations
+
+When working with the AI SDK, you may want to create sequences of generations (often referred to as "chains" or "pipes"), where the output of one becomes the input for the next. This can be useful for creating more complex AI-powered workflows or for breaking down larger tasks into smaller, more manageable steps.
+
+## Example
+
+In a sequential chain, the output of one generation is directly used as input for the next generation. This allows you to create a series of dependent generations, where each step builds upon the previous one.
+
+Here's an example of how you can implement sequential actions:
+
+```typescript
+import { generateText } from 'ai';
+__PROVIDER_IMPORT__;
+
+async function sequentialActions() {
+  // Generate blog post ideas
+  const ideasGeneration = await generateText({
+    model: __MODEL__,
+    prompt: 'Generate 10 ideas for a blog post about making spaghetti.',
+  });
+
+  console.log('Generated Ideas:\n', ideasGeneration);
+
+  // Pick the best idea
+  const bestIdeaGeneration = await generateText({
+    model: __MODEL__,
+    prompt: `Here are some blog post ideas about making spaghetti:
+${ideasGeneration}
+
+Pick the best idea from the list above and explain why it's the best.`,
+  });
+
+  console.log('\nBest Idea:\n', bestIdeaGeneration);
+
+  // Generate an outline
+  const outlineGeneration = await generateText({
+    model: __MODEL__,
+    prompt: `We've chosen the following blog post idea about making spaghetti:
+${bestIdeaGeneration}
+
+Create a detailed outline for a blog post based on this idea.`,
+  });
+
+  console.log('\nBlog Post Outline:\n', outlineGeneration);
+}
+
+sequentialActions().catch(console.error);
+```
+
+In this example, we first generate ideas for a blog post, then pick the best idea, and finally create an outline based on that idea. Each step uses the output from the previous step as input for the next generation.