Skip to content

Latest commit

 

History

History
843 lines (664 loc) · 60.2 KB

transcoding.md

File metadata and controls

843 lines (664 loc) · 60.2 KB

Protocol Transcoding

EggPool transparently translates between OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, and selected native provider wire surfaces, letting clients keep their public grammar while upstream contracts vary. The request path captures a small canonical semantic intent before provider-specific encoding. The mature field-level transcoders remain the compatibility implementation for Chat/Messages semantics; concrete wire codecs cover Responses and native Gemini Interactions/generateContent.

Overview

Protocol transcoding exists because providers expose several incompatible wire formats: OpenAI Chat Completions/Responses, Anthropic Messages, and native Gemini APIs. Most providers serve only one. Without the canonical boundary, a client would be limited to providers exposing its exact request grammar.

Transcoding is on by default. Every EggPool data plane normalises the client request to the appropriate upstream wire format automatically: an OpenAI Chat Completions client posting to /v1/chat/completions reaches Anthropic upstreams (and vice versa) without any operator configuration. This is the primary behaviour of the router: clients should always see their expected protocol, regardless of the upstream provider's protocol.

The transcoder sits in the request path and:

  1. Rewrites the request body before dispatch using the selected surface codec.
  2. Decodes the response body back to the client's expected format.
  3. Re-renders non-retryable errors in the client protocol so error handling stays uniform.
  4. Adapts streaming SSE events from one shared bounded frame stream in real time, preserving native terminal semantics. Same-surface Responses streams are observed and forwarded without payload reconstruction; cross-surface Responses streams use bounded lifecycle state to synthesize complete output items.

Canonical request and reasoning boundary

rust/src/wire/ir.rs contains the portable subset used for cross-surface replay: ordered messages/content blocks, function/freeform/deferred-search tools and choices, response format intent, normalized usage, response blocks, and bounded stream events. ReasoningIntent records unspecified, explicit disable, named effort, fixed budget, adaptive, or toggle semantics. Named effort is not converted to a guessed token budget; the selected provider/model capability owns the final wire encoding.

The original canonical request is retained in TranscodeContext and ProxyRequestContext. A retry or future alternate-surface attempt must start from that source, not from the body emitted for an earlier provider. Native same-surface requests retain the existing byte-preserving fast path. For Responses specifically, admission also retains a bounded source-native envelope outside the canonical IR. Responses-to-Responses forwarding keeps ordered native history, encrypted reasoning, native tools, and extensions; when an alias changes the upstream model, only the top-level model is rewritten. Cross-surface adaptation rejects native-only items/tools before dispatch and reports safely omittable extensions through bounded adaptation notices.

Responses custom tools are the portable freeform exception: a function-only target receives a strict single-string input wrapper, and the per-request tool declaration maps the provider call back to a Responses custom_tool_call/custom_tool_call_output pair. Client-executed tool_search is the portable deferred-search exception: the wrapper reuses the exact bounded query/limit schema and maps back to an authoritative tool_search_call with distinct item/call IDs. Both mappings are declaration-scoped, never inferred from a name alone, and never persisted. Hosted/server search, namespaces, and other native/server tools without a reusable semantic equivalent remain preserved only on native Responses routes or fail before provider dispatch. Eggpool never executes the search.

Request ownership and media validation

Request encoders receive the provider-bound payload as a read-only Mapping and construct a fresh target graph. The coordinator adopts that graph as the new request-local provider generation; it does not recursively copy the source request first or rematerialize the translated graph afterward. Prepared transcodes remain request-local and reuse their encoded bytes when valid.

Image and PDF data-URI validation first uses encoded-length arithmetic to reject obvious provider-limit overflow. Inputs that remain possible candidates still use strict base64 decoding; the temporary decoded validation buffer is released before the translated output container is built. Media limits, invalid-base64 behavior, and URL-source behavior are unchanged.

Streaming hot path

RequestCoordinator creates one SSEDecoder for each upstream stream. It owns UTF-8 decoding, line-ending normalization, multiline data: assembly, and bounds incomplete input to 64 KiB. Each DecodedSSEFrame is then delivered to the completion/usage observer and, when needed, the selected transcoder. DecodedSSEFrame.json_object() lazily caches a parsed object so two consumers never parse the same frame twice. Concrete transcoders do not parse raw bytes; their translate_frame() and finish() methods are synchronous. Native Responses responses remain byte-for-byte pass-through apart from observation when the client and upstream Responses surfaces match. Other translated streams retain only bounded active text, reasoning, and tool argument state. Responses output indexes and sequence numbers are downstream serialization state; function-call call_id is kept distinct from the generated output-item ID, and response.output_item.done is emitted before response.completed. Encrypted reasoning is preserved only on the native Responses path and is never synthesized from plaintext.

Usage and cost fields are preserved exactly as the upstream reported them: no translation, no rounding, no loss.

Configuration

The [transcoder] block is optional and rarely needs to be touched:

[transcoder]
# Optional loss policy: "warn" (default) or "reject"
loss_policy = "warn"
# Optional routing preference: native-protocol accounts outrank transcodable ones
prefer_native = true

[transcoder.features]
# Deprecated compatibility field; tool calling is baseline protocol
# compatibility and is translated regardless of this value.
tools = true
# Image / document content parts (default: false)
vision = false
# Extended thinking blocks ↔ reasoning_content (default: true)
thinking = true
# OpenAI response_format / json_schema coercion (default: false)
structured_outputs = false
# Anthropic-only primitives explicit handling (default: false)
anthropic_primitives = false

At boot you'll see:

INFO  Protocol transcoding ENABLED (default): clients may reach upstream accounts whose provider.protocols does not match the client protocol. loss_policy=warn prefer_native=true

Deprecated escape hatch: enabled = false

The enabled flag is deprecated but still honoured as an escape hatch for operators who need to disable translation (for example, while diagnosing routing issues or pinning legacy behaviour):

[transcoder]
enabled = false   # DEPRECATED: forces legacy protocol-exact routing

When set, EggPool boots with a WARNING and reverts to the pre-default behaviour: every request must match its upstream protocol exactly. Cross-protocol requests will fail with HTTP 400 ProtocolMismatchError. This option will be removed in a future release.

Translation Tables

Request Bodies

OpenAI → Anthropic

