feat(ai): systemPrompts accept { content, metadata } for per-provider metadata#575
Open
AlemTuzlak wants to merge 2 commits into
Open
feat(ai): systemPrompts accept { content, metadata } for per-provider metadata#575AlemTuzlak wants to merge 2 commits into
AlemTuzlak wants to merge 2 commits into
Conversation
Contributor
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
🚀 Changeset Version Preview8 package(s) bumped directly, 22 bumped as dependents. 🟥 Major bumps
🟨 Minor bumps
🟩 Patch bumps
|
|
View your CI Pipeline Execution ↗ for commit 2cfda79
☁️ 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: |
…erred metadata typing
Extends `chat({ systemPrompts })` to accept either a plain string (existing
shape — backward compatible) or `{ content, metadata }`. The structured
form's `metadata` type is inferred from the adapter at the chat() call site
via a new `TSystemPromptMetadata` generic on `TextAdapter` — no `satisfies`
needed by callers.
- Anthropic declares `AnthropicSystemPromptMetadata` → users get
`cache_control` autocomplete + type-checking.
- Adapters with no per-prompt metadata (OpenAI, Gemini, Ollama,
OpenRouter, openai-base) inherit the default `never`, which makes the
`metadata` field unusable at the call site. Passing metadata to those
adapters is a TypeScript error.
Closes the regression introduced by removing the `modelOptions.system`
escape hatch in the audit PR — there is now a public, typed path for
attaching Anthropic `cache_control` to system prompts.
Plumbing
- New `TSystemPromptMetadata = never` generic on `TextAdapter` /
`BaseTextAdapter`, surfaced via `'~types'['systemPromptMetadata']`.
`TextActivityOptions.systemPrompts` is now
`Array<SystemPrompt<TAdapter['~types']['systemPromptMetadata']>>`.
- `AnyTextAdapter` extended to 7 generic slots.
- `TextOptions.systemPrompts` (the wide internal shape adapters receive)
is `Array<SystemPrompt>`; adapters call `normalizeSystemPrompts<...>()`
to narrow.
- Chat engine + middleware context/config widened to carry
`Array<SystemPrompt>` so metadata flows through to the adapter.
- OpenTelemetry middleware extracts `.content` for span events;
per-prompt metadata is dropped from spans.
- `@tanstack/ai-event-client` mirrors the `SystemPrompt` shape locally
(avoids a circular import with `@tanstack/ai`) and projects metadata
away on the devtools wire.
Adapter mappings
- Anthropic reads `metadata.cache_control` and attaches it to the
matching `TextBlockParam`.
- OpenAI / Gemini / Ollama / OpenRouter / openai-base call
`normalizeSystemPrompts()` and join `.content` for their respective
`instructions` / `system` / `systemInstruction` fields. (Their
metadata type is `never`, so the field can't be set anyway.)
Tests
- ai-anthropic: new test verifies `cache_control` flows from
`systemPrompts[i].metadata` onto the outbound `TextBlockParam`, and
plain-string entries still produce metadata-less blocks.
- ai-openai: new test verifies mixed string + object-form input
(without metadata) produces the expected joined `instructions`.
AlemTuzlak
force-pushed
the
feat/system-prompts-metadata
branch
from
2cfda79 to
8dc3dd7
Compare
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.
Summary
Restores the ability to attach Anthropic
cache_controlto system prompts — the regression introduced by removing themodelOptions.systemescape hatch in #572 — via a typed, cross-provider mechanism.chat({ systemPrompts })now accepts either a plain string (existing shape — fully backward compatible) or{ content, metadata }. The structured form lets providers attach typed metadata per prompt:Design
@tanstack/aiexportsSystemPrompt<TMetadata = unknown>,NormalizedSystemPrompt, andnormalizeSystemPrompts(). The chat layer carries the wide shape through middleware; each adapter calls the helper at the top of its option-mapping pipeline so the rest of its code only sees{ content, metadata }..contentfor their respectiveinstructions/system/systemInstructionfields.metadata.cache_controland attaches it to the correspondingTextBlockParam. The newAnthropicSystemPromptMetadatainterface is exported from@tanstack/ai-anthropic.Plumbing
TextOptions.systemPromptswidened fromArray<string>toArray<SystemPrompt>.ChatMiddlewareContext.systemPrompts/ChatMiddlewareConfig.systemPromptswidened so middleware can read/mutate the wide shape..contentfor span events; per-prompt metadata is dropped from spans (not useful for observability).@tanstack/ai-event-clientmirrors theSystemPromptshape locally (it intentionally avoids importing@tanstack/aito prevent a circular dep) and projects metadata away on the devtools wire — devtools UI continues to receiveArray<string>.Tests
ai-anthropic: new test verifiescache_controlflows fromsystemPrompts[i].metadataonto the outboundTextBlockParam, and plain-string entries still produce metadata-less blocks.ai-openai: new test verifies mixed string + object-form input produces the expected joinedinstructionsand that provider-foreign metadata is silently dropped.Test plan
pnpm test:ciis green on this branch (33 projects × 8 targets).systemPrompts: ['x']still works for every provider;systemPrompts: [{ content: 'x' }]works for every provider; Anthropicmetadata.cache_controlreaches the wire payload.Notes
@tanstack/ai+@tanstack/ai-anthropicminor; downstream adapters patch).C:\Users\AlemTuzlak\.claude\projects\F--projects-tanstack-ai\design\system-prompts-metadata-2026-05-18.md(outside the repo, not committed).