ai 6.0.31 → 6.0.32

package/docs/07-reference/01-ai-sdk-core/25-json-schema.mdx

@@ -0,0 +1,94 @@
+---
+title: jsonSchema
+description: Helper function for creating JSON schemas
+---
+
+# `jsonSchema()`
+
+`jsonSchema` is a helper function that creates a JSON schema object that is compatible with the AI SDK.
+It takes the JSON schema and an optional validation function as inputs, and can be typed.
+
+You can use it to [generate structured data](/docs/ai-sdk-core/generating-structured-data) and in [tools](/docs/ai-sdk-core/tools-and-tool-calling).
+
+`jsonSchema` is an alternative to using Zod schemas that provides you with flexibility in dynamic situations
+(e.g. when using OpenAPI definitions) or for using other validation libraries.
+
+```ts
+import { jsonSchema } from 'ai';
+
+const mySchema = jsonSchema<{
+  recipe: {
+    name: string;
+    ingredients: { name: string; amount: string }[];
+    steps: string[];
+  };
+}>({
+  type: 'object',
+  properties: {
+    recipe: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        ingredients: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              amount: { type: 'string' },
+            },
+            required: ['name', 'amount'],
+          },
+        },
+        steps: {
+          type: 'array',
+          items: { type: 'string' },
+        },
+      },
+      required: ['name', 'ingredients', 'steps'],
+    },
+  },
+  required: ['recipe'],
+});
+```
+
+## Import
+
+<Snippet text={`import { jsonSchema } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'schema',
+      type: 'JSONSchema7',
+      description: 'The JSON schema definition.',
+    },
+    {
+      name: 'options',
+      type: 'SchemaOptions',
+      description: 'Additional options for the JSON schema.',
+      properties: [
+        {
+          type: 'SchemaOptions',
+          parameters: [
+            {
+              name: 'validate',
+              isOptional: true,
+              type: '(value: unknown) => { success: true; value: OBJECT } | { success: false; error: Error };',
+              description:
+                'A function that validates the value against the JSON schema. If the value is valid, the function should return an object with a `success` property set to `true` and a `value` property set to the validated value. If the value is invalid, the function should return an object with a `success` property set to `false` and an `error` property set to the error.',
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+### Returns
+
+A JSON schema object that is compatible with the AI SDK.

package/docs/07-reference/01-ai-sdk-core/26-zod-schema.mdx

@@ -0,0 +1,109 @@
+---
+title: zodSchema
+description: Helper function for creating Zod schemas
+---
+
+# `zodSchema()`
+
+`zodSchema` is a helper function that converts a Zod schema into a JSON schema object that is compatible with the AI SDK.
+It takes a Zod schema and optional configuration as inputs, and returns a typed schema.
+
+You can use it to [generate structured data](/docs/ai-sdk-core/generating-structured-data) and in [tools](/docs/ai-sdk-core/tools-and-tool-calling).
+
+<Note>
+  You can also pass Zod objects directly to the AI SDK functions. Internally,
+  the AI SDK will convert the Zod schema to a JSON schema using `zodSchema()`.
+  However, if you want to specify options such as `useReferences`, you can pass
+  the `zodSchema()` helper function instead.
+</Note>
+
+<Note type="warning">
+  When using `.meta()` or `.describe()` to add metadata to your Zod schemas,
+  make sure these methods are called **at the end** of the schema chain.
+  
+  metadata is attached to a specific schema
+  instance, and most schema methods (`.min()`, `.optional()`, `.extend()`, etc.)
+  return a new schema instance that does not inherit metadata from the previous one.
+  Due to Zod's immutability, metadata is only included in the JSON schema output
+  if `.meta()` or `.describe()` is the last method in the chain.
+
+```ts
+// ❌ Metadata will be lost - .min() returns a new instance without metadata
+z.string().meta({ describe: 'first name' }).min(1);
+
+// ✅ Metadata is preserved - .meta() is the final method
+z.string().min(1).meta({ describe: 'first name' });
+```
+
+</Note>
+
+## Example with recursive schemas
+
+```ts
+import { zodSchema } from 'ai';
+import { z } from 'zod';
+
+// Define a base category schema
+const baseCategorySchema = z.object({
+  name: z.string(),
+});
+
+// Define the recursive Category type
+type Category = z.infer<typeof baseCategorySchema> & {
+  subcategories: Category[];
+};
+
+// Create the recursive schema using z.lazy
+const categorySchema: z.ZodType<Category> = baseCategorySchema.extend({
+  subcategories: z.lazy(() => categorySchema.array()),
+});
+
+// Create the final schema with useReferences enabled for recursive support
+const mySchema = zodSchema(
+  z.object({
+    category: categorySchema,
+  }),
+  { useReferences: true },
+);
+```
+
+## Import
+
+<Snippet text={`import { zodSchema } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'zodSchema',
+      type: 'z.Schema',
+      description: 'The Zod schema definition.',
+    },
+    {
+      name: 'options',
+      type: 'object',
+      description: 'Additional options for the schema conversion.',
+      properties: [
+        {
+          type: 'object',
+          parameters: [
+            {
+              name: 'useReferences',
+              isOptional: true,
+              type: 'boolean',
+              description:
+                'Enables support for references in the schema. This is required for recursive schemas, e.g. with `z.lazy`. However, not all language models and providers support such references. Defaults to `false`.',
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+### Returns
+
+A Schema object that is compatible with the AI SDK, containing both the JSON schema representation and validation functionality.

package/docs/07-reference/01-ai-sdk-core/27-valibot-schema.mdx

@@ -0,0 +1,55 @@
+---
+title: valibotSchema
+description: Helper function for creating Valibot schemas
+---
+
+# `valibotSchema()`
+
+`valibotSchema` is a helper function that converts a Valibot schema into a JSON schema object
+that is compatible with the AI SDK.
+It takes a Valibot schema as input, and returns a typed schema.
+
+You can use it to [generate structured data](/docs/ai-sdk-core/generating-structured-data) and
+in [tools](/docs/ai-sdk-core/tools-and-tool-calling).
+
+## Example
+
+```ts
+import { valibotSchema } from '@ai-sdk/valibot';
+import { object, string, array } from 'valibot';
+
+const recipeSchema = valibotSchema(
+  object({
+    name: string(),
+    ingredients: array(
+      object({
+        name: string(),
+        amount: string(),
+      }),
+    ),
+    steps: array(string()),
+  }),
+);
+```
+
+## Import
+
+<Snippet text={`import { valibotSchema } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'valibotSchema',
+      type: 'GenericSchema<unknown, T>',
+      description: 'The Valibot schema definition.',
+    },
+  ]}
+/>
+
+### Returns
+
+A Schema object that is compatible with the AI SDK, containing both the JSON schema representation and validation functionality.

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

@@ -0,0 +1,342 @@
+---
+title: Output
+description: API Reference for Output.
+---
+
+# `Output`
+
+The `Output` object provides output specifications for structured data generation with [`generateText`](/docs/reference/ai-sdk-core/generate-text) and [`streamText`](/docs/reference/ai-sdk-core/stream-text). It allows you to specify the expected shape of the generated data and handles validation automatically.
+
+```ts
+import { generateText, Output } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+const { output } = await generateText({
+  model: __MODEL__,
+  output: Output.object({
+    schema: z.object({
+      name: z.string(),
+      age: z.number(),
+    }),
+  }),
+  prompt: 'Generate a user profile.',
+});
+```
+
+## Import
+
+<Snippet text={`import { Output } from "ai"`} prompt={false} />
+
+## Output Types
+
+### `Output.text()`
+
+Output specification for plain text generation. This is the default behavior when no `output` is specified.
+
+```ts
+import { generateText, Output } from 'ai';
+
+const { output } = await generateText({
+  model: yourModel,
+  output: Output.text(),
+  prompt: 'Tell me a joke.',
+});
+// output is a string
+```
+
+#### Parameters
+
+No parameters required.
+
+#### Returns
+
+An `Output<string, string>` specification that generates plain text without schema validation.
+
+---
+
+### `Output.object()`
+
+Output specification for typed object generation using schemas. The output is validated against the provided schema to ensure type safety.
+
+```ts
+import { generateText, Output } from 'ai';
+import { z } from 'zod';
+
+const { output } = await generateText({
+  model: yourModel,
+  output: Output.object({
+    schema: z.object({
+      name: z.string(),
+      age: z.number().nullable(),
+      labels: z.array(z.string()),
+    }),
+  }),
+  prompt: 'Generate information for a test user.',
+});
+// output matches the schema type
+```
+
+#### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'schema',
+      type: 'FlexibleSchema<OBJECT>',
+      description:
+        'The schema that defines the structure of the object to generate. Supports Zod schemas, Standard JSON schemas, and custom JSON schemas.',
+    },
+    {
+      name: 'name',
+      type: 'string',
+      isOptional: true,
+      description:
+        'Optional name of the output that should be generated. Used by some providers for additional LLM guidance, e.g. via tool or schema name.',
+    },
+    {
+      name: 'description',
+      type: 'string',
+      isOptional: true,
+      description:
+        'Optional description of the output that should be generated. Used by some providers for additional LLM guidance, e.g. via tool or schema description.',
+    },
+  ]}
+/>
+
+#### Returns
+
+An `Output<OBJECT, DeepPartial<OBJECT>>` specification where:
+
+- Complete output is fully validated against the schema
+- Partial output (during streaming) is a deep partial version of the schema type
+
+<Note>
+  Partial outputs streamed via `streamText` cannot be validated against your
+  provided schema, as incomplete data may not yet conform to the expected
+  structure.
+</Note>
+
+---
+
+### `Output.array()`
+
+Output specification for generating arrays of typed elements. Each element is validated against the provided element schema.
+
+```ts
+import { generateText, Output } from 'ai';
+import { z } from 'zod';
+
+const { output } = await generateText({
+  model: yourModel,
+  output: Output.array({
+    element: z.object({
+      location: z.string(),
+      temperature: z.number(),
+      condition: z.string(),
+    }),
+  }),
+  prompt: 'List the weather for San Francisco and Paris.',
+});
+// output is an array of weather objects
+```
+
+#### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'element',
+      type: 'FlexibleSchema<ELEMENT>',
+      description:
+        'The schema that defines the structure of each array element. Supports Zod schemas, Valibot schemas, or JSON schemas.',
+    },
+    {
+      name: 'name',
+      type: 'string',
+      isOptional: true,
+      description:
+        'Optional name of the output that should be generated. Used by some providers for additional LLM guidance, e.g. via tool or schema name.',
+    },
+    {
+      name: 'description',
+      type: 'string',
+      isOptional: true,
+      description:
+        'Optional description of the output that should be generated. Used by some providers for additional LLM guidance, e.g. via tool or schema description.',
+    },
+  ]}
+/>
+
+#### Returns
+
+An `Output<Array<ELEMENT>, Array<ELEMENT>>` specification where:
+
+- Complete output is an array with all elements validated
+- Partial output contains only fully validated elements (incomplete elements are excluded)
+
+#### Streaming with `elementStream`
+
+When using `streamText` with `Output.array()`, you can iterate over elements as they are generated using `elementStream`:
+
+```ts
+import { streamText, Output } from 'ai';
+import { z } from 'zod';
+
+const { elementStream } = streamText({
+  model: yourModel,
+  output: Output.array({
+    element: z.object({
+      name: z.string(),
+      class: z.string(),
+      description: z.string(),
+    }),
+  }),
+  prompt: 'Generate 3 hero descriptions for a fantasy role playing game.',
+});
+
+for await (const hero of elementStream) {
+  console.log(hero); // Each hero is complete and validated
+}
+```
+
+<Note>
+  Each element emitted by `elementStream` is complete and validated against your
+  element schema, ensuring type safety for each item as it is generated.
+</Note>
+
+---
+
+### `Output.choice()`
+
+Output specification for selecting from a predefined set of string options. Useful for classification tasks or fixed-enum answers.
+
+```ts
+import { generateText, Output } from 'ai';
+
+const { output } = await generateText({
+  model: yourModel,
+  output: Output.choice({
+    options: ['sunny', 'rainy', 'snowy'],
+  }),
+  prompt: 'Is the weather sunny, rainy, or snowy today?',
+});
+// output is 'sunny' | 'rainy' | 'snowy'
+```
+
+#### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'options',
+      type: 'Array<CHOICE>',
+      description:
+        'An array of string options that the model can choose from. The output will be exactly one of these values.',
+    },
+    {
+      name: 'name',
+      type: 'string',
+      isOptional: true,
+      description:
+        'Optional name of the output that should be generated. Used by some providers for additional LLM guidance, e.g. via tool or schema name.',
+    },
+    {
+      name: 'description',
+      type: 'string',
+      isOptional: true,
+      description:
+        'Optional description of the output that should be generated. Used by some providers for additional LLM guidance, e.g. via tool or schema description.',
+    },
+  ]}
+/>
+
+#### Returns
+
+An `Output<CHOICE, CHOICE>` specification where:
+
+- Complete output is validated to be exactly one of the provided options
+
+---
+
+### `Output.json()`
+
+Output specification for unstructured JSON generation. Use this when you want to generate arbitrary JSON without enforcing a specific schema.
+
+```ts
+import { generateText, Output } from 'ai';
+
+const { output } = await generateText({
+  model: yourModel,
+  output: Output.json(),
+  prompt:
+    'For each city, return the current temperature and weather condition as a JSON object.',
+});
+// output is any valid JSON value
+```
+
+#### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'name',
+      type: 'string',
+      isOptional: true,
+      description:
+        'Optional name of the output that should be generated. Used by some providers for additional LLM guidance, e.g. via tool or schema name.',
+    },
+    {
+      name: 'description',
+      type: 'string',
+      isOptional: true,
+      description:
+        'Optional description of the output that should be generated. Used by some providers for additional LLM guidance, e.g. via tool or schema description.',
+    },
+  ]}
+/>
+
+#### Returns
+
+An `Output<JSONValue, JSONValue>` specification that:
+
+- Validates that the output is valid JSON
+- Does not enforce any specific structure
+
+<Note>
+  With `Output.json()`, the AI SDK only checks that the response is valid JSON;
+  it doesn't validate the structure or types of the values. If you need schema
+  validation, use `Output.object()` or `Output.array()` instead.
+</Note>
+
+## Error Handling
+
+When `generateText` with structured output cannot generate a valid object, it throws a [`NoObjectGeneratedError`](/docs/reference/ai-sdk-errors/ai-no-object-generated-error).
+
+```ts
+import { generateText, Output, NoObjectGeneratedError } from 'ai';
+
+try {
+  await generateText({
+    model: yourModel,
+    output: Output.object({ schema }),
+    prompt: 'Generate a user profile.',
+  });
+} catch (error) {
+  if (NoObjectGeneratedError.isInstance(error)) {
+    console.log('NoObjectGeneratedError');
+    console.log('Cause:', error.cause);
+    console.log('Text:', error.text);
+    console.log('Response:', error.response);
+    console.log('Usage:', error.usage);
+  }
+}
+```
+
+## See also
+
+- [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data)
+- [`generateText()`](/docs/reference/ai-sdk-core/generate-text)
+- [`streamText()`](/docs/reference/ai-sdk-core/stream-text)
+- [`zod-schema`](/docs/reference/ai-sdk-core/zod-schema)
+- [`json-schema`](/docs/reference/ai-sdk-core/json-schema)