@tanstack/ai 0.53.0 → 0.55.0

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

@@ -45,16 +45,20 @@ Create an adapter and use it with `chat()`:
 import { chat, toServerSentEventsResponse } from '@tanstack/ai'
 import { openaiText } from '@tanstack/ai-openai'
 
-const stream = chat({
-  adapter: openaiText('gpt-5.2'),
-  messages,
-  modelOptions: {
-    temperature: 0.7,
-    max_output_tokens: 1000,
-  },
-})
+export async function POST(request: Request) {
+  const { messages } = await request.json()
+
+  const stream = chat({
+    adapter: openaiText('gpt-5.2'),
+    messages,
+    modelOptions: {
+      temperature: 0.7,
+      max_output_tokens: 1000,
+    },
+  })
 
-return toServerSentEventsResponse(stream)
+  return toServerSentEventsResponse(stream)
+}
 ```
 
 The adapter factory function takes the model name as a string literal and an
@@ -95,7 +99,7 @@ The text adapter is the primary one for chat/completions:
 
 ```typescript
 // Each factory takes model as first arg, optional config as second
-import { openaiText } from '@tanstack/ai-openai'
+import { openaiText, createOpenaiChat } from '@tanstack/ai-openai'
 import { anthropicText } from '@tanstack/ai-anthropic'
 import { geminiText } from '@tanstack/ai-gemini'
 import { grokText } from '@tanstack/ai-grok'
@@ -109,24 +113,23 @@ import { byteplusText } from '@tanstack/ai-byteplus'
 const adapter = openaiText('gpt-5.2')
 const adapter2 = anthropicText('claude-sonnet-4-6')
 const adapter3 = geminiText('gemini-2.5-pro')
-const adapter4 = grokText('grok-4')
+const adapter4 = grokText('grok-4.6')
 const adapter5 = groqText('llama-3.3-70b-versatile')
 const adapter6 = openRouterText('anthropic/claude-sonnet-4')
-const adapter7 = ollamaText('llama3.3')
+const adapter7 = ollamaText('llama3.3:latest')
 const adapter8 = bedrockText('us.anthropic.claude-3-7-sonnet-20250219-v1:0')
 const adapter9 = byteplusText('seed-2-0-lite-260428')
 
-// Optional: pass explicit API key
-const adapterWithKey = openaiText('gpt-5.2', {
-  apiKey: 'sk-...',
-})
+// Optional: pass an explicit API key via the create* sibling
+// (the plain factory reads it from the environment)
+const adapterWithKey = createOpenaiChat('gpt-5.2', 'sk-...')
 ```
 
 `@tanstack/ai-bedrock` (Amazon Bedrock) branches on `config.api`:
 
 - `bedrockText(model)` or `bedrockText(model, { api: 'converse' })` (the default) — Bedrock's native Converse API via `@aws-sdk/client-bedrock-runtime` (adapter name `bedrock-converse`). Reaches the broad catalog: Claude, Nova, Llama, Mistral, DeepSeek, and more.
 - `bedrockText(model, { api: 'chat' })` — OpenAI-compatible Chat Completions endpoint (adapter name `bedrock`). Open-weight models only (gpt-oss, DeepSeek V3.x, Gemma, Qwen, etc.). Does NOT reach Claude, Nova, or Llama.
-- `bedrockText(model, { api: 'responses' })` — OpenAI-compatible Responses API, mantle-only (adapter name `bedrock-responses`). Currently gpt-oss family.
+- `bedrockText(model, { api: 'responses' })` — OpenAI-compatible Responses API, mantle-only (adapter name `bedrock-responses`). Currently gpt-oss and Gemma 4.
 
 Use `createBedrockText(model, apiKey, config?)` to pass the key explicitly. Auth resolves from `BEDROCK_API_KEY` / `AWS_BEARER_TOKEN_BEDROCK`, or SigV4 via the standard AWS credential chain (no extra packages needed — handled by `@aws-sdk/client-bedrock-runtime`).
 
@@ -137,26 +140,32 @@ input or configuration:
 
 ```typescript
 import { chat, toServerSentEventsResponse } from '@tanstack/ai'
