tokenary

Calculate LLM API cost estimates in USD from LiteLLM pricing data. Use the bundled offline snapshot, generate a catalog for selected models, or opt into asynchronous price updates. calculate() is synchronous and performs no network I/O.

Install

Requires Python 3.13 or newer.

pip install tokenary

Calculate a cost

from tokenary import calculate

result = calculate(model="gpt-4o", input_tokens=1000, output_tokens=500)
print(result.total_cost)
print(result.model_dump())  # Category breakdown and pricing checksums

No setup or generation is needed. The default uses prices shipped with the installed version, opens requested providers and validates models on demand.

Input and output counts are inclusive totals: reasoning, audio and cache counts are subsets. A requested category without a supported rate raises MissingPriceError. See usage and billing rules.

Choose your pricing source

For example, generate a small Python catalog:

tokenary-generate --models gpt-4o o1 --output my_prices.py

from tokenary import calculate
from my_prices import CATALOG, ModelName

result = calculate(
    model=ModelName.GPT_4O,
    input_tokens=1000,
    output_tokens=500,
    catalog=CATALOG,
)

Without --input, generation downloads the current LiteLLM catalog once. It does not update the installed default. JSON and gzip catalogs are supported too.

Find the details

• Documentation index — guides, reference and runnable examples.
• Usage reference — request fields, adapters, cache and context tiers.
• Development — setup, checks and catalog regeneration.
• Snapshot provenance — bundled source, checksum and refresh summary.
• Migration notes and performance.
• Changelog — release changes and intentional breaking changes.
• Agent instructions — repository map, invariants and verification.

Review history and completed implementation tickets live in tickets/.