@tanstack/ai 0.26.1 → 0.27.0

package/dist/esm/utilities/sampling-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling-keys.js","sources":["../../../src/utilities/sampling-keys.ts"],"sourcesContent":["/**\n * Single source of truth for the provider-native key spellings that cap output\n * tokens. Sampling options live in opaque, provider-native `modelOptions`, and\n * every provider spells the token cap differently. Two call sites must agree on\n * this set or they silently drift:\n *\n * - `activities/summarize/chat-stream-summarize.ts` — detects a caller-supplied\n *   token limit so the summarize default never overrides it.\n * - `middlewares/otel.ts` — picks the first numeric spelling to populate the\n *   `gen_ai.request.max_tokens` attribute across providers.\n *\n * Keep this list in lockstep with `MAX_TOKENS_KEY_BY_ADAPTER` (the adapter →\n * native-key map) in the summarize wrapper.\n */\nexport const MAX_TOKENS_KEYS = [\n  'max_output_tokens', // OpenAI (Responses)\n  'max_tokens', // Anthropic / Grok\n  'max_completion_tokens', // Groq\n  'maxOutputTokens', // Gemini\n  'maxCompletionTokens', // OpenRouter\n  'maxTokens', // generic / migration leftover (no adapter reads it)\n] as const\n\n/**\n * Ollama nests sampling under `options`; its token cap is `options.num_predict`\n * rather than a flat key.\n */\nexport const NESTED_MAX_TOKENS_KEY = 'num_predict' as const\n"],"names":[],"mappings":"AAcO,MAAM,kBAAkB;AAAA,EAC7B;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AACF;AAMO,MAAM,wBAAwB;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -68,7 +68,7 @@
     "@ag-ui/core": "^0.0.52",
     "@standard-schema/spec": "^1.1.0",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "0.5.2"
+    "@tanstack/ai-event-client": "0.5.3"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.9.0"

package/skills/ai-core/adapter-configuration/SKILL.md

@@ -44,8 +44,10 @@ import { openaiText } from '@tanstack/ai-openai'
 const stream = chat({
   adapter: openaiText('gpt-5.2'),
   messages,
-  temperature: 0.7,
-  maxTokens: 1000,
+  modelOptions: {
+    temperature: 0.7,
+    max_output_tokens: 1000,
+  },
 })
 
 return toServerSentEventsResponse(stream)
@@ -55,6 +57,11 @@ The adapter factory function takes the model name as a string literal and an
 optional config object (API key, base URL, etc.). The model name is passed
 into the factory, not into `chat()`.
 
+Sampling options (`temperature`, token limits, `top_p`/`topP`, etc.) live
+inside `modelOptions` using each provider's native key — they are **not**
+top-level options on `chat()`. See the per-provider table in
+[Configuring Sampling](#5-configuring-sampling) below.
+
 ## Core Patterns
 
 ### 1. Adapter Selection
@@ -158,11 +165,11 @@ const openaiStream = chat({
 const anthropicStream = chat({
   adapter: anthropicText('claude-sonnet-4-6'),
   messages,
-  maxTokens: 16000,
   modelOptions: {
+    max_tokens: 16000,
     thinking: {
       type: 'enabled',
-      budget_tokens: 8000, // must be >= 1024 and < maxTokens
+      budget_tokens: 8000, // must be >= 1024 and < max_tokens
     },
   },
 })
@@ -171,8 +178,8 @@ const anthropicStream = chat({
 const adaptiveStream = chat({
   adapter: anthropicText('claude-sonnet-4-6'),
   messages,
-  maxTokens: 16000,
   modelOptions: {
+    max_tokens: 16000,
     thinking: {
       type: 'adaptive',
     },
@@ -224,7 +231,61 @@ const custom = myOpenai('ft:gpt-5.2:my-org:custom-model:abc123')
 At runtime, `extendAdapter` simply passes through to the original factory.
 The `_customModels` parameter is only used for type inference.
 
-### 5. Capability Flag: `supportsCombinedToolsAndSchema`
+### 5. Configuring Sampling
+
+Sampling controls (`temperature`, token limits, nucleus sampling) are passed
+inside `modelOptions` using each provider's **native** key. They are not
+top-level fields on `chat()`/`ai()`/`generate()`.
+
+```typescript
+// OpenAI — native keys
+chat({
+  adapter: openaiText('gpt-5.2'),
+  messages,
+  modelOptions: { temperature: 0.7, top_p: 0.9, max_output_tokens: 1000 },
+})
+
+// Anthropic
+chat({
+  adapter: anthropicText('claude-sonnet-4-6'),
+  messages,
+  modelOptions: { temperature: 0.7, top_p: 0.9, max_tokens: 1000 },
+})
+
+// Gemini — camelCase
+chat({
+  adapter: geminiText('gemini-2.5-pro'),
+  messages,
+  modelOptions: { temperature: 0.7, topP: 0.9, maxOutputTokens: 1000 },
+})
+
+// Ollama — NESTED under modelOptions.options
+chat({
+  adapter: ollamaText('llama3.3'),
+  messages,
+  modelOptions: {
+    options: { temperature: 0.7, top_p: 0.9, num_predict: 1000 },
+  },
+})
+```
+
+Per-provider sampling keys (all live inside `modelOptions`):
+
+| Provider          | Temperature   | Nucleus | Max output tokens                   |
+| ----------------- | ------------- | ------- | ----------------------------------- |
+| OpenAI            | `temperature` | `top_p` | `max_output_tokens`                 |
+| Anthropic         | `temperature` | `top_p` | `max_tokens`                        |
+| Gemini            | `temperature` | `topP`  | `maxOutputTokens`                   |
+| Grok (xAI)        | `temperature` | `top_p` | `max_tokens`                        |
+| Groq              | `temperature` | `top_p` | `max_completion_tokens`             |
+| OpenRouter (chat) | `temperature` | `topP`  | `maxCompletionTokens`               |
+| Ollama            | `temperature` | `top_p` | `num_predict` (nested in `options`) |
+
+`temperature` is the one key every provider names identically; token limits and
+some sampling options use provider-native names. Ollama nests all sampling under
+`modelOptions.options`.
+
+### 6. Capability Flag: `supportsCombinedToolsAndSchema`
 
 Adapters can declare an optional capability method:
 

package/skills/ai-core/adapter-configuration/references/anthropic-adapter.md

@@ -39,12 +39,15 @@ Note: Model IDs use the format `claude-opus-4-6`, `claude-sonnet-4-6`, etc.
 chat({
   adapter: anthropicText('claude-sonnet-4-6'),
   messages,
-  maxTokens: 16000,
   modelOptions: {
+    // Sampling
+    temperature: 0.7,
+    top_p: 0.9, // cannot be combined with temperature
+    max_tokens: 16000,
     // Extended thinking (budget-based)
     thinking: {
       type: 'enabled',
-      budget_tokens: 8000, // must be >= 1024 and < maxTokens
+      budget_tokens: 8000, // must be >= 1024 and < max_tokens
     },
     // Adaptive thinking (claude-sonnet-4-6, claude-opus-4-6+)
     thinking: {
@@ -89,7 +92,7 @@ ANTHROPIC_API_KEY
 
 ## Gotchas
 
-- `thinking.budget_tokens` must be >= 1024 AND less than `maxTokens`.
+- `thinking.budget_tokens` must be >= 1024 AND less than `modelOptions.max_tokens`.
   Failing either check throws a validation error.
 - Cannot set both `top_p` and `temperature` at the same time (throws error).
 - `claude-3-5-haiku` and `claude-3-haiku` do NOT support extended thinking.

package/skills/ai-core/adapter-configuration/references/gemini-adapter.md

@@ -72,6 +72,9 @@ chat({
     // Response modalities
     responseModalities: ['TEXT'],
     // Sampling
+    temperature: 0.7,
+    topP: 0.9,
+    maxOutputTokens: 1000,
     topK: 40,
     seed: 42,
     presencePenalty: 0.5,

package/skills/ai-core/adapter-configuration/references/ollama-adapter.md

@@ -40,6 +40,9 @@ Models must be pulled first: `ollama pull llama3.3`
 
 Ollama models use a generic options type. Provider options vary by the
 underlying model. The adapter passes options through to the Ollama API.
+Sampling options are **nested** under `modelOptions.options` (this matches
+Ollama's own request shape) — `temperature`, `top_p`, and `num_predict`
+(max output tokens) all live there.
 
 ```typescript
 import { chat } from '@tanstack/ai'
@@ -48,7 +51,13 @@ import { ollamaText } from '@tanstack/ai-ollama'
 const stream = chat({
   adapter: ollamaText('llama3.3'),
   messages,
-  temperature: 0.7,
+  modelOptions: {
+    options: {
+      temperature: 0.7,
+      top_p: 0.9,
+      num_predict: 1000, // max output tokens
+    },
+  },
   // Ollama-specific options are limited compared to cloud providers
 })
 ```

package/skills/ai-core/adapter-configuration/references/openai-adapter.md

@@ -44,6 +44,10 @@ chat({
   adapter: openaiText('gpt-5.4'),
   messages,
   modelOptions: {
+    // Sampling
+    temperature: 0.7,
+    top_p: 0.9,
+    max_output_tokens: 1000,
     // Reasoning (effort levels: none, minimal, low, medium, high)
     reasoning: {
       effort: 'high',

package/skills/ai-core/chat-experience/SKILL.md

@@ -137,8 +137,10 @@ import { anthropicText } from '@tanstack/ai-anthropic'
 const stream = chat({
   adapter: anthropicText('claude-sonnet-4-5'),
   messages,
-  temperature: 0.7,
-  maxTokens: 2000,
+  modelOptions: {
+    temperature: 0.7,
+    max_tokens: 2000, // Anthropic-native key
+  },
   systemPrompts: ['You are a helpful assistant.'],
   abortController,
 })
@@ -377,17 +379,32 @@ chat({ adapter: openaiText('gpt-5.2'), messages })
 
 The model is passed to the adapter factory, not to `chat()`.
 
-### f. HIGH: Nesting temperature/maxTokens in options object
+### f. HIGH: Passing sampling options at the root of chat()
+
+Sampling options (`temperature`, token limits, `top_p`/`topP`) are **not**
+top-level fields on `chat()`. They live inside `modelOptions` using the
+provider's native key.
 
 ```typescript
-// WRONG
+// WRONG — temperature/maxTokens are not root options
+chat({ adapter, messages, temperature: 0.7, maxTokens: 1000 })
+
+// WRONG — there is no `options` field either
 chat({ adapter, messages, options: { temperature: 0.7, maxTokens: 1000 } })
 
-// CORRECT
-chat({ adapter, messages, temperature: 0.7, maxTokens: 1000 })
+// CORRECT — inside modelOptions, provider-native keys (OpenAI shown)
+chat({
+  adapter,
+  messages,
+  modelOptions: { temperature: 0.7, max_output_tokens: 1000 },
+})
 ```
 
-All parameters are top-level on the `chat()` options object.
+`temperature` is universal across providers; token limits use provider-native
+keys (`max_output_tokens` for OpenAI, `max_tokens` for Anthropic/Grok,
+`maxOutputTokens` for Gemini, `max_completion_tokens` for Groq,
+`maxCompletionTokens` for OpenRouter, and `num_predict` nested under
+`modelOptions.options` for Ollama). See ai-core/adapter-configuration/SKILL.md.
 
 ### g. HIGH: Using providerOptions instead of modelOptions
 

package/skills/ai-core/middleware/SKILL.md

@@ -68,6 +68,13 @@ Every hook receives a `ChatMiddlewareContext` as its first argument, which provi
 Terminal hooks (`onFinish`, `onAbort`, `onError`) are **mutually exclusive** -- exactly
 one fires per `chat()` invocation.
 
+> **Sampling in `onConfig`:** `temperature`, `topP`, and `maxTokens` are **not**
+> first-class fields on `ChatMiddlewareConfig`. To adjust sampling from
+> middleware, return a partial that mutates `config.modelOptions` using the
+> provider's native key (e.g. OpenAI `temperature` / `max_output_tokens`,
+> Anthropic `max_tokens`, Ollama nested `options.num_predict`). Returning a
+> top-level `temperature`/`maxTokens` has no effect.
+
 ### Phase values
 
 `ctx.phase` is one of:
@@ -304,6 +311,10 @@ const configTransform: ChatMiddleware = {
     if (ctx.phase === 'init') {
       return {
         systemPrompts: [...config.systemPrompts, 'Always respond in JSON.'],
+        // Sampling options are NOT first-class config fields — mutate them
+        // through `config.modelOptions` using the provider's native key.
+        // (e.g. OpenAI `temperature` / `max_output_tokens`.)
+        modelOptions: { ...config.modelOptions, temperature: 0.2 },
       }
     }
   },

package/src/activities/chat/index.ts

@@ -208,12 +208,6 @@ export interface TextActivityOptions<
         | ProviderTool<string, TAdapter['~types']['toolCapabilities'][number]>
       >
     | undefined
-  /** Controls the randomness of the output. Higher values make output more random. Range: [0.0, 2.0] */
-  temperature?: TextOptions['temperature']
-  /** Nucleus sampling parameter. The model considers tokens with topP probability mass. */
-  topP?: TextOptions['topP']
-  /** The maximum number of tokens to generate in the response. */
-  maxTokens?: TextOptions['maxTokens']
   /** Additional metadata to attach to the request. */
   metadata?: TextOptions['metadata']
   /** Model-specific provider options (type comes from adapter) */
@@ -844,13 +838,10 @@ class TextEngine<
 
   private beforeRun(): void {
     this.streamStartTime = Date.now()
-    const { tools, temperature, topP, maxTokens, metadata } = this.params
+    const { tools, metadata } = this.params
 
     // Gather flattened options into an object for context
     const options: Record<string, unknown> = {}
-    if (temperature !== undefined) options.temperature = temperature
-    if (topP !== undefined) options.topP = topP
-    if (maxTokens !== undefined) options.maxTokens = maxTokens
     if (metadata !== undefined) options.metadata = metadata
 
     this.eventOptions = Object.keys(options).length > 0 ? options : undefined
@@ -897,7 +888,7 @@ class TextEngine<
   }
 
   private async *streamModelResponse(): AsyncGenerator<StreamChunk> {
-    const { temperature, topP, maxTokens, metadata, modelOptions } = this.params
+    const { metadata, modelOptions } = this.params
     const tools = this.tools
 
     // Convert tool schemas to JSON Schema before passing to adapter
@@ -941,9 +932,6 @@ class TextEngine<
       model: this.params.model,
       messages: this.messages,
       tools: toolsWithJsonSchemas,
-      temperature,
-      topP,
-      maxTokens,
       metadata,
       request: this.effectiveRequest,
       modelOptions,
@@ -1869,9 +1857,6 @@ class TextEngine<
       chatOptions: {
         model: this.params.model,
         messages: this.messages,
-        temperature: postOnConfig.temperature,
-        topP: postOnConfig.topP,
-        maxTokens: postOnConfig.maxTokens,
         metadata: postOnConfig.metadata,
         modelOptions: postOnConfig.modelOptions,
         systemPrompts: postOnConfig.systemPrompts,
@@ -2351,9 +2336,6 @@ class TextEngine<
       messages: this.messages,
       systemPrompts: [...this.systemPrompts],
       tools: [...this.tools],
-      temperature: this.params.temperature,
-      topP: this.params.topP,
-      maxTokens: this.params.maxTokens,
       metadata: this.params.metadata,
       modelOptions: this.params.modelOptions,
     }
@@ -2365,9 +2347,6 @@ class TextEngine<
     this.tools = config.tools
     this.params = {
       ...this.params,
-      temperature: config.temperature,
-      topP: config.topP,
-      maxTokens: config.maxTokens,
       metadata: config.metadata,
       modelOptions: config.modelOptions,
     }

package/src/activities/chat/middleware/types.ts

@@ -90,7 +90,7 @@ export interface ChatMiddlewareContext<TContext = unknown> {
   systemPrompts: Array<SystemPrompt>
   /** Names of configured tools, if any */
   toolNames?: Array<string>
-  /** Flattened generation options (temperature, topP, maxTokens, metadata) */
+  /** Flattened generation options (metadata) */
   options?: Record<string, unknown> | undefined
   /** Provider-specific model options */
   modelOptions?: Record<string, unknown> | undefined
@@ -130,9 +130,6 @@ export interface ChatMiddlewareConfig {
   messages: Array<ModelMessage>
   systemPrompts: Array<SystemPrompt>
   tools: Array<Tool>
-  temperature?: number
-  topP?: number
-  maxTokens?: number
   metadata?: Record<string, unknown> | undefined
   modelOptions?: Record<string, unknown> | undefined
 }

package/src/activities/summarize/chat-stream-summarize.ts

@@ -1,5 +1,6 @@
 import { EventType } from '@ag-ui/core'
 import { toRunErrorPayload } from '../error-payload'
+import { MAX_TOKENS_KEYS } from '../../utilities/sampling-keys'
 import { BaseSummarizeAdapter } from './adapter'
 import type {
   StreamChunk,
@@ -23,6 +24,139 @@ export interface ChatStreamCapable {
   chatStream: (options: TextOptions<any>) => AsyncIterable<StreamChunk>
 }
 
+/**
+ * Provider-native max-output-tokens key per summarize-adapter `name`. summarize
+ * is provider-agnostic and forwards `modelOptions` opaquely to the wrapped text
+ * adapter, so `maxLength` must be written under the exact key the underlying
+ * provider reads — no adapter reads a generic `maxTokens`. Ollama is the one
+ * exception: it nests sampling under `options`, so it has no entry here and is
+ * handled as a special nested case in `applyMaxLength`/`applyDefaultTemperature`.
+ *
+ * Keep in sync with each adapter's wire mapping:
+ * - OpenAI (Responses): `max_output_tokens`
+ * - Anthropic / Grok: `max_tokens`
+ * - Groq: `max_completion_tokens`
+ * - Gemini: `maxOutputTokens`
+ * - OpenRouter: `maxCompletionTokens`
+ * - Ollama: nested `options.num_predict` (no entry — see `applyMaxLength`)
+ */
+const MAX_TOKENS_KEY_BY_ADAPTER: Record<string, string> = {
+  openai: 'max_output_tokens',
+  anthropic: 'max_tokens',
+  grok: 'max_tokens',
+  groq: 'max_completion_tokens',
+  gemini: 'maxOutputTokens',
+  openrouter: 'maxCompletionTokens',
+}
+
+/**
+ * Every flat key any supported provider uses to cap output tokens (plus the
+ * generic `maxTokens` spelling no adapter reads). Used to detect a
+ * caller-supplied token limit so the summarize default never overrides an
+ * explicit caller value. Shared with the OTel middleware via
+ * `MAX_TOKENS_KEYS` so the two spelling sets cannot drift.
+ */
+const KNOWN_MAX_TOKENS_KEYS = MAX_TOKENS_KEYS
+
+/**
+ * Whether `applyMaxLength` knows how to place a token limit for this adapter
+ * `name` (either the nested Ollama shape or a flat provider-native key).
+ * Used to surface a warning when `maxLength` would otherwise be silently
+ * dropped for an unrecognised adapter name.
+ */
+function isKnownMaxTokensAdapter(adapterName: string): boolean {
+  return (
+    adapterName === 'ollama' ||
+    MAX_TOKENS_KEY_BY_ADAPTER[adapterName] !== undefined
+  )
+}
+
+/**
+ * Apply the low-temperature summarize default to a working copy of the
+ * caller's `modelOptions`, placed where the wrapped provider actually reads
+ * it (nested under `options` for Ollama, flat otherwise). The caller always
+ * wins: if they already set `temperature` in that location, it is untouched.
+ */
+function applyDefaultTemperature(
+  adapterName: string,
+  temperature: number,
+  modelOptions: Record<string, unknown>,
+): Record<string, unknown> {
+  const merged: Record<string, unknown> = { ...modelOptions }
+
+  if (adapterName === 'ollama') {
+    const existing =
+      merged.options && typeof merged.options === 'object'
+        ? (merged.options as Record<string, unknown>)
+        : undefined
+    if (existing && 'temperature' in existing) return merged
+    merged.options = { temperature, ...existing }
+    return merged
+  }
+
+  if ('temperature' in merged) return merged
+  merged.temperature = temperature
+  return merged
+}
+
+/**
+ * Resolve `maxLength` to the provider-native max-output-tokens key for the
+ * given summarize-adapter `name` (this wrapper's OWN `name`, not the wrapped
+ * text adapter's) and merge it into a working copy of the caller's
+ * `modelOptions`. The caller always wins: if they already set any recognised
+ * token-limit key (flat or, for Ollama, nested `options.num_predict`), the
+ * default is left untouched. Unknown/unrecognised adapter names fall back to
+ * NOT setting a token key (the prompt hint still asks the model to stay under
+ * `maxLength`) rather than writing a dead key no provider reads.
+ *
+ * Caveat (intentional): "caller wins" keys off ANY recognised spelling in
+ * `KNOWN_MAX_TOKENS_KEYS`, but only the adapter's native key is read on the
+ * wire. So a caller who sets a NON-native spelling for this provider — e.g.
+ * `maxTokens`, or Anthropic's `max_tokens` against an OpenAI adapter — suppresses
+ * the summarize default WITHOUT getting their own value applied either: neither
+ * cap reaches the wire. This favours never clobbering a migration leftover over
+ * guaranteeing a cap; the prompt-level hint still asks the model to stay under
+ * `maxLength`. Rename the key to the provider-native spelling to forward it.
+ */
+function applyMaxLength(
+  adapterName: string,
+  maxLength: number,
+  modelOptions: Record<string, unknown>,
+): Record<string, unknown> {
+  const merged: Record<string, unknown> = { ...modelOptions }
+
+  if (adapterName === 'ollama') {
+    // Honor a caller-set limit in either shape: a recognised flat key (e.g.
+    // left over from a migration) or the nested `options.num_predict`.
+    const callerSetFlatLimit = KNOWN_MAX_TOKENS_KEYS.some(
+      (k) => typeof merged[k] === 'number',
+    )
+    const existing =
+      merged.options && typeof merged.options === 'object'
+        ? (merged.options as Record<string, unknown>)
+        : undefined
+    if (
+      callerSetFlatLimit ||
+      (existing && typeof existing.num_predict === 'number')
+    ) {
+      return merged
+    }
+    merged.options = { num_predict: maxLength, ...existing }
+    return merged
+  }
+
+  const key = MAX_TOKENS_KEY_BY_ADAPTER[adapterName]
+  if (key === undefined) return merged
+
+  const callerSetLimit = KNOWN_MAX_TOKENS_KEYS.some(
+    (k) => typeof merged[k] === 'number',
+  )
+  if (callerSetLimit) return merged
+
+  merged[key] = maxLength
+  return merged
+}
+
 /**
  * Extract the per-model `modelOptions` type a text adapter accepts. Used by
  * provider summarize factories so their `modelOptions` IntelliSense matches
@@ -195,13 +329,38 @@ export class ChatStreamSummarizeAdapter<
     options: SummarizationOptions<TProviderOptions>,
     systemPrompt: string,
   ): TextOptions<TProviderOptions> {
+    // Sampling knobs now live in provider-native `modelOptions`. Apply the
+    // low-temperature default where the wrapped provider actually reads it
+    // (nested under `options` for Ollama, flat otherwise) so callers can still
+    // override it. Resolving the placement from this summarize adapter's OWN
+    // `name` keeps the default off the wire correctly per provider — a flat
+    // `temperature` would be silently dropped by Ollama while still showing up
+    // in OTel.
+    let working: Record<string, unknown> = {
+      ...(options.modelOptions as Record<string, unknown> | undefined),
+    }
+    working = applyDefaultTemperature(this.name, 0.3, working)
+    // `maxLength` must reach the wire under the provider-native token key (it
+    // differs per provider, and no adapter reads a generic `maxTokens`).
+    // Resolve it from this summarize adapter's `name` (the constructor arg,
+    // not the wrapped text adapter's name), never overriding a caller-supplied
+    // token limit.
+    if (options.maxLength !== undefined) {
+      if (!isKnownMaxTokensAdapter(this.name)) {
+        options.logger.warn(
+          `summarize: maxLength=${options.maxLength} could not be mapped to a provider token key for adapter name "${this.name}" — it was dropped from modelOptions (the prompt still asks the model to stay under it). Construct ChatStreamSummarizeAdapter with a recognised provider name to forward the cap.`,
+          { provider: this.name },
+        )
+      }
+      working = applyMaxLength(this.name, options.maxLength, working)
+    }
+    const modelOptions = working as TProviderOptions
+
     return {
       model: options.model,
       messages: [{ role: 'user', content: options.text }],
       systemPrompts: [systemPrompt],
-      maxTokens: options.maxLength,
-      temperature: 0.3,
-      modelOptions: options.modelOptions,
+      modelOptions,
       logger: options.logger,
     }
   }

package/src/logger/internal-logger.ts

@@ -104,4 +104,22 @@ export class InternalLogger {
   request(message: string, meta?: Record<string, unknown>): void {
     this.emit('debug', 'request', message, meta)
   }
+
+  /**
+   * Log a non-fatal misconfiguration or recoverable anomaly. Gated by the
+   * `errors` category — on by default (and when `debug` is unspecified), so
+   * silent-drop conditions surface, but still silenced by `debug: false`,
+   * which honors the "disable everything including errors" contract. Routes to
+   * the underlying logger's `warn` level.
+   */
+  warn(message: string, meta?: Record<string, unknown>): void {
+    if (!this.categories.errors) return
+    const prefixed = `⚠️ [tanstack-ai:warn] ⚠️ ${message}`
+    try {
+      this.logger.warn(prefixed, meta)
+    } catch {
+      // User-supplied logger threw; swallow so a broken logger never masks the
+      // condition we were trying to surface.
+    }
+  }
 }

package/src/middlewares/otel.ts

@@ -4,6 +4,10 @@ import {
   context as otelContext,
   trace as otelTrace,
 } from '@opentelemetry/api'
+import {
+  MAX_TOKENS_KEYS,
+  NESTED_MAX_TOKENS_KEY,
+} from '../utilities/sampling-keys'
 import type {
   AttributeValue,
   Exception,
@@ -162,6 +166,19 @@ function messageEventName(role: string): string {
   }
 }
 
+/**
+ * Return the first candidate that is a finite `number`, or `undefined`. Used to
+ * pick a sampling attribute from among the several provider-native spellings.
+ */
+function firstNumber(...candidates: Array<unknown>): number | undefined {
+  for (const candidate of candidates) {
+    if (typeof candidate === 'number' && Number.isFinite(candidate)) {
+      return candidate
+    }
+  }
+  return undefined
+}
+
 function errorMessage(err: unknown): string | undefined {
   if (err instanceof Error) return err.message
   if (typeof err === 'string') return err
@@ -333,12 +350,37 @@ export function otelMiddleware(options: OtelMiddlewareOptions): ChatMiddleware {
           'gen_ai.request.model': ctx.model,
           'tanstack.ai.iteration': ctx.iteration,
         }
-        if (config.temperature !== undefined)
-          baseAttrs['gen_ai.request.temperature'] = config.temperature
-        if (config.topP !== undefined)
-          baseAttrs['gen_ai.request.top_p'] = config.topP
-        if (config.maxTokens !== undefined)
-          baseAttrs['gen_ai.request.max_tokens'] = config.maxTokens
+        // Sampling options now live in provider-native `modelOptions`, and
+        // providers spell them differently (e.g. `max_output_tokens`,
+        // `max_completion_tokens`, `maxOutputTokens`, `num_predict`). Read the
+        // first numeric value among the known spellings — including Ollama's
+        // nested `options` — so gen_ai attributes populate across providers.
+        const sampling = config.modelOptions ?? {}
+        const nestedOptions =
+          sampling['options'] && typeof sampling['options'] === 'object'
+            ? (sampling['options'] as Record<string, unknown>)
+            : undefined
+        const samplingTemperature = firstNumber(
+          sampling['temperature'],
+          nestedOptions?.['temperature'],
+        )
+        const samplingTopP = firstNumber(
+          sampling['top_p'],
+          sampling['topP'],
+          nestedOptions?.['top_p'],
+        )
+        // Spellings come from the shared `MAX_TOKENS_KEYS` table so this stays
+        // in lockstep with the summarize wrapper's caller-limit detection.
+        const samplingMaxTokens = firstNumber(
+          ...MAX_TOKENS_KEYS.map((k) => sampling[k]),
+          nestedOptions?.[NESTED_MAX_TOKENS_KEY],
+        )
+        if (samplingTemperature !== undefined)
+          baseAttrs['gen_ai.request.temperature'] = samplingTemperature
+        if (samplingTopP !== undefined)
+          baseAttrs['gen_ai.request.top_p'] = samplingTopP
+        if (samplingMaxTokens !== undefined)
+          baseAttrs['gen_ai.request.max_tokens'] = samplingMaxTokens
 
         const baseOptions: SpanOptions = {
           kind: SpanKind.CLIENT,