Prompt caching:
экономия до 90% на повторах

import anthropic
client = anthropic.Anthropic()

resp = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system=[
        {"type": "text", "text": SYSTEM_PROMPT},          # статика
        {
            "type": "text",
            "text": KNOWLEDGE_BASE,                        # большой статичный блок
            "cache_control": {"type": "ephemeral"},        # ← ГРАНИЦА КЭША здесь
        },
    ],
    # всё ПОСЛЕ границы меняется от запроса к запросу и не кэшируется
    messages=[{"role": "user", "content": user_question}],
)

u = resp.usage
print(u.cache_creation_input_tokens)  # записали в кэш (1-й раз)
print(u.cache_read_input_tokens)      # прочитали из кэша (дальше) ← цель
print(u.input_tokens)                 # посчитано заново (не кэшировано)

def cache_stats(usage) -> dict:
    cached = usage.cache_read_input_tokens          # прочитано из кэша
    fresh  = usage.input_tokens                     # посчитано заново
    total  = cached + fresh
    return {
        "cache_hit_rate": cached / total if total else 0,
        "cached_tokens": cached,
        "fresh_tokens": fresh,
    }

# логируем в structured-логи и на дашборд (разделы Observability)
log.info("llm_call", **cache_stats(resp.usage), model="claude-sonnet-5")

# ориентиры:
#   hit rate ~0        → кэш НЕ работает: ищи динамику в начале промпта
#   hit rate 0.7–0.9   → отлично, платишь за вход в разы меньше
# ⚠️ смотри hit rate ПОСЛЕ первого запроса: первый всегда write, не read

PROMPT CACHING = переиспользование обработанного ПРЕФИКСА промпта
  экономия до ~90% на входных токенах + быстрее ответ (пропускается prefill)

ПОЧЕМУ РАБОТАЕТ: представление токена зависит от него и ВСЕГО, что ДО него
  → одинаковое начало = одинаковое состояние = можно сохранить
  → отсюда: только ПРЕФИКС и только ТОЧНОЕ совпадение

ГЛАВНОЕ ПРАВИЛО ПОРЯДКА:
  статичное → В НАЧАЛО · изменчивое → В КОНЕЦ
  system → tools → база знаний/few-shot → история → текущий запрос
  ❌ одно изменение в начале обесценивает ВЕСЬ кэш после него

ПРОВАЙДЕРЫ:
  Anthropic — ЯВНО: cache_control на блоке = граница кэша · запись дороже, чтение сильно дешевле
    ставь метку после САМОГО БОЛЬШОГО статичного блока
  OpenAI — АВТОМАТИЧЕСКИ для длинных промптов · контроля нет → важен ПОРЯДОК
  у обоих: минимальный порог токенов · точные цифры — в актуальной доке

АГЕНТЫ: каждый шаг ДОПИСЫВАЕТ в конец → предыдущая часть совпадает → кэш-хит РАСТЁТ
  ⚠️ суммаризация истории ЛОМАЕТ кэш → сжимай по порогу и РЕДКО

TTL: префикс живёт минуты, продлевается при обращении
  ✓ поток запросов / активный диалог · ✗ редкие обращения раз в час (всегда промах)

ИЗМЕРЯЙ: cache_hit_rate = cache_read / (cache_read + input_tokens)
  ~0 → кэш НЕ работает (ищи динамику в начале) · 0.7–0.9 → отлично
  на дашборд рядом с cost: падение hit rate = ранний сигнал роста счёта

ГРАБЛИ: динамика в начале · изменчивое перед статичным · не мерить hit rate ·
        кэш на редких запросах · суммаризация на каждом шаге