Files
Support-Agent/API/docs/2026-11-05-support-api-plan.md
maximeandClaude Opus 5.5 8ba75b92fa 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>
2026-11-05 12:58:39 +01:00

23 KiB
Raw Permalink Blame History

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.

    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/.