OpenAI field Anthropic field Notes
model model Passed through verbatim
messages[system] system Extracted from messages, concatenated
messages[user] messages[user] Text content passed through
messages[assistant] messages[assistant] Text content passed through
temperature temperature Clamped to ≤ 1.0 (Anthropic max)
max_tokens max_tokens Defaults to 4096 if missing
stop stop_sequences String → single-element list
top_p N/A Dropped, warning emitted
frequency_penalty N/A Dropped, warning emitted
presence_penalty N/A Dropped, warning emitted
n N/A Dropped when > 1, warning emitted
logprobs N/A Dropped, warning emitted
top_logprobs N/A Dropped, warning emitted
response_format output_config.format or system A verified Anthropic target receives native json_schema; otherwise the configured loss policy governs the explicitly lossy prompt fallback. json_object remains prompt-based because it has no schema to send.
reasoning_effort thinking Feature-gated: the canonical effort intent is resolved only after target capability selection; verified low/medium/high mappings remain supported and unknown labels are never assigned a guessed budget
seed N/A Dropped, warning emitted
user N/A Dropped, warning emitted
logit_bias N/A Dropped, warning emitted
messages[user].content[image_url] messages[user].content[image] Feature-gated: base64 data URI → {type: "base64", media_type, data} where data is the raw base64 payload; URL → {type: "url", url}; detail dropped; images over 5 MB are dropped with image_too_large
messages[user].content[input_audio] N/A Dropped, warning emitted
messages[user].content[file] N/A Dropped, warning emitted (file storage not bridged)
tools (function-shape) tools (Anthropic-shape) Translated field-by-field (see Tool-Use Transcoding below)
tool_choice tool_choice Translated between string and object shapes
parallel_tool_calls: true omitted Anthropic defaults to allowing parallel calls
parallel_tool_calls: false tool_choice.disable_parallel_tool_use Emitted only for a target with explicit parallel_tool_control = ["anthropic"]; otherwise loss is reported.
tools[].function.strict tools[].strict Emitted only for a target with explicit strict_tools = ["anthropic"]; otherwise loss is reported.
stream_options N/A Wrapper dropped with warning; include_usage lifted onto TranscodeContext.request_include_usage
messages[assistant].tool_calls[] messages[assistant].content[].tool_use Translated; id map mints new upstream ids
messages[tool] messages[user].content[].tool_result Translated; tool_call_id ↔ tool_use_id via id map
messages[].content[non-text] N/A Non-text blocks dropped, warning emitted

Anthropic → OpenAI

Anthropic field OpenAI field Notes
model model Passed through verbatim
system messages[system] Converted to system message
messages[user] messages[user] Text content passed through
messages[assistant] messages[assistant] Text content passed through
temperature temperature Passed through
max_tokens max_tokens Passed through
stop_sequences stop Single → string, multi → list
metadata.user_id user Mapped to OpenAI user field
top_k N/A Dropped, warning top_k_dropped emitted
cache_control N/A Dropped, warning cache_control_feature_disabled emitted
thinking N/A Dropped, warning emitted (see Extended Thinking below)
context_management N/A Dropped, warning emitted (experimental)
container N/A Dropped, warning emitted (experimental)
mcp_servers N/A Dropped, warning emitted (experimental)
tools (Anthropic-shape) tools (function-shape) Translated field-by-field (see Tool-Use Transcoding below)
tool_choice tool_choice Translated between object and string shapes
tools[].cache_control N/A Dropped with cache_control_unsupported_by_target_protocol warning; boundary tracked on TranscodeContext.cache_boundary_tracker
messages[].content[].cache_control N/A Dropped with cache_control_unsupported_by_target_protocol warning
messages[assistant].content[thinking] messages[assistant].reasoning_content Feature-gated: thinking text mapped; signature dropped with thinking_signature_dropped warning
messages[assistant].content[image] messages[user].content[image_url] Feature-gated: base64 → data URI; URL → image_url.url
messages[user].content[document] messages[user].content[file] Feature-gated: PDF base64 → file with data URI; URL dropped; non-PDF, invalid base64, and PDFs over 32 MB are dropped. All requests must also fit [server].max_request_body_bytes (10 MiB by default).
messages[assistant].content[].tool_use messages[assistant].tool_calls[] Translated; id map mints new client ids
messages[user].content[].tool_result messages[tool] Translated; tool_use_id ↔ tool_call_id via id map
messages[].content[non-text] N/A Non-text blocks dropped, warning emitted

Response Bodies

Anthropic → OpenAI

Anthropic field OpenAI field Notes
id id Prefixed chatcmpl- if needed
model model Passed through
content[].text message.content Text blocks concatenated
content[].tool_use message.tool_calls[] Translated; id map mints new client ids
content[].thinking message.reasoning_content Feature-gated: thinking text mapped; signature dropped with thinking_signature_dropped warning
content[].redacted_thinking N/A Dropped, warning emitted
content[].image message.content[image_url] Feature-gated: base64 → data URI; URL → image_url.url
stop_reason choices[].finish_reason Mapped (see table below)
usage.input_tokens usage.prompt_tokens Direct mapping
usage.output_tokens usage.completion_tokens Direct mapping
N/A usage.total_tokens Computed (prompt + completion)

OpenAI → Anthropic

OpenAI field Anthropic field Notes
id id Prefixed msg_ if needed
model model Passed through
message.content content[].text Wrapped in text block
message.tool_calls[] content[].tool_use Translated; id map mints new upstream ids
message.reasoning_content content[].thinking Feature-gated: reasoning text mapped to thinking block
choices[].finish_reason stop_reason Mapped (see table below)
usage.prompt_tokens usage.input_tokens Direct mapping
usage.completion_tokens usage.output_tokens Direct mapping
message.refusal content[].text + stop_reason=refusal Content replaced

Stop/Finish Reason Mapping

Anthropic stop_reason OpenAI finish_reason
end_turn stop Lossless
stop_sequence stop Lossy (sequence identity lost)
max_tokens length Lossless
tool_use tool_calls Lossless
refusal content_filter Lossless
pause_turn tool_calls + sentinel Lossy; see Tool-Use Transcoding
model_context_window_exceeded length Lossy (cause obscured)

Tool-Use Transcoding

Tool calling is translated between OpenAI Chat Completions and Anthropic Messages in both directions, for streaming and non-streaming requests. The OpenAI Chat Completions client's tools and tool_choice reach Anthropic-only upstreams (e.g. MiniMax International) intact, and tool calls emitted by an Anthropic upstream are reconstructed as OpenAI tool_calls on the response. Anthropic clients driving OpenAI Chat Completions-only upstreams see the same round trip in reverse.

