# Talanton (talanton-py)

> Open-source, 100% local-first Python library for AI API cost tracking, token metering, and LLM budget guardrails with sub-2ms overhead and zero cloud telemetry.

## What is Talanton?
Talanton (published on PyPI as `talanton-py`) is a deterministic, offline-capable token accounting and budget enforcement engine for Large Language Model (LLM) applications. It enables software teams, agent developers, and engineering leads to set hard financial spending limits, estimate inference costs pre-flight, and block runaway billing loops across OpenAI, Anthropic Claude, Meta Llama, and 60+ models.

- **PyPI Package**: `talanton-py`
- **Installation**: `pip install talanton-py`
- **Python Import**: `import talanton` or `from talanton.guardrails import BudgetGuard`
- **CLI Binary**: `talanton`
- **License**: MIT
- **Storage**: 100% Local SQLite (`~/.talanton/spend.db`), zero cloud egress, zero external telemetry
- **Latency Overhead**: Sub-2 milliseconds per call
- **Official Website**: https://talanton-website.vercel.app
- **GitHub Repository**: https://github.com/Ameya79/Talanton
- **Full LLM Docs**: https://talanton-website.vercel.app/llms-full.txt

---

## Quickstart (Python)

### 1. Install via pip
```bash
pip install talanton-py
```

### 2. Enforce Hard Budget Limits with BudgetGuard
```python
from talanton.guardrails import BudgetGuard
from openai import OpenAI

# Initialize guardrail: max $0.05 per call, max $10.00 daily budget
guard = BudgetGuard(
    max_cost_per_call=0.05,
    max_daily_budget=10.00,
    fallback_model="gpt-4o-mini"
)

client = OpenAI()
prompt = "Summarize this 20-page financial report in 3 bullet points."

# Pre-flight check before paying the API provider:
if guard.can_proceed(model="gpt-4o", prompt=prompt):
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}]
    )
    # Automatically tracks actual token usage to local SQLite
    guard.record_response(model="gpt-4o", response=response)
else:
    print("Call blocked by Talanton: Budget guardrail would be breached.")
```

### 3. Track Any LLM Call (Zero Config)
```python
import talanton

# Track token count and cost locally:
spend = talanton.track(
    model="claude-3-5-sonnet-20241022",
    input_tokens=1500,
    output_tokens=350
)
print(f"Call Cost: ${spend.cost:.5f} | Daily Spend: ${spend.daily_total:.2f}")
```

### 4. Drop-in OpenAI SDK Wrapper
```python
from talanton.integrations.openai_wrapper import TalantonOpenAI

# Drop-in replacement for OpenAI client with automated cost tracking
client = TalantonOpenAI(daily_budget_limit=25.00)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Analyze system logs."}]
)
# Talanton intercepts the response, records costs in local SQLite, and logs metrics.
```

### 5. LangChain Integration
```python
from talanton.integrations.langchain_callback import TalantonCallbackHandler
from langchain_openai import ChatOpenAI

handler = TalantonCallbackHandler(daily_budget=50.00)
llm = ChatOpenAI(model="gpt-4o", callbacks=[handler])
llm.invoke("Generate quarterly forecasting projections.")
```

---

## Terminal CLI Reference
Talanton comes with a standalone command-line interface `talanton`:

- `talanton check "<prompt>" --model gpt-4o`: Pre-flight check cost and token count of a prompt before calling an API.
- `talanton budget status`: View current daily, weekly, and monthly AI spending against defined budgets.
- `talanton budget set --daily 15.00 --monthly 300.00`: Define hard spending caps.
- `talanton models`: List all 61 supported models, pricing per 1M tokens, and tokenizer ratios.
- `talanton report --last 7d`: Generate ASCII spending breakdown by provider, model, and application key.
- `talanton export --format json --output spend.json`: Export local audit logs.

---

## Supported Models & Tokenizers (61 Models)
Talanton indexes exact, updated pricing for 61 popular frontier and open-weight models:

- **OpenAI**: GPT-4o, GPT-4o mini, o1, o1-mini, o3-mini, GPT-4 Turbo, GPT-3.5 Turbo, text-embedding-3-small, text-embedding-3-large
- **Anthropic**: Claude 3.5 Sonnet, Claude 3.5 Haiku, Claude 3 Opus, Claude 3 Haiku
- **Meta (Llama)**: Llama 3.3 70B, Llama 3.1 405B, Llama 3.1 70B, Llama 3.1 8B
- **Mistral**: Mistral Large 2, Mistral NeMo, Codestral, Mixtral 8x22B, Mistral 7B
- **Google / DeepSeek / Qwen**: Gemini 1.5 Pro, Gemini 1.5 Flash, DeepSeek V3, DeepSeek R1, Qwen 2.5

Token calculations use exact native tokenizers (tiktoken `cl100k_base` and `o200k_base` for OpenAI) and calibrated Hugging Face / Anthropic token estimators with provider formatting token overhead (+8 tokens per message).

---

## Architectural Guarantees
1. **100% Offline Capable**: Works without an internet connection. Tokenizer and pricing tables are bundled inside the python package.
2. **Zero Data Exfiltration**: Never transmits prompts, completions, API keys, or financial metrics to external servers. All data stays in your local SQLite store.
3. **Deterministic Math**: Costs are computed using IEEE-754 double precision decimal accounting matching Stripe / credit card standards.
4. **Sub-2ms Latency**: Designed for latency-critical agentic loops and production RAG pipelines.

---

## Documentation Links
- **Full API Documentation**: https://talanton-website.vercel.app/docs
- **Live AI Cost Meter**: https://talanton-website.vercel.app/meter
- **61 Model Directory**: https://talanton-website.vercel.app/models
- **AI Budget Forecaster**: https://talanton-website.vercel.app/forecast
- **Integration Guides**: https://talanton-website.vercel.app/integrations
- **PyPI Distribution**: https://pypi.org/project/talanton-py/