ai 6.0.31 → 6.0.32

package/docs/07-reference/01-ai-sdk-core/71-has-tool-call.mdx

@@ -0,0 +1,120 @@
+---
+title: hasToolCall
+description: API Reference for hasToolCall.
+---
+
+# `hasToolCall()`
+
+Creates a stop condition that stops when a specific tool is called.
+
+This function is used with `stopWhen` in `generateText` and `streamText` to control when a tool-calling loop should stop based on whether a particular tool has been invoked.
+
+```ts
+import { generateText, hasToolCall } from 'ai';
+__PROVIDER_IMPORT__;
+
+const result = await generateText({
+  model: __MODEL__,
+  tools: {
+    weather: weatherTool,
+    finalAnswer: finalAnswerTool,
+  },
+  // Stop when the finalAnswer tool is called
+  stopWhen: hasToolCall('finalAnswer'),
+});
+```
+
+## Import
+
+<Snippet text={`import { hasToolCall } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'toolName',
+      type: 'string',
+      description:
+        'The name of the tool that should trigger the stop condition when called.',
+    },
+  ]}
+/>
+
+### Returns
+
+A `StopCondition` function that returns `true` when the specified tool is called in the current step. The function can be used with the `stopWhen` parameter in `generateText` and `streamText`.
+
+## Examples
+
+### Basic Usage
+
+Stop when a specific tool is called:
+
+```ts
+import { generateText, hasToolCall } from 'ai';
+
+const result = await generateText({
+  model: yourModel,
+  tools: {
+    submitAnswer: submitAnswerTool,
+    search: searchTool,
+  },
+  stopWhen: hasToolCall('submitAnswer'),
+});
+```
+
+### Combining with Other Conditions
+
+You can combine multiple stop conditions in an array:
+
+```ts
+import { generateText, hasToolCall, stepCountIs } from 'ai';
+
+const result = await generateText({
+  model: yourModel,
+  tools: {
+    weather: weatherTool,
+    search: searchTool,
+    finalAnswer: finalAnswerTool,
+  },
+  // Stop when weather tool is called OR finalAnswer is called OR after 5 steps
+  stopWhen: [
+    hasToolCall('weather'),
+    hasToolCall('finalAnswer'),
+    stepCountIs(5),
+  ],
+});
+```
+
+### Agent Pattern
+
+Common pattern for agents that run until they provide a final answer:
+
+```ts
+import { generateText, hasToolCall } from 'ai';
+
+const result = await generateText({
+  model: yourModel,
+  tools: {
+    search: searchTool,
+    calculate: calculateTool,
+    finalAnswer: {
+      description: 'Provide the final answer to the user',
+      parameters: z.object({
+        answer: z.string(),
+      }),
+      execute: async ({ answer }) => answer,
+    },
+  },
+  stopWhen: hasToolCall('finalAnswer'),
+});
+```
+
+## See also
+
+- [`stepCountIs()`](/docs/reference/ai-sdk-core/step-count-is)
+- [`generateText()`](/docs/reference/ai-sdk-core/generate-text)
+- [`streamText()`](/docs/reference/ai-sdk-core/stream-text)

package/docs/07-reference/01-ai-sdk-core/75-simulate-readable-stream.mdx

@@ -0,0 +1,94 @@
+---
+title: simulateReadableStream
+description: Create a ReadableStream that emits values with configurable delays
+---
+
+# `simulateReadableStream()`
+
+`simulateReadableStream` is a utility function that creates a ReadableStream which emits provided values sequentially with configurable delays. This is particularly useful for testing streaming functionality or simulating time-delayed data streams.
+
+```ts
+import { simulateReadableStream } from 'ai';
+
+const stream = simulateReadableStream({
+  chunks: ['Hello', ' ', 'World'],
+  initialDelayInMs: 100,
+  chunkDelayInMs: 50,
+});
+```
+
+## Import
+
+<Snippet text={`import { simulateReadableStream } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'chunks',
+      type: 'T[]',
+      isOptional: false,
+      description: 'Array of values to be emitted by the stream',
+    },
+    {
+      name: 'initialDelayInMs',
+      type: 'number | null',
+      isOptional: true,
+      description:
+        'Initial delay in milliseconds before emitting the first value. Defaults to 0. Set to null to skip the initial delay entirely.',
+    },
+    {
+      name: 'chunkDelayInMs',
+      type: 'number | null',
+      isOptional: true,
+      description:
+        'Delay in milliseconds between emitting each value. Defaults to 0. Set to null to skip delays between chunks.',
+    },
+  ]}
+/>
+
+### Returns
+
+Returns a `ReadableStream<T>` that:
+
+- Emits each value from the provided `chunks` array sequentially
+- Waits for `initialDelayInMs` before emitting the first value (if not `null`)
+- Waits for `chunkDelayInMs` between emitting subsequent values (if not `null`)
+- Closes automatically after all chunks have been emitted
+
+### Type Parameters
+
+- `T`: The type of values contained in the chunks array and emitted by the stream
+
+## Examples
+
+### Basic Usage
+
+```ts
+const stream = simulateReadableStream({
+  chunks: ['Hello', ' ', 'World'],
+});
+```
+
+### With Delays
+
+```ts
+const stream = simulateReadableStream({
+  chunks: ['Hello', ' ', 'World'],
+  initialDelayInMs: 1000, // Wait 1 second before first chunk
+  chunkDelayInMs: 500, // Wait 0.5 seconds between chunks
+});
+```
+
+### Without Delays
+
+```ts
+const stream = simulateReadableStream({
+  chunks: ['Hello', ' ', 'World'],
+  initialDelayInMs: null, // No initial delay
+  chunkDelayInMs: null, // No delay between chunks
+});
+```

