tonst 0.2.0__py3-none-any.whl

tonst/__init__.py

@@ -0,0 +1,81 @@
+from .client import TonstClient, OptimizationReport, StructuredRedactionResult
+from .cache_structuring import (
+    PromptParts,
+    structure_for_caching,
+    build_anthropic_cache_request,
+    check_cache_eligibility,
+    CacheEligibility,
+    parse_anthropic_usage,
+    CacheUsageReport,
+)
+from .compactor import (
+    HistoryCompactor,
+    compact_history,
+    CompactionResult,
+    compact_history_rolling,
+    RollingSummary,
+    RollingCompactionResult,
+    FoldJob,
+    run_fold_job,
+    estimate_fold_payback,
+)
+from .trim import flatten_messages
+from .tool_optimizer import (
+    select_tools,
+    ToolSelection,
+    ToolSession,
+    build_anthropic_deferred_tools,
+    estimate_tool_tokens,
+    DEFERRED_TOOLS_SYSTEM_HINT,
+)
+from .rag import optimize_chunks, ChunkSelection
+from .token_count import AnthropicTokenCounter, GeminiTokenCounter
+from .summarizers import AnthropicSummarizer, GeminiSummarizer
+from .savings_log import SavingsLog, summarize as summarize_savings, SavingsSummary
+from .placeholders import PlaceholderFactory
+from .redact import StreamRestorer, restore_placeholders
+from . import providers
+from . import adapters
+
+__all__ = [
+    "PlaceholderFactory",
+    "restore_placeholders",
+    "StreamRestorer",
+    "TonstClient",
+    "OptimizationReport",
+    "StructuredRedactionResult",
+    "PromptParts",
+    "structure_for_caching",
+    "build_anthropic_cache_request",
+    "check_cache_eligibility",
+    "CacheEligibility",
+    "parse_anthropic_usage",
+    "CacheUsageReport",
+    "HistoryCompactor",
+    "compact_history",
+    "CompactionResult",
+    "compact_history_rolling",
+    "RollingSummary",
+    "RollingCompactionResult",
+    "FoldJob",
+    "run_fold_job",
+    "estimate_fold_payback",
+    "flatten_messages",
+    "select_tools",
+    "ToolSelection",
+    "ToolSession",
+    "build_anthropic_deferred_tools",
+    "estimate_tool_tokens",
+    "DEFERRED_TOOLS_SYSTEM_HINT",
+    "optimize_chunks",
+    "ChunkSelection",
+    "AnthropicTokenCounter",
+    "GeminiTokenCounter",
+    "AnthropicSummarizer",
+    "GeminiSummarizer",
+    "SavingsLog",
+    "summarize_savings",
+    "SavingsSummary",
+    "providers",
+    "adapters",
+]

tonst/__main__.py

@@ -0,0 +1,43 @@
+"""
+Command-line entry point.
+
+    tonst stats [--log PATH] [--app NAME] [--since YYYY-MM-DD] [--json]
+
+Also runnable without installing the console script:
+
+    python -m tonst stats
+"""
+
+from __future__ import annotations
+import argparse
+import json
+import sys
+
+from .savings_log import summarize, format_summary
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="tonst", description="tonst command-line tools")
+    sub = parser.add_subparsers(dest="command")
+
+    stats = sub.add_parser("stats", help="summarize the local savings log")
+    stats.add_argument("--log", default=None, help="log path (default: $TONST_SAVINGS_LOG or ~/.tonst/savings.jsonl)")
+    stats.add_argument("--app", default=None, help="only include entries for this app name")
+    stats.add_argument("--since", default=None, help="only include entries on/after this ISO date, e.g. 2026-09-01")
+    stats.add_argument("--json", action="store_true", help="print machine-readable JSON")
+
+    args = parser.parse_args(argv)
+    if args.command != "stats":
+        parser.print_help()
+        return 1
+
+    summary = summarize(args.log, app=args.app, since=args.since)
+    if args.json:
+        print(json.dumps(summary.to_dict(), indent=2))
+    else:
+        print(format_summary(summary))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tonst/adapters.py

