coding-agent-cost 0.3.0__tar.gz → 0.5.0__tar.gz

{coding_agent_cost-0.3.0/coding_agent_cost.egg-info → coding_agent_cost-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-agent-cost
-Version: 0.3.0
+Version: 0.5.0
 Summary: Estimate AI coding agent (Claude Code / Codex CLI) token usage and cost from local logs
 Author: shiki-yusuke
 License: MIT
@@ -200,6 +200,114 @@ If another program wants to parse agent-cost's output for one or more
 specific session ids, see `agent-cost measure` below rather than
 scraping `report`.
 
+## Internal billing plan (optional, confidential)
+
+Some organizations bill Claude seats internally with their own rules -- a
+fixed subscription per billing window, a usage allowance measured in
+list-price dollars, and a discounted rate above it. `report --billing-plan
+PATH` applies such a plan to the Claude usage agent-cost already prices at
+the public catalog. Nothing changes without the flag, and there is no
+default path or environment variable that turns it on.
+
+```bash
+agent-cost report --billing-plan ~/private/billing-plan.json \
+  --since 2030-01-01T00:00:00+00:00 --until 2030-02-01T00:00:00+00:00 --format json
+```
+
+A plan (`plan_schema_version` `"1"`; every value below is made up):
+
+```json
+{
+  "plan_schema_version": "1",
+  "plan_id": "bp-example",
+  "nonce": "0123456789abcdef0123456789abcdef",
+  "applies_to": {"agent": "claude", "scope": "seat"},
+  "basis": "agent-cost-list-price",
+  "periods": [
+    {"period_id": "p1", "effective_from": "2030-01-01T00:00:00+00:00",
+     "window_subscription_usd": "3", "allowance_usd": null, "overage": null},
+    {"period_id": "p2", "effective_from": "2030-01-11T00:00:00+00:00",
+     "window_subscription_usd": "10", "allowance_usd": "50",
+     "overage": {"type": "charge_multiplier", "value": "0.5"}},
+    {"period_id": "end", "effective_from": "2030-02-01T00:00:00+00:00", "terminates": true}
+  ]
+}
+```
+
+- `periods` is a list of finite billing windows: window *i* is
+  `[effective_from_i, effective_from_{i+1})`, and the last entry must be
+  `{period_id, effective_from, terminates: true}` so that no window is
+  open-ended. Write one window per billing month (or per contract change).
+  `effective_from` needs a UTC offset and no sub-second part.
+- `window_subscription_usd` is the fixed amount billed for that window, as
+  you write it -- agent-cost never prorates it.
+- `allowance_usd` is the window's usage allowance in list-price dollars.
+  `null` means the window has no overage concept at all (it is not a zero
+  allowance), and then `overage` must be `null` too.
+- `overage` prices `max(0, list_cost - allowance)`:
+  `{"type": "charge_multiplier", "value": "0.5"}` charges overage × value
+  (`0 <= value <= 1`), and `{"type": "block_discount", "block_usd": "5",
+  "discount_usd": "1"}` charges overage minus `floor(overage / block_usd) ×
+  discount_usd` (`0 < discount_usd <= block_usd`).
+- Amounts are decimal strings only (no JSON numbers), at most 28
+  significant digits. `plan_id` is `[A-Za-z0-9_-]{1,32}`, `period_id`
+  `[A-Za-z0-9_-]{1,16}`, `nonce` 32 lowercase hex characters (e.g.
+  `python3 -c 'import secrets; print(secrets.token_hex(16))'`). Unknown or
+  duplicate keys are errors. v1 only accepts `scope: "seat"`: an allowance
+  shared by a department or org cannot be computed from one person's logs.
+
+The JSON output gains an `internal_billing` block (existing keys are
+unchanged), and the table gains a section headed `Internal billing
+(CONFIDENTIAL -- do not share)`. For each window that intersects
+`[since, until)` it shows `list_cost_usd` (Claude facts in the window,
+priced at the packaged catalog), `allowance_usd`, `overage_usd`,
+`overage_cost_usd`, `window_subscription_usd`, `internal_cost_usd` --
+all as 4-decimal strings -- and four separate status fields:
+
+- `query_coverage`: `full` when `--since`/`--until` cover the whole
+  window, otherwise `partial`. It says nothing about whether the logs
+  themselves are complete (deleted transcripts, other machines, API or web
+  usage are never seen; see `data_quality` at the top level as well).
+- `window_state`: `closed` once the window has ended (`until <=
+  generated_at`), otherwise `open`.
+- `list_cost_pricing`: `priced`, `lower_bound` (some facts were unpriced
+  or only priced as a lower bound, or an output fact's tokens are only a
+  lower bound -- `source_quality: "output_lower_bound"`) or
+  `no_usage_observed`.
+- `internal_cost_certainty`: `estimate` only when the window is fully
+  queried, closed and `priced`. Otherwise `lower_bound` for windows with no
+  overage or `charge_multiplier` (more usage can only raise the amount), and
+  `indeterminate` for `block_discount` (more usage can cross a block
+  boundary and lower it). This describes what can be derived from the
+  observed list cost -- it is not a statement that the number matches an
+  actual invoice.
+
+`window_subscription_usd` in each row is the plan's input echoed back, not
+an amount allocated to your query. `internal_cost_usd` is the cost of the
+whole billing window computed from the usage visible in this report -- it
+is not the cost of the `[since, until)` range, so do not sum windows to get
+one. `plan_coverage: partial` with `uncovered` ranges flags the parts of
+`[since, until)` that no window covers (before the first window or after
+`terminates`); usage there is not billed.
+
+`measure` has no billing plan option on purpose: a per-session internal
+cost would mean allocating a window-level charge across sessions.
+`--billing-plan` cannot be combined with `--rates` (the basis must be the
+packaged public catalog), `--format csv`, an `--agent` list without
+`claude`, or a missing `--since`/`--until`; any of those, an unreadable or
+invalid plan, or a calculation that would need rounding exits 2 with
+nothing on stdout. `AGENT_COST_NOW` (an ISO 8601 instant with a UTC offset)
+pins `generated_at`, and with it `window_state`, for reproducible runs.
+
+**Keep the plan and its output private.** The plan must be a regular file
+owned by you with mode `0600` (or stricter), reached without any symlink in
+its path (on macOS `/tmp` and `/var` are symlinks -- keep it under your
+home directory), and not inside a git repository or worktree. Error messages
+never print plan values or the path. Output produced with the plan is
+confidential: agent-cost has no redaction, so mind your terminal scrollback,
+shell history, and the permissions of any file you redirect it to, and keep
+it out of shared logs, CI, artifacts and ledgers.
+
 ## What this measures, and what it doesn't
 
 agent-cost only reads data that is already on disk. It never talks to the
@@ -244,6 +352,16 @@ network, never calls `gh`, and never resolves branches or PRs.
   present in the log, it's used; otherwise the cache-write tokens are priced
   at the 5-minute rate as an explicit **lower bound** and flagged
   `lower_bound` rather than guessed at the (more expensive) 1-hour rate.
+  Each Claude fact also carries its request's prompt length
+  (`prompt_tokens` = `input_tokens` + `cache_read_input_tokens` +
+  `cache_creation_input_tokens`), used only to pick the tier of a model
+  whose price depends on prompt length (`claude-haiku-5-5`).
+- **Prompt-length tiers need a known prompt length.** A fact whose prompt
+  length is unknown -- every Codex fact (a delta of cumulative totals, not
+  one request), a Claude fact from a conflicting dedup group, or a Claude
+  row whose cache-write TTL breakdown exceeds its `cache_creation_input_tokens`
+  -- is priced at the model's base (cheapest) tier and flagged
+  `lower_bound`. Models without tiers are unaffected.
 - **Codex CLI**: rollout files record a *cumulative* token count after each
   turn; agent-cost turns that into per-turn deltas. Under the Codex token-rate
   tariff used here, cache writes are not added as a separate charge. The current
@@ -303,6 +421,37 @@ carries a `catalog_version`, a list of `sources` (the pricing page a rate
 came from), and is validated on load (no duplicate model keys or aliases,
 no negative rates, no overlapping periods for the same model).
 
+A rate period can price by prompt length (catalog `schema_version` `"2"`).
+The period's own five values are the base tier, for prompts up to the first
+threshold; each entry in `prompt_tiers` applies to prompts *strictly over*
+its `prompt_tokens_over`, and a request uses the largest threshold it
+exceeds. Prompt length is the request's input + cache-read + cache-write
+tokens, and the chosen tier prices every token kind of that request,
+output included:
+
+```json
+{
+  "rate_id": "claude-haiku-5-5-launch-2026-10-07",
+  "effective_from": "2026-10-07T00:00:00+00:00",
+  "effective_until": null,
+  "input_nocache": "0.10", "cache_read": "0.01", "cache_write_5m": "0.125", "cache_write_1h": "0.20", "output": "0.50",
+  "prompt_tiers": [
+    { "prompt_tokens_over": 100000,
+      "input_nocache": "0.50", "cache_read": "0.05", "cache_write_5m": "0.625", "cache_write_1h": "1.0", "output": "2.50" }
+  ]
+}
+```
+
+In a period with `prompt_tiers`, all five values of the base and of every
+tier must be present and non-null, thresholds must be positive integers in
+ascending order without duplicates, and every value must be greater than or
+equal to the same value in the previous tier (the base first). That
+monotonicity is what makes the base tier a true lower bound for a fact whose
+prompt length is unknown. A `schema_version` `"1"` catalog may not contain
+`prompt_tiers`; agent-cost 0.3.0 and earlier reject a `"2"` catalog as
+unsupported rather than mispricing it, so a custom `--rates` file that uses
+tiers must declare `"2"`.
+
 To use your own catalog instead of the one bundled with the package, pass
 `--rates path/to/rates.json` to `report` or `export` -- this fully replaces
 the bundled catalog, it does not merge with it. Inspect any catalog with:
@@ -402,10 +551,11 @@ agent-cost makes zero network calls. `agent-cost export`'s JSONL never
 includes absolute file paths, rollout paths, prompt/message content, or git
 branch names -- only the fields needed to reproduce a cost estimate:
 `occurred_at_utc`, `agent`, `session_id`, `model_raw`, `model_key`,
-`token_kind`, `tokens`, `mode`, and `source_quality` (a fixed-vocabulary
+`token_kind`, `tokens`, `mode`, `source_quality` (a fixed-vocabulary
 caveat about how that one fact was derived: `"ok"`, Codex's
 `"first_event_delta"`, or Claude's `"identity_missing"` /
-`"output_lower_bound"` -- never null).
+`"output_lower_bound"` -- never null), and `prompt_tokens` (the request's
+prompt length as an integer, or null when unknown).
 
 ## License
 
@@ -429,10 +579,17 @@ MIT. See [LICENSE](LICENSE).
   未知のモデル・単価表にない token 種別は `unpriced` として扱い、憶測の価格を出しません。
 - 単価表 (`agent_cost/rates.json`) は履歴型カタログで、値上げは新しい期間として追加します。
   `--rates PATH` で別カタログに完全差し替えできます。
+- prompt 長で単価が変わるモデル（`claude-haiku-5-5`、100,000 tokens 超で高い単価）は期間の
+  `prompt_tiers`（schema_version `"2"`）で表し、リクエストごとの prompt 長（input + cache read +
+  cache write）で tier を選びます。prompt 長が不明な fact（Codex 由来、conflicting group、usage
+  不整合）は基底 tier（最安）で **下限推計**（`lower_bound`）になります。
 - `agent-cost measure --session-id ID [--session-id ID ...] --format json` は他プログラムから
   subprocess で叩くための機械可読な契約です（`protocol_version: "measure/v1"`）。指定した
   session_id が1件も見つからなくても終了コードは0（空集計として表現）、`--session-id` 未指定など
   の入力エラーのみ終了コード2です。
+- `report --billing-plan PATH`（任意・機密）は、ローカルの課金プラン（窓ごとの定額・利用枠・超過規則）を
+  公開単価で集計した Claude の list_cost に当てて `internal_billing` を出します。フラグ無しの出力は不変です。
+- plan ファイルは 0600・symlink 不可・git repo 外に置き、出力は機密成果物として扱います（`measure` には按分になるため無し）。
 - 破損したログ行、読めなくなったファイル、Codex の累積カウンタが逆行するケースなどは、すべて
   `data_quality` に件数として記録し、黙って丸めたり捨てたりしません。
 - Codex の `output` は `output_tokens` のみです。実 rollout データを突合した結果

{coding_agent_cost-0.3.0 → coding_agent_cost-0.5.0}/README.md

@@ -174,6 +174,114 @@ If another program wants to parse agent-cost's output for one or more
 specific session ids, see `agent-cost measure` below rather than
 scraping `report`.
 
+## Internal billing plan (optional, confidential)
+
+Some organizations bill Claude seats internally with their own rules -- a
+fixed subscription per billing window, a usage allowance measured in
+list-price dollars, and a discounted rate above it. `report --billing-plan
+PATH` applies such a plan to the Claude usage agent-cost already prices at
+the public catalog. Nothing changes without the flag, and there is no
+default path or environment variable that turns it on.
+
+```bash
+agent-cost report --billing-plan ~/private/billing-plan.json \
+  --since 2030-01-01T00:00:00+00:00 --until 2030-02-01T00:00:00+00:00 --format json
+```
+
+A plan (`plan_schema_version` `"1"`; every value below is made up):
+
+```json
+{
+  "plan_schema_version": "1",
+  "plan_id": "bp-example",
+  "nonce": "0123456789abcdef0123456789abcdef",
+  "applies_to": {"agent": "claude", "scope": "seat"},
+  "basis": "agent-cost-list-price",
+  "periods": [
+    {"period_id": "p1", "effective_from": "2030-01-01T00:00:00+00:00",
+     "window_subscription_usd": "3", "allowance_usd": null, "overage": null},
+    {"period_id": "p2", "effective_from": "2030-01-11T00:00:00+00:00",
+     "window_subscription_usd": "10", "allowance_usd": "50",
+     "overage": {"type": "charge_multiplier", "value": "0.5"}},
+    {"period_id": "end", "effective_from": "2030-02-01T00:00:00+00:00", "terminates": true}
+  ]
+}
+```
+
+- `periods` is a list of finite billing windows: window *i* is
+  `[effective_from_i, effective_from_{i+1})`, and the last entry must be
+  `{period_id, effective_from, terminates: true}` so that no window is
+  open-ended. Write one window per billing month (or per contract change).
+  `effective_from` needs a UTC offset and no sub-second part.
+- `window_subscription_usd` is the fixed amount billed for that window, as
+  you write it -- agent-cost never prorates it.
+- `allowance_usd` is the window's usage allowance in list-price dollars.
+  `null` means the window has no overage concept at all (it is not a zero
+  allowance), and then `overage` must be `null` too.
+- `overage` prices `max(0, list_cost - allowance)`:
+  `{"type": "charge_multiplier", "value": "0.5"}` charges overage × value
+  (`0 <= value <= 1`), and `{"type": "block_discount", "block_usd": "5",
+  "discount_usd": "1"}` charges overage minus `floor(overage / block_usd) ×
+  discount_usd` (`0 < discount_usd <= block_usd`).
+- Amounts are decimal strings only (no JSON numbers), at most 28
+  significant digits. `plan_id` is `[A-Za-z0-9_-]{1,32}`, `period_id`
+  `[A-Za-z0-9_-]{1,16}`, `nonce` 32 lowercase hex characters (e.g.
+  `python3 -c 'import secrets; print(secrets.token_hex(16))'`). Unknown or
+  duplicate keys are errors. v1 only accepts `scope: "seat"`: an allowance
+  shared by a department or org cannot be computed from one person's logs.
+
+The JSON output gains an `internal_billing` block (existing keys are
+unchanged), and the table gains a section headed `Internal billing
+(CONFIDENTIAL -- do not share)`. For each window that intersects
+`[since, until)` it shows `list_cost_usd` (Claude facts in the window,
+priced at the packaged catalog), `allowance_usd`, `overage_usd`,
+`overage_cost_usd`, `window_subscription_usd`, `internal_cost_usd` --
+all as 4-decimal strings -- and four separate status fields:
+
+- `query_coverage`: `full` when `--since`/`--until` cover the whole
+  window, otherwise `partial`. It says nothing about whether the logs
+  themselves are complete (deleted transcripts, other machines, API or web
+  usage are never seen; see `data_quality` at the top level as well).
+- `window_state`: `closed` once the window has ended (`until <=
+  generated_at`), otherwise `open`.
+- `list_cost_pricing`: `priced`, `lower_bound` (some facts were unpriced
+  or only priced as a lower bound, or an output fact's tokens are only a
+  lower bound -- `source_quality: "output_lower_bound"`) or
+  `no_usage_observed`.
+- `internal_cost_certainty`: `estimate` only when the window is fully
+  queried, closed and `priced`. Otherwise `lower_bound` for windows with no
+  overage or `charge_multiplier` (more usage can only raise the amount), and
+  `indeterminate` for `block_discount` (more usage can cross a block
+  boundary and lower it). This describes what can be derived from the
+  observed list cost -- it is not a statement that the number matches an
+  actual invoice.
+
+`window_subscription_usd` in each row is the plan's input echoed back, not
+an amount allocated to your query. `internal_cost_usd` is the cost of the
+whole billing window computed from the usage visible in this report -- it
+is not the cost of the `[since, until)` range, so do not sum windows to get
+one. `plan_coverage: partial` with `uncovered` ranges flags the parts of
+`[since, until)` that no window covers (before the first window or after
+`terminates`); usage there is not billed.
+
+`measure` has no billing plan option on purpose: a per-session internal
+cost would mean allocating a window-level charge across sessions.
+`--billing-plan` cannot be combined with `--rates` (the basis must be the
+packaged public catalog), `--format csv`, an `--agent` list without
+`claude`, or a missing `--since`/`--until`; any of those, an unreadable or
+invalid plan, or a calculation that would need rounding exits 2 with
+nothing on stdout. `AGENT_COST_NOW` (an ISO 8601 instant with a UTC offset)
+pins `generated_at`, and with it `window_state`, for reproducible runs.
+
+**Keep the plan and its output private.** The plan must be a regular file
+owned by you with mode `0600` (or stricter), reached without any symlink in
+its path (on macOS `/tmp` and `/var` are symlinks -- keep it under your
+home directory), and not inside a git repository or worktree. Error messages
+never print plan values or the path. Output produced with the plan is
+confidential: agent-cost has no redaction, so mind your terminal scrollback,
+shell history, and the permissions of any file you redirect it to, and keep
+it out of shared logs, CI, artifacts and ledgers.
+
 ## What this measures, and what it doesn't
 
 agent-cost only reads data that is already on disk. It never talks to the
@@ -218,6 +326,16 @@ network, never calls `gh`, and never resolves branches or PRs.
   present in the log, it's used; otherwise the cache-write tokens are priced
   at the 5-minute rate as an explicit **lower bound** and flagged
   `lower_bound` rather than guessed at the (more expensive) 1-hour rate.
+  Each Claude fact also carries its request's prompt length
+  (`prompt_tokens` = `input_tokens` + `cache_read_input_tokens` +
+  `cache_creation_input_tokens`), used only to pick the tier of a model
+  whose price depends on prompt length (`claude-haiku-5-5`).
+- **Prompt-length tiers need a known prompt length.** A fact whose prompt
+  length is unknown -- every Codex fact (a delta of cumulative totals, not
+  one request), a Claude fact from a conflicting dedup group, or a Claude
+  row whose cache-write TTL breakdown exceeds its `cache_creation_input_tokens`
+  -- is priced at the model's base (cheapest) tier and flagged
+  `lower_bound`. Models without tiers are unaffected.
 - **Codex CLI**: rollout files record a *cumulative* token count after each
   turn; agent-cost turns that into per-turn deltas. Under the Codex token-rate
   tariff used here, cache writes are not added as a separate charge. The current
@@ -277,6 +395,37 @@ carries a `catalog_version`, a list of `sources` (the pricing page a rate
 came from), and is validated on load (no duplicate model keys or aliases,
 no negative rates, no overlapping periods for the same model).
 
+A rate period can price by prompt length (catalog `schema_version` `"2"`).
+The period's own five values are the base tier, for prompts up to the first
+threshold; each entry in `prompt_tiers` applies to prompts *strictly over*
+its `prompt_tokens_over`, and a request uses the largest threshold it
+exceeds. Prompt length is the request's input + cache-read + cache-write
+tokens, and the chosen tier prices every token kind of that request,
+output included:
+
+```json
+{
+  "rate_id": "claude-haiku-5-5-launch-2026-10-07",
+  "effective_from": "2026-10-07T00:00:00+00:00",
+  "effective_until": null,
+  "input_nocache": "0.10", "cache_read": "0.01", "cache_write_5m": "0.125", "cache_write_1h": "0.20", "output": "0.50",
+  "prompt_tiers": [
+    { "prompt_tokens_over": 100000,
+      "input_nocache": "0.50", "cache_read": "0.05", "cache_write_5m": "0.625", "cache_write_1h": "1.0", "output": "2.50" }
+  ]
+}
+```
+
+In a period with `prompt_tiers`, all five values of the base and of every
+tier must be present and non-null, thresholds must be positive integers in
+ascending order without duplicates, and every value must be greater than or
+equal to the same value in the previous tier (the base first). That
+monotonicity is what makes the base tier a true lower bound for a fact whose
+prompt length is unknown. A `schema_version` `"1"` catalog may not contain
+`prompt_tiers`; agent-cost 0.3.0 and earlier reject a `"2"` catalog as
+unsupported rather than mispricing it, so a custom `--rates` file that uses
+tiers must declare `"2"`.
+
 To use your own catalog instead of the one bundled with the package, pass
 `--rates path/to/rates.json` to `report` or `export` -- this fully replaces
 the bundled catalog, it does not merge with it. Inspect any catalog with:
@@ -376,10 +525,11 @@ agent-cost makes zero network calls. `agent-cost export`'s JSONL never
 includes absolute file paths, rollout paths, prompt/message content, or git
 branch names -- only the fields needed to reproduce a cost estimate:
 `occurred_at_utc`, `agent`, `session_id`, `model_raw`, `model_key`,
-`token_kind`, `tokens`, `mode`, and `source_quality` (a fixed-vocabulary
+`token_kind`, `tokens`, `mode`, `source_quality` (a fixed-vocabulary
 caveat about how that one fact was derived: `"ok"`, Codex's
 `"first_event_delta"`, or Claude's `"identity_missing"` /
-`"output_lower_bound"` -- never null).
+`"output_lower_bound"` -- never null), and `prompt_tokens` (the request's
+prompt length as an integer, or null when unknown).
 
 ## License
 
@@ -403,10 +553,17 @@ MIT. See [LICENSE](LICENSE).
   未知のモデル・単価表にない token 種別は `unpriced` として扱い、憶測の価格を出しません。
 - 単価表 (`agent_cost/rates.json`) は履歴型カタログで、値上げは新しい期間として追加します。
   `--rates PATH` で別カタログに完全差し替えできます。
+- prompt 長で単価が変わるモデル（`claude-haiku-5-5`、100,000 tokens 超で高い単価）は期間の
+  `prompt_tiers`（schema_version `"2"`）で表し、リクエストごとの prompt 長（input + cache read +
+  cache write）で tier を選びます。prompt 長が不明な fact（Codex 由来、conflicting group、usage
+  不整合）は基底 tier（最安）で **下限推計**（`lower_bound`）になります。
 - `agent-cost measure --session-id ID [--session-id ID ...] --format json` は他プログラムから
   subprocess で叩くための機械可読な契約です（`protocol_version: "measure/v1"`）。指定した
   session_id が1件も見つからなくても終了コードは0（空集計として表現）、`--session-id` 未指定など
   の入力エラーのみ終了コード2です。
+- `report --billing-plan PATH`（任意・機密）は、ローカルの課金プラン（窓ごとの定額・利用枠・超過規則）を
+  公開単価で集計した Claude の list_cost に当てて `internal_billing` を出します。フラグ無しの出力は不変です。
+- plan ファイルは 0600・symlink 不可・git repo 外に置き、出力は機密成果物として扱います（`measure` には按分になるため無し）。
 - 破損したログ行、読めなくなったファイル、Codex の累積カウンタが逆行するケースなどは、すべて
   `data_quality` に件数として記録し、黙って丸めたり捨てたりしません。
 - Codex の `output` は `output_tokens` のみです。実 rollout データを突合した結果

{coding_agent_cost-0.3.0 → coding_agent_cost-0.5.0}/agent_cost/__init__.py

@@ -6,4 +6,4 @@ against a versioned rate catalog. Everything happens locally; there are no
 network calls.
 """
 
-__version__ = "0.3.0"
+__version__ = "0.5.0"

{coding_agent_cost-0.3.0 → coding_agent_cost-0.5.0}/agent_cost/aggregate.py

@@ -28,6 +28,11 @@ def price_fact(catalog: RateCatalog, fact: Fact) -> Tuple[Optional[Decimal], str
     never at the more expensive 1-hour rate -- and flagged accordingly.
     An unrecognized model or an unpriced token kind for an otherwise-known
     model both return ``(None, "unpriced", None)`` rather than a guess.
+
+    For a period with ``prompt_tiers``, the fact is priced at the tier with
+    the largest ``prompt_tokens_over`` its ``prompt_tokens`` exceeds (the
+    base values when none). A fact whose ``prompt_tokens`` is unknown is
+    priced at the base values -- the cheapest tier -- as a lower bound.
     """
     resolved_key, period = catalog.rate_for(fact.model_key, fact.occurred_at_utc)
     if resolved_key is None or period is None:
@@ -47,7 +52,16 @@ def price_fact(catalog: RateCatalog, fact: Fact) -> Tuple[Optional[Decimal], str
         rate_field = "cache_write_5m"
         lower_bound = True
 
-    rate = period.values.get(rate_field)
+    values = period.values
+    if period.prompt_tiers:
+        if fact.prompt_tokens is None:
+            lower_bound = True
+        else:
+            for tier in period.prompt_tiers:
+                if fact.prompt_tokens > tier.prompt_tokens_over:
+                    values = tier.values
+
+    rate = values.get(rate_field)
     if rate is None:
         return None, "unpriced", None