# ADR 0002 — Intégration Claude : provider IA natif Zammad (Anthropic) + Writing Assistant

- **Statut** : Accepté
- **Date** : 2026-06-26
- **Remplace le point ouvert** : `docs/research/claude-integration.md` (supprimé depuis — historique dans git)

## Contexte

Le brief demande d'**assister la rédaction** des réponses aux devis via Claude 4.5
(génération/reformulation de brouillons, **révision humaine obligatoire avant envoi**). C'était
le seul point d'architecture non tranché. Après lecture de la doc IA de Zammad et **vérification
sur notre instance** (Zammad 7.1.1 community self-hosted), on a constaté que :

- Zammad supporte nativement **Anthropic (Claude)** comme provider IA (`ai_provider`,
  `ai_provider_config` présents ; permissions `admin.ai_provider`, `admin.ai_assistance_text_tools`
  actives) — utilisable sur l'édition community self-hosted **avec notre propre clé API**, sans
  abonnement Zammad (le « plan V2 + AI calls » ne concerne que le provider managé *Zammad AI*).
- Le **Writing Assistant** (text tools) reformule/complète un texte sélectionné par l'agent,
  **manuel, human-in-the-loop, sans auto-send** — exactement le besoin (reformulation + 1er jet).

## Décision

- **Hook Claude = fonctions IA natives de Zammad**, provider **Anthropic**, **notre clé API**.
- **Modèle** : `claude-sonnet-4-6` (Sonnet 4.6). **Retenu pour le POC** après test bout-en-bout
  (cf. ci-dessous) : qualité des brouillons de devis déjà excellente, pour un coût **~3–5× moindre**
  qu'Opus 4.8 et une latence plus faible — pertinent vu le volume attendu. Saisir la chaîne **exacte**,
  sans suffixe, dans le champ *Model* du provider (Channels/AI › Provider).
  - _Note_ : la décision initiale visait `claude-opus-4-8` (le plus capable). On reste sur Sonnet 4.6
    tant que la qualité suffit ; bascule vers Opus 4.8 triviale (un champ) si un cas le justifie.
    Tarifs de référence (cf. skill `claude-api`) : Opus 4.8 $5/M in · $25/M out ; Sonnet ~5× moins cher.
- **Surface principale** : **Writing Assistant** (Channels/AI › Writing Assistant) avec un/des
  outils custom à instructions (ex. « Draft a professional quote reply based on the customer's
  message », « Make this reply more formal »). L'agent déclenche → Claude rédige/reformule →
  **l'agent relit et édite → envoie**. Jamais d'envoi automatique.
- **Niveau de brouillon visé** : reformulation + 1er jet simple (validé avec l'utilisateur).
- Le stub `services/ai-draft/` devient **inutile** pour ce périmètre (pas de service webhook custom).

## Conséquences

- **Clé API Anthropic** = secret, saisie dans l'UI Zammad (jamais en clair dans le repo ni vue
  par l'assistant). Coût = facturation Anthropic directe (pas de marge Zammad).
- Pas de code custom à maintenir pour le POC ; on valide d'abord la **qualité des brouillons**.
- Langue de travail = **anglais** (cohérent avec le routage) ; les instructions des outils
  Writing Assistant doivent préserver la langue du texte d'entrée.

## Validation (2026-06-26) — test bout-en-bout OK

Test sur le ticket **#86003 « URGENT quote request »** (groupe Quote / Estimating) :
sélection d'un brouillon brut → Writing Assistant → outil **« Draft quote reply »** → Claude
(`claude-sonnet-4-6`) a généré un 1er jet conforme. Critères vérifiés : génération sans erreur
(provider Anthropic OK), **anglais préservé**, **placeholders** présents (`[contact name]`,
`[lead time…]`), **aucun prix/délai inventé**, bandeau *« check AI-generated content »* +
**Approve/Cancel** (human-in-the-loop, pas d'auto-send). Exemple de sortie consigné dans
[`docs/ai/writing-assistant-tools.md`](../ai/writing-assistant-tools.md).

## Porte de sortie (future, hors POC)

Si un besoin dépasse le natif (RAG sur devis passés, parsing de pièces jointes CAD, logique de
tarification, génération de brouillon complet 100% automatique depuis le mail), on rouvrira via un
**service externe** (webhook/trigger Zammad → `services/ai-draft/` → API Claude) dans un **ADR 0003**.