Metadata-Version: 2.4
Name: tokentifyai-usagemeter
Version: 0.1.1
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 (API key is global)

Copy `.env.example` to `.env`. The **API key lives only in `.env`** (or your deployment environment)—never in `init()` code.

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

```bash
# .env — required
USAGEMETER_API_KEY=your_ingest_api_key
USAGEMETER_BUCKET=my-bucket

# optional (SDK default if unset)
USAGEMETER_COLLECTOR_URL=http://205.209.126.182:8006
```

| Variable | Required | Where to set |
|----------|----------|----------------|
| `USAGEMETER_API_KEY` | **Yes** | `.env` only (global secret) |
| `USAGEMETER_BUCKET` | Yes* | `.env` or `init(bucket=...)` |
| `USAGEMETER_COLLECTOR_URL` | No | Default `http://205.209.126.182:8006`; override in `.env` |
| `USAGEMETER_ENVIRONMENT` | No | `.env` (default `production`) |
| `USAGEMETER_APP_NAME` | No | `.env` |
| `USAGEMETER_DOTENV_PATH` | No | `.env` path override |

\*Bucket: set in `.env` **or** pass to `init()` / `setup()`.

Aliases: `TOKENTIFY_API_KEY`, `TOKENTIFY_BUCKET`, `TOKENTIFY_COLLECTOR_URL`, `UM_API_KEY`, `USAGEMETER_TOKEN`, `COLLECTOR_URL`, etc.

Optional early load (same as the automatic load inside `init()`):

```python
import tokentifyai_usagemeter as um

um.load_env()  # reads .env into os.environ before init
```

### 2. Initialize

```python
import tokentifyai_usagemeter as um

# API key from .env; bucket from argument
um.setup("my-bucket")

# API key and bucket both from .env
um.setup()

# Production (skip health checks after first successful setup)
um.init("my-bucket", verify_connection=False, verify_api_key=False)
```

| Function | When to use |
|----------|-------------|
| `setup(bucket)` | First run; verifies collector + API key from `.env` |
| `init(bucket)` | Same; control `verify_connection` / `verify_api_key` |

**Init parameters** (API key is not accepted):

| Parameter | Source |
|-----------|--------|
| `bucket` | Argument or `USAGEMETER_BUCKET` in `.env` |
| `app_name` | Argument or `.env` |
| `environment` | Argument or `.env` (default `production`) |
| `collector_url` | Argument or `.env` |
| `load_env_file` | Default `True` — loads `.env` before reading env vars |
| `verify_connection` | Default `False` (`True` in `setup`) |
| `verify_api_key` | Default `True` |

```python
# Not supported — will raise TypeError:
# um.init("my-bucket", api_key="secret")
```

Call `init()` / `setup()` **before** creating httpx clients.

### 3. Launch (v0.1.1)

`.env` (API key + bucket):

```bash
USAGEMETER_API_KEY=your_ingest_api_key
USAGEMETER_BUCKET=my-bucket
```

`app.py`:

```python
import httpx
import tokentifyai_usagemeter as um

um.setup()  # loads .env; API key from USAGEMETER_API_KEY only

client = httpx.Client()
response = client.post(
    "https://api.openai.com/v1/chat/completions",
    json={"model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}]},
    headers={"Authorization": "Bearer YOUR_OPENAI_KEY"},
)
print(response.status_code)

um.flush()
```

```bash
python app.py
```

### 4. Develop from this repo

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