ai 6.0.31 → 6.0.32

package/docs/07-reference/01-ai-sdk-core/32-validate-ui-messages.mdx

@@ -0,0 +1,101 @@
+---
+title: validateUIMessages
+description: API Reference for validateUIMessages
+---
+
+# `validateUIMessages`
+
+`validateUIMessages` is an async function that validates UI messages against schemas for metadata, data parts, and tools. It ensures type safety and data integrity for your message arrays before processing or rendering.
+
+## Basic Usage
+
+Simple validation without custom schemas:
+
+```typescript
+import { validateUIMessages } from 'ai';
+
+const messages = [
+  {
+    id: '1',
+    role: 'user',
+    parts: [{ type: 'text', text: 'Hello!' }],
+  },
+];
+
+const validatedMessages = await validateUIMessages({
+  messages,
+});
+```
+
+## Advanced Usage
+
+Comprehensive validation with custom metadata, data parts, and tools:
+
+```typescript
+import { validateUIMessages, tool } from 'ai';
+import { z } from 'zod';
+
+// Define schemas
+const metadataSchema = z.object({
+  timestamp: z.string().datetime(),
+  userId: z.string(),
+});
+
+const dataSchemas = {
+  chart: z.object({
+    data: z.array(z.number()),
+    labels: z.array(z.string()),
+  }),
+  image: z.object({
+    url: z.string().url(),
+    caption: z.string(),
+  }),
+};
+
+const tools = {
+  weather: tool({
+    description: 'Get weather info',
+    parameters: z.object({
+      location: z.string(),
+    }),
+    execute: async ({ location }) => `Weather in ${location}: sunny`,
+  }),
+};
+
+// Messages with custom parts
+const messages = [
+  {
+    id: '1',
+    role: 'user',
+    metadata: { timestamp: '2024-01-01T00:00:00Z', userId: 'user123' },
+    parts: [
+      { type: 'text', text: 'Show me a chart' },
+      {
+        type: 'data-chart',
+        data: { data: [1, 2, 3], labels: ['A', 'B', 'C'] },
+      },
+    ],
+  },
+  {
+    id: '2',
+    role: 'assistant',
+    parts: [
+      {
+        type: 'tool-weather',
+        toolCallId: 'call_123',
+        state: 'output-available',
+        input: { location: 'San Francisco' },
+        output: 'Weather in San Francisco: sunny',
+      },
+    ],
+  },
+];
+
+// Validate with all schemas
+const validatedMessages = await validateUIMessages({
+  messages,
+  metadataSchema,
+  dataSchemas,
+  tools,
+});
+```

package/docs/07-reference/01-ai-sdk-core/33-safe-validate-ui-messages.mdx