Field translation

OpenAI tools → Anthropic tools:

OpenAI input Anthropic output Notes
tools[i].type == "function" tools[i] (Anthropic-shape) Lifted; function.name → name, function.description → description, function.parameters → input_schema
tools[i].type other than "function" dropped Warning unsupported_tool_type
tools[i].function.strict tools[i].strict Capability-gated native mapping; generic compatible providers remain conservative.

Anthropic tools → OpenAI tools:

Anthropic input OpenAI output Notes
tools[i].name, description, input_schema tools[i].type == "function" with function.{name, description, parameters} parameters is the lifted input_schema
tools[i].cache_control N/A Dropped with warning; OpenAI Chat Completions has no tool-definition boundary placement

tool_choice translation:

OpenAI input Anthropic output Notes
"none" {"type": "none"}
"auto" omitted Anthropic default
"required" {"type": "any"}
{"type": "function", "function": {"name": "X"}} {"type": "tool", "name": "X"}
anything else omitted Warning invalid_tool_choice
Anthropic input OpenAI output Notes
{"type": "auto"} "auto"
{"type": "any"} "required"
{"type": "tool", "name": "X"} {"type": "function", "function": {"name": "X"}}
{"type": "none"} "none"
anything else "auto" Warning invalid_tool_choice

parallel_tool_calls:

  • parallel_tool_calls: true is omitted on the Anthropic side (Anthropic defaults to allowing parallel calls).
  • parallel_tool_calls: false maps to tool_choice.disable_parallel_tool_use = true only when the target model capability explicitly verifies that control; otherwise it produces a loss warning (or a local 400 under loss_policy = "reject").

Native capability overrides

Provider/model capability overrides use [model_capabilities.<model>.transcoding] or the provider-scoped equivalent. Supported fields are native_structured_outputs, strict_tools, parallel_tool_control, prompt_cache_breakpoints, and reasoning_efforts. Cache entries are keyed by target protocol and must declare dialect = "first_party" or dialect = "compatible_extension", plus any verified TTLs and breakpoint limit. Empty or missing fields mean unknown/unverified support; EggPool never enables native fields solely because an account advertises an OpenAI or Anthropic protocol.

Prompt-cache translation is best-effort across the representable subset. An explicit OpenAI content breakpoint can become an Anthropic block cache_control, and an Anthropic message/system block boundary can become an OpenAI prompt_cache_breakpoint, only when the target capability explicitly lists that protocol. Source-only breakpoint fields are consumed at the translation boundary and never remain on the target wire. TTLs are not treated as equivalent: Anthropic's 5-minute and 1-hour controls do not silently become OpenAI's 30-minute setting (or vice versa); mismatch metadata uses the selected target contract rather than a generic TTL literal. Anthropic tool-definition boundaries remain lossy for OpenAI Chat Completions when no native tool breakpoint is available. OpenAI's automatic caching and prompt_cache_key grouping do not opt translated Anthropic requests into explicit caching, and explicit source intent can request a mapped target boundary; EggPool does not synthesize cache controls. An absent OpenAI breakpoint is ordinary content, not a cache loss. In the reverse direction, only a breakpoint actually emitted on the OpenAI target counts as a mapping; malformed, unsupported, and overflow cases remain loss-visible without causing prompt_cache_options to appear by themselves.

Tool-call id translation

Tool-call ids are protocol-shaped and never reused across the wire. OpenAI clients expect call_<…> ids; Anthropic upstreams expect toolu_<…> ids. The transcoder maintains a per-request ToolCallIdMap keyed on the originating TranscodeContext.id_map so the two namespaces stay independent.

Direction Source id Generated id
OpenAI → Anthropic (assistant tool_calls) call_… (client) toolu_<24 hex> (via generate_anthropic_id)
Anthropic → OpenAI (assistant content[].tool_use) toolu_… (upstream) call_<24 hex> (via generate_openai_id)
OpenAI → Anthropic (role: "tool" history) call_… (client tool_call_id) toolu_… carried over as the tool_use_id on the Anthropic tool_result block
Anthropic → OpenAI (tool_result history) toolu_… (upstream tool_use_id) call_… carried over as the tool_call_id on the OpenAI tool message

Both generate_openai_id and generate_anthropic_id produce 24 hex characters after the prefix (call_ / toolu_), matching what real OpenAI and Anthropic responses emit. The id_map is per-TranscodeContext (i.e. per-request), so concurrent requests cannot collide.

Whenever the map mints a new id, the transcoder appends a tool_call_id_translated loss warning so operators can audit id translation traffic.

Message history translation