package/docs/07-reference/01-ai-sdk-core/80-smooth-stream.mdx

@@ -0,0 +1,145 @@
+---
+title: smoothStream
+description: Stream transformer for smoothing text and reasoning output
+---
+
+# `smoothStream()`
+
+`smoothStream` is a utility function that creates a TransformStream
+for the `streamText` `transform` option
+to smooth out text and reasoning streaming by buffering and releasing complete chunks with configurable delays.
+This creates a more natural reading experience when streaming text and reasoning responses.
+
+```ts highlight={"6-9"}
+import { smoothStream, streamText } from 'ai';
+
+const result = streamText({
+  model,
+  prompt,
+  experimental_transform: smoothStream({
+    delayInMs: 20, // optional: defaults to 10ms
+    chunking: 'line', // optional: defaults to 'word'
+  }),
+});
+```
+
+## Import
+
+<Snippet text={`import { smoothStream } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'delayInMs',
+      type: 'number | null',
+      isOptional: true,
+      description:
+        'The delay in milliseconds between outputting each chunk. Defaults to 10ms. Set to `null` to disable delays.',
+    },
+    {
+      name: 'chunking',
+      type: '"word" | "line" | RegExp | Intl.Segmenter | (buffer: string) => string | undefined | null',
+      isOptional: true,
+      description:
+        'Controls how text and reasoning content is chunked for streaming. Use "word" to stream word by word (default), "line" to stream line by line, an Intl.Segmenter for locale-aware word segmentation (recommended for CJK languages), or provide a custom callback or RegExp pattern for custom chunking.',
+    },
+  ]}
+/>
+
+#### Word chunking caveats with non-latin languages
+
+The word based chunking **does not work well** with the following languages that do not delimit words with spaces:
+
+- Chinese
+- Japanese
+- Korean
+- Vietnamese
+- Thai
+
+#### Using Intl.Segmenter (recommended)
+
+For these languages, we recommend using `Intl.Segmenter` for proper locale-aware word segmentation.
+This is the preferred approach as it provides accurate word boundaries for CJK and other languages.
+
+<Note>
+  `Intl.Segmenter` is available in Node.js 16+ and all modern browsers (Chrome
+  87+, Firefox 125+, Safari 14.1+).
+</Note>
+
+```tsx filename="Japanese example with Intl.Segmenter"
+import { smoothStream, streamText } from 'ai';
+__PROVIDER_IMPORT__;
+
+const segmenter = new Intl.Segmenter('ja', { granularity: 'word' });
+
+const result = streamText({
+  model: __MODEL__,
+  prompt: 'Your prompt here',
+  experimental_transform: smoothStream({
+    chunking: segmenter,
+  }),
+});
+```
+
+```tsx filename="Chinese example with Intl.Segmenter"
+import { smoothStream, streamText } from 'ai';
+__PROVIDER_IMPORT__;
+
+const segmenter = new Intl.Segmenter('zh', { granularity: 'word' });
+
+const result = streamText({
+  model: __MODEL__,
+  prompt: 'Your prompt here',
+  experimental_transform: smoothStream({
+    chunking: segmenter,
+  }),
+});
+```
+
+#### Regex based chunking
+
+To use regex based chunking, pass a `RegExp` to the `chunking` option.
+
+```ts
+// To split on underscores:
+smoothStream({
+  chunking: /_+/,
+});
+
+// Also can do it like this, same behavior
+smoothStream({
+  chunking: /[^_]*_/,
+});
+```
+
+#### Custom callback chunking
+
+To use a custom callback for chunking, pass a function to the `chunking` option.
+
+```ts
+smoothStream({
+  chunking: text => {
+    const findString = 'some string';
+    const index = text.indexOf(findString);
+
+    if (index === -1) {
+      return null;
+    }
+
+    return text.slice(0, index) + findString;
+  },
+});
+```
+
+### Returns
+
+Returns a `TransformStream` that:
+
+- Buffers incoming text and reasoning chunks
+- Releases content when the chunking pattern is encountered
+- Adds configurable delays between chunks for smooth output
+- Passes through non-text/reasoning chunks (like tool calls, step-finish events) immediately

package/docs/07-reference/01-ai-sdk-core/90-generate-id.mdx

@@ -0,0 +1,43 @@
+---
+title: generateId
+description: Generate a unique identifier (API Reference)
+---
+
+# `generateId()`
+
+Generates a unique identifier. You can optionally provide the length of the ID.
+
+This is the same id generator used by the AI SDK.
+
+```ts
+import { generateId } from 'ai';
+
+const id = generateId();
+```
+
+## Import
+
+<Snippet text={`import { generateId } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'size',
+      type: 'number',
+      description:
+        'The length of the generated ID. It defaults to 16. This parameter is deprecated and will be removed in the next major version.',
+    },
+  ]}
+/>
+
+### Returns
+
+A string representing the generated ID.
+
+## See also
+
+- [`createIdGenerator()`](/docs/reference/ai-sdk-core/create-id-generator)

