Lightweight, framework-agnostic token tracking and LLM cost calculation across providers.
TokenHelm gives you one normalized usage/cost event for every LLM call — OpenAI, Gemini, Anthropic, or Ollama — without locking you into any framework, patching any provider SDK, or ever touching your credentials. It simply observes the response object your own client already returns.
from tokenhelm import TokenHelm
tracker = TokenHelm() # zero-config
response = client.chat.completions.create(...) # your own OpenAI call
event = tracker.track(response) # normalized LLMEvent
print(event.to_dict())
# {'provider': 'openai', 'model': 'gpt-4o', 'input_tokens': 1000,
# 'output_tokens': 500, 'total_tokens': 1500, 'latency': 0.0,
# 'cost': '0.00750', 'timestamp': '...', 'usage_complete': True,
# 'priced': True, 'currency': 'USD'}pip install tokenhelm # core (only dependency: PyYAML)
pip install "tokenhelm[openai]" # + OpenAI extras (for your own client)
pip install "tokenhelm[anthropic]" # + Anthropic
pip install "tokenhelm[gemini]" # + Google Gemini
pip install "tokenhelm[ollama]" # + Ollama
pip install "tokenhelm[all]" # all provider extras
pip install "tokenhelm[dev]" # test/lint toolchainRequires Python 3.11+. The extras only pull in the provider SDKs you call — TokenHelm itself never imports them to read a response.
from tokenhelm import TokenHelm
tracker = TokenHelm()
# 1. Manual tracking — track any completed response
event = tracker.track(response)
# 2. Scoped tracking — collect every event in a block
with tracker.trace() as scope:
response = client.chat.completions.create(...)
scope.track(response)
print(scope.events) # [LLMEvent(...)]
# 3. Choose where events go (any logger, callable, or storage)
from tokenhelm import ConsoleLogger
tracker = TokenHelm(logger=[ConsoleLogger(), lambda e: metrics.push(e.to_dict())])
# 4. Bring your own pricing (file, dict, or a full PricingProvider)
tracker = TokenHelm(pricing="my_rates.yaml")
tracker = TokenHelm(pricing={"openai": {"gpt-4o": {"input": 2.5, "output": 10.0}}})
# 5. Reconfigure later without rebuilding
tracker.configure(currency="EUR")
# 6. Streaming — exactly one event after the stream is exhausted
for chunk in tracker.track_stream(client.chat.completions.create(..., stream=True)):
... # consume chunks as usual
# 7. Async — same API with `async with` / `async for`
async with tracker.trace() as scope:
scope.track(await aclient.chat.completions.create(...))Every tracked request yields the same normalized LLMEvent with the eight mandated
fields — provider, model, input_tokens, output_tokens, total_tokens, latency, cost, timestamp — plus usage_complete / priced status flags. Consumers never see a
provider-specific usage object. Costs use decimal.Decimal (no float drift). Missing usage or
unknown pricing degrade gracefully via the flags — tracking never raises on missing data.
TokenHelm is built around five replaceable extension points; the core depends only on their interfaces, never on a concrete implementation.
┌──────────────────────────────────────────────────────────┐
│ Your Application │
└───────────────────────────┬──────────────────────────────┘
│ track() / trace() / configure()
▼
┌────────────────────┐
│ TokenHelm │ (sdk: client + TraceScope)
└─────────┬──────────┘
▼
┌────────────────────┐
│ TokenTracker │ builds the normalized LLMEvent
└───┬────────────┬───┘
extract usage │ │ compute cost
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ BaseAdapter ① │ │ CostCalculator │
│ OpenAI/Gemini/ │ └────────┬─────────┘
│ Anthropic/Ollama │ ▼
└──────────────────┘ ┌──────────────────┐
│ PricingProvider ② │ (YAML default)
└──────────────────┘
│
▼ emit (tracker is unaware of sinks)
┌────────────────────┐
│ EventDispatcher ③ │
└───┬────────────┬───┘
▼ ▼
┌──────────────┐ ┌──────────────────┐
│ Logger ④ │ │ StorageBackend ⑤ │ (optional)
│ Console/... │ └──────────────────┘
└──────────────┘
Extension points (all public & stable — Constitution Principle VI):
| # | Interface | Default | Swap it to… |
|---|---|---|---|
| ① | BaseAdapter |
OpenAI, Gemini, Anthropic, Ollama | add a new provider |
| ② | PricingProvider |
YamlPricingProvider |
remote/dynamic pricing, AI FinOps |
| ③ | EventDispatcher |
DefaultEventDispatcher |
custom routing/batching/export |
| ④ | Logger |
ConsoleLogger |
JSON/file/metrics/dashboards |
| ⑤ | StorageBackend |
none (opt-in) | in-memory/SQLite/warehouse/analytics |
Dependency direction is strictly one-way (no reverse dependencies):
Application → TokenHelm → TokenTracker → EventDispatcher → Logger / StorageBackend
└────────→ CostCalculator → PricingProvider
└────────→ UsageParser → BaseAdapter
CostCalculator depends only on PricingProvider; TokenTracker emits only through
EventDispatcher. Analytics, dashboards, and FinOps are downstream consumers of LLMEvent
behind these interfaces — they require no change to the core.
All four providers are supported, with streaming and async, in v0.1.0.
| Provider | Status | Usage fields read |
|---|---|---|
| OpenAI | ✅ supported | usage.prompt_tokens / completion_tokens (Chat); input_tokens / output_tokens (Responses) |
| Google Gemini | ✅ supported | usage_metadata.prompt_token_count / candidates_token_count |
| Anthropic | ✅ supported | usage.input_tokens / output_tokens (+ cache token extras) |
| Ollama (local) | ✅ supported | prompt_eval_count / eval_count |
All providers normalize into the same LLMEvent schema — switching providers is a
configuration change, not a code change. Each adapter handles both completed responses and
streaming.
v0.1.0 — Core SDK ✅ (current)
- Track usage and cost across one provider (MVP): cost calculation, normalized event,
scoped
trace(), console logging, graceful degradation. - Provider parity: OpenAI, Gemini, Anthropic, Ollama adapters; identical event shape.
- Output choice:
JSONLogger,FileLogger,InMemoryStorageBackend, fullconfigure()and multi-sink dispatch. - Streaming & async:
track_stream()(one final event), asynctrace(). - Hardening: <5 ms / <20 MB budgets, thread/async isolation suite, docs, packaging.
Beyond v0.1 — each tier is additive on the five extension points; the v0.1 core API does
not change. See ROADMAP.md.
- v0.2 — Analytics SDK (
SQLiteStorageBackend+ usage queries) - v0.3 — Prompt Intelligence (per-prompt/template attribution)
- v0.4 — RAG Intelligence (retrieval-aware accounting)
- v0.5 — AI FinOps (budgets, alerts, remote pricing)
- v1.0 — Enterprise Platform (stabilize the v0.x surface; dashboard, plugins)
Framework-agnostic · provider-independent · zero vendor lock-in · <5 ms overhead · observe-don't-patch · one standardized event · everything replaceable.
See specs/001-core-sdk/ for the constitution, spec, plan, data model, and public API
contract.
Releases follow a documented, automated procedure (Conventional Commits → release-please → Trusted Publishing on PyPI via OIDC). The canonical, end-to-end release procedure is the Go-Live & Release checklist — follow it for every release.
Supporting docs:
docs/releasing.md— how publishing works (TestPyPI → PyPI, OIDC).docs/repository-setup.md— branch protection, required checks, Dependabot, security features.docs/release-checklist.md— per-version quality gates.
Contributors: see CONTRIBUTING.md for the dev workflow, versioning, and
deprecation policy.
MIT