From 6e9f69a006204c7bfd995f4ef482b05c66bb98cb Mon Sep 17 00:00:00 2001 From: maxime Date: Thu, 5 Nov 2026 13:08:07 +0100 Subject: [PATCH] API: the analyst gets its maps in the prompt and reads the rest on demand (D-136) Co-Authored-By: Claude Opus 5.5 --- API/README.md | 2 +- API/prompts/analyste.md | 2 +- API/support/check.py | 21 ++++++++++++++++++++- API/support/outils.py | 22 ++++++++++++++++++++++ API/support/seance.py | 28 +++++++++++++++++++++++++--- docs/decisions.md | 7 +++++++ 6 files changed, 76 insertions(+), 6 deletions(-) diff --git a/API/README.md b/API/README.md index 5cf6a8c..d12469c 100644 --- a/API/README.md +++ b/API/README.md @@ -34,7 +34,7 @@ La page s'ouvre sur `http://127.0.0.1:8770`. Une séance à la fois ; elle est g - `docs/` : le design et le plan. - `prompts/` : les prompts système du support et de l'analyste (en balises) ; le savoir de `knowledge/` y est ajouté au chargement. -- `knowledge/` : ce que lisent les agents, copié du projet : `analyste/` (familles, carte des étiquettes, connaissances, outils de lecture, règles de preuve), `support/` (présentation, modèle Typst, rédaction). +- `knowledge/` : ce que lisent les agents, copié du projet (pour l'analyste, les cartes dans le prompt, le reste à la demande par `lire_document`, D-136) : `analyste/` (familles, carte des étiquettes, connaissances, outils de lecture, règles de preuve), `support/` (présentation, modèle Typst, rédaction). - `tools/` : copies des outils de lecture (`agent-tools/`), des détecteurs (`detectors/`), des figures (`figures/`), de la fabrique Typst (`typst/brand/`) ; `journal.py`, les événements des détecteurs avec leurs capteurs ; `stabilite.py`, la médiane de corr_y jour par jour et son étendue, par cible. - `support/` : le serveur, la page, les deux agents, leurs outils, `check.py` (vérifications : `API/.venv/bin/python API/support/check.py`). - `cases/` : une séance par dossier : le mail, le contexte, les deux historiques, les figures, le source Typst, les PDF par version. Contient des mails et des images de clients. diff --git a/API/prompts/analyste.md b/API/prompts/analyste.md index 9a2903d..65881ce 100644 --- a/API/prompts/analyste.md +++ b/API/prompts/analyste.md @@ -46,4 +46,4 @@ Puis une section `Hors question (pour Marc)` : ce que tu as vu sans que le clien - Un outil qui échoue rend son erreur : dis-la au support plutôt que de deviner (station absente, aucune mesure sur la plage). -Le savoir qui suit est copié du projet. Lis-le comme une référence : `lire-les-donnees.md` pour les outils de lecture, `familles.md` et `carte-des-etiquettes.md` pour reconnaître un phénomène, les connaissances pour raisonner sur un cas nouveau. +Le savoir qui suit est copié du projet : les cartes (`familles.md`, le sommaire et les règles de la carte des étiquettes, les règles de preuve), puis l'index de ce qui se lit à la demande par `lire_document` : la fiche d'un phénomène de la carte quand tu le rencontres, le mode d'emploi des outils de lecture avant `outil_de_lecture`, les connaissances pour raisonner sur un cas nouveau. Ne lis que ce qui sert au cas : chaque document lu reste dans ta conversation. diff --git a/API/support/check.py b/API/support/check.py index 2a67bf9..4d59023 100644 --- a/API/support/check.py +++ b/API/support/check.py @@ -238,12 +238,31 @@ def check_stabilite(): assert ligne.split()[1] == "3", ligne # 4 jours, dont le 17 écarté +def check_lire_document(): + b = boite(seance_temporaire()) + t = b.executer_analyste("lire_document", {"nom": "carte-des-etiquettes.md", + "section": "La station s'éteint faute d'énergie"}) + assert t.startswith("#### La station s'éteint faute d'énergie") and "#### Coupure du secteur" not in t, t[:200] + assert "Les frontières" in b.executer_analyste("lire_document", {"nom": "familles.md", "section": ""}) + assert "sections" in leve(b.executer_analyste, "lire_document", {"nom": "familles.md", "section": "n'existe pas"}) + leve(b.executer_analyste, "lire_document", {"nom": "../../.env", "section": ""}) + + +def check_cartes(): + from seance import systeme + a = systeme("analyste") + assert len(a) < 60_000, len(a) # les cartes, pas tout le savoir (214 000 caractères avant) + assert "## Sommaire" in a and "#### Un trou commun" not in a and "## Les frontières" in a + assert "lire-les-donnees.md" in a # dans l'index + assert "#### Un trou commun" not in a and "## Les outils" not in a + + def check_stations_dans_la_seance(): from outils import AVEC_SORTIE assert "stations" in AVEC_SORTIE -CHECKS = [check_stabilite, check_image_proche, check_max_tokens, check_sans_repli, check_capture_reduite, check_stations_dans_la_seance, check_boucle, check_erreur, check_cout, check_source, check_outil_qui_leve, check_lecture_refusee, +CHECKS = [check_lire_document, check_cartes, check_stabilite, check_image_proche, check_max_tokens, check_sans_repli, check_capture_reduite, check_stations_dans_la_seance, check_boucle, check_erreur, check_cout, check_source, check_outil_qui_leve, check_lecture_refusee, check_chemin, check_station_absente, check_detecteurs, check_plafond, check_image, check_compiler] if __name__ == "__main__": diff --git a/API/support/outils.py b/API/support/outils.py index e15be99..31e07ea 100644 --- a/API/support/outils.py +++ b/API/support/outils.py @@ -19,6 +19,7 @@ API = Path(__file__).resolve().parents[1] PY = str(API / ".venv" / "bin" / "python") TOOLS = API / "tools" TYPST = TOOLS / "typst" +KNOWLEDGE = API / "knowledge" LECTURE = {"inventaire", "resume", "plages", "jours", "vignettes", "qualite", "ensemble", "graphique", "metriques", "stations"} AVEC_SORTIE = {"graphique", "ensemble", "jours", "metriques", "vignettes", "qualite", "stations"} # ceux qui écrivent des PNG @@ -37,6 +38,18 @@ def plafonner(texte: str, n: int = 40_000) -> str: return texte if len(texte) <= n else texte[:n] + f"\n[… tronqué : {len(texte)} caractères]" +def section(texte: str, titre: str) -> str: + """La section d'un markdown dont le titre contient `titre` (sans la casse), jusqu'au titre suivant de même niveau ou + plus haut ; lève ErreurOutil avec la liste des titres si aucun ne convient.""" + lignes = texte.splitlines() + titres = [(i, len(l) - len(l.lstrip("#"))) for i, l in enumerate(lignes) if l.startswith("#")] + for k, (i, niveau) in enumerate(titres): + if titre.lower() in lignes[i].lstrip("#").strip().lower(): + fin = next((j for j, n in titres[k + 1:] if n <= niveau), len(lignes)) + return "\n".join(lignes[i:fin]).strip() + raise ErreurOutil(f"pas de section « {titre} » ; sections : " + " | ".join(lignes[i].strip() for i, _ in titres)) + + def bloc_image(chemin: Path, cote: int = 1568) -> dict: """Image -> bloc image de l'API, plus grand côté ≤ cote px (au-delà de 1568, l'API la réduirait de toute façon).""" im = Image.open(chemin) @@ -66,6 +79,8 @@ OUTILS_ANALYSTE = [ "l'étendue de ces médianes (de combien elle a varié d'un jour à l'autre), mesures rejetées écartées ; hors : " "plages à écarter, AAAA-MM-JJTHH:MMZ/AAAA-MM-JJTHH:MMZ (les nuits de visibilité réduite). du, au : AAAA-MM-JJ, " "au exclu.", {"station": S, "du": S, "au": S, "hors": LISTE}), + _schema("lire_document", "Lit un document de ton savoir (l'index de ton prompt), entier (section vide) ou une seule " + "section par son titre (ex. une fiche de la carte des étiquettes : « La pluie »).", {"nom": S, "section": S}), _schema("outil_de_lecture", "Lance un outil de lecture (lire-les-donnees.md) : nom parmi " + ", ".join(sorted(LECTURE)) + ". arguments : la ligne de commande après le nom du script, data/ pour le dossier.", {"nom": S, "arguments": LISTE}), @@ -160,6 +175,13 @@ class Boite: if nom == "detecteurs": return self._lancer([PY, str(TOOLS / "journal.py"), str(self._station(e["station"])), "--du", e["du"], "--au", e["au"]]) + if nom == "lire_document": + p = KNOWLEDGE / "analyste" / e["nom"] + if "/" in e["nom"] or not p.is_file(): + raise ErreurOutil(f"document inconnu : {e['nom']} ; documents : " + + ", ".join(sorted(f.name for f in (KNOWLEDGE / "analyste").iterdir()))) + texte = p.read_text() + return plafonner(section(texte, e["section"]) if e["section"].strip() else texte) if nom == "stabilite": return self._lancer([PY, str(TOOLS / "stabilite.py"), str(self._station(e["station"])), "--du", e["du"], "--au", e["au"], *(["--hors", *e["hors"]] if e["hors"] else [])]) diff --git a/API/support/seance.py b/API/support/seance.py index 6057d8f..e2b9104 100644 --- a/API/support/seance.py +++ b/API/support/seance.py @@ -28,14 +28,36 @@ import anthropic # noqa: E402 from langsmith import traceable # noqa: E402 from agent import Agent # noqa: E402 -from outils import OUTILS_ANALYSTE, OUTILS_SUPPORT, Boite, bloc_image # noqa: E402 +from outils import OUTILS_ANALYSTE, OUTILS_SUPPORT, Boite, bloc_image, section # noqa: E402 + + +# Le savoir toujours présent (les cartes) ; le reste se lit à la demande par lire_document (Marc, 2026-11-05 : le strict +# nécessaire aux agents). Un document absent d'ici est entier dans le prompt ; une liste : seulement ces sections. +CARTES = {"analyste": {"familles.md": None, "regles-de-preuve.md": None, + "carte-des-etiquettes.md": ["Sommaire", "2. Les règles de lecture", "3. Faux amis", + "4. Le contexte des stations"]}} def systeme(nom: str) -> str: - """Le prompt de l'agent, puis chaque fichier de knowledge// dans sa balise : stable, donc en cache.""" + """Le prompt de l'agent, puis son savoir dans des balises : les cartes en entier (ou leurs sections), et l'index + de ce qui se lit à la demande. Stable d'une séance à l'autre, donc en cache.""" texte = (API / "prompts" / f"{nom}.md").read_text() + cartes, index = CARTES.get(nom), [] for f in sorted((API / "knowledge" / nom).iterdir()): - texte += f'\n\n\n{f.read_text()}\n' + contenu = f.read_text() + if cartes is None or (f.name in cartes and cartes[f.name] is None): + texte += f'\n\n\n{contenu}\n' + continue + if f.name in cartes: + parties = "\n\n".join(section(contenu, t) for t in cartes[f.name]) + texte += f'\n\n\n{parties}\n' + titres = [l.lstrip("#").strip() for l in contenu.splitlines() if l.startswith("## ")] + index.append(f"- `{f.name}` ({len(contenu) // 1000} k car.) : {next((l[2:] for l in contenu.splitlines() if l.startswith('# ')), f.stem)}" + + (f" ; sections : {' | '.join(titres)}" if titres else "")) + if index: + texte += ("\n\n\nÀ lire à la demande, par lire_document(nom, section) : seulement ce qui sert au cas. " + "Les fiches de la carte des étiquettes se lisent par leur titre (le sommaire ci-dessus).\n" + + "\n".join(index) + "\n") return texte diff --git a/docs/decisions.md b/docs/decisions.md index 0588678..bfb4daa 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -1257,3 +1257,10 @@ Règles du journal : - **Pourquoi** : l'utilisateur (2026-11-05), après la séance Displacement : « si leur lecture est cohérente et une alternative qui va aussi, alors c'est bon ». La règle des 2 instants avait renvoyé une modification qui faisait passer CLARIDEN de 0 à 83 % trouvées pour 20 instants de bordure. - **Options écartées** : un seuil relatif aux instants gagnés (plus compliqué, même effet) ; trancher les contradictions des étiquettes avant les séances (les ambiguïtés restent, même d'expert). - **Conséquence** : `.claude/agents/detectors-*.md`, le skill, `regression.py` et `capteurs.py` ; 11 entrées de `docs/ameliorations-processus.md` traitées. La plage de CLARIDEN finit au 2026-11-01 (au lieu du 02) : son bloc du benchmark change sans les détecteurs. + +## D-136 — 2026-11-05 — Les agents de l'API reçoivent les cartes, et lisent le reste à la demande +- **Statut** : active. Complète D-133. +- **Décision** : le prompt système d'un agent de `API/` ne porte que le strict nécessaire : son prompt et ses **cartes** (pour l'analyste : `familles.md`, les règles de preuve, le sommaire et les sections 2 à 4 de la carte des étiquettes), puis un **index** des autres documents de `API/knowledge//`, une ligne chacun avec ses sections. Le reste se lit à la demande par l'outil `lire_document(nom, section)` : un document entier, ou une seule section par son titre (une fiche de la carte des étiquettes). Le support garde tout son savoir (présentation, rédaction, modèle Typst), dont il se sert à chaque séance. Réglage : `CARTES` dans `API/support/seance.py`. +- **Pourquoi** : l'analyste recevait 214 000 caractères (~55 000 jetons) à chaque appel, la carte des étiquettes surtout, pour 1,50 $ par séance ; il n'en lit qu'une petite partie par cas. Avec les cartes, 39 000 caractères ; un essai a trouvé seul la bonne fiche par le sommaire. « Il ne faut donner que le strict nécessaire aux agents » (l'utilisateur, 2026-11-05). +- **Options écartées** : tout dans le prompt (coût, et un savoir noyé) ; une recherche par mots-clés (le sommaire de la carte suffit à trouver la fiche). +- **Conséquence** : un document lu reste dans l'historique de l'agent pour la séance, payé une fois ; l'index se refait seul quand `knowledge/` change.