tokentifyai-usagemeter 0.1.0

Out-of-band AI API usage metering SDK

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

pip install tokentifyai-usagemeter

Optional virtual environment:

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:

cp .env.example .env

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):

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:

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

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