Metadata-Version: 2.4
Name: tokentifyai-usagemeter
Version: 0.1.0
Summary: Out-of-band AI API usage metering SDK
Author: Tokentify
License-Expression: MIT
Project-URL: Homepage, https://github.com/tokentifyai/tokentify-sdk-python
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Requires-Dist: requests>=2.28.0
Requires-Dist: python-dotenv>=1.0.0

# Tokentify UsageMeter (Python)

Out-of-band AI API usage metering for Python. After setup, use **httpx** for provider calls; the SDK captures usage automatically.

## Install

```bash
pip install tokentifyai-usagemeter
```

Optional virtual environment:

```bash
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install tokentifyai-usagemeter
```

## Setup

### 1. Environment

Copy `.env.example` to `.env` and set values from the Tokentify dashboard:

```bash
cp .env.example .env
```

```bash
USAGEMETER_API_KEY=your_ingest_api_key
USAGEMETER_BUCKET=my-bucket
# USAGEMETER_COLLECTOR_URL=https://collector.example.com   # optional
```

`setup()` and `init()` load `.env` automatically (python-dotenv searches upward from the working directory).

| Variable | Required | Description |
|----------|----------|-------------|
| `USAGEMETER_API_KEY` | Yes* | Ingest API key |
| `USAGEMETER_BUCKET` | Yes* | Dashboard bucket name |
| `USAGEMETER_COLLECTOR_URL` | No | Collector base URL (default `http://localhost:8000`) |
| `USAGEMETER_ENVIRONMENT` | No | e.g. `production`, `staging` (default `production`) |
| `USAGEMETER_APP_NAME` | No | App label on events |
| `USAGEMETER_DOTENV_PATH` | No | Explicit `.env` file path |

\*Or pass `api_key=` / `bucket=` in code.

Aliases: `TOKENTIFY_API_KEY`, `TOKENTIFY_BUCKET`, `TOKENTIFY_COLLECTOR_URL`, `TOKENTIFY_ENVIRONMENT`, `TOKENTIFY_APP_NAME`, `TOKENTIFY_DOTENV_PATH`, `UM_API_KEY`, `USAGEMETER_TOKEN`, `UM_TOKEN`, `COLLECTOR_URL`.

### 2. Initialize

Call once at application startup (before any httpx AI traffic):

```python
import tokentifyai_usagemeter as um

# Recommended first run — verifies collector + API key
um.setup("my-bucket")

# Or read bucket + API key from .env only:
um.setup()

# Later / production hot path (skip health checks after a good boot):
um.init("my-bucket", verify_connection=False, verify_api_key=False)
```

| Function | When to use |
|----------|-------------|
| `setup(bucket)` | First integration; runs collector health + API key checks |
| `init(bucket)` | Same wiring; control checks with `verify_connection` / `verify_api_key` |

**Init options** (all optional except bucket + API key, which can come from env):

| Parameter | Default | Notes |
|-----------|---------|--------|
| `api_key` | env | Override ingest key |
| `app_name` | env | Event label |
| `environment` | `production` | In event metadata |
| `collector_url` | env | Base URL, no path |
| `load_env_file` | `True` | Load `.env` |
| `verify_connection` | `False` (`True` in `setup`) | `GET /health` |
| `verify_api_key` | `True` | Validates ingest key |
| `debug` | `False` | SDK debug logs |

Example with explicit values:

```python
um.init(
    "my-bucket",
    api_key="um_...",
    collector_url="https://collector.example.com",
    environment="staging",
)
```

Call `um.init()` or `um.setup()` **before** creating httpx clients. On shutdown, `um.flush()` is optional (events also flush at process exit).

### 3. Develop from this repo

```bash
cd tokentify-sdk-python
python -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env
python -c "import tokentifyai_usagemeter as um; um.setup(); print(um.is_initialized())"
```
