ADR-003 : Claude via SSH plutôt qu'API Anthropic directe

ADR-003 : Claude via SSH plutôt qu'API Anthropic directe
Date : 2026 (premiers tests RAG) — Statut : accepté
Contexte
L'app a besoin d'appeler Claude (Opus + Haiku) pour : génération RAG, HyDE, decompose-query, contextual retrieval, hierarchy LLM, conflict detection, intent classification, deckbuilding.
Volume estimé : 1000-5000 appels Claude par jour en pic d'usage (notamment pendant les ingestions).
Options :
API Anthropic directe (
https://api.anthropic.com/v1/messages)
Claude Code CLI via SSH vers une VM 
oracle (compte personnel Pro/Team)
Décision
Claude Code CLI via SSH vers une VM dédiée.
Raisons :
Quota Pro/Team : compte personnel Anthropic Pro/Team paie un forfait fixe (~$20/mois) avec quota glissant 5h. Beaucoup plus économique que payer à l'API ($/M tokens) pour du volume moyen-élevé.
Outil 
Read natif : Claude Code a un outil 
Read qui lui permet de lire les PNG des règles directement. Pour la "vision inline" (cf. ADR-004), c'est la fonctionnalité-pivot.
No-cost marginal : un appel de plus = pas de coût supplémentaire (dans la limite quota). Permet d'expérimenter (Contextual Retrieval B = 1 appel par chunk = potentiellement 1000s d'appels par PDF) sans angoisse de facturation.
CLI maintenu par Anthropic : pas de risque que la lib bouge sous mes pieds.
Conséquences
Bonnes
Coût stable et prévisible
Vision inline gratuite (lecture PNG ad libitum dans la limite quota)
Outil 
Read directement accessible — pas besoin d'inliner les images en base64 dans les prompts
Possibilité d'utiliser des system prompts riches sans facturer chaque token
Mauvaises
Quota saturable : si on dépasse, pause obligatoire (cf. 
services/claude-quota.ts + ADR-007 implicite sur la pause/reprise auto). À l'API ce serait juste $$.
Latence baseline ~5s : tunnel SSH + cold start CLI. Pour les calls courts (HyDE, classify), c'est non-négligeable. D'où le timeout 25s configuré pour absorber cette latence.
Sécurité SSH critique : la VM oracle exécute du code Claude. Verrouillage multi-couche obligatoire (cf. ADR sécurité ssh-oracle).
Single point of failure : si la VM oracle tombe, plus de RAG. Pas de fallback API direct (faisable mais pas implémenté).
Pas de batching natif : chaque appel = un SSH. Pour les pools (Contextual B 10 parallèles), on multiplie les SSH simultanés.
Alternative envisagée
API Anthropic directe : plus rapide (latence ~500ms vs 5s SSH), mais coûte 5-10× plus pour le volume actuel. Non retenu pour des raisons économiques.
Hybrid : API pour les calls courts (HyDE, classify) + SSH pour Opus/Read. Plus complexe, gain marginal. Reporté.
Si on doit migrer un jour
Implémenter un fallback 
services/claude-api.ts qui wrappe 
@anthropic-ai/sdk
Mettre les credentials dans une env var 
ANTHROPIC_API_KEY
Toggle via env (
CLAUDE_BACKEND = 'ssh' | 'api' | 'hybrid')
Garder la vision via une upload image base64 dans le prompt (latence + coût supérieurs)
Effort : 1-2 jours si urgent.