Claude cache_control — no cache hit, paying full input token cost

import anthropic

client = anthropic.Anthropic()

# ✓ CORRECT — stable content before cache_control, variable after
def ask_over_document(document: str, user_question: str):
    return client.messages.create(
        model="claude-opus-4-7",
        max_tokens=1000,
        system=[
            {
                "type": "text",
                "text": (
                    "You are a research assistant. Answer strictly from the document.\n\n"
                    f"<document>\n{document}\n</document>"
                ),
                "cache_control": {"type": "ephemeral"},  # ← breakpoint HERE
            },
        ],
        messages=[
            {"role": "user", "content": user_question},   # ← variable AFTER breakpoint
        ],
    )

# First call: document is cached (cache_creation_input_tokens > 0)
r1 = ask_over_document(long_document, "Who is the CEO?")
print("create:", r1.usage.cache_creation_input_tokens,
      "read:",   r1.usage.cache_read_input_tokens)

# Subsequent calls with the SAME document: cache_read_input_tokens > 0 (90% off)
r2 = ask_over_document(long_document, "What was 2024 revenue?")
print("create:", r2.usage.cache_creation_input_tokens,
      "read:",   r2.usage.cache_read_input_tokens)

import anthropic
import logging
from dataclasses import dataclass

log = logging.getLogger(__name__)
client = anthropic.Anthropic()

@dataclass
class CacheStats:
    uncached_input: int
    cache_create: int
    cache_read: int

    @property
    def hit_rate(self) -> float:
        total = self.cache_create + self.cache_read + self.uncached_input
        return self.cache_read / total if total else 0.0

    def cost_estimate(self, model_input_price_per_mtok: float) -> float:
        return (
            self.uncached_input * (model_input_price_per_mtok / 1_000_000)
            + self.cache_create * (model_input_price_per_mtok * 1.25 / 1_000_000)
            + self.cache_read * (model_input_price_per_mtok * 0.10 / 1_000_000)
        )

def call_with_tracking(**kwargs) -> tuple[anthropic.types.Message, CacheStats]:
    response = client.messages.create(**kwargs)
    usage = response.usage
    stats = CacheStats(
        uncached_input=usage.input_tokens,        # NOT including cache read/create
        cache_create=getattr(usage, "cache_creation_input_tokens", 0) or 0,
        cache_read=getattr(usage, "cache_read_input_tokens", 0) or 0,
    )
    log.info("cache: create=%d read=%d uncached=%d hit_rate=%.1f%%",
             stats.cache_create, stats.cache_read, stats.uncached_input,
             stats.hit_rate * 100)

    if stats.cache_create > 0 and stats.cache_read == 0:
        log.warning("CACHE MISS — paid create but no read. Prefix probably changed.")
    if stats.cache_read > 0 and stats.cache_create > 0:
        log.info("PARTIAL HIT — matched only some blocks. Reorganise cache_control?")

    return response, stats

response, stats = call_with_tracking(
    model="claude-opus-4-7",
    max_tokens=500,
    system=[{"type": "text", "text": SYSTEM_PROMPT,
             "cache_control": {"type": "ephemeral"}}],
    messages=[{"role": "user", "content": user_input}],
)

import anthropic

client = anthropic.Anthropic(
    default_headers={
        # Extended TTL beta — check current header name in Anthropic docs
        "anthropic-beta": "extended-cache-ttl-2025-04-11",
    }
)

# Extended TTL is best for prompts that are read many times per hour
# (agent memory, per-user personas, long-lived context)
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=500,
    system=[
        {
            "type": "text",
            "text": VERY_LARGE_STABLE_PROMPT,   # e.g. 40K-token knowledge base
            "cache_control": {
                "type": "ephemeral",
                "ttl": "1h",                    # 1-hour cache (vs default 5m)
            },
        },
    ],
    messages=[
        {"role": "user", "content": user_question},
    ],
)

# Breakeven: extended TTL wins when reads per creation > ~13
# (2x create cost / 0.10x read savings = 20 reads pay back one create at extended
# vs 0.25x/0.10x = 3 reads pay back at default TTL)