ai 6.0.31 → 6.0.33

package/docs/07-reference/01-ai-sdk-core/65-language-model-v2-middleware.mdx

@@ -0,0 +1,46 @@
+---
+title: LanguageModelV3Middleware
+description: Middleware for enhancing language model behavior (API Reference)
+---
+
+# `LanguageModelV3Middleware`
+
+<Note type="warning">
+  Language model middleware is an experimental feature.
+</Note>
+
+Language model middleware provides a way to enhance the behavior of language models
+by intercepting and modifying the calls to the language model. It can be used to add
+features like guardrails, RAG, caching, and logging in a language model agnostic way.
+
+See [Language Model Middleware](/docs/ai-sdk-core/middleware) for more information.
+
+## Import
+
+<Snippet
+  text={`import { LanguageModelV3Middleware } from "ai"`}
+  prompt={false}
+/>
+
+## API Signature
+
+<PropertiesTable
+  content={[
+    {
+      name: 'transformParams',
+      type: '({ type: "generate" | "stream", params: LanguageModelV3CallOptions }) => Promise<LanguageModelV3CallOptions>',
+      description:
+        'Transforms the parameters before they are passed to the language model.',
+    },
+    {
+      name: 'wrapGenerate',
+      type: '({ doGenerate: DoGenerateFunction, params: LanguageModelV3CallOptions, model: LanguageModelV3 }) => Promise<DoGenerateResult>',
+      description: 'Wraps the generate operation of the language model.',
+    },
+    {
+      name: 'wrapStream',
+      type: '({ doStream: DoStreamFunction, params: LanguageModelV3CallOptions, model: LanguageModelV3 }) => Promise<DoStreamResult>',
+      description: 'Wraps the stream operation of the language model.',
+    },
+  ]}
+/>

package/docs/07-reference/01-ai-sdk-core/66-extract-reasoning-middleware.mdx

@@ -0,0 +1,68 @@
+---
+title: extractReasoningMiddleware
+description: Middleware that extracts XML-tagged reasoning sections from generated text
+---
+
+# `extractReasoningMiddleware()`
+
+`extractReasoningMiddleware` is a middleware function that extracts XML-tagged reasoning sections from generated text and exposes them separately from the main text content. This is particularly useful when you want to separate an AI model's reasoning process from its final output.
+
+```ts
+import { extractReasoningMiddleware } from 'ai';
+
+const middleware = extractReasoningMiddleware({
+  tagName: 'reasoning',
+  separator: '\n',
+});
+```
+
+## Import
+
+<Snippet
+  text={`import { extractReasoningMiddleware } from "ai"`}
+  prompt={false}
+/>
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'tagName',
+      type: 'string',
+      isOptional: false,
+      description:
+        'The name of the XML tag to extract reasoning from (without angle brackets)',
+    },
+    {
+      name: 'separator',
+      type: 'string',
+      isOptional: true,
+      description:
+        'The separator to use between reasoning and text sections. Defaults to "\\n"',
+    },
+    {
+      name: 'startWithReasoning',
+      type: 'boolean',
+      isOptional: true,
+      description:
+        'Starts with reasoning tokens. Set to true when the response always starts with reasoning and the initial tag is omitted. Defaults to false.',
+    },
+  ]}
+/>
+
+### Returns
+
+Returns a middleware object that:
+
+- Processes both streaming and non-streaming responses
+- Extracts content between specified XML tags as reasoning
+- Removes the XML tags and reasoning from the main text
+- Adds a `reasoning` property to the result containing the extracted content
+- Maintains proper separation between text sections using the specified separator
+
+### Type Parameters
+
+The middleware works with the `LanguageModelV3StreamPart` type for streaming responses.

package/docs/07-reference/01-ai-sdk-core/67-simulate-streaming-middleware.mdx

