Anthropic Messages API

Relevant source files

The following files were used as context for generating this wiki page:

• c/openai_server.py
• CHANGELOG.md
• README.md
• c/tools/diag_harness.py
• web/src/App.tsx

The Anthropic Messages API provides a compatibility layer that translates Anthropic-formatted HTTP requests into internal engine commands. This system allows clients designed for Anthropic models, such as Claude Code, to interface directly with the Colibrì engine without a shim. The translation layer handles request mapping, Server-Sent Events (SSE) formatting, and protocol-specific features like thinking blocks and keepalive pings.

Sources: c/openai_server.py:539-544, CHANGELOG.md:27-33

Architecture and Data Flow

The Anthropic Messages API operates as a translation layer within openai_server.py. It does not create a new inference path; instead, it rewrites the Anthropic-shaped request into an OpenAI-compatible body that the existing scheduling and generation logic understands. The response and SSE streams are then formatted back into the Anthropic specification.

Request Pipeline

The server processes Anthropic requests through the following stages:

1. Entry Point: The APIHandler receives a POST request at /v1/messages.
2. Authentication: The handler validates the request using either x-api-key or standard Bearer tokens.
3. Translation: The anthropic_to_openai function maps Anthropic content blocks and system prompts to a standard message array.
4. Inference: The engine processes the translated prompt using existing schedulers and KV cache slots.
5. Response Formatting: The server returns a JSON response or an SSE stream following the Anthropic event protocol.

Sources: c/openai_server.py:875-877, c/openai_server.py:970-985, CHANGELOG.md:30-33

The diagram shows the transformation of Anthropic requests into engine-compatible formats and the subsequent response re-formatting. Sources: c/openai_server.py:970-1123

Request Translation Logic

The API converts Anthropic-specific structures into internal representations. This include mapping top-level system strings to system messages and decomposing content arrays.

Supported Content Blocks

Anthropic Block Type	OpenAI/Internal Mapping	Description
text	content: str	Standard text content.
thinking	reasoning_content: str	Used for model reasoning/CoT.
tool_use	tool_calls: list	Maps to function call identifiers and arguments.
tool_result	role: tool	Maps tool outputs back to the assistant turn.

Sources: c/openai_server.py:612-658

Message Mapping Behavior

• System Prompts: Top-level system strings or blocks are inserted as the first message with the system role.
• Role Restrictions: Only user and assistant roles are accepted within the messages array.
• Tool Sequencing: Tool results are sequenced to precede the user's next text block to satisfy the underlying prompt template requirements.

Sources: c/openai_server.py:601-665

Streaming and SSE Events

For streaming requests, the API implements the full Anthropic named-event SSE sequence. This includes specific event types for message lifecycle and content generation.

Event Sequence

1. message_start: Initializes the message ID and role.
2. content_block_start: Signals the start of a text or thinking block.
3. content_block_delta: Streams incremental updates for text, thinking, or JSON input.
4. content_block_stop: Terminates a specific block.
5. message_delta: Provides final usage stats and stop reasons.
6. message_stop: Final event in the stream.

Sources: c/openai_server.py:1056-1123

Protocol Keepalives

Unlike the OpenAI path which uses reasoning deltas for keepalives, the Anthropic path uses a native ping event. This prevents client timeouts during long prefill operations by sending a {"type": "ping"} event every 10 seconds of inactivity.

Sources: c/openai_server.py:1049-1054, CHANGELOG.md:31-32

The sequence diagram illustrates the use of the protocol-native ping during long prefill phases. Sources: c/openai_server.py:1049-1123

Thinking and Reasoning

The API supports Anthropic's extended thinking blocks. When thinking is enabled in the request, the server utilizes the ThinkingStreamSplit class to separate reasoning from the final answer in the engine output.

• GLM Parsing: For GLM-style models, the server detects <think> and </think> tags.
• Signature: Reasoning blocks include a signature defined as colibri-local.
• Safety: If the engine budget is exhausted before a thinking block is closed, the server automatically closes the block to ensure a valid Anthropic response.

Sources: c/openai_server.py:542, c/openai_server.py:560-590, c/openai_server.py:1099-1102

Limitations and Validation

The implementation explicitly refuses parameters that are not currently supported by the Colibrì engine to prevent silent failures.

Parameter	Validation Status	Reason
stop_sequences	Refused	Not yet supported for custom sequences.
top_k	Refused	Internal sampler focuses on top_p.
thinking (non-object)	Error 400	Must be an object with type.
max_tokens (missing)	Error 400	Required by Anthropic specification.

Sources: c/openai_server.py:972-985

Conclusion

The Anthropic Messages API integrates the Colibrì engine into the broader LLM ecosystem by providing a high-fidelity translation layer. By managing the complexities of thinking blocks, tool sequence mapping, and protocol-specific SSE events, it enables seamless use of the engine with advanced development tools like Claude Code while maintaining the performance benefits of the underlying C-based inference runtime.

Sources: CHANGELOG.md:27-36, c/openai_server.py:539-555