Implementation:Explodinggradients Ragas HeliconeSingleton Class

Metadata	Value
Source	src/ragas/integrations/helicone.py (Lines 11-101)
Domains	Integration, Observability
Last Updated	2026-02-10

Overview

A singleton dataclass that manages Helicone observability proxy configuration, generating HTTP headers for routing LLM requests through the Helicone platform with extensive customization support.

Description

HeliconeSingleton implements the singleton pattern via __new__ to ensure only one configuration instance exists throughout the application. It is a @dataclass with a rich set of optional fields corresponding to Helicone proxy headers:

• Authentication: api_key is used to set the Helicone-Auth bearer token header.
• Routing: base_url (defaults to https://oai.helicone.ai), target_url, openai_api_base.
• Request metadata: request_id, model_override, prompt_id, user_id.
• Session management: session_id, session_path, session_name.
• Reliability: fallbacks, rate_limit_policy, retry_enabled.
• Privacy/security: omit_response, omit_request, moderations_enabled, llm_security_enabled.
• Caching: cache_enabled, cache_config (a CacheConfig with ttl and maxsize).
• Analytics: posthog_key, posthog_host.
• Custom properties: custom_properties dict, mapped to Helicone-Property-{key} headers.

The default_headers() method builds a dictionary of HTTP headers from all configured fields. Boolean fields are converted to lowercase string representations. The is_enabled property returns True when an API key is set.

A module-level instance helicone_config is provided as the pre-instantiated singleton.

Usage

Use this class when you want to route Ragas LLM calls through the Helicone proxy for observability, caching, rate limiting, or security monitoring. Configure the singleton before running evaluations to automatically apply Helicone headers to outgoing requests.

Code Reference

Source Location

Item	Detail
File	src/ragas/integrations/helicone.py
Lines	11-101
Module	ragas.integrations.helicone

Class Signature

@dataclass
class HeliconeSingleton:
    api_key: Optional[str] = None
    base_url: Optional[str] = "https://oai.helicone.ai"
    cache_config: Optional[CacheConfig] = None
    target_url: Optional[str] = None
    openai_api_base: Optional[str] = None
    request_id: Optional[str] = None
    model_override: Optional[str] = None
    prompt_id: Optional[str] = None
    user_id: Optional[str] = None
    fallbacks: Optional[str] = None
    rate_limit_policy: Optional[str] = None
    session_id: Optional[str] = None
    session_path: Optional[str] = None
    session_name: Optional[str] = None
    posthog_key: Optional[str] = None
    posthog_host: Optional[str] = None
    omit_response: Optional[bool] = None
    omit_request: Optional[bool] = None
    cache_enabled: Optional[bool] = None
    retry_enabled: Optional[bool] = None
    moderations_enabled: Optional[bool] = None
    llm_security_enabled: Optional[bool] = None
    stream_force_format: Optional[bool] = None
    custom_properties: Dict[str, str] = field(default_factory=dict)

Import

from ragas.integrations.helicone import helicone_config

I/O Contract

default_headers()

Direction	Name	Type	Description
Input	(self)	HeliconeSingleton	The singleton instance with configured fields
Output	(return)	Dict[str, Any]	Dictionary of HTTP headers for the Helicone proxy

is_enabled (property)

Direction	Name	Type	Description
Output	(return)	bool	True if api_key is not None

Key Header Mappings

Field	Header Name	Type
api_key	Helicone-Auth	Bearer token
target_url	Helicone-Target-URL	String
session_id	Helicone-Session-Id	String
cache_enabled	Helicone-Cache-Enabled	Boolean (lowercase)
retry_enabled	Helicone-Retry-Enabled	Boolean (lowercase)
custom_properties	Helicone-Property-{key}	String per key

Usage Examples

Basic Configuration

from ragas.integrations.helicone import helicone_config

# Configure the singleton with your Helicone API key
helicone_config.api_key = "sk-helicone-..."

# Check if Helicone is enabled
if helicone_config.is_enabled:
    headers = helicone_config.default_headers()
    print(headers)
    # {"Helicone-Auth": "Bearer sk-helicone-..."}

Full Configuration with Caching and Sessions

from ragas.integrations.helicone import helicone_config, CacheConfig

# Configure Helicone with caching and session tracking
helicone_config.api_key = "sk-helicone-..."
helicone_config.cache_enabled = True
helicone_config.cache_config = CacheConfig(ttl=3600, maxsize=500)
helicone_config.session_id = "eval-session-001"
helicone_config.session_name = "RAG Evaluation Run"
helicone_config.user_id = "evaluator-1"

# Add custom properties for filtering in Helicone dashboard
helicone_config.custom_properties = {
    "environment": "staging",
    "eval_type": "faithfulness",
}

headers = helicone_config.default_headers()
# Headers will include all configured values

Related Pages

• OpikTracer Class - Another observability integration for logging evaluation traces
• LiteLLMStructuredLLM Class - LLM wrapper that can be used with Helicone proxy routing
• EvaluatorChain Class - LangChain chain wrapper whose LLM calls can be routed through Helicone