Metadata-Version: 2.4
Name: llm-costs
Version: 0.1.3
Summary: LLM cost calculator for major providers
Author-email: jason <jtan92@gmail.com>
Requires-Python: >=3.13
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# llm-costs

LLM cost calculator for major providers. Calculates API costs from token usage data.

## Installation

```bash
pip install llm-costs
```

Or with uv:

```bash
uv add llm-costs
```

## Usage

```python
from llm_costs import calculate_cost, get_model_pricing

# Calculate cost from LangChain UsageMetadata structure
result = calculate_cost(
    provider="anthropic",
    model="claude-sonnet-4-20250514",
    usage={
        "input_tokens": 1000,
        "output_tokens": 500,
        "total_tokens": 1500,
    },
)

print(f"Cost: ${result['cost']:.6f}")  # Cost: $0.010500
print(f"Input: ${result['breakdown']['input_cost']:.6f}")
print(f"Output: ${result['breakdown']['output_cost']:.6f}")
```

### With Prompt Caching

```python
result = calculate_cost(
    provider="anthropic",
    model="claude-sonnet-4-20250514",
    usage={
        "input_tokens": 1000,
        "output_tokens": 500,
        "total_tokens": 1500,
        "input_token_details": {
            "cache_read": 5000,
            "cache_creation": 0,
        },
    },
)
```

### Batch Pricing

```python
result = calculate_cost(
    provider="anthropic",
    model="claude-sonnet-4-20250514",
    usage={"input_tokens": 1000, "output_tokens": 500, "total_tokens": 1500},
    batch=True,  # 50% discount
)
```

### Get Model Pricing Info

```python
pricing = get_model_pricing("anthropic", "claude-sonnet-4-20250514")
print(f"Input: ${pricing['input']}/MTok")   # Input: $3.0/MTok
print(f"Output: ${pricing['output']}/MTok") # Output: $15.0/MTok
```

### List Available Models

```python
from llm_costs.calculator import list_models, list_providers

providers = list_providers()  # ['anthropic', 'openai', 'google']
models = list_models("anthropic")  # ['claude-opus-4-5-20251101', ...]
```

## Supported Providers

### Anthropic

| Model | Input | Output | Cache Read |
|-------|-------|--------|------------|
| claude-opus-4-5-20251101 | $5.00 | $25.00 | $0.50 |
| claude-opus-4-1-20250414 | $15.00 | $75.00 | $1.50 |
| claude-opus-4-20250514 | $15.00 | $75.00 | $1.50 |
| claude-sonnet-4-5-20250514 | $3.00 | $15.00 | $0.30 |
| claude-sonnet-4-20250514 | $3.00 | $15.00 | $0.30 |
| claude-3-7-sonnet-20250219 | $3.00 | $15.00 | $0.30 |
| claude-haiku-4-5-20250514 | $1.00 | $5.00 | $0.10 |
| claude-3-5-haiku-20241022 | $0.80 | $4.00 | $0.08 |
| claude-3-opus-20240229 | $15.00 | $75.00 | $1.50 |
| claude-3-haiku-20240307 | $0.25 | $1.25 | $0.03 |

Prices per million tokens. Long context pricing (>200K tokens) applies to Sonnet models.

### OpenAI

| Model | Input | Output | Cache Read |
|-------|-------|--------|------------|
| gpt-5.2 | $1.75 | $14.00 | $0.175 |
| gpt-5.1 | $1.25 | $10.00 | $0.125 |
| gpt-5 | $1.25 | $10.00 | $0.125 |
| gpt-5-mini | $0.25 | $2.00 | $0.025 |
| gpt-5-nano | $0.05 | $0.40 | $0.005 |
| gpt-5.2-pro | $21.00 | $168.00 | - |
| gpt-5-pro | $15.00 | $120.00 | - |
| gpt-4.1 | $2.00 | $8.00 | $0.50 |
| gpt-4.1-mini | $0.40 | $1.60 | $0.10 |
| gpt-4.1-nano | $0.10 | $0.40 | $0.025 |
| gpt-4o | $2.50 | $10.00 | $1.25 |
| gpt-4o-mini | $0.15 | $0.60 | $0.075 |
| o1 | $15.00 | $60.00 | $7.50 |
| o1-pro | $150.00 | $600.00 | - |
| o1-mini | $1.10 | $4.40 | $0.55 |
| o3 | $2.00 | $8.00 | $0.50 |
| o3-pro | $20.00 | $80.00 | - |
| o3-mini | $1.10 | $4.40 | $0.55 |
| o3-deep-research | $10.00 | $40.00 | $2.50 |
| o4-mini | $1.10 | $4.40 | $0.275 |
| o4-mini-deep-research | $2.00 | $8.00 | $0.50 |
| computer-use-preview | $3.00 | $12.00 | - |

Prices per million tokens (Standard tier).

### Google

| Model | Input | Output | Cache Read |
|-------|-------|--------|------------|
| gemini-3-pro-preview | $2.00 | $12.00 | $0.20 |
| gemini-2.5-pro | $1.25 | $10.00 | $0.125 |
| gemini-2.5-flash | $0.30 | $2.50 | $0.03 |
| gemini-2.5-flash-lite | $0.10 | $0.40 | $0.01 |
| gemini-2.0-flash | $0.10 | $0.40 | $0.025 |
| gemini-2.0-flash-lite | $0.075 | $0.30 | - |

Prices per million tokens (Paid tier). Long context pricing (>200K tokens) applies to Pro models.

## Usage Schema

The library accepts token usage in LangChain's `UsageMetadata` format:

```python
{
    "input_tokens": int,
    "output_tokens": int,
    "total_tokens": int,
    "input_token_details": {
        "cache_read": int,      # Cached tokens read
        "cache_creation": int,  # Tokens written to cache
    },
    "output_token_details": {
        "reasoning": int,       # Reasoning tokens (o1/thinking models)
    },
}
```

## Return Value

`calculate_cost()` returns a `CostResult`:

```python
{
    "cost": 0.0105,           # Total cost in USD
    "currency": "USD",
    "breakdown": {
        "input_cost": 0.003,
        "output_cost": 0.0075,
        "cache_read_cost": 0.0,      # If applicable
        "cache_creation_cost": 0.0,  # If applicable
    },
    "pricing_used": {
        "input_per_mtok": 3.0,
        "output_per_mtok": 15.0,
        "batch_applied": False,
        "long_context_applied": False,
    },
}
```

## License

MIT
