API: support page with two Claude API clients, support and analyst (D-133)
Self-contained sub-project API/: a local support page where Marc pastes a client's mail; a support agent and an analyst agent stay alive for the session and produce a slide PDF that answers the client's question. Tools, detectors, knowledge and Typst brand are copied (API/PROVENANCE.md). First real case: Crissier (LENZSPITZE), workflow validated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
874f6bf7ea
commit
8ba75b92fa
130 files changed
+42094
No files matched your search
@@ -0,0 +1,145 @@
|
||||
# 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 <STATION>` 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 (`<role>`, `<regles>`, `<sortie>`…), 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 : <date>_<STATION>_<sujet>/
|
||||
.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/<date>_<STATION>_<sujet>/`) : 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.
|
||||
@@ -0,0 +1,185 @@
|
||||
# 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 `<API>/../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 : `<source>marc</source>` ou `<source>support</source>`.
|
||||
- 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 <dossier> --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 `<source>marc</source>`.
|
||||
- [ ] **É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 <donnees>/<station> --du <du> --au <au>`
|
||||
- `outil_de_lecture(nom: str, arguments: list[str])` → `tools/agent-tools/<nom>.py <arguments>` ; `nom` hors de `LECTURE` → erreur ; pour `graphique`, `ensemble`, `jours`, `metriques`, `vignettes`, `qualite`, ajouter `--sortie <dossier de la séance>`
|
||||
- `figure_courbes(nom: str, debut: str, fin: str, cibles: list[str], options: list[str])` → `tools/figures/figure-y.py <donnees>/<station> <séance>/<nom>.png <debut> <fin> --cibles <…> <options>` (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 <donnees>/<station> <x> <y> <séance>/<nom>.png <instants>`
|
||||
- `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 `<donnees>/<station>` existe ; renomme le dossier de la séance en `<AAAA-MM-JJ>_<STATION>_<sujet>` ; 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 `<séance>/<station minuscule>.typ`
|
||||
- `compiler()` → copie le `.typ` (en `main.typ`) et les PNG de la séance dans `tools/typst/documents/<slug>/`, lance `brand/tools/build.py <slug>` depuis `tools/typst/`, copie `build/<slug>-draft.pdf` vers `<séance>/v<N>.pdf` (N = 1 + nombre de `v*.pdf` présents), rend `v<N>.pdf : <k> 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/<AAAA-MM-JJ>_<HHMMSS>/`, 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 : `<role>`, `<premiere_passe>`, `<approfondi>`, `<rendu>`, `<regles>`, puis le savoir de `knowledge/analyste/` inclus par le code au chargement (balise `<savoir fichier="…">` 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 `<source>marc</source>` 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 : `<role>`, `<deroule>`, `<presentation>`, `<redaction>`, `<interdits>`, 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 `<echange_marc_analyste>`. 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 `<iframe>` rechargé à chaque nouvelle version, son numéro et **Télécharger**. Interrogation de `/evenements` chaque seconde.
|
||||
- [ ] **Étape 3 : vérifier par lancement et capture.** `API/.venv/bin/python API/support/serveur.py`, coller le mail de la Task 4 étape 4, **Analyser** : les deux fils se remplissent au fil de l'eau, le coût monte, le PDF v1 apparaît et se télécharge. Écrire au support « La conclusion est trop longue, deux puces au plus » → v2. Écrire au support pendant qu'il travaille → refusé, « occupé ». Capture de la page à montrer à Marc.
|
||||
|
||||
### Task 6 : documenter et livrer
|
||||
|
||||
**Fichiers :**
|
||||
- Modifier : `docs/decisions.md` (D-133), `CLAUDE.md` (carte et « État »), `run.md` (la commande de la page)
|
||||
|
||||
- [ ] **Étape 1 : D-133**, au format du fichier : le support par l'API Claude dans le sous-projet `API/`, séparé de `.claude/` ; options écartées (Agent SDK, Managed Agents) et pourquoi ; renvoi au design.
|
||||
- [ ] **Étape 2 : `CLAUDE.md`.** Une ligne dans « État et prochaine étape » (support par l'API, prototype) et une entrée `API/` dans la carte du dépôt (sous-projet autonome ; sa doc dans `API/README.md`) ; rester sous 200 lignes.
|
||||
- [ ] **Étape 3 : montrer à Marc** la capture et le PDF de l'essai ; attendre sa validation.
|
||||
- [ ] **Étape 4 : commit, après sa validation seulement.**
|
||||
```bash
|
||||
git add API docs/decisions.md CLAUDE.md run.md docs/superpowers/plans/2026-10-23-journal-du-matin.md
|
||||
git commit -m "API: support page with two Claude API clients, support and analyst (D-133)"
|
||||
```
|
||||
Vérifier avant que `git status` ne montre ni `API/.env` ni `API/.venv/`.
|
||||
Reference in new issue
Block a user