Add the exploratory report on a diagnostic agent framework

Record decision D-027: a server-side LLM agent layer next to the
unchanged deterministic rules, aimed at unknown anomalies and rule
edge cases. The agent annotates and never rewrites the day color.
Home-made harness (Messages API + Tool Runner), staged start with a
manual Energy pilot on VERMONT history. D-003 is partly replaced.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
maximeandClaude Opus 5.5 committed 2026-10-12 17:41:42 +02:00
1 parent 8a32f4d418
commit df9ab5cdae
3 files changed
+321 -5

No files matched your search

+292
View File
@@ -0,0 +1,292 @@
# Cadre d'agents de diagnostic : rapport exploratoire
- **Date** : 2026-10-12.
- **Statut** : exploratoire. Rien n'est construit ; ce rapport fixe une direction et une première étape. Décision liée : D-027 (`docs/decisions.md`).
- **Principe de travail** : commencer simple, ne complexifier que si le besoin apparaît. Le corps du rapport décrit le socle ; les règles détaillées proposées pendant le brainstorm sont rangées en annexe A, comme pistes à revoir étape par étape pendant la réalisation.
---
## 1. Objet
Aujourd'hui, le diagnostic (domaine Energy) est fait par des scripts déterministes : `DAILY_BATTERY_STATE` et `DAILY_BATTERY_TREND`, combinées en une couleur par jour. Ils sont justes « dans la majorité des cas » (D-005), mais ils ne voient que ce que leurs règles décrivent.
L'idée explorée : ajouter des **agents** qui utilisent l'intelligence interprétative d'un LLM pour capter une palette plus large de problèmes. Chaque agent a accès aux données qui le concernent, à ses instructions et à sa base de connaissance métier. Exemple : un agent tourne chaque jour, lit les nouvelles données, les interprète, puis notifie le client ou le support selon ses conclusions.
Ce rapport décrit le **cadre** qui accueillera ces agents : l'infrastructure nécessaire et les choix stratégiques.
### Ce que l'agent doit capter que les scripts ne captent pas
Deux missions, retenues par l'utilisateur :
1. **Les anomalies inconnues** : des formes qu'aucune règle ne décrit (dérive lente, palier, comportement inhabituel). L'agent voit que « ça ne ressemble pas à d'habitude ».
2. **Les cas limites des règles** : les jours où une règle est muette (UNKNOWN), probablement fausse, ou endormie par l'accoutumance (point ouvert de `MOVING_AVERAGE_7_DAYS_DROP`).
Hors objectif pour l'instant : croiser les métriques et les domaines, ou expliquer le contexte (météo, saison). L'agent le fera peut-être en passant, mais on ne le jugera pas là-dessus.
### Ce qui change dans le projet
D-003 refusait tout LLM et écartait explicitement l'agent de synthèse prévu par les docs AIMsight. Ce rapport le remplace **en partie** :
- la **couche déterministe ne change pas** : pas de LLM, bibliothèque standard, embarquable, couleur du jour reproductible ;
- une **couche d'agents s'ajoute côté serveur**. Un LLM ne tourne pas sur l'embarqué solaire d'une station.
Les docs AIMsight décrivaient déjà cette organisation : analyseurs déterministes, puis faits, puis couche de raisonnement (§18 de `AIMsight_agentic_support_project_context.md`), et le support comme mécanisme de découverte de nouvelles règles (§21).
---
## 2. Choix retenus
| Question | Choix | Raison |
|---|---|---|
| Rôle de l'agent face aux scripts | Un mélange : il **interprète** les faits des règles, **explore** avec ses outils (de façon traçable) et **propose des règles candidates** | Les scripts restent le socle ; l'agent élargit |
| Qui l'agent notifie | Le **client** et le **support** | Choix de l'utilisateur |
| Données envoyées à une API externe | **Oui** (API Claude d'Anthropic) | Modèle de pointe, sans infrastructure GPU |
| Découpage des agents (par domaine, station, rôle…) | **Ouvert** : trop tôt pour décider | Le cadre ne le fige pas (§4) |
| Taille de la flotte | **Moins de 50 stations** | Le coût du modèle n'est pas limitant (§7) |
| Accès aux données | **Requêtes SQL** sur la base des stations | Pas d'export manuel ; tout l'historique est accessible |
| Hébergement | **Harnais maison** sur un serveur AIMsight (approche A, §3) | Le plus simple et le plus contrôlable à cette échelle |
---
## 3. Architecture d'ensemble
```
Station (embarqué) ──mesures──▶ Base SQL de la plateforme
│ lecture seule
Couche déterministe (inchangée, bibliothèque standard, embarquable)
DAILY_BATTERY_STATE, DAILY_BATTERY_TREND… ──▶ faits + couleur du jour
│
Couche agents (nouveau, serveur AIMsight, Python + API Claude)
runner quotidien ──▶ une session par (agent, station, jour)
outils en lecture ──▶ interprétation ──▶ conclusions structurées
│
Journal des conclusions
├──▶ notifications client / support
└──▶ règles candidates ──▶ revue humaine ──▶ nouveau script
```
Deux règles structurantes :
- **L'agent annote, il ne réécrit pas.** Le verdict déterministe (couleur du jour) n'est jamais modifié par l'agent. Son avis est une notification séparée, marquée « agent », qui peut contredire le verdict (« la couleur est Green, mais… »). Ainsi la couleur reste reproductible et traçable, et l'avis de l'agent forme une couche à part, qu'on peut évaluer.
- **Boucle de découverte.** Quand l'agent signale à répétition une même forme d'anomalie, elle devient une règle candidate. Un humain l'examine, puis la code en script déterministe. À terme, l'agent rend les scripts plus complets.
### Hébergement retenu : un harnais maison (approche A)
Un script Python appelle l'API Messages de Claude avec le *Tool Runner* du SDK `anthropic`, qui gère la boucle de l'agent. Les outils sont nos fonctions Python ; la base SQL n'est jamais exposée à l'extérieur. Une seule dépendance nouvelle (`anthropic`), de l'ordre de quelques centaines de lignes de code.
Les deux autres approches étudiées sont en §8 (options écartées). Si la définition d'un agent reste un dossier déclaratif (§4), elle est **portable vers Managed Agents** : on pourra migrer si l'orchestration maison devient pénible.
---
## 4. Anatomie d'un agent
**Un agent est un dossier déclaratif**, lu par le runner. Le découpage reste ouvert : la station (ou le domaine) qu'un agent couvre est un paramètre d'exécution, pas une structure du cadre. On peut donc essayer plusieurs découpages sans rien reconstruire.
```
agents/ emplacement proposé, à fixer au pilote
_commun.md règles de tous les agents : traçabilité, vocabulaire
(consistent with…), fait ≠ hypothèse, lecture seule,
interdiction d'inventer un seuil de validité
energy/
agent.md en-tête : modèle, périmètre (métriques), outils
autorisés, fichiers de connaissance
corps : mission et méthode de l'agent
```
**Base de connaissance : des pointeurs, pas des copies.** `agent.md` liste les fichiers de `docs/` à charger (notes de domaine, fiches des règles, cas annotés, guide), qui restent la seule source. Pour Energy, cela représente environ 56 Ko, soit 15 à 20 k tokens. Tout tient dans le prompt système, **mis en cache** : les sessions suivantes du même jour le relisent presque gratuitement. Pas de recherche documentaire (RAG) ni de base vectorielle : inutile à cette taille.
**Règles non négociables** : celles du projet (`CLAUDE.md`) s'appliquent aux agents. Chaque conclusion est traçable, avec le vocabulaire `confirmed` / `strongly supported` / `consistent with` / `possible` / `insufficient evidence` / `not observed`. Pas de pseudo-probabilités, lecture seule, aucun seuil inventé.
### Outils
Typés, tous en lecture sauf `notify`. On commence avec trois outils ; les autres s'ajoutent quand le besoin apparaît.
| Outil | Rôle | Quand |
|---|---|---|
| `get_series(station, métrique, début, fin)` | Séries horaires, sur une fenêtre bornée, jamais au-delà du jour J | Étape 1 (CSV), puis SQL à l'étape 2 |
| `run_rule(règle, station, fenêtre)` | Les analyses déterministes existantes et leurs faits | Étape 1 |
| `notify(...)` | **La seule action** : écrire une conclusion dans le journal | Étape 1 (fichier), puis table SQL |
| `code_execution` + appel programmatique de `get_series` | L'agent écrit du Python qui lit les séries **dans un bac à sable** et calcule (statistiques, comparaison au passé). Seul le résultat entre dans son contexte | Si l'agent lit mal les nombres bruts |
| `plot(station, métriques, fenêtre)` | Une image du graphique, que l'agent regarde (Claude lit les graphiques) | Si l'image aide à repérer l'inhabituel |
| `get_station_meta(station)` | Alimentation (solaire ou secteur), installation, configuration | Avec l'accès SQL |
| `get_history(station, jours)` | Les conclusions passées de l'agent et les retours du support | Quand l'agent tourne chaque jour (étape 2) |
Raison de `code_execution` : un LLM lit mal un long tableau de nombres. Mieux vaut lui donner du calcul et une image qu'un tableau de 720 lignes. Le bac à sable tourne chez Anthropic, donc les séries y transitent, ce qui est cohérent avec l'accord pour une API externe. Si cela gêne un jour, on le remplace par un bac à sable local sans changer le reste.
**Volontairement absents** :
- SQL libre : on ne pourrait ni l'auditer ni le borner ;
- Bash et accès web ;
- mémoire libre de l'agent : l'historique des conclusions suffit pour commencer.
---
## 5. Exécution et notification (socle)
- **Une session par (agent, station, jour)**, indépendante des autres. Le premier message est préparé par le code : station, jour J, faits déterministes du jour.
- **Causalité garantie par les outils** : une session du jour J ne lit aucune donnée postérieure à J. On peut donc **rejouer le passé** comme s'il était en direct. C'est la base de l'évaluation.
- **Chaque session se termine par une conclusion**, y compris « rien à signaler », qui compte dans l'évaluation.
- **Chaque preuve citée renvoie à un appel d'outil réel de la session**, ce qui empêche les faits inventés.
Le détail (journal, déduplication, contrôles de `notify`, politique de destinataire, affichage sur le site) est en annexe A, à reprendre étape par étape.
---
## 6. Démarrage par étapes
Chaque étape répond à une question, et sa réponse décide si l'étape suivante est nécessaire.
### Étape 1 : pilote manuel sur l'historique de VERMONT
- **Périmètre** : un agent (Energy), une station (VERMONT), les CSV de `data/`. Pas de SQL, de cron ni de site.
- **Lancement** : à la main, sur un jour ou une plage rejouée, par exemple `python3 agents/run.py energy VERMONT 2026-09-01 2026-10-09`.
- **Outils** : `get_series`, `run_rule`, `notify` (qui écrit dans un fichier journal).
- **Question** : l'agent apporte-t-il quelque chose que les règles n'ont pas, à quel coût, avec combien de fausses alertes ? Par exemple : voit-il venir les coupures du 27/09 plus tôt que la couleur du jour ? Signale-t-il les jours UNKNOWN ou l'accoutumance ?
- **Évaluation** : relecture humaine du journal, jour par jour, face aux cas annotés par l'expert (`docs/energy/domaine/cas-annotes-par-l-expert.md`) et à la couleur du jour. Pas de cadre de test automatique (D-008).
- **Mesures** : coût par session (tokens réels), nombre de conclusions jugées pertinentes, fausses ou déjà connues.
### Étape 2 : branchement réel, support seulement
Requêtes SQL, toutes les stations, cron quotidien, journal en table, notifications **au support seulement**, en rodage. Question posée : quel est le taux de fausses alertes en conditions réelles ?
### Étape 3 : ouverture au client
Une fois le taux de fausses alertes de l'étape 2 jugé acceptable, les notifications client sont ouvertes, avec une politique de destinataire à définir (piste en annexe A).
### Étape 4 : élargissement
Selon les besoins : autres domaines (acquisition, transport, déplacements), découpage des agents, boucle des règles candidates, et passage à Managed Agents si l'orchestration maison devient pénible.
---
## 7. Coût, risques, prérequis
### Coût (hypothèse, à mesurer à l'étape 1)
Prix d'Opus 5.5 (`claude-opus-5-5`, modèle par défaut) : 4 $ par million de tokens en entrée, 20 $ en sortie, 0,20 $ en lecture de cache.
Hypothèse par session : 20 k tokens de prompt système en cache, environ 5 tours, ~100 k tokens d'entrée cumulés dont ~80 % lus en cache, ~10 k tokens de sortie (raisonnement compris).
| Poste | Calcul | Coût |
|---|---|---|
| Entrée non cachée | 20 k × 4 $/M | 0,08 $ |
| Lecture de cache | 80 k × 0,20 $/M | 0,02 $ |
| Sortie | 10 k × 20 $/M | 0,20 $ |
| **Par session** | | **~0,30 $ (fourchette 0,1 à 0,5 $)** |
- Rejouer six mois de VERMONT (~180 sessions) : **~55 $** (20 à 90 $).
- En régime établi, 50 stations × 30 jours = 1500 sessions : **~450 $ par mois et par agent** (150 à 750 $).
Sonnet 5.5 (`claude-sonnet-5-5`, 2 $ et 10 $ par million) coûte deux fois moins cher. Il peut être comparé sur le même rejeu : c'est une décision à prendre sur mesure, pas a priori.
### Risques
| Risque | Parade |
|---|---|
| Faits inventés par l'agent | Chaque preuve renvoie à un appel d'outil ; relecture humaine à l'étape 1 |
| Lassitude face aux fausses alertes | Le support reçoit seul les notifications tant que le taux n'est pas mesuré (étape 2) |
| Dérive du coût | Budget de tokens par session ; coût mesuré à chaque étape |
| Changement de modèle | Identifiant du modèle fixé ; rejeu de VERMONT avant tout changement |
| Données envoyées chez Anthropic | Accepté ; conditions de conservation des données à vérifier avec la direction |
### Prérequis
- **Étape 1** : un compte et une clé API Anthropic.
- **Étape 2** : un accès SQL en lecture seule à la base des stations, et un serveur pour héberger le runner et le cron.
---
## 8. Options écartées
| Option | Raison |
|---|---|
| **B. Managed Agents** (Anthropic héberge la boucle, la planification par *scheduled deployments* et la mémoire par *memory stores*) | Service en bêta. La base SQL devrait être joignable depuis Anthropic (l'exposer via une API, ou faire tourner un *worker* auto-hébergé). **Reste la cible si l'orchestration maison devient pénible** : la définition en dossier est portable. |
| **C. Claude Agent SDK** (harnais de Claude Code sur notre serveur) | C'est un harnais de codage. Avec Bash, la surface d'action est large et difficile à auditer, ce qui convient mal à un agent qui notifie des clients. |
| Modèle open-weights hébergé chez AIMsight | Inutile : l'API externe est acceptée. Il serait moins capable et demanderait un serveur GPU. |
| LLM sur la station | Trop lourd pour un système embarqué solaire. |
| L'agent corrige lui-même la couleur du jour | On perdrait la reproductibilité et la traçabilité du verdict déterministe. |
| Agent « explorateur libre » seul (sans les faits des règles) | Moins traçable et moins reproductible, avec un risque de seuils inventés. L'exploration reste permise, mais encadrée et à côté des faits. |
| SQL libre, Bash, accès web pour l'agent | Non auditable, non borné, inutile pour la mission. |
| RAG / base vectorielle pour la connaissance | Inutile : la connaissance d'un domaine tient dans le prompt (~20 k tokens). |
---
## 9. Questions ouvertes
1. **Découpage des agents** : par domaine, par station, par rôle ? À décider quand un deuxième agent sera envisagé (étape 4).
2. **Politique de destinataire précise** : qui reçoit quoi, à partir de quel niveau de certitude ? À définir sur mesure, avant l'étape 3.
3. **Affichage côté site** : où et comment les notifications de l'agent apparaissent (maquettes `maquettes/user/` et `maquettes/support/`). À voir avec l'équipe du site.
4. **Choix du modèle** : Opus 5.5 par défaut ; comparaison éventuelle avec Sonnet 5.5 sur le rejeu de VERMONT.
5. **Relecture** : qui relit les conclusions de l'agent pendant le pilote et le rodage (l'expert, le support) ?
6. **Conditions de conservation des données** chez Anthropic : à valider avec la direction.
7. **Emplacement du code d'agent** dans le dépôt (proposé : `agents/` à la racine, séparé de `src/<domaine>/`, qui reste sans LLM).
---
## Annexe A : pistes détaillées, à revoir étape par étape
Règles proposées pendant le brainstorm. L'utilisateur en approuve l'idée générale, mais pas chaque détail : elles sont à reprendre au moment de construire l'étape concernée, et à n'adopter que si le besoin apparaît.
### A.1 Exécution
- Cron vers 01:00 UTC, après la clôture du jour UTC (la couleur du jour se fige à minuit UTC).
- Sessions en parallèle ; l'échec de l'une ne bloque pas les autres.
- Le premier message contient aussi les conclusions encore ouvertes pour la station.
- Budget de tokens par session (*task budget* de l'API).
- Si l'API échoue : une ligne « agent non exécuté » dans le journal, pour qu'un silence ne passe jamais pour un « rien à signaler ».
- Effort du modèle fixé explicitement (le défaut d'Opus 5.5 est `medium`) ; gérer l'arrêt `refusal` de l'API.
- Programmatic tool calling : incompatible avec `strict: true` sur l'outil appelé depuis le bac à sable.
### A.2 Journal des conclusions (table SQL)
Champs envisagés :
- agent, version (hash git du dossier de l'agent), modèle, station, jour ;
- type : `anomalie inconnue`, `cas limite de règle` ou `rien` ;
- niveau de certitude (vocabulaire du projet) ;
- preuves : chacune renvoie à un appel d'outil (identifiant, entrées, extrait du résultat) ;
- ce qui reste non établi ; règle candidate éventuelle (description) ;
- verdict déterministe du jour (couleur), pour comparer ;
- statut : ouverte, en cours, résolue ;
- transcription complète de la session (audit) ;
- retour du support : pertinent, faux positif, déjà connu.
Déduplication : une anomalie qui dure met à jour sa conclusion ouverte au lieu de notifier chaque jour. L'agent voit les conclusions ouvertes (via `get_history`) et dit si c'est nouveau, une suite, ou résolu.
### A.3 Contrôles de `notify` (par le code, pas par le modèle)
Le runner refuse l'appel et renvoie l'erreur à l'agent pour qu'il corrige, dans quatre cas :
- une preuve ne correspond à aucun appel d'outil réel de la session ;
- le niveau de certitude est hors vocabulaire ;
- le destinataire n'est pas permis par la politique ;
- le message destiné au client contient du jargon : côté client, pas de tension brute ni de mécanisme (cf. maquettes client).
### A.4 Politique de destinataire (proposition)
- **Support** : tout, avec le détail technique, y compris le niveau `possible`.
- **Client** : seulement une anomalie inconnue de niveau `strongly supported` au moins, avec un message simple.
- **Cas limites de règle** : au support seulement. Si l'agent écrivait au client « la couleur est verte, mais… », le client recevrait deux messages contradictoires. Le support tranche, puis écrit au client ou corrige la règle.
### A.5 Affichage sur le site
- Client : une carte « Agent » dans la section Diagnostic de la page System Summary, distincte de la couleur Energy (`maquettes/user/`).
- Support : une entrée dans la section Status de la page Home (`maquettes/support/`).
### A.6 Mise en service
- Rodage : pendant les premières semaines de l'étape 3, les notifications destinées au client sont écrites dans le journal (« aurait été envoyé ») et vues par le support seul, avant l'ouverture réelle.
---
## Annexe B : références
- `docs/aimsight/AIMsight_agentic_support_project_context.md` :
- §10 : règles épistémiques ;
- §14-15 : format de réponse ;
- §18 : architecture (analyseurs, faits, raisonnement) ;
- §21 : boucle de découverte des règles ;
- §27 : anti-patterns, dont « laisser le LLM inventer des seuils de validité ».
- `docs/decisions.md` : D-003 (pas de LLM, remplacée en partie), D-005 (analyses imparfaites combinées), D-008 (pas de tests automatisés), D-020 (couleur du jour), D-027 (cette direction).
- API Claude (fonctionnalités citées) :
- Messages API et *Tool Runner* (SDK `anthropic`) ;
- *programmatic tool calling* avec `code_execution` ;
- *prompt caching* et *task budgets* ;
- Managed Agents : *scheduled deployments*, *memory stores*.