ai 6.0.31 → 6.0.32

package/docs/03-ai-sdk-core/45-provider-management.mdx

@@ -0,0 +1,349 @@
+---
+title: Provider & Model Management
+description: Learn how to work with multiple providers and models
+---
+
+# Provider & Model Management
+
+When you work with multiple providers and models, it is often desirable to manage them in a central place
+and access the models through simple string ids.
+
+The AI SDK offers [custom providers](/docs/reference/ai-sdk-core/custom-provider) and
+a [provider registry](/docs/reference/ai-sdk-core/provider-registry) for this purpose:
+
+- With **custom providers**, you can pre-configure model settings, provide model name aliases,
+  and limit the available models.
+- The **provider registry** lets you mix multiple providers and access them through simple string ids.
+
+You can mix and match custom providers, the provider registry, and [middleware](/docs/ai-sdk-core/middleware) in your application.
+
+## Custom Providers
+
+You can create a [custom provider](/docs/reference/ai-sdk-core/custom-provider) using `customProvider`.
+
+### Example: custom model settings
+
+You might want to override the default model settings for a provider or provide model name aliases
+with pre-configured settings.
+
+```ts
+import {
+  gateway,
+  customProvider,
+  defaultSettingsMiddleware,
+  wrapLanguageModel,
+} from 'ai';
+
+// custom provider with different provider options:
+export const openai = customProvider({
+  languageModels: {
+    // replacement model with custom provider options:
+    'gpt-5.1': wrapLanguageModel({
+      model: gateway('openai/gpt-5.1'),
+      middleware: defaultSettingsMiddleware({
+        settings: {
+          providerOptions: {
+            openai: {
+              reasoningEffort: 'high',
+            },
+          },
+        },
+      }),
+    }),
+    // alias model with custom provider options:
+    'gpt-5.1-high-reasoning': wrapLanguageModel({
+      model: gateway('openai/gpt-5.1'),
+      middleware: defaultSettingsMiddleware({
+        settings: {
+          providerOptions: {
+            openai: {
+              reasoningEffort: 'high',
+            },
+          },
+        },
+      }),
+    }),
+  },
+  fallbackProvider: gateway,
+});
+```
+
+### Example: model name alias
+
+You can also provide model name aliases, so you can update the model version in one place in the future:
+
+```ts
+import { customProvider, gateway } from 'ai';
+
+// custom provider with alias names:
+export const anthropic = customProvider({
+  languageModels: {
+    opus: gateway('anthropic/claude-opus-4.1'),
+    sonnet: gateway('anthropic/claude-sonnet-4.5'),
+    haiku: gateway('anthropic/claude-haiku-4.5'),
+  },
+  fallbackProvider: gateway,
+});
+```
+
+### Example: limit available models
+
+You can limit the available models in the system, even if you have multiple providers.
+
+```ts
+import {
+  customProvider,
+  defaultSettingsMiddleware,
+  wrapLanguageModel,
+  gateway,
+} from 'ai';
+
+export const myProvider = customProvider({
+  languageModels: {
+    'text-medium': gateway('anthropic/claude-3-5-sonnet-20240620'),
+    'text-small': gateway('openai/gpt-5-mini'),
+    'reasoning-medium': wrapLanguageModel({
+      model: gateway('openai/gpt-5.1'),
+      middleware: defaultSettingsMiddleware({
+        settings: {
+          providerOptions: {
+            openai: {
+              reasoningEffort: 'high',
+            },
+          },
+        },
+      }),
+    }),
+    'reasoning-fast': wrapLanguageModel({
+      model: gateway('openai/gpt-5.1'),
+      middleware: defaultSettingsMiddleware({
+        settings: {
+          providerOptions: {
+            openai: {
+              reasoningEffort: 'low',
+            },
+          },
+        },
+      }),
+    }),
+  },
+  embeddingModels: {
+    embedding: gateway.embeddingModel('openai/text-embedding-3-small'),
+  },
+  // no fallback provider
+});
+```
+
+## Provider Registry
+
+You can create a [provider registry](/docs/reference/ai-sdk-core/provider-registry) with multiple providers and models using `createProviderRegistry`.
+
+### Setup
+
+```ts filename={"registry.ts"}
+import { anthropic } from '@ai-sdk/anthropic';
+import { openai } from '@ai-sdk/openai';
+import { createProviderRegistry, gateway } from 'ai';
+
+export const registry = createProviderRegistry({
+  // register provider with prefix and default setup using gateway:
+  gateway,
+
+  // register provider with prefix and direct provider import:
+  anthropic,
+  openai,
+});
+```
+
+### Setup with Custom Separator
+
+By default, the registry uses `:` as the separator between provider and model IDs. You can customize this separator:
+
+```ts filename={"registry.ts"}
+import { anthropic } from '@ai-sdk/anthropic';
+import { openai } from '@ai-sdk/openai';
+import { createProviderRegistry, gateway } from 'ai';
+
+export const customSeparatorRegistry = createProviderRegistry(
+  {
+    gateway,
+    anthropic,
+    openai,
+  },
+  { separator: ' > ' },
+);
+```
+
+### Example: Use language models
+
+You can access language models by using the `languageModel` method on the registry.
+The provider id will become the prefix of the model id: `providerId:modelId`.
+
+```ts highlight={"5"}
+import { generateText } from 'ai';
+import { registry } from './registry';
+
+const { text } = await generateText({
+  model: registry.languageModel('openai:gpt-5.1'), // default separator
+  // or with custom separator:
+  // model: customSeparatorRegistry.languageModel('openai > gpt-5.1'),
+  prompt: 'Invent a new holiday and describe its traditions.',
+});
+```
+
+### Example: Use text embedding models
+
+You can access text embedding models by using the `.embeddingModel` method on the registry.
+The provider id will become the prefix of the model id: `providerId:modelId`.
+
+```ts highlight={"5"}
+import { embed } from 'ai';
+import { registry } from './registry';
+
+const { embedding } = await embed({
+  model: registry.embeddingModel('openai:text-embedding-3-small'),
+  value: 'sunny day at the beach',
+});
+```
+
+### Example: Use image models
+
+You can access image models by using the `imageModel` method on the registry.
+The provider id will become the prefix of the model id: `providerId:modelId`.
+
+```ts highlight={"5"}
+import { generateImage } from 'ai';
+import { registry } from './registry';
+
+const { image } = await generateImage({
+  model: registry.imageModel('openai:dall-e-3'),
+  prompt: 'A beautiful sunset over a calm ocean',
+});
+```
+
+## Combining Custom Providers, Provider Registry, and Middleware
+
+The central idea of provider management is to set up a file that contains all the providers and models you want to use.
+You may want to pre-configure model settings, provide model name aliases, limit the available models, and more.
+
+Here is an example that implements the following concepts:
+
+- pass through gateway with a namespace prefix (here: `gateway > *`)
+- pass through a full provider with a namespace prefix (here: `xai > *`)
+- setup an OpenAI-compatible provider with custom api key and base URL (here: `custom > *`)
+- setup model name aliases (here: `anthropic > fast`, `anthropic > writing`, `anthropic > reasoning`)
+- pre-configure model settings (here: `anthropic > reasoning`)
+- validate the provider-specific options (here: `AnthropicProviderOptions`)
+- use a fallback provider (here: `anthropic > *`)
+- limit a provider to certain models without a fallback (here: `groq > gemma2-9b-it`, `groq > qwen-qwq-32b`)
+- define a custom separator for the provider registry (here: `>`)
+
+```ts
+import { anthropic, AnthropicProviderOptions } from '@ai-sdk/anthropic';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+import { xai } from '@ai-sdk/xai';
+import { groq } from '@ai-sdk/groq';
+import {
+  createProviderRegistry,
+  customProvider,
+  defaultSettingsMiddleware,
+  gateway,
+  wrapLanguageModel,
+} from 'ai';
+
+export const registry = createProviderRegistry(
+  {
+    // pass through gateway with a namespace prefix
+    gateway,
+
+    // pass through full providers with namespace prefixes
+    xai,
+
+    // access an OpenAI-compatible provider with custom setup
+    custom: createOpenAICompatible({
+      name: 'provider-name',
+      apiKey: process.env.CUSTOM_API_KEY,
+      baseURL: 'https://api.custom.com/v1',
+    }),
+
+    // setup model name aliases
+    anthropic: customProvider({
+      languageModels: {
+        fast: anthropic('claude-haiku-4-5'),
+
+        // simple model
+        writing: anthropic('claude-sonnet-4-5'),
+
+        // extended reasoning model configuration:
+        reasoning: wrapLanguageModel({
+          model: anthropic('claude-sonnet-4-5'),
+          middleware: defaultSettingsMiddleware({
+            settings: {
+              maxOutputTokens: 100000, // example default setting
+              providerOptions: {
+                anthropic: {
+                  thinking: {
+                    type: 'enabled',
+                    budgetTokens: 32000,
+                  },
+                } satisfies AnthropicProviderOptions,
+              },
+            },
+          }),
+        }),
+      },
+      fallbackProvider: anthropic,
+    }),
+
+    // limit a provider to certain models without a fallback
+    groq: customProvider({
+      languageModels: {
+        'gemma2-9b-it': groq('gemma2-9b-it'),
+        'qwen-qwq-32b': groq('qwen-qwq-32b'),
+      },
+    }),
+  },
+  { separator: ' > ' },
+);
+
+// usage:
+const model = registry.languageModel('anthropic > reasoning');
+```
+
+## Global Provider Configuration
+
+The AI SDK 5 includes a global provider feature that allows you to specify a model using just a plain model ID string:
+
+```ts
+import { streamText } from 'ai';
+__PROVIDER_IMPORT__;
+
+const result = await streamText({
+  model: __MODEL__, // Uses the global provider (defaults to gateway)
+  prompt: 'Invent a new holiday and describe its traditions.',
+});
+```
+
+By default, the global provider is set to the Vercel AI Gateway.
+
+### Customizing the Global Provider
+
+You can set your own preferred global provider:
+
+```ts filename="setup.ts"
+import { openai } from '@ai-sdk/openai';
+
+// Initialize once during startup:
+globalThis.AI_SDK_DEFAULT_PROVIDER = openai;
+```
+
+```ts filename="app.ts"
+import { streamText } from 'ai';
+
+const result = await streamText({
+  model: 'gpt-5.1', // Uses OpenAI provider without prefix
+  prompt: 'Invent a new holiday and describe its traditions.',
+});
+```
+
+This simplifies provider usage and makes it easier to switch between providers without changing your model references throughout your codebase.