@@ -0,0 +1,133 @@
+"""
+adapters.py
+-----------
+Small converters between tonst's plain message list and each provider's
+request/response shapes, for TonstClient(messages_fn=...).
+
+tonst hands messages_fn the final, redacted conversation as
+[{"role": "system" | "user" | "assistant", "content": str}, ...].
+These helpers turn that into what each API expects, and turn the API's
+usage block back into the {"prompt_tokens", "cached_tokens"} dict tonst
+reads (so the report and cache-aware compaction see real numbers).
+
+    import anthropic
+    from tonst import TonstClient
+    from tonst.adapters import to_anthropic, usage_from_anthropic
+
+    api = anthropic.Anthropic()
+
+    def call_claude(messages):
+        resp = api.messages.create(model="claude-sonnet-4-6", max_tokens=1024,
+                                   **to_anthropic(messages))
+        return resp.content[0].text, usage_from_anthropic(resp)
+
+    client = TonstClient(messages_fn=call_claude)
+
+Every helper accepts either a plain dict (raw JSON) or an SDK response
+object, and none of them imports a provider SDK.
+"""
+
+from __future__ import annotations
+from typing import Optional
+
+
+def _get(obj, *path, default=None):
+    """obj.a.b or obj["a"]["b"], whichever exists."""
+    cur = obj
+    for key in path:
+        if cur is None:
+            return default
+        if isinstance(cur, dict):
+            cur = cur.get(key)
+        else:
+            cur = getattr(cur, key, None)
+    return default if cur is None else cur
+
+
+def _merge_turns(messages: list, assistant_role: str) -> tuple:
+    """(system text, [(role, [texts])]) with same-role neighbours merged and a user turn first."""
+    system = "\n\n".join(m["content"] for m in messages if m.get("role") == "system" and m.get("content"))
+    turns = []
+    for m in messages:
+        role = m.get("role")
+        if role == "system" or not m.get("content"):
+            continue
+        role = assistant_role if role == "assistant" else "user"
+        if turns and turns[-1][0] == role:
+            turns[-1][1].append(m["content"])
+        else:
+            turns.append((role, [m["content"]]))
+    if turns and turns[0][0] != "user":
+        turns.insert(0, ("user", ["(Earlier conversation omitted.)"]))
+    return system, turns
+
+
+def to_anthropic(messages: list, cache: bool = True) -> dict:
+    """
+    Keyword arguments for Anthropic's Messages API: {"system", "messages"}.
+    Roles must alternate there, so same-role neighbours are merged (tonst's
+    summary message is a user turn and can sit next to one). cache=True puts
+    a cache_control breakpoint on the system prompt and a moving one on the
+    last block, which is how a multi-turn chat gets cached turn after turn.
+    Prompts under the model's minimum cacheable length are simply not cached.
+    """
+    system, turns = _merge_turns(messages, "assistant")
+    out_msgs = [{"role": r, "content": [{"type": "text", "text": t} for t in texts]} for r, texts in turns]
+    if cache and out_msgs:
+        last = out_msgs[-1]["content"][-1]
+        out_msgs[-1]["content"][-1] = {**last, "cache_control": {"type": "ephemeral"}}
+    body = {"messages": out_msgs}
+    if system:
+        block = {"type": "text", "text": system}
+        if cache:
+            block["cache_control"] = {"type": "ephemeral"}
+        body["system"] = [block]
+    return body
+
+
+def to_openai(messages: list) -> list:
+    """Chat Completions `messages`. OpenAI caches repeated prefixes automatically; no markers needed."""
+    return [{"role": m["role"], "content": m["content"]} for m in messages if m.get("content")]
+
+
+def to_gemini(messages: list) -> dict:
+    """
+    generateContent REST body fields: {"systemInstruction", "contents"}
+    (role "model" for the assistant). Gemini 2.5+ caches repeated prefixes
+    implicitly; it's best-effort and needs a few thousand tokens.
+    """
+    system, turns = _merge_turns(messages, "model")
+    body = {"contents": [{"role": r, "parts": [{"text": t} for t in texts]} for r, texts in turns]}
+    if system:
+        body["systemInstruction"] = {"parts": [{"text": system}]}
+    return body
+
+
+def usage_from_anthropic(resp) -> Optional[dict]:
+    u = _get(resp, "usage")
+    if u is None:
+        return None
+    read = int(_get(u, "cache_read_input_tokens", default=0))
+    total = int(_get(u, "input_tokens", default=0)) + int(_get(u, "cache_creation_input_tokens", default=0)) + read
+    return {"prompt_tokens": total, "cached_tokens": read}
+
+
+def usage_from_openai(resp) -> Optional[dict]:
+    u = _get(resp, "usage")
+    if u is None:
+        return None
+    if _get(u, "prompt_tokens") is not None:   # Chat Completions
+        return {"prompt_tokens": int(_get(u, "prompt_tokens")),
+                "cached_tokens": int(_get(u, "prompt_tokens_details", "cached_tokens", default=0))}
+    return {"prompt_tokens": int(_get(u, "input_tokens", default=0)),   # Responses API
+            "cached_tokens": int(_get(u, "input_tokens_details", "cached_tokens", default=0))}
+
+
+def usage_from_gemini(resp) -> Optional[dict]:
+    u = _get(resp, "usageMetadata") or _get(resp, "usage_metadata")
+    if u is None:
+        return None
+    prompt = _get(u, "promptTokenCount") if _get(u, "promptTokenCount") is not None else _get(u, "prompt_token_count", default=0)
+    cached = _get(u, "cachedContentTokenCount") if _get(u, "cachedContentTokenCount") is not None \
+        else _get(u, "cached_content_token_count", default=0)
+    return {"prompt_tokens": int(prompt), "cached_tokens": int(cached or 0)}

