helicone

library1.0.14pypypi✓ verified 26d ago

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.

llm-agents observability

# No pip install required for core functionality

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HELICONE

helicone

llm-agentspythonv1.0.14

Install

2.6s avg

Import

—

Disk

109MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v? · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 74MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.6s · import 0.000s · 145MB

109MB installed

● package 109MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

No SDK import required

✓ # Just override base_url on your existing OpenAI/Anthropic client

✗ import helicone; helicone.instrument()

There is no helicone.instrument() or @helicone.trace decorator. The integration is entirely at the HTTP transport level.

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"]}', } )

Debug

Known issues

gotchaThere 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.

affects: all

gotchaAll 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.

affects: all

gotchaHelicone 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.

affects: all

gotchaPrompt 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.

affects: all

breakingThe `openai` Python package is a core dependency for integrating with OpenAI's API via Helicone. It must be installed separately in your environment.

fix

Ensure the `openai` library is installed by running `pip install openai`.

affects: all

breakingThe script fails with a 'ModuleNotFoundError: No module named 'openai''. This error occurs when the 'openai' Python package, required to interact with the OpenAI API, has not been installed in the environment.

fix

Install the 'openai' package using pip: `pip install openai`. Ensure all necessary dependencies are installed before running the script.

affects: all

Upgrade

Version history

1.0.14latest on PyPI · released Nov 3, 2023

Audit

Dependencies

No dependency data recorded yet.

Agent activity

30 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/helicone/helicone ↗

packagehttps://pypi.org/project/helicone/ ↗

homepagehttps://www.helicone.ai ↗