Helicone

helicone-helpers 1.0.3 (optional stub) · active · verified Sat Feb 28

Open-source LLM observability platform using a proxy-based architecture. Unlike LangSmith or Langfuse, Helicone requires NO Python SDK install for core tracing — it works by routing requests through its AI gateway (https://ai-gateway.helicone.ai) via a base_url override on the OpenAI/Anthropic client. All logging happens at the proxy layer. The 'helicone' PyPI package (helicone-helpers) is a thin optional helper with minimal functionality. Primary integration is via HTTP headers and base_url, not a Python library.

Warnings

gotcha There is no meaningful Python package to install. The 'helicone' and 'helicone-helpers' PyPI packages are thin stubs with minimal utility. Most Helicone documentation and features are implemented via base_url + HTTP headers, not Python code. Searching PyPI for 'helicone' and expecting a rich SDK like LangSmith or Langfuse will lead to confusion.
Fix: Do not expect a Python instrumentation library. Helicone's Python integration is: (1) change base_url to https://ai-gateway.helicone.ai, (2) add Helicone-Auth header.
gotcha All LLM requests route through Helicone's cloud proxy. This adds ~10ms latency (Cloudflare Workers) and means all prompt/response content passes through Helicone's infrastructure. Not suitable for environments with strict data residency requirements without the self-hosted option.
Fix: For data residency requirements, use Helicone self-hosted (Docker/Helm) and point base_url at your own instance. EU users: check if the EU region endpoint satisfies GDPR requirements.
gotcha Helicone headers are silently ignored if misspelled or if the base_url is wrong. For example, passing the Helicone-Auth header but keeping the original OpenAI base_url sends the header directly to OpenAI — no error, no tracing, and OpenAI ignores the unknown header.
Fix: Verify the gateway is active by checking your Helicone dashboard after the first request. Confirm base_url is set AND Helicone-Auth header is present.
gotcha Prompt caching via Helicone-Cache-Enabled returns cached responses that bypass your LLM provider entirely. In development/testing, this can cause confusing stale results. The cache key is based on the full request body — small prompt changes bypass the cache.
Fix: Disable caching in dev/test by omitting the Helicone-Cache-Enabled header or setting it to 'false'. Enable only in production for cost savings.

Install

# No pip install required for core functionality Core tracing — base_url change only
pip install helicone-helpers Optional thin helper package (minimal utility)

Imports

No SDK import required
```
# Just override base_url on your existing OpenAI/Anthropic client
```
There is no helicone.instrument() or @helicone.trace decorator. The integration is entirely at the HTTP transport level.

Quickstart

Helicone's entire Python integration is a base_url change. No import, no decorator, no SDK call. Features like caching, rate limiting, user tracking, and prompt versioning are all controlled via HTTP headers added to default_headers.

import os
import openai

# Core integration: change base_url, add auth header
# No pip install needed beyond openai
client = openai.OpenAI(
    api_key=os.environ['OPENAI_API_KEY'],
    base_url='https://ai-gateway.helicone.ai/openai/v1',
    default_headers={
        'Helicone-Auth': f'Bearer {os.environ["HELICONE_API_KEY"]}',
    }
)

response = client.chat.completions.create(
    model='gpt-4o',
    messages=[{'role': 'user', 'content': 'Hello!'}]
)
# Request is now logged in your Helicone dashboard

# Add metadata via headers
client_with_metadata = openai.OpenAI(
    api_key=os.environ['OPENAI_API_KEY'],
    base_url='https://ai-gateway.helicone.ai/openai/v1',
    default_headers={
        'Helicone-Auth': f'Bearer {os.environ["HELICONE_API_KEY"]}',
        'Helicone-User-Id': 'user-123',           # per-user tracking
        'Helicone-Session-Id': 'session-abc',      # session grouping
        'Helicone-Cache-Enabled': 'true',          # response caching
    }
)

# Anthropic integration
import anthropic
client_anthropic = anthropic.Anthropic(
    api_key=os.environ['ANTHROPIC_API_KEY'],
    base_url='https://ai-gateway.helicone.ai/anthropic',
    default_headers={
        'Helicone-Auth': f'Bearer {os.environ["HELICONE_API_KEY"]}',
    }
)

view raw JSON →