-import type { TextAdapter } from '@tanstack/ai/adapters'
+import type { ModelMessage } from '@tanstack/ai'
 import { openaiText } from '@tanstack/ai-openai'
 import { anthropicText } from '@tanstack/ai-anthropic'
 import { geminiText } from '@tanstack/ai-gemini'
 
 // Define a map of provider+model to adapter factory calls
-const adapters: Record<string, () => TextAdapter> = {
+const adapters = {
   'openai/gpt-5.2': () => openaiText('gpt-5.2'),
   'anthropic/claude-sonnet-4-6': () => anthropicText('claude-sonnet-4-6'),
   'gemini/gemini-2.5-pro': () => geminiText('gemini-2.5-pro'),
 }
 
-export function handleChat(providerModel: string, messages: Array<any>) {
-  const createAdapter = adapters[providerModel]
-  if (!createAdapter) {
+function isKnownProviderModel(key: string): key is keyof typeof adapters {
+  return key in adapters
+}
+
+export function handleChat(
+  providerModel: string,
+  messages: Array<ModelMessage>,
+) {
+  if (!isKnownProviderModel(providerModel)) {
     throw new Error(`Unknown provider/model: ${providerModel}`)
   }
 
   const stream = chat({
-    adapter: createAdapter(),
+    adapter: adapters[providerModel](),
     messages,
   })
 
@@ -174,6 +183,10 @@ import { openaiText } from '@tanstack/ai-openai'
 import { anthropicText } from '@tanstack/ai-anthropic'
 import { geminiText } from '@tanstack/ai-gemini'
 
+const messages = [
+  { role: 'user' as const, content: 'Plan a database migration.' },
+]
+
 // OpenAI: reasoning with effort and summary
 const openaiStream = chat({
   adapter: openaiText('gpt-5.2'),
@@ -199,16 +212,18 @@ const anthropicStream = chat({
   },
 })
 
-// Anthropic: adaptive thinking (claude-sonnet-4-6 and newer)
+// Anthropic: adaptive thinking (Sonnet 5, Fable 5, Opus 4.7+) — depth is
+// tuned with output_config.effort instead of a token budget
 const adaptiveStream = chat({
-  adapter: anthropicText('claude-sonnet-4-6'),
+  adapter: anthropicText('claude-sonnet-5'),
   messages,
   modelOptions: {
     max_tokens: 16000,
     thinking: {
       type: 'adaptive',
+      display: 'summarized', // stream the reasoning text (default 'omitted')
     },
-    effort: 'high', // 'max' | 'high' | 'medium' | 'low'
+    output_config: { effort: 'high' }, // 'low' | 'medium' | 'high' | 'xhigh' | 'max'
   },
 })
 
@@ -263,6 +278,14 @@ inside `modelOptions` using each provider's **native** key. They are not
 top-level fields on `chat()`/`ai()`/`generate()`.
 
 ```typescript
+import { chat } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+import { geminiText } from '@tanstack/ai-gemini'
+import { ollamaText } from '@tanstack/ai-ollama'
+
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 // OpenAI — native keys
 chat({
   adapter: openaiText('gpt-5.2'),
@@ -285,8 +308,9 @@ chat({
 })
 
 // Ollama — NESTED under modelOptions.options
+// (use the `family:tag` id — a bare `llama3.3` falls back to untyped options)
 chat({
-  adapter: ollamaText('llama3.3'),
+  adapter: ollamaText('llama3.3:latest'),
   messages,
   modelOptions: {
     options: { temperature: 0.7, top_p: 0.9, num_predict: 1000 },
@@ -301,7 +325,7 @@ Per-provider sampling keys (all live inside `modelOptions`):
 | OpenAI            | `temperature` | `top_p` | `max_output_tokens`                       |
 | Anthropic         | `temperature` | `top_p` | `max_tokens`                              |
 | Gemini            | `temperature` | `topP`  | `maxOutputTokens`                         |
-| Grok (xAI)        | `temperature` | `top_p` | `max_tokens`                              |
+| Grok (xAI)        | `temperature` | `top_p` | `max_output_tokens`                       |
 | Groq              | `temperature` | `top_p` | `max_completion_tokens`                   |
 | OpenRouter (chat) | `temperature` | `topP`  | `maxCompletionTokens`                     |
 | Ollama            | `temperature` | `top_p` | `num_predict` (nested in `options`)       |
@@ -326,7 +350,16 @@ some sampling options use provider-native names. Ollama nests all sampling under
 Adapters can declare an optional capability method:
 
 ```ts
-supportsCombinedToolsAndSchema?(modelOptions?: TProviderOptions): boolean
+import { AnthropicTextAdapter } from '@tanstack/ai-anthropic'
+
+// The TextAdapter contract:
+//   supportsCombinedToolsAndSchema?: (modelOptions?: TProviderOptions) => boolean
+// Subclasses override it to narrow the capability:
+class LegacyPathAnthropic extends AnthropicTextAdapter<'claude-sonnet-4-6'> {
+  override supportsCombinedToolsAndSchema(): boolean {
+    return false
+  }
+}
 ```
 
 When `true`, the engine wires `outputSchema` into the regular
@@ -338,16 +371,16 @@ runs.
 
 Current per-adapter status (#605):
 
-| Adapter                                      | Returns                                                                                               |
-| -------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `openaiText` / `openaiChatCompletions`       | `true` (all supported models)                                                                         |
-| `anthropicText`                              | `true` for Claude 4.5+ (gated by `ANTHROPIC_COMBINED_TOOLS_AND_SCHEMA_MODELS`), `false` otherwise     |
-| `geminiText`                                 | `true` for Gemini 3.x (gated by `GEMINI_COMBINED_TOOLS_AND_SCHEMA_MODELS`), `false` otherwise         |
-| `grokText`                                   | `true` for Grok 4 family (gated by `GROK_COMBINED_TOOLS_AND_SCHEMA_MODELS`), `false` otherwise        |
-| `groqText`                                   | `false` (Groq API rejects schema + tools + stream)                                                    |
-| `openRouterText` / `openRouterResponsesText` | `false` (per-call resolution is a follow-up)                                                          |
-| `ollamaText`                                 | `false` (constrained-decoding vs tool-call grammar conflict)                                          |
-| `byteplusText`                               | Per model — `true` only for the 10 ids in `BYTEPLUS_STRUCTURED_OUTPUT_CHAT_MODELS`, `false` otherwise |
+| Adapter                                      | Returns                                                                                                                              |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `openaiText` / `openaiChatCompletions`       | `true` (all supported models)                                                                                                        |
+| `anthropicText`                              | `true` for Claude 4.5+ (gated by `ANTHROPIC_COMBINED_TOOLS_AND_SCHEMA_MODELS`), `false` otherwise                                    |
+| `geminiText`                                 | `true` for Gemini 3.x (gated by `GEMINI_COMBINED_TOOLS_AND_SCHEMA_MODELS`), `false` otherwise                                        |
+| `grokText`                                   | `true` (all chat models — inherits the OpenAI Responses base; no per-model gate)                                                     |
+| `groqText`                                   | `false` (Groq API rejects schema + tools + stream)                                                                                   |
+| `openRouterText` / `openRouterResponsesText` | Per model — `true` only when the model and every `modelOptions.models` fallback are in `OPENROUTER_COMBINED_TOOLS_AND_SCHEMA_MODELS` |
+| `ollamaText`                                 | `false` (constrained-decoding vs tool-call grammar conflict)                                                                         |
+| `byteplusText`                               | Per model — `true` only for the 10 ids in `BYTEPLUS_STRUCTURED_OUTPUT_CHAT_MODELS`, `false` otherwise                                |
 
 Subclasses can override to narrow the capability. When extending an
 adapter for a custom model that doesn't support the combination, return
@@ -371,7 +404,9 @@ dedicated package required.
 
 ```typescript
 import { openaiCompatible } from '@tanstack/ai-openai/compatible'
-import { createModel } from '@tanstack/ai'
+import { chat, createModel } from '@tanstack/ai'
+
+const messages = [{ role: 'user' as const, content: 'Hello' }]
 
 // Provider-factory: configure baseURL + apiKey + models ONCE,
 // then select a model per call (the model arg is a type-safe union).
@@ -400,6 +435,9 @@ For a single model, use the one-shot helper:
 
 ```typescript
 import { openaiCompatibleText } from '@tanstack/ai-openai/compatible'
+import { chat } from '@tanstack/ai'
+
+const messages = [{ role: 'user' as const, content: 'Hello' }]
 
 chat({
   adapter: openaiCompatibleText('deepseek-chat', {
@@ -428,13 +466,17 @@ ElevenLabs `baseUrl`/`headers`). The vendor names still work; when both are
 set, `baseURL` and `defaultHeaders` win.
 
 ```typescript
+import { createGeminiChat } from '@tanstack/ai-gemini'
+
 const gateway = {
   baseURL: 'https://gateway.example.com/google-ai-studio',
   defaultHeaders: {
     'cf-aig-authorization': `Bearer ${process.env.GATEWAY_TOKEN}`,
   },
 }
-createGeminiChat('gemini-3.8-flash', apiKey, { ...gateway })
+createGeminiChat('gemini-3.8-flash', process.env.GOOGLE_API_KEY!, {
+  ...gateway,
+})
 ```
 
 ## Common Mistakes
@@ -444,13 +486,19 @@ createGeminiChat('gemini-3.8-flash', apiKey, { ...gateway })
 The legacy `openai()` (and `anthropic()`, etc.) monolithic adapters are
 deprecated. They take the model in `chat()`, not in the factory.
 
-```typescript
-// WRONG: Legacy monolithic adapter pattern
+```typescript ignore
+// WRONG: Legacy monolithic adapter pattern (no longer exported)
 import { openai } from '@tanstack/ai-openai'
 chat({ adapter: openai(), model: 'gpt-5.2', messages })
+```
 
+```typescript
 // CORRECT: Tree-shakeable adapter, model in factory
+import { chat } from '@tanstack/ai'
 import { openaiText } from '@tanstack/ai-openai'
+
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 chat({ adapter: openaiText('gpt-5.2'), messages })
 ```
 

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

@@ -21,45 +21,58 @@ import { anthropicText } from '@tanstack/ai-anthropic'
 
 ## Key Chat Models
 
-| Model               | Context Window | Max Output | Notes                                       |
-| ------------------- | -------------- | ---------- | ------------------------------------------- |
-| `claude-fable-5`    | 1M             | 128K       | Most capable; thinking always on (adaptive) |
-| `claude-sonnet-5`   | 1M             | 128K       | Best balance; adaptive thinking by default  |
-| `claude-opus-4-8`   | 1M             | 128K       | Opus tier; adaptive thinking, no sampling   |
-| `claude-opus-4-7`   | 1M             | 128K       | Older Opus; adaptive thinking, no sampling  |
-| `claude-opus-4-6`   | 200K           | 128K       | Older Opus, adaptive + budget thinking      |
-| `claude-sonnet-4-6` | 1M             | 64K        | Previous gen balanced, adaptive + budget    |
-| `claude-sonnet-4-5` | 200K           | 64K        | Previous gen balanced                       |
-| `claude-opus-4-5`   | 200K           | 32K        | Previous gen most capable                   |
-| `claude-opus-4-1`   | 200K           | 64K        | Deprecated (retires 2026-08-05)             |
-| `claude-haiku-4-5`  | 200K           | 64K        | Fast and affordable                         |
+| Model                | Context Window | Max Output | Notes                                       |
+| -------------------- | -------------- | ---------- | ------------------------------------------- |
+| `claude-fable-5-1`   | 1M             | 128K       | Newest; thinking always on (adaptive)       |
+| `claude-fable-5`     | 1M             | 128K       | Most capable; thinking always on (adaptive) |
+| `claude-opus-5`      | 1M             | 128K       | Opus tier; budget thinking + sampling       |
+| `claude-opus-5-fast` | 1M             | 128K       | Fast-mode Opus 5; same options as opus-5    |
+| `claude-sonnet-5`    | 1M             | 128K       | Best balance; adaptive thinking by default  |
+| `claude-opus-4-8`    | 1M             | 128K       | Opus tier; adaptive thinking, no sampling   |
+| `claude-opus-4-7`    | 1M             | 128K       | Older Opus; adaptive thinking, no sampling  |
+| `claude-opus-4-6`    | 200K           | 128K       | Older Opus, adaptive + budget thinking      |
+| `claude-sonnet-4-6`  | 1M             | 64K        | Previous gen balanced, adaptive + budget    |
+| `claude-sonnet-4-5`  | 200K           | 64K        | Previous gen balanced                       |
+| `claude-opus-4-5`    | 200K           | 32K        | Previous gen most capable                   |
+| `claude-opus-4-1`    | 200K           | 64K        | Deprecated (retires 2026-08-05)             |
+| `claude-haiku-4-5`   | 200K           | 64K        | Fast and affordable                         |
 
 Note: Model IDs use the format `claude-sonnet-5`, `claude-opus-4-8`, etc.
-Retired models (Claude 3.x, Sonnet 3.7, Opus 4 / Sonnet 4) and the `-fast`
-variant ids were removed — every registered id resolves against the
-first-party Anthropic API.
+Retired models (Claude 3.x, Sonnet 3.7, Opus 4 / Sonnet 4) were removed —
+every registered id resolves against the first-party Anthropic API.
+`claude-opus-5-fast` is the only `-fast` id that remains.
+
+`output_config.effort` is typed only on the adaptive-era models
+(`claude-opus-4-7`, `claude-opus-4-8`, `claude-sonnet-5`, `claude-fable-5`,
+`claude-fable-5-1`). There is no top-level `effort` option on any model;
+`claude-opus-4-6` / `claude-sonnet-4-6` accept `thinking: { type: 'adaptive' }`
+but no effort knob.
 
 ## Provider-Specific modelOptions
 
 ```typescript
+import { chat } from '@tanstack/ai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 chat({
   adapter: anthropicText('claude-sonnet-4-6'),
   messages,
   modelOptions: {
     // Sampling
     temperature: 0.7,
-    top_p: 0.9, // cannot be combined with temperature
+    // 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 < max_tokens
     },
-    // Adaptive thinking (claude-sonnet-4-6, claude-opus-4-6+)
-    thinking: {
-      type: 'adaptive',
-    },
-    effort: 'high', // 'max' | 'high' | 'medium' | 'low'
+    // Adaptive thinking (claude-sonnet-4-6, claude-opus-4-6+) — the
+    // alternative to the budget shape above; effort is tuned via
+    // output_config.effort on the adaptive-era models (see below)
+    // thinking: { type: 'adaptive' },
     // Service tier
     service_tier: 'auto', // 'auto' | 'standard_only'
     // Stop sequences
@@ -99,6 +112,11 @@ ANTHROPIC_API_KEY
 The per-model types restrict `modelOptions` on the newest models:
 
 ```typescript
+import { chat } from '@tanstack/ai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 chat({
   adapter: anthropicText('claude-sonnet-5'), // or 'claude-fable-5', 'claude-opus-4-8'
   messages,

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

@@ -62,6 +62,11 @@ Media models: `BYTEPLUS_VIDEO_MODELS` (Seedance —
 ## Provider-Specific modelOptions
 
 ```typescript
+import { chat } from '@tanstack/ai'
+import { byteplusText } from '@tanstack/ai-byteplus'
+
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 chat({
   adapter: byteplusText('dola-seed-2-1-turbo-260628'),
   messages,

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

@@ -38,6 +38,15 @@ Most Gemini text models accept `text`, `image`, `audio`, `video`, and `document`
 ## Provider-Specific modelOptions
 
 ```typescript
+import { chat } from '@tanstack/ai'
+import {
+  geminiText,
+  HarmBlockThreshold,
+  HarmCategory,
+} from '@tanstack/ai-gemini'
+
+const messages = [{ role: 'user' as const, content: 'Hello' }]
+
 chat({
   adapter: geminiText('gemini-2.5-pro'),
   messages,
@@ -47,15 +56,14 @@ chat({
       includeThoughts: true,
       thinkingBudget: 4096,
     },
-    // Thinking (level-based, advanced models)
-    thinkingConfig: {
-      thinkingLevel: 'THINKING_LEVEL_HIGH',
-    },
+    // Thinking (level-based, advanced models) — the alternative to the
+    // budget shape above:
+    // thinkingConfig: { thinkingLevel: 'THINKING_LEVEL_HIGH' },
     // Safety settings
     safetySettings: [
       {
-        category: 'HARM_CATEGORY_HATE_SPEECH',
-        threshold: 'BLOCK_MEDIUM_AND_ABOVE',
+        category: HarmCategory.HARM_CATEGORY_HATE_SPEECH,
+        threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
       },
     ],
     // Tool config

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