Metadata-Version: 2.4
Name: modelcost
Version: 0.1.0
Summary: Calculate LLM API call costs from token usage
Project-URL: Homepage, https://github.com/rmescandon/modelcost
Project-URL: Repository, https://github.com/rmescandon/modelcost
Author-email: Roberto Mier Escandon <rmescandon@gmail.com>
License: MIT
Keywords: cost,llm,openai,pricing,tokens
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.27
Requires-Dist: tokencost>=0.1.16
Description-Content-Type: text/markdown

# modelcost

Calculate LLM API call costs from token usage using price catalogs from multiple sources.

Supported pricing sources:
- `litellm` (default)
- `openrouter`
- `tokencost`

## Install

```bash
python -m pip install modelcost
```

## CLI

The default command calculates cost, so you can omit the `cost` subcommand.

```bash
# Default (cost)
modelcost gpt-4o 1000 500

# Explicit cost (optional)
modelcost cost gpt-4o 1000 500

# All sources in one run
modelcost --source all gpt-4o 1000 500

# JSON output
modelcost --json gpt-4o 1000 500
```

List available models:

```bash
modelcost models
modelcost models --source openrouter
modelcost models --filter gpt
modelcost models --json
```

CLI help:

```bash
modelcost --help
modelcost models --help
```

## Library

```python
from modelcost.calculator import calculate_cost, list_models

result = calculate_cost("gpt-4o", 1000, 500)

for source in result.available_sources:
    print(f"{source.source}: ${source.total_cost_usd:.6f}")

litellm_cost = next(s for s in result.sources if s.source == "litellm")
print(litellm_cost.price_per_million_input, litellm_cost.price_per_million_output)

models = list_models("openrouter")
```

## Output details

`calculate_cost()` returns a `CostResult` with:
- `model`, `input_tokens`, `output_tokens`
- `sources`: list of `SourceCost` objects
- `available_sources`: only sources with prices found

Each `SourceCost` includes:
- `source`
- `total_cost_usd`
- `price_per_million_input`
- `price_per_million_output`
- `error` (when not available)

## Caching

`openrouter` responses are cached in `~/.modelcost_cache.json` for 1 hour.

## Notes

- Prices are fetched at runtime from the upstream catalogs.
- If a model is missing in a source, that source is marked as unavailable.
- Network sources are fetched in parallel for the `all` option.
