hong-lab-ai-cost 0.1.0

Lightweight API cost tracker for research labs

Hong Lab AI Cost Tracker

A lightweight Python SDK that transparently tracks LLM API costs. Wrap your existing client with tracker.wrap() — costs are logged automatically.

Supports OpenAI, Google Gemini, Anthropic, and third-party proxies (e.g. apiyihe.org).

Installation

pip install hong-lab-ai-cost

# With specific provider support
pip install "hong-lab-ai-cost[openai]"
pip install "hong-lab-ai-cost[all]"       # OpenAI + Gemini + Anthropic

Usage

OpenAI

from openai import OpenAI
from hong_lab_ai_cost import CostTracker

tracker = CostTracker(project="MyProject", user="kyle", email="[e-mail]")
client = tracker.wrap(OpenAI(api_key="sk-..."))

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}],
)

print(tracker.summary())

Google Gemini

from google import genai
from hong_lab_ai_cost import CostTracker

tracker = CostTracker(project="MyProject", user="kyle", email="[e-mail]")
client = tracker.wrap(genai.Client(api_key="..."))

response = client.models.generate_content(model="gemini-2.5-flash", contents="Hello!")

Anthropic

import anthropic
from hong_lab_ai_cost import CostTracker

tracker = CostTracker(project="MyProject", user="kyle", email="[e-mail]")
client = tracker.wrap(anthropic.Anthropic(api_key="..."))

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)

Third-party Proxy

from openai import OpenAI
from hong_lab_ai_cost import CostTracker

tracker = CostTracker(project="MyProject", user="kyle", email="[e-mail]")
client = tracker.wrap(OpenAI(api_key="...", base_url="https://z.apiyihe.org/v1"))

response = client.chat.completions.create(model="gpt-4o-mini", messages=[...])

Manual Recording

For unsupported providers, record usage manually:

tracker.record(model="llama-3-8b", prompt_tokens=1000, completion_tokens=500)

Configuration

All settings can be provided via constructor arguments, environment variables, or a .cost-tracker.yaml file (priority: constructor > env > yaml > defaults).

Setting	Constructor	Env Variable	Default
Project name	project=	COST_TRACKER_PROJECT	"default"
User name	user=	COST_TRACKER_USER	None
Email	email=	COST_TRACKER_EMAIL	None
Remote API	remote_url=	COST_TRACKER_REMOTE_URL	None (local only)
Storage dir	storage_dir=	—	.cost-tracker/

Example .cost-tracker.yaml:

project: DentalVLM
user: kyle
email: [e-mail]
remote_url: https://cost-api-xxxx.run.app

Remote Sync

By default, the SDK only saves records locally. To enable automatic upload to a remote server, configure remote_url:

Method 1: Constructor argument

tracker = CostTracker(
    project="MyProject",
    user="kyle",
    email="[e-mail]",
    remote_url="https://cost-api-xxxx.run.app",  # Add this to enable upload
)

Method 2: Environment variable

export COST_TRACKER_REMOTE_URL="https://cost-api-xxxx.run.app"

Method 3: Config file .cost-tracker.yaml

remote_url: https://cost-api-xxxx.run.app

Records are uploaded to POST {remote_url}/api/v1/usage/batch with X-Lab-User and X-Lab-Email headers. The server validates these against a whitelist.

If the upload fails (network error, server down), the record is kept locally and retried on the next tracker.flush() or at process exit.

License

MIT