@tanstack/ai 0.52.3 → 0.54.0

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

@@ -23,34 +23,41 @@ import { grokImage } from '@tanstack/ai-grok'
 
 ## Key Chat Models
 
-| Model                         | Context Window | Notes                        |
-| ----------------------------- | -------------- | ---------------------------- |
-| `grok-4-1-fast-reasoning`     | 2M             | Latest, fast reasoning       |
-| `grok-4-1-fast-non-reasoning` | 2M             | Latest, no reasoning         |
-| `grok-code-fast-1`            | 256K           | Code-specialized, reasoning  |
-| `grok-4`                      | 256K           | Full reasoning, tool calling |
-| `grok-4-fast-reasoning`       | 2M             | Fast reasoning variant       |
-| `grok-3`                      | 131K           | Previous gen, no reasoning   |
-| `grok-3-mini`                 | 131K           | Budget reasoning             |
-| `grok-2-vision-1212`          | 32K            | Vision input                 |
-
-Image model: `grok-2-image-1212`
+| Model            | Context Window | Notes                                                    |
+| ---------------- | -------------- | -------------------------------------------------------- |
+| `grok-4.6`       | 500K           | Latest; reasoning, tools, structured output; document in |
+| `grok-4.5`       | 500K           | Reasoning, tools, structured output; document in         |
+| `grok-4.3`       | 1M             | Reasoning, tools, structured output; text + image in     |
+| `grok-build-0.1` | 256K           | Code-specialized; `reasoning` option is not accepted     |
+
+`GROK_CHAT_MODELS` is exactly these four ids. Image models
+(`GROK_IMAGE_MODELS`): `grok-2-image-1212`, `grok-imagine-image`,
+`grok-imagine-image-2.0`, `grok-imagine-image-quality`.
 
 ## Provider-Specific modelOptions
 
-Grok uses an OpenAI-compatible API. Options are straightforward:
+Grok speaks the OpenAI **Responses** API (the adapter uses the OpenAI SDK
+against `https://api.x.ai/v1`), so option names follow that API:
 
 ```typescript
+import { chat } from '@tanstack/ai'
+import { grokText } from '@tanstack/ai-grok'
+
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 chat({
-  adapter: grokText('grok-4'),
+  adapter: grokText('grok-4.6'),
   messages,
   modelOptions: {
+    // Sampling (Responses API names)
     temperature: 0.7,
-    max_tokens: 4096,
     top_p: 0.9,
-    frequency_penalty: 0.5,
-    presence_penalty: 0.5,
-    stop: ['\n\n'],
+    max_output_tokens: 4096,
+    // Reasoning (reasoning-capable models)
+    reasoning: { effort: 'high' }, // 'none' | 'low' | 'medium' | 'high'
+    // Response storage (adapter default: false)
+    store: false,
+    // End-user id for abuse monitoring
     user: 'user-123',
   },
 })
@@ -68,10 +75,11 @@ The adapter uses the OpenAI SDK with xAI's base URL (`https://api.x.ai/v1`).
 ## Gotchas
 
 - Uses the OpenAI SDK under the hood with a custom `baseURL`.
-- `grok-4-1-fast-non-reasoning` and `grok-4-fast-non-reasoning` explicitly
-  do NOT support reasoning. Other grok-4+ models do.
-- `grok-2-vision-1212` is the only model with image input support in the
-  older generation.
-- The grok-4-1 fast models have a massive 2M context window.
-- Provider options are simpler than OpenAI's (no Responses API features,
-  no structured outputs config, no metadata).
+- All four chat models support reasoning; `grok-build-0.1` is the exception
+  in that it rejects the `reasoning` option (`GrokBuildProviderOptions`).
+- `grok-4.5` / `grok-4.6` accept `text`, `image`, and `document` input;
+  `grok-4.3` / `grok-build-0.1` accept `text` and `image`.
+- Provider options are a subset of OpenAI's Responses options:
+  `temperature`, `top_p`, `max_output_tokens`, `reasoning`, `store`,
+  `include`, `user`. There is no `max_tokens`, `frequency_penalty`,
+  `presence_penalty`, `stop`, or `metadata`.

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

@@ -38,6 +38,11 @@ Guard models: `meta-llama/llama-guard-4-12b`, `meta-llama/llama-prompt-guard-2-8
 ## Provider-Specific modelOptions
 
 ```typescript
