Metadata-Version: 2.4
Name: tokentifyai-usagemeter
Version: 0.1.2
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
python3 -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=your_bucket_name
```

### 2. Initialize

```python
import os
import tokentifyai_usagemeter as um

# USAGEMETER_API_KEY from .env; USAGEMETER_BUCKET from argument
um.load_env()
um.setup(os.environ["USAGEMETER_BUCKET"])

# USAGEMETER_API_KEY and USAGEMETER_BUCKET both from .env
um.setup()

# Production (skip health checks after first successful setup)
um.load_env()
um.init(
    os.environ["USAGEMETER_BUCKET"],
    verify_connection=False,
    verify_api_key=False,
)
```

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

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

| Parameter | Source |
|-----------|--------|
| `bucket` | Argument (value of `USAGEMETER_BUCKET`) or `USAGEMETER_BUCKET` in `.env` |
| `app_name` | Argument or `USAGEMETER_APP_NAME` in `.env` |
| `environment` | Argument or `USAGEMETER_ENVIRONMENT` in `.env` (default `production`) |
| `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(os.environ["USAGEMETER_BUCKET"], api_key="secret")
```

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

### 3. Launch (v0.1.2)

`.env` (`USAGEMETER_API_KEY` + `USAGEMETER_BUCKET`):

```bash
USAGEMETER_API_KEY=your_ingest_api_key
USAGEMETER_BUCKET=your_bucket_name
```

`app.py`:

```python
import httpx
import tokentifyai_usagemeter as um

um.setup()  # loads .env; reads USAGEMETER_API_KEY and USAGEMETER_BUCKET

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())"
```
