Provider Shape Audit

This document is the control surface for provider wire-shape correctness. The SDK should not rely on a provider being "OpenAI-compatible" without request, response, stream, or live evidence that the adapter still matches the provider surface.

Coverage markers:

• request-golden - tests assert method, URL, headers, query params, and body.
• response-fixture - tests parse provider-shaped response fixtures or stubs.
• stream-fixture - tests replay SSE/stream/eventstream chunks.
• live-smoke - env-gated live test calls the real provider.
• unchecked - adapter behavior is inferred from shared code or docs only.

Chat

Provider	ID	Adapter family	Coverage	High-risk gaps
OpenAI	:openai	OpenAI Chat Completions	request-golden, response-fixture, stream-fixture, live-smoke	Broaden live tool/JSON-schema coverage after refactor.
Anthropic	:anthropic	Anthropic Messages	request-golden, response-fixture, stream-fixture, live-smoke	Keep thinking signatures, OAuth headers, tool replay, and cache markers pinned.
Gemini Native	:gemini-native	Gemini REST	request-golden, response-fixture, stream-fixture, live-smoke	Thought signatures, tool responses, cachedContent, and safety blocks need explicit fixtures.
Vertex Gemini	:vertex-gemini	Vertex REST wrapper over Gemini	request-golden, response-fixture, stream-fixture, live-smoke	Region/global URL routing, ADC headers, and provider id preservation are critical.
Vertex Anthropic	:vertex-anthropic	Anthropic Messages over Vertex (rawPredict/streamRawPredict)	request-golden, response-fixture, stream-fixture, live-smoke	Model moves to URL path, anthropic_version in body, GCP OAuth replaces x-api-key, region/global routing; reuses native Anthropic body/parse.
OpenRouter	:openrouter	OpenAI-wire custom wrapper	request-golden, response-fixture, stream-fixture, live-smoke	Provider routing, plugins, reasoning, envelope cache, embeddings, and provider-specific usage need fixtures.
Azure OpenAI deployment	caller-defined	OpenAI Chat Completions with classic deployment or v1 routing	request-golden, response-fixture, stream-fixture	Classic routes by URL deployment and API version; v1 routes under /openai/v1 and binds the deployment as the body model.
Codex Responses	:codex	OpenAI Responses	request-golden, response-fixture, stream-fixture, live-smoke	Encrypted reasoning/provider replay state must stay intact.
Codex Backend	:codex-backend	ChatGPT Codex backend	request-golden, response-fixture, stream-fixture, live-smoke	SSE-first non-streaming behavior, auth headers, and backend usage parsing are load-bearing.
Perplexity	:perplexity	Native Agent POST /v1/agent	request-golden, response-fixture, stream-fixture, live-smoke	Canonical messages become Agent input items; typed message/search output, URL annotations, usage, and Responses-style SSE events must stay pinned.
Cohere	:cohere	Native Cohere chat	request-golden, response-fixture, stream-fixture, live-smoke	Documents, citations, tool calls, and v2 response variants need pinned fixtures.
Bedrock	:bedrock	AWS Bedrock Converse	request-golden, response-fixture, stream-fixture	Live proof depends on AWS env; eventstream and cachePoint fixtures are mandatory.
Ollama Native	:ollama-native	Ollama /api/chat	request-golden, response-fixture, stream-fixture	Local runtime live smoke is optional; NDJSON stream shape must be pinned.
Fake/Test	:fake	Deterministic test transport	request-golden, response-fixture	Keep as SDK-internal test fixture only; never count as provider parity.
DeepSeek	:deepseek	OpenAI-compatible alias	request-golden, response-fixture	Live smoke and provider-specific reasoning output drift.
Kimi / Moonshot	:kimi	OpenAI-compatible alias	request-golden, response-fixture, live-smoke	Thinking fields and model catalog separation.
Kimi Code	:kimi-code	OpenAI-compatible alias	request-golden, response-fixture, live-smoke	Required KimiCLI identity headers and prompt cache key.
Mistral	:mistral	OpenAI-compatible alias	request-golden, response-fixture, live-smoke	Dropped penalty fields and JSON-schema compatibility.
Groq	:groq	OpenAI-compatible alias	request-golden, response-fixture, live-smoke	Reasoning format and transcription alias interactions.
Cerebras	:cerebras	OpenAI-compatible alias	request-golden, response-fixture, live-smoke	Model names and reasoning fields.
Together	:together	OpenAI-compatible alias	request-golden, response-fixture, live-smoke	Chat and embedding model/provider ids.
xAI	:xai	OpenAI-compatible alias	request-golden, response-fixture, live-smoke	Reasoning/cache routing fields.
Z.AI	:zai	OpenAI-compatible GLM chat completions	request-golden, response-fixture, stream-fixture	Reasoning replay, automatic-only tool choice, image-part serialization, cached-token usage, provider id, and structured errors must stay pinned; broader file/video support is not implied.
HuggingFace Router	:huggingface	OpenAI-compatible alias	request-golden, response-fixture, live-smoke	Router model ids and tool support are model-dependent.
Aggregator aliases	:sambanova, :deepinfra, :nebius, :hyperbolic, :novita, :friendliai, :featherless, :cloudflare, :dashscope, :volcengine	OpenAI-compatible aliases	request-golden	Mostly unchecked live behavior; keep claims conservative.

