Metadata-Version: 2.4
Name: botzy-tokenizer
Version: 0.1.0
Summary: Anthropic API wrapper with per-call token usage logging and ₹-cost intelligence. Drop-in replacement for client.messages.create().
Author: Tanya Bansal (BOTZIFY)
License: PolyForm Noncommercial License 1.0.0
Project-URL: Homepage, https://github.com/stokify-auto-post/botzy-tokenizer
Project-URL: Bug Tracker, https://github.com/stokify-auto-post/botzy-tokenizer/issues
Keywords: anthropic,claude,token,cost,usage,logging,sdk,llm,botzy
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic
Requires-Dist: PyYAML
Dynamic: license-file

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

---

## Install

```bash
pip install botzy-tokenizer
```

Requires Python ≥ 3.9.

---

## Quickstart

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

```python
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:

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

```python
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:

```json
{
  "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

```bash
# 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](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.
