kalaa 1.0.0

Drop-in AI cost tracking for Python. Auto-instruments OpenAI, Anthropic, and Gemini with zero code at the call site.

kalaa

Drop-in AI cost tracking for Python. Patches the OpenAI, Anthropic, and Gemini client libraries at the class level, so every client you create — before or after observe(), sync or async — is already instrumented.

Install

pip install kalaa

Setup

import kalaa
kalaa.observe()
app = kalaa.init_app(app)   # auto-detects Flask vs. FastAPI

That's it. Put KALAA_KEY=cm_live_xxx in your environment and every OpenAI, Anthropic, and Gemini call your app makes from here on is tracked automatically — including the user who made the request, with zero extra code, if you're running Flask or FastAPI.

If init_app doesn't recognize your setup, wire the right middleware directly:

# Flask / any WSGI app:
app.wsgi_app = kalaa.wsgi_middleware(app.wsgi_app)

# FastAPI / Starlette / any ASGI app:
app = kalaa.asgi_middleware(app)

Tagging a user manually

Automatic detection covers most setups (reads X-User-Id, a decoded JWT, or a client-side anonymous id). If yours doesn't fit that shape:

kalaa.set_user(current_user.id)

Background jobs / cron

No request to hang a route off of, so give it a label instead:

with kalaa.with_context("nightly-digest"):
    run_the_job()

What's tracked automatically

• OpenAI: chat completions, sync and async, including streaming
• Anthropic: messages, sync and async, including streaming
• Gemini: generate_content, sync and async (via the current google.genai package — the older google.generativeai package is deprecated and not supported)
• Whisper/audio transcription duration, read from the file itself and parsed in an isolated subprocess with a timeout — a malformed file can never hang your app, only cost a few seconds and an unmeasured duration

Configuration

Option	Env var	Default
key	KALAA_KEY	—
endpoint	KALAA_ENDPOINT	https://api.kalaa.cc/api/ingest
env	KALAA_ENV	production
debug	KALAA_DEBUG=1	false

Failure behavior

This package never touches a database and never sits in the path of your AI calls. If the ingest endpoint is unreachable, events are buffered and retried on the next flush cycle — your app is never blocked or crashed by a tracking failure.

License

MIT