@@ -0,0 +1,71 @@
+---
+title: simulateStreamingMiddleware
+description: Middleware that simulates streaming for non-streaming language models
+---
+
+# `simulateStreamingMiddleware()`
+
+`simulateStreamingMiddleware` is a middleware function that simulates streaming behavior with responses from non-streaming language models. This is useful when you want to maintain a consistent streaming interface even when using models that only provide complete responses.
+
+```ts
+import { simulateStreamingMiddleware } from 'ai';
+
+const middleware = simulateStreamingMiddleware();
+```
+
+## Import
+
+<Snippet
+  text={`import { simulateStreamingMiddleware } from "ai"`}
+  prompt={false}
+/>
+
+## API Signature
+
+### Parameters
+
+This middleware doesn't accept any parameters.
+
+### Returns
+
+Returns a middleware object that:
+
+- Takes a complete response from a language model
+- Converts it into a simulated stream of chunks
+- Properly handles various response components including:
+  - Text content
+  - Reasoning (as string or array of objects)
+  - Tool calls
+  - Metadata and usage information
+  - Warnings
+
+### Usage Example
+
+```ts
+import { streamText } from 'ai';
+import { wrapLanguageModel } from 'ai';
+import { simulateStreamingMiddleware } from 'ai';
+
+// Example with a non-streaming model
+const result = streamText({
+  model: wrapLanguageModel({
+    model: nonStreamingModel,
+    middleware: simulateStreamingMiddleware(),
+  }),
+  prompt: 'Your prompt here',
+});
+
+// Now you can use the streaming interface
+for await (const chunk of result.fullStream) {
+  // Process streaming chunks
+}
+```
+
+## How It Works
+
+The middleware:
+
+1. Awaits the complete response from the language model
+2. Creates a `ReadableStream` that emits chunks in the correct sequence
+3. Simulates streaming by breaking down the response into appropriate chunk types
+4. Preserves all metadata, reasoning, tool calls, and other response properties

package/docs/07-reference/01-ai-sdk-core/68-default-settings-middleware.mdx

@@ -0,0 +1,80 @@
+---
+title: defaultSettingsMiddleware
+description: Middleware that applies default settings for language models
+---
+
+# `defaultSettingsMiddleware()`
+
+`defaultSettingsMiddleware` is a middleware function that applies default settings to language model calls. This is useful when you want to establish consistent default parameters across multiple model invocations.
+
+```ts
+import { defaultSettingsMiddleware } from 'ai';
+
+const middleware = defaultSettingsMiddleware({
+  settings: {
+    temperature: 0.7,
+    maxOutputTokens: 1000,
+    // other settings...
+  },
+});
+```
+
+## Import
+
+<Snippet
+  text={`import { defaultSettingsMiddleware } from "ai"`}
+  prompt={false}
+/>
+
+## API Signature
+
+### Parameters
+
+The middleware accepts a configuration object with the following properties:
+
+- `settings`: An object containing default parameter values to apply to language model calls. These can include any valid `LanguageModelV3CallOptions` properties and optional provider metadata.
+
+### Returns
+
+Returns a middleware object that:
+
+- Merges the default settings with the parameters provided in each model call
+- Ensures that explicitly provided parameters take precedence over defaults
+- Merges provider metadata objects
+
+### Usage Example
+
+```ts
+import { streamText, wrapLanguageModel, defaultSettingsMiddleware } from 'ai';
+
+// Create a model with default settings
+const modelWithDefaults = wrapLanguageModel({
+  model: gateway('anthropic/claude-sonnet-4.5'),
+  middleware: defaultSettingsMiddleware({
+    settings: {
+      providerOptions: {
+        openai: {
+          reasoningEffort: 'high',
+        },
+      },
+    },
+  }),
+});
+
+// Use the model - default settings will be applied
+const result = await streamText({
+  model: modelWithDefaults,
+  prompt: 'Your prompt here',
+  // These parameters will override the defaults
+  temperature: 0.8,
+});
+```
+
+## How It Works
+
+The middleware:
+
+1. Takes a set of default settings as configuration
+2. Merges these defaults with the parameters provided in each model call
+3. Ensures that explicitly provided parameters take precedence over defaults
+4. Merges provider metadata objects from both sources

package/docs/07-reference/01-ai-sdk-core/69-add-tool-input-examples-middleware.mdx