tonst/cache_structuring.py

@@ -0,0 +1,405 @@
+"""
+cache_structuring.py
+---------------------
+Structures a request so that provider-side prompt caching actually pays
+off. Important to be precise about what this is NOT: prompt caching does
+not skip the LLM call. Anthropic, OpenAI, and Gemini all cache the
+*processed representation* of repeated prefix tokens so the model
+doesn't have to reprocess them, but the model still runs and generates a
+fresh response on every call -- caching only discounts (and speeds up)
+the repeated portion of the input.
+
+It only pays off if the request is shaped correctly:
+  - Stable, reused content (system instructions, a reference document,
+    tool descriptions written out as text) has to come FIRST.
+  - That stable content has to be byte-for-byte IDENTICAL across calls --
+    reordering it, changing its whitespace, or interleaving the variable
+    question into it all silently break the match. There's no error when
+    this happens; you just quietly stop getting the discount.
+  - The variable part (the actual question, the newest turn) goes LAST.
+  - The stable prefix also has to clear a PER-MODEL MINIMUM LENGTH --
+    see CACHE_MINIMUM_TOKENS below. Below it, Anthropic silently skips
+    caching entirely: no error, cache_creation_input_tokens and
+    cache_read_input_tokens both stay 0. check_cache_eligibility() and
+    the warning in build_anthropic_cache_request() exist specifically so
+    this doesn't fail silently on you too.
+
+Output shapes provided:
+  - structure_for_caching() returns a flat, correctly-ordered string.
+    This is enough for providers with automatic prefix caching (no
+    explicit marker required) and works with TonstClient.query(str).
+  - build_anthropic_cache_request() returns the actual Anthropic
+    Messages API JSON body with an explicit `cache_control` breakpoint,
+    which Anthropic requires -- correct ordering alone is not sufficient
+    on that provider. Verified against Anthropic's prompt-caching docs
+    (platform.claude.com/docs/en/build-with-claude/prompt-caching,
+    checked 2026-09-08): cache_control goes on the LAST block whose
+    prefix should be cached, as {"type": "ephemeral", "ttl": "5m"|"1h"}.
+  - parse_anthropic_usage() reads the `usage` field of a REAL API
+    response and reports whether a cache hit actually happened --
+    the only ground truth for whether any of this worked.
+"""
+
+from __future__ import annotations
+import warnings
+from dataclasses import dataclass, field
+from typing import Optional
+
+VALID_TTLS = ("5m", "1h")
+
+# Anthropic's minimum cacheable-prefix length per model, in tokens, as of
+# the docs checked 2026-09-08. A stable prefix shorter than this is
+# processed normally with NO ERROR and NO CACHING -- the response's
+# usage.cache_creation_input_tokens / usage.cache_read_input_tokens both
+# come back 0. This table exists so tonst can warn about that ahead of
+# time instead of a developer discovering it by silently getting no
+# savings. Keyed on the model string as passed to the API; unknown/future
+# models fall back to DEFAULT_CACHE_MINIMUM_TOKENS (the most common
+# figure across the current lineup).
+CACHE_MINIMUM_TOKENS: dict[str, int] = {
+    "claude-haiku-4-5": 4096,
+    "claude-haiku-3-5": 2048,
+    "claude-opus-4-6": 4096,
+    "claude-opus-4-5": 4096,
+    "claude-opus-4-7": 2048,
+    "claude-opus-4-8": 1024,
+    "claude-opus-4-1": 1024,
+    "claude-opus-4": 1024,
+    "claude-sonnet-5": 1024,
+    "claude-sonnet-4-6": 1024,
+    "claude-sonnet-4-5": 1024,
+    "claude-sonnet-4": 1024,
+    "claude-opus-5": 512,
+    "claude-fable-5": 512,
+    "claude-fable-5-1": 512,
+    "claude-mythos-5": 512,
+    "claude-mythos-5-1": 512,
+    # "Claude Mythos Preview" is documented at 2,048 tokens, but its
+    # exact API model-id string wasn't confirmed at the time this table
+    # was written -- add it here once known, rather than guess a key
+    # that would silently never match.
+}
+DEFAULT_CACHE_MINIMUM_TOKENS = 1024
+
+# Anthropic's cache pricing multipliers, relative to that model's own
+# base (uncached) input-token price of 1.0x. Verified against
+# platform.claude.com/docs/en/build-with-claude/prompt-caching, checked
+# 2026-09-09. A cache WRITE costs MORE than a fresh token -- you're
+# paying a premium to populate the cache -- and only a cache READ is
+# discounted. This is what makes "percent of input from cache" (see
+# CacheUsageReport.percent_of_input_from_cache) different from an actual
+# cost saving: caching never changes how many tokens get processed, so
+# a real savings estimate has to weight each token type by its actual
+# price, not just count what fraction came from cache.
+CACHE_READ_MULTIPLIER_DEFAULT = 0.1  # 10% of base input price
+CACHE_READ_MULTIPLIER_LOW_COST = 0.025  # Fable/Mythos family: 2.5% of base price
+CACHE_WRITE_MULTIPLIER_5M = 1.25  # 125% of base input price
+CACHE_WRITE_MULTIPLIER_1H = 2.0  # 200% of base input price
+
+# Models with the lower 2.5% cache-read rate instead of the standard 10%.
+_LOW_COST_CACHE_READ_MODELS = {
+    "claude-fable-5",
+    "claude-fable-5-1",
+    "claude-mythos-5",
+    "claude-mythos-5-1",
+}
+
+
+def _cache_read_multiplier(model: str) -> float:
+    return (
+        CACHE_READ_MULTIPLIER_LOW_COST
+        if model in _LOW_COST_CACHE_READ_MODELS
+        else CACHE_READ_MULTIPLIER_DEFAULT
+    )
+
+
+@dataclass
+class PromptParts:
+    """
+    system: instructions that never change between calls in this
+        conversation/session (e.g. "You are a support assistant...").
+    stable_blocks: large reusable content that's IDENTICAL across many
+        calls -- reference documents, few-shot examples, tool
+        descriptions written out as text. List order is preserved; put
+        the content least likely to ever change first, since everything
+        up to and including the cache_control breakpoint must match
+        exactly for a hit.
+    variable: the part that's different on every call -- the user's
+        actual question, or the newest turn. Always placed last.
+    """
+    system: Optional[str] = None
+    stable_blocks: list = field(default_factory=list)
+    variable: str = ""
+
+
+def structure_for_caching(parts: PromptParts) -> str:
+    """
+    Returns a single string with stable content first, variable last.
+    Byte-for-byte identical stable content across calls is what lets
+    providers with automatic prefix caching (no explicit marker needed)
+    actually get a cache hit -- reordering, whitespace changes, or
+    interleaving the question into the stable section all silently
+    defeat it. This is the ordering guarantee; it does not, by itself,
+    set an explicit cache breakpoint (see build_anthropic_cache_request
+    for that).
+    """
+    sections = []
+    if parts.system:
+        sections.append(parts.system.strip())
+    sections.extend(b.strip() for b in parts.stable_blocks if b and b.strip())
+    if parts.variable:
+        sections.append(parts.variable.strip())
+    return "\n\n".join(sections)
+
+
+@dataclass
+class CacheEligibility:
+    """
+    Heuristic estimate of whether `parts`'s stable content is long enough
+    for `model` to actually cache it. This uses tonst's chars/4 token
+    estimate (see trim.py), NOT the provider's real tokenizer -- treat it
+    as a smoke test that catches the obvious "way too short" case, not
+    an exact prediction. The only real ground truth is the `usage` field
+    of an actual API response (see parse_anthropic_usage()).
+    """
+    eligible: bool
+    stable_tokens_estimate: int
+    minimum_required: int
+    model: str
+
+    @property
+    def message(self) -> str:
+        if self.eligible:
+            return (
+                f"Stable content is ~{self.stable_tokens_estimate} tokens "
+                f"(est.), above {self.model}'s {self.minimum_required}-token "
+                "minimum -- likely eligible for caching."
+            )
+        return (
+            f"Stable content is only ~{self.stable_tokens_estimate} tokens "
+            f"(est.), below {self.model}'s {self.minimum_required}-token "
+            "minimum. This provider will NOT cache it: most providers raise "
+            "no error here, they simply process the request without "
+            "caching. Add more reusable content to stable_blocks/system, "
+            "or don't bother shaping this request for caching at all."
+        )
+
+
+def check_cache_eligibility(
+    parts: PromptParts, model: str, token_estimator=None, tools: Optional[list] = None
+) -> CacheEligibility:
+    """
+    Estimates whether the stable/cacheable portion of `parts` meets
+    Anthropic's minimum prefix length for `model`. Meant to catch an
+    obviously-too-short system prompt or reference snippet before
+    spending an API call that silently won't cache -- not a substitute
+    for checking real usage.cache_creation_input_tokens /
+    usage.cache_read_input_tokens from an actual response.
+
+    `tools`, if given, counts toward the cached prefix too (tool
+    definitions come first in Anthropic's prefix order) -- except tools
+    marked defer_loading, which the API keeps out of the prefix.
+    """
+    if token_estimator is None:
+        from .trim import estimate_tokens as token_estimator
+
+    stable_text = "\n\n".join([parts.system or ""] + list(parts.stable_blocks))
+    stable_tokens = token_estimator(stable_text) if stable_text.strip() else 0
+    loaded = [t for t in (tools or []) if not t.get("defer_loading")]
+    if loaded:
+        import json
+        stable_tokens += token_estimator(json.dumps(loaded, separators=(",", ":"), sort_keys=True))
+
+    minimum = CACHE_MINIMUM_TOKENS.get(model, DEFAULT_CACHE_MINIMUM_TOKENS)
+    return CacheEligibility(
+        eligible=stable_tokens >= minimum,
+        stable_tokens_estimate=stable_tokens,
+        minimum_required=minimum,
+        model=model,
+    )
+
+
+def build_anthropic_cache_request(
+    parts: PromptParts,
+    model: str,
+    max_tokens: int = 1000,
+    cache_ttl: str = "5m",
+    warn_if_ineligible: bool = True,
+    tools: Optional[list] = None,
+) -> dict:
+    """
+    Builds the JSON body for a direct call to
+    https://api.anthropic.com/v1/messages with an explicit cache
+    breakpoint placed after the stable content. Anthropic requires this
+    `cache_control` marker on the last stable block -- ordering alone
+    (unlike OpenAI/Gemini's automatic prefix caching) does not trigger a
+    cache hit on this provider.
+
+    If `warn_if_ineligible` is True (default), this checks stable-content
+    length against CACHE_MINIMUM_TOKENS and raises a UserWarning if it's
+    likely too short to actually be cached. The request is still built
+    and returned either way -- Anthropic itself doesn't error on a
+    too-short cache_control block, it just silently skips caching, and
+    tonst matches that (fail-soft), just with a visible warning instead
+    of silence.
+
+    If `parts.system` is set, it's cached too (as its own block with its
+    own breakpoint) since a large, reused system prompt is one of the
+    most common things worth caching.
+
+    If there are no stable_blocks, this falls back to a plain string
+    message body -- there's nothing to cache, so the block-array
+    overhead (and the cost of writing a cache entry with no reuse ahead
+    of it) isn't worth it.
+
+    `tools` (optional) is passed through as the request's `tools` array,
+    unmodified -- e.g. the output of tool_optimizer.select_tools() or
+    build_anthropic_deferred_tools(). Tools come FIRST in Anthropic's
+    cache prefix, so the system breakpoint already covers them; when
+    there's no system prompt, a breakpoint is put on the last
+    non-deferred tool instead so the tool definitions still get cached.
+    """
+    if cache_ttl not in VALID_TTLS:
+        raise ValueError(f"cache_ttl must be one of {VALID_TTLS}, got {cache_ttl!r}")
+
+    if warn_if_ineligible:
+        eligibility = check_cache_eligibility(parts, model, tools=tools)
+        if not eligibility.eligible:
+            warnings.warn(eligibility.message, UserWarning, stacklevel=2)
+
+    body: dict = {"model": model, "max_tokens": max_tokens}
+
+    if tools:
+        for t in tools:
+            if t.get("defer_loading") and "cache_control" in t:
+                raise ValueError(
+                    f"tool {t.get('name')!r} has both defer_loading and cache_control; "
+                    "Anthropic rejects that with a 400"
+                )
+        body["tools"] = [dict(t) for t in tools]
+        if not parts.system:
+            loaded_idx = [i for i, t in enumerate(body["tools"]) if not t.get("defer_loading")]
+            if loaded_idx and not any("cache_control" in t for t in body["tools"]):
+                body["tools"][loaded_idx[-1]]["cache_control"] = {"type": "ephemeral", "ttl": cache_ttl}
+
+    if parts.system:
+        body["system"] = [
+            {
+                "type": "text",
+                "text": parts.system.strip(),
+                "cache_control": {"type": "ephemeral", "ttl": cache_ttl},
+            }
+        ]
+
+    stable = [b.strip() for b in parts.stable_blocks if b and b.strip()]
+    variable_text = (parts.variable or "").strip()
+
+    if stable:
+        content_blocks = [{"type": "text", "text": b} for b in stable]
+        # The breakpoint goes on the LAST stable block: everything up to
+        # and including it becomes the cached prefix, so only one marker
+        # is needed even if there are many stable blocks.
+        content_blocks[-1]["cache_control"] = {"type": "ephemeral", "ttl": cache_ttl}
+        if variable_text:
+            content_blocks.append({"type": "text", "text": variable_text})
+        body["messages"] = [{"role": "user", "content": content_blocks}]
+    else:
+        # Nothing stable to cache -- a plain string is simpler and avoids
+        # block-array overhead for a one-off call.
+        body["messages"] = [{"role": "user", "content": variable_text}]
+
+    return body
+
+
+@dataclass
+class CacheUsageReport:
+    """
+    Parsed from a REAL Anthropic API response's `usage` field -- the
+    only ground truth for whether caching actually happened on a given
+    call. cache_creation_input_tokens > 0 means this call WROTE a new
+    cache entry (expected on the first call with a given stable prefix).
+    cache_read_input_tokens > 0 means this call GOT the discount by
+    reading a previously-written cache entry.
+    """
+    input_tokens: int
+    output_tokens: int
+    cache_creation_input_tokens: int
+    cache_read_input_tokens: int
+
+    @property
+    def cache_hit(self) -> bool:
+        return self.cache_read_input_tokens > 0
+
+    @property
+    def cache_write(self) -> bool:
+        return self.cache_creation_input_tokens > 0
+
+    @property
+    def percent_of_input_from_cache(self) -> float:
+        total_input = (
+            self.input_tokens
+            + self.cache_creation_input_tokens
+            + self.cache_read_input_tokens
+        )
+        if total_input == 0:
+            return 0.0
+        return round(100 * self.cache_read_input_tokens / total_input, 1)
+
+    def estimated_cost_savings_percent(self, model: str, cache_ttl: str = "5m") -> float:
+        """
+        Estimates the % COST difference caching made on this call,
+        against the baseline of the exact same token count being sent
+        with NO caching at all (everything billed at the standard 1x
+        input rate). That baseline -- not "tokens saved" -- is the
+        correct comparison, because caching never reduces how many
+        tokens the model processes; see the module docstring and
+        percent_of_input_from_cache above.
+
+        This can come back NEGATIVE: a cache-WRITE call (the first call
+        with a new stable prefix) costs MORE than not caching at all,
+        since Anthropic charges a premium (1.25x for a 5-minute TTL,
+        2x for 1-hour) to populate the cache. The saving only shows up
+        on a later cache-READ call against that same prefix. Report
+        both calls, not just the read, if you want an honest before/
+        after picture -- see examples/cache_savings_demo_anthropic.py (or the OpenAI/Gemini/generic siblings).
+
+        Uses tonst's own CACHE_READ/WRITE multiplier constants above
+        (verified against Anthropic's published pricing docs, not this
+        library's own guess), applied to the REAL token counts parsed
+        from an actual API response -- not an estimate.
+        """
+        read_mult = _cache_read_multiplier(model)
+        write_mult = CACHE_WRITE_MULTIPLIER_1H if cache_ttl == "1h" else CACHE_WRITE_MULTIPLIER_5M
+
+        actual_cost = (
+            self.input_tokens * 1.0
+            + self.cache_creation_input_tokens * write_mult
+            + self.cache_read_input_tokens * read_mult
+        )
+        total_tokens = (
+            self.input_tokens
+            + self.cache_creation_input_tokens
+            + self.cache_read_input_tokens
+        )
+        no_cache_cost = total_tokens * 1.0  # same token count, all at the base rate
+
+        if no_cache_cost == 0:
+            return 0.0
+        return round(100 * (no_cache_cost - actual_cost) / no_cache_cost, 1)
+
+
+def parse_anthropic_usage(response_json: dict) -> CacheUsageReport:
+    """
+    Extracts cache-relevant token counts from a real Anthropic Messages
+    API response. Pass the full decoded JSON body of the response (the
+    function reads its "usage" key) -- this is the only way to actually
+    confirm caching worked, as opposed to just building a
+    correctly-shaped request and assuming it did.
+    """
+    usage = response_json.get("usage", {})
+    return CacheUsageReport(
+        input_tokens=usage.get("input_tokens", 0),
+        output_tokens=usage.get("output_tokens", 0),
+        cache_creation_input_tokens=usage.get("cache_creation_input_tokens", 0),
+        cache_read_input_tokens=usage.get("cache_read_input_tokens", 0),
+    )