package/docs/03-ai-sdk-core/50-error-handling.mdx

@@ -0,0 +1,149 @@
+---
+title: Error Handling
+description: Learn how to handle errors in the AI SDK Core
+---
+
+# Error Handling
+
+## Handling regular errors
+
+Regular errors are thrown and can be handled using the `try/catch` block.
+
+```ts highlight="3,8-10"
+import { generateText } from 'ai';
+__PROVIDER_IMPORT__;
+
+try {
+  const { text } = await generateText({
+    model: __MODEL__,
+    prompt: 'Write a vegetarian lasagna recipe for 4 people.',
+  });
+} catch (error) {
+  // handle error
+}
+```
+
+See [Error Types](/docs/reference/ai-sdk-errors) for more information on the different types of errors that may be thrown.
+
+## Handling streaming errors (simple streams)
+
+When errors occur during streams that do not support error chunks,
+the error is thrown as a regular error.
+You can handle these errors using the `try/catch` block.
+
+```ts highlight="3,12-14"
+import { streamText } from 'ai';
+__PROVIDER_IMPORT__;
+
+try {
+  const { textStream } = streamText({
+    model: __MODEL__,
+    prompt: 'Write a vegetarian lasagna recipe for 4 people.',
+  });
+
+  for await (const textPart of textStream) {
+    process.stdout.write(textPart);
+  }
+} catch (error) {
+  // handle error
+}
+```
+
+## Handling streaming errors (streaming with `error` support)
+
+Full streams support error parts.
+You can handle those parts similar to other parts.
+It is recommended to also add a try-catch block for errors that
+happen outside of the streaming.
+
+```ts highlight="13-21"
+import { streamText } from 'ai';
+__PROVIDER_IMPORT__;
+
+try {
+  const { fullStream } = streamText({
+    model: __MODEL__,
+    prompt: 'Write a vegetarian lasagna recipe for 4 people.',
+  });
+
+  for await (const part of fullStream) {
+    switch (part.type) {
+      // ... handle other part types
+
+      case 'error': {
+        const error = part.error;
+        // handle error
+        break;
+      }
+
+      case 'abort': {
+        // handle stream abort
+        break;
+      }
+
+      case 'tool-error': {
+        const error = part.error;
+        // handle error
+        break;
+      }
+    }
+  }
+} catch (error) {
+  // handle error
+}
+```
+
+## Handling stream aborts
+
+When streams are aborted (e.g., via chat stop button), you may want to perform cleanup operations like updating stored messages in your UI. Use the `onAbort` callback to handle these cases.
+
+The `onAbort` callback is called when a stream is aborted via `AbortSignal`, but `onFinish` is not called. This ensures you can still update your UI state appropriately.
+
+```ts highlight="5-9"
+import { streamText } from 'ai';
+__PROVIDER_IMPORT__;
+
+const { textStream } = streamText({
+  model: __MODEL__,
+  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
+  onAbort: ({ steps }) => {
+    // Update stored messages or perform cleanup
+    console.log('Stream aborted after', steps.length, 'steps');
+  },
+  onFinish: ({ steps, totalUsage }) => {
+    // This is called on normal completion
+    console.log('Stream completed normally');
+  },
+});
+
+for await (const textPart of textStream) {
+  process.stdout.write(textPart);
+}
+```
+
+The `onAbort` callback receives:
+
+- `steps`: An array of all completed steps before the abort
+
+You can also handle abort events directly in the stream:
+
+```ts highlight="10-13"
+import { streamText } from 'ai';
+__PROVIDER_IMPORT__;
+
+const { fullStream } = streamText({
+  model: __MODEL__,
+  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
+});
+
+for await (const chunk of fullStream) {
+  switch (chunk.type) {
+    case 'abort': {
+      // Handle abort directly in stream
+      console.log('Stream was aborted');
+      break;
+    }
+    // ... handle other part types
+  }
+}
+```

