Ai Token Tracker Python SDK
ai-token-tracker captures outbound LLM traffic and posts ingest envelopes to Ai Token Tracker.
Supports:
- Automatic HTTP interception (
requests,httpxsync/async) - SDK wrapper integration (
begin_llm_callscope)
Requirements
- Python 3.10+
Installation
pip install ai-token-tracker
Optional extras:
pip install ai-token-tracker[requests]
pip install ai-token-tracker[httpx]
pip install ai-token-tracker[all]
Defaults
enable_auto_interception=True
Quick Start (Plain Script)
from ai_token_tracker import (
AiTokenTrackerIngestionClient,
AiTokenTrackerOptions,
AiTokenTrackerSdkClient,
)
ingestion = AiTokenTrackerIngestionClient(
AiTokenTrackerOptions(auth_token="atk_your_key")
)
sdk = AiTokenTrackerSdkClient(ingestion)
scope = sdk.begin_llm_call(
request={"model": "gpt-4.1-mini", "input": "hello"},
additional_custom_filters={"workflow": "quickstart"},
provider_hint="anthropic",
)
try:
provider_response = {"id": "resp_123", "output": [{"type": "output_text", "text": "hi"}]}
scope.complete(provider_response, status_code=200)
except Exception as ex:
scope.fail(ex, status_code=500)
raise
finally:
ingestion.close()
Automatic HTTP Interception
Interception is explicit install + option-gated:
import requests
from ai_token_tracker import (
AiTokenTrackerIngestionClient,
AiTokenTrackerOptions,
install_http_interception,
)
client = AiTokenTrackerIngestionClient(
AiTokenTrackerOptions(
auth_token="atk_your_key",
enable_auto_interception=True,
)
)
install_http_interception(client)
# Classified request is captured and ingested automatically.
requests.post(
"https://api.openai.com/v1/responses",
headers={"Authorization": "Bearer sk_test"},
json={"model": "gpt-4.1-mini", "input": "hello"},
timeout=10,
)
client.close() # unpatches interceptors + shuts down background worker
Scoped Custom Filters For Automatic Interception
Use interception scope to attach custom filters without wrapper integration:
import requests
from ai_token_tracker import (
AiTokenTrackerIngestionClient,
AiTokenTrackerInterceptionScope,
AiTokenTrackerOptions,
install_http_interception,
)
client = AiTokenTrackerIngestionClient(
AiTokenTrackerOptions(auth_token="atk_your_key", enable_auto_interception=True)
)
install_http_interception(client)
scope = AiTokenTrackerInterceptionScope.create({"workflow": "social_post_generation"})
scope.add_custom_filters({"job_id": "job-42", "customer_id": "cust-19"})
try:
requests.post(
"https://api.openai.com/v1/responses",
headers={"Authorization": "Bearer sk_test"},
json={"model": "gpt-4.1-mini", "input": "hello"},
timeout=10,
)
finally:
scope.close()
create(...) opens scope automatically. Call close() when you want to end scope early.
SDK Wrapper Example
from ai_token_tracker import AiTokenTrackerIngestionClient, AiTokenTrackerOptions, AiTokenTrackerSdkClient
ingestion = AiTokenTrackerIngestionClient(AiTokenTrackerOptions(auth_token="atk_your_key"))
tracker = AiTokenTrackerSdkClient(ingestion)
scope = tracker.begin_llm_call(
request={"model": "claude-sonnet-4-6", "max_tokens": 256, "messages": [{"role": "user", "content": "hello"}]},
additional_custom_filters={"tenant": "acme", "job": "summarization"},
provider_hint="anthropic",
)
scope.complete({"id": "msg_123"}, status_code=200)
ingestion.close()
FastAPI Example
from contextlib import asynccontextmanager
from fastapi import FastAPI
from ai_token_tracker import (
AiTokenTrackerIngestionClient,
AiTokenTrackerOptions,
AiTokenTrackerSdkClient,
install_http_interception,
)
ingestion = AiTokenTrackerIngestionClient(
AiTokenTrackerOptions(auth_token="atk_your_key", enable_auto_interception=True)
)
tracker = AiTokenTrackerSdkClient(ingestion)
@asynccontextmanager
async def lifespan(app: FastAPI):
install_http_interception(ingestion)
yield
ingestion.close()
app = FastAPI(lifespan=lifespan)
@app.get("/health")
def health() -> dict[str, str]:
return {"status": "ok"}
Background Worker / Job Pipeline Example
from ai_token_tracker import AiTokenTrackerIngestionClient, AiTokenTrackerOptions, AiTokenTrackerSdkClient
ingestion = AiTokenTrackerIngestionClient(AiTokenTrackerOptions(auth_token="atk_your_key"))
tracker = AiTokenTrackerSdkClient(ingestion)
def run_job(job_id: str, prompt: str) -> None:
scope = tracker.begin_llm_call(
request={"model": "gpt-4.1-mini", "input": prompt},
additional_custom_filters={"job_id": job_id, "pipeline": "nightly"},
provider_hint="anthropic",
)
try:
response = {"id": f"resp_{job_id}", "output": [{"type": "output_text", "text": "done"}]}
scope.complete(response)
except Exception as ex:
scope.fail(ex)
raise
run_job("42", "summarize daily usage")
ingestion.close()
Custom Filters Guidance
additional_custom_filters is key/value metadata attached to each envelope:
- keep keys stable (
tenant,workflow,job_id,environment) - keep values low-cardinality when possible
- avoid putting secrets or full prompt bodies in filters
Verification Checklist
- Create client with valid
auth_token. - For interception, set option flag and call
install_http_interception(client). - Send known LLM request (
/v1/responsesor/chat/completions). - Confirm event appears in AI Token Tracker dashboard.
- Confirm app flow still works if ingest is unavailable (tracking paths are non-throwing).
Public API Summary
AiTokenTrackerOptions(auth_token, enable_auto_interception=True)AiTokenTrackerIngestionClient.track(...) -> TrackResultAiTokenTrackerIngestionClient.track_async(...) -> TrackResultAiTokenTrackerIngestionClient.close()AiTokenTrackerInterceptionScope.create(...),open(),close()AiTokenTrackerSdkClient.begin_llm_call(...) -> CallScopeCallScope.complete(...),CallScope.fail(...)CallScope.complete_async(...),CallScope.fail_async(...)install_http_interception(client),uninstall_http_interception(client)
Metadata
Release files for ai-token-tracker 0.2.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ai_token_tracker-0.2.7.tar.gz | 18.2 kB | Without provenance | Details for ai_token_tracker-0.2.7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ai_token_tracker-0.2.7-py3-none-any.whl | Python 3 | none | any | Details for ai_token_tracker-0.2.7-py3-none-any.whl |
Total release size: 34.7 kB
Release files / ai_token_tracker-0.2.7.tar.gz
| Download URL | ai_token_tracker-0.2.7.tar.gz |
|---|---|
| Size | 18.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7c531831e7ad7353fd38aea134148f02b989414a97de1e1cac566bee60060f2a
|
|
BLAKE2b-256 checksum How to use checksums |
fafeaa23bb249c301c05440d0815b4543b047ec97f932aabe7716c4f6384e1d9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Release files / ai_token_tracker-0.2.7-py3-none-any.whl
| Download URL | ai_token_tracker-0.2.7-py3-none-any.whl |
|---|---|
| Size | 16.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
596338b7a7445543747c55d0000e83f7f26368d8194a5903f1f466f10a9e56cd
|
|
BLAKE2b-256 checksum How to use checksums |
671fb0c63807cbc09d25152defdeb9e45e435b3d8f42ba9aee64f2706cf5c7e7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Security for ai-token-tracker 0.2.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.