tokentifyai-usagemeter 0.1.1

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 (API key is global)

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

cp .env.example .env

# .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()):

import tokentifyai_usagemeter as um

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

2. Initialize

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

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

USAGEMETER_API_KEY=your_ingest_api_key
USAGEMETER_BUCKET=my-bucket

app.py:

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

python app.py

4. Develop from this repo

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