atomiclens 0.1.0

Atomic Lens Python SDK. OpenTelemetry-native auto-instrumentation for LLM agents.

atomiclens

OpenTelemetry-native observability for LLM agents. One init() call auto-instruments your OpenAI, Anthropic, and Hugging Face calls and exports priced, attributed spans (tokens, USD cost, latency, model) to any OTLP endpoint, including the open-source Atomic Lens backend and dashboard.

pip install atomiclens            # core
pip install "atomiclens[openai]"  # + OpenAI auto-instrumentation
pip install "atomiclens[all]"     # OpenAI + Anthropic + Hugging Face

Quickstart

import atomiclens

atomiclens.init(service_name="my-agent", otlp_endpoint="http://localhost:4318")

# Every OpenAI / Anthropic / Hugging Face call is now traced with token
# counts and USD cost, with no other code change.
from openai import OpenAI

client = OpenAI()
client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)

Streaming calls are handled too: stream_options.include_usage is injected so token usage and cost are captured even when you stream.

Attribution

Tag spans with the workflow, agent, user, and team they belong to so the dashboard can break cost down by any of them:

from atomiclens import workflow, agent, set_user, set_team

set_user("user_123")
set_team("growth")

with workflow("weekly-report"):
    summarize()          # spans inherit workflow="weekly-report"

@agent("researcher")
def research(topic): ...  # spans inherit agent_name="researcher"

Configuration

init() reads sensible defaults from the environment so you can configure it without touching code:

Env var	Purpose
ATOMICLENS_OTLP_ENDPOINT	Where spans are exported (defaults to http://localhost:4318)
ATOMICLENS_API_KEY	Sent as the ingest key to a protected backend

service_name is a required argument to init(). init() is idempotent, so calling it more than once is safe (pass force=True to reconfigure).

Framework integrations

LangChain and LlamaIndex callback handlers are available as optional extras (pip install "atomiclens[langchain]" / "atomiclens[llamaindex]").

License

Apache-2.0. Source and the full self-hostable backend + dashboard live at github.com/Worldwideblake/atomic-lens.