@fondation-io/ai 7.0.0-beta.45

package/docs/03-ai-sdk-core/25-settings.mdx

@@ -0,0 +1,216 @@
+---
+title: Settings
+description: Learn how to configure the AI SDK.
+---
+
+# Settings
+
+Large language models (LLMs) typically provide settings to augment their output.
+
+All AI SDK functions support the following common settings in addition to the model, the [prompt](./prompts), and additional provider-specific settings:
+
+```ts highlight="3-5"
+const result = await generateText({
+  model: __MODEL__,
+  maxOutputTokens: 512,
+  temperature: 0.3,
+  maxRetries: 5,
+  prompt: 'Invent a new holiday and describe its traditions.',
+});
+```
+
+<Note>
+  Some providers do not support all common settings. If you use a setting with a
+  provider that does not support it, a warning will be generated. You can check
+  the `warnings` property in the result object to see if any warnings were
+  generated.
+</Note>
+
+### `maxOutputTokens`
+
+Maximum number of tokens to generate.
+
+### `temperature`
+
+Temperature setting.
+
+The value is passed through to the provider. The range depends on the provider and model.
+For most providers, `0` means almost deterministic results, and higher values mean more randomness.
+
+It is recommended to set either `temperature` or `topP`, but not both.
+
+<Note>In AI SDK 5.0, temperature is no longer set to `0` by default.</Note>
+
+### `topP`
+
+Nucleus sampling.
+
+The value is passed through to the provider. The range depends on the provider and model.
+For most providers, nucleus sampling is a number between 0 and 1.
+E.g. 0.1 would mean that only tokens with the top 10% probability mass are considered.
+
+It is recommended to set either `temperature` or `topP`, but not both.
+
+### `topK`
+
+Only sample from the top K options for each subsequent token.
+
+Used to remove "long tail" low probability responses.
+Recommended for advanced use cases only. You usually only need to use `temperature`.
+
+### `presencePenalty`
+
+The presence penalty affects the likelihood of the model to repeat information that is already in the prompt.
+
+The value is passed through to the provider. The range depends on the provider and model.
+For most providers, `0` means no penalty.
+
+### `frequencyPenalty`
+
+The frequency penalty affects the likelihood of the model to repeatedly use the same words or phrases.
+
+The value is passed through to the provider. The range depends on the provider and model.
+For most providers, `0` means no penalty.
+
+### `stopSequences`
+
+The stop sequences to use for stopping the text generation.
+
+If set, the model will stop generating text when one of the stop sequences is generated.
+Providers may have limits on the number of stop sequences.
+
+### `seed`
+
+It is the seed (integer) to use for random sampling.
+If set and supported by the model, calls will generate deterministic results.
+
+### `reasoning`
+
+Controls how much reasoning the model performs before generating a response.
+
+| Value                | Behavior                                                             |
+| -------------------- | -------------------------------------------------------------------- |
+| `'provider-default'` | Use the provider's default reasoning behavior (default when omitted) |
+| `'none'`             | Disable reasoning                                                    |
+| `'minimal'`          | Bare-minimum reasoning                                               |
+| `'low'`              | Fast, concise reasoning                                              |
+| `'medium'`           | Balanced reasoning                                                   |
+| `'high'`             | Thorough reasoning                                                   |
+| `'xhigh'`            | Maximum reasoning                                                    |
+
+If you also set reasoning-related options in `providerOptions` (e.g. `openai.reasoningEffort` or `anthropic.thinking`), the provider-specific options take precedence and the top-level `reasoning` parameter is ignored.
+
+See the [reasoning guide](/docs/ai-sdk-core/reasoning) for details on per-provider mapping and migration from `providerOptions`.
+
+### `maxRetries`
+
+Maximum number of retries. Set to 0 to disable retries. Default: `2`.
+
+### `abortSignal`
+
+An optional abort signal that can be used to cancel the call.
+
+The abort signal can e.g. be forwarded from a user interface to cancel the call,
+or to define a timeout using `AbortSignal.timeout`.
+
+#### Example: AbortSignal.timeout
+
+```ts
+const result = await generateText({
+  model: __MODEL__,
+  prompt: 'Invent a new holiday and describe its traditions.',
+  abortSignal: AbortSignal.timeout(5000), // 5 seconds
+});
+```
+
+### `timeout`
+
+An optional timeout in milliseconds. The call will be aborted if it takes longer than the specified duration.
+
+This is a convenience parameter that creates an abort signal internally. It can be used alongside `abortSignal` - if both are provided, the call will abort when either condition is met.
+
+You can specify the timeout either as a number (milliseconds) or as an object with `totalMs`, `stepMs`, and/or `chunkMs` properties:
+
+- `totalMs`: The total timeout for the entire call including all steps.
+- `stepMs`: The timeout for each individual step (LLM call). This is useful for multi-step generations where you want to limit the time spent on each step independently.
+- `chunkMs`: The timeout between stream chunks (streaming only). The call will abort if no new chunk is received within this duration. This is useful for detecting stalled streams.
+
+#### Example: 5 second timeout (number format)
+
+```ts
+const result = await generateText({
+  model: __MODEL__,
+  prompt: 'Invent a new holiday and describe its traditions.',
+  timeout: 5000, // 5 seconds
+});
+```
+
+#### Example: 5 second total timeout (object format)
+
+```ts
+const result = await generateText({
+  model: __MODEL__,
+  prompt: 'Invent a new holiday and describe its traditions.',
+  timeout: { totalMs: 5000 }, // 5 seconds
+});
+```
+
+#### Example: 10 second step timeout
+
+```ts
+const result = await generateText({
+  model: __MODEL__,
+  prompt: 'Invent a new holiday and describe its traditions.',
+  timeout: { stepMs: 10000 }, // 10 seconds per step
+});
+```
+
+#### Example: Combined total and step timeout
+
+```ts
+const result = await generateText({
+  model: __MODEL__,
+  prompt: 'Invent a new holiday and describe its traditions.',
+  timeout: {
+    totalMs: 60000, // 60 seconds total
+    stepMs: 10000, // 10 seconds per step
+  },
+});
+```
+
+#### Example: Per-chunk timeout for streaming (streamText only)
+
+```ts
+const result = streamText({
+  model: __MODEL__,
+  prompt: 'Invent a new holiday and describe its traditions.',
+  timeout: { chunkMs: 5000 }, // abort if no chunk received for 5 seconds
+});
+```
+
+### `headers`
+
+Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.
+
+You can use the request headers to provide additional information to the provider,
+depending on what the provider supports. For example, some observability providers support
+headers such as `Prompt-Id`.
+
+```ts
+import { generateText } from 'ai';
+__PROVIDER_IMPORT__;
+
+const result = await generateText({
+  model: __MODEL__,
+  prompt: 'Invent a new holiday and describe its traditions.',
+  headers: {
+    'Prompt-Id': 'my-prompt-id',
+  },
+});
+```
+
+<Note>
+  The `headers` setting is for request-specific headers. You can also set
+  `headers` in the provider configuration. These headers will be sent with every
+  request made by the provider.
+</Note>

