Tokenomicon

Tokenomicon is a post-hoc financial divination tool for LLM hunger and budget dread. It calculates what a call to an LLM provider owes you back, in the form of a tribute. Nothing more, nothing less.

No token counting before the call. No pricing catalog to keep in sync with whatever model shipped this week. Just the augur, reading the entrails of the response you already got.

Why

Most cost-tracking tools for LLM calls either bundle a tokenizer (useful only for one provider, drifting out of date as models change) or ship a hardcoded pricing table (equally stale the moment a provider changes a rate). Tokenomicon does neither.

• Zero runtime dependencies. Pure standard library, Python 3.11+.
• No opinion on what exists. Tokenomicon doesn't know or care which models are on the market. You register what you use, at the price you were quoted.
• No redeploy for a price change. Pricing lives in an external TOML file, reloadable at runtime.
• Reads the bill, doesn't guess it. Token usage is read from the provider's own response, the same numbers you'd already be billed on, not estimated with a local tokenizer.

Installation

pip install tokenomicon

Quick start

from tokenomicon import augur, config

config.load_toml("pricing.toml")

@augur(model="gpt-5.4-mini")
def call_llm(prompt: str):
    return your_llm_client.chat.completions.create(
        model="gpt-5.4-mini",
        messages=[{"role": "user", "content": prompt}],
    )

outcome = call_llm("hi")

print(outcome.tribute)  # Decimal("3.14159"), what this call owes
print(outcome.result)  # the original provider response, untouched

pricing.toml:

[gpt-5.4-mini]
input_per_million = "0.75"
output_per_million = "4.50"

Configuration

TOML

Register pricing plans by loading a TOML file. There's no fixed or implied location: pass whatever path fits your project (root, config/, a path from an environment variable, etc.). Tokenomicon never looks for a file on its own.

config.load_toml("pricing.toml")

Each table is a model name; currency defaults to "USD" if omitted:

[claude-sonnet-5]
input_per_million = "3.00"
output_per_million = "15.00"
currency = "EUR"

An unregistered model raises ModelNotConfiguredError: Tokenomicon never falls back to a bundled "market price."

Loading is atomic: the active registry is replaced only after the complete TOML document has been parsed and every model entry validated. Malformed TOML and structurally invalid entries (a model that isn't a table, a missing field, a non-numeric rate) raise ConfigError; invalid values keep their specific exception (InvalidCurrencyError for the currency, InvalidPricingError for negative or non-finite rates). In every case the previously loaded configuration is left untouched.

Environment variable expansion

${VAR_NAME} patterns in the TOML file are left untouched by default. Opt in explicitly to expand them from the environment:

config.load_toml("pricing.toml", expand_env=True)

[gpt-5.4-mini]
input_per_million = "${GPT_5_4_MINI_INPUT}"
output_per_million = "${GPT_5_4_MINI_OUTPUT}"

A referenced variable that isn't set raises ConfigError.

Expansion is a plain text substitution performed before the TOML is parsed, so the environment is treated as trusted input: a variable whose value contains TOML syntax (quotes, newlines, table headers) is parsed as TOML, not kept as a literal value. Only enable expand_env when both the file and the environment come from sources you control.

Prompt caching

Set cached_input_per_million on a plan to price cache reads at a discounted rate:

[claude-sonnet-5]
input_per_million = "3.00"
output_per_million = "15.00"
cached_input_per_million = "0.30"

Cached tokens are billed separately from regular input tokens, not as a subset of them, matching how the token counts are reported back to tribute() and CallResult. If cached_input_per_million isn't set, cached tokens fall back to the regular input rate — no discount, but nothing lost or silently dropped either.

Extraction is automatic wherever the provider reports it: OpenAI's cached_tokens, Anthropic's cache_read_input_tokens, Google's cached_content_token_count, and DeepSeek's prompt_cache_hit_tokens are all recognized.

Cache writes (Anthropic-only, the premium paid to populate the cache) are also supported, split by TTL tier:

[claude-sonnet-5]
input_per_million = "3.00"
output_per_million = "15.00"
cache_write_5m_per_million = "3.75"
cache_write_1h_per_million = "6.00"

Unlike cache reads, there's no rate fallback for cache writes: billing a write premium at the base input rate would silently understate the real cost. If Anthropic reports cache-write tokens for either tier and the corresponding rate isn't configured, tribute() raises CachePricingNotConfiguredError instead of guessing.

The augur decorator

augur wraps a function that returns a provider response. It reads token usage off that response, calculates the tribute owed, and returns a CallResult without touching your original return value:

@dataclass(frozen=True, slots=True)
class CallResult:
    result: Any  # the original, untouched response
    tribute: Decimal | None  # what this call owes, or None if undetermined
    input_tokens: int | None
    output_tokens: int | None
    cached_tokens: int | None  # tokens served from a prompt cache, 0 if none
    cache_write_5m_tokens: int | None  # Anthropic-only, 5-minute cache TTL tier
    cache_write_1h_tokens: int | None  # Anthropic-only, 1-hour cache TTL tier
    currency: str | None

Supported providers

Token usage is extracted automatically from known response shapes:

import openai
client = openai.OpenAI()

@augur(model="gpt-5.4-mini")
def call():
    return client.chat.completions.create(
        model="gpt-5.4-mini",
        messages=[{"role": "user", "content": "hi"}],
    )

Or, if you need to use async code:

@augur(model="gpt-5.4-mini")
async def call_llm(prompt: str):
    return await your_async_llm_client.chat.completions.create(
        model="gpt-5.4-mini",
        messages=[{"role": "user", "content": prompt}],
    )

outcome = await call_llm("hi")

The same works out of the box for anthropic, google-genai, and mistralai clients; Tokenomicon recognizes their respective usage / usage_metadata shapes without any extra configuration. DeepSeek is also recognized automatically when used via its OpenAI-compatible endpoint (including cache-read token accounting).

Fallback for unrecognized responses

If a response doesn't match a known shape (a local model, a custom client, a provider not yet supported), supply a manual_tokens function:

@augur(
    model="local-llama",
    manual_tokens=lambda response: (response["prompt_len"], response["gen_len"]),
)
def call_local(prompt: str):
    return my_local_client.generate(prompt)

manual_tokens is only called if automatic extraction fails, it never overrides a successful automatic read. If neither succeeds, Tokenomicon emits a TokenExtractionWarning and returns a CallResult with tribute=None, rather than guessing.

The callback must return exactly two non-negative integers: (input_tokens, output_tokens). Anything else, or an exception raised by the callback itself, raises InvalidManualTokensError.

Error handling

All exceptions inherit from TokenomiconError:

TokenExtractionWarning is a UserWarning, not an exception: it doesn't interrupt the call, it only signals that the tribute couldn't be determined.

Not yet supported

• Cost accumulation / ledger across multiple calls. Tokenomicon deliberately stays per-call; aggregate however fits your own storage.

Development

git clone https://github.com/seto/tokenomicon.git
cd tokenomicon
pip install -r requirements-dev.txt
invoke utest

Integration tests make real, minimal calls against actual provider SDKs, purely as optional extra confidence. The unit test suite already covers correctness with 100% coverage, deterministically. They require API keys, are opt-in only, and are never run in CI: adapt them to whichever providers you actually have accounts with.

pip install -r tests/integration/requirements.txt
invoke itest

See tests/integration/conftest.py for the expected environment variables.

License

This program is licensed under the Apache License, Version 2.0.
See the LICENSE file for details.

Changelog

See CHANGES.md for release notes.