Principle:Helicone Helicone Request Parsing
| Knowledge Sources | |
|---|---|
| Domains | LLM Observability, Response Normalization, Data Pipeline |
| Last Updated | 2026-02-14 00:00 GMT |
Overview
Request Parsing is the master orchestration step that dispatches raw LLM request/response pairs to provider-specific mappers and produces a unified, sanitized MappedLLMRequest object.
Description
After Mapper Type Detection identifies which provider format a request uses, Request Parsing takes over as the central dispatch layer. It looks up the correct mapper function from a registry of 19+ provider-specific mappers, invokes it with the raw request body, response body, status code, and model name, then wraps the result in a complete MappedLLMRequest structure that includes the parsed schema, preview text, raw data, and Helicone metadata (tokens, cost, latency, user, custom properties, etc.).
The process also includes a sanitization pass that ensures all message content is a proper string (stringifying non-string content), truncates preview text to a maximum of 1,000 characters, and formats error messages as pretty-printed JSON. This guarantees that downstream consumers (dashboard UI, analytics queries, export pipelines) receive clean, consistent data regardless of the original provider format.
Usage
Use Request Parsing whenever you need the fully normalized representation of an LLM interaction. This is the primary entry point for the normalization pipeline, called from:
- The Jawn backend when processing logged requests for storage and display
- The web frontend when rendering request detail views
- Analytics pipelines that need structured access to messages, tools, and model parameters
- The convenience function
heliconeRequestToMappedContentwhich chains mapper type detection and content mapping in a single call
Theoretical Basis
Request Parsing implements the Strategy pattern with a static registry. The MAPPERS record maps each MapperType to its corresponding mapper function, making the dispatch O(1) by key lookup. Each mapper function conforms to the MapperFn<T, K> interface, accepting typed request/response bodies and returning an LlmSchema plus an LLMPreview.
The design separates concerns into three layers:
- Dispatch layer (
getMappedContent) -- selects and invokes the mapper, handles errors gracefully by producing a fallback schema with the error message. - Metadata extraction (
metaDataFromHeliconeRequest) -- maps database-level fields (tokens, cost, latency, feedback, scores) into the structuredHeliconeMetadatatype. - Sanitization layer (
sanitizeMappedContent) -- normalizes message content types, truncates previews, and formats error messages.
Error handling is defensive: if a mapper throws an exception, the dispatch layer catches it and produces a minimal schema containing the error message rather than propagating the failure. This ensures the normalization pipeline never crashes on malformed provider data.
The preview system provides both truncated strings (for list views) and lazy full-text accessors (fullRequestText / fullResponseText) that concatenate all messages on demand, avoiding unnecessary computation for list-level rendering.