# 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 :
1. **API Anthropic directe** (`https://api.anthropic.com/v1/messages`)
2. **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.