@@ -0,0 +1,113 @@
+---
+title: safeValidateUIMessages
+description: API Reference for safeValidateUIMessages
+---
+
+# `safeValidateUIMessages`
+
+`safeValidateUIMessages` is an async function that validates UI messages like [`validateUIMessages`](https://ai-sdk.dev/docs/reference/ai-sdk-core/validate-ui-messages), but instead of throwing it returns an object with a `success` key and either `data` or `error`.
+
+## Basic Usage
+
+Simple validation without custom schemas:
+
+```typescript
+import { safeValidateUIMessages } from 'ai';
+
+const messages = [
+  {
+    id: '1',
+    role: 'user',
+    parts: [{ type: 'text', text: 'Hello!' }],
+  },
+];
+
+const result = await safeValidateUIMessages({
+  messages,
+});
+
+if (!result.success) {
+  console.error(result.error.message);
+} else {
+  const validatedMessages = result.data;
+}
+```
+
+## Advanced Usage
+
+Comprehensive validation with custom metadata, data parts, and tools:
+
+```typescript
+import { safeValidateUIMessages, tool } from 'ai';
+import { z } from 'zod';
+
+// Define schemas
+const metadataSchema = z.object({
+  timestamp: z.string().datetime(),
+  userId: z.string(),
+});
+
+const dataSchemas = {
+  chart: z.object({
+    data: z.array(z.number()),
+    labels: z.array(z.string()),
+  }),
+  image: z.object({
+    url: z.string().url(),
+    caption: z.string(),
+  }),
+};
+
+const tools = {
+  weather: tool({
+    description: 'Get weather info',
+    parameters: z.object({
+      location: z.string(),
+    }),
+    execute: async ({ location }) => `Weather in ${location}: sunny`,
+  }),
+};
+
+// Messages with custom parts
+const messages = [
+  {
+    id: '1',
+    role: 'user',
+    metadata: { timestamp: '2024-01-01T00:00:00Z', userId: 'user123' },
+    parts: [
+      { type: 'text', text: 'Show me a chart' },
+      {
+        type: 'data-chart',
+        data: { data: [1, 2, 3], labels: ['A', 'B', 'C'] },
+      },
+    ],
+  },
+  {
+    id: '2',
+    role: 'assistant',
+    parts: [
+      {
+        type: 'tool-weather',
+        toolCallId: 'call_123',
+        state: 'output-available',
+        input: { location: 'San Francisco' },
+        output: 'Weather in San Francisco: sunny',
+      },
+    ],
+  },
+];
+
+// Validate with all schemas
+const result = await safeValidateUIMessages({
+  messages,
+  metadataSchema,
+  dataSchemas,
+  tools,
+});
+
+if (!result.success) {
+  console.error(result.error.message);
+} else {
+  const validatedMessages = result.data;
+}
+```

package/docs/07-reference/01-ai-sdk-core/40-provider-registry.mdx

@@ -0,0 +1,182 @@
+---
+title: createProviderRegistry
+description: Registry for managing multiple providers and models (API Reference)
+---
+
+# `createProviderRegistry()`
+
+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.
+
+`createProviderRegistry` lets you create a registry with multiple providers that you
+can access by their ids in the format `providerId:modelId`.
+
+### Setup
+
+You can create a registry with multiple providers and models using `createProviderRegistry`.
+
+```ts
+import { anthropic } from '@ai-sdk/anthropic';
+import { createOpenAI } from '@ai-sdk/openai';
+import { createProviderRegistry } from 'ai';
+
+export const registry = createProviderRegistry({
+  // register provider with prefix and default setup:
+  anthropic,
+
+  // register provider with prefix and custom setup:
+  openai: createOpenAI({
+    apiKey: process.env.OPENAI_API_KEY,
+  }),
+});
+```
+
+### Custom Separator
+
+By default, the registry uses `:` as the separator between provider and model IDs. You can customize this separator by passing a `separator` option:
+
+```ts
+const registry = createProviderRegistry(
+  {
+    anthropic,
+    openai,
+  },
+  { separator: ' > ' },
+);
+
+// Now you can use the custom separator
+const model = registry.languageModel('anthropic > claude-3-opus-20240229');
+```
+
+### 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-4.1'),
+  prompt: 'Invent a new holiday and describe its traditions.',
+});
+```
+
+### 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',
+});
+```
+
+### 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',
+});
+```
+
+## Import
+
+<Snippet text={`import { createProviderRegistry } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'providers',
+      type: 'Record<string, Provider>',
+      description:
+        'The unique identifier for the provider. It should be unique within the registry.',
+      properties: [
+        {
+          type: 'Provider',
+          parameters: [
+            {
+              name: 'languageModel',
+              type: '(id: string) => LanguageModel',
+              description:
+                'A function that returns a language model by its id.',
+            },
+            {
+              name: 'embeddingModel',
+              type: '(id: string) => EmbeddingModel<string>',
+              description:
+                'A function that returns a text embedding model by its id.',
+            },
+            {
+              name: 'imageModel',
+              type: '(id: string) => ImageModel',
+              description: 'A function that returns an image model by its id.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'options',
+      type: 'object',
+      description: 'Optional configuration for the registry.',
+      properties: [
+        {
+          type: 'Options',
+          parameters: [
+            {
+              name: 'separator',
+              type: 'string',
+              description:
+                'Custom separator between provider and model IDs. Defaults to ":".',
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+### Returns
+
+The `createProviderRegistry` function returns a `Provider` instance. It has the following methods:
+
+<PropertiesTable
+  content={[
+    {
+      name: 'languageModel',
+      type: '(id: string) => LanguageModel',
+      description:
+        'A function that returns a language model by its id (format: providerId:modelId)',
+    },
+    {
+      name: 'embeddingModel',
+      type: '(id: string) => EmbeddingModel<string>',
+      description:
+        'A function that returns a text embedding model by its id (format: providerId:modelId)',
+    },
+    {
+      name: 'imageModel',
+      type: '(id: string) => ImageModel',
+      description:
+        'A function that returns an image model by its id (format: providerId:modelId)',
+    },
+  ]}
+/>

package/docs/07-reference/01-ai-sdk-core/42-custom-provider.mdx

@@ -0,0 +1,121 @@
+---
+title: customProvider
+description: Custom provider that uses models from a different provider (API Reference)
+---
+
+# `customProvider()`
+
+With a custom provider, you can map ids to any model.
+This allows you to set up custom model configurations, alias names, and more.
+The custom provider also supports a fallback provider, which is useful for
+wrapping existing providers and adding additional functionality.
+
+### Example: custom model settings
+
+You can create a custom provider using `customProvider`.
+
+```ts
+import { openai } from '@ai-sdk/openai';
+import { customProvider } from 'ai';
+
+// custom provider with different model settings:
+export const myOpenAI = customProvider({
+  languageModels: {
+    // replacement model with custom settings:
+    'gpt-4': wrapLanguageModel({
+      model: openai('gpt-4'),
+      middleware: defaultSettingsMiddleware({
+        settings: {
+          providerOptions: {
+            openai: {
+              reasoningEffort: 'high',
+            },
+          },
+        },
+      }),
+    }),
+    // alias model with custom settings:
+    'gpt-4o-reasoning-high': wrapLanguageModel({
+      model: openai('gpt-4o'),
+      middleware: defaultSettingsMiddleware({
+        settings: {
+          providerOptions: {
+            openai: {
+              reasoningEffort: 'high',
+            },
+          },
+        },
+      }),
+    }),
+  },
+  fallbackProvider: openai,
+});
+```
+
+## Import
+
+<Snippet text={`import {  customProvider } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'languageModels',
+      type: 'Record<string, LanguageModel>',
+      isOptional: true,
+      description:
+        'A record of language models, where keys are model IDs and values are LanguageModel instances.',
+    },
+    {
+      name: '.embeddingModels',
+      type: 'Record<string, EmbeddingModel<string>>',
+      isOptional: true,
+      description:
+        'A record of text embedding models, where keys are model IDs and values are EmbeddingModel<string> instances.',
+    },
+    {
+      name: 'imageModels',
+      type: 'Record<string, ImageModel>',
+      isOptional: true,
+      description:
+        'A record of image models, where keys are model IDs and values are image model instances.',
+    },
+    {
+      name: 'fallbackProvider',
+      type: 'Provider',
+      isOptional: true,
+      description:
+        'An optional fallback provider to use when a requested model is not found in the custom provider.',
+    },
+  ]}
+/>
+
+### Returns
+
+The `customProvider` function returns a `Provider` instance. It has the following methods:
+
+<PropertiesTable
+  content={[
+    {
+      name: 'languageModel',
+      type: '(id: string) => LanguageModel',
+      description:
+        'A function that returns a language model by its id (format: providerId:modelId)',
+    },
+    {
+      name: 'embeddingModel',
+      type: '(id: string) => EmbeddingModel<string>',
+      description:
+        'A function that returns a text embedding model by its id (format: providerId:modelId)',
+    },
+    {
+      name: 'imageModel',
+      type: '(id: string) => ImageModel',
+      description:
+        'A function that returns an image model by its id (format: providerId:modelId)',
+    },
+  ]}
+/>

package/docs/07-reference/01-ai-sdk-core/50-cosine-similarity.mdx

@@ -0,0 +1,52 @@
+---
+title: cosineSimilarity
+description: Calculate the cosine similarity between two vectors (API Reference)
+---
+
+# `cosineSimilarity()`
+
+When you want to compare the similarity of embeddings, standard vector similarity metrics
+like cosine similarity are often used.
+
+`cosineSimilarity` calculates the cosine similarity between two vectors.
+A high value (close to 1) indicates that the vectors are very similar, while a low value (close to -1) indicates that they are different.
+
+```ts
+import { cosineSimilarity, embedMany } from 'ai';
+
+const { embeddings } = await embedMany({
+  model: 'openai/text-embedding-3-small',
+  values: ['sunny day at the beach', 'rainy afternoon in the city'],
+});
+
+console.log(
+  `cosine similarity: ${cosineSimilarity(embeddings[0], embeddings[1])}`,
+);
+```
+
+## Import
+
+<Snippet text={`import { cosineSimilarity } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'vector1',
+      type: 'number[]',
+      description: 'The first vector to compare',
+    },
+    {
+      name: 'vector2',
+      type: 'number[]',
+      description: 'The second vector to compare',
+    },
+  ]}
+/>
+
+### Returns
+
+A number between -1 and 1 representing the cosine similarity between the two vectors.

package/docs/07-reference/01-ai-sdk-core/60-wrap-language-model.mdx

@@ -0,0 +1,59 @@
+---
+title: wrapLanguageModel
+description: Function for wrapping a language model with middleware (API Reference)
+---
+
+# `wrapLanguageModel()`
+
+The `wrapLanguageModel` function provides a way to enhance the behavior of language models
+by wrapping them with middleware.
+See [Language Model Middleware](/docs/ai-sdk-core/middleware) for more information on middleware.
+
+```ts
+import { wrapLanguageModel, gateway } from 'ai';
+
+const wrappedLanguageModel = wrapLanguageModel({
+  model: gateway('openai/gpt-4.1'),
+  middleware: yourLanguageModelMiddleware,
+});
+```
+
+## Import
+
+<Snippet text={`import { wrapLanguageModel } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'model',
+      type: 'LanguageModelV3',
+      description: 'The original LanguageModelV3 instance to be wrapped.',
+    },
+    {
+      name: 'middleware',
+      type: 'LanguageModelV3Middleware | LanguageModelV3Middleware[]',
+      description:
+        'The middleware to be applied to the language model. When multiple middlewares are provided, the first middleware will transform the input first, and the last middleware will be wrapped directly around the model.',
+    },
+    {
+      name: 'modelId',
+      type: 'string',
+      description:
+        "Optional custom model ID to override the original model's ID.",
+    },
+    {
+      name: 'providerId',
+      type: 'string',
+      description:
+        "Optional custom provider ID to override the original model's provider.",
+    },
+  ]}
+/>
+
+### Returns
+
+A new `LanguageModelV3` instance with middleware applied.

package/docs/07-reference/01-ai-sdk-core/61-wrap-image-model.mdx

@@ -0,0 +1,64 @@
+---
+title: wrapImageModel
+description: Function for wrapping an image model with middleware (API Reference)
+---
+
+# `wrapImageModel()`
+
+The `wrapImageModel` function provides a way to enhance the behavior of image models
+by wrapping them with middleware.
+
+```ts
+import { generateImage, wrapImageModel } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const model = wrapImageModel({
+  model: openai.image('gpt-image-1'),
+  middleware: yourImageModelMiddleware,
+});
+
+const { image } = await generateImage({
+  model,
+  prompt: 'Santa Claus driving a Cadillac',
+});
+```
+
+## Import
+
+<Snippet text={`import { wrapImageModel } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'model',
+      type: 'ImageModelV3',
+      description: 'The original ImageModelV3 instance to be wrapped.',
+    },
+    {
+      name: 'middleware',
+      type: 'ImageModelV3Middleware | ImageModelV3Middleware[]',
+      description:
+        'The middleware to be applied to the image model. When multiple middlewares are provided, the first middleware will transform the input first, and the last middleware will be wrapped directly around the model.',
+    },
+    {
+      name: 'modelId',
+      type: 'string',
+      description:
+        "Optional custom model ID to override the original model's ID.",
+    },
+    {
+      name: 'providerId',
+      type: 'string',
+      description:
+        "Optional custom provider ID to override the original model's provider.",
+    },
+  ]}
+/>
+
+### Returns
+
+A new `ImageModelV3` instance with middleware applied.