Embeddings

Provider	ID	Adapter family	Coverage	High-risk gaps
OpenAI	:openai	OpenAI /embeddings	request-golden, response-fixture, live-smoke	Dimensions override and multi-input ordering.
Gemini Native	:gemini-native	Gemini batchEmbedContents	request-golden, response-fixture	Per-input request order, dimensions/task/title options, requested model preservation, and absent usage must stay explicit.
Azure OpenAI deployment	caller-defined	OpenAI embeddings with classic deployment or v1 routing	request-golden, response-fixture	The chat registration helper must install the embedding constructor; v1 binds the deployment as body model without an API-version query.
Cohere	:cohere	Cohere /embed	request-golden, response-fixture, live-smoke	v3 input type and embedding type variants.
Voyage	:voyage	OpenAI-compatible embeddings	request-golden, response-fixture, live-smoke	Input type/provider-options behavior.
Mistral	:mistral	OpenAI-compatible embeddings	request-golden, live-smoke	Add fixture response coverage.
Together	:together	OpenAI-compatible embeddings	request-golden, live-smoke	Add fixture response coverage.
Jina	:jina	OpenAI-compatible embeddings	request-golden, live-smoke	Add fixture response coverage.
OpenRouter	:openrouter	OpenAI-compatible embeddings with OpenRouter headers	request-golden, response-fixture, live-smoke	Model prefix stripping and billing-route pricing must stay explicit.
Nebius	:nebius	OpenAI-compatible embeddings	request-golden, response-fixture	Live smoke depends on Nebius credentials/model availability.
Ollama Native	:ollama-native	Ollama /api/embed	request-golden, response-fixture	Optional local live smoke.

Other Modalities

Modality	Provider	ID	Coverage	High-risk gaps
Moderation	OpenAI	:openai	request-golden, response-fixture, live-smoke	Multi-modal moderation shape should stay explicit.
Rerank	Cohere	:cohere	request-golden, response-fixture, live-smoke	v2 and v3 field compatibility.
Rerank	Voyage	:voyage	request-golden, response-fixture, live-smoke	Score/document response variants.
Rerank	Jina	:jina	request-golden, response-fixture, live-smoke	Provider id tagging and document return shape.
Rerank	Bedrock	:bedrock	request-golden, response-fixture	Bedrock Agent Runtime /rerank requires SigV4 and model ARN routing.
Image	OpenAI	:openai	request-golden, response-fixture	Every request must name :image/model; supported gpt-image-* option families and b64 responses must stay pinned.
Image	OpenRouter	:openrouter	request-golden, response-fixture	Every request must name an OpenRouter image model; native /images parameters, usage, media type, and provider-reported cost must stay pinned.
Image	Vertex Gemini	:vertex-imagen	request-golden, response-fixture	Requested Gemini image models route over Vertex generateContent; discontinued imagen-* models fail explicitly.
Image	Bedrock	:bedrock	request-golden, response-fixture	Every request must name :image/model; the selected Amazon or Stability id controls the native request family, including legacy compatibility shapes.
Transcription	OpenAI	:openai	request-golden, response-fixture	Multipart boundary and verbose JSON variants.
Transcription	Groq	:groq	request-golden, response-fixture	Groq endpoint/base URL and model aliases.
TTS	OpenAI	:openai	request-golden, response-fixture	Raw byte response headers.
TTS	ElevenLabs	:elevenlabs	request-golden, response-fixture	Voice id URL path and output_format query.

