Anthropic API & Prompt Caching

Le prompt caching d'Anthropic est la clé de la rentabilité du produit. Sans cache, un message concierge coûte ~1.5 ¢ ; avec cache bien configuré, 0.3 ¢ — un facteur 5 qui fait basculer le modèle économique de "à peine viable" à "marge brute 90%".

Tarifs Messages API (2026)

Haiku 4.5 est notre modèle par défaut (AI_MODEL_CONCIERGE=claude-haiku-4-5). Sonnet 4.6 sera utilisé sur les tiers Enterprise pour du raisonnement plus complexe et le web search (Haiku ne supporte pas le tool web_search built-in).

Règles d'or du pricing

• Cache read = 10% du prix input de base → −90% sur la partie cachée.
• Cache write 5m = 1.25× base, break-even dès 1 lecture.
• Cache write 1h = 2× base, break-even à 2 lectures. Surcoût absorbé par le gain long-terme.
• Batch API = −50% (non-streaming, async). Stackable avec le cache. Utile pour résumés nightly, rapports analytics.
• Cached input tokens ne comptent PAS dans les rate limits → capacité effective ×5 si cache hit > 80%.

Prompt caching — mécanique

Minimum cacheable par modèle

Sous ce seuil, Anthropic ne renvoie PAS d'erreur : l'API répond simplement avec cache_creation_input_tokens = 0. Silent fail. Vérifier systématiquement la réponse usage pour confirmer que le cache a bien été écrit.

Breakpoints et ordre

• Max 4 cache_control breakpoints par requête.
• Ordre strict : tools → system → messages. Un breakpoint cache TOUT ce qui le précède, pas uniquement son bloc.
• Modifier un champ invalide tous les blocs avals (changer un tool invalide le cache du system prompt).

TTL

• 5 min (défaut) : refresh gratuit pendant la fenêtre. Idéal pour sessions guest courtes.
• 1 h : write 2× base mais couvre ~12 sessions. Idéal pour le system prompt statique qui ne change qu'au deploy.

Ce qui invalide le cache

Invalident (force rewrite) :

• Modification des tool definitions (schéma, description).
• Modification du system prompt.
• Toggle web_search.
• Ajout/suppression d'images.

Restent valides :

• Changement de tool_choice.
• Toggle thinking mode / speed mode.

Architecture caching Bell

Notre implémentation (packages/api/src/services/ai/claude.ts) utilise un seul breakpoint stratégique au bout du bloc statique du system prompt :

┌──────────────────────────────────────────────────────┐
│ Tools (~500 tokens)                                   │
│ ├─ escalate_to_ticket                                 │
│ └─ redirect_to_booking                                │
├──────────────────────────────────────────────────────┤
│ System block STATIC (~4.5k tokens)         TTL 1h    │
│ ├─ Header (ton, style, interdictions markdown)       │
│ ├─ 8 intents (room service, spa, laundry, ...)       │
│ ├─ Exemples de tonalité (6 cas concrets)             │
│ ├─ Guardrails & edge cases                           │
│ └─ Footer (règles conduite, priorités ticket)        │
│ ▲ cache_control: { type: "ephemeral", ttl: "1h" }    │
├──────────────────────────────────────────────────────┤
│ System block DYNAMIC (~500 tokens, uncached)         │
│ └─ KB chunks retrievés pour cette query              │
├──────────────────────────────────────────────────────┤
│ Messages (history + user) — ~1-2k tokens, uncached   │
└──────────────────────────────────────────────────────┘

Pourquoi un seul breakpoint ? Parce que chaque breakpoint ajoute une contrainte de min tokens incrémentale. Sur Haiku 4.5 avec son min 4 096 :

• Breakpoint sur tools seul (~500 tok) → fail.
• Breakpoint à la fin du static → englobe tools + static = ~5k tok ✓.
• 2ᵉ breakpoint sur KB dynamic (~500 tok incrémental) → fail silencieux.

Concentrer sur un seul breakpoint généreux maximise l'écriture cache.

Pourquoi 1 h et pas 5 min ? Les hôtels actifs ont >10 sessions guest dans l'heure. Le surcoût write 2× base est amorti dès la 2ᵉ lecture. Le system prompt ne change qu'aux deploys (souvent < 1 fois par jour).

Web Search tool

Tool natif Anthropic, facturé $10 / 1 000 recherches ($0.01/appel) + tokens des résultats injectés en input.

• Compatible : Opus 4.7, Sonnet 4.6 (pas Haiku 4.5).
• Usage Bell futur : requêtes type "meilleur resto italien près de l'hôtel". Pour l'instant on escalate ces questions au staff ; on activera web search sur les tiers Pro/Enterprise (AI_MODEL_CONCIERGE_STRONG=claude-sonnet-4-6).
• Filtering dynamique (web_search_20260209 + code exec) : Claude peut filtrer les résultats avant de les injecter en contexte → économise tokens.

Batch API

Discount −50% sur input ET output. Stackable avec cache discount.

• Exemple Haiku Batch : $0.50/MTok input, $2.50/MTok output.
• Async uniquement, pas de streaming.
• Délai de traitement < 24h (souvent < 1h).

Usage Bell prévu :

• Résumés nightly de conversations guests → revue staff le matin.
• Analytics des tickets hebdomadaires.
• Ingestion KB bulk (si on importe 1000+ articles d'un PMS).

Rate limits par tier

Bell démarre au tier 1 (développement). On passera au tier 2 quand on aura 3-5 hôtels actifs. Les cached tokens ne comptent pas dans ITPM → au tier 2 avec 80% cache hit on gère ~2.25M tokens effectifs/min.

Embeddings

Anthropic n'offre pas d'API embeddings. Bell utilise OpenAI text-embedding-3-small (1 536 dims, $0.02/MTok). Voir Embeddings & RAG pour la stack complète.

Choix acté : Voyage AI est officiellement recommandé par Anthropic pour le retrieval en contexte Claude. On bascule sur voyage-3.5-lite ($0.02/MTok, 1024 dims) pour bénéficier du gain de qualité native. OpenAI est gardé comme provider alternatif via EMBEDDING_PROVIDER=openai pour retour arrière rapide si besoin. Détails dans Embeddings & RAG.

Variables d'environnement

# Modèle par défaut du concierge (économique)
AI_MODEL_CONCIERGE=claude-haiku-4-5

# Modèle Enterprise (pour web search + raisonnement complexe)
AI_MODEL_CONCIERGE_STRONG=claude-sonnet-4-6

# Modèle pour tâches auxiliaires non-concierge (résumés, classif)
AI_MODEL_AUXILIARY=gpt-4o-mini

# Provider embeddings
AI_MODEL_EMBEDDINGS=text-embedding-3-small
EMBEDDING_PROVIDER=openai

# Kill switch prompt caching (si bug Anthropic ou debug)
AI_PROMPT_CACHING_ENABLED=true

Références

• Pricing officiel Anthropic
• Prompt caching docs
• Rate limits
• Web search tool
• ADR-10 : AI provider strategy