+import { chat } from '@tanstack/ai'
+import { groqText } from '@tanstack/ai-groq'
+
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 chat({
   adapter: groqText('llama-3.3-70b-versatile'),
   messages,
@@ -49,7 +54,7 @@ chat({
     // Response format
     response_format: {
       type: 'json_schema',
-      json_schema: {/* ... */},
+      json_schema: { name: 'answer', schema: {/* JSON Schema */} },
     },
     // Sampling
     temperature: 0.7,
@@ -67,7 +72,7 @@ chat({
     // Citations
     citation_options: 'enabled',
     // Documents for context
-    documents: [{ text: '...' }],
+    documents: [{ source: { type: 'text', text: '...' } }],
     // Search settings (for web search tool)
     search_settings: {/* SearchSettings */},
     // Service tier

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

@@ -24,15 +24,20 @@ import { ollamaText } from '@tanstack/ai-ollama'
 Ollama runs models locally. The adapter supports a large catalog of models.
 Key families include:
 
-| Model Family | Example Names                    | Notes                   |
-| ------------ | -------------------------------- | ----------------------- |
-| Llama 4      | `llama4`, `llama4:scout`         | Latest Meta models      |
-| Llama 3.3    | `llama3.3`, `llama3.3:70b`       | Strong general purpose  |
-| Qwen 3       | `qwen3`, `qwen3:32b`             | Reasoning capable       |
-| DeepSeek R1  | `deepseek-r1`, `deepseek-r1:70b` | Reasoning focused       |
-| Gemma 3      | `gemma3`, `gemma3:27b`           | Google's open model     |
-| Phi 4        | `phi4`, `phi4:14b`               | Microsoft's small model |
-| Mistral      | `mistral`, `mistral-large`       | Mistral AI models       |
+| Model Family | Example Names                            | Notes                   |
+| ------------ | ---------------------------------------- | ----------------------- |
+| Llama 4      | `llama4:latest`, `llama4:16x17b`         | Latest Meta models      |
+| Llama 3.3    | `llama3.3:latest`, `llama3.3:70b`        | Strong general purpose  |
+| Qwen 3       | `qwen3:latest`, `qwen3:32b`              | Reasoning capable       |
+| DeepSeek R1  | `deepseek-r1:latest`, `deepseek-r1:70b`  | Reasoning focused       |
+| Gemma 3      | `gemma3:latest`, `gemma3:27b`            | Google's open model     |
+| Phi 4        | `phi4:latest`, `phi4:14b`                | Microsoft's small model |
+| Mistral      | `mistral:latest`, `mistral-large:latest` | Mistral AI models       |
+
+Typed ids are always `family:tag` (`OLLAMA_TEXT_MODELS`). `ollamaText()`
+accepts any string, but a bare `llama3.3` falls outside the typed catalog and
+`modelOptions` degrades to the raw Ollama `ChatRequest` (which then demands a
+`model` field). Use `llama3.3:latest`.
 
 Models must be pulled first: `ollama pull llama3.3`
 
@@ -48,8 +53,10 @@ Ollama's own request shape) — `temperature`, `top_p`, and `num_predict`
 import { chat } from '@tanstack/ai'
 import { ollamaText } from '@tanstack/ai-ollama'
 
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 const stream = chat({
-  adapter: ollamaText('llama3.3'),
+  adapter: ollamaText('llama3.3:latest'),
   messages,
   modelOptions: {
     options: {
@@ -64,9 +71,15 @@ const stream = chat({
 
 ## Configuration
 
+`ollamaText(model)` takes no config — it reads `OLLAMA_HOST`. To point at
+another server (or pass headers / `baseURL` for a gateway), use
+`createOllamaChat(model, hostOrConfig)`:
+
 ```typescript
-// With explicit host
-const adapter = ollamaText('llama3.3', {
+import { createOllamaChat } from '@tanstack/ai-ollama'
+
+// With explicit host (ollamaText() reads OLLAMA_HOST instead)
+const adapter = createOllamaChat('llama3.3:latest', {
   host: 'http://my-server:11434',
 })
 ```

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

@@ -28,20 +28,30 @@ import { openaiSpeech } from '@tanstack/ai-openai'
 
 ## Key Chat Models
 
-| Model                 | Context Window | Max Output | Notes                                  |
-| --------------------- | -------------- | ---------- | -------------------------------------- |
-| `gpt-5.4`             | 400K           | 128K       | Flagship, reasoning, image input       |
-| `gpt-5.4-pro`         | 400K           | 128K       | Higher reasoning, no structured output |
-| `gpt-5.4-chat-latest` | 128K           | 16K        | Chat-optimized variant                 |
-| `gpt-5.1`             | 400K           | 128K       | Previous flagship, image I/O           |
-| `gpt-5`               | 400K           | 128K       | Previous gen flagship                  |
-| `gpt-5-mini`          | 400K           | 128K       | Cost-efficient                         |
+| Model          | Context Window | Max Output | Notes                                          |
+| -------------- | -------------- | ---------- | ---------------------------------------------- |
+| `gpt-6-astra`  | 1M             | 128K       | Newest; reasoning, tools, image input          |
+| `gpt-5.6`      | 1M             | 128K       | Reasoning, tools, image input                  |
+| `gpt-5.5`      | 1M             | 128K       | Flagship used in examples; text/image/document |
+| `gpt-5.5-pro`  | 1M             | 128K       | Higher reasoning tier                          |
+| `gpt-5.4-mini` | 400K           | 128K       | Cost-efficient (no bare `gpt-5.4` chat id)     |
+| `gpt-5.2`      | 400K           | 128K       | Previous flagship; text/image/document         |
+| `gpt-5-mini`   | 400K           | 128K       | Budget                                         |
+
+`OPENAI_CHAT_MODELS` is the full list (also `gpt-6-astra-pro`, the
+`gpt-5.6-luna/sol/terra` family, `gpt-5.4-nano`, `gpt-5.2-pro`,
+`gpt-5.1`, `gpt-5`, the `o3`/`o4-mini` reasoning models, and `gpt-4.1`/`gpt-4o`).
 
 ## Provider-Specific modelOptions
 
 ```typescript
+import { chat } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 chat({
-  adapter: openaiText('gpt-5.4'),
+  adapter: openaiText('gpt-5.5'),
   messages,
   modelOptions: {
     // Sampling

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

@@ -38,24 +38,29 @@ the format `provider/model-name`:
 OpenRouter has unique routing and provider selection options:
 
 ```typescript
+import { chat } from '@tanstack/ai'
+import { openRouterText } from '@tanstack/ai-openrouter'
+
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
+// Options are narrowed per model from OpenRouter's published metadata —
+// e.g. 'anthropic/claude-sonnet-4' only accepts temperature/topP/
+// maxCompletionTokens/stop/toolChoice/reasoning. This model takes the full set.
 chat({
-  adapter: openRouterText('anthropic/claude-sonnet-4'),
+  adapter: openRouterText('deepseek/deepseek-v4-pro'),
   messages,
   modelOptions: {
     // Reasoning
     reasoning: {
-      effort: 'high', // 'none' | 'minimal' | 'low' | 'medium' | 'high'
-      max_tokens: 4096,
-      exclude: false,
+      effort: 'high', // 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+      summary: 'auto',
+      // enabled: false — explicit opt-out (normalized to effort: 'none')
     },
     // Sampling
     temperature: 0.7,
     topP: 0.9,
-    topK: 40,
     frequencyPenalty: 0.5,
     presencePenalty: 0.5,
-    repetitionPenalty: 1.1,
-    minP: 0.05,
     seed: 42,
     // Token limits
     maxCompletionTokens: 8192,
@@ -66,12 +71,11 @@ chat({
     parallelToolCalls: true,
     // Response format
     responseFormat: { type: 'json_object' },
-    // Web search
-    webSearchOptions: {
-      search_context_size: 'medium', // 'low' | 'medium' | 'high'
-    },
-    // Verbosity
-    verbosity: 'medium',
+    // Routing (available on every model)
+    variant: 'nitro', // 'free' | 'nitro' | 'online' | 'exacto' | 'extended' | 'thinking'
+    models: ['deepseek/deepseek-v4-flash'], // fallbacks, tried in order
+    provider: { order: ['DeepSeek'], allowFallbacks: true },
+    plugins: [{ id: 'web' }], // web search
     // Logprobs
     logprobs: true,
     topLogprobs: 5,
@@ -89,11 +93,20 @@ OPENROUTER_API_KEY
 
 - Model IDs are `provider/model-name` format (e.g., `openai/gpt-5.2`).
 - OpenRouter has unique features not found in direct provider adapters:
-  - `variant` option: `'free'`, `'nitro'`, `'online'`, `'thinking'`, etc.
-  - `provider` routing preferences (order, fallbacks, data collection policies)
-  - `transforms: ['middle-out']` for context compression
-  - `prediction` for latency reduction
-  - `plugins: [{ id: 'web' }]` for web search
-- Uses `camelCase` for option names (e.g., `topP`, `frequencyPenalty`),
-  unlike OpenAI's `snake_case`.
-- `route: 'fallback'` with `models` array tries models in order.
+  - `variant` option: `'free'`, `'nitro'`, `'online'`, `'exacto'`,
+    `'extended'`, `'thinking'`
+  - `provider` routing preferences (`order`, `allowFallbacks`, data
+    collection policies — camelCase keys)
+  - `models` array of fallback ids, tried in order
+  - `plugins: [{ id: 'web' }]` for web search (also `file-parser`,
+    `response-healing`, `moderation`, `auto-router`)
+- Uses `camelCase` for option names (e.g., `topP`, `frequencyPenalty`,
+  `maxCompletionTokens`), unlike OpenAI's `snake_case`.
+- `reasoning` is `{ effort, summary, enabled }` — there is no
+  `max_tokens`/`exclude` inside it; `enabled: false` is normalized to
+  `effort: 'none'`.
+- Per-model options are narrowed from OpenRouter's published metadata, so
+  keys like `frequencyPenalty`, `seed`, `logprobs`, or `responseFormat` are
+  only accepted on models that support them. `topK`, `minP`,
+  `repetitionPenalty`, `webSearchOptions`, `verbosity`, `transforms`, and
+  `route` are not exposed by the adapter.

package/skills/ai-core/ag-ui-protocol/SKILL.md

@@ -29,7 +29,7 @@ import { openaiText } from '@tanstack/ai-openai'
 export async function POST(request: Request) {
   const { messages } = await request.json()
   const stream = chat({
-    adapter: openaiText('gpt-5.2'),
+    adapter: openaiText('gpt-5.6'),
     messages,
   })
   return toServerSentEventsResponse(stream)
@@ -49,7 +49,7 @@ import {
   mergeAgentTools,
   toServerSentEventsResponse,
 } from '@tanstack/ai'
-import { openaiText } from '@tanstack/ai-openai/adapters'
+import { openaiText } from '@tanstack/ai-openai'
 import { serverTools } from './tools'
 
 export async function POST(req: Request) {
@@ -64,7 +64,7 @@ export async function POST(req: Request) {
   }
 
   const stream = chat({
-    adapter: openaiText('gpt-4o'),
+    adapter: openaiText('gpt-5.6'),
     messages: params.messages,
     tools: mergeAgentTools(serverTools, params.tools),
   })
@@ -87,7 +87,7 @@ export async function POST(req: Request) {
 
 **Wire format:** Each event is `data: <JSON>\n\n`. Stream ends with `data: [DONE]\n\n`.
 
-```typescript
+```typescript group=sse-response
 import {
   chat,
   toServerSentEventsStream,
@@ -95,10 +95,12 @@ import {
 } from '@tanstack/ai'
 import { openaiText } from '@tanstack/ai-openai'
 
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 // Option A: Get a ReadableStream (manual Response construction)
 const abortController = new AbortController()
 const stream = chat({
-  adapter: openaiText('gpt-5.2'),
+  adapter: openaiText('gpt-5.6'),
   messages,
   abortController,
 })
@@ -127,7 +129,7 @@ const response2 = toServerSentEventsResponse(stream, { abortController })
 
 Custom headers merge on top (user headers override defaults):
 
-```typescript
+```typescript group=sse-response
 toServerSentEventsResponse(stream, {
   headers: {
     'X-Accel-Buffering': 'no', // Disable nginx buffering
@@ -149,10 +151,12 @@ aborted, the error event is suppressed and the stream closes silently.
 import { chat, toHttpStream, toHttpResponse } from '@tanstack/ai'
 import { openaiText } from '@tanstack/ai-openai'
 
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 // Option A: Get a ReadableStream
 const abortController = new AbortController()
 const stream = chat({
-  adapter: openaiText('gpt-5.2'),
+  adapter: openaiText('gpt-5.6'),
   messages,
   abortController,
 })
@@ -199,7 +203,7 @@ All events extend `BaseAGUIEvent` which carries `type`, `timestamp`, optional
 | `STATE_DELTA`          | Incremental state update. Carries `delta: Record<string, unknown>`.                                                         |
 | `CUSTOM`               | Extension point. Carries `name` (string) and optional `value` (unknown).                                                    |
 | `RUN_FINISHED`         | Stream complete. Carries `runId` and `finishReason` (`'stop'` / `'length'` / `'content_filter'` / `'tool_calls'` / `null`). |
-| `RUN_ERROR`            | Error during stream. Carries optional `runId` and `error: { message, code? }`.                                              |
+| `RUN_ERROR`            | Error during stream. Carries `message`, optional `code` and `runId`; a nested `error: { message, code? }` copy is kept too. |
 
 **Typical event sequence for a text-only response:**
 
@@ -235,8 +239,10 @@ no helper, no cast:
 import { chat } from '@tanstack/ai'
 import { openaiText } from '@tanstack/ai-openai'
 
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 const stream = chat({
-  adapter: openaiText('gpt-5.2'),
+  adapter: openaiText('gpt-5.6'),
   messages,
 })
 
@@ -284,7 +290,7 @@ causing events to arrive in batches instead of streaming token-by-token.
 
 Fix: Set proxy-bypass headers on the response.
 
-```typescript
+```typescript group=sse-response
 toServerSentEventsResponse(stream, {
   headers: {
     'X-Accel-Buffering': 'no', // nginx