Codecs are the only layer that knows a provider’s JSON and stream dialect. A codec maps the secret-free inference.Request and inference.Response types to and from bytes; transport, routing, authorization, and cancellation remain outside the codec.

Boundary

The public contracts are deliberately split. RequestEncoder and ResponseDecoder handle one-shot calls, while StreamDecoder is optional. ServerCodec is the inverse boundary used by the gateway. A codec is expected to be stateless and safe to share; only a returned StreamEncoder is request-scoped.

%%{init: {"theme":"base","themeVariables":{"background":"#111827","primaryColor":"#1f2937","primaryTextColor":"#f9fafb","primaryBorderColor":"#60a5fa","lineColor":"#94a3b8","secondaryColor":"#172033","tertiaryColor":"#0f172a","fontFamily":"Inter, ui-sans-serif, system-ui"}}}%%
flowchart LR
    R["inference.Request"] --> E["RequestEncoder"]
    E --> B["single-shot body"]
    B --> T["transport"]
    T --> D["ResponseDecoder"]
    D --> P["inference.Response"]
    T --> S["optional StreamDecoder"]
    S --> C["content.Chunk stream"]

Choose a codec

Package	Native endpoint shape	Streaming selection	Distinctive mapping
`codec/openaiapi`	`POST /v1/chat/completions`	JSON `stream: true` and SSE	string or multipart message content
`codec/openairesponses`	`POST /v1/responses`	JSON `stream: true` and typed SSE events	items, function calls, reasoning items
`codec/anthropicapi`	`POST /v1/messages`	JSON `stream: true` and SSE	top-level system, content blocks, cache breakpoints
`codec/geminiapi`	`:generateContent`	route changes to `:streamGenerateContent?alt=sse`	`contents` roles and function parts
`codec/bedrockconverse`	Converse body	route and response framing change	tagged Converse union, inline media

Use the matching route builder with the codec. The generic transport must not guess a path or replay a body.

Source and proof

Run the contract tests with go test ./codec/....