genai-prices

genai-prices is a Python library from the Pydantic team for calculating the price of calling large-language-model inference APIs. Given a token usage figure and a model reference, it resolves the correct provider and model pricing entry — including historic price changes, variable daily pricing, and tiered context pricing — and returns a precise cost breakdown.

Beyond raw price calculation, the library can extract token usage directly from a provider’s raw response payload (handling flavor differences like OpenAI’s chat vs. responses APIs), and it ships an opt-in background updater that periodically refreshes the bundled pricing dataset from GitHub so applications stay accurate without a release. It supports over 30 providers — OpenAI, Anthropic, Google, AWS Bedrock, Azure, Groq, Mistral, OpenRouter, and more — spanning hundreds of models.

What You Get

• A calc_price() function that turns token usage plus a model reference into a full price breakdown (input, output, and total cost)
• An extract_usage() helper that parses usage and model identifiers straight out of a provider’s raw API response, including provider-specific API flavors like OpenAI’s chat vs. responses formats
• Coverage of 30+ providers and hundreds of models — OpenAI, Anthropic, Google, AWS Bedrock, Azure, Groq, Mistral, Cohere, DeepSeek, OpenRouter, and more — including historic price changes and variable/off-peak pricing
• Tiered pricing support for providers like Gemini that charge different rates once a request crosses a context-length threshold
• An opt-in UpdatePrices background thread that refreshes pricing data from GitHub on an interval, so long-running services don’t need a new release to pick up price changes
• A companion CLI (genai-prices) for listing providers/models and calculating costs from the terminal, with Rich-formatted or plain-text output

Common Use Cases

• Attaching a real dollar cost to every LLM call in an application’s logging or observability pipeline
• Building internal dashboards or budget alerts that track spend across multiple LLM providers from one usage figure
• Comparing the cost of the same workload across providers/models before committing to one in production
• Estimating cost up front for a batch job by summing projected input/output tokens across many requests
• Reconciling billing anomalies by recalculating what a given set of logged API responses should have cost

Under The Hood

Architecture The public API in __init__.py (calc_price, extract_usage) is a thin typed wrapper around data_snapshot.get_snapshot(), which lazily builds and caches (via functools.cache) a DataSnapshot dataclass wrapping the full providers list compiled into data.py — a 13,000+ line, code-generated module of provider/model pricing entries chosen for zero-parse-time lookup speed. DataSnapshot.calc() matches a model_ref and optional provider_id/provider_api_url against this list to find a Provider/ModelInfo pair, then delegates to ModelInfo.calc_price() to resolve tiered- and time-based pricing rules defined in types.py. extract_usage() follows the same snapshot-lookup path but dispatches to provider-specific UsageExtractor callables keyed by provider_id and api_flavor to parse raw response payloads. update_prices.py layers an optional background daemon thread (UpdatePrices) that fetches a refreshed data.json from GitHub via httpx2 on an interval and swaps it in through set_custom_snapshot(), so the compiled-in dataset acts as an always-available fallback rather than a hard dependency on network access.

Tech Stack The package targets Python 3.10+ and is built with uv_build. Runtime dependencies are minimal by design — httpx2 (used only by the optional background updater) and pydantic>=2.10 (used throughout types.py for schema validation and the JSON-schema-backed pricing data format). The CLI is entirely optional, gated behind a [cli] extra pulling in pydantic-settings, rich, and rich-argparse, so consumers who only need the library API avoid that dependency weight.

Code Quality The tests/ directory is unusually thorough for a library this size, with dedicated suites for custom prices, usage extraction, tiered pricing, provider/model matching, the background updater’s lifecycle, CLI behavior, end-to-end flows, and price regressions against known-correct values, plus a schema-validation test (test_package_schema.py) that guards the generated pricing data itself. The package ships a py.typed marker, public functions carry full docstrings with Args/Returns sections, and a coverage badge is tracked in CI — all signs of a codebase treated as production infrastructure rather than a convenience script.

API Design The surface area is deliberately small: two top-level functions (calc_price, extract_usage) plus an UpdatePrices class, each with typed @overload signatures that make the provider_id vs. provider_api_url choice explicit at the type-checker level. The README leads with copy-pasteable snippets for both the synchronous common case and the background-updater pattern, and the CLI mirrors the same two operations (list, calc) for users who’d rather not write Python. There’s no separate hosted docs site, but the API’s small footprint and inline docstrings keep the learning curve low.