OpenAI input Anthropic output Notes
messages[i].role == "assistant", tool_calls[j].id (call_…) messages[i].content[k].type == "tool_use", id (toolu_…) id via id_map.register(call_…, toolu_…)
messages[i].role == "assistant", tool_calls[j].function.name, function.arguments tool_use.name, tool_use.input arguments JSON-parsed into an object; on parse failure the raw string is preserved as {"__raw_arguments__": "<string>"} and a malformed_tool_arguments warning is emitted
messages[i].role == "assistant", mixed text + tool_calls content: [{type: "text", ...}, {type: "tool_use", ...}, ...] Anthropic permits mixed text + tool_use in one assistant turn
messages[i].role == "tool", content: str, tool_call_id messages[i].role == "user", content: [{type: "tool_result", tool_use_id, content: <str>, is_error: <bool>}] tool_use_id resolved via id_map.to_upstream(call_id)
messages[i].role == "tool", content: list (mixed text/image) tool_result with joined text; image parts dropped Warning media_tool_result_flattened
messages[i].role == "tool", is_error: true tool_result.is_error: true Forwarded verbatim
Anthropic input OpenAI output Notes
messages[i].content[k].type == "tool_use", id (toolu_…), name, input messages[i].role == "assistant", tool_calls[k'] with id (call_…), type: "function", function.name, function.arguments input JSON-stringified into arguments; on encode failure the raw value is preserved as {"__raw_arguments__": "<string>"} with malformed_tool_arguments warning
messages[i].content[k].type == "tool_result", tool_use_id, content: str messages[i].role == "tool", tool_call_id (call_…), content: <str>
messages[i].content[k].type == "tool_result", content: list messages[i].role == "tool", content: <joined text> Text parts joined with \n; non-text dropped with non_text_content_dropped
messages[i].content[k].type == "tool_result", is_error: true messages[i].role == "tool", content: <error text> Warning tool_result_error_passthrough: OpenAI has no is_error field

Streaming translation

Anthropic → OpenAI (upstream SSE → client SSE):

Each Anthropic content_block_start with content_block.type == "tool_use" opens an indexed slot in the streaming transcoder's per-request state, keyed by the Anthropic index. The transcoder mints a fresh call_<…> id via id_map.generate_openai_id() and emits a tool_calls delta carrying {index, id, type: "function", function: {name, arguments: ""}}. Each subsequent content_block_delta with delta.type == "input_json_delta" appends partial_json to the slot's argument buffer and emits a tool_calls delta with {index, function: {arguments: <chunk>}}. The content_block_stop finalises the slot but emits nothing extra: the terminal finish_reason: "tool_calls" chunk plus [DONE] arrive on message_delta.

Upstream event Emitted client delta
content_block_start (type: tool_use, id: toolu_X, name: fn, input: {}) delta.tool_calls[i] = {index, id: call_Y, type: "function", function: {name: fn, arguments: ""}}
content_block_delta (type: input_json_delta, partial_json: <chunk>) delta.tool_calls[i] = {index, function: {arguments: <chunk>}}
content_block_stop (index: i) (nothing)
message_delta (stop_reason: tool_use) delta: {}, finish_reason: "tool_calls", then [DONE]

If flush() is called before a slot received its content_block_stop, the streaming transcoder still emits a final tool_calls delta with the accumulated arguments. If the accumulated JSON fails to parse, a malformed_tool_arguments warning is appended and the raw string is delivered anyway so the client can attempt to use the partial value.

OpenAI → Anthropic (upstream SSE → client SSE):

OpenAI tool_calls[*] deltas may arrive split across many chunks (often with the id and name on the first chunk and incremental arguments on subsequent chunks). The transcoder buffers each call keyed on the OpenAI tool_calls[*].index until finish_reason: "tool_calls" arrives on the terminal delta, then assembles the Anthropic tool_use blocks in insertion order:

event: content_block_start
data: {"index": K, "content_block": {"type": "tool_use", "id": "toolu_<…>", "name": <name>, "input": <parsed JSON>}}
event: content_block_stop
data: {"index": K}

The message_delta then carries stop_reason: "tool_use" and message_stop closes the stream. Each block is emitted at a fresh index (the position in the assembled list), so multi-tool-call OpenAI traffic round-trips to multiple Anthropic tool_use blocks at distinct indices.

Edge cases:

  • If an OpenAI delta arrives with a new index, a new slot is allocated.
  • If an existing slot receives a non-empty id mid-stream, a tool_call_id_changed warning is appended and the new id is re-registered; callers should not update the id mid-stream.
  • tool_calls[*].function.arguments is accumulated verbatim and parsed at finish_reason: "tool_calls". On parse failure, the raw string is wrapped in {"__raw_arguments__": "<string>"} and a malformed_tool_arguments warning is emitted.

pause_turn handling

Anthropic's pause_turn stop_reason signals that the model paused mid-turn (typically to wait for a long-running tool). EggPool surfaces this to OpenAI clients by mapping stop_reason: pause_turn to finish_reason: "tool_calls" and appending a synthetic sentinel entry to message.tool_calls:

{
  "id": "call_pause_turn_<request_id>",
  "type": "function",
  "function": {
    "name": "__eggpool_pause_turn__",
    "arguments": "{}"
  }
}

OpenAI clients detect the sentinel by name (__eggpool_pause_turn__) and resume the turn with the same tool_use_id they received from the original Anthropic content_block_start. The sentinel is emitted on both streaming and non-streaming paths, with a pause_turn loss warning appended in each case.

A pause_turn loss warning is also appended to TranscodeContext.loss_warnings whenever the sentinel is synthesized, so operators can audit how often pause-and-resume flows happen against their upstreams.

stream_options.include_usage lifting

OpenAI's stream_options.include_usage flag has no Anthropic analogue, so the wrapper object is dropped with a dropped_field warning when transcoding to an Anthropic upstream. The single field inside (include_usage: bool) is significant for usage accounting, so the transcoder lifts it onto TranscodeContext.request_include_usage before the streaming transcoder runs. The streaming transcoder reads request_include_usage from the context to decide whether to forward upstream usage chunks to the OpenAI client. The reverse direction (Anthropic → OpenAI) does not need this: OpenAI clients receive usage only when stream_options.include_usage was set on the request, which it wasn't.

Thinking streaming

Anthropic thinking_delta events translate to OpenAI reasoning delta fields. The field names are configurable via [transcoder.openai_reasoning_fields]: stream_delta (default ["reasoning"]) controls streaming field names. Order is preserved: thinking comes before tool_use comes before text in Anthropic, and reasoning content comes before content in OpenAI.

Upstream event Emitted client delta
content_block_start (type: thinking) (none; block is started lazily)
content_block_delta (type: thinking_delta, thinking: <text>) delta.<reasoning_field>: <text>
content_block_stop (thinking index) (nothing)

When [transcoder.features].thinking = false, streaming thinking deltas are dropped (consistent with non-streaming behavior). When emit_compat_aliases = true, multiple field names are emitted per delta.

Thinking deltas and text deltas are emitted independently: a stream may contain both reasoning and content chunks on the same request.

Response-field compatibility

EggPool makes the JSON field names used for reasoning content configurable via [transcoder.openai_reasoning_fields]. This controls both non-streaming and streaming output.

[transcoder.openai_reasoning_fields]
non_stream = ["reasoning_content"]    # message field(s) for reasoning
stream_delta = ["reasoning"]          # delta field(s) for reasoning
emit_compat_aliases = false           # emit extra aliases?

The first entry in each list is always emitted. Additional entries are only included when emit_compat_aliases = true. This is useful for clients that recognize different field names.

Non-streaming: OpenAIToAnthropic.decode_response emits reasoning content in the configured non_stream field(s) on choices[].message.

Streaming: AnthropicToOpenAIStreaming emits reasoning deltas in the configured stream_delta field(s) on choices[].delta. Streaming is feature-gated consistently with non-streaming: when [transcoder.features].thinking = false, streaming thinking deltas are dropped with no output.

Loss-warning kinds

The following kind values may appear on TranscodeContext.loss_warnings:

kind Emitted when Example fields
tool_call_id_translated The id map mints a fresh id on either side of the translation field, from, to
tool_call_id_changed A streaming delta re-supplies a non-empty id for an existing tool_call slot field, from, to
parallel_tool_calls_collapsed parallel_tool_calls: false cannot be sent because target capability is unverified field, reason
malformed_tool_arguments tool_calls[*].function.arguments or content[].tool_use.input fails to JSON-parse field, value_type, length, reason
invalid_tool_choice A tool_choice value cannot be mapped to the target shape field, optional from
unsupported_tool_type A tools[i].type other than "function" is dropped field, from
empty_tool_use_block Anthropic stop_reason: tool_use produced zero tool_use blocks field
media_tool_result_flattened Non-text media inside a tool_result block was flattened to text because the target does not support media-bearing tool results field
tool_result_error_passthrough Anthropic tool_result.is_error was forwarded as OpenAI tool content + warning (no is_error field in OpenAI shape) field
cache_control_feature_disabled Top-level Anthropic cache_control was dropped because OpenAI has no equivalent field field
cache_control_unsupported_by_target_protocol A nested cache_control annotation (system block, message block, tool definition) was dropped because the target protocol cannot carry it field
cache_control_invalid_shape A cache_control annotation was malformed (missing or non-string type) and could not be carried across field
provider_extension_not_preserved A non-portable vendor extension on an Anthropic tool (e.g. defer_loading) was dropped during translation field
stable_prefix_preserved The provider-visible stable prefix round-trips without reordering; upstream cache hints should remain valid field
stable_prefix_reordered_canonically The stable prefix was reordered to canonical key order before wire serialisation; the upstream will treat this as a new cache key but content is identical field
pause_turn stop_reason: pause_turn was mapped to finish_reason: tool_calls plus a sentinel tool_call field, to
non_text_content_dropped A non-text content part inside a translated message was dropped field
image_unsupported_format An image URL had an unrecognised scheme (not data: or https:) field
image_too_large An image exceeded the 5 MB size limit field, size
pdf_too_large A PDF document exceeded the 32 MB size limit field, size
document_url_dropped An Anthropic document with a URL source was dropped (OpenAI has no PDF URL intake) field
document_unsupported_media An Anthropic document had a non-PDF media type and was dropped field, media_type
thinking_signature_dropped An Anthropic thinking block's cryptographic signature was dropped during translation field
reasoning_content_dropped A thinking/reasoning content block was dropped because the feature was disabled field
anthropic_top_level_thinking_dropped The Anthropic top-level thinking block was dropped when transcoding to OpenAI (no verified mapping) reason
response_format_to_system_prompt An OpenAI response_format was coerced to a system-prompt instruction field
top_k_dropped Anthropic top_k was dropped (OpenAI has no top-k sampling knob) field
budget_clamped A thinking budget was clamped to the provider's maximum requested, resolved
unknown_effort A reasoning_effort value could not be mapped to a budget effort
budget_rejected Strict policy rejected an unresolvable thinking budget requested, policy
budget_resolution_no_input Budget resolution was requested but no input was provided policy

The complete catalogue lives in the Rust wire-adaptation registry.

Loss warnings are safe to emit to ordinary logs: malformed tool arguments and inputs are represented by structural metadata only. Raw request content is never included in warning objects or transcode observability logs.

Error Envelopes

Protocol Status code field Error type field Message field Request ID field
OpenAI HTTP status error.type error.message request_id
Anthropic HTTP status type error.message request_id

Error types are mapped bidirectionally:

Anthropic error type OpenAI error type
invalid_request_error invalid_request_error
authentication_error invalid_api_key
permission_error insufficient_quota
not_found_error invalid_request_error
request_too_large invalid_request_error
rate_limit_error rate_limit_exceeded
api_error api_error
overloaded_error api_error
billing_error insufficient_quota
timeout_error timeout
conflict_error invalid_request_error
internal_error api_error

Usage (Canonicalisation)

Both protocols are normalised to a common internal representation before reaching the cost calculator:

Canonical field OpenAI source Anthropic source
prompt_tokens prompt_tokens input_tokens
completion_tokens completion_tokens output_tokens
total_tokens total_tokens Computed (input + output)
cache_creation_tokens N/A cache_creation_input_tokens
cache_read_tokens N/A cache_read_input_tokens

Cache token fields are only populated for Anthropic upstreams.

For request finalization and dashboard accounting, streaming and non-streaming responses use the same protocol-specific usage extractors. Malformed, negative, or non-finite token counts are passed through the shared token-count coercion path and treated as zero for internal cost/quota calculation. The downstream response body is not rewritten solely for accounting normalization.

Provider Notes

Transcoding is triggered when the client protocol differs from the selected account's upstream protocol. Providers that need transcoding:

Provider Upstream protocol When transcoding fires
Anthropic Anthropic Client sends OpenAI requests to a model routed to an Anthropic account
OpenAI OpenAI Client sends Anthropic requests to a model routed to an OpenAI account
OpenRouter OpenAI Same as OpenAI: Anthropic clients hitting OpenRouter models
DeepSeek OpenAI Anthropic clients hitting DeepSeek models
Together AI OpenAI Anthropic clients hitting Together models
Google Gemini OpenAI Anthropic clients hitting Gemini models

Providers that support both protocols natively (like OpenCode Go) may never trigger transcoding if accounts are configured with the right protocol flags.

When prefer_native = true (the default), the router uses native protocol as a tie-breaker inside the selected routing_priority tier. Transcoding still fires when no native account is available, when a transcodable account has a better quota score, or when a higher-priority provider tier is transcodable.

Operator Checklist

For production deployments using transcoding:

  1. Review your client mix. If every client and every selected upstream account already speak the same protocol, transcoding will stay idle even though it is enabled.

  2. Set loss_policy = "warn" first. Run in warn mode for at least a week to see what fields are being dropped. Check logs for transcode.loss_warnings entries.

  3. Audit loss warnings. If a dropped field is critical for your use case (e.g., top_k for Anthropic-specific tuning), either:

    • Switch to a native-protocol provider for that model, or
    • Accept the loss and document it for your users.
  4. Test streaming. Streaming transcoding is the most complex path. Verify with a real streaming client that:

    • Text content arrives correctly.
    • finish_reason / stop_reason is correct.
    • Usage values appear in the final chunk.
    • Tool-call deltas arrive in insertion order and terminate with finish_reason: "tool_calls" plus [DONE]. For tool-using requests against Anthropic-only upstreams, ensure the synthetic __eggpool_pause_turn__ sentinel (if any) is detected and surfaced to the application logic.
  5. Check your dashboard. The Runtime page shows a Transcoding card with total transcoded requests, direction breakdown, and top loss warnings. Monitor this after adding cross-protocol providers or clients.

  6. Verify prefer_native. With prefer_native = true, native-protocol accounts win score ties inside the selected priority tier. routing_priority still selects the provider tier before this tie-breaker runs. Set prefer_native = false only if quota score alone should decide same-tier native-versus-transcoded ordering.

  7. Set loss_policy = "reject" only if you've confirmed no critical request fields are dropped. In reject mode, lossy request-body translation returns a 400 before dispatch. Loss warnings discovered while decoding upstream responses are still logged and shown in diagnostics.

Loss Warning Reference

Every loss warning is a structured dict with at minimum kind and field. The possible kind values:

kind Meaning Example
dropped_field A field was removed because the target protocol has no equivalent {"kind": "dropped_field", "field": "top_p", "reason": "anthropic_unsupported"}
missing_field A required field was absent and a default was inserted {"kind": "missing_field", "field": "max_tokens", "default": 4096}
value_clamped A value was adjusted to fit the target protocol's range {"kind": "value_clamped", "field": "temperature", "from": 2.0, "to": 1.0}
lossy_mapping A value was mapped but semantics changed {"kind": "lossy_mapping", "field": "stop_reason", "from": "stop_sequence", "to": "stop"}
inserted_field An empty or missing structure was synthesised {"kind": "inserted_field", "field": "messages", "reason": "empty_messages"}
tool_call_id_translated The id map minted a new id on either side of the translation {"kind": "tool_call_id_translated", "field": "messages[assistant].tool_calls[].id", "from": "call_…", "to": "toolu_…"}
tool_call_id_changed A streaming delta re-supplied a non-empty id for an existing tool_call slot {"kind": "tool_call_id_changed", "field": "tool_calls[]", "from": "call_X", "to": "call_Y"}
parallel_tool_calls_collapsed parallel_tool_calls: false was dropped (no Anthropic equivalent) {"kind": "parallel_tool_calls_collapsed", "field": "parallel_tool_calls"}
malformed_tool_arguments Tool argument JSON failed to parse; raw string delivered as __raw_arguments__ {"kind": "malformed_tool_arguments", "id": "call_…"}
invalid_tool_choice A tool_choice value could not be mapped to the target shape {"kind": "invalid_tool_choice", "field": "tool_choice"}
unsupported_tool_type A tools[i].type other than "function" was dropped {"kind": "unsupported_tool_type", "field": "tools[].type"}
empty_tool_use_block Anthropic stop_reason: tool_use produced zero tool_use blocks {"kind": "empty_tool_use_block", "field": "content[].tool_use"}
media_tool_result_flattened Non-text media inside a tool_result block was flattened to text {"kind": "media_tool_result_flattened", "field": "messages[tool].content"}
tool_result_error_passthrough Anthropic tool_result.is_error was forwarded as OpenAI tool content + warning {"kind": "tool_result_error_passthrough", "field": "tool_result.is_error"}
cache_control_feature_disabled Top-level Anthropic cache_control was dropped during Anthropic → OpenAI translation {"kind": "cache_control_feature_disabled", "field": "cache_control"}
cache_control_unsupported_by_target_protocol A nested cache_control annotation (system block, message block, tool definition) was dropped because OpenAI cannot carry it {"kind": "cache_control_unsupported_by_target_protocol", "field": "tools[0].cache_control"}
cache_control_invalid_shape A cache_control annotation was malformed and could not be carried across {"kind": "cache_control_invalid_shape", "field": "tools[0].cache_control"}
cache_breakpoint_invalid_shape An OpenAI explicit breakpoint marker was malformed and was removed from the Anthropic target body {"kind": "cache_breakpoint_invalid_shape", "field": "messages[0].content[0].prompt_cache_breakpoint"}
provider_extension_not_preserved A non-portable vendor extension on an Anthropic tool was dropped during translation {"kind": "provider_extension_not_preserved", "field": "tools[0].defer_loading"}
stable_prefix_preserved The provider-visible stable prefix round-trips without reordering {"kind": "stable_prefix_preserved", "field": "cache_control"}
stable_prefix_reordered_canonically The stable prefix was reordered to canonical key order before wire serialisation {"kind": "stable_prefix_reordered_canonically", "field": "cache_control"}
pause_turn stop_reason: pause_turn was mapped to finish_reason: tool_calls plus a sentinel tool_call {"kind": "pause_turn", "field": "stop_reason", "to": "tool_calls"}
non_text_content_dropped A non-text content part inside a translated message was dropped {"kind": "non_text_content_dropped", "field": "messages[assistant].content"}
image_unsupported_format An image URL had an unrecognised scheme (not data: or https:) {"kind": "image_unsupported_format", "field": "messages[user].content[image_url]"}
image_too_large An image exceeded the 5 MB size limit {"kind": "image_too_large", "field": "...", "size": 6291456}
pdf_too_large A PDF document exceeded the 32 MB size limit {"kind": "pdf_too_large", "field": "...", "size": 33554432}
document_url_dropped An Anthropic document with a URL source was dropped (OpenAI has no PDF URL intake) {"kind": "document_url_dropped", "field": "messages[user].content[document]"}
document_media_type_unsupported An Anthropic document had a non-PDF media type and was dropped {"kind": "document_media_type_unsupported", "field": "...", "media_type": "text/html"}
unsupported_modality An entire modality (e.g. audio) is not representable by the target protocol {"kind": "unsupported_modality", "field": "content[audio]", "modality": "audio"}
unsupported_source_form A specific source form (base64 or URL) is not supported for the given media type {"kind": "unsupported_source_form", "field": "content[image_url]", "source_form": "url"}
thinking_signature_dropped An Anthropic thinking block's cryptographic signature was dropped during translation {"kind": "thinking_signature_dropped", "field": "content[].thinking"}
reasoning_content_dropped A thinking/reasoning content block was dropped because the feature was disabled {"kind": "reasoning_content_dropped", "field": "content[].thinking"}
response_format_to_system_prompt An OpenAI response_format was coerced to a system-prompt instruction {"kind": "response_format_to_system_prompt", "field": "response_format"}
top_k_dropped Anthropic top_k was dropped (OpenAI has no top-k sampling knob) {"kind": "top_k_dropped", "field": "top_k"}
budget_clamped A thinking budget was clamped to the provider's maximum {"kind": "budget_clamped", "requested": 16384, "resolved": 8192}
unknown_effort A reasoning_effort value could not be mapped to a budget {"kind": "unknown_effort", "effort": "xlow"}
budget_rejected Strict policy rejected an unresolvable thinking budget {"kind": "budget_rejected", "requested": 32768, "policy": "strict"}
budget_resolution_no_input Budget resolution was requested but no input was provided {"kind": "budget_resolution_no_input", "policy": "strict"}

Additional context fields that may appear:

Field Present when
reason Explains why (e.g., anthropic_unsupported, openai_unsupported, empty_messages)
from / to Shows original and mapped value for value_clamped, lossy_mapping, tool_call_id_translated, tool_call_id_changed, pause_turn
default Shows the synthetic default for missing_field
id Tool-call id associated with the warning (e.g., malformed_tool_arguments)

The complete catalogue lives in the Rust wire-adaptation registry.

Known Lossy Mappings

Scenario Kind Detail
temperature > 1.0 → Anthropic value_clamped Clamped to 1.0
max_tokens missing from OpenAI request → Anthropic missing_field Defaulted to 4096
stop_sequence → OpenAI stop lossy_mapping Sequence identity lost
pause_turn → OpenAI tool_calls + __eggpool_pause_turn__ sentinel lossy_mapping + pause_turn Semantic change; see Tool-Use Transcoding
model_context_window_exceeded → OpenAI length lossy_mapping Cause obscured
parallel_tool_calls: false → Anthropic parallel_tool_calls_collapsed Target lacks verified parallel-tool control
tools[].function.strict → Anthropic strict_tool_capability_missing Target lacks verified strict-tool support
tools[].cache_control → OpenAI cache_control_unsupported_by_target_protocol Chat Completions has no tool-definition breakpoint placement; selected-provider contracts cannot relocate it
Top-level cache_control → OpenAI cache_control_feature_disabled OpenAI has no equivalent field; loss is policy-driven
messages[].content[].cache_control → OpenAI (preserved when capability is verified) Otherwise the boundary is reported as cache_control_unsupported_by_target_protocol; tool-definition boundaries remain unrepresentable
tools[].cache_control (OpenAI-side extension) → Anthropic (preserved) Boundary annotated preserved on TranscodeContext.cache_boundary_tracker
Non-portable Anthropic tool fields (defer_loading, etc.) → OpenAI provider_extension_not_preserved Vendor extensions have no OpenAI equivalent
function_call / functions (deprecated OpenAI API) dropped_field Deprecated; clients should migrate to tools
Tool-call id rewritten (call_… ↔ toolu_…) tool_call_id_translated Map is per-request, never collides across requests
reasoning_effort → Anthropic thinking budget_tokens lossy_mapping Heuristic mapping (low→1024, medium→4096, high→16384)
Thinking block signature → OpenAI thinking_signature_dropped Cryptographic receipt cannot be re-fed to OpenAI
response_format: json_object → Anthropic system prompt response_format_to_system_prompt Best-effort coercion; no schema is available for native output
Image input_audio / file → Anthropic dropped_field No Anthropic equivalent for OpenAI audio/file parts
Anthropic document (non-PDF) → OpenAI document_unsupported_media OpenAI file intake limited to PDF
Anthropic document (URL) → OpenAI document_url_dropped OpenAI has no PDF URL intake

Performance Characteristics

  • Body translation: a bounded in-process Rust transformation: no I/O or network calls.
  • Streaming translation: One state machine per request. The state machine processes SSE frames incrementally: no buffering of the full stream.
  • Memory: The shared decoder bounds each incomplete line/event to 64KB; the transcoder retains only protocol state and bounded tool/reasoning buffers.
  • No additional network hops: Transcoding happens inside the existing request path. There is no sidecar or proxy.

The overhead is negligible compared to upstream latency (typically 200ms–30s). You will not measure a difference in p99 latency from transcoding alone.

Streaming hot path (transcoded-stream-dispatch-fixes)

The streaming transcoder path is optimised to minimise per-chunk event-loop pressure when many transcoded streams are in flight concurrently:

  • Shared frame fan-out: The coordinator's bounded SSEDecoder owns the only UTF-8/SSE framing pass. It sends each DecodedSSEFrame to IncrementalSSEObserver and the transcoder; the transcoder no longer parses raw bytes. Shared frames lazily cache JSON objects, so usage extraction and translation do not repeat a parse. The transcoder's usage property returns a default StreamUsageResult(); callers should always read usage from the coordinator's observer.
  • Synchronous frame translation: The streaming transcoder's per-frame work (cached JSON parsing, nested map construction, serde_json serialization) performs no async I/O, so spawning an async task per chunk is unnecessary scheduler overhead. Any future implementation that requires async I/O must not be placed in this per-chunk path without a separate design review.
  • Coalesced per-chunk output: The coordinator joins the bytes the transcoder produces for one upstream chunk into a single body write rather than yielding each translated frame separately. This preserves wire ordering and granularity while reducing Hyper body writes. [DONE] and the terminal message_delta/message_stop frames are still emitted in the correct order.
  • Single-pass include_usage: upstream_include_usage is computed once during streaming dispatch setup (after any injection of OpenAI stream_options.include_usage) and threaded into the stream generator via an explicit parameter. The generator no longer re-parses the request body to determine the include-usage behaviour.
  • Compact JSON frames: Frame helpers use compact serde_json serialization (no extra whitespace). SSE clients parse the JSON payload and never rely on preserved whitespace, so this reduces both output bytes and serialization work.

Streaming codec contracts are covered by the Rust integration targets under rust/tests/, including wire_stream.rs and wire_codecs.rs. Use the native Cargo test flow for replay and terminal-evidence checks.

Cache Stability

Provider-visible prompt caching (Anthropic's cache_control breakpoints) is observational in v1: the transcoder preserves or annotates every cache_control event but never reorders key material, mutates prompt content, or synthesises cache hints that the caller did not provide. Two helpers make the cache surface explicit:

  • rust/src/wire/ owns the per-request cache-boundary tracker, structural boundary extraction, provider-visible prefix handling, and deterministic hashing.

Cache-boundary annotation kinds emitted by the tracker:

Kind Meaning
preserved Cache annotation carried across at the same path with the same cache_control_type.
preserved_relocated Reserved for future phases that rewrite the annotation onto a different target path.
dropped_unsupported_target The target protocol cannot carry this annotation (e.g. OpenAI has no cache_control).
dropped_feature_disabled Operator-disabled preservation path; the annotation was discarded by policy.
dropped_invalid_shape The annotation failed shape validation (missing or non-string type).
synthesized Reserved for future phases that synthesise cache hints on behalf of the caller.

Operators can read the boundary tracker through structured loss warnings (stable_prefix_preserved, stable_prefix_reordered_canonically, cache_control_*). Routing does not consume these annotations; cache observability is reporting-only.

Loss-policy enforcement

When the operator has set loss_policy = "reject" on [transcoder], the body transcoder raises the Rust wire-adaptation error (rendered as HTTP 400 with invalid_request_error) before upstream dispatch whenever any of the protected loss kinds is recorded:

Kind When fired
cache_control_unsupported_by_target_protocol The target protocol has no cache_control primitive and the annotation could not be carried across.
cache_control_feature_disabled The operator disabled cache_control preservation (the top-level cache_control feature gate).
cache_control_invalid_shape The annotation lacked a string type field and was rejected by shape validation.
provider_extension_not_preserved A non-portable vendor field (e.g. defer_loading) on an Anthropic tool could not be carried into the OpenAI wire.
stable_prefix_reordered_canonically Source and target cache boundary lists diverge: the prefix was canonically reordered.
unsupported_modality An entire modality (e.g. audio) is not representable by the target protocol.
unsupported_source_form A specific source form (base64 or URL) is not supported for the given media type by the target provider.
media_tool_result_flattened Non-text media inside a tool result was flattened to text because the target does not support media-bearing tool results.
document_media_type_unsupported A document media type (e.g. non-PDF) is not supported by the target provider.

The warn default preserves the v1 behaviour: the request proceeds and the loss is recorded for audit. The transcoder never injects warning text into the translated body.

Pricing Catalog Cache

The transcoder depends on the upstream pricing catalogs (OpenRouter, OpenCode Zen, ...) that the resolver pipeline caches per catalog. Each TTLCache is bounded by a configurable max_entries knob (default 4096, LRU eviction on store). Unparsed raw payloads are stripped after the catalog is parsed so the cache footprint stays small even with hundreds of models in the upstream catalog.

[pricing.catalogs.openrouter]
enabled = true
priority = 100
ttl_seconds = 86400
max_entries = 4096  # bound the in-memory catalog cache; oldest entries evict first

Lower max_entries to trade catalog completeness for steady-state RSS on memory-constrained hosts (Raspberry Pi, SBC). The OpenRouter catalog ships ~250+ entries today, so the default has plenty of headroom.

Known Limitations

  1. Headers preserved verbatim. Upstream response headers are passed through to the client without translation. Some Anthropic-specific headers (e.g., anthropic-ratelimit-*) may leak to OpenAI clients. This is cosmetic and harmless.

  2. All-or-nothing per deployment. When enabled = true, transcoding applies to every account. Per-account opt-out is not supported in v1.

  3. No partial translation. If a request contains both translatable and non-translatable features (e.g., text + vision content), the entire request is translated. Non-translatable request parts are dropped with warnings: the transcoder refuses the request only when loss_policy = "reject".

  4. loss_policy = "reject" is opt-in and strict for requests. Any single request translation loss warning causes a 400 response before upstream dispatch. This can be surprising: use warn mode first to audit.

  5. Anthropic error types are best-effort. The error type mapping covers the common cases but not every edge case. Unrecognised error types map to api_error (Anthropic) or invalid_request_error (OpenAI).

  6. Usage values are upstream-authoritative. If the upstream reports unusual usage (e.g., negative cache tokens), the transcoder passes them through. There is no sanitisation.

  7. Tool-call id remapping is opaque to clients. Every cross-protocol tool call has its id rewritten (call_… ↔ toolu_…) by the id_map. Clients that compare ids across turns see the rewritten id, not the original. The mapping is per-request so concurrent requests never collide.

  8. pause_turn is surfaced as a sentinel tool call. Anthropic's pause_turn stop_reason becomes finish_reason: "tool_calls" plus a synthetic __eggpool_pause_turn__ tool_call entry. OpenAI clients detect the pause by name and resume with the same tool_use_id.

  9. Structured outputs are capability-gated. Verified Anthropic targets receive native output_config.format JSON-schema output. Unverified targets use the explicitly lossy prompt fallback (or reject under loss_policy = "reject"), and json_object remains prompt-based because it carries no schema.

Troubleshooting

Confirm transcoding is active

Check the boot log:

INFO  Protocol transcoding ENABLED (default): clients may reach upstream accounts whose provider.protocols does not match the client protocol. loss_policy=warn prefer_native=true

If you see WARNING Protocol transcoding DISABLED, the [transcoder] enabled = false escape hatch is in effect and cross-protocol requests will fail.

Read per-request transcoding logs

Every transcoded request emits a structured INFO log:

INFO  request_id=req_abc123 client_protocol=openai upstream_protocol=anthropic
      account=anthropic-primary provider=anthropic native_match=false
      loss_warnings=2

Key fields:

  • client_protocol / upstream_protocol: confirms translation is happening
  • native_match=false: means the request was transcoded (true = no translation needed)
  • loss_warnings: count of dropped fields / lossy mappings for this request

Check loss warnings in logs

Search for dropped_field, value_clamped, or lossy_mapping in structured logs. Each entry includes the request ID and field name.

Monitor via the dashboard

The Runtime page (/runtime) includes a Transcoding card showing:

  • Total transcoded requests
  • Direction breakdown (OpenAI→Anthropic vs Anthropic→OpenAI)
  • Top loss warnings by kind and field

Monitor via CLI

eggpool stats transcoding --period 7d
eggpool stats transcoding --period 30d --json

Monitor via API

GET /api/stats/transcoding?period=24h returns the same counters as the Runtime card. JSON responses encode direction keys as strings such as "openai→anthropic" under per_direction; internal tuple keys are never exposed on the API surface.

Disable transcoding (deprecated escape hatch)

Set enabled = false in [transcoder] and restart. All requests will now require protocol match: a client speaking OpenAI to an Anthropic-only account will get a protocol mismatch error. This option is deprecated; transcoding will become unconditionally on in a future release.

Debug a specific request

  1. Find the request_id from the per-request log or dashboard.
  2. Search logs for that request ID.
  3. Look for loss_warnings: each entry tells you which field was dropped and why.
  4. If the issue is a missing field, check the translation tables above to understand what the transcoder does and does not support.