Implementation:BerriAI Litellm Core Helpers

Attribute	Value
Sources	litellm/litellm_core_utils/core_helpers.py
Domains	Utilities, Data Transformation, Response Processing, Safety
last_updated	2026-02-15 16:00 GMT

Overview

The Core Helpers module provides foundational utility functions used across LiteLLM for finish reason mapping, metadata extraction, safe division, deep copying, response header processing, and parameter filtering.

Description

This module is a collection of small, focused helper functions that serve as building blocks for LiteLLM's request/response pipeline:

Finish Reason Mapping:

• map_finish_reason() normalizes provider-specific finish reasons (Anthropic's end_turn, Vertex AI's STOP, Cohere's COMPLETE, etc.) to OpenAI-compatible values (stop, length, content_filter, tool_calls).

Metadata Handling:

• get_litellm_metadata_from_kwargs() extracts LiteLLM metadata from request kwargs, preferring litellm_metadata over legacy metadata.
• get_metadata_variable_name_from_kwargs() determines which metadata key name to use.
• _get_parent_otel_span_from_kwargs() locates the parent OpenTelemetry span from various possible locations in kwargs.

Safe Operations:

• safe_divide() and safe_divide_seconds() prevent zero-division errors.
• safe_deep_copy() performs per-key deep copying with fallback for unpicklable objects (OTEL spans, locks), temporarily removing and restoring litellm_parent_otel_span.
• filter_exceptions_from_params() recursively removes Exception and callable objects from data structures to prevent deepcopy/serialization failures.

Response Processing:

• process_response_headers() normalizes provider response headers into an OpenAI-compatible format with llm_provider- prefixed raw headers.
• remove_index_from_tool_calls() strips the index field from tool call dicts in messages.
• preserve_upstream_non_openai_attributes() copies provider-specific fields from streaming chunks.
• reconstruct_model_name() rebuilds the full model name with provider prefix for logging.
• filter_internal_params() removes LiteLLM internal parameters (e.g., MCP-related) from dicts before sending to providers.

Usage

Import individual helpers as needed:

from litellm.litellm_core_utils.core_helpers import map_finish_reason, safe_deep_copy

Code Reference

Source Location

/litellm/litellm_core_utils/core_helpers.py (424 lines)

Key Functions

Function	Signature	Purpose
map_finish_reason	def map_finish_reason(finish_reason: str) -> str	Maps provider finish reasons to OpenAI format
safe_divide	def safe_divide(numerator, denominator, default=0) -> Union[int, float]	Division with zero-safe fallback
safe_divide_seconds	def safe_divide_seconds(seconds, denominator, default=None) -> Optional[float]	Division for time-per-token calculations
safe_deep_copy	def safe_deep_copy(data) -> Any	Deep copy with fallback for unpicklable objects
get_litellm_metadata_from_kwargs	def get_litellm_metadata_from_kwargs(kwargs: dict) -> dict	Extracts metadata from request kwargs
process_response_headers	def process_response_headers(response_headers: Union[httpx.Headers, dict]) -> dict	Normalizes response headers to OpenAI format
remove_index_from_tool_calls	def remove_index_from_tool_calls(messages: Optional[List]) -> None	Strips index from tool call dicts
filter_exceptions_from_params	def filter_exceptions_from_params(data: Any, max_depth: int = 20) -> Any	Recursively removes Exception/callable objects
filter_internal_params	def filter_internal_params(data: dict, additional_internal_params: Optional[set] = None) -> dict	Removes LiteLLM internal params before API calls
reconstruct_model_name	def reconstruct_model_name(model_name: str, custom_llm_provider: Optional[str], metadata: dict) -> str	Rebuilds full model name with provider prefix

Import

from litellm.litellm_core_utils.core_helpers import (
    map_finish_reason,
    safe_deep_copy,
    get_litellm_metadata_from_kwargs,
    process_response_headers,
    filter_internal_params,
)

I/O Contract

Inputs (map_finish_reason)

Parameter	Type	Description
finish_reason	str	Provider-specific finish reason string (e.g., "end_turn", "STOP", "MAX_TOKENS")

Outputs (map_finish_reason)

Return	Type	Description
Mapped reason	str	OpenAI-compatible finish reason (e.g., "stop", "length", "tool_calls")

Usage Examples

from litellm.litellm_core_utils.core_helpers import (
    map_finish_reason,
    safe_deep_copy,
    get_litellm_metadata_from_kwargs,
)

# Map Anthropic finish reason to OpenAI format
reason = map_finish_reason("end_turn")  # returns "stop"
reason = map_finish_reason("tool_use")  # returns "tool_calls"
reason = map_finish_reason("MAX_TOKENS")  # returns "length"

# Safe division for tokens per second
from litellm.litellm_core_utils.core_helpers import safe_divide_seconds
tps = safe_divide_seconds(seconds=2.5, denominator=100)  # 0.025 seconds per token

# Deep copy request data safely (handles OTEL spans)
copied_data = safe_deep_copy(request_kwargs)

# Extract metadata
metadata = get_litellm_metadata_from_kwargs(kwargs)
api_key_hash = metadata.get("user_api_key_hash")

Related Pages

• BerriAI_Litellm_Streaming_Chunk_Builder - uses map_finish_reason and other helpers
• BerriAI_Litellm_Logging_Setup - provides verbose_logger used for error reporting
• BerriAI_Litellm_Constants - defines OPENAI_FINISH_REASONS list