Principle:Helicone Helicone Mapper Type Detection
| Knowledge Sources | |
|---|---|
| Domains | LLM Observability, Provider Detection, Response Normalization |
| Last Updated | 2026-02-14 00:00 GMT |
Overview
Mapper Type Detection is the process of determining which provider-specific mapper should handle parsing a given LLM request/response pair, based on model name, provider identifier, URL path, and other contextual signals.
Description
When Helicone intercepts LLM traffic from many different providers (OpenAI, Anthropic, Google Gemini, Llama, Groq, Together, etc.), it must first identify the correct normalization pathway before any parsing can begin. Mapper Type Detection solves this classification problem by examining a combination of heuristics: the model name string (e.g., starts with "claude" for Anthropic, contains "gemini" for Google), the declared provider enum, the request URL path, and special markers like assistant IDs or realtime session objects. The result is a MapperType string such as "openai-chat", "anthropic-chat", "gemini-chat", or one of 19 total mapper types.
The detection logic handles edge cases such as: Google provider using OpenAI-compatible chat/completions endpoints (returns "openai-chat"), Claude models served through a CUSTOM provider, DeepSeek models that use the OpenAI format, special request body markers like _type: "vector_db" or _type: "tool", and AI Gateway requests that may carry a bodyMapping field to select the correct normalization path.
Usage
Use Mapper Type Detection whenever a raw LLM request/response needs to be normalized into Helicone's unified LlmSchema. It is the first step in the LLM Response Normalization pipeline, invoked before any request or response parsing. It is also used when displaying request details in the dashboard, computing cost, or running analytics across heterogeneous provider data.
Theoretical Basis
Mapper Type Detection follows a chain-of-responsibility pattern implemented as a prioritized cascade of conditional checks. The approach is intentionally rule-based rather than schema-inference-based because:
- Provider APIs evolve independently -- new models may appear under existing providers but use different formats (e.g., OpenAI Responses API vs. Chat Completions API).
- Model names encode provider identity -- by convention, model strings like
"claude-3-opus"or"gemini-1.5-pro"reliably indicate the originating provider's format. - URL path overrides -- when a request is routed through a custom proxy or AI gateway, the URL path (e.g.,
/v1/response) can be a stronger signal than the model name. - Fallback to OpenAI -- since OpenAI's Chat Completions format is the most common, the system defaults to
"openai-chat"when no other rule matches, ensuring graceful degradation.
The two-level detection approach (first getMapperTypeFromHeliconeRequest checking body-level markers, then getMapperType applying model/provider heuristics) allows separation between application-level signals (AI gateway body mapping, assistant IDs, realtime sessions) and format-level signals (model name patterns, provider enums).
The resulting MapperType is a discriminated union of 19 string literal types that serves as the dispatch key for the downstream mapper registry.