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:
1 parent
8a32f4d418
commit
df9ab5cdae
3 files changed
+321
-5
No files matched your search
@@ -6,7 +6,7 @@ Ce fichier est une **carte**, chargée à chaque session : il doit rester court
|
||||
|
||||
## Projet
|
||||
|
||||
Agent de diagnostic proactif pour **AIMsight**, un système de surveillance optique de déplacements : une caméra suit des cibles (prismes, réflecteurs) sur un ouvrage, et le mouvement de la caméra est compensé grâce à des cibles de référence. L'agent analyse les séries temporelles avec des **méthodes analytiques (pas de LLM)**, détecte les anomalies et explique chacune d'elles (preuves calculées + ce qui reste non établi) **avant** que le client ne pose la question. Cible d'exécution idéale : **le système embarqué de la station**. Langage : **Python**.
|
||||
Agent de diagnostic proactif pour **AIMsight**, un système de surveillance optique de déplacements : une caméra suit des cibles (prismes, réflecteurs) sur un ouvrage, et le mouvement de la caméra est compensé grâce à des cibles de référence. L'agent analyse les séries temporelles avec des **méthodes analytiques (pas de LLM)**, complétées à l'étude par une couche d'agents LLM côté serveur (D-027), détecte les anomalies et explique chacune d'elles (preuves calculées + ce qui reste non établi) **avant** que le client ne pose la question. Cible d'exécution idéale : **le système embarqué de la station**. Langage : **Python**.
|
||||
|
||||
## État et prochaine étape
|
||||
|
||||
@@ -22,7 +22,8 @@ Agent de diagnostic proactif pour **AIMsight**, un système de surveillance opti
|
||||
- **2026-10-12 (D-024)** : focus sur un jour, J et la veille seulement : `src/energy/focus_jour.py` (résumé des faits + graphique de 48 h), sélection des données dans `day_color.focus()`.
|
||||
- **2026-10-12 (D-025)** : maquette support « Home » en place : page d'accueil (toutes les stations) avec une section Status, une notification par station Orange ou Red, et un lien vers la vue client.
|
||||
- **2026-10-12 (D-026)** : projet rangé par domaine (`src/energy/`, `docs/energy/`, code commun dans `src/common/`, documentation AIMsight dans `docs/aimsight/`). Les analyses ne sont plus numérotées : chacune est désignée par sa règle. Deux scripts Energy : `daily.py` (analyses livrées) et `all_analyses.py` (comparaison).
|
||||
- **Prochaine étape** : mise en forme du manuel avec le plugin Interactive Docs (dans une autre conversation) ; choisir avec l'équipe du site le format d'intégration du graphique ; maquettes : poursuivre « Energy » côté client pas à pas, puis le côté support pas à pas (points ouverts dans D-022).
|
||||
- **2026-10-12 (D-027)** : piste exploratoire d'une couche d'agents LLM côté serveur, en complément des règles (anomalies inconnues, cas limites des règles) : `docs/agents/rapport-exploratoire.md`. Rien n'est construit.
|
||||
- **Prochaine étape** : étape 1 du rapport d'agents (pilote manuel Energy sur l'historique de VERMONT, il faut une clé API Anthropic) ; mise en forme du manuel avec le plugin Interactive Docs (dans une autre conversation) ; choisir avec l'équipe du site le format d'intégration du graphique ; maquettes : poursuivre « Energy » côté client pas à pas, puis le côté support pas à pas (points ouverts dans D-022).
|
||||
|
||||
## Analyses (domaine Energy)
|
||||
|
||||
@@ -55,6 +56,7 @@ Pour créer une analyse : skill `nouvelle-analyse` (`.claude/skills/nouvelle-ana
|
||||
- `comment-se-comporte-la-batterie.md` : LiFePO4, plateau et coude, table OCV, redémarrage à 12,6 V, capacité.
|
||||
- `tensions-selon-l-etat-de-la-batterie.md` : tensions et pentes en charge, pleine charge et décharge (VERMONT, collecteur, chimie).
|
||||
- `cas-annotes-par-l-expert.md` : diagnostics experts des 5 stations.
|
||||
- `docs/agents/rapport-exploratoire.md` : cadre d'agents de diagnostic LLM (D-027). Choix retenus, architecture, démarrage par étapes ; annexe A : pistes détaillées à revoir étape par étape.
|
||||
- `docs/energy/guide/diagnostic-energetique.md` : manuel du diagnostic énergétique, pour le client (partie 1) et le support (partie 2). À tenir à jour avec la matrice (`docs/energy/matrice-etat-tendance.drawio`) et les fiches `DAILY_BATTERY_STATE` et `DAILY_BATTERY_TREND`.
|
||||
- **Règle de travail** :
|
||||
- une décision projet prise en conversation donne une entrée dans `docs/decisions.md` ;
|
||||
@@ -70,7 +72,7 @@ Pour créer une analyse : skill `nouvelle-analyse` (`.claude/skills/nouvelle-ana
|
||||
- `docs/aimsight/` : documentation AIMsight d'origine, à lire avant de concevoir. Ne pas re-demander à l'utilisateur ce qui y figure. Contenus non modifiés.
|
||||
- `AIMsight_reference_quality_event_explainer_roadmap.md` : **référence qui fait autorité**. Elle couvre la couche diagnostique commune, l'explainer d'événements, les classifications (§4.3) et l'API indépendante de l'estimateur (§10).
|
||||
- `AIMsight_agentic_support_project_context.md` : extension support. Contenu : chaîne de dépendance (§4), domaines dont la santé système (§5.1), règles épistémiques (§10), familles d'hypothèses (§12), format de sortie (§14-15), cas de régression (§16-17), cas d'usage (§23).
|
||||
- Les deux docs prévoient un LLM/agent pour la synthèse : **ne pas suivre ce point**, le projet est 100 % analytique.
|
||||
- Les deux docs prévoient un LLM/agent pour la synthèse : la couche déterministe reste 100 % analytique ; la couche d'agents côté serveur (D-027) reprend cette idée, en exploration.
|
||||
- `AIMsight FAQ.pdf` et `AIMsight Test Manual.pdf` (ce dernier est en réalité le manuel de la station) : définitions des signaux et des colonnes CSV, alimentation, schedules. Pour les lire : `pdftotext -layout "docs/aimsight/<fichier>.pdf" -`.
|
||||
- `collecteur_system_info.py` : copie de référence du collecteur `system_info` embarqué (INA219, table OCV LiFePO4, compensation IR 0,34 Ω). Source des unités. Ne pas modifier.
|
||||
- `data/` : **jeu de travail = VERMONT seule**, le seul dataset complet (les 7 métriques système, telles qu'extraites de la plateforme) + diagnostics experts (`metadata.md`, `d.md`). Les analyses tournent uniquement sur ce jeu.
|
||||
@@ -85,7 +87,7 @@ Pour créer une analyse : skill `nouvelle-analyse` (`.claude/skills/nouvelle-ana
|
||||
|
||||
- **Point d'entrée du POC : scan proactif d'un export.** L'agent détecte les événements, les classe et explique chacun. Le mode « question de support » viendra ensuite, sur le même socle.
|
||||
- **Premier cas d'usage : santé énergétique des stations.** Ici, le trou de données *est* l'anomalie. L'interprétation des déplacements viendra ensuite.
|
||||
- **Pas de LLM, pas de données synthétiques** (ni CSV simulés, ni générateur de scénarios : refus explicite de l'utilisateur). Le code d'analyse est **embarquable** : bibliothèque standard, calcul léger.
|
||||
- **Pas de LLM dans la couche déterministe (agents LLM côté serveur en exploration, D-027), pas de données synthétiques** (ni CSV simulés, ni générateur de scénarios : refus explicite de l'utilisateur). Le code d'analyse est **embarquable** : bibliothèque standard, calcul léger.
|
||||
- **Anomalie énergétique = régime non soutenable** (l'apport ne couvre pas la consommation), pas une batterie basse. Une station débranchée avec une batterie pleine est déjà en anomalie.
|
||||
- **Analyses combinées** : chaque analyse est une preuve imparfaite, juste « dans la majorité des cas » ; la combinaison fait le diagnostic. Préférer des fenêtres larges (plusieurs jours, multiples de 24 h).
|
||||
- Contrat commun : `run(series) -> {analysis, rule, points: [{t, value, anomaly, facts}]}`. Calcul causal (le point t n'utilise que les données ≤ t). `anomaly = None` signifie UNKNOWN (exception : `DAILY_BATTERY_STATE` en phase C et `DAILY_BATTERY_TREND`, où `None` = pas de verdict ; l'UNKNOWN est dans `facts.state` ou `facts.trend`).
|
||||
|
||||
@@ -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*.
|
||||
+23
-1
@@ -23,7 +23,7 @@ Règles du journal :
|
||||
- **Options écartées** : commencer par l'interprétation des déplacements ; elle viendra ensuite.
|
||||
|
||||
## D-003 — 2026-10-09 — 100 % analytique, embarquable, données réelles
|
||||
- **Statut** : active.
|
||||
- **Statut** : active, remplacée en partie par D-027 (le refus du LLM ne vaut plus que pour la couche déterministe).
|
||||
- **Décision** : pas de LLM ; pas de données synthétiques ; code d'analyse en bibliothèque standard Python.
|
||||
- **Pourquoi** : la cible est le système embarqué de la station, souvent sur batterie et panneau solaire. Chaque conclusion doit être traçable jusqu'aux faits calculés.
|
||||
- **Options écartées** :
|
||||
@@ -272,3 +272,25 @@ Règles du journal :
|
||||
- **Conséquence** :
|
||||
- les anciens chemins restent dans `docs/superpowers/` et dans le texte des entrées antérieures du journal (historique non réécrit) ;
|
||||
- le code de calcul s'embarque en copiant `src/energy/` sans `daily.py`, `all_analyses.py` ni `focus_jour.py`, qui demandent plotly.
|
||||
|
||||
## D-027 — 2026-10-12 — Couche d'agents de diagnostic côté serveur (exploratoire)
|
||||
- **Statut** : active, exploratoire (rapport `docs/agents/rapport-exploratoire.md`, rien n'est construit). Remplace en partie D-003 : le refus du LLM ne vaut plus que pour la couche déterministe.
|
||||
- **Décision** :
|
||||
- à côté de la couche déterministe (inchangée : sans LLM, bibliothèque standard, embarquable), une **couche d'agents LLM** (Claude, via l'API d'Anthropic) tourne **côté serveur**. Elle lit les faits des règles et les données, avec deux missions : les **anomalies inconnues** (qu'aucune règle ne décrit) et les **cas limites des règles** (UNKNOWN, accoutumance, faux positifs) ;
|
||||
- **l'agent annote, il ne réécrit pas** : il ne modifie jamais le verdict déterministe (couleur du jour). Son avis est une notification séparée, marquée « agent » ;
|
||||
- il notifie le **client** et le **support** ;
|
||||
- **harnais maison** : script Python, API Messages et *Tool Runner* du SDK `anthropic`, outils typés en lecture seule (sauf `notify`), base SQL jamais exposée. Un agent est un **dossier déclaratif** (instructions, pointeurs vers la connaissance de `docs/`, outils). Le **découpage des agents reste ouvert** ;
|
||||
- **démarrage simple, par étapes** : (1) pilote manuel Energy sur l'historique de VERMONT (CSV), (2) SQL, cron et notifications au support seul, (3) ouverture au client, (4) élargissement. Chaque étape décide si la suivante est nécessaire.
|
||||
- **Pourquoi** : demande de l'utilisateur. Les scripts sont justes « dans la majorité des cas » (D-005) ; l'interprétation d'un agent doit élargir la palette des problèmes captés. Les docs AIMsight prévoyaient cette couche (§18 et §21 du contexte support). L'utilisateur accepte d'envoyer les données à une API externe. Avec moins de 50 stations, le coût reste modéré (~0,30 $ par session, à mesurer). Les données sont accessibles par requêtes SQL.
|
||||
- **Options écartées** :
|
||||
- Managed Agents (Anthropic héberge la boucle, la planification et la mémoire) : service en bêta, et la base SQL serait à exposer ou à servir par un *worker* auto-hébergé. Reste la cible si l'orchestration maison devient pénible, car la définition en dossier est portable ;
|
||||
- Claude Agent SDK : un harnais de codage, dont le Bash donne une surface d'action large et peu auditable pour un agent qui notifie des clients ;
|
||||
- un modèle open-weights hébergé chez AIMsight : inutile, l'API externe étant acceptée ;
|
||||
- un LLM sur la station : trop lourd pour l'embarqué ;
|
||||
- un agent qui corrige lui-même la couleur du jour : on perdrait la reproductibilité du verdict ;
|
||||
- SQL libre, Bash, accès web, RAG : non auditables ou inutiles à cette taille.
|
||||
- **Conséquence** :
|
||||
- pas de LLM dans `src/<domaine>/` : le code d'agent vivra à part (emplacement proposé : `agents/`) ;
|
||||
- les règles non négociables (traçabilité, vocabulaire, lecture seule, pas de seuil inventé) s'appliquent aux agents ;
|
||||
- les règles détaillées proposées (journal, contrôles de `notify`, politique de destinataire, affichage) sont des **pistes à revoir étape par étape**, pas des décisions (annexe A du rapport) ;
|
||||
- prérequis de l'étape 1 : un compte et une clé API Anthropic.
|
||||
Reference in new issue
Block a user