@@ -0,0 +1,155 @@
+---
+title: addToolInputExamplesMiddleware
+description: Middleware that appends tool input examples to tool descriptions.
+---
+
+# `addToolInputExamplesMiddleware`
+
+`addToolInputExamplesMiddleware` is a middleware function that appends input examples to tool descriptions. This is especially useful for language model providers that **do not natively support the `inputExamples` property**—the middleware serializes and injects the examples into the tool's `description` so models can learn from them.
+
+## Import
+
+<Snippet
+  text={`import { addToolInputExamplesMiddleware } from "ai"`}
+  prompt={false}
+/>
+
+## API
+
+### Signature
+
+```ts
+function addToolInputExamplesMiddleware(options?: {
+  prefix?: string;
+  format?: (example: { input: JSONObject }, index: number) => string;
+  remove?: boolean;
+}): LanguageModelMiddleware;
+```
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'prefix',
+      type: 'string',
+      isOptional: true,
+      description:
+        "A prefix prepended before the input examples section. Defaults to `'Input Examples:'`.",
+    },
+    {
+      name: 'format',
+      type: '(example: { input: JSONObject }, index: number) => string',
+      isOptional: true,
+      description:
+        'Optional custom formatter for each example. Receives the example object and its index. Default: JSON.stringify(example.input).',
+    },
+    {
+      name: 'remove',
+      type: 'boolean',
+      isOptional: true,
+      description:
+        'Whether to remove the `inputExamples` property from the tool after adding them to the description. Default: true.',
+    },
+  ]}
+/>
+
+### Returns
+
+A [LanguageModelMiddleware](/docs/03-ai-sdk-core/40-middleware) that:
+
+- Locates function tools with an `inputExamples` property.
+- Serializes each input example (by default as JSON, or using your custom formatter).
+- Prepends a section at the end of the tool description containing all formatted examples, prefixed by the `prefix`.
+- Removes the `inputExamples` property from the tool (unless `remove: false`).
+- Passes through all other tools (including those without examples) unchanged.
+
+## Usage Example
+
+```ts
+import {
+  generateText,
+  tool,
+  wrapLanguageModel,
+  addToolInputExamplesMiddleware,
+} from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { z } from 'zod';
+
+const model = wrapLanguageModel({
+  model: __MODEL__,
+  middleware: addToolInputExamplesMiddleware({
+    prefix: 'Input Examples:',
+    format: (example, index) =>
+      `${index + 1}. ${JSON.stringify(example.input)}`,
+  }),
+});
+
+const result = await generateText({
+  model,
+  tools: {
+    weather: tool({
+      description: 'Get the weather in a location',
+      inputSchema: z.object({ location: z.string() }),
+      inputExamples: [
+        { input: { location: 'San Francisco' } },
+        { input: { location: 'London' } },
+      ],
+    }),
+  },
+  prompt: 'What is the weather in Tokyo?',
+});
+```
+
+## How It Works
+
+1. For every function tool that defines `inputExamples`, the middleware:
+
+   - Formats each example with the `format` function (default: JSON.stringify).
+   - Builds a section like:
+
+     ```
+     Input Examples:
+     {"location":"San Francisco"}
+     {"location":"London"}
+     ```
+
+   - Appends this section to the end of the tool's `description`.
+
+2. By default, it removes the `inputExamples` property after appending to prevent duplication (can be disabled with `remove: false`).
+3. Tools without input examples or non-function tools are left unmodified.
+
+> **Tip:** This middleware is especially useful with providers such as OpenAI or Anthropic, where native support for `inputExamples` is not available.
+
+## Example effect
+
+If your original tool definition is:
+
+```ts
+{
+  type: 'function',
+  name: 'weather',
+  description: 'Get the weather in a location',
+  inputSchema: { ... },
+  inputExamples: [
+    { input: { location: 'San Francisco' } },
+    { input: { location: 'London' } }
+  ]
+}
+```
+
+After applying the middleware (with default settings), the tool passed to the model will look like:
+
+```ts
+{
+  type: 'function',
+  name: 'weather',
+  description: `Get the weather in a location
+
+Input Examples:
+{"location":"San Francisco"}
+{"location":"London"}`,
+  inputSchema: { ... }
+  // inputExamples is removed by default
+}
+```

package/docs/07-reference/01-ai-sdk-core/70-extract-json-middleware.mdx

