# Support par l'API Claude : plan de construction > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **But** : une page locale `support` où Marc colle le mail d'un client ; deux clients de l'API Claude (support, analyste) produisent un PDF de diapositives qui répond à la question, et Marc les fait corriger jusqu'à un PDF qu'il peut envoyer. **Architecture** : un serveur de la bibliothèque standard (`ThreadingHTTPServer`, 127.0.0.1) sert la page et tient une séance en mémoire. Chaque agent est un historique de messages, seulement ajouté, et une boucle d'outils écrite à la main sur `client.beta.messages.stream`. Les outils lancent des copies des détecteurs, des outils de lecture, des scripts de figures et de la fabrique Typst, toutes dans `API/tools/`. LangSmith trace chaque appel. **Technique** : Python 3.14, `anthropic`, `langsmith`, `matplotlib` dans `API/.venv` ; Typst ≥ 0.14 (`~/.local/bin/typst`), `pdftotext`, `pdftoppm`. **Spec** : `API/docs/2026-11-05-support-api-design.md` (validé par Marc le 2026-11-05). ## Contraintes globales - Tout dans `API/` ; aucun fichier de `API/` ne lit `.claude/`, `agent-tools/`, `detectors/` ni `labeling/` à l'exécution. Seule dépendance extérieure : le dossier des données, réglage `AIMSIGHT_DATA` (défaut `/../data`). - Modèle `claude-opus-5-5` pour les deux agents, `thinking={"type": "adaptive"}`, `output_config={"effort": ...}` explicite : support `"medium"`, analyste `"high"`. `betas=["server-side-fallback-2026-07-01"]`, `fallbacks="default"`. Streaming, `max_tokens=64000`, `.get_final_message()`. - Tarifs pour le coût (Opus 5.5, $ par million de tokens) : entrée 4,00 ; sortie 20,00 ; lecture du cache 0,20 ; écriture du cache 5,00. - Historique **seulement ajouté** : jamais réécrit ni tronqué (le modèle refuse un historique édité qui contient ses blocs de réflexion). Un message assistant qui demande des outils et ses `tool_result` s'ajoutent ensemble, ou pas du tout. - Chaque message entrant porte sa source en tête : `marc` ou `support`. - Le serveur écoute sur `127.0.0.1:8770` seulement. Bibliothèque standard pour le serveur, HTML et JS sans framework pour la page. - Toute heure en UTC. Page, prompts et documents de `API/` en français ; le PDF dans la langue du client. - Lecture seule sur les données. Les outils n'écrivent que dans le dossier de la séance et dans `API/tools/typst/{documents,build}/`. - Pas de tests automatisés dans le projet (D-008) : un seul `API/support/check.py` à `assert`, plus des vérifications par lancement. - Pas de commit avant la validation de Marc (sa règle pour les essais de fonctionnalités). Un seul commit à la fin (Task 6). ## Points d'attention 1. **Mail sans station ni plage** : le support pose sa question à Marc et n'appelle pas l'analyste. Vérifié en Task 4, étape 5. 2. **Station absente de `data/`, ou aucune mesure sur la plage** : l'outil rend une erreur claire (`is_error`), l'analyste le dit, le support le dit à Marc ; aucune exception ne remonte au serveur. `check.py`, Task 3. 3. **Marc écrit pendant qu'un agent travaille** : le serveur répond 409 et la page affiche « occupé » ; l'historique reste valide. Le support est occupé tant que l'analyste qu'il a appelé l'est. Task 5. 4. **Erreur de l'API au milieu d'un tour** (surcharge, quota) : le tour s'arrête sur un événement d'erreur, sans `tool_use` orphelin dans l'historique ; le message suivant de Marc repart proprement. `check.py`, Task 2. 5. **Sortie d'outil énorme ou image trop grande** : texte plafonné à 40 000 caractères avec la mention `[… tronqué : N caractères]` ; image réduite à 1568 px de côté au plus. `check.py`, Task 3. --- ### Task 1 : le dossier `API/` et ses copies **Fichiers :** - Créer : `API/README.md`, `API/PROVENANCE.md`, `API/.gitignore`, `API/requirements.txt` - Copier : `agent-tools/*.py` → `API/tools/agent-tools/` ; `detectors/*.py` (sans `archive/`) → `API/tools/detectors/` ; `.claude/skills/presentation/figure-y.py` et `image-de-la-cause.py` → `API/tools/figures/` ; `~/docfactory-presentation/brand/` → `API/tools/typst/brand/` - Copier, savoir de l'analyste → `API/knowledge/analyste/` : `labeling/familles.md`, `labeling/carte-des-etiquettes.md`, `labeling/connaissances/{chaine-de-mesure,colonnes-des-deplacements,cycle-thermique,images-de-la-camera,les-trous,metriques-de-qualite}.md`, `.claude/skills/lire-les-donnees/SKILL.md` (→ `lire-les-donnees.md`), `agent-diagnostic/instructions.md` §5 seul (→ `regles-de-preuve.md`) - Copier, savoir du support → `API/knowledge/support/` : `.claude/skills/presentation/SKILL.md` (→ `presentation.md`), `.claude/skills/presentation/modele.typ`, `.claude/skills/support/SKILL.md` §5 seul (→ `redaction.md`) **Interfaces :** - Produit : `API/tools/detectors/categories.py --du AAAA-MM-JJ --au AAAA-MM-JJ` (inchangé) ; `API/tools/figures/figure-y.py` (mêmes arguments que l'original) ; `API/tools/typst/` = fabrique réduite (`brand/`, `documents/`, `build/`). - [ ] **Étape 1 : copier.** `agent-tools/` et `detectors/` restent frères dans `API/tools/` : leurs `sys.path` relatifs (`.., agent-tools`) marchent tels quels. Dans `figures/figure-y.py`, remplacer `"..", "..", "..", "agent-tools"` par `"..", "agent-tools"`. Dans les copies du savoir, les chemins qui pointent hors de `API/` (`.claude/…`, `agent-tools/…`) deviennent ceux de `API/tools/…` ; le reste du texte est inchangé. - [ ] **Étape 2 : `PROVENANCE.md`.** Une ligne par copie : source, destination, `git rev-parse --short HEAD` du jour (pour `brand/` : le `VERSION` de la fabrique), date 2026-11-05, et ce qui a été adapté. En tête, comment rafraîchir : recopier, puis mettre à jour la ligne. - [ ] **Étape 3 : `.gitignore`, `requirements.txt`, venv.** Ignorer `.venv/`, `.env`, `__pycache__/`, `tools/typst/documents/`, `tools/typst/build/`. `requirements.txt` : `anthropic`, `langsmith`, `matplotlib`. Lancer : `python3 -m venv API/.venv && API/.venv/bin/pip install -r API/requirements.txt` - [ ] **Étape 4 : vérifier les détecteurs copiés.** Lancer : `cd API && .venv/bin/python tools/detectors/categories.py ../data/NEBRASKA --du 2026-10-20 --au 2026-11-01` Attendu : les mêmes lignes que `python3 detectors/categories.py data/NEBRASKA --du 2026-10-20 --au 2026-11-01` depuis la racine (`diff` vide). - [ ] **Étape 5 : vérifier les figures et la fabrique.** Lancer : `cd API && .venv/bin/python tools/figures/figure-y.py ../data/NEBRASKA /tmp/f.png 2026-10-20T00:00Z 2026-11-01T00:00Z --cam tilt,pan --cibles COLJ20,COLH21` → PNG écrit. Puis copier `knowledge/support/modele.typ` dans `tools/typst/documents/essai/main.typ` avec les PNG qu'il cite (pris dans `support/2026-11-02_BREITHORN_rapport-situation/`), et `cd tools/typst && ../../.venv/bin/python brand/tools/build.py essai` → `build/essai-draft.pdf` existe. Supprimer `documents/essai/` et `build/` ensuite. - [ ] **Étape 6 : `README.md`.** Installer (étape 3), les clés dans `API/.env` (`ANTHROPIC_API_KEY`, `LANGSMITH_API_KEY`, `LANGSMITH_TRACING=true`, `LANGSMITH_PROJECT=aimsight-support`), `AIMSIGHT_DATA`, lancer la page (`API/.venv/bin/python API/support/serveur.py`), ce que contient chaque dossier. ### Task 2 : l'agent, une boucle d'outils qui reste vivante **Fichiers :** - Créer : `API/support/agent.py`, `API/support/check.py` **Interfaces :** - Produit : - `PRIX = {"claude-opus-5-5": {"entree": 4.0, "sortie": 20.0, "cache_lu": 0.20, "cache_ecrit": 5.0}}` ($/Mtok) - `class Agent(nom: str, systeme: str, outils: list[dict], executer: Callable[[str, dict], str | list[dict]], client, journal: Callable[[dict], None], effort: str, modele: str = "claude-opus-5-5")` - `Agent.messages: list[dict]`, `Agent.cout: float` ($), `Agent.occupe: bool` - `Agent.tour(contenu: str | list[dict], source: str) -> str` : ajoute le message de l'utilisateur (source en tête), fait tourner la boucle jusqu'à `end_turn` et rend le texte final - `Agent.sauver(chemin: Path) -> None` : écrit `messages` en JSON - événements du journal : `{"agent": nom, "type": "entree" | "texte" | "outil" | "erreur" | "cout", "texte": str, "source": str}` ; `"entree"` : le message reçu, avec sa source (`marc` ou `support`), pour que le fil de l'analyste montre aussi les demandes du support ; pour `"cout"`, `"texte"` = le coût cumulé de l'agent, formaté `0.42` ; `"source"` seulement pour `"entree"` - [ ] **Étape 1 : écrire les vérifications dans `check.py`** avec un faux client (un objet dont `beta.messages.stream(**kw)` est un gestionnaire de contexte qui rend des réponses scriptées, avec `content`, `stop_reason` et `usage`) : - `check_boucle()` : réponse 1 = `tool_use` (`detecteurs`), réponse 2 = `end_turn` avec un texte → `tour` rend ce texte ; `messages` contient, dans l'ordre, user, assistant (tool_use), user (tool_result du même `tool_use_id`), assistant ; l'exécuteur a été appelé une fois avec le bon nom et la bonne entrée. - `check_erreur()` : la réponse 2 lève une exception → `tour` ne la propage pas, émet un événement `"erreur"` ; la dernière entrée de `messages` n'est pas un assistant avec `tool_use` sans `tool_result` ; `occupe` revient à `False`. - `check_cout()` : usage `input_tokens=1_000_000, output_tokens=100_000, cache_read_input_tokens=0, cache_creation_input_tokens=0` → `cout == 6.0`. - `check_source()` : le premier bloc texte du message de l'utilisateur commence par `marc`. - [ ] **Étape 2 : lancer, constater l'échec.** `API/.venv/bin/python API/support/check.py` → ImportError sur `agent`. - [ ] **Étape 3 : écrire `agent.py`.** Appel : `client.beta.messages.stream(model, max_tokens=64000, system=[{"type": "text", "text": systeme, "cache_control": {"type": "ephemeral"}}], tools=outils, messages=messages, thinking={"type": "adaptive"}, output_config={"effort": effort}, betas=["server-side-fallback-2026-07-01"], fallbacks="default", cache_control={"type": "ephemeral"})`, puis `.get_final_message()`. Le contenu de la réponse est ajouté en dicts (`b.model_dump(mode="json", exclude_none=True)`). `stop_reason` : `tool_use` → exécuter **tous** les `tool_use`, puis ajouter l'assistant et un seul message user avec tous les `tool_result` ; un exécuteur qui lève → `tool_result` avec `is_error: True` et le message d'erreur ; `pause_turn` → renvoyer tel quel ; `end_turn` → fin ; `max_tokens` ou `refusal` → événement `"erreur"` et fin. Un événement `"texte"` par bloc texte de l'assistant ; un événement `"outil"` par appel (`nom` et entrée résumée sur une ligne). Coût : usage × `PRIX`, cumulé, un événement `"cout"` par réponse. Une exception autour d'un appel à l'API : événement `"erreur"`, l'assistant n'est pas ajouté, fin du tour. - [ ] **Étape 4 : lancer `check.py`** → `ok` pour chaque vérification. ### Task 3 : les outils des deux agents **Fichiers :** - Créer : `API/support/outils.py` - Modifier : `API/support/check.py` (ajouter les vérifications des outils) **Interfaces :** - Consomme : `Agent` (Task 2) seulement pour l'outil `demander_analyste`, par un rappel que lui donne la séance. - Produit : - `OUTILS_ANALYSTE: list[dict]`, `OUTILS_SUPPORT: list[dict]` (schémas de l'API, `strict: True`, `additionalProperties: false`) - `class Boite(dossier_seance: Callable[[], Path], station: Callable[[], str | None], donnees: Path, demander_analyste: Callable[[str], str], poser: Callable[[str, str], Path])` (`poser(station, sujet)` : le rappel de la séance qui renomme son dossier et retient la station) avec `executer_analyste(nom: str, entree: dict) -> str | list[dict]` et `executer_support(nom: str, entree: dict) -> str | list[dict]` - `LECTURE = {"inventaire", "resume", "plages", "jours", "vignettes", "qualite", "ensemble", "graphique", "metriques", "stations"}` - `plafonner(texte: str, n: int = 40_000) -> str` ; `bloc_image(chemin: Path) -> dict` (bloc image en base64, PNG ou JPEG, plus grand côté ≤ 1568 px) Outils de l'**analyste** (tous lancés par `subprocess.run` avec `API/.venv/bin/python`, `cwd` = le parent de `donnees`, délai 600 s, stdout et stderr rendus, plafonnés) : - `detecteurs(station: str, du: str, au: str)` → `tools/detectors/categories.py / --du --au ` - `outil_de_lecture(nom: str, arguments: list[str])` → `tools/agent-tools/.py ` ; `nom` hors de `LECTURE` → erreur ; pour `graphique`, `ensemble`, `jours`, `metriques`, `vignettes`, `qualite`, ajouter `--sortie ` - `figure_courbes(nom: str, debut: str, fin: str, cibles: list[str], options: list[str])` → `tools/figures/figure-y.py / /.png --cibles <…> ` (station : celle de la séance, posée par le support, cf. Task 4) - `image_de_la_cause(nom: str, x: int, y: int, instants: list[str])` → `tools/figures/image-de-la-cause.py / /.png ` - `voir_image(chemin: str)` → `[bloc_image(…)]` ; chemin relatif au dossier de la séance, ou `images/…` de la station ; tout autre chemin (`..`, absolu) → erreur Outils du **support** : - `poser_station(station: str, sujet: str)` → vérifie que `/` existe ; renomme le dossier de la séance en `__` ; rend la liste des sous-dossiers de données de la station - `demander_analyste(message: str)` → le rappel de la séance - `ecrire_presentation(source_typ: str)` → écrit `/.typ` - `compiler()` → copie le `.typ` (en `main.typ`) et les PNG de la séance dans `tools/typst/documents//`, lance `brand/tools/build.py ` depuis `tools/typst/`, copie `build/-draft.pdf` vers `/v.pdf` (N = 1 + nombre de `v*.pdf` présents), rend `v.pdf : diapositive(s) qui débordent` (`pdftotext` puis compter `Overflow`) ou la sortie d'erreur de Typst, sans créer de version - `voir_page(n: int)` → `pdftoppm -f n -l n -png -r 80` sur la dernière version, rendu par `bloc_image` - [ ] **Étape 1 : vérifications dans `check.py`** (sans appel à l'API ; sur `data/NEBRASKA`) : - `check_lecture_refusee()` : `outil_de_lecture("rm", [])` rend une erreur et ne lance rien. - `check_chemin()` : `voir_image("../../.env")` et `voir_image("/etc/passwd")` → erreur. - `check_station_absente()` : `detecteurs("NULLEPART", "2026-10-01", "2026-10-02")` → une erreur qui nomme la station, pas d'exception. - `check_detecteurs()` : `detecteurs("NEBRASKA", "2026-10-20", "2026-11-01")` → texte non vide. - `check_plafond()` : `plafonner("x" * 50_000)` fait au plus 40 100 caractères et finit par `tronqué : 50000 caractères]`. - `check_image()` : `bloc_image` d'une image de `data/NEBRASKA/images/` → `media_type` `image/jpeg`, image décodée de côté ≤ 1568. - `check_compiler()` : séance temporaire contenant `modele.typ` (en `nebraska.typ`) et ses PNG → `compiler()` rend `v1.pdf : …` et `v1.pdf` existe ; une seconde fois → `v2.pdf`. Un `.typ` cassé (`#oups(`) → erreur, pas de `v3.pdf`. - [ ] **Étape 2 : lancer `check.py`** → échec (pas de `outils`). - [ ] **Étape 3 : écrire `outils.py`.** - [ ] **Étape 4 : lancer `check.py`** → `ok` partout. ### Task 4 : les prompts, la séance et LangSmith **Fichiers :** - Créer : `API/prompts/support.md`, `API/prompts/analyste.md`, `API/support/seance.py` **Interfaces :** - Consomme : `Agent` (Task 2), `Boite`, `OUTILS_*` (Task 3). - Produit : `class Seance(mail: str, images: list[tuple[str, bytes]], contexte: str, donnees: Path, journal: Callable[[dict], None])`, avec : - `dossier: Path` (d'abord `API/cases/_/`, renommé par `poser_station`), `station: str | None` - `support: Agent`, `analyste: Agent` - `demarrer() -> None` : écrit `demande.md` (mail, contexte, images en fichiers), puis premier tour du support avec le mail, les images (blocs image) et le contexte - `parler(agent: str, texte: str) -> None` : `"support"` ou `"analyste"`, source `marc` - `occupe(agent: str) -> bool` : le support est occupé aussi pendant qu'il attend l'analyste - `cout() -> dict` : `{"support": float, "analyste": float, "total": float}` - `derniere_version() -> Path | None` - [ ] **Étape 1 : `prompts/analyste.md`**, en balises : ``, ``, ``, ``, ``, puis le savoir de `knowledge/analyste/` inclus par le code au chargement (balise `` par fichier : prompt stable, donc en cache). Il doit dire : - première passe : `detecteurs` sur la plage, les événements qui répondent à la question, **une illustration par événement retenu** (courbe `corr_y` à plage grisée, ou image de la cause), regardée par `voir_image` avant d'être gardée ; - approfondi (`outil_de_lecture`, images, critique des détecteurs) seulement si le message vient de `marc` et le demande ; une demande du support qui l'exigerait est renvoyée au support, pour Marc ; - le rendu au support : un bloc par événement (quand, cibles, ce qu'on voit, diagnostic, illustration), puis `Hors question (pour Marc)` ; vocabulaire de preuve (`regles-de-preuve.md`) ; il ne modifie jamais les détecteurs. - [ ] **Étape 2 : `prompts/support.md`**, en balises : ``, ``, ``, ``, ``, puis `knowledge/support/` inclus de la même façon. Il doit dire : - tirer station, plage UTC et question du mail et du contexte ; ce qui manque, le demander à Marc et finir son tour ; sinon `poser_station`, puis `demander_analyste` avec station, plage et question ; - la présentation suit `presentation.md` et `modele.typ`, **restreinte à la question du mail** : seuls les événements qui y répondent ; titre, résumé, une diapositive par événement, conclusions, clôture ; rien de la section « Hors question » ; - `compiler`, puis `voir_page` sur chaque page à image ; corriger jusqu'à zéro débordement ; - un retour de forme : corriger seul ; un retour de fond : le transmettre à l'analyste ; - les interdits (spec §2, anti-buts) : rien d'interne, ne pas se mettre en cause, ne rien affirmer sur l'ouvrage, aucune consigne au client. - [ ] **Étape 3 : `seance.py`.** Un client `anthropic.Anthropic()` enveloppé par `langsmith.wrappers.wrap_anthropic`, et `demarrer`, `parler` décorés `@langsmith.traceable` (le nom de la séance en métadonnée) : une trace par séance. Clés lues dans `API/.env` par un petit lecteur `CLE=valeur` (pas de dépendance). Quand Marc parle à l'analyste, l'échange (sa question, la réponse) est mis de côté puis ajouté en tête du prochain tour du support, dans ``. Les deux historiques sont sauvés (`support.json`, `analyste.json`) dans le dossier de la séance après chaque tour. - [ ] **Étape 4 : essai sans page** (coûte quelques dollars). Un mail court, station explicite : `cd API && .venv/bin/python -c "from support.seance import Seance; …"` avec le mail « Bonjour, pourquoi les courbes de NEBRASKA sont-elles si bruitées du 28 au 31 octobre ? », journal = `print`. Attendu : `poser_station` ; un `demander_analyste` ; l'analyste lance `detecteurs`, produit au moins une figure et la regarde ; le support écrit, compile, regarde ses pages ; `v1.pdf` existe ; `cache_read_input_tokens > 0` à partir du deuxième appel d'un même agent ; une trace dans le projet LangSmith `aimsight-support`. - [ ] **Étape 5 : essai du point d'attention 1.** Mail « Bonjour, les courbes sont bizarres depuis la semaine passée, tu peux regarder ? » sans contexte → le support pose une question à Marc, et aucun `demander_analyste`. ### Task 5 : la page et le serveur **Fichiers :** - Créer : `API/support/serveur.py`, `API/support/page.html` **Interfaces :** - Consomme : `Seance` (Task 4). - Produit, routes de `127.0.0.1:8770` : - `GET /` → `page.html` - `POST /analyser` `{"mail": str, "contexte": str, "images": [{"nom": str, "type": str, "base64": str}]}` → crée la séance, lance `demarrer` dans un fil ; 409 si une séance tourne déjà - `POST /message` `{"agent": "support" | "analyste", "texte": str}` → `parler` dans un fil ; 409 si `occupe(agent)` - `GET /evenements?depuis=N` → `{"evenements": [...], "n": int, "cout": {...}, "version": "v2.pdf" | null, "occupe": {"support": bool, "analyste": bool}}` - `GET /pdf` → la dernière version (`application/pdf`) - [ ] **Étape 1 : `serveur.py`.** `ThreadingHTTPServer`, une seule séance à la fois, la liste des événements en mémoire derrière un `threading.Lock`. Au lancement, ouvrir la page dans le navigateur comme les autres pages du projet (`explorer.exe` sous WSL, sinon `webbrowser`), sans dépendre de `src/common/`. - [ ] **Étape 2 : `page.html`, disposition B** (maquette : `.superpowers/brainstorm/*/content/page-support.html`) : en haut, le mail (zone de texte ; une image collée depuis le presse-papiers s'ajoute en vignette), le contexte, **Analyser**, le coût (support, analyste, total, en $) ; au milieu, deux fils côte à côte, **support** à gauche, **analyste** à droite, chacun avec sa zone de saisie, désactivée et marquée « occupé » quand l'agent travaille ; les événements `"outil"` en une ligne grise, les `"erreur"` en rouge ; en dessous, le PDF dans un `