# Support par l'API Claude : design - **Date** : 2026-11-05 - **Statut** : brouillon, à valider par Marc - **Portée** : premier prototype opérationnel ; pas de design visuel peaufiné. ## 1. Intention Le projet a beaucoup exploré : détecteurs, étiquettes, agents Claude Code. Marc veut passer à l'**opérationnel** et faire du « AI as software » sur l'API Claude, avec ses crédits API, tracé dans LangSmith. Le premier usage, c'est le **support au client**. Un client (souvent un installateur, comme celui qui travaille pour Renault) paie le support. Il ne comprend pas ses courbes : du bruit, beaucoup d'anomalies. Il doit souvent lui-même rendre compte à quelqu'un. Aujourd'hui, Marc lui répond à la main : `/support ` puis `/presentation` dans Claude Code, avec trois présentations PDF pour le cas Renault. Ça prend du temps. Le diagnostic, lui, est déjà là, grâce aux détecteurs et à l'analyste ; il reste à en faire une réponse. On suppose des détecteurs fiables et un analyste performant : ce sont les deux seuls ingrédients du diagnostic. Le diagnostic analytique (détecteurs) reste sans LLM. **Succès** : à partir du mail d'un client, une séance produit un PDF que Marc envoie tel quel, juste, clair, pas trop technique, qui répond à la question et à rien d'autre. On y converge par essais successifs : le prompt et la forme du rapport s'affinent de séance en séance. ## 2. Buts, non-buts, anti-buts **Buts (v1)** - Une page web locale `support`, lancée par un script Python comme `labeling/labeling.py`. - Deux clients API, **support** et **analyste**, vivants pendant toute la séance. - Une seule sortie : un PDF dans la forme des présentations AIMsight, ciblé sur la question du mail. - Marc peut dialoguer avec chacun des deux, et redemander des versions du PDF. - Le coût de la séance est visible ; chaque appel est tracé dans LangSmith. - Tout vit dans `API/`, extractible tel quel vers un autre projet. **Non-buts (plus tard, peut-être)** - Connexion aux boîtes mail, suivi des conversations, gestion de dossiers clients. - Saisie vocale (Whisper, `~/whisper`). - Sortie HTML avec GIF, rapport de situation complet, mail de réponse. - Boutons d'action (« analyse approfondie ») : le langage naturel suffit d'abord. - Déploiement serveur, authentification, plusieurs séances en parallèle, reprise d'une séance après redémarrage du serveur. **Anti-buts (un échec même si ça marche)** - Le PDF répond à autre chose que la question, ou en dit plus qu'elle. - De l'interne dans le PDF : codes d'events, noms des détecteurs ou des outils, autres stations, identifiants (`SIM_CCID`, `ip`), vocabulaire de preuve en anglais. - Le PDF met en cause notre système, ou affirme ce qu'on ne sait pas (« l'ouvrage ne bouge pas »), ou donne des consignes au client. Les règles de `.claude/skills/presentation/SKILL.md` (« Ce que veut l'utilisateur », « Ce qui n'a pas marché ») s'appliquent. - L'analyse approfondie part sans que Marc l'ait demandée. - Un fichier de `API/` dépend de `.claude/`, de `agent-tools/`, de `detectors/` ou d'une autre partie du projet (hors des données, §6). ## 3. Le déroulé d'une séance 1. Marc colle le mail du client (texte et images) dans la page, ajoute au besoin son **contexte** (station, plage, ce qu'il sait du cas), et clique **Analyser**. 2. Le **support** tire du mail et du contexte la station (un dossier de `data/`), la plage (UTC) et la question reformulée. S'il lui manque quelque chose qu'il ne peut pas déduire, il le demande à Marc dans son fil, puis attend la réponse. 3. Le support envoie à l'**analyste** une demande précise : station, plage, question. 4. **Première passe de l'analyste** : il lance les détecteurs sur la plage (pas les étiquettes de `labeling/auto/` : en opérationnel, une plage nouvelle n'en a pas). Les détecteurs doivent dire quand la caméra bouge (tilt, pan, rotation) : aujourd'hui aucun ne lit `camera/`, c'est un préalable, développé dans `detectors/` (point 78 du plan vivant, §10) puis copié dans `API/`. Il retient les événements qui répondent à la question et produit **une illustration par événement retenu** (la courbe `corr_y` à plage grisée, ou l'image de la cause), qu'il regarde avant de la garder. Il rend au support les faits par événement (quand, cibles, ce qu'on voit, diagnostic), les illustrations, et à part une courte liste « hors question, pour Marc ». 5. Le support écrit la présentation (`.typ`) et la compile. Le PDF v1 s'affiche dans la page ; la liste « hors question » s'affiche dans le fil de l'analyste, pour Marc seulement. 6. **Retours de Marc** : - **Forme** (trop technique, trop long, une diapositive de trop) : il l'écrit au support, qui corrige et recompile (v2, v3…). - **Fond** (« ce n'est pas la pluie, regarde les images du 28 ») : il l'écrit au support, qui transmet à l'analyste, ou directement à l'analyste dans son fil. - **Analyse approfondie** : seulement à la demande explicite de Marc, dans le fil de l'analyste ou par le support qui relaie sa demande. L'analyste prend alors la plage avec les outils de lecture et les images, et critique ou complète les détecteurs. En v1, il n'exécute pas de code qu'il écrirait lui-même (décision de Claude : code arbitraire sur le poste, projet en lecture seule) ; on l'ajoutera quand une analyse approfondie en aura besoin. 7. Marc télécharge le PDF. La séance est gardée dans `API/cases/` (§6). **Une séance, un PDF**, même si le mail concerne plusieurs stations. En v1, Marc ne donne que des cas sur une seule station ; les cas croisés viendront ensuite. Le dossier de la séance et les outils sont pensés pour une station, sans rien interdire pour plusieurs. **L'analyste ne modifie jamais les détecteurs** (ni l'original ni la copie) : il complète ou critique leurs constats dans la séance, par un texte rendu au support (décision de Claude). ## 4. La page (disposition B, choisie par Marc) - **En haut** : la zone du mail (texte, et images collées depuis le presse-papiers), la zone de contexte, le bouton **Analyser**, le **coût de la séance** en dollars (par agent et total). - **Au milieu, deux fils côte à côte** : à gauche, le **support** ; à droite, l'**analyste**. Chacun avec sa zone de saisie. Dans le fil de l'analyste, on voit aussi les demandes du support et ce que l'analyste lui rend, pour savoir sur quoi le rapport s'appuie. Une ligne courte par appel d'outil (« → détecteurs NEBRASKA 20.10–31.10 ») suffit pour suivre ce qu'il fait. - **En dessous** : l'aperçu du PDF (le lecteur PDF du navigateur), la version (v1, v2…), le bouton **Télécharger**. Les messages s'affichent au fil de l'eau, pas seulement à la fin d'un tour (un tour de l'analyste peut durer plusieurs minutes). ## 5. Les deux clients **Mon choix (Claude), pas une demande de Marc** : la Messages API avec le SDK Python `anthropic` et des **outils que nous définissons** (Tool Runner, `client.beta.messages.tool_runner` avec `@beta_tool`, ou une boucle écrite à la main si les tours doivent être interrompus ou suivis plus finement). Pas d'Agent SDK : c'est Claude Code empaqueté, la frontière avec `.claude/` deviendrait floue, et nos outils déclarent exactement ce que chaque agent a le droit de faire. Pas de Managed Agents : les données et la fabrique Typst sont sur le poste. **Un agent vivant** = un historique de messages tenu en mémoire par le serveur de la page, auquel chaque message de Marc ou du support s'ajoute. L'historique est seulement ajouté, jamais réécrit (le modèle refuse un historique modifié qui contient ses blocs de réflexion). **Modèle** : `claude-opus-5-5` pour les deux (défaut de l'API), réflexion adaptative, `effort` réglé explicitement par agent (la valeur par défaut d'Opus 5.5 est `medium`). Passer le support sur `claude-sonnet-5-5` pour réduire le coût, c'est à Marc de le décider, après mesure. Mise en cache du prompt (outils et système stables en tête) ; `fallbacks: "default"` contre les refus des classifieurs. **Prompts** : en balises (``, ``, ``…), un fichier par prompt dans `API/prompts/`, versionnés. ### Le support - **Rôle** : il pilote la séance, parle à Marc, met en forme. Il ne fait pas d'analyse lui-même. - **Savoir** : les règles de rédaction du support (`.claude/skills/support/SKILL.md`, §5 : la langue du client, des faits plutôt que des consignes, rien d'interne), celles de la présentation (`.claude/skills/presentation/SKILL.md`, tout le fichier) et le modèle `modele.typ`, **copiés** dans `API/` ; la structure de la présentation (titre, résumé, une diapositive par événement, conclusions, clôture) se restreint à la question du mail. - **Outils** : - `demander_analyste(message)` : ajoute le message au fil de l'analyste, en le marquant comme venant du support, fait tourner l'analyste jusqu'à sa réponse, et la rend ; - `ecrire_presentation(source_typ)` : écrit le `.typ` dans le dossier de la séance ; - `compiler()` : compile avec la fabrique copiée, rend le nombre de diapositives qui débordent et les erreurs ; - `voir_page(n)` : l'image d'une page du PDF, pour vérifier la mise en page. - Poser une question à Marc n'est pas un outil : le support finit son tour par sa question, et attend. ### L'analyste - **Rôle** : le diagnostic. Première passe sur les détecteurs ; analyse approfondie sur demande de Marc seulement. - **Savoir** : le strict nécessaire, copié dans `API/` : ce que sont les familles et comment les lire (`labeling/familles.md`), les connaissances utiles de `labeling/connaissances/` (colonnes des déplacements, images de la caméra, cycle thermique, trous), la carte des événements, le mode d'emploi des outils de lecture (`.claude/skills/lire-les-donnees/SKILL.md`, adapté) et les règles de preuve (`agent-diagnostic/instructions.md`, §5). Choisir quoi copier relève du constructeur, avec une règle : un document n'entre que si l'analyste s'en sert. - **Outils** : - `detecteurs(station, debut, fin)` : les événements du journal sur la plage (copie de `detectors/categories.py` et des détecteurs) ; - `figure(...)` : la courbe `corr_y` à plage grisée, la caméra, la température (copie de `figure-y.py`), et l'image de la cause (copie de `image-de-la-cause.py`), écrites dans le dossier de la séance ; - `voir_image(chemin)` : rend l'image elle-même (bloc image) pour qu'il la regarde ; - `outil_de_lecture(nom, arguments)` : lance un des outils de lecture copiés (`inventaire`, `resume`, `plages`, `vignettes`, `qualite`…), sur une liste fermée ; c'est l'outil de l'analyse approfondie. - **Qui décide de l'approfondi** : chaque message entrant porte sa source (Marc ou le support). Le prompt de l'analyste dit de n'approfondir que sur la demande de Marc ; une demande du support qui l'exigerait se renvoie au support, qui la soumet à Marc. **Mon choix** : quand Marc écrit directement à l'analyste, l'échange (sa question, la réponse de l'analyste) est transmis au support au début de son tour suivant, pour qu'il en tienne compte dans le rapport. ## 6. Le dossier `API/`, un sous-projet Tout ce dont les clients ont besoin est dans `API/` ; rien de `API/` n'est lu par les agents Claude Code, et réciproquement. Si on extrait `API/` vers un nouveau projet, il tourne seul, avec des données. ``` API/ README.md # lancer la page, installer, les clés PROVENANCE.md # chaque fichier copié : d'où, à quel commit, le 2026-11-05 docs/ # ce design, puis la doc du sous-projet prompts/ # support.md, analyste.md (balises) knowledge/ # les documents copiés que lisent les agents tools/ # détecteurs, outils de lecture, figures copiés ; la fabrique Typst (brand/, build) copiée support/ # le serveur de la page, la page HTML, les deux clients cases/ # une séance par dossier : __/ .venv/ .env # hors de git ``` Les noms des sous-dossiers relèvent du constructeur ; la séparation, non. - **Données** : `data/` reste hors de `API/` (hors de git, pompé par `extraction/`). Son chemin est un réglage (défaut `../data`). C'est la seule dépendance extérieure. - **Versions** : les copies vieillissent (les détecteurs évoluent par `/detector-learner`). `PROVENANCE.md` dit d'où vient chaque copie et à quel commit ; on les rafraîchit à la main, quand Marc le décide. - **Dossier d'une séance** (`cases/__/`) : le mail et ses images, le contexte, les deux historiques (JSON, sauvegardés à chaque tour), les figures, le `.typ`, les PDF par version. Il contient des mails et des images de clients, comme `support/`. Versionné comme `support/`, commité seulement quand Marc valide le PDF. - **Dépendances** : `API/.venv` avec `anthropic`, `langsmith`, `matplotlib` (figures) ; Typst ≥ 0.14 et `pdftotext` sur le poste. - **Clés** : `ANTHROPIC_API_KEY` et celles de LangSmith dans `API/.env`, hors de git. Traces LangSmith : un projet LangSmith dédié, une trace par séance, les deux agents dedans, **complètes** (mails, images, sorties des outils : accord de Marc, sans masquage). ## 7. Contraintes - Lecture seule sur les stations et les données, comme tout le projet. - Le serveur écoute sur `127.0.0.1` seulement. - Bibliothèque standard pour le serveur et la page (pas de framework), comme les autres pages du projet. - Toute heure en UTC ; la page et les documents de `API/` en français ; le PDF dans la langue du client. ## 8. Laissé au constructeur - Le découpage du code, le mécanisme d'affichage au fil de l'eau (SSE ou interrogation périodique), le format exact des historiques. - Les prompts de départ, à partir des skills `support` et `presentation` et de l'agent `analyste` ; ils s'affineront par les séances. - Les arguments exacts des outils, les valeurs d'`effort`, la fenêtre de contexte (compaction si un fil grossit trop). - Le calcul du coût (usage de chaque réponse × tarif du modèle). ## 9. Premier essai Un cas sur une seule station, donné par Marc. À défaut (décision de Claude) : une des trois stations du cas Renault (NEBRASKA, octobre), avec un mail écrit d'après la réunion et une question précise (« pourquoi les courbes sont-elles si bruitées ? »), pas « que s'est-il passé en octobre », sinon on ne teste pas la règle de la question et rien d'autre. Comparer ensuite le PDF aux constats de `support/2026-11-02_NEBRASKA_rapport-situation/`, qui reposent sur la caméra qui bouge : l'essai n'a de sens qu'après le préalable du §10. ## 10. Ordre 1. **Préalable, hors de `API/`** : les détecteurs lisent le mouvement de la caméra (point 78 du plan vivant `docs/superpowers/plans/2026-10-23-journal-du-matin.md`), mesuré par le benchmark de `/detector-learner`. 2. **`API/`** : la page, les deux clients, les outils copiés, la fabrique ; on peut le construire en parallèle du point 1 sur les détecteurs actuels, puis rafraîchir la copie. 3. Le premier essai (§9), puis les séances qui affinent les prompts.