package/docs/07-reference/01-ai-sdk-core/91-create-id-generator.mdx

@@ -0,0 +1,89 @@
+---
+title: createIdGenerator
+description: Create a customizable unique identifier generator (API Reference)
+---
+
+# `createIdGenerator()`
+
+Creates a customizable ID generator function. You can configure the alphabet, prefix, separator, and default size of the generated IDs.
+
+```ts
+import { createIdGenerator } from 'ai';
+
+const generateCustomId = createIdGenerator({
+  prefix: 'user',
+  separator: '_',
+});
+
+const id = generateCustomId(); // Example: "user_1a2b3c4d5e6f7g8h"
+```
+
+## Import
+
+<Snippet text={`import { createIdGenerator } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'options',
+      type: 'object',
+      description:
+        'Optional configuration object with the following properties:',
+    },
+    {
+      name: 'options.alphabet',
+      type: 'string',
+      description:
+        'The characters to use for generating the random part of the ID. Defaults to alphanumeric characters (0-9, A-Z, a-z).',
+    },
+    {
+      name: 'options.prefix',
+      type: 'string',
+      description:
+        'A string to prepend to all generated IDs. Defaults to none.',
+    },
+    {
+      name: 'options.separator',
+      type: 'string',
+      description:
+        'The character(s) to use between the prefix and the random part. Defaults to "-".',
+    },
+    {
+      name: 'options.size',
+      type: 'number',
+      description:
+        'The default length of the random part of the ID. Defaults to 16.',
+    },
+  ]}
+/>
+
+### Returns
+
+Returns a function that generates IDs based on the configured options.
+
+### Notes
+
+- The generator uses non-secure random generation and should not be used for security-critical purposes.
+- The separator character must not be part of the alphabet to ensure reliable prefix checking.
+
+## Example
+
+```ts
+// Create a custom ID generator for user IDs
+const generateUserId = createIdGenerator({
+  prefix: 'user',
+  separator: '_',
+  size: 8,
+});
+
+// Generate IDs
+const id1 = generateUserId(); // e.g., "user_1a2b3c4d"
+```
+
+## See also
+
+- [`generateId()`](/docs/reference/ai-sdk-core/generate-id)

package/docs/07-reference/01-ai-sdk-core/index.mdx

@@ -0,0 +1,159 @@
+---
+title: AI SDK Core
+description: Reference documentation for the AI SDK Core
+collapsed: true
+---
+
+# AI SDK Core
+
+[AI SDK Core](/docs/ai-sdk-core) is a set of functions that allow you to interact with language models and other AI models.
+These functions are designed to be easy-to-use and flexible, allowing you to generate text, structured data,
+and embeddings from language models and other AI models.
+
+AI SDK Core contains the following main functions:
+
+<IndexCards
+  cards={[
+    {
+      title: 'generateText()',
+      description: 'Generate text and call tools from a language model.',
+      href: '/docs/reference/ai-sdk-core/generate-text',
+    },
+    {
+      title: 'streamText()',
+      description: 'Stream text and call tools from a language model.',
+      href: '/docs/reference/ai-sdk-core/stream-text',
+    },
+    {
+      title: 'generateObject()',
+      description: 'Generate structured data from a language model.',
+      href: '/docs/reference/ai-sdk-core/generate-object',
+    },
+    {
+      title: 'streamObject()',
+      description: 'Stream structured data from a language model.',
+      href: '/docs/reference/ai-sdk-core/stream-object',
+    },
+    {
+      title: 'embed()',
+      description:
+        'Generate an embedding for a single value using an embedding model.',
+      href: '/docs/reference/ai-sdk-core/embed',
+    },
+    {
+      title: 'embedMany()',
+      description:
+        'Generate embeddings for several values using an embedding model (batch embedding).',
+      href: '/docs/reference/ai-sdk-core/embed-many',
+    },
+    {
+      title: 'generateImage()',
+      description:
+        'Generate images based on a given prompt using an image model.',
+      href: '/docs/reference/ai-sdk-core/generate-image',
+    },
+    {
+      title: 'experimental_transcribe()',
+      description: 'Generate a transcript from an audio file.',
+      href: '/docs/reference/ai-sdk-core/transcribe',
+    },
+    {
+      title: 'experimental_generateSpeech()',
+      description: 'Generate speech audio from text.',
+      href: '/docs/reference/ai-sdk-core/generate-speech',
+    },
+  ]}
+/>
+
+It also contains the following helper functions:
+
+<IndexCards
+  cards={[
+    {
+      title: 'tool()',
+      description: 'Type inference helper function for tools.',
+      href: '/docs/reference/ai-sdk-core/tool',
+    },
+    {
+      title: 'createMCPClient()',
+      description: 'Creates a client for connecting to MCP servers.',
+      href: '/docs/reference/ai-sdk-core/create-mcp-client',
+    },
+    {
+      title: 'jsonSchema()',
+      description: 'Creates AI SDK compatible JSON schema objects.',
+      href: '/docs/reference/ai-sdk-core/json-schema',
+    },
+    {
+      title: 'zodSchema()',
+      description: 'Creates AI SDK compatible Zod schema objects.',
+      href: '/docs/reference/ai-sdk-core/zod-schema',
+    },
+    {
+      title: 'createProviderRegistry()',
+      description:
+        'Creates a registry for using models from multiple providers.',
+      href: '/docs/reference/ai-sdk-core/provider-registry',
+    },
+    {
+      title: 'cosineSimilarity()',
+      description:
+        'Calculates the cosine similarity between two vectors, e.g. embeddings.',
+      href: '/docs/reference/ai-sdk-core/cosine-similarity',
+    },
+    {
+      title: 'simulateReadableStream()',
+      description:
+        'Creates a ReadableStream that emits values with configurable delays.',
+      href: '/docs/reference/ai-sdk-core/simulate-readable-stream',
+    },
+    {
+      title: 'wrapLanguageModel()',
+      description: 'Wraps a language model with middleware.',
+      href: '/docs/reference/ai-sdk-core/wrap-language-model',
+    },
+    {
+      title: 'wrapImageModel()',
+      description: 'Wraps an image model with middleware.',
+      href: '/docs/reference/ai-sdk-core/wrap-image-model',
+    },
+    {
+      title: 'extractReasoningMiddleware()',
+      description:
+        'Extracts reasoning from the generated text and exposes it as a `reasoning` property on the result.',
+      href: '/docs/reference/ai-sdk-core/extract-reasoning-middleware',
+    },
+    {
+      title: 'extractJsonMiddleware()',
+      description:
+        'Extracts JSON from text content by stripping markdown code fences.',
+      href: '/docs/reference/ai-sdk-core/extract-json-middleware',
+    },
+    {
+      title: 'simulateStreamingMiddleware()',
+      description:
+        'Simulates streaming behavior with responses from non-streaming language models.',
+      href: '/docs/reference/ai-sdk-core/simulate-streaming-middleware',
+    },
+    {
+      title: 'defaultSettingsMiddleware()',
+      description: 'Applies default settings to a language model.',
+      href: '/docs/reference/ai-sdk-core/default-settings-middleware',
+    },
+    {
+      title: 'smoothStream()',
+      description: 'Smooths text and reasoning streaming output.',
+      href: '/docs/reference/ai-sdk-core/smooth-stream',
+    },
+    {
+      title: 'generateId()',
+      description: 'Helper function for generating unique IDs',
+      href: '/docs/reference/ai-sdk-core/generate-id',
+    },
+    {
+      title: 'createIdGenerator()',
+      description: 'Creates an ID generator',
+      href: '/docs/reference/ai-sdk-core/create-id-generator',
+    },
+  ]}
+/>