@tanstack/ai 0.9.2 → 0.10.1

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

@@ -0,0 +1,82 @@
+# Ollama Adapter Reference
+
+## Package
+
+```
+@tanstack/ai-ollama
+```
+
+## Adapter Factories
+
+| Factory           | Type      | Description        |
+| ----------------- | --------- | ------------------ |
+| `ollamaText`      | Text/Chat | Chat completions   |
+| `ollamaSummarize` | Summarize | Text summarization |
+
+## Import
+
+```typescript
+import { ollamaText } from '@tanstack/ai-ollama'
+```
+
+## Key Models (Local)
+
+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       |
+
+Models must be pulled first: `ollama pull llama3.3`
+
+## Provider-Specific modelOptions
+
+Ollama models use a generic options type. Provider options vary by the
+underlying model. The adapter passes options through to the Ollama API.
+
+```typescript
+import { chat } from '@tanstack/ai'
+import { ollamaText } from '@tanstack/ai-ollama'
+
+const stream = chat({
+  adapter: ollamaText('llama3.3'),
+  messages,
+  temperature: 0.7,
+  // Ollama-specific options are limited compared to cloud providers
+})
+```
+
+## Configuration
+
+```typescript
+// With explicit host
+const adapter = ollamaText('llama3.3', {
+  host: 'http://my-server:11434',
+})
+```
+
+## Environment Variable
+
+```
+OLLAMA_HOST  (default: http://localhost:11434)
+```
+
+No API key is needed. Ollama runs locally by default.
+
+## Gotchas
+
+- **System prompts:** Pass system prompts via the `systemPrompts` option in `chat()`.
+- Ollama requires models to be downloaded first (`ollama pull <model>`).
+  The adapter does not auto-download models.
+- The model catalog is very large (60+ model families). Model names follow
+  Ollama's naming: `family:variant` (e.g., `llama3.3:70b`).
+- Vision models (e.g., `llama3.2-vision`, `llava`, `gemma3`) support
+  image input. Text-only models do not.
+- No image generation, TTS, or transcription adapters for Ollama.

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

