Metadata-Version: 2.4
Name: kalaa
Version: 1.0.0
Summary: Drop-in AI cost tracking for Python. Auto-instruments OpenAI, Anthropic, and Gemini with zero code at the call site.
License: MIT
Project-URL: Homepage, https://kalaa.cc
Project-URL: Repository, https://github.com/YOUR_ORG/kalaa-python
Keywords: ai,llm,cost-tracking,openai,anthropic,gemini,observability,monitoring,flask,fastapi
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: mutagen>=1.47
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.25; extra == "anthropic"
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0; extra == "gemini"
Dynamic: license-file

# 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

```bash
pip install kalaa
```

## Setup

```python
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:

```python
# 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:

```python
kalaa.set_user(current_user.id)
```

## Background jobs / cron

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

```python
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