package/docs/03-ai-sdk-core/55-testing.mdx

@@ -0,0 +1,218 @@
+---
+title: Testing
+description: Learn how to use AI SDK Core mock providers for testing.
+---
+
+# Testing
+
+Testing language models can be challenging, because they are non-deterministic
+and calling them is slow and expensive.
+
+To enable you to unit test your code that uses the AI SDK, the AI SDK Core
+includes mock providers and test helpers. You can import the following helpers from `ai/test`:
+
+- `MockEmbeddingModelV3`: A mock embedding model using the [embedding model v3 specification](https://github.com/vercel/ai/blob/main/packages/provider/src/embedding-model/v3/embedding-model-v3.ts).
+- `MockLanguageModelV3`: A mock language model using the [language model v3 specification](https://github.com/vercel/ai/blob/main/packages/provider/src/language-model/v3/language-model-v3.ts).
+- `mockId`: Provides an incrementing integer ID.
+- `mockValues`: Iterates over an array of values with each call. Returns the last value when the array is exhausted.
+- [`simulateReadableStream`](/docs/reference/ai-sdk-core/simulate-readable-stream): Simulates a readable stream with delays.
+
+With mock providers and test helpers, you can control the output of the AI SDK
+and test your code in a repeatable and deterministic way without actually calling
+a language model provider.
+
+## Examples
+
+You can use the test helpers with the AI Core functions in your unit tests:
+
+### generateText
+
+```ts
+import { generateText } from 'ai';
+import { MockLanguageModelV3 } from 'ai/test';
+
+const result = await generateText({
+  model: new MockLanguageModelV3({
+    doGenerate: async () => ({
+      content: [{ type: 'text', text: `Hello, world!` }],
+      finishReason: { unified: 'stop', raw: undefined },
+      usage: {
+        inputTokens: {
+          total: 10,
+          noCache: 10,
+          cacheRead: undefined,
+          cacheWrite: undefined,
+        },
+        outputTokens: {
+          total: 20,
+          text: 20,
+          reasoning: undefined,
+        },
+      },
+      warnings: [],
+    }),
+  }),
+  prompt: 'Hello, test!',
+});
+```
+
+### streamText
+
+```ts
+import { streamText, simulateReadableStream } from 'ai';
+import { MockLanguageModelV3 } from 'ai/test';
+
+const result = streamText({
+  model: new MockLanguageModelV3({
+    doStream: async () => ({
+      stream: simulateReadableStream({
+        chunks: [
+          { type: 'text-start', id: 'text-1' },
+          { type: 'text-delta', id: 'text-1', delta: 'Hello' },
+          { type: 'text-delta', id: 'text-1', delta: ', ' },
+          { type: 'text-delta', id: 'text-1', delta: 'world!' },
+          { type: 'text-end', id: 'text-1' },
+          {
+            type: 'finish',
+            finishReason: { unified: 'stop', raw: undefined },
+            logprobs: undefined,
+            usage: {
+              inputTokens: {
+                total: 3,
+                noCache: 3,
+                cacheRead: undefined,
+                cacheWrite: undefined,
+              },
+              outputTokens: {
+                total: 10,
+                text: 10,
+                reasoning: undefined,
+              },
+            },
+          },
+        ],
+      }),
+    }),
+  }),
+  prompt: 'Hello, test!',
+});
+```
+
+### generateObject
+
+```ts
+import { generateObject } from 'ai';
+import { MockLanguageModelV3 } from 'ai/test';
+import { z } from 'zod';
+
+const result = await generateObject({
+  model: new MockLanguageModelV3({
+    doGenerate: async () => ({
+      content: [{ type: 'text', text: `{"content":"Hello, world!"}` }],
+      finishReason: { unified: 'stop', raw: undefined },
+      usage: {
+        inputTokens: {
+          total: 10,
+          noCache: 10,
+          cacheRead: undefined,
+          cacheWrite: undefined,
+        },
+        outputTokens: {
+          total: 20,
+          text: 20,
+          reasoning: undefined,
+        },
+      },
+      warnings: [],
+    }),
+  }),
+  schema: z.object({ content: z.string() }),
+  prompt: 'Hello, test!',
+});
+```
+
+### streamObject
+
+```ts
+import { streamObject, simulateReadableStream } from 'ai';
+import { MockLanguageModelV3 } from 'ai/test';
+import { z } from 'zod';
+
+const result = streamObject({
+  model: new MockLanguageModelV3({
+    doStream: async () => ({
+      stream: simulateReadableStream({
+        chunks: [
+          { type: 'text-start', id: 'text-1' },
+          { type: 'text-delta', id: 'text-1', delta: '{ ' },
+          { type: 'text-delta', id: 'text-1', delta: '"content": ' },
+          { type: 'text-delta', id: 'text-1', delta: `"Hello, ` },
+          { type: 'text-delta', id: 'text-1', delta: `world` },
+          { type: 'text-delta', id: 'text-1', delta: `!"` },
+          { type: 'text-delta', id: 'text-1', delta: ' }' },
+          { type: 'text-end', id: 'text-1' },
+          {
+            type: 'finish',
+            finishReason: { unified: 'stop', raw: undefined },
+            logprobs: undefined,
+            usage: {
+              inputTokens: {
+                total: 3,
+                noCache: 3,
+                cacheRead: undefined,
+                cacheWrite: undefined,
+              },
+              outputTokens: {
+                total: 10,
+                text: 10,
+                reasoning: undefined,
+              },
+            },
+          },
+        ],
+      }),
+    }),
+  }),
+  schema: z.object({ content: z.string() }),
+  prompt: 'Hello, test!',
+});
+```
+
+### Simulate UI Message Stream Responses
+
+You can also simulate [UI Message Stream](/docs/ai-sdk-ui/stream-protocol#ui-message-stream) responses for testing,
+debugging, or demonstration purposes.
+
+Here is a Next example:
+
+```ts filename="route.ts"
+import { simulateReadableStream } from 'ai';
+
+export async function POST(req: Request) {
+  return new Response(
+    simulateReadableStream({
+      initialDelayInMs: 1000, // Delay before the first chunk
+      chunkDelayInMs: 300, // Delay between chunks
+      chunks: [
+        `data: {"type":"start","messageId":"msg-123"}\n\n`,
+        `data: {"type":"text-start","id":"text-1"}\n\n`,
+        `data: {"type":"text-delta","id":"text-1","delta":"This"}\n\n`,
+        `data: {"type":"text-delta","id":"text-1","delta":" is an"}\n\n`,
+        `data: {"type":"text-delta","id":"text-1","delta":" example."}\n\n`,
+        `data: {"type":"text-end","id":"text-1"}\n\n`,
+        `data: {"type":"finish"}\n\n`,
+        `data: [DONE]\n\n`,
+      ],
+    }).pipeThrough(new TextEncoderStream()),
+    {
+      status: 200,
+      headers: {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive',
+        'x-vercel-ai-ui-message-stream': 'v1',
+      },
+    },
+  );
+}
+```