botzy-tokenizer 0.1.0

Anthropic API wrapper with per-call token usage logging and ₹-cost intelligence. Drop-in replacement for client.messages.create().

botzy-tokenizer

Per-call token usage logging and ₹-cost intelligence for the Anthropic API.

The moat is observed per-key data — not a counter, but a full audit trail: which source called which model, how many tokens were spent, what those tokens cost in ₹, and exactly how much you saved (or left on the table) through prompt caching.

BOTZIFY™ / botzy_tokenizer™ — trademark of Tanya Bansal (BOTZIFY). Source-available under the PolyForm Noncommercial License 1.0.0.

---

Install

pip install botzy-tokenizer

Requires Python ≥ 3.9.

---

Quickstart

Replace client.messages.create(...) with botzy_tokenizer.create(...):

from botzy_tokenizer import create

response = create(
    model="claude-haiku-4-5-20251001",
    max_tokens=256,
    source="mymod:my_function",   # optional — tags the usage row
    messages=[{"role": "user", "content": "Hello, Claude!"}],
)
print(response.content[0].text)

Async:

from botzy_tokenizer import async_create

response = await async_create(
    model="claude-sonnet-4-5-20251001",
    max_tokens=512,
    messages=[{"role": "user", "content": "Summarise this for me..."}],
)

Every successful call writes one row to a local SQLite database. Usage logging is best-effort — it never raises into your code.

---

Configuration

Environment variables (recommended)

Variable	Purpose	Default
BOTZY_TOKENIZER_HOME	Home directory	~/.botzy_tokenizer/
BOTZY_TOKENIZER_DB	Path to usage.db	$HOME/usage.db
BOTZY_TOKENIZER_RATES	Path to usage_rates.yaml	$HOME/usage_rates.yaml
BOTZY_TOKENIZER_LOCKFILE	Path to model_locks.json (opt-in)	(disabled)

Programmatic override (call before the first create())

from botzy_tokenizer import configure

configure(
    db="/data/my_project/usage.db",
    rates="/etc/myapp/rates.yaml",
    lock_file="/etc/myapp/model_locks.json",  # omit to disable lock enforcement
)

Rates file

On first use, ~/.botzy_tokenizer/usage_rates.yaml is auto-seeded from the bundled defaults (Anthropic published pricing as of 2026-05). Edit that file to update the USD→INR rate or model prices without touching code (R13).

---

Model-lock gate (opt-in)

Lock enforcement is disabled by default — every model is allowed. To enable it, set BOTZY_TOKENIZER_LOCKFILE (or call configure(lock_file=...)) to a JSON file:

{
  "haiku":  {"locked": false, "calls_since_unlock": 42},
  "sonnet": {"locked": true,  "calls_since_unlock": 0},
  "opus":   {"locked": true,  "calls_since_unlock": 0}
}

When the file exists and a family is locked, create() raises ValueError before making any API call.

---

Cost-report CLI

# Initialise home dir, db, and rates file
botzy-tokenizer init

# Show last 24 hours (default)
botzy-tokenizer report

# Show last hour / week / 30 days
botzy-tokenizer report 1h
botzy-tokenizer report 1w
botzy-tokenizer report 1m

Report sections:

1. PER-MODEL — calls, in/out tokens, cache r/w tokens, ₹ cost
2. SAVED BY CACHE — ₹ actually saved through cache reads and % of full cost
3. MISSED SAVINGS — ₹ left on the table by source (uncached vs eligible-but-missed)
4. TOTAL — window cost + per-date breakdown for windows ≥ 1 day

Use BOTZY_TOKENIZER_HOME=/tmp/test botzy-tokenizer report to point at a non-default database.

---

License

PolyForm Noncommercial License 1.0.0 — see LICENSE. Commercial use requires a separate agreement with BOTZIFY.

BOTZIFY™ and botzy_tokenizer™ are trademarks of Tanya Bansal (BOTZIFY). Trademark rights are not licensed under the PolyForm Noncommercial License.