llmtrack-sdk (Python)

LLMtrack records server-side LLM token usage, cost, and request context so teams can understand AI usage in one dashboard.

The PyPI distribution is named llmtrack-sdk, while Python imports use llmtrack_sdk: distribution names can contain hyphens, but import identifiers cannot, and the distinct name also avoids the unrelated llmtrack distribution.

Install

pip install llmtrack-sdk

Quickstart

Create an ingestion key in LLMtrack, save it at ~/.config/llmtrack/api-key, and run:

export LLMTRACK_API_KEY="$(cat ~/.config/llmtrack/api-key)"

import os
from llmtrack_sdk import LLMtrack
tracker = LLMtrack(api_key=os.environ["LLMTRACK_API_KEY"])
tracker.track(provider="openai", model="gpt-5.6-sol", prompt_tokens=241,
              completion_tokens=86, reasoning_tokens=32, feature="support-chat")

Exported Node.js event type

When using the companion Node.js package, import its canonical class (with a lowercase t) and exported event type directly:

import { LLMtrack, type TrackOptions } from 'llmtrack';
const event: TrackOptions = { provider: 'openai', model: 'gpt-5.6-sol', promptTokens: 241, completionTokens: 86 };

Common mistakes

• Class casing: the canonical class is LLMtrack, with a lowercase t. Python also exports LLMTrack as a safety alias, but documentation and examples use LLMtrack.
• Field casing: Python accepts snake_case event fields only (for example, prompt_tokens); an unknown or wrong-cased key causes an unexpected-keyword TypeError, reported through on_error when using track(). Node.js accepts camelCase only and silently drops unknown runtime properties (while TypeScript normally rejects them).
• Provider usage: use from_openai_usage() or from_anthropic_usage() rather than manually copying token counts and cache-accounting conventions.
• Cost: do not supply cost; client-supplied cost is ignored because LLMtrack computes cost server-side.

Provider examples

Both examples call track() immediately after the provider completion and read counts from the official response objects.

OpenAI

import os
from openai import OpenAI
from llmtrack_sdk import LLMtrack, from_openai_usage
openai, tracker = OpenAI(), LLMtrack(api_key=os.environ["LLMTRACK_API_KEY"])
response = openai.chat.completions.create(model="gpt-5.6-sol", messages=[{"role": "user", "content": "Explain why the sky is blue in two sentences."}])
tracker.track(provider="openai", model=response.model, **from_openai_usage(response.usage), feature="science-explainer")

Anthropic

Anthropic includes thinking tokens in output_tokens rather than exposing a separate reasoning-token count, so do not duplicate them in reasoning_tokens.

import os
from anthropic import Anthropic
from llmtrack_sdk import LLMtrack, from_anthropic_usage
anthropic, tracker = Anthropic(), LLMtrack(api_key=os.environ["LLMTRACK_API_KEY"])
response = anthropic.messages.create(model="claude-opus-5", max_tokens=1024, messages=[{"role": "user", "content": "Summarize the benefits of typed APIs."}])
tracker.track(provider="anthropic", model=response.model, **from_anthropic_usage(response.usage), feature="document-summary")

Cache accounting conventions

OpenAI-style usage is inclusive: prompt tokens already include cached input tokens, and completion tokens already include reasoning tokens. Anthropic-style usage is exclusive: input tokens exclude cache reads and writes reported separately. The adapters label these conventions automatically. Set cache_accounting yourself only when the server cannot infer the convention, such as for a gateway or an unrecognised vendor; use exactly inclusive or exclusive.

Fire-and-forget and awaited usage

result = await tracker.track_sync(provider="openai", model="gpt-5.6-sol", prompt_tokens=241,
                                  completion_tokens=86, reasoning_tokens=32, feature="support-chat")

Set enabled=False in tests and local development to make both methods no-ops:

tracker = LLMtrack(api_key=os.environ["LLMTRACK_API_KEY"], enabled=False)

Constructor options

Event fields

The wrapper accepts the following snake-case fields from the IngestRequest contract.

The client validates all token-count fields as non-negative integers, validates cache_accounting, and rejects metadata whose compact UTF-8 JSON serialization exceeds 8192 bytes. The server validates the remaining contract constraints.

Delivery, retries, and idempotency

Each call automatically receives a UUID v4 idempotency key. That key stays stable across retries, preventing double-counting when a stored response is lost. Supply your own stable key to deduplicate separate calls:

tracker.track(provider="openai", model="gpt-5.6-sol", prompt_tokens=241, completion_tokens=86,
              reasoning_tokens=32, feature="support-chat", idempotency_key="9ea0c2ec-7b98-4bc3-9802-20ae6a468a35")

The SDK retries only network failures, timeouts, and HTTP 5xx responses. It never retries HTTP 4xx responses.

Errors

track_sync() raises these errors. track() sends them to on_error and never raises.

Warnings

Troubleshooting

Events are not appearing

A short-lived process can exit before the daemon thread finishes; use await track_sync() in scripts and jobs that must confirm delivery, and inspect its returned API dictionary.

Cost shows 0

Check for UNKNOWN_MODEL or pricing_status: unknown_model. Use the exact response.model returned by the provider so active pricing can match it.

The key is rejected

Inspect LLMtrackError.code: replace invalid/revoked keys, reactivate inactive keys, and confirm the environment variable is available to the server process. Use await track_sync() to inspect the complete exception.

Contributing

Async tests use pytest-asyncio (included in the test and dev extras):

pip install -e 'packages/python[test]'
pytest packages/python/tests

More information

• LLMtrack documentation
• MIT License