Implementation:Helicone Helicone GetMapperType

Knowledge Sources	Helicone
Domains	LLM Observability, Provider Detection, Response Normalization
Last Updated	2026-02-14 00:00 GMT

Overview

Concrete function for determining the correct mapper type based on model name, provider, and request metadata, provided by the llm-mapper package.

Description

getMapperType is a pure function that accepts a model string, a provider identifier, and optional contextual fields (URL path, assistant flag, target URL, request referrer), then returns one of 19 possible MapperType string literals. It applies a prioritized sequence of regex matches and provider checks to classify the request format. A companion function getMapperTypeFromHeliconeRequest wraps it with additional body-level checks for AI Gateway requests, assistant threads, realtime sessions, and custom event types (vector_db, tool, data).

Usage

Call getMapperType when you have extracted model/provider metadata and need to determine which mapper to dispatch to. Call getMapperTypeFromHeliconeRequest when you have a full HeliconeRequest object and want the complete detection pipeline including body-level markers.

Code Reference

Source Location

• Repository: Helicone
• File: packages/llm-mapper/utils/getMapperType.ts

Signature

export const getMapperType = ({
  model,
  provider,
  path,
  isAssistant,
  targetUrl,
  requestReferrer,
}: {
  model: string;
  provider: Provider;
  path?: string | null;
  isAssistant?: boolean;
  targetUrl?: string | null;
  requestReferrer?: string | null;
}): MapperType

export const getMapperTypeFromHeliconeRequest = (
  heliconeRequest: HeliconeRequest,
  model: string
) => MapperType

Import

import { getMapperType, getMapperTypeFromHeliconeRequest } from "@helicone-package/llm-mapper/utils/getMapperType";

I/O Contract

Inputs (getMapperType)

Name	Type	Required	Description
model	string	Yes	The model identifier string (e.g. "gpt-4", "claude-3-opus", "gemini-1.5-pro")
provider	Provider	Yes	The provider enum value (e.g. "OPENAI", "ANTHROPIC", "GOOGLE", "CUSTOM", "GROQ", "TOGETHER", "OPENROUTER", etc.)
path	null	No	The request URL path, used to detect specific API endpoints (e.g. contains "oai2ant" or "/v1/response")
isAssistant	boolean	No	Whether the request is an OpenAI Assistant API request (detected via metadata/assistant_id fields)
targetUrl	null	No	The full target URL; used to detect Google-via-OpenAI-compatible endpoints and OpenAI Responses API
requestReferrer	null	No	The request referrer; used to detect AI Gateway requests

Inputs (getMapperTypeFromHeliconeRequest)

Name	Type	Required	Description
heliconeRequest	HeliconeRequest	Yes	Full Helicone request object including request_body, response_body, provider, and metadata
model	string	Yes	The model identifier string

Outputs

Name	Type	Description
(return)	MapperType	A string literal union: "openai-chat", "openai-response", "anthropic-chat", "gemini-chat", "llama-chat", "vercel-chat", "black-forest-labs-image", "openai-assistant", "openai-image", "openai-moderation", "openai-embedding", "openai-instruct", "openai-realtime", "ai-gateway-chat", "ai-gateway-responses", "vector-db", "tool", "data", or "unknown"

Detection Rules Summary

The following table summarizes the priority-ordered detection rules in getMapperType:

Priority	Condition	Result
1	Google provider + targetUrl contains "chat/completions"	"openai-chat"
2	Provider is VERCEL	"vercel-chat"
3	Model is falsy or non-string	"openai-chat" (default)
4	targetUrl contains "/v1/response" + OPENAI provider	"openai-response"
5	Model contains "deepseek"	"openai-chat"
6	Model is "vector_db", starts with "tool:", or "data:"	"vector-db", "tool", "data"
7	Model matches /^gpt-3\.5-turbo-instruct/	"openai-instruct"
8	Model is "black-forest-labs/FLUX.1-schnell"	"black-forest-labs-image"
9	Model matches GPT-4/3.5 patterns, or provider is OPENROUTER/CUSTOM/GROQ/TOGETHER	"openai-chat" (with claude exception returning "anthropic-chat")
10	Model starts with or contains "claude"/"anthropic", or provider is ANTHROPIC/AWS	"anthropic-chat"
11	Provider is NVIDIA	"openai-chat"
12	Model matches Llama pattern or provider is LLAMA	"llama-chat"
13	isAssistant is true	"openai-assistant"
14	Model contains "gemini" or provider is GOOGLE	"gemini-chat" (unless OPENAI provider)
15	Model is "dall-e-2", "dall-e-3", or starts with "gpt-image-1"	"openai-image"
16	Model matches text-moderation pattern	"openai-moderation"
17	Model matches /^text-embedding/	"openai-embedding"
18	Fallback	"openai-chat"

Usage Examples

Basic Usage

import { getMapperType } from "@helicone-package/llm-mapper/utils/getMapperType";

// OpenAI GPT-4 request
const type1 = getMapperType({
  model: "gpt-4-turbo",
  provider: "OPENAI",
});
// Returns: "openai-chat"

// Anthropic Claude request
const type2 = getMapperType({
  model: "claude-3-opus-20240229",
  provider: "ANTHROPIC",
});
// Returns: "anthropic-chat"

// Google Gemini request
const type3 = getMapperType({
  model: "gemini-1.5-pro",
  provider: "GOOGLE",
});
// Returns: "gemini-chat"

// OpenAI Responses API
const type4 = getMapperType({
  model: "gpt-4o",
  provider: "OPENAI",
  targetUrl: "https://api.openai.com/v1/response",
});
// Returns: "openai-response"

Full Request Detection

import { getMapperTypeFromHeliconeRequest } from "@helicone-package/llm-mapper/utils/getMapperType";

const mapperType = getMapperTypeFromHeliconeRequest(heliconeRequest, heliconeRequest.model);
// Checks body-level markers first, then falls back to getMapperType

Related Pages

Implements Principle

• Principle:Helicone_Helicone_Mapper_Type_Detection