docs: fix inaccurate code samples and expand coverage across guides#691
Merged
Conversation
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThis PR updates 45 documentation files: protocol and transport specs, new built-in middleware page and imports, widespread adapter/model example string updates, chat streaming/reasoning reconciliation, tool lifecycle and approval clarifications, media/transcription docs, structured-output consumption guidance, and navigation changes. ChangesDocumentation updates
Estimated code review effort: Possibly related PRs
Suggested reviewers
✨ Finishing Touches🧪 Generate unit tests (beta)
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/chat/agentic-cycle.md (1)
163-164:maxIterationsis correctly exported from@tanstack/ai(no import change needed)
maxIterationsis re-exported as a named export from@tanstack/ai(viapackages/ai/src/index.ts), so the imports atdocs/chat/agentic-cycle.md(lines 163-164) are valid. Optional: combine intoimport { chat, maxIterations } from "@tanstack/ai";.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/chat/agentic-cycle.md` around lines 163 - 164, The two separate imports of chat and maxIterations are valid but redundant; update the import statements to a single combined import to tidy the file by replacing the separate imports with one line importing both symbols (chat, maxIterations) from "`@tanstack/ai`" so the module usage remains identical while reducing duplication.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/tools/tool-architecture.md`:
- Around line 137-139: Docs currently state the call part has no "complete"
value but ToolCallState in code includes 'complete'; update the problematic
paragraph describing the call part states (the list on the tool-call part and
the surrounding wording) to include 'complete' among the call states
(awaiting-input, input-streaming, input-complete, approval-requested,
approval-responded, complete) while keeping executing/error/cancelled described
as only present on the sibling tool-result part; ensure you reference part.state
for the tool-call and part.output mirroring to keep the conceptual diagram text
consistent with the ToolCallState type.
---
Nitpick comments:
In `@docs/chat/agentic-cycle.md`:
- Around line 163-164: The two separate imports of chat and maxIterations are
valid but redundant; update the import statements to a single combined import to
tidy the file by replacing the separate imports with one line importing both
symbols (chat, maxIterations) from "`@tanstack/ai`" so the module usage remains
identical while reducing duplication.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: a99f3893-7d45-4056-8284-5bdc1d056ba9
📒 Files selected for processing (38)
docs/adapters/anthropic.mddocs/adapters/elevenlabs.mddocs/adapters/ollama.mddocs/advanced/built-in-middleware.mddocs/advanced/extend-adapter.mddocs/advanced/middleware.mddocs/advanced/multimodal-content.mddocs/advanced/observability.mddocs/advanced/otel.mddocs/advanced/per-model-type-safety.mddocs/advanced/runtime-adapter-switching.mddocs/advanced/tree-shaking.mddocs/advanced/typed-options.mddocs/chat/agentic-cycle.mddocs/chat/streaming.mddocs/chat/thinking-content.mddocs/community-adapters/cencori.mddocs/comparison/vercel-ai-sdk.mddocs/config.jsondocs/getting-started/quick-start.mddocs/media/audio-generation.mddocs/media/generation-hooks.mddocs/media/generations.mddocs/media/image-generation.mddocs/media/text-to-speech.mddocs/media/transcription.mddocs/media/video-generation.mddocs/migration/ag-ui-compliance.mddocs/protocol/chunk-definitions.mddocs/protocol/http-stream-protocol.mddocs/protocol/sse-protocol.mddocs/structured-outputs/one-shot.mddocs/structured-outputs/overview.mddocs/tools/client-tools.mddocs/tools/server-tools.mddocs/tools/tool-approval.mddocs/tools/tool-architecture.mddocs/tools/tools.md
Comment on lines
+137
to
+139
| > **Two parts, two state sets — this page is the canonical reference.** Call states (`awaiting-input`, `input-streaming`, `input-complete`, `approval-requested`, `approval-responded`) live on the **`tool-call`** part as `part.state`. There is no `complete`/`error`/`executing`/`cancelled` value on the call part. The *result* lives on a separate sibling **`tool-result`** part whose own `state` is `streaming`, `complete`, or `error`; the resolved value is also mirrored onto the call part's `part.output`. | ||
|
|
||
| The diagram below is conceptual: the nodes after `approval-responded` (executing, success, error, cancelled) are **not** `ToolCallState` values — they correspond to the sibling `tool-result` part's state (`complete` / `error`) and the call part's `output` field. |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Check the complete ToolCallState type definition to confirm whether 'complete' is a valid call state.
# Search for the ToolCallState type definition
rg -nP -A 10 "^export type ToolCallState\s*=" --type=tsRepository: TanStack/ai
Length of output: 2465
Fix docs to include ToolCallState’s complete on the call part (tool-architecture.md).
ToolCallState includes 'complete' in the source types (e.g., packages/ai/src/types.ts and the corresponding client/event-client types), but the doc lists only five call states and claims there is no complete value on the call part. Update the call-state list/wording around lines 137-139 to include complete; keep error/executing/cancelled as tool-result-only states.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/tools/tool-architecture.md` around lines 137 - 139, Docs currently state
the call part has no "complete" value but ToolCallState in code includes
'complete'; update the problematic paragraph describing the call part states
(the list on the tool-call part and the surrounding wording) to include
'complete' among the call states (awaiting-input, input-streaming,
input-complete, approval-requested, approval-responded, complete) while keeping
executing/error/cancelled described as only present on the sibling tool-result
part; ensure you reference part.state for the tool-call and part.output
mirroring to keep the conceptual diagram text consistent with the ToolCallState
type.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/chat/thinking-content.md`:
- Line 42: Rewrite the ambiguous phrase to use an explicit comparator: update
the sentence that references passing the thinking option (modelOptions with
type: "enabled" and budget_tokens) to say that if budget_tokens >= maxTokens
then the adapter will automatically increase maxTokens so there is room for the
visible response in addition to the thinking budget; mention the exact fields
(modelOptions.thinking.type, modelOptions.thinking.budget_tokens and maxTokens)
so readers know which values are compared.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: f9bf6fda-2d68-4ad6-85ec-28dcce0788ff
📒 Files selected for processing (17)
docs/adapters/anthropic.mddocs/adapters/elevenlabs.mddocs/advanced/multimodal-content.mddocs/advanced/observability.mddocs/advanced/typed-options.mddocs/chat/thinking-content.mddocs/comparison/vercel-ai-sdk.mddocs/media/generations.mddocs/media/text-to-speech.mddocs/media/transcription.mddocs/media/video-generation.mddocs/protocol/chunk-definitions.mddocs/structured-outputs/one-shot.mddocs/structured-outputs/overview.mddocs/tools/client-tools.mddocs/tools/server-tools.mddocs/tools/tools.md
✅ Files skipped from review due to trivial changes (6)
- docs/media/generations.md
- docs/adapters/anthropic.md
- docs/advanced/typed-options.md
- docs/tools/server-tools.md
- docs/media/transcription.md
- docs/media/video-generation.md
🚧 Files skipped from review as they are similar to previous changes (6)
- docs/advanced/observability.md
- docs/structured-outputs/overview.md
- docs/media/text-to-speech.md
- docs/advanced/multimodal-content.md
- docs/tools/client-tools.md
- docs/protocol/chunk-definitions.md
| ### Anthropic (Extended Thinking) | ||
|
|
||
| Pass the `thinking` option in `providerOptions`. You must specify `budget_tokens` (minimum 1024): | ||
| Pass the `thinking` option in `modelOptions` with `type: "enabled"` and a `budget_tokens` (minimum 1024). If `budget_tokens` is not below `maxTokens`, the adapter automatically raises `maxTokens` so there is room for the visible response in addition to the thinking budget: |
Contributor
There was a problem hiding this comment.
Clarify the budget_tokens vs maxTokens condition wording.
“not below maxTokens” is ambiguous; use an explicit comparator (for example, “if budget_tokens >= maxTokens”) to avoid misconfiguration.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/chat/thinking-content.md` at line 42, Rewrite the ambiguous phrase to
use an explicit comparator: update the sentence that references passing the
thinking option (modelOptions with type: "enabled" and budget_tokens) to say
that if budget_tokens >= maxTokens then the adapter will automatically increase
maxTokens so there is room for the visible response in addition to the thinking
budget; mention the exact fields (modelOptions.thinking.type,
modelOptions.thinking.budget_tokens and maxTokens) so readers know which values
are compared.
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/chat/agentic-cycle.md (1)
163-164: 💤 Low valueConsider combining imports from the same package.
Both
chatandmaxIterationsare imported from@tanstack/ai, so they can be combined into a single import statement for consistency with standard practices.📦 Proposed fix to combine imports
-import { chat } from "`@tanstack/ai`"; -import { maxIterations } from "`@tanstack/ai`"; +import { chat, maxIterations } from "`@tanstack/ai`";🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/chat/agentic-cycle.md` around lines 163 - 164, Combine the two separate imports from the same package into a single import statement: replace the separate imports of chat and maxIterations from "`@tanstack/ai`" with one import that includes both symbols (e.g., import { chat, maxIterations } from "`@tanstack/ai`") so update the import lines that reference chat and maxIterations accordingly.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/chat/agentic-cycle.md`:
- Around line 163-164: Combine the two separate imports from the same package
into a single import statement: replace the separate imports of chat and
maxIterations from "`@tanstack/ai`" with one import that includes both symbols
(e.g., import { chat, maxIterations } from "`@tanstack/ai`") so update the import
lines that reference chat and maxIterations accordingly.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 812614e8-9b76-4dca-9487-86c9daa8e731
📒 Files selected for processing (24)
docs/adapters/anthropic.mddocs/advanced/multimodal-content.mddocs/advanced/runtime-adapter-switching.mddocs/advanced/tree-shaking.mddocs/advanced/typed-options.mddocs/chat/agentic-cycle.mddocs/chat/streaming.mddocs/chat/thinking-content.mddocs/comparison/vercel-ai-sdk.mddocs/getting-started/quick-start.mddocs/media/text-to-speech.mddocs/protocol/http-stream-protocol.mddocs/protocol/sse-protocol.mddocs/structured-outputs/multi-turn.mddocs/structured-outputs/one-shot.mddocs/structured-outputs/overview.mddocs/structured-outputs/streaming.mddocs/structured-outputs/with-tools.mddocs/tools/client-tools.mddocs/tools/provider-tools.mddocs/tools/server-tools.mddocs/tools/tool-approval.mddocs/tools/tool-architecture.mddocs/tools/tools.md
✅ Files skipped from review due to trivial changes (12)
- docs/tools/provider-tools.md
- docs/structured-outputs/overview.md
- docs/structured-outputs/multi-turn.md
- docs/structured-outputs/streaming.md
- docs/tools/tool-approval.md
- docs/chat/streaming.md
- docs/structured-outputs/one-shot.md
- docs/comparison/vercel-ai-sdk.md
- docs/protocol/http-stream-protocol.md
- docs/advanced/tree-shaking.md
- docs/media/text-to-speech.md
- docs/advanced/typed-options.md
🚧 Files skipped from review as they are similar to previous changes (6)
- docs/tools/tools.md
- docs/tools/server-tools.md
- docs/getting-started/quick-start.md
- docs/tools/tool-architecture.md
- docs/protocol/sse-protocol.md
- docs/chat/thinking-content.md
Audited all guide pages against the actual package APIs and fixed copy-paste-broken / outdated samples and filled coverage gaps. Middleware & structured outputs: - New Built-in Middleware page (toolCache, contentGuard, otel) + new top-level Middleware nav section; document structured-output chunk transforms via onChunk + ctx.phase; fix middleware type import paths. - Document client consumption (useChat partial/final) on the one-shot page. Correctness fixes (verified against packages/ source): - chat: providerOptions -> modelOptions; invalid model ids; budget_tokens requires maxTokens; async stream() factory -> fetcher; add missing imports; document default maxIterations(5) and agentLoopStrategy. - tools: toServerSentEventsStream -> toServerSentEventsResponse; remove duplicate tools key; clarify tool-call vs tool-result states; fix the React examples and state diagram; add emitCustomEvent / runtime-context. - media: add required model args to factory calls; fix recursive generateVideo; TranscriptionResult.words is top-level; speed is a top-level speech option; Gemini audio returns b64Json; onResult transform. - advanced: adapter.model (not selectedModel); GeminiImageMetadata; source.mimeType; text.format structured-output shape; fill How It Works; createModel capabilities form; soften unsubstantiated bundle figures. - protocol: rewrite SSE / HTTP-stream pages to the AG-UI event format (drop obsolete chunk shapes and [DONE]); use toHttpResponse/toHttpStream; expand chunk-definitions with TOOL_CALL_RESULT, MESSAGES_SNAPSHOT, REASONING_* and deprecated-alias notes. - adapters: elevenlabs SFX model + @elevenlabs/client; ollama modelOptions placement; cencori AG-UI event/tools alignment. - fix @tanstack/ai-openai/adapters -> @tanstack/ai-openai (ag-ui-compliance, otel).
A 7+1-agent confirmation review of the docs PR surfaced further
source-accuracy issues (and caught one regression the first fix pass
introduced). All verified against packages/ source:
- tools/server-tools: JSON-schema tool input is `unknown` (not `any`);
samples now narrow/cast args.
- thinking-content: drop the adaptive-thinking / output_config.effort
example — those option types are not wired into any model's typed
modelOptions; document the `{ type: 'enabled', budget_tokens }` form.
- multimodal-content: correct the Anthropic modality bullets (no
`claude-3*` ids; Claude Haiku 3 supports documents).
- comparison: fix the ImagePart (`source: { type:'url', url }`) and
TextPart (`content`) shapes in the flagship example.
- chunk-definitions: RUN_STARTED/RUN_FINISHED `threadId` is required;
add REASONING_MESSAGE_CHUNK to the internal-members note.
- media: createOpenaiVideo needs a model arg; video `seconds` is a
string union; transcription `responseFormat`/`prompt` are top-level
(not modelOptions); drop the non-existent gpt-4o-mini-audio-preview
TTS model; add the Audio row to the generations table.
- advanced: typed-options gpt-image-1 size must be a GptImageSize.
- observability: aiEventClient imports from @tanstack/ai-event-client
(the @tanstack/ai/event-client subpath does not exist).
- adapters: revert claude-haiku-3 -> claude-3-haiku (the id passed to
anthropicText); clarify max_tokens auto-adjust; @elevenlabs/client
(not @11labs/client); elevenlabs agentId optional, debug is DebugOption.
- structured-outputs: Standard JSON Schema /json-schema link; Zod v4.2+.
Model ids touched in these fixes use the latest per provider from
model-meta.ts (gpt-5.5, claude-sonnet-4-6, etc.).
Sweep example model ids across the PR's docs to the latest available per provider, sourced from each adapter's model-meta.ts: - OpenAI: gpt-5.2 -> gpt-5.5, gpt-5-mini -> gpt-5.4-mini - Anthropic: claude-sonnet-4-5 -> claude-sonnet-4-6, claude-opus-4-6 -> claude-opus-4.8 - Gemini: gemini-2.0-flash -> gemini-3-flash-preview, image -> gemini-3.1-flash-image-preview, tts -> gemini-3.1-flash-tts-preview Every replacement id was verified present in model-meta.ts. Intentional cases preserved: negative/capability-contrast examples (per-model-type-safety), the claude-3-haiku web_search note, model enumeration/availability tables, DALL-E and o-series demos, and the Cencori pass-through ids (external provider, no in-repo model-meta).
After rebasing onto main (which merged #660 moving temperature/topP/ maxTokens into modelOptions), fix the two spots where our edits still assumed top-level sampling: - thinking-content.md: max_tokens now lives in modelOptions alongside the thinking budget (was a top-level maxTokens). - anthropic.md: drop the stale "auto-raises top-level maxTokens" note; budget_tokens must be below modelOptions.max_tokens. (ollama.md and typed-options.md conflicts were resolved to main's new convention during the rebase.)
AlemTuzlak
force-pushed
the
worktree-lazy-beaming-sloth
branch
from
dbcbeb1 to
5017df7
Compare
Contributor
🚀 Changeset Version PreviewNo changeset entries found. Merging this PR will not cause a version bump for any packages. |
|
View your CI Pipeline Execution ↗ for commit f74d5eb
☁️ Nx Cloud last updated this comment at |
@tanstack/ai
@tanstack/ai-anthropic
@tanstack/ai-client
@tanstack/ai-code-mode
@tanstack/ai-code-mode-skills
@tanstack/ai-devtools-core
@tanstack/ai-elevenlabs
@tanstack/ai-event-client
@tanstack/ai-fal
@tanstack/ai-gemini
@tanstack/ai-grok
@tanstack/ai-groq
@tanstack/ai-isolate-cloudflare
@tanstack/ai-isolate-node
@tanstack/ai-isolate-quickjs
@tanstack/ai-ollama
@tanstack/ai-openai
@tanstack/ai-openrouter
@tanstack/ai-preact
@tanstack/ai-react
@tanstack/ai-react-ui
@tanstack/ai-solid
@tanstack/ai-solid-ui
@tanstack/ai-svelte
@tanstack/ai-utils
@tanstack/ai-vue
@tanstack/ai-vue-ui
@tanstack/openai-base
@tanstack/preact-ai-devtools
@tanstack/react-ai-devtools
@tanstack/solid-ai-devtools
commit: |
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/advanced/middleware.md (1)
701-733:⚠️ Potential issue | 🟠 MajorFix the documented middleware type import paths in
docs/advanced/middleware.md(701-733)
- The text claims built-in middleware option/type exports come from
@tanstack/ai/middlewares“not the main barrel”, butToolCacheMiddlewareOptionsis documented as importable from@tanstack/aidirectly—so the “not the main barrel” statement is likely wrong and will mislead users.- Update this section to match the actual exported TypeScript paths for
ToolCacheMiddlewareOptions,ContentGuardMiddlewareOptions, andContentFilteredInfo(or adjust the wording to reflect the correct barrel/subpath exports).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/advanced/middleware.md` around lines 701 - 733, The docs incorrectly state that built-in middleware types are exported from the subpath "`@tanstack/ai/middlewares`"; update the text to reflect the actual export surface for the types (e.g., ToolCacheMiddlewareOptions, ToolCacheStorage, ToolCacheEntry, ContentGuardMiddlewareOptions, ContentGuardRule, ContentFilteredInfo) by either changing the import example to use the main barrel "`@tanstack/ai`" if those symbols are exported there or by adjusting the wording to accurately say which specific types come from the subpath and which come from the main barrel; ensure the examples and sentence about "not the main barrel" consistently match the real TypeScript export locations for those symbols.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@docs/advanced/middleware.md`:
- Around line 701-733: The docs incorrectly state that built-in middleware types
are exported from the subpath "`@tanstack/ai/middlewares`"; update the text to
reflect the actual export surface for the types (e.g.,
ToolCacheMiddlewareOptions, ToolCacheStorage, ToolCacheEntry,
ContentGuardMiddlewareOptions, ContentGuardRule, ContentFilteredInfo) by either
changing the import example to use the main barrel "`@tanstack/ai`" if those
symbols are exported there or by adjusting the wording to accurately say which
specific types come from the subpath and which come from the main barrel; ensure
the examples and sentence about "not the main barrel" consistently match the
real TypeScript export locations for those symbols.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 8b9a44cd-7a0b-4538-97d1-c0f471947597
📒 Files selected for processing (41)
docs/adapters/anthropic.mddocs/adapters/elevenlabs.mddocs/advanced/built-in-middleware.mddocs/advanced/extend-adapter.mddocs/advanced/middleware.mddocs/advanced/multimodal-content.mddocs/advanced/observability.mddocs/advanced/otel.mddocs/advanced/per-model-type-safety.mddocs/advanced/runtime-adapter-switching.mddocs/advanced/tree-shaking.mddocs/advanced/typed-options.mddocs/chat/agentic-cycle.mddocs/chat/streaming.mddocs/chat/thinking-content.mddocs/community-adapters/cencori.mddocs/comparison/vercel-ai-sdk.mddocs/config.jsondocs/getting-started/quick-start.mddocs/media/audio-generation.mddocs/media/generation-hooks.mddocs/media/generations.mddocs/media/image-generation.mddocs/media/text-to-speech.mddocs/media/transcription.mddocs/media/video-generation.mddocs/migration/ag-ui-compliance.mddocs/protocol/chunk-definitions.mddocs/protocol/http-stream-protocol.mddocs/protocol/sse-protocol.mddocs/structured-outputs/multi-turn.mddocs/structured-outputs/one-shot.mddocs/structured-outputs/overview.mddocs/structured-outputs/streaming.mddocs/structured-outputs/with-tools.mddocs/tools/client-tools.mddocs/tools/provider-tools.mddocs/tools/server-tools.mddocs/tools/tool-approval.mddocs/tools/tool-architecture.mddocs/tools/tools.md
✅ Files skipped from review due to trivial changes (27)
- docs/structured-outputs/with-tools.md
- docs/structured-outputs/streaming.md
- docs/structured-outputs/multi-turn.md
- docs/media/generation-hooks.md
- docs/tools/provider-tools.md
- docs/media/audio-generation.md
- docs/advanced/otel.md
- docs/advanced/per-model-type-safety.md
- docs/structured-outputs/overview.md
- docs/chat/agentic-cycle.md
- docs/community-adapters/cencori.md
- docs/advanced/extend-adapter.md
- docs/advanced/tree-shaking.md
- docs/migration/ag-ui-compliance.md
- docs/tools/tools.md
- docs/media/video-generation.md
- docs/comparison/vercel-ai-sdk.md
- docs/advanced/observability.md
- docs/tools/server-tools.md
- docs/structured-outputs/one-shot.md
- docs/tools/tool-architecture.md
- docs/advanced/typed-options.md
- docs/chat/streaming.md
- docs/media/text-to-speech.md
- docs/advanced/built-in-middleware.md
- docs/protocol/http-stream-protocol.md
- docs/media/transcription.md
The "safe allowlist" example still forwarded temperature/maxTokens as top-level chat() options (missed by #660's sampling-into-modelOptions migration). Map them into modelOptions under OpenAI's native keys (temperature / max_output_tokens) so the example type-checks.
- Remove the deprecated Observability page (event-client observability is
superseded; otelMiddleware is the supported path) and its nav entry +
inbound links.
- Remove the protocol pages (chunk-definitions, sse-protocol,
http-stream-protocol) — TanStack AI implements AG-UI, whose protocol is
documented upstream; repoint the few inbound links to docs.ag-ui.com.
- Fix the broken ToolCacheStorage snippet (it imported the type then
re-declared it) and verify the shape against source.
- Remove every `as <Type>` assertion cast from the docs (JSON-schema tool
inputs, JSON.parse, formData, custom-event values, type brands, …),
replacing them with typeof/in guards, type guards, typed annotations, or
schema validation. `createModel`'s provider-option brand now uses a typed
const instead of `{} as X`.
- CLAUDE.md / AGENTS.md: codify the docs conventions — no `as` casts in
samples, use the latest model per provider from model-meta.ts, and show
both server and client sides when a doc spans both.
…t transform - built-in-middleware.md: gpt-4o -> gpt-5.5 in the examples. - middleware.md: make the "Transforming structured-output chunks" example self-contained — redact SSNs inline in the streaming JSON delta instead of calling an undefined `redact()` helper. (The docs conventions — no casts, latest models, show both sides — already live in the project CLAUDE.md / AGENTS.md; the earlier global-CLAUDE.md addition has been reverted.)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
A documentation-only pass that audited the guide pages against the actual package APIs and fixed copy-paste-broken / outdated code samples, plus filled some coverage gaps. Every fix was cross-checked against
packages/source.Highlights
Middleware & structured outputs
toolCacheMiddleware,contentGuardMiddleware,otelMiddleware) and a new top-level Middleware nav section.onChunk+ctx.phase(and the native-combined caveat); correct middleware type import paths (@tanstack/ai/middlewares).useChat'spartial/final.Correctness fixes (verified against source)
providerOptions→modelOptions; invalid model ids;budget_tokensrequiresmaxTokens;async stream()factory →fetcher; add missing imports; document the defaultmaxIterations(5)andagentLoopStrategy.toServerSentEventsStream→toServerSentEventsResponse; remove a duplicatetools:key; clarify tool-call vs tool-result states; fix the React examples and state diagram; addemitCustomEvent/ runtime-context coverage.generateVideo;TranscriptionResult.wordsis top-level;speedis a top-level speech option; Gemini audio returnsb64Json;onResulttransform signature.adapter.model(notselectedModel);GeminiImageMetadata;source.mimeType; thetext.formatstructured-output shape; fill the empty "How It Works";createModelcapabilities form; soften unsubstantiated bundle-size figures.{"type":"content"}shapes and the non-existent[DONE]marker); usetoHttpResponse/toHttpStream; expandchunk-definitionswithTOOL_CALL_RESULT,MESSAGES_SNAPSHOT, theREASONING_*family, and deprecated-alias notes.@elevenlabs/client; OllamamodelOptionsplacement; Cencori AG-UI event/tools alignment.@tanstack/ai-openai/adapters→@tanstack/ai-openai(not a real subpath).How it was done
Audited via parallel source-cross-checking agents (one per doc cluster), then applied fixes via parallel editors. One auditor claim (
complete"isn't aToolCallState") was wrong —completeis in the union but the runtime never emits it for tool-call parts — so the wording was corrected to be both type- and runtime-accurate.Verification
node scripts/verify-links.ts— no broken links🤖 Generated with Claude Code
Summary by CodeRabbit