File Attachments

File/document attachments are SDK request-shape surfaces, distinct from file lifecycle APIs such as upload/list/delete. Canonical :part/type :file content parts are provider-native only where the underlying API has a stable attachment shape:

Provider	ID	Wire Shape	Coverage	High-risk gaps
OpenAI Chat	:openai	Chat Completions file content part with file_data or file_id	request-golden, live-smoke	File data must be a data:<mime>;base64,... URI.
Codex Responses	:codex, :codex-backend	Responses input_file with file_data, file_id, or file_url	request-golden, live-smoke	File data must be a data:<mime>;base64,... URI.
Anthropic	:anthropic	Messages document block with Files API, URL, base64, or text source	request-golden	File IDs require the files-api-2025-04-14 beta header.
Gemini Native	:gemini-native	fileData URI or inlineData base64 part	request-golden	URI sources must already be provider-accessible.
Vertex Gemini	:vertex-gemini	Gemini fileData URI or inlineData base64 part under Vertex routing	request-golden	GCS URI permissions are outside SDK serialization.
Bedrock	:bedrock	Converse document content block with bytes, text, or S3 source	request-golden	Document names/formats are sanitized before signing.
Cohere	:cohere	Textual :file/content maps to native top-level documents	request-golden, live-smoke	Cohere does not fetch file IDs or decode binary data; those fail explicitly.
OpenAI-compatible aliases	aliases such as :deepseek, :kimi-code, :mistral	Unsupported for canonical :file content parts	request-golden	These adapters fail explicitly instead of inheriting OpenAI-only file support.

Refactor Gate

Before moving a provider family, the corresponding rows above must have request and response coverage. For streaming providers, stream fixtures must also exist. Live tests are useful proof, but fixtures remain the required offline regression net.

Capability Coverage Gate

The detailed per-provider SDK surface matrix lives in src/llm/sdk/provider_coverage.clj and is enforced by test/llm/sdk/provider_coverage_test.clj.

Every registered provider must explicitly declare coverage for:

• public SDK surfaces: complete/chat, streaming, embeddings, moderation, rerank, image generation, transcription, and TTS as applicable
• request shape and response shape fixtures
• stream shape, including explicit :not-applicable or :none
• context-cache behavior, including honest :none or :not-applicable
• usage/metrics normalization and canonical response stamping
• pricing/cost source, including :unknown only where intentionally unknown
• model listing source, including live /models, snapshot-only, local-only, or unsupported
• auth path and structured error classification
• live smoke status

Generated provider clients are not part of the production SDK architecture. Official OpenAPI, Discovery, Smithy, or SDK-derived examples may be stored as spec snapshots and used to create or validate fixtures.

Current Logic Audit

The provider-family rewrite includes a direct implementation read across the provider owners, not only a metadata coverage pass:

• OpenAI-compatible, OpenRouter, Perplexity Agent, Cohere, Bedrock, Gemini, Z.AI, caller-registered Azure deployment, Anthropic, Codex, and Ollama chat builders were checked for request shape, typed response/stream flattening, usage normalization, cache handling, and error classification.
• Gemini native and Azure deployment embedding builders were checked for endpoint routing, model placement, auth preservation, input ordering, usage, and structured errors.
• Provider-native cache logic stays provider-specific: Anthropic uses native cache_control, OpenRouter uses envelope markers where upstream Claude/Qwen cache semantics apply, Gemini accepts explicit cachedContent, Bedrock uses Converse cachePoint, Z.AI normalizes provider-reported cached input tokens, and unsupported providers explicitly report no cache strategy.
• Canonical typed tool-result parts keep id, name, content, and error status together. Providers with a native status lower it explicitly; providers without one reject error results rather than silently changing their meaning.
• The shared extra_body merge rejects protected and canonical wire-key collisions after normalizing string/keyword spelling, while otherwise preserving JSON field case.
• Cost attribution is wired in the public drivers for chat, embeddings, rerank, image generation, transcription, and TTS. Unknown pricing remains explicit and is not treated as zero.
• Stop-sequence handling is pinned across Anthropic, Gemini, Cohere, Bedrock, and Ollama so a single string is one stop sequence rather than a vector of characters.