llm-rates 0.3.0__tar.gz

llm_rates-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 m0j0d
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

llm_rates-0.3.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: llm-rates
+Version: 0.3.0
+Summary: One vendored litellm-catalog snapshot + one internal overlay + shared lookup/cost math for portfolio LLM pricing
+Author-email: Mike Donnelly <82827803+m0j0d@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/m0j0d/libs/tree/main/llm-rates
+Project-URL: Repository, https://github.com/m0j0d/libs
+Project-URL: Issues, https://github.com/m0j0d/libs/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Provides-Extra: refresh
+Requires-Dist: anthropic>=0.122.0; extra == "refresh"
+Dynamic: license-file
+
+# llm-rates
+
+Named `llm-rates` (not `llm-prices`, its name until 2026-08-21) because
+PyPI's similarity check rejected `llm-prices` as too close to the existing
+`llmprices` project — collapsed-separator collision, not an exact-name
+clash. `llm-rates` was verified free in every form (`llm-rates`,
+`llmrates`, `llm_rates`, singular `llm-rate`/`llmrate`) before adopting it;
+don't re-litigate the name.
+
+One vendored model-price catalog + one internal overlay + a shared Python
+lookup/cost-math module, replacing four independently hand-maintained price
+tables that were drifting apart. Full origin story and decisions: this
+repo's sibling checkout `plugin/docs/plans/model-catalog-consolidation.md`
+(cross-repo — `plugin` is a separate git repository from `libs`, so this is
+a path reference, not a clickable link).
+
+## Why this exists
+
+Four tables held the same vendor facts (`plugin/scripts/prices/anthropic.json`,
+`plugin/skills/tokenator/scripts/pricing.json`,
+`sessions/src/sessmon/pricing.py`,
+`factory-bench/runs/model-bench/model-bench-runner.py`). One of them silently
+returned `$0.00` for any model it didn't recognise — a lookup bug, not a data
+bug — and under-reported real spend by over $800 in one 30-day window. This
+package fixes the *lookup logic* (never $0 for an unknown model) and gives
+the data one home.
+
+## Files
+
+- `catalog.json` — vendored snapshot of
+  [litellm's `model_prices_and_context_window.json`](https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json),
+  filtered to the providers/models the portfolio actually uses. Vendor list
+  price, per-single-token USD (litellm's native unit). Never hand-edit —
+  regenerate prices via `refresh.py --apply`; for Anthropic-provider rows,
+  the capability fields (`max_input_tokens`/`max_output_tokens`) are instead
+  kept in sync with Anthropic's own live Models API via
+  `refresh_context.py --apply` (litellm's snapshot is a third-party guess
+  for those fields, not authoritative).
+- `overlay.json` — everything no public catalog can know: actual-billing
+  overrides (e.g. Groq OSS models are free-tier here, not their list price),
+  family-rate fallbacks (`claude-opus` → tier rate, so an unrecognised new
+  model prices at its family's rate instead of $0), model-ID aliases (dated
+  suffixes → canonical key), retirement/deprecation history (a retired
+  model's row is kept, never deleted, so historical transcripts still
+  reprice correctly), `context_overrides` for the rare model whose real
+  default-served context genuinely differs from its published maximum
+  (empty as of 2026-08-21 — see "Context-window data" below), and
+  per-consumer portfolio pins.
+- `llm_rates/` — `lookup(model_id) -> PriceRecord` + cost math (in
+  `__init__.py`); `catalog.json` and `overlay.json` ship inside this
+  directory as package data so an installed wheel carries them alongside
+  the code. Shared by every Python consumer; the sole PowerShell consumer
+  (`tokenator.ps1`) can't import Python, so it reads a **generated** JSON
+  table instead — see `generate_tokenator_table.py` below and the plan
+  doc's "Known constraint".
+- `refresh.py` — re-pulls the live litellm catalog, re-filters it to the
+  same model set, diffs against the vendored `catalog.json`, and prints a
+  report. Never applies silently — pass `--apply` to write. Price source
+  only; does not touch capability fields for Anthropic-provider rows.
+- `refresh_context.py` — re-pulls `max_input_tokens`/`max_tokens` for every
+  Anthropic-provider `catalog.json` row from Anthropic's own live Models API
+  (`client.models.retrieve()`), diffs against the vendored values, and
+  prints a report. Never applies silently — pass `--apply` to write.
+  Requires the `anthropic` package (`pip install "llm-rates[refresh]"`) and
+  a resolvable Anthropic credential (`ANTHROPIC_API_KEY`,
+  `ANTHROPIC_AUTH_TOKEN`, or an `ant auth login` profile) — never falls back
+  to a guessed value if no credential resolves. Run manually; not wired
+  into any scheduled job. `lookup()`/`cost()` never import this module or
+  touch the network — see "Context-window data" below.
+- `generate_tokenator_table.py` — emits a plain JSON price table shaped for
+  `tokenator.ps1` (a `models` map of `{input, output, context}` per model id,
+  plus flat `cache_read_multiplier`/`cache_write_multiplier` and a
+  `default` row) from `catalog.json` + `overlay.json`, so that repo can hold
+  a generated copy instead of a hand-maintained one. Deterministic — the
+  same inputs always produce byte-identical output.
+
+## Usage
+
+```python
+from llm_rates import lookup, cost, UnknownModelError
+
+record = lookup("claude-sonnet-5")
+record.input          # 2.0   ($/MTok)
+record.output          # 10.0  ($/MTok)
+record.source           # "catalog"
+record.context           # 1000000 (context-window token limit, or None)
+
+# A client-side "[1m]" resolvedModel signal (not a vendor id — see
+# overlay.json's aliases) resolves to the same price and, as of 2026-08-21,
+# the same context — the base id already reports the model's real
+# 1,000,000-token window:
+lookup("claude-sonnet-5[1m]").context   # 1000000
+
+# One-shot cost for a turn:
+usd = cost(
+    "claude-opus-4-8",
+    input_tokens=12_000,
+    output_tokens=800,
+    cache_read_tokens=50_000,
+)
+
+# An unrecognised model still resolves at its family rate:
+lookup("claude-opus-4-9").source   # "overlay-family-fallback"
+
+# A genuinely unknown vendor/model raises instead of returning $0:
+try:
+    lookup("some-new-vendor/mystery-model")
+except UnknownModelError as e:
+    ...
+```
+
+`lookup()` and `cost()` both accept optional `catalog=`/`overlay=` kwargs
+(already-loaded dicts) — useful for tests, or for a caller that wants to load
+once and reuse across many lookups instead of re-reading the JSON files each
+call.
+
+## Refreshing the catalog
+
+```bash
+python refresh.py            # pull live litellm catalog, diff, print report
+python refresh.py --apply    # also overwrite catalog.json with the diff
+```
+
+`refresh.py` always pulls the **live** GitHub-hosted catalog URL, never the
+`litellm` pip package's bundled snapshot — that bundled copy is stale (it was
+missing Haiku 4.5, Opus 5, Opus 4.8, Fable 5, and Sonnet 5 entirely as of
+2026-07-28; see the plan doc's "Two traps found").
+
+## Refreshing context-window data
+
+```bash
+python refresh_context.py            # pull the live Models API, diff, print report
+python refresh_context.py --apply    # also overwrite catalog.json with the diff
+```
+
+Context-window limits (`max_input_tokens`) and output caps
+(`max_output_tokens`) for Anthropic-provider rows come from Anthropic's own
+**Models API** (`client.models.retrieve(model_id)`), not litellm's snapshot
+— litellm is a third-party-maintained guess for these fields, and it was
+wrong at least once (see "Pricing notes worth knowing" below). `lookup()`
+itself never calls this API: it's a refresh-time-only script, exactly like
+`refresh.py`, that writes into the vendored `catalog.json`, so
+`lookup()`/`cost()` stay pure and offline (they price historical
+transcripts and run behind a PowerShell overlay with no network access).
+Requires `pip install "llm-rates[refresh]"` (the `anthropic` SDK) and a
+credential the SDK's own resolution chain can find
+(`ANTHROPIC_API_KEY`/`ANTHROPIC_AUTH_TOKEN`/`ant auth login`) — with none
+resolvable, the script fails with an actionable message and writes nothing,
+never a guessed value.
+
+## Generating tokenator's pricing table
+
+```bash
+python generate_tokenator_table.py            # print to stdout
+python generate_tokenator_table.py --out FILE  # write to FILE
+```
+
+This is a read-only export — it never touches `plugin`'s checkout. The
+consumer migration that adopts the generated bytes as `tokenator/pricing.json`
+is tracked separately. Before emitting anything, the generator proves (via
+`verify_cache_multipliers()`) that its flat cache multipliers (0.1x read,
+2.0x write of input — tuned to Claude Code's 1h-TTL cache behaviour) match
+this package's real per-model cache rates for every model tokenator prices;
+a divergence raises instead of silently drifting.
+
+## Pricing notes worth knowing
+
+- **`claude-sonnet-5` is $2.00/$10.00 per MTok, permanently** — not a
+  time-limited introductory rate. It was announced as an introductory price
+  through 2026-08-31, but the vendor cancelled the scheduled 2026-09-01 rise
+  to $3.00/$15.00 (~2026-08-17). See `overlay.json`'s `notes`.
+- **Groq OSS models list at $0.075–$0.29/MTok but bill $0.00** on the
+  portfolio's free-tier key — the vendor list price lives in `catalog.json`,
+  the actual billed rate lives in `overlay.json`'s
+  `actual_billing_overrides`. Both are correct; they answer different
+  questions.
+- **A retired/de-listed model keeps its row.** `claude-opus-4-1` (retired
+  2026-08-05) and the Groq-delisted `llama-4-scout`/`qwen3-32b` entries stay
+  priced at their historical rate so old transcripts still reprice
+  correctly — deleting a row would silently re-price past usage at whatever
+  family-fallback rate happens to apply now.
+- **`claude-fable-5`, `claude-opus-5`, and `claude-sonnet-5` all serve
+  1,000,000 tokens of context, natively** — confirmed by Anthropic's own
+  Models API. A prior `overlay.json` `context_overrides` block forced all
+  three to 200,000 (on the mistaken theory that catalog.json's
+  `max_input_tokens=1000000` was an extended-context-beta-only ceiling);
+  that override has been removed (corrected 2026-08-21, C8). Only
+  `claude-haiku-4-5` among current Claude models genuinely has a
+  200,000-token window.
+
+## Setup for consumers
+
+```bash
+pip install -e C:/data/projects/libs/llm-rates
+```
+
+Same convention as `libs/plan-doc` and `libs/triad-base` — see
+`plugin/CLAUDE.md`.
+
+## Status
+
+**Rollout step 1 of `model-catalog-consolidation.md` — the library itself,
+built and tested.** Consumer migrations (`activity_cost.py`, `sessmon`,
+`model-bench-runner.py`, `tokenator.ps1`) are steps 2–5, tracked separately
+in the plan doc and out of scope for this package's initial PR.
+
+## Testing
+
+```bash
+pytest llm-rates/tests/ -v
+```

llm_rates-0.3.0/README.md

@@ -0,0 +1,211 @@
+# llm-rates
+
+Named `llm-rates` (not `llm-prices`, its name until 2026-08-21) because
+PyPI's similarity check rejected `llm-prices` as too close to the existing
+`llmprices` project — collapsed-separator collision, not an exact-name
+clash. `llm-rates` was verified free in every form (`llm-rates`,
+`llmrates`, `llm_rates`, singular `llm-rate`/`llmrate`) before adopting it;
+don't re-litigate the name.
+
+One vendored model-price catalog + one internal overlay + a shared Python
+lookup/cost-math module, replacing four independently hand-maintained price
+tables that were drifting apart. Full origin story and decisions: this
+repo's sibling checkout `plugin/docs/plans/model-catalog-consolidation.md`
+(cross-repo — `plugin` is a separate git repository from `libs`, so this is
+a path reference, not a clickable link).
+
+## Why this exists
+
+Four tables held the same vendor facts (`plugin/scripts/prices/anthropic.json`,
+`plugin/skills/tokenator/scripts/pricing.json`,
+`sessions/src/sessmon/pricing.py`,
+`factory-bench/runs/model-bench/model-bench-runner.py`). One of them silently
+returned `$0.00` for any model it didn't recognise — a lookup bug, not a data
+bug — and under-reported real spend by over $800 in one 30-day window. This
+package fixes the *lookup logic* (never $0 for an unknown model) and gives
+the data one home.
+
+## Files
+
+- `catalog.json` — vendored snapshot of
+  [litellm's `model_prices_and_context_window.json`](https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json),
+  filtered to the providers/models the portfolio actually uses. Vendor list
+  price, per-single-token USD (litellm's native unit). Never hand-edit —
+  regenerate prices via `refresh.py --apply`; for Anthropic-provider rows,
+  the capability fields (`max_input_tokens`/`max_output_tokens`) are instead
+  kept in sync with Anthropic's own live Models API via
+  `refresh_context.py --apply` (litellm's snapshot is a third-party guess
+  for those fields, not authoritative).
+- `overlay.json` — everything no public catalog can know: actual-billing
+  overrides (e.g. Groq OSS models are free-tier here, not their list price),
+  family-rate fallbacks (`claude-opus` → tier rate, so an unrecognised new
+  model prices at its family's rate instead of $0), model-ID aliases (dated
+  suffixes → canonical key), retirement/deprecation history (a retired
+  model's row is kept, never deleted, so historical transcripts still
+  reprice correctly), `context_overrides` for the rare model whose real
+  default-served context genuinely differs from its published maximum
+  (empty as of 2026-08-21 — see "Context-window data" below), and
+  per-consumer portfolio pins.
+- `llm_rates/` — `lookup(model_id) -> PriceRecord` + cost math (in
+  `__init__.py`); `catalog.json` and `overlay.json` ship inside this
+  directory as package data so an installed wheel carries them alongside
+  the code. Shared by every Python consumer; the sole PowerShell consumer
+  (`tokenator.ps1`) can't import Python, so it reads a **generated** JSON
+  table instead — see `generate_tokenator_table.py` below and the plan
+  doc's "Known constraint".
+- `refresh.py` — re-pulls the live litellm catalog, re-filters it to the
+  same model set, diffs against the vendored `catalog.json`, and prints a
+  report. Never applies silently — pass `--apply` to write. Price source
+  only; does not touch capability fields for Anthropic-provider rows.
+- `refresh_context.py` — re-pulls `max_input_tokens`/`max_tokens` for every
+  Anthropic-provider `catalog.json` row from Anthropic's own live Models API
+  (`client.models.retrieve()`), diffs against the vendored values, and
+  prints a report. Never applies silently — pass `--apply` to write.
+  Requires the `anthropic` package (`pip install "llm-rates[refresh]"`) and
+  a resolvable Anthropic credential (`ANTHROPIC_API_KEY`,
+  `ANTHROPIC_AUTH_TOKEN`, or an `ant auth login` profile) — never falls back
+  to a guessed value if no credential resolves. Run manually; not wired
+  into any scheduled job. `lookup()`/`cost()` never import this module or
+  touch the network — see "Context-window data" below.
+- `generate_tokenator_table.py` — emits a plain JSON price table shaped for
+  `tokenator.ps1` (a `models` map of `{input, output, context}` per model id,
+  plus flat `cache_read_multiplier`/`cache_write_multiplier` and a
+  `default` row) from `catalog.json` + `overlay.json`, so that repo can hold
+  a generated copy instead of a hand-maintained one. Deterministic — the
+  same inputs always produce byte-identical output.
+
+## Usage
+
+```python
+from llm_rates import lookup, cost, UnknownModelError
+
+record = lookup("claude-sonnet-5")
+record.input          # 2.0   ($/MTok)
+record.output          # 10.0  ($/MTok)
+record.source           # "catalog"
+record.context           # 1000000 (context-window token limit, or None)
+
+# A client-side "[1m]" resolvedModel signal (not a vendor id — see
+# overlay.json's aliases) resolves to the same price and, as of 2026-08-21,
+# the same context — the base id already reports the model's real
+# 1,000,000-token window:
+lookup("claude-sonnet-5[1m]").context   # 1000000
+
+# One-shot cost for a turn:
+usd = cost(
+    "claude-opus-4-8",
+    input_tokens=12_000,
+    output_tokens=800,
+    cache_read_tokens=50_000,
+)
+
+# An unrecognised model still resolves at its family rate:
+lookup("claude-opus-4-9").source   # "overlay-family-fallback"
+
+# A genuinely unknown vendor/model raises instead of returning $0:
+try:
+    lookup("some-new-vendor/mystery-model")
+except UnknownModelError as e:
+    ...
+```
+
+`lookup()` and `cost()` both accept optional `catalog=`/`overlay=` kwargs
+(already-loaded dicts) — useful for tests, or for a caller that wants to load
+once and reuse across many lookups instead of re-reading the JSON files each
+call.
+
+## Refreshing the catalog
+
+```bash
+python refresh.py            # pull live litellm catalog, diff, print report
+python refresh.py --apply    # also overwrite catalog.json with the diff
+```
+
+`refresh.py` always pulls the **live** GitHub-hosted catalog URL, never the
+`litellm` pip package's bundled snapshot — that bundled copy is stale (it was
+missing Haiku 4.5, Opus 5, Opus 4.8, Fable 5, and Sonnet 5 entirely as of
+2026-07-28; see the plan doc's "Two traps found").
+
+## Refreshing context-window data
+
+```bash
+python refresh_context.py            # pull the live Models API, diff, print report
+python refresh_context.py --apply    # also overwrite catalog.json with the diff
+```
+
+Context-window limits (`max_input_tokens`) and output caps
+(`max_output_tokens`) for Anthropic-provider rows come from Anthropic's own
+**Models API** (`client.models.retrieve(model_id)`), not litellm's snapshot
+— litellm is a third-party-maintained guess for these fields, and it was
+wrong at least once (see "Pricing notes worth knowing" below). `lookup()`
+itself never calls this API: it's a refresh-time-only script, exactly like
+`refresh.py`, that writes into the vendored `catalog.json`, so
+`lookup()`/`cost()` stay pure and offline (they price historical
+transcripts and run behind a PowerShell overlay with no network access).
+Requires `pip install "llm-rates[refresh]"` (the `anthropic` SDK) and a
+credential the SDK's own resolution chain can find
+(`ANTHROPIC_API_KEY`/`ANTHROPIC_AUTH_TOKEN`/`ant auth login`) — with none
+resolvable, the script fails with an actionable message and writes nothing,
+never a guessed value.
+
+## Generating tokenator's pricing table
+
+```bash
+python generate_tokenator_table.py            # print to stdout
+python generate_tokenator_table.py --out FILE  # write to FILE
+```
+
+This is a read-only export — it never touches `plugin`'s checkout. The
+consumer migration that adopts the generated bytes as `tokenator/pricing.json`
+is tracked separately. Before emitting anything, the generator proves (via
+`verify_cache_multipliers()`) that its flat cache multipliers (0.1x read,
+2.0x write of input — tuned to Claude Code's 1h-TTL cache behaviour) match
+this package's real per-model cache rates for every model tokenator prices;
+a divergence raises instead of silently drifting.
+
+## Pricing notes worth knowing
+
+- **`claude-sonnet-5` is $2.00/$10.00 per MTok, permanently** — not a
+  time-limited introductory rate. It was announced as an introductory price
+  through 2026-08-31, but the vendor cancelled the scheduled 2026-09-01 rise
+  to $3.00/$15.00 (~2026-08-17). See `overlay.json`'s `notes`.
+- **Groq OSS models list at $0.075–$0.29/MTok but bill $0.00** on the
+  portfolio's free-tier key — the vendor list price lives in `catalog.json`,
+  the actual billed rate lives in `overlay.json`'s
+  `actual_billing_overrides`. Both are correct; they answer different
+  questions.
+- **A retired/de-listed model keeps its row.** `claude-opus-4-1` (retired
+  2026-08-05) and the Groq-delisted `llama-4-scout`/`qwen3-32b` entries stay
+  priced at their historical rate so old transcripts still reprice
+  correctly — deleting a row would silently re-price past usage at whatever
+  family-fallback rate happens to apply now.
+- **`claude-fable-5`, `claude-opus-5`, and `claude-sonnet-5` all serve
+  1,000,000 tokens of context, natively** — confirmed by Anthropic's own
+  Models API. A prior `overlay.json` `context_overrides` block forced all
+  three to 200,000 (on the mistaken theory that catalog.json's
+  `max_input_tokens=1000000` was an extended-context-beta-only ceiling);
+  that override has been removed (corrected 2026-08-21, C8). Only
+  `claude-haiku-4-5` among current Claude models genuinely has a
+  200,000-token window.
+
+## Setup for consumers
+
+```bash
+pip install -e C:/data/projects/libs/llm-rates
+```
+
+Same convention as `libs/plan-doc` and `libs/triad-base` — see
+`plugin/CLAUDE.md`.
+
+## Status
+
+**Rollout step 1 of `model-catalog-consolidation.md` — the library itself,
+built and tested.** Consumer migrations (`activity_cost.py`, `sessmon`,
+`model-bench-runner.py`, `tokenator.ps1`) are steps 2–5, tracked separately
+in the plan doc and out of scope for this package's initial PR.
+
+## Testing
+
+```bash
+pytest llm-rates/tests/ -v
+```

llm_rates-0.3.0/generate_tokenator_table.py

@@ -0,0 +1,192 @@
+"""Generate a plain JSON price table for tokenator.ps1 — the sole PowerShell
+consumer of this package's data, which can't `import llm_rates` and instead
+reads a generated JSON file directly (see README.md's "Known constraint").
+
+Deterministic: the same catalog.json/overlay.json inputs always produce
+byte-identical output, so a downstream drift test in the tokenator skill's
+own repo can assert its committed pricing.json matches a fresh generation.
+
+Usage:
+    python generate_tokenator_table.py            # print to stdout
+    python generate_tokenator_table.py --out FILE  # write to FILE
+
+Never writes tokenator's actual pricing.json from this repo — that file
+lives in a separate repository (plugin) and is owned by a separate
+migration; this script only produces the bytes for that migration to adopt.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from llm_rates import load_catalog, load_overlay, lookup
+
+# Order matters for output determinism/readability — mirrors tokenator's
+# existing pricing.json key order exactly. Each key IS the model_id passed
+# to lookup(): the bare family ids ("claude-opus", "claude-sonnet",
+# "claude-haiku") resolve via overlay.json's family_fallback (no specific
+# version pinned), and the "[1m]" entries are client-side resolvedModel
+# signals (not vendor ids) that resolve via overlay.json's aliases +
+# context_overrides — see llm_rates.py's module docstring "Context-window
+# limits" section and overlay.json's notes.
+TOKENATOR_MODEL_IDS = [
+    "claude-fable-5",
+    "claude-mythos-5",
+    "claude-opus-5[1m]",
+    "claude-opus",
+    "claude-sonnet-5[1m]",
+    "claude-sonnet-5",
+    "claude-sonnet",
+    "claude-haiku",
+]
+
+# tokenator.ps1 uses flat cache multipliers tuned to Claude Code's 1h-TTL
+# cache behaviour: reads at 0.1x input, writes at 2.0x input (the 1h-TTL
+# creation rate — Claude Code writes 1h-TTL caches exclusively; see
+# tokenator/pricing.json's own _comment). These are not independently
+# invented constants: verify_cache_multipliers() below proves, for every
+# model in TOKENATOR_MODEL_IDS, that the lib's real per-model
+# cache_read/cache_creation_1h rates divide by that model's input rate to
+# exactly these two numbers, before build_table() ever emits them. If a
+# future catalog update broke that identity for any model, this raises
+# instead of silently drifting from what tokenator actually bills.
+CACHE_READ_MULTIPLIER = 0.1
+CACHE_WRITE_MULTIPLIER = 2.0
+
+# tokenator's "default" row (used when no prefix in its models map matches)
+# has always carried the claude-opus family rate — same lookup id used for
+# the bare "claude-opus" entry above.
+DEFAULT_MODEL_ID = "claude-opus"
+
+_RATIO_TOLERANCE = 1e-9
+
+
+def verify_cache_multipliers(
+    model_ids: list[str],
+    *,
+    catalog: dict[str, Any] | None = None,
+    overlay: dict[str, Any] | None = None,
+) -> None:
+    """Raise ValueError if any model's real cache_read/cache_creation_1h
+    rate diverges from the flat CACHE_READ_MULTIPLIER/CACHE_WRITE_MULTIPLIER
+    this module emits. Called by build_table() before it writes anything.
+    """
+    for model_id in model_ids:
+        record = lookup(model_id, catalog=catalog, overlay=overlay)
+        if record.input == 0:
+            # Free-tier override (not reachable for any current tokenator
+            # id, but guarded for future-proofing) — ratio is undefined.
+            continue
+        read_ratio = record.cache_read / record.input
+        write_ratio = record.cache_creation_1h / record.input
+        if abs(read_ratio - CACHE_READ_MULTIPLIER) > _RATIO_TOLERANCE:
+            raise ValueError(
+                f"{model_id}: cache_read/input ratio {read_ratio!r} does not "
+                f"match declared CACHE_READ_MULTIPLIER {CACHE_READ_MULTIPLIER!r} "
+                "— tokenator's flat multiplier would silently diverge from "
+                "the lib's real rate for this model."
+            )
+        if abs(write_ratio - CACHE_WRITE_MULTIPLIER) > _RATIO_TOLERANCE:
+            raise ValueError(
+                f"{model_id}: cache_creation_1h/input ratio {write_ratio!r} "
+                f"does not match declared CACHE_WRITE_MULTIPLIER "
+                f"{CACHE_WRITE_MULTIPLIER!r}."
+            )
+
+
+def build_table(
+    *,
+    catalog: dict[str, Any] | None = None,
+    overlay: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Pure function: build the tokenator-shaped pricing dict from the
+    catalog + overlay. No I/O beyond catalog=/overlay=None triggering the
+    package's own load_catalog()/load_overlay().
+    """
+    catalog = catalog if catalog is not None else load_catalog()
+    overlay = overlay if overlay is not None else load_overlay()
+
+    verify_cache_multipliers(TOKENATOR_MODEL_IDS, catalog=catalog, overlay=overlay)
+
+    models: dict[str, Any] = {}
+    for model_id in TOKENATOR_MODEL_IDS:
+        record = lookup(model_id, catalog=catalog, overlay=overlay)
+        if record.context is None:
+            raise ValueError(
+                f"{model_id}: lookup() resolved no context-window value — "
+                "tokenator needs a context for every emitted model; refusing "
+                "to emit a guessed number. Add a context_overrides row (or a "
+                "family_fallback 'context' field) in overlay.json."
+            )
+        models[model_id] = {
+            "input": record.input,
+            "output": record.output,
+            "context": record.context,
+        }
+
+    default_record = lookup(DEFAULT_MODEL_ID, catalog=catalog, overlay=overlay)
+    if default_record.context is None:
+        raise ValueError(f"{DEFAULT_MODEL_ID}: no context-window value for default row.")
+
+    return {
+        "_comment": (
+            "USD per million tokens. GENERATED by "
+            "libs/llm-rates/generate_tokenator_table.py from llm-rates' "
+            "catalog.json + overlay.json — do not hand-edit; regenerate "
+            "instead. Cache multipliers are flat (read 0.1x, write 2.0x of "
+            "input) because Claude Code uses 1h-TTL cache writes exclusively; "
+            "the generator's verify_cache_multipliers() proves per-model "
+            "that this matches the lib's real per-token cache rates before "
+            "every generation. Longest-prefix match on model id; 'default' "
+            "used when no prefix matches. 'context' is the model's "
+            "context-window token limit. The bracketed '[1m]' entries are "
+            "client-side resolvedModel signals (tokenator.ps1's Get-Context) "
+            "for the 1M-context beta, not vendor model ids -- the base model "
+            "id never carries a bracket suffix on its own."
+        ),
+        "models": models,
+        "cache_read_multiplier": CACHE_READ_MULTIPLIER,
+        "cache_write_multiplier": CACHE_WRITE_MULTIPLIER,
+        "default": {
+            "input": default_record.input,
+            "output": default_record.output,
+            "context": default_record.context,
+        },
+    }
+
+
+def render_json(table: dict[str, Any]) -> str:
+    """Deterministic JSON rendering — same table -> byte-identical string
+    every call. Trailing newline matches the existing hand-maintained file.
+    """
+    return json.dumps(table, indent=2) + "\n"
+
+
+def _cli(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--out",
+        type=Path,
+        default=None,
+        help="Write to this path instead of stdout.",
+    )
+    args = parser.parse_args(argv)
+
+    table = build_table()
+    rendered = render_json(table)
+
+    if args.out is not None:
+        args.out.write_text(rendered, encoding="utf-8", newline="\n")
+        print(f"Wrote {args.out}", file=sys.stderr)
+    else:
+        sys.stdout.write(rendered)
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(_cli())