@@ -0,0 +1,95 @@
+# OpenAI Adapter Reference
+
+## Package
+
+```
+@tanstack/ai-openai
+```
+
+## Adapter Factories
+
+| Factory               | Type           | Description                          |
+| --------------------- | -------------- | ------------------------------------ |
+| `openaiText`          | Text/Chat      | Chat completions (Responses API)     |
+| `openaiImage`         | Image          | Image generation (DALL-E, GPT Image) |
+| `openaiSpeech`        | TTS            | Text-to-speech                       |
+| `openaiTranscription` | Transcription  | Speech-to-text                       |
+| `openaiVideo`         | Video          | Video generation (experimental)      |
+| `openaiSummarize`     | Summarize      | Text summarization                   |
+| `openaiRealtime`      | Realtime/Voice | Realtime voice conversations         |
+
+## Import
+
+```typescript
+import { openaiText } from '@tanstack/ai-openai'
+import { openaiImage } from '@tanstack/ai-openai'
+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                         |
+
+## Provider-Specific modelOptions
+
+```typescript
+chat({
+  adapter: openaiText('gpt-5.4'),
+  messages,
+  modelOptions: {
+    // Reasoning (effort levels: none, minimal, low, medium, high)
+    reasoning: {
+      effort: 'high',
+      summary: 'auto', // 'auto' | 'detailed'
+    },
+    // Service tier
+    service_tier: 'auto', // 'auto' | 'default' | 'flex' | 'priority'
+    // Response storage
+    store: true,
+    // Truncation strategy
+    truncation: 'auto', // 'auto' | 'disabled'
+    // Tool calling
+    max_tool_calls: 10,
+    parallel_tool_calls: true,
+    tool_choice: 'auto', // 'auto' | 'none' | 'required'
+    // Structured output
+    text: {
+      /* ResponseTextConfig */
+    },
+    // Metadata (max 16 key-value pairs)
+    metadata: { session_id: 'abc' },
+    // Streaming
+    stream_options: { include_obfuscation: true },
+    // Verbosity
+    verbosity: 'medium', // 'low' | 'medium' | 'high'
+    // Prompt caching
+    prompt_cache_key: 'my-cache',
+    prompt_cache_retention: '24h',
+    // Conversations API
+    conversation: { id: 'conv-123' },
+    // Background processing
+    background: false,
+  },
+})
+```
+
+## Environment Variable
+
+```
+OPENAI_API_KEY
+```
+
+## Gotchas
+
+- Uses the **Responses API** (not Chat Completions) by default.
+- `gpt-5.1` defaults reasoning effort to `none`; you must explicitly set
+  `effort: 'low'` or higher to enable reasoning.
+- `o3-pro` only supports `high` reasoning effort.
+- `conversation` and `previous_response_id` cannot be used together.

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

@@ -0,0 +1,99 @@
+# OpenRouter Adapter Reference
+
+## Package
+
+```
+@tanstack/ai-openrouter
+```
+
+## Adapter Factories
+
+| Factory               | Type      | Description        |
+| --------------------- | --------- | ------------------ |
+| `openRouterText`      | Text/Chat | Chat completions   |
+| `openRouterImage`     | Image     | Image generation   |
+| `openRouterSummarize` | Summarize | Text summarization |
+
+## Import
+
+```typescript
+import { openRouterText } from '@tanstack/ai-openrouter'
+```
+
+## Key Models
+
+OpenRouter routes to hundreds of models across providers. Model IDs use
+the format `provider/model-name`:
+
+| Model ID                      | Notes                      |
+| ----------------------------- | -------------------------- |
+| `anthropic/claude-sonnet-4`   | Claude via OpenRouter      |
+| `openai/gpt-5.2`              | GPT-5.2 via OpenRouter     |
+| `google/gemini-2.5-pro`       | Gemini via OpenRouter      |
+| `meta-llama/llama-4-maverick` | Open-source via OpenRouter |
+| `deepseek/deepseek-r1`        | Reasoning model            |
+
+## Provider-Specific modelOptions
+
+OpenRouter has unique routing and provider selection options:
+
+```typescript
+chat({
+  adapter: openRouterText('anthropic/claude-sonnet-4'),
+  messages,
+  modelOptions: {
+    // Reasoning
+    reasoning: {
+      effort: 'high', // 'none' | 'minimal' | 'low' | 'medium' | 'high'
+      max_tokens: 4096,
+      exclude: false,
+    },
+    // 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,
+    // Stop sequences
+    stop: ['\n\n'],
+    // Tool calling
+    toolChoice: 'auto',
+    parallelToolCalls: true,
+    // Response format
+    responseFormat: { type: 'json_object' },
+    // Web search
+    webSearchOptions: {
+      search_context_size: 'medium', // 'low' | 'medium' | 'high'
+    },
+    // Verbosity
+    verbosity: 'medium',
+    // Logprobs
+    logprobs: true,
+    topLogprobs: 5,
+  },
+})
+```
+
+## Environment Variable
+
+```
+OPENROUTER_API_KEY
+```
+
+## Gotchas
+
+- 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.

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

@@ -0,0 +1,232 @@
+---
+name: ai-core/ag-ui-protocol
+description: >
+  Server-side AG-UI streaming protocol implementation: StreamChunk event
+  types (RUN_STARTED, TEXT_MESSAGE_START/CONTENT/END, TOOL_CALL_START/ARGS/END,
+  RUN_FINISHED, RUN_ERROR, STEP_STARTED/STEP_FINISHED, STATE_SNAPSHOT/DELTA,
+  CUSTOM), toServerSentEventsStream() for SSE format, toHttpStream() for
+  NDJSON format. For backends serving AG-UI events without client packages.
+type: sub-skill
+library: tanstack-ai
+library_version: '0.10.0'
+sources:
+  - 'TanStack/ai:docs/protocol/chunk-definitions.md'
+  - 'TanStack/ai:docs/protocol/sse-protocol.md'
+  - 'TanStack/ai:docs/protocol/http-stream-protocol.md'
+---
+
+# AG-UI Protocol
+
+This skill builds on ai-core. Read it first for critical rules.
+
+## Setup — Server Endpoint Producing AG-UI Events via SSE
+
+```typescript
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+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'),
+    messages,
+  })
+  return toServerSentEventsResponse(stream)
+}
+```
+
+`chat()` returns an `AsyncIterable<StreamChunk>`. Each `StreamChunk` is a
+typed AG-UI event (discriminated union on `type`). The `toServerSentEventsResponse()`
+helper encodes that iterable into an SSE-formatted `Response` with correct headers.
+
+## Core Patterns
+
+### 1. SSE Format — toServerSentEventsStream / toServerSentEventsResponse
+
+**Wire format:** Each event is `data: <JSON>\n\n`. Stream ends with `data: [DONE]\n\n`.
+
+```typescript
+import {
+  chat,
+  toServerSentEventsStream,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+
+// Option A: Get a ReadableStream (manual Response construction)
+const abortController = new AbortController()
+const stream = chat({
+  adapter: openaiText('gpt-5.2'),
+  messages,
+  abortController,
+})
+const sseStream = toServerSentEventsStream(stream, abortController)
+
+const response = new Response(sseStream, {
+  headers: {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    Connection: 'keep-alive',
+  },
+})
+
+// Option B: Use the helper (sets headers automatically)
+const response2 = toServerSentEventsResponse(stream, { abortController })
+// Default headers: Content-Type: text/event-stream, Cache-Control: no-cache, Connection: keep-alive
+```
+
+**Default response headers set by `toServerSentEventsResponse()`:**
+
+| Header          | Value               |
+| --------------- | ------------------- |
+| `Content-Type`  | `text/event-stream` |
+| `Cache-Control` | `no-cache`          |
+| `Connection`    | `keep-alive`        |
+
+Custom headers merge on top (user headers override defaults):
+
+```typescript
+toServerSentEventsResponse(stream, {
+  headers: {
+    'X-Accel-Buffering': 'no', // Disable nginx buffering
+    'Cache-Control': 'no-store', // Override default
+  },
+  abortController,
+})
+```
+
+**Error handling:** If the stream throws, a `RUN_ERROR` event is emitted
+automatically before the stream closes. If the `abortController` is already
+aborted, the error event is suppressed and the stream closes silently.
+
+### 2. HTTP Stream (NDJSON) — toHttpStream / toHttpResponse
+
+**Wire format:** Each event is `<JSON>\n` (newline-delimited JSON, no SSE prefix, no `[DONE]` marker).
+
+```typescript
+import { chat, toHttpStream, toHttpResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+
+// Option A: Get a ReadableStream
+const abortController = new AbortController()
+const stream = chat({
+  adapter: openaiText('gpt-5.2'),
+  messages,
+  abortController,
+})
+const ndjsonStream = toHttpStream(stream, abortController)
+
+const response = new Response(ndjsonStream, {
+  headers: {
+    'Content-Type': 'application/x-ndjson',
+  },
+})
+
+// Option B: Use the helper (does NOT set headers automatically)
+const response2 = toHttpResponse(stream, { abortController })
+// Note: toHttpResponse does NOT set Content-Type automatically.
+// You should pass headers explicitly:
+const response3 = toHttpResponse(stream, {
+  headers: { 'Content-Type': 'application/x-ndjson' },
+  abortController,
+})
+```
+
+**Client-side pairing:** SSE endpoints are consumed by `fetchServerSentEvents()`.
+HTTP stream endpoints are consumed by `fetchHttpStream()`. Both are connection
+adapters from `@tanstack/ai-react` (or the framework-specific package).
+
+### 3. AG-UI Event Types Reference
+
+All events extend `BaseAGUIEvent` which carries `type`, `timestamp`, optional
+`model`, and optional `rawEvent`.
+
+| Event Type             | Description                                                                                                                 |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `RUN_STARTED`          | First event in a stream. Carries `runId` and optional `threadId`.                                                           |
+| `TEXT_MESSAGE_START`   | New text message begins. Carries `messageId` and `role`.                                                                    |
+| `TEXT_MESSAGE_CONTENT` | Incremental text token. Carries `messageId` and `delta` (the new text).                                                     |
+| `TEXT_MESSAGE_END`     | Text message complete. Carries `messageId`.                                                                                 |
+| `TOOL_CALL_START`      | Tool invocation begins. Carries `toolCallId`, `toolName`, and `index`.                                                      |
+| `TOOL_CALL_ARGS`       | Incremental tool arguments JSON. Carries `toolCallId` and `delta`.                                                          |
+| `TOOL_CALL_END`        | Tool call arguments complete. Carries `toolCallId` and `toolName`.                                                          |
+| `STEP_STARTED`         | Thinking/reasoning step begins. Carries `stepId` and optional `stepType`.                                                   |
+| `STEP_FINISHED`        | Thinking step complete. Carries `stepId`, `delta`, and optional `content`.                                                  |
+| `MESSAGES_SNAPSHOT`    | Full conversation transcript snapshot. Carries `messages: Array<UIMessage>`.                                                |
+| `STATE_SNAPSHOT`       | Full application state snapshot. Carries `state: Record<string, unknown>`.                                                  |
+| `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? }`.                                              |
+
+**Typical event sequence for a text-only response:**
+
+```
+RUN_STARTED -> TEXT_MESSAGE_START -> TEXT_MESSAGE_CONTENT (repeated) -> TEXT_MESSAGE_END -> RUN_FINISHED
+```
+
+**Typical event sequence with tool calls:**
+
+```
+RUN_STARTED -> TEXT_MESSAGE_START -> TEXT_MESSAGE_CONTENT* -> TEXT_MESSAGE_END
+            -> TOOL_CALL_START -> TOOL_CALL_ARGS* -> TOOL_CALL_END
+            -> RUN_FINISHED (finishReason: 'tool_calls')
+```
+
+**Type aliases:** `StreamChunk` is an alias for `AGUIEvent` (the discriminated
+union of all event interfaces). `StreamChunkType` is an alias for `AGUIEventType`
+(the string union of all event type literals).
+
+## Common Mistakes
+
+### MEDIUM: Proxy buffering breaks SSE streaming
+
+Reverse proxies (nginx, Cloudflare, AWS ALB) buffer SSE responses by default,
+causing events to arrive in batches instead of streaming token-by-token.
+
+Fix: Set proxy-bypass headers on the response.
+
+```typescript
+toServerSentEventsResponse(stream, {
+  headers: {
+    'X-Accel-Buffering': 'no', // nginx
+    'X-Content-Type-Options': 'nosniff', // Some CDNs
+  },
+  abortController,
+})
+```
+
+For Cloudflare Workers, SSE streams automatically. For Cloudflare proxied
+origins, ensure "Response Buffering" is disabled in the dashboard.
+
+Source: docs/protocol/sse-protocol.md
+
+### MEDIUM: Assuming all AG-UI events arrive in every response
+
+Not all event types appear in every stream:
+
+- `STEP_STARTED` / `STEP_FINISHED` only appear with thinking-enabled models
+  (e.g., `o3`, `claude-sonnet-4-5` with extended thinking). Standard models
+  skip these entirely.
+- `TOOL_CALL_START` / `TOOL_CALL_ARGS` / `TOOL_CALL_END` only appear when
+  the model invokes tools. A text-only response has none.
+- `STATE_SNAPSHOT` / `STATE_DELTA` only appear when server code explicitly
+  emits them for stateful agent workflows.
+- `MESSAGES_SNAPSHOT` only appears when the server explicitly sends a
+  full transcript snapshot.
+- `CUSTOM` events are application-defined and never emitted by default.
+
+Code that expects a fixed sequence (e.g., always waiting for `STEP_FINISHED`
+before processing text) will hang or break on models that don't emit those events.
+
+Source: docs/protocol/chunk-definitions.md
+
+## Tension
+
+HIGH Tension: AG-UI protocol compliance vs. internal message format -- TanStack
+AI's `UIMessage` format (parts-based) diverges from AG-UI spec (content-based).
+Full compliance would require a different message structure.
+
+## Cross-References
+
+- See also: `ai-core/custom-backend-integration/SKILL.md` -- Custom backends must implement SSE or HTTP stream format to work with TanStack AI client connection adapters.