@@ -0,0 +1,147 @@
+---
+title: extractJsonMiddleware
+description: Middleware that extracts JSON from text content by stripping markdown code fences
+---
+
+# `extractJsonMiddleware()`
+
+`extractJsonMiddleware` is a middleware function that extracts JSON from text content by stripping markdown code fences and other formatting. This is useful when using `Output.object()` with models that wrap JSON responses in markdown code blocks (e.g., ` ```json ... ``` `).
+
+```ts
+import { extractJsonMiddleware } from 'ai';
+
+const middleware = extractJsonMiddleware();
+```
+
+## Import
+
+<Snippet text={`import { extractJsonMiddleware } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'transform',
+      type: '(text: string) => string',
+      isOptional: true,
+      description:
+        'Custom transform function to apply to text content. Receives the raw text and should return the transformed text. If not provided, the default transform strips markdown code fences.',
+    },
+  ]}
+/>
+
+### Returns
+
+Returns a middleware object that:
+
+- Processes both streaming and non-streaming responses
+- Strips markdown code fences (` ```json ` and ` ``` `) from text content
+- Applies custom transformations when a `transform` function is provided
+- Maintains proper streaming behavior with efficient buffering
+
+## Usage Examples
+
+### Basic Usage
+
+Strip markdown code fences from model responses when using structured output:
+
+```ts
+import {
+  generateText,
+  wrapLanguageModel,
+  extractJsonMiddleware,
+  Output,
+} from 'ai';
+import { z } from 'zod';
+
+const result = await generateText({
+  model: wrapLanguageModel({
+    model: yourModel,
+    middleware: extractJsonMiddleware(),
+  }),
+  output: Output.object({
+    schema: z.object({
+      recipe: z.object({
+        name: z.string(),
+        steps: z.array(z.string()),
+      }),
+    }),
+  }),
+  prompt: 'Generate a lasagna recipe.',
+});
+
+console.log(result.output);
+```
+
+### With Streaming
+
+The middleware also works with streaming responses:
+
+```ts
+import {
+  streamText,
+  wrapLanguageModel,
+  extractJsonMiddleware,
+  Output,
+} from 'ai';
+import { z } from 'zod';
+
+const { partialOutputStream } = streamText({
+  model: wrapLanguageModel({
+    model: yourModel,
+    middleware: extractJsonMiddleware(),
+  }),
+  output: Output.object({
+    schema: z.object({
+      recipe: z.object({
+        ingredients: z.array(z.string()),
+        steps: z.array(z.string()),
+      }),
+    }),
+  }),
+  prompt: 'Generate a detailed recipe.',
+});
+
+for await (const partialObject of partialOutputStream) {
+  console.log(partialObject);
+}
+```
+
+### Custom Transform Function
+
+For models that use different formatting, you can provide a custom transform:
+
+```ts
+import { extractJsonMiddleware } from 'ai';
+
+const middleware = extractJsonMiddleware({
+  transform: text =>
+    text
+      .replace(/^PREFIX/, '')
+      .replace(/SUFFIX$/, '')
+      .trim(),
+});
+```
+
+## How It Works
+
+The middleware handles text content in two ways:
+
+### Non-Streaming (generateText)
+
+1. Receives the complete response from the model
+2. Applies the transform function to strip markdown fences (or custom formatting)
+3. Returns the cleaned text content
+
+### Streaming (streamText)
+
+1. Buffers initial content to detect markdown fence prefixes (` ```json\n `)
+2. If a fence is detected, strips the prefix and switches to streaming mode
+3. Maintains a small suffix buffer to handle the closing fence (` \n``` `)
+4. When the stream ends, strips any trailing fence from the buffer
+5. For custom transforms, buffers all content and applies the transform at the end
+
+This approach ensures efficient streaming while correctly handling code fences that may be split across multiple chunks.

package/docs/07-reference/01-ai-sdk-core/70-step-count-is.mdx

@@ -0,0 +1,84 @@
+---
+title: stepCountIs
+description: API Reference for stepCountIs.
+---
+
+# `stepCountIs()`
+
+Creates a stop condition that stops when the number of steps reaches a specified count.
+
+This function is used with `stopWhen` in `generateText` and `streamText` to control when a tool-calling loop should stop based on the number of steps executed.
+
+```ts
+import { generateText, stepCountIs } from 'ai';
+__PROVIDER_IMPORT__;
+
+const result = await generateText({
+  model: __MODEL__,
+  tools: {
+    // your tools
+  },
+  // Stop after 5 steps
+  stopWhen: stepCountIs(5),
+});
+```
+
+## Import
+
+<Snippet text={`import { stepCountIs } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'count',
+      type: 'number',
+      description:
+        'The maximum number of steps to execute before stopping the tool-calling loop.',
+    },
+  ]}
+/>
+
+### Returns
+
+A `StopCondition` function that returns `true` when the step count reaches the specified number. The function can be used with the `stopWhen` parameter in `generateText` and `streamText`.
+
+## Examples
+
+### Basic Usage
+
+Stop after 3 steps:
+
+```ts
+import { generateText, stepCountIs } from 'ai';
+
+const result = await generateText({
+  model: yourModel,
+  tools: yourTools,
+  stopWhen: stepCountIs(3),
+});
+```
+
+### Combining with Other Conditions
+
+You can combine multiple stop conditions in an array:
+
+```ts
+import { generateText, stepCountIs, hasToolCall } from 'ai';
+
+const result = await generateText({
+  model: yourModel,
+  tools: yourTools,
+  // Stop after 10 steps OR when finalAnswer tool is called
+  stopWhen: [stepCountIs(10), hasToolCall('finalAnswer')],
+});
+```
+
+## See also
+
+- [`hasToolCall()`](/docs/reference/ai-sdk-core/has-tool-call)
+- [`generateText()`](/docs/reference/ai-sdk-core/generate-text)
+- [`streamText()`](/docs/reference/ai-sdk-core/stream-text)