falaw.llm_prices#

One first-party LLM price table: what a direct Anthropic / OpenAI call costs (falaw#81).

falaw.llm_rates prices LLMs routed through fal (fal-ai/any-llm). This module prices calls made straight to the model vendor, the way reelee’s agent loop and chat relay and foley’s rungs make them. Those three used to keep a private copy of the same numbers and drifted; this is the one home.

>>> llm_call_cost_usd("anthropic", "claude-opus-4-7",
...                   {"input_tokens": 1_000_000, "output_tokens": 0})
(5.0, True)

The answer is (usd, known). A model the table does not list is **unknown, not free**: it is priced at the dearest rates listed for that provider and known is False. The cost is then a floor on a guess, not a ceiling: an unlisted model can cost more than the dearest listed one (an older, pricier model). A spend cap can count it; a caller that must never under-count should refuse an unpriced model by testing known:

>>> usd, known = llm_call_cost_usd("anthropic", "claude-from-the-future",
...                                {"input_tokens": 1_000_000})
>>> known, usd > 0
(False, True)

usage is the vendor’s own reported usage, a mapping or an object with attributes, in either of OpenAI’s two shapes (Responses or Chat Completions):

>>> llm_call_cost_usd("openai", "gpt-5", {"prompt_tokens": 1000,
...     "completion_tokens": 100, "prompt_tokens_details": {"cached_tokens": 1000}})
(0.001125, True)

The table is data, not code: PRICES_FILENAME under falaw/data, one row per model, each row carrying its own source and date. Nothing here touches the network. Model ids are matched exactly: a dated snapshot is not priced as its family, because older snapshots can cost more.

Module Attributes

`PRICES_FILENAME`	Basename of the price table under `falaw/data`.
`TOKENS_PER_PRICE_UNIT`	Token count the table's `*_usd_per_mtok` columns are quoted per.
`COST_DECIMALS`	Digits the returned USD is rounded to, which only removes float noise.
`PROVIDERS`	First-party providers the table prices.

Functions

`get_llm_price`(provider, model, *[, prices])	The row for `model` (exact id), or `None` when the table does not list it.
`list_llm_prices`([provider, prices])	Every row, or the rows of one `provider`.
`llm_call_cost_usd`(provider, model, usage, *)	`(USD, known)` for one first-party call from the vendor's reported `usage`.
`llm_prices_table_version`()	The table's version, a digest of its bytes (see `falaw.base.data_table_version()`).
`load_llm_prices`()	The committed table, keyed by `(provider, model)`.

Classes

`LlmPrice`(*, provider, model, rates[, ...])	One row of the first-party table: a model's rates and where they came from.
`LlmPriceRates`(*, input_usd_per_mtok, ...[, ...])	USD per million tokens for one prompt-length regime of one model.

falaw.llm_prices.COST_DECIMALS = 9#: Digits the returned USD is rounded to, which only removes float noise.

class falaw.llm_prices.LlmPrice(*, provider, model, rates, long_prompt_over_tokens=None, long_prompt_rates=None, source='', date='', notes='')[source]#

Bases: object

One row of the first-party table: a model’s rates and where they came from.

class falaw.llm_prices.LlmPriceRates(*, input_usd_per_mtok, output_usd_per_mtok, cache_read_usd_per_mtok=None, cache_write_usd_per_mtok=None, cache_write_1h_usd_per_mtok=None)[source]#

Bases: object

USD per million tokens for one prompt-length regime of one model.

falaw.llm_prices.PRICES_FILENAME = 'first_party_llm_prices.json'#: Basename of the price table under falaw/data.

falaw.llm_prices.PROVIDERS = ('anthropic', 'openai')#: First-party providers the table prices.

falaw.llm_prices.TOKENS_PER_PRICE_UNIT = 1000000#: Token count the table’s *_usd_per_mtok columns are quoted per.

falaw.llm_prices.get_llm_price(provider, model, *, prices=None)[source]#

The row for model (exact id), or None when the table does not list it.

Return type:: Optional[LlmPrice]

falaw.llm_prices.list_llm_prices(provider=None, *, prices=None)[source]#

Every row, or the rows of one provider.

Return type:: list[LlmPrice]

falaw.llm_prices.llm_call_cost_usd(provider, model, usage, *, prices=None)[source]#

(USD, known) for one first-party call from the vendor’s reported usage.

provider="anthropic": input_tokens (uncached), output_tokens, cache_read_input_tokens, cache_creation_input_tokens.
provider="openai": Responses (input_tokens / output_tokens / input_tokens_details.cached_tokens) or Chat Completions (prompt_tokens / completion_tokens / prompt_tokens_details.cached_tokens). Input includes the cached part, which is billed at the cached rate; reasoning tokens are already in output.

known is False when the model is not in the table; the cost is then priced at the provider’s dearest listed rates, which is not a ceiling for a model pricier than any listed (see the module docstring). prices= swaps in the caller’s own table, e.g. one reconciled against an invoice.

Raises:: ValueError – provider is not one of PROVIDERS.
Return type:: tuple[float, bool]

falaw.llm_prices.llm_prices_table_version()[source]#

The table’s version, a digest of its bytes (see falaw.base.data_table_version()).

Return type:: str

falaw.llm_prices.load_llm_prices()[source]#

The committed table, keyed by (provider, model). Read once per process.

Return type:: Mapping[tuple[str, str], LlmPrice]