Chat Completions protocol adapter
The Chat Completions protocol adapter is the provider boundary for OpenAI-compatible chat APIs. It preserves native Chat requests when the upstream supports them and converts related message formats when a caller uses Anthropic Messages or OpenAI Responses. Its main job is to keep messages, tools, reasoning, streamed events, usage, and provider quirks consistent across these protocol shapes.
This page describes the Chat adapter beside the broader protocol adapter page and the Anthropic and Gemini adapters.
Boundary role
The adapter accepts several public protocol forms and selects Chat Completions as the provider-facing form. A native Chat request keeps its JSON fields and stream shape. A Messages or Responses request first becomes a Chat request, then its provider events become the caller’s original protocol again.
flowchart LR
A[Chat request] --> N[Chat boundary]
B[Messages request] --> N
C[Responses request] --> N
N --> P[OpenAI-compatible Chat provider]
P --> D[Native Chat stream]
P --> E[Messages stream]
P --> F[Responses stream]
The adapter also owns provider-specific policy. That policy can change the request shape, reasoning controls, model name, or tool name without changing the public request contract. The provider identity remains separate from the model identity sent to the upstream and the model identity returned to the caller.
Protocol paths
The main paths are:
| Caller protocol | Provider request | Caller response |
|---|---|---|
| Chat Completions | Native Chat JSON | Native Chat SSE or aggregated JSON |
| Anthropic Messages | Converted Chat JSON | Anthropic Messages SSE |
| OpenAI Responses | Converted Chat JSON | Responses SSE |
| Gemini | Converted Chat JSON | Gemini-compatible output |
References: src/…/transport.py• L539-540 src/…/transport.py• L926-1039 src/…/transport.py• L1100-1138
Request conversion
Chat request conversion starts with a strict, extensible Chat request model. Known fields are checked for valid roles, content parts, tool declarations, tool choices, refusal text, and reasoning records. Unknown fields remain available for native Chat egress, so the adapter does not discard provider extensions that it does not need to interpret.
Native Chat requests
Native Chat requests keep their supplied fields and explicit nulls when they go to a Chat provider. The adapter removes only the stream control needed for its own execution and places non-SDK fields in the provider extension area, which lets vendor fields cross the boundary without replacing canonical request fields.
Non-stream Chat requests still use the provider’s stream path so the adapter can collect the final usage data and build the requested non-stream result. The public result remains a normal Chat completion rather than an upstream stream detail.
References: src/…/request.py• L17-30 src/…/request.py• L142-150 src/…/transport.py• L926-981
Cross-protocol request forms
The adapter translates a Chat request into other provider-native request forms only when the destination can represent the data. It rejects fields that would be silently lost instead of sending a partial request.
The two main translated shapes are:
- Messages shape: system and developer instructions become system content. Tool calls become tool-use blocks. Tool results become tool-result blocks. Images become image sources.
- Responses shape: messages become input items. Tool calls become function-call items. Tool results become function-call outputs. Reasoning and refusal text keep their typed meaning when the destination supports it.
The source request is copied before translation. This keeps the caller’s history stable and allows later protocol paths to use the same request data.
References: src/…/request.py• L158-180 src/…/request.py• L352-466 src/…/request.py• L493-588 tests/…/test_chat_completions.py• L33-70
Message normalization
Message normalization creates one predictable conversation history from several valid Chat message forms. It groups compatible turns, carries assistant reasoning with assistant output, and keeps tool results tied to the tool call that produced them.
Message roles and content
The adapter accepts system, developer, user, assistant, tool, and legacy function roles at the Chat boundary. Text can be a string or a list of typed parts. Text and image parts are translated only where the destination supports them; unsupported parts or image settings produce a clear conversion error.
Assistant refusal text is preserved as text for destinations that lack a separate refusal field. Nullable assistant fields are omitted during translation so a source-side null does not become an invalid destination field.
References: src/…/request.py• L78-140 src/…/request.py• L222-263 src/…/request.py• L469-490 tests/…/test_chat_completions.py• L119-172
Tool turns
Tool history is a linked pair: an assistant message declares one or more calls, and each tool message returns output by call ID. The adapter keeps that link when it changes the pair into Messages tool blocks or Responses function-call items.
Some Chat-compatible templates reject a user turn immediately after tool output. The adapter inserts a synthetic assistant boundary with no model content in that case. This closes the tool round without changing the visible conversation.
References: src/…/request.py• L193-219 src/…/request.py• L382-411 src/…/request.py• L512-543 src/…/openai_chat.py• L29-54
Tool normalization
Tool normalization makes tool declarations and streamed tool calls portable across providers. It keeps one tool identity across the declaration, selected tool, prior assistant history, and returned call.
Tool names
OpenAI-compatible APIs limit tool names to a portable character set and length. When a client name is not portable, the adapter creates a deterministic alias for the request and uses that alias in every provider-facing tool location. Returned names are decoded before they reach the caller.
The alias map is built from the complete request history, not only the current declaration. This keeps aliases stable when a conversation is extended and prevents a generated alias from colliding with an unchanged tool name.
References: src/…/openai_tool_names.py• L11-79 src/…/openai_tool_names.py• L82-133 tests/…/test_openai_chat_tool_names.py• L78-149
Tool call streams
Tool calls can arrive as fragments. The adapter groups each fragment by its choice and by a usable upstream index or ID, then joins the name and argument text in arrival order. It supports both function-style and custom tool calls while retaining provider metadata that the output path may need.
The adapter rejects fragments when no unique call owns them, so a call cannot be attached to the wrong tool execution. It seals a call only when the source choice reaches a terminal finish and validates that the completed name is usable. It decodes tool names and restores argument-key aliases only after the argument JSON is complete. Returned calls receive a unique execution ID when the provider omits one or reuses one.
References: src/…/tool_calls.py• L17-95 src/…/tool_calls.py• L98-176 src/…/tool_calls.py• L192-352 src/…/tool_calls.py• L354-445 src/…/tool_calls.py• L43-114 src/…/tool_calls.py• L142-271
Streaming contracts
The streaming contract turns provider chunks into one client-visible lifecycle. Each output path tracks open text, reasoning, and tool blocks, maps the provider stop reason, closes open blocks, and emits one terminal event.
Each provider event is read under a fixed upstream deadline. Recognized keepalive pings do not renew that deadline, so a connection that sends only heartbeats enters the existing failure and recovery handling instead of waiting indefinitely.
Native Chat streams
Native Chat output keeps upstream chunks intact except for the public model identity. The relay checks choice indexes and finish states, rejects data after a choice has finished, and emits [DONE] only after every expected choice has completed.
Tool-call chunks receive an additional safety pass. The adapter can separate ordinary choice content from tool fragments when the envelope is known, but it does not guess how opaque provider fields map to calls. Completed native calls require a usable, unique execution ID before the grouped native frames are released. The grouped frames retain enough provider metadata for native callers while exposing completed call identity consistently.
When the adapter builds Chat output for a non-native protocol, it emits Chat-shaped deltas for assistant text, reasoning, and tool calls. A final usage chunk is included when requested. A provider that rejects the optional stream_options.include_usage field gets one retry without that option.
References: src/…/response.py• L117-155 src/…/tool_calls.py• L205-352 src/…/tool_calls.py• L354-445 src/…/transport.py• L475-537 src/…/usage.py• L23-59
Messages and Responses streams
Messages output uses the established Anthropic event lifecycle. Responses output uses one Responses lifecycle with response.created followed by output item events and one terminal event. The adapter does not expose the source protocol’s event names on the other wire.
The stream rejects events that cannot be represented. Examples include unsupported citations, annotations, content blocks, incomplete item changes, and unknown incomplete reasons. Repeated terminal calls are idempotent, so recovery or cleanup cannot emit a second completion or failure.
References: src/…/messages_stream.py• L35-118 src/…/responses_stream.py• L48-146 src/…/stream_output.py• L353-367 tests/…/test_openai_chat_stream_output.py• L53-92 tests/…/test_openai_chat_stream_output.py• L102-190
Compatibility behavior
OpenAI-compatible providers share a request protocol but differ in model lists, reasoning controls, token field names, extensions, and stream details. The adapter uses a provider profile to encode these differences at the boundary while keeping the public request and response contracts stable.
Provider profiles
A provider profile defines the provider’s name, request limits, model discovery rules, reasoning form, stream field names, and supported body fields. The profile can normalize a base URL, move caller extensions into extra_body, strip unsupported fields, or change max_tokens to max_completion_tokens.
This separation lets one transport serve many compatible providers. A provider-specific behavior change belongs in the profile or its policy rather than in the shared message and stream model.
References: src/…/profiles.py• L114-170 src/…/request_policy.py• L33-46 src/…/request_policy.py• L105-144
Reasoning compatibility
Reasoning is a provider-neutral request intent. The adapter maps that intent to the provider’s supported form, such as a named effort, a reasoning object, a thinking object, a chat-template flag, or a numeric budget. A provider with no safe control keeps its default behavior instead of receiving an invented field.
Reasoning output can arrive in a native field, a structured detail, or an opaque protected record. The adapter preserves readable reasoning when the target supports it and carries protected records through replay data when later requests need the original record.
References: src/…/reasoning.py• L15-110 src/…/request.py• L266-337 src/…/stream_output.py• L104-192
Usage and lifecycle
Usage is normalized at the end of the stream. Provider prompt, completion, cache, and reasoning counts become the fields required by the caller’s protocol. Values that are missing or inconsistent are omitted or bounded instead of being reported as false precision.
Each request owns its stream and attempt state but can borrow the provider client and connection pool. Cancellation closes the stream and releases admission so a later request can run. A failed turn does not close the reusable provider client.
References: src/…/stream_output.py• L794-817 src/…/transport.py• L1186-1221 src/…/openai_stream.py• L8-30 tests/…/test_openai_chat_transport.py• L97-123 tests/…/test_openai_chat_transport.py• L126-171
Change checklist
When these files or sections are changed, remember to consider these:
- A new Chat field must be checked in native forwarding, translated destinations, and the unsupported-field guard. Do not silently drop it in only one path.
- A new message or content type must have a representation in every advertised output protocol or must fail before the upstream request.
- A tool identity change must update declarations, tool choice, assistant history, streamed calls, and recovery aliases as one contract.
- A streamed tool-call change must keep identity scoped to the choice, seal only on source termination, preserve native metadata when fragments are replayed, and keep returned IDs unique.
- A new reasoning field must preserve the replay link between streamed readable text and its protected record.
- A stream event change must keep one terminal event, close open blocks, and preserve usage placement for both streamed and aggregated clients.
- A provider profile change must be checked against model discovery, token limits, reasoning output fields, and extension-field filtering.
- A change to upstream event reading must preserve the per-event deadline, keepalive filtering, retry paths, and cleanup for native and translated streams.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A translated request contains a field the destination cannot represent | The request could lose client intent | ChatConversionError rejects unsupported controls before an upstream attempt |
| A tool name exceeds the provider’s portable form | The provider rejects the tool or cannot match a returned call | The request gets a deterministic alias and the response decodes it |
| A tool fragment has no usable index or ID, or matches more than one call | Arguments can attach to the wrong execution | Choice-scoped identity resolution raises an upstream failure instead of guessing |
| A native call has no unique execution ID or opaque metadata cannot be separated | Native frames cannot be replayed without changing call meaning | The adapter rejects ambiguous native association and does not release the grouped frames |
| A streamed tool call ends without a valid name | The client receives a tool block that it cannot execute | The call is not sealed until its source choice finishes and its name is usable |
| A provider sends distinct metadata fragments that the destination cannot represent together | The client can receive a call with lost or conflicting metadata | Finalization rejects the call instead of selecting one fragment silently |
| A provider stream ends without a finish reason | The client sees an incomplete protocol lifecycle | The stream raises a truncation failure and does not emit normal completion |
| An upstream sends only keepalive pings within each read window | The request can wait forever without a client-visible event | The event reader consumes recognized pings without renewing the upstream read deadline |
A provider rejects stream_options.include_usage | A normal request would fail on a compatibility-only option | The adapter retries once without the optional usage request |
| A stream is cancelled while reading | Admission can remain occupied and block later requests | The stream closes and the attempt releases its admission in final cleanup |
Key files
| File | Why to read it |
|---|---|
| src/…/request.py | Defines Chat request validation and the Chat-to-Messages and Chat-to-Responses conversion rules. |
| src/…/response.py | Defines Chat SSE frames, native relay checks, and stream aggregation. |
| src/…/tool_calls.py | Defines choice-scoped tool-fragment identity, completion, native frame grouping, and safe recovery. |
| src/…/transport.py | Shows how requests enter the provider, streams run, upstream reads are bounded, and public protocol paths are selected. |
| src/…/openai_stream.py | Shows how OpenAI SDK events receive the shared read deadline and keepalive handling. |
| src/…/stream_read.py | Defines the per-event read boundary used to prevent keepalives from extending a wait forever. |
| src/…/stream_output.py | Defines the shared stream lifecycle and the Messages and Responses output contracts. |
| src/…/tool_calls.py | Explains provider-level fragmented tool-call assembly and recovery. |
| src/…/openai_tool_names.py | Defines stable tool-name aliases at the provider boundary. |
| src/…/profiles.py | Shows how provider differences are expressed without changing the shared transport. |