fix(cost): bill 1h cache writes at 2x using the usage cache_creation TTL split

[Brian Krabach (bkrabach)]

The bug

_cost.py (around line 141-143, in the Fable-5 rate block, with the same
behavior applying to every model) billed all prompt-cache writes at the
5-minute (1.25x) rate, with this comment:

A 1-hour cache write tier exists at $20.00/MTok but Anthropic's usage
object returns a single cache_creation_input_tokens count and does not
distinguish TTLs — track the 5-minute rate ($12.50) here.

That comment is stale. Verified directly against this repo's pinned SDK
version (anthropic>=1.0.0,<2.0.0, resolves to exactly 1.0.0 via
uv sync):

>>> import anthropic; anthropic.__version__
'1.0.0'
>>> from anthropic.types import Usage
class Usage(BaseModel):
    cache_creation: Optional[CacheCreation] = None
    """Breakdown of cached tokens by TTL"""
    cache_creation_input_tokens: Optional[int] = None
    """The number of input tokens used to create the cache entry."""
    ...

>>> from anthropic.types import CacheCreation
class CacheCreation(BaseModel):
    ephemeral_1h_input_tokens: int
    """The number of input tokens used to create the 1 hour cache entry."""
    ephemeral_5m_input_tokens: int
    """The number of input tokens used to create the 5 minute cache entry."""

usage.cache_creation (when present) carries the exact per-TTL split;
usage.cache_creation_input_tokens remains the aggregate. Official Anthropic
pricing: 5-minute cache writes = 1.25x base input, 1-hour cache writes = 2x
base input. Because the module billed everything at 1.25x, any session using
cache_stable_region_ttl_1h had its 1h write costs undercounted by
~37.5%.

The fix

• compute_cost() gains optional cache_creation_5m_input_tokens /
  cache_creation_1h_input_tokens parameters. When either is supplied, 5m
  tokens are billed at cache_write_per_m (1.25x) and 1h tokens at
  2 * input_per_m (2x). When neither is supplied (older SDK response
  shapes, other callers, existing test doubles), the legacy
  aggregate-at-1.25x path is unchanged — a graceful, non-breaking fallback.
• If the split is present but doesn't sum to the aggregate
  cache_creation_input_tokens, the split wins (it's the more precise,
  billable figure) and the discrepancy is logged at DEBUG only — no
  warning spam.
• __init__.py extracts usage.cache_creation.ephemeral_5m_input_tokens /
  .ephemeral_1h_input_tokens defensively (isinstance(..., int)-guarded,
  so a malformed or mocked object degrades to "split absent" rather than
  crashing) and wires them into compute_cost().
• Corrected the stale comment; Fable-5's 1h rate ($20.00/MTok) is exactly 2x
  its input rate, consistent with every other model — no special-casing
  needed.
• Read-only check (as requested): no other consumer in the module reads
  cache_creation_input_tokens for cost or telemetry. The only other reader
  is the kernel Usage.cache_write_tokens field, which reports the raw
  aggregate token count for observability, not a dollar cost — it needs no
  equivalent change.

Tests

Added to tests/test_cost.py, following the module's existing conventions:

• Split with nonzero 1h tokens → billed at 2x (the key regression test)
• Split that is all-5m → identical to legacy behavior
• Mixed 5m + 1h split → each portion billed at its own rate
• Aggregate-only (no split kwargs) → legacy 1.25x path unchanged
• Explicit 0/None split fields → zero cost contribution, no crash
• Split/aggregate mismatch → split wins, logged at DEBUG (asserted via
  caplog, not WARNING+)
• End-to-end _convert_to_chat_response() test proving the corrected cost
  reaches Usage.cost_usd

All 6 of the new behavior-under-test cases were verified to fail against
the pre-fix code (TypeError for the new kwargs on the old signature, or the
stale $3.75 assertion instead of $6.00) before the fix was applied, and
pass after.

Full suite: 671 passed (662 baseline + 9 new), 0 failed, on a fresh clone
of main @ e64b114.

Credit

This was independently corroborated by Joi's review comment on closed PR
#91, and by upstream issue microsoft/amplifier#337. ramparte's PR was the
signal that first surfaced this as worth investigating. Thank you both.

🤖 Generated with Amplifier

[Brian Krabach (bkrabach)]

All required checks are green: license/cla passes, and the full pytest matrix
(ubuntu/macos/windows × py3.11/py3.12) passes.

This PR is self-authored (by the maintainer, at explicit user direction) to fix a
verified cost-undercounting bug — see the PR description for the SDK-verified
evidence (stale comment, exact anthropic 1.0.0 Usage/CacheCreation field
shapes) and the fail-before/pass-after test results (671 passed: 662 baseline + 9
new, 0 failed).

Branch protection requires a review that isn't available in this context, so this
is being merged with --admin at the maintainer's/user's explicit direction,
following our documented admin-merge pattern: checks are the substantive gate here
(all green, none bypassed), and the review requirement is what's being
administratively satisfied — not a substitute for testing or CI evidence.

Merging via gh pr merge --squash --delete-branch=false --admin.