package/docs/03-ai-sdk-core/26-reasoning.mdx

@@ -0,0 +1,190 @@
+---
+title: Reasoning
+description: Learn how to control reasoning across providers with the top-level reasoning parameter.
+---
+
+# Reasoning
+
+Many language models support an internal "reasoning" phase (sometimes also called "thinking") before producing a response. The AI SDK provides a top-level `reasoning` parameter on [`generateText`](/docs/reference/ai-sdk-core/generate-text) and [`streamText`](/docs/reference/ai-sdk-core/stream-text) that controls this behavior across providers with a single, portable setting.
+
+## Basic Usage
+
+```ts
+import { generateText } from 'ai';
+
+const { text, reasoning, reasoningText } = await generateText({
+  model: 'anthropic/claude-sonnet-4.6,
+  reasoning: 'medium',
+  prompt: 'How many people will live in the world in 2040?',
+});
+```
+
+The `reasoning` parameter accepts the following values:
+
+| Value                | Behavior                                                             |
+| -------------------- | -------------------------------------------------------------------- |
+| `'provider-default'` | Use the provider's default reasoning behavior (default when omitted) |
+| `'none'`             | Disable reasoning                                                    |
+| `'minimal'`          | Bare-minimum reasoning                                               |
+| `'low'`              | Fast, concise reasoning                                              |
+| `'medium'`           | Balanced reasoning                                                   |
+| `'high'`             | Thorough reasoning                                                   |
+| `'xhigh'`            | Maximum reasoning                                                    |
+
+## Streaming
+
+The `reasoning` parameter works the same way with `streamText`:
+
+```ts
+import { streamText } from 'ai';
+
+const result = streamText({
+  model: 'google/gemini-3-flash-preview',
+  reasoning: 'high',
+  prompt: 'Explain the Riemann hypothesis in simple terms.',
+});
+
+for await (const part of result.fullStream) {
+  if (part.type === 'reasoning') {
+    process.stdout.write(part.textDelta);
+  } else if (part.type === 'text-delta') {
+    process.stdout.write(part.textDelta);
+  }
+}
+```
+
+## Precedence Rules
+
+The top-level `reasoning` parameter and provider-specific `providerOptions` are **never merged**. If you set reasoning-related options in `providerOptions`, they take full precedence and the top-level `reasoning` parameter is ignored.
+
+```ts
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const { text } = await generateText({
+  model: openai.responses('gpt-5.4'),
+  reasoning: 'low', // ignored because providerOptions.openai.reasoningEffort is set
+  providerOptions: {
+    openai: {
+      reasoningEffort: 'high', // this wins
+    },
+  },
+  prompt: 'Explain quantum entanglement.',
+});
+```
+
+This design lets you use the portable `reasoning` parameter by default and fall back to `providerOptions` only when you need provider-specific features like exact token budgets.
+
+## Provider Support
+
+The `reasoning` parameter is supported by the following providers: OpenAI, Anthropic, Google, xAI, Groq, DeepSeek, Fireworks, and Amazon Bedrock. Each provider translates the value to its native reasoning API. Some providers support all six levels natively, while others coerce to fewer levels (a warning is emitted when coercion occurs). Some providers use a numeric token budget instead of an enum for reasoning control; in those cases the top-level `reasoning` value is mapped to a budget calculated as a percentage of the model's maximum output tokens.
+
+Providers that do not support reasoning (e.g. Mistral, Perplexity, Cohere) emit an `unsupported` warning and ignore the parameter.
+
+## Migrating from `providerOptions`
+
+If you currently control reasoning via `providerOptions`, you can migrate to the top-level `reasoning` parameter for portability across providers.
+
+### Before (Anthropic)
+
+```ts
+const { text } = await generateText({
+  model: anthropic('claude-opus-4.6'),
+  providerOptions: {
+    anthropic: {
+      thinking: { type: 'adaptive', effort: 'high' },
+    },
+  },
+  prompt: 'How many people will live in the world in 2040?',
+});
+```
+
+### After (Anthropic)
+
+```ts
+const { text } = await generateText({
+  model: anthropic('claude-opus-4.6'),
+  reasoning: 'high',
+  prompt: 'How many people will live in the world in 2040?',
+});
+```
+
+### Before (Anthropic with older model)
+
+```ts
+const { text } = await generateText({
+  model: anthropic('claude-sonnet-4-20250514'),
+  providerOptions: {
+    anthropic: {
+      thinking: { type: 'enabled', budgetTokens: 12000 },
+    },
+  },
+  prompt: 'How many people will live in the world in 2040?',
+});
+```
+
+### After (Anthropic with older model)
+
+```ts
+const { text } = await generateText({
+  model: anthropic('claude-sonnet-4-20250514'),
+  reasoning: 'medium',
+  prompt: 'How many people will live in the world in 2040?',
+});
+```
+
+If you need to enforce an exact token budget (e.g. exactly 12000 tokens), keep using `providerOptions` instead of the top-level `reasoning` parameter.
+
+### Before (Google with `includeThoughts`)
+
+```ts
+const { text } = await generateText({
+  model: google('gemini-3-flash-preview'),
+  providerOptions: {
+    google: {
+      thinkingConfig: { thinkingBudget: 4096, includeThoughts: true },
+    },
+  },
+  prompt: 'Explain the Riemann hypothesis in simple terms.',
+});
+```
+
+### After (Google with `includeThoughts`)
+
+```ts
+const { text } = await generateText({
+  model: google('gemini-3-flash-preview'),
+  reasoning: 'medium',
+  providerOptions: {
+    google: { thinkingConfig: { includeThoughts: true } },
+  },
+  prompt: 'Explain the Riemann hypothesis in simple terms.',
+});
+```
+
+### Before (OpenAI with `reasoningSummary`)
+
+```ts
+const { text } = await generateText({
+  model: openai.responses('o3'),
+  providerOptions: {
+    openai: { reasoningEffort: 'high', reasoningSummary: 'auto' },
+  },
+  prompt: 'Explain quantum entanglement.',
+});
+```
+
+### After (OpenAI with `reasoningSummary`)
+
+```ts
+const { text } = await generateText({
+  model: openai.responses('o3'),
+  reasoning: 'high',
+  providerOptions: {
+    openai: { reasoningSummary: 'auto' },
+  },
+  prompt: 'Explain quantum entanglement.',
+});
+```
+
+Note that `providerOptions` can still be used alongside `reasoning` for provider-specific features unrelated to reasoning effort. However, if `providerOptions` includes reasoning effort/budget settings (e.g. `reasoningEffort`, `thinking`, `thinkingConfig.thinkingBudget`), those take full precedence and the top-level `reasoning` parameter is ignored.

package/docs/03-ai-sdk-core/30-embeddings.mdx

@@ -0,0 +1,236 @@
+---
+title: Embeddings
+description: Learn how to embed values with the AI SDK.
+---
+
+# Embeddings
+
+Embeddings are a way to represent words, phrases, or images as vectors in a high-dimensional space.
+In this space, similar words are close to each other, and the distance between words can be used to measure their similarity.
+
+## Embedding a Single Value
+
+The AI SDK provides the [`embed`](/docs/reference/ai-sdk-core/embed) function to embed single values, which is useful for tasks such as finding similar words
+or phrases or clustering text.
+You can use it with embeddings models, e.g. `openai.embeddingModel('text-embedding-3-large')` or `mistral.embeddingModel('mistral-embed')`.
+
+```tsx
+import { embed } from 'ai';
+
+// 'embedding' is a single embedding object (number[])
+const { embedding } = await embed({
+  model: 'openai/text-embedding-3-small',
+  value: 'sunny day at the beach',
+});
+```
+
+## Embedding Many Values
+
+When loading data, e.g. when preparing a data store for retrieval-augmented generation (RAG),
+it is often useful to embed many values at once (batch embedding).
+
+The AI SDK provides the [`embedMany`](/docs/reference/ai-sdk-core/embed-many) function for this purpose.
+Similar to `embed`, you can use it with embeddings models,
+e.g. `openai.embeddingModel('text-embedding-3-large')` or `mistral.embeddingModel('mistral-embed')`.
+
+```tsx
+import { embedMany } from 'ai';
+
+// 'embeddings' is an array of embedding objects (number[][]).
+// It is sorted in the same order as the input values.
+const { embeddings } = await embedMany({
+  model: 'openai/text-embedding-3-small',
+  values: [
+    'sunny day at the beach',
+    'rainy afternoon in the city',
+    'snowy night in the mountains',
+  ],
+});
+```
+
+## Embedding Similarity
+
+After embedding values, you can calculate the similarity between them using the [`cosineSimilarity`](/docs/reference/ai-sdk-core/cosine-similarity) function.
+This is useful to e.g. find similar words or phrases in a dataset.
+You can also rank and filter related items based on their similarity.
+
+```ts highlight={"1,9"}
+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])}`,
+);
+```
+
+## Token Usage
+
+Many providers charge based on the number of tokens used to generate embeddings.
+Both `embed` and `embedMany` provide token usage information in the `usage` property of the result object:
+
+```ts highlight={"3,8"}
+import { embed } from 'ai';
+
+const { embedding, usage } = await embed({
+  model: 'openai/text-embedding-3-small',
+  value: 'sunny day at the beach',
+});
+
+console.log(usage); // { tokens: 10 }
+```
+
+## Settings
+
+### Provider Options
+
+Embedding model settings can be configured using `providerOptions` for provider-specific parameters:
+
+```ts highlight={"4-8"}
+import { embed } from 'ai';
+
+const { embedding } = await embed({
+  model: 'openai/text-embedding-3-small',
+  value: 'sunny day at the beach',
+  providerOptions: {
+    openai: {
+      dimensions: 512, // Reduce embedding dimensions
+    },
+  },
+});
+```
+
+### Parallel Requests
+
+The `embedMany` function now supports parallel processing with configurable `maxParallelCalls` to optimize performance:
+
+```ts highlight={"3"}
+import { embedMany } from 'ai';
+
+const { embeddings, usage } = await embedMany({
+  maxParallelCalls: 2, // Limit parallel requests
+  model: 'openai/text-embedding-3-small',
+  values: [
+    'sunny day at the beach',
+    'rainy afternoon in the city',
+    'snowy night in the mountains',
+  ],
+});
+```
+
+### Retries
+
+Both `embed` and `embedMany` accept an optional `maxRetries` parameter of type `number`
+that you can use to set the maximum number of retries for the embedding process.
+It defaults to `2` retries (3 attempts in total). You can set it to `0` to disable retries.
+
+```ts highlight={"6"}
+import { embed } from 'ai';
+
+const { embedding } = await embed({
+  model: 'openai/text-embedding-3-small',
+  value: 'sunny day at the beach',
+  maxRetries: 0, // Disable retries
+});
+```
+
+### Abort Signals and Timeouts
+
+Both `embed` and `embedMany` accept an optional `abortSignal` parameter of
+type [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
+that you can use to abort the embedding process or set a timeout.
+
+```ts highlight={"6"}
+import { embed } from 'ai';
+
+const { embedding } = await embed({
+  model: 'openai/text-embedding-3-small',
+  value: 'sunny day at the beach',
+  abortSignal: AbortSignal.timeout(1000), // Abort after 1 second
+});
+```
+
+### Custom Headers
+
+Both `embed` and `embedMany` accept an optional `headers` parameter of type `Record<string, string>`
+that you can use to add custom headers to the embedding request.
+
+```ts highlight={"6"}
+import { embed } from 'ai';
+
+const { embedding } = await embed({
+  model: 'openai/text-embedding-3-small',
+  value: 'sunny day at the beach',
+  headers: { 'X-Custom-Header': 'custom-value' },
+});
+```
+
+## Response Information
+
+Both `embed` and `embedMany` return response information that includes the raw provider response:
+
+```ts highlight={"3,8"}
+import { embed } from 'ai';
+
+const { embedding, response } = await embed({
+  model: 'openai/text-embedding-3-small',
+  value: 'sunny day at the beach',
+});
+
+console.log(response); // Raw provider response
+```
+
+## Embedding Middleware
+
+You can enhance embedding models, e.g. to set default values, using
+`wrapEmbeddingModel` and `EmbeddingModelMiddleware`.
+
+Here is an example that uses the built-in `defaultEmbeddingSettingsMiddleware`:
+
+```ts
+import {
+  defaultEmbeddingSettingsMiddleware,
+  embed,
+  wrapEmbeddingModel,
+  gateway,
+} from 'ai';
+
+const embeddingModelWithDefaults = wrapEmbeddingModel({
+  model: gateway.embeddingModel('google/gemini-embedding-001'),
+  middleware: defaultEmbeddingSettingsMiddleware({
+    settings: {
+      providerOptions: {
+        google: {
+          outputDimensionality: 256,
+          taskType: 'CLASSIFICATION',
+        },
+      },
+    },
+  }),
+});
+```
+
+## Embedding Providers & Models
+
+Several providers offer embedding models:
+
+| Provider                                                                                  | Model                           | Embedding Dimensions | Multimodal          |
+| ----------------------------------------------------------------------------------------- | ------------------------------- | -------------------- | ------------------- |
+| [OpenAI](/providers/ai-sdk-providers/openai#embedding-models)                             | `text-embedding-3-large`        | 3072                 | <Cross size={18} /> |
+| [OpenAI](/providers/ai-sdk-providers/openai#embedding-models)                             | `text-embedding-3-small`        | 1536                 | <Cross size={18} /> |
+| [OpenAI](/providers/ai-sdk-providers/openai#embedding-models)                             | `text-embedding-ada-002`        | 1536                 | <Cross size={18} /> |
+| [Google Generative AI](/providers/ai-sdk-providers/google-generative-ai#embedding-models) | `gemini-embedding-001`          | 3072                 | <Cross size={18} /> |
+| [Google Generative AI](/providers/ai-sdk-providers/google-generative-ai#embedding-models) | `gemini-embedding-2-preview`    | 3072                 | <Check size={18} /> |
+| [Mistral](/providers/ai-sdk-providers/mistral#embedding-models)                           | `mistral-embed`                 | 1024                 | <Cross size={18} /> |
+| [Cohere](/providers/ai-sdk-providers/cohere#embedding-models)                             | `embed-english-v3.0`            | 1024                 | <Cross size={18} /> |
+| [Cohere](/providers/ai-sdk-providers/cohere#embedding-models)                             | `embed-multilingual-v3.0`       | 1024                 | <Cross size={18} /> |
+| [Cohere](/providers/ai-sdk-providers/cohere#embedding-models)                             | `embed-english-light-v3.0`      | 384                  | <Cross size={18} /> |
+| [Cohere](/providers/ai-sdk-providers/cohere#embedding-models)                             | `embed-multilingual-light-v3.0` | 384                  | <Cross size={18} /> |
+| [Cohere](/providers/ai-sdk-providers/cohere#embedding-models)                             | `embed-english-v2.0`            | 4096                 | <Cross size={18} /> |
+| [Cohere](/providers/ai-sdk-providers/cohere#embedding-models)                             | `embed-english-light-v2.0`      | 1024                 | <Cross size={18} /> |
+| [Cohere](/providers/ai-sdk-providers/cohere#embedding-models)                             | `embed-multilingual-v2.0`       | 768                  | <Cross size={18} /> |
+| [Amazon Bedrock](/providers/ai-sdk-providers/amazon-bedrock#embedding-models)             | `amazon.titan-embed-text-v1`    | 1536                 | <Cross size={18} /> |
+| [Amazon Bedrock](/providers/ai-sdk-providers/amazon-bedrock#embedding-models)             | `amazon.titan-embed-text-v2:0`  | 1024                 | <Cross size={18} /> |