# Talanton (talanton-py) — Full Technical Reference & Developer Guide

> Package: `talanton-py` | CLI: `talanton` | Import: `import talanton` | License: MIT
> Repository: https://github.com/Ameya79/Talanton | Website: https://talanton-website.vercel.app

---

## 1. What is Talanton?
Talanton is a high-performance Python library and CLI tool designed to track AI API spending in real time, enforce rigid budget limits, and prevent accidental runaway billing in autonomous agents, RAG workflows, and multi-tenant LLM backends.

Key problems Talanton solves:
1. **Agent Runaway Loops**: When an LLM agent gets caught in a recursive tool-calling loop, it can rack up hundreds of dollars within minutes. Talanton's `BudgetGuard` intercepts each call pre-flight and terminates or falls back when spending reaches your threshold.
2. **Hidden Provider Markups & Overheads**: Chat APIs inject formatting tokens (role tags, delimiting tokens) that increase billable tokens. Talanton models this exact overhead.
3. **Privacy & Compliance**: Many enterprise security teams prohibit sending usage metrics to third-party SaaS dashboards. Talanton is 100% local-first and stores all metrics in an offline SQLite database (`~/.talanton/spend.db`).

---

## 2. Installation & Configuration

### Standard Pip Install
```bash
pip install talanton-py
```

### Optional Dependencies
```bash
pip install "talanton-py[tiktoken]"       # For exact byte-pair encoding token counts
pip install "talanton-py[langchain]"      # For LangChain callback integration
pip install "talanton-py[litellm]"        # For LiteLLM proxy integration
pip install "talanton-py[all]"            # Full suite
```

### Global Configuration
Talanton stores its persistent ledger at `~/.talanton/spend.db`.
Environment variables:
- `TALANTON_DB_PATH`: Override SQLite database location (default: `~/.talanton/spend.db`).
- `TALANTON_DAILY_BUDGET`: Default daily spending limit in USD (e.g. `20.00`).
- `TALANTON_MONTHLY_BUDGET`: Default monthly spending limit in USD (e.g. `500.00`).
- `TALANTON_STRICT_MODE`: Set to `true` to raise `BudgetExceededError` instead of warning.

---

## 3. Python SDK Reference

### 3.1 BudgetGuard API
The core guardrail primitive is `talanton.guardrails.BudgetGuard`.

```python
from talanton.guardrails import BudgetGuard, BudgetExceededError

guard = BudgetGuard(
    max_cost_per_call=0.08,           # Max USD per individual completion
    max_daily_budget=25.00,           # Max USD aggregate spend per calendar day
    max_monthly_budget=500.00,        # Max USD aggregate spend per calendar month
    fallback_model="gpt-4o-mini",     # Automatic downgrade model candidate
    on_breach="raise",                # Action: "raise", "warn", or "fallback"
    log_file="~/.talanton/alerts.log" # Audit trail
)

# Method 1: Pre-flight permission check
can_run, reason = guard.can_proceed(
    model="gpt-4o",
    prompt="Explain general relativity to a 10 year old."
)

if not can_run:
    print(f"Call blocked: {reason}")
else:
    # Execute API call...
    pass

# Method 2: Post-completion recording
guard.record(
    model="gpt-4o",
    input_tokens=420,
    output_tokens=180,
    metadata={"user_id": "usr_9912", "service": "chat-agent"}
)
```

### 3.2 Direct Cost Calculation API
```python
import talanton

# Estimate pre-flight cost from raw text without calling provider:
cost_estimate = talanton.estimate(
    model="claude-3-5-sonnet-20241022",
    prompt="Summarize this 10,000 word transcript.",
    expected_output_tokens=500
)

print(f"Estimated Tokens: {cost_estimate.tokens}")
print(f"Estimated USD Cost: ${cost_estimate.cost:.5f}")

# Calculate exact cost from token counts:
exact_cost = talanton.calculate_cost(
    model="gpt-4o",
    input_tokens=1200,
    output_tokens=450
)
print(f"Exact Cost: ${exact_cost:.5f}")
```

### 3.3 Provider Drop-in Wrappers

#### OpenAI Wrapper (`TalantonOpenAI`)
```python
from talanton.integrations.openai_wrapper import TalantonOpenAI

client = TalantonOpenAI(
    api_key="your-api-key",
    daily_budget=15.00
)

# Works identically to standard openai.OpenAI client:
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Write a python script to parse CSV files."}]
)

print(response.choices[0].message.content)
# Total call cost and cumulative daily spend are automatically recorded in SQLite.
```

#### Anthropic Claude Wrapper (`TalantonAnthropic`)
```python
from talanton.integrations.anthropic_wrapper import TalantonAnthropic

client = TalantonAnthropic(
    api_key="your-api-key",
    daily_budget=20.00
)

message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1000,
    messages=[{"role": "user", "content": "Review this security architecture."}]
)
```

#### LangChain Callback Handler
```python
from talanton.integrations.langchain_callback import TalantonCallbackHandler
from langchain_openai import ChatOpenAI

handler = TalantonCallbackHandler(
    daily_budget=30.00,
    on_limit_reached="raise"
)

llm = ChatOpenAI(model="gpt-4o", callbacks=[handler])
result = llm.invoke("Draft an executive summary.")
```

#### LiteLLM Proxy Integration
```python
import litellm
from talanton.integrations.litellm_callback import talanton_litellm_callback

litellm.success_callback = [talanton_litellm_callback]
litellm.failure_callback = [talanton_litellm_callback]
```

---

## 4. CLI Commands Guide (`talanton`)

Run `talanton --help` to view all subcommands:

### `talanton check`
Simulate prompt cost before calling APIs.
```bash
talanton check "Explain quantum entanglement in 200 words." --model gpt-4o
talanton check --file system_prompt.txt --model claude-3-5-sonnet-20241022
```

### `talanton budget`
Manage local spending limits.
```bash
talanton budget status                       # View today's burn rate vs limit
talanton budget set --daily 10.00            # Set $10.00 daily ceiling
talanton budget set --monthly 250.00         # Set $250.00 monthly ceiling
talanton budget reset                        # Reset ledger counters for today
```

### `talanton models`
List supported models and updated pricing.
```bash
talanton models                              # List all 61 models
talanton models --provider anthropic         # Filter by provider
talanton models --sort price                 # Sort by cheapest blended price
```

### `talanton report`
Audit trails and historical spending reports.
```bash
talanton report --today                      # Today's breakdown by model
talanton report --last 30d                   # Last 30 days
talanton report --export csv --out spend.csv # Export to CSV
```

---

## 5. Storage Schema (SQLite)
Table `talanton_spend_events`:
- `id` (INTEGER PRIMARY KEY AUTOINCREMENT)
- `timestamp` (DATETIME DEFAULT CURRENT_TIMESTAMP)
- `model` (TEXT NOT NULL)
- `provider` (TEXT NOT NULL)
- `input_tokens` (INTEGER NOT NULL)
- `output_tokens` (INTEGER NOT NULL)
- `input_cost_usd` (REAL NOT NULL)
- `output_cost_usd` (REAL NOT NULL)
- `total_cost_usd` (REAL NOT NULL)
- `latency_ms` (REAL)
- `app_metadata` (TEXT / JSON)

---

## 6. Model Pricing Table (Sample)
- `gpt-4o`: $2.50 / 1M input, $10.00 / 1M output
- `gpt-4o-mini`: $0.15 / 1M input, $0.60 / 1M output
- `claude-sonnet-4.5` / `claude-3-5-sonnet-20241022`: $3.00 / 1M input, $15.00 / 1M output
- `claude-3-5-haiku-latest`: $0.80 / 1M input, $4.00 / 1M output
- `meta-llama/Llama-3.1-8B-Instruct`: $0.05 / 1M input, $0.08 / 1M output
- `meta-llama/Llama-3.3-70B-Instruct`: $0.13 / 1M input, $0.40 / 1M output
- `o3-mini`: $1.10 / 1M input, $4.40 / 1M output
- `o1`: $15.00 / 1M input, $60.00 / 1M output

For complete, live pricing across all 61 models, visit:
https://talanton-website.vercel.app/models