Compare commits

..
3 Commits
Author SHA1 Message Date
maximeandClaude Opus 5.5 ef8ad70285 Turn CLAUDE.md into a full map of the repository
D-028: CLAUDE.md names every folder and document with its size in
lines, says how to read without filling the context (outline of a long
file then one section, index of the decision log, CSV by script,
folders not to read), and gives the current state instead of a dated
history. It and D-026 now name final.py for the delivered script.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 08:58:43 +02:00
maximeandClaude Opus 5.5 7f911e41a3 Rename the delivered Energy script daily.py to final.py
src/energy/final.py is daily.py unchanged; the comparison script, the
day focus and the client mockup now import energy.final. References in
the README, the analysis rule, the nouvelle-analyse skill, the two
delivered analysis sheets and the guide follow. Output files keep
their names (out/<STATION>_daily.html and .json).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 08:58:43 +02:00
maximeandClaude Opus 5.5 df9ab5cdae 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>
2026-10-12 17:41:42 +02:00
14 changed files with 425 additions and 92 deletions

No files matched your search

+1 -1
View File
@@ -25,5 +25,5 @@ paths:
- mettre à jour la fiche dans le même changement (résultats, limites, historique) ;
- si c'est une décision projet, ajouter une entrée dans `docs/decisions.md` ;
- si c'est un savoir métier nouveau, l'ajouter dans `docs/domaine/` (commun) ou `docs/<domaine>/domaine/`.
- **Vérifier à la main** sur VERMONT (`data/`) : pour Energy, `python3 src/energy/all_analyses.py`, et `python3 src/energy/daily.py` si l'analyse est livrée. Pas de tests automatisés en phase prototype (D-008).
- **Vérifier à la main** sur VERMONT (`data/`) : pour Energy, `python3 src/energy/all_analyses.py`, et `python3 src/energy/final.py` si l'analyse est livrée. Pas de tests automatisés en phase prototype (D-008).
- **Nouvelle analyse** : utiliser le skill `nouvelle-analyse`.
+1 -1
View File
@@ -32,7 +32,7 @@ description: Créer une nouvelle analyse dans le projet de diagnostic AIMsight
- `value` est exprimé dans une unité physique, sans pseudo-probabilité.
- Une analyse seule conclut au plus `consistent with`.
- Le module va dans `src/<domaine>/`. Les séries arrivent par `common.stations.load_stations`. Extraire du code partagé seulement quand une deuxième analyse en a vraiment besoin.
- **Pas de point d'entrée par analyse** : ajouter le panneau de l'analyse à la page de comparaison du domaine (pour Energy, `figure()` et `main()` de `src/energy/all_analyses.py`). Si l'analyse devient livrée, elle rejoint aussi la page livrée (pour Energy, `src/energy/daily.py`).
- **Pas de point d'entrée par analyse** : ajouter le panneau de l'analyse à la page de comparaison du domaine (pour Energy, `figure()` et `main()` de `src/energy/all_analyses.py`). Si l'analyse devient livrée, elle rejoint aussi la page livrée (pour Energy, `src/energy/final.py`).
- Graphique (D-011) : en haut, l'analyse avec ses courbes superposées ; dessous, un graphique par série temporelle. Écrire le HTML avec `post_script=common.page.AUTOSCALE_Y_JS` et des ordonnées en `fixedrange`, pour que l'ordonnée se recale à chaque zoom.
- Pas de tests automatisés en phase prototype (D-008).
@@ -1,7 +1,7 @@
# `NOM_DE_LA_REGLE` : titre court
- **Statut** : idée | en conception | prototype en place | livrée | comparaison seulement | abandonnée (date).
- **Script** : la page qui montre l'analyse. Pour Energy : son panneau dans `python3 src/energy/all_analyses.py [CSV ou dossiers]` (défaut : `data/`), et dans `python3 src/energy/daily.py` si elle est livrée. La page est écrite dans `out/` et ouverte dans le navigateur.
- **Script** : la page qui montre l'analyse. Pour Energy : son panneau dans `python3 src/energy/all_analyses.py [CSV ou dossiers]` (défaut : `data/`), et dans `python3 src/energy/final.py` si elle est livrée. La page est écrite dans `out/` et ouverte dans le navigateur.
- **Code** : les modules utilisés, dans `src/<domaine>/` ; le calcul est en bibliothèque standard uniquement.
## Question posée
+84 -75
View File
@@ -1,97 +1,110 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Ce fichier est une **carte**, chargée à chaque session : il doit rester court (< 200 lignes). Le détail est dans `docs/` et se lit quand on en a besoin.
Ce fichier est une **carte** du projet, chargée à chaque session : il dit ce qui existe et où, pas le détail. Il reste court (< 200 lignes, D-012). Le reste se lit à la demande, et seulement la partie utile (voir « Lire sans saturer le contexte »).
## 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
## État et prochaine étape (au 2026-10-12)
- **2026-10-09** : `MOVING_AVERAGE_7_DAYS_DROP` est en place sur VERMONT et produit un graphique HTML. C'est un prototype expérimental, sans tests automatisés.
- **Point ouvert de `MOVING_AVERAGE_7_DAYS_DROP`** : l'accoutumance. Après plus de 30 jours de déficit, l'anomalie peut disparaître (voir sa fiche).
- **2026-10-12** : `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP` (suggestion d'un collègue) en place, en panneau sous la précédente pour comparer. Elle est bien moins bruitée (pire cas sain −0,04 V contre −0,16 V), mais plus tardive sur VERMONT : 1 h avant la première coupure, contre ~2,7 jours.
- **2026-10-12, changement d'échelle (D-018)** : les analyses suivantes donnent l'état de la batterie jour par jour, avec des seuils physiques du matériel, pour être utilisables dès l'installation. Phase C (état seul), puis phase B (niveaux gradués).
- **2026-10-12** : `DAILY_BATTERY_STATE` en place (phase C, état seul).
- **2026-10-12** : `DAILY_BATTERY_TREND` en place (tendance markovienne : chaque jour face à la veille, mieux / stable / pire).
- **2026-10-12, recentrage (D-020)** : le diagnostic énergétique livré ne retient que `DAILY_BATTERY_STATE` et `DAILY_BATTERY_TREND`, combinées par la matrice état × tendance de `docs/energy/matrice-etat-tendance.drawio` en une couleur par jour (vert / orange / rouge). Le manuel `docs/energy/guide/diagnostic-energetique.md` (brouillon) l'explique au client et au support.
- **2026-10-12 (D-021)** : graphique pour le site de monitoring (Plotly) : une seule figure, l'état en haut et la tendance dessous, écrite en page de démo et en JSON. La matrice est codée (`src/energy/day_color.py`, jours inconnus en gris), mais pas tracée (la bande de couleurs a été écartée).
- **2026-10-12 (D-022, D-023)** : maquettes du site en HTML sur données réelles (`maquettes/user/` pour le client, `maquettes/support/` pour le support ; Figma seulement sur demande). Maquette client « Energy » en place : section Diagnostic de la page System Summary. Tout ce qui va au site est en anglais, figure état × tendance comprise.
- **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).
L'état courant seulement ; l'historique est dans `git log` et `docs/decisions.md`.
- **Energy, livré (prototype, D-020)** : `DAILY_BATTERY_STATE` et `DAILY_BATTERY_TREND`, combinées par la matrice état × tendance en une couleur par jour (vert / orange / rouge, gris si inconnu). Une figure Plotly pour le site (D-021 ; la matrice est codée mais pas tracée), un focus sur un jour et sa veille (D-024), un manuel en brouillon.
- **Energy, comparaison seulement** : les deux moyennes glissantes sur 7 jours. Point ouvert : l'accoutumance après ~30 jours de déficit (fiche `moving_average_7_days_drop`).
- **Maquettes du site (D-022)** : client « Energy » (section Diagnostic de la page System Summary) ; support « Home » (section Status, une notification par station Orange ou Red, lien vers la vue client, D-025).
- **Agents LLM côté serveur (D-027)** : rapport exploratoire seulement, 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)
| Règle | Question | Statut | Fiche |
|---|---|---|---|
| `DAILY_BATTERY_STATE` | Chaque jour : pleine charge, charge partielle (incertain), sous le plateau ou aucune charge ? | livrée (prototype, D-020) | `docs/energy/analyses/daily_battery_state.md` |
| `DAILY_BATTERY_TREND` | Chaque jour, face à la veille : mieux, stable ou pire (changement d'état, sinon écart de fin de nuit) ? | livrée (prototype, D-020) | `docs/energy/analyses/daily_battery_trend.md` |
| `MOVING_AVERAGE_7_DAYS_DROP` | La tension moyenne sur 7 jours décroche-t-elle de son propre passé récent (> 0,2 V) ? | comparaison seulement | `docs/energy/analyses/moving_average_7_days_drop.md` |
| `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP` | Même question, sur la seule mesure de 00:00 UTC de chaque jour | comparaison seulement | `docs/energy/analyses/moving_average_7_days_midnight_utc_drop.md` |
Code dans `src/energy/`, fiche dans `docs/energy/analyses/<règle en minuscules>.md`.
Pour créer une analyse : skill `nouvelle-analyse` (`.claude/skills/nouvelle-analyse/`).
| Règle | Question | Statut | Code |
|---|---|---|---|
| `DAILY_BATTERY_STATE` | Chaque jour : pleine charge, charge partielle (incertain), sous le plateau ou aucune charge ? | livrée (prototype, D-020) | `battery_state.py` |
| `DAILY_BATTERY_TREND` | Chaque jour, face à la veille : mieux, stable ou pire (changement d'état, sinon écart de fin de nuit) ? | livrée (prototype, D-020) | `battery_trend.py` |
| `MOVING_AVERAGE_7_DAYS_DROP` | La tension moyenne sur 7 jours décroche-t-elle de son propre passé récent (> 0,2 V) ? | comparaison : ~2,7 jours d'avance sur la première coupure de VERMONT, mais bruitée (pire cas sain −0,16 V) | `moving_average.py` |
| `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP` | Même question, sur la seule mesure de 00:00 UTC de chaque jour | comparaison : peu bruitée (−0,04 V), mais 1 h d'avance seulement | `moving_average.py` |
- **Couleur du jour** : `src/energy/day_color.py` (`MATRIX`, `focus()` pour J−1 / J), transcription de `docs/energy/matrice-etat-tendance.drawio`.
- **Travailler sur une analyse** : `.claude/rules/analyses.md` (contrat `run(series)`, calcul causal, constantes sourcées, graphiques, fiche à jour) se charge seul dès qu'on touche `src/` ou `docs/*/analyses/`.
- **Créer une analyse** : skill `nouvelle-analyse`.
## Commandes
- `python3 src/energy/daily.py [données]` : analyses livrées (`DAILY_BATTERY_STATE`, `DAILY_BATTERY_TREND`). Il écrit `out/<STATION>_daily.html` + `.json` (figure pour le site, D-021) et les ouvre dans le navigateur (via `explorer.exe` sous WSL). Défaut : `data/`. Il bascule seul sur `.venv` si plotly manque, comme tous les scripts plotly.
- `python3 src/energy/all_analyses.py [données]` : les quatre analyses ensemble pour comparer (D-016), un panneau chacune, puis un graphique par série. Il écrit `out/<STATION>_energy.html` et l'ouvre.
- `python3 src/energy/focus_jour.py 27.09` : focus sur un jour et sa veille (D-024). Il affiche les faits de la couleur et écrit `out/<STATION>_focus_<AAAA-MM-JJ>.html` + `.json`, puis l'ouvre.
- `python3 maquettes/user/energy.py [début] [fin]` : maquette client « Energy » (page System Summary, section Diagnostic, D-022), écrite dans `out/maquette_user_energy.html` et ouverte.
- `python3 maquettes/support/home.py [début] [fin]` : maquette support « Home » (toutes les stations, section Status, D-025), écrite dans `out/maquette_support_home.html` et ouverte.
```bash
python3 src/energy/final.py [données] # livré : out/<STATION>_daily.html + .json (figure du site, D-021)
python3 src/energy/all_analyses.py [données] # les 4 analyses comparées (D-016) : out/<STATION>_energy.html
python3 src/energy/focus_jour.py JJ.MM[.AAAA] [données] # un jour et sa veille (D-024) : faits + out/<STATION>_focus_<AAAA-MM-JJ>.html + .json
python3 maquettes/user/energy.py [début] [fin] # maquette client : out/maquette_user_energy.html
python3 maquettes/support/home.py [début] [fin] # maquette support : out/maquette_support_home.html
pdftotext -layout "docs/aimsight/<fichier>.pdf" - # lire un PDF AIMsight
python3 -m venv .venv && .venv/bin/pip install plotly # recréer .venv
```
## Documentation (à lire à la demande)
- `[données]` : CSV ou dossiers, défaut `data/`. Dates des maquettes en `AAAA-MM-JJ`, défaut 2026-09-18 à 2026-09-28 ; la maquette support mène à la maquette client : les lancer avec les mêmes dates.
- Chaque script bascule seul sur `.venv` si plotly manque, puis ouvre sa page (navigateur Windows via `explorer.exe` sous WSL).
- **Vérifier un changement** : pas de tests automatisés (D-008). Lancer `all_analyses.py`, et `final.py` pour le livré, sur VERMONT.
- `docs/decisions.md` : journal des décisions **projet**, au format ADR allégé (statut, décision, pourquoi, options écartées, conséquence). Le lire avant de changer d'orientation ou de reproposer une option : elle a peut-être déjà été écartée.
- `docs/<domaine>/analyses/<règle>.md` : fiche vivante de chaque analyse (principe, constantes et sources, résultats, limites, options écartées, historique). Modèle : `.claude/skills/nouvelle-analyse/modele-fiche.md`.
- `docs/domaine/` : le savoir métier commun, une note par question.
## Carte du dépôt
### Lire sans saturer le contexte
- Fichier long (tailles en lignes ci-dessous) : lire son plan (`grep -n '^#' <fichier>`), puis la seule section utile (Read avec `offset` et `limit`).
- `docs/decisions.md` : l'index est `grep -n '^## D-' docs/decisions.md` ; lire ensuite l'entrée citée seulement. Son **Statut** dit si elle est remplacée.
- CSV de `data/` : les explorer par script (`common.stations.load_stations`), jamais en les affichant.
- Ne pas lire : `docs/superpowers/` (historique), `out/` (sorties générées), `.venv/`.
### Fichiers
- `README.md` (40 l) : point d'entrée pour un humain.
- `docs/decisions.md` (300 l, D-001 à D-027) : décisions **projet**, au format ADR allégé (statut, décision, pourquoi, options écartées, conséquence). À consulter avant de changer d'orientation ou de reproposer une option : elle a peut-être déjà été écartée.
- `docs/domaine/` : savoir métier commun, une note courte (< 50 l) par question.
- `ce-que-mesure-la-station.md` : format CSV, métriques et unités, consommation mesurée mais pas l'apport.
- `pieges-des-donnees.md` : trou ≠ coupure, signatures d'une coupure, seuils absolus, cycle jour/nuit.
- `colonnes-des-deplacements.md` : colonnes des déplacements (cas d'usage suivant).
- `docs/energy/domaine/` : le savoir métier Energy.
- `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/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` ;
- toute modification d'une analyse met à jour sa fiche dans le même changement ;
- un savoir métier nouveau va dans `docs/domaine/` (commun) ou `docs/<domaine>/domaine/` ;
- un changement de cap met à jour « État et prochaine étape » ci-dessus.
- `.claude/rules/analyses.md` se charge seul quand Claude touche `src/` ou `docs/*/analyses/`.
- `docs/superpowers/` : documents de travail superpowers (specs, plans). C'est un historique, non maintenu après coup, et ce n'est pas une référence. La spec d'une nouvelle analyse s'écrit directement dans sa fiche `docs/<domaine>/analyses/<règle>.md` ; le plan peut rester dans `docs/superpowers/plans/`.
## Fichiers
- `README.md` : point d'entrée pour un humain (lancer l'analyse, où trouver quoi). Tout le projet est versionné, sauf `out/`, `.venv/` et `__pycache__/` (D-014).
- `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.
- `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" -`.
- `docs/energy/` : le domaine Energy.
- `analyses/<règle>.md` (80-120 l) : fiche vivante de chaque analyse (principe, constantes et sources, résultats, limites, options écartées, pistes, historique). Modèle : `.claude/skills/nouvelle-analyse/modele-fiche.md`.
- `domaine/` (< 80 l) : `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) ; `cas-annotes-par-l-expert.md` (diagnostics experts des 5 stations, vérité de référence).
- `guide/diagnostic-energetique.md` (180 l, brouillon) : manuel, partie 1 pour le client (§1-4), partie 2 pour le support (§5-9). À tenir à jour avec la matrice et les fiches des deux analyses livrées.
- `matrice-etat-tendance.drawio` : matrice état × tendance, tenue par l'utilisateur.
- `docs/agents/rapport-exploratoire.md` (290 l) : cadre d'agents LLM (D-027) : choix retenus, architecture, démarrage par étapes (§6) ; annexe A : pistes à revoir étape par étape. Le code d'agent vivra à part (`agents/`, proposé, pas créé).
- `docs/aimsight/` : documentation AIMsight d'origine, en anglais, non modifiée. À lire avant de concevoir, **par section** ; ne pas re-demander à l'utilisateur ce qui y figure.
- `AIMsight_reference_quality_event_explainer_roadmap.md` (1 180 l) : **référence qui fait autorité** : couche diagnostique commune, explainer d'événements, classifications (§4.3), API indépendante de l'estimateur (§10).
- `AIMsight_agentic_support_project_context.md` (2 090 l) : extension support : chaîne de dépendance (§4), domaines dont la santé système (§5.1, le cas d'usage actuel), 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 : 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`, `AIMsight Test Manual.pdf` (en réalité le manuel de la station) : définitions des signaux et des colonnes CSV, alimentation, schedules.
- `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.
- `data/archive/` : `BusVoltage` seule des autres stations (incomplètes), mises de côté le 2026-10-09. Non analysées ; ne pas les réintroduire sans demande.
- `docs/superpowers/` : specs et plans superpowers (170-850 l chacun). Historique non maintenu, pas une référence. La spec d'une nouvelle analyse s'écrit dans sa fiche ; le plan peut aller dans `docs/superpowers/plans/`.
- `data/` : **jeu de travail = VERMONT seule** (D-009), le seul dataset complet : 7 CSV, un par métrique système (~5 000 l chacun). Les analyses tournent uniquement sur ce jeu.
- `metadata.md` (220 l) et `d.md` : notes brutes de l'expert, résumées dans `cas-annotes-par-l-expert.md`. `metadata.md` contient aussi des identifiants techniques de station (SIM, IP) : le dépôt doit rester privé (D-014).
- `archive/` : `BusVoltage` seule de 4 autres stations (incomplètes), mises de côté le 2026-10-09. Non analysées ; ne pas les réintroduire sans demande.
- `src/` : un sous-dossier par domaine, plus le code commun (D-026).
- `src/common/` : `stations.py` (chargement des CSV, trous de mesure ; bibliothèque standard) et `page.py` (poste de dev : bascule `.venv`, ouverture dans le navigateur, `AUTOSCALE_Y_JS`).
- `src/energy/` : calcul embarquable, en bibliothèque standard et sans import de `common/` : `moving_average.py`, `battery_state.py`, `battery_trend.py` et `day_color.py` (matrice, couleur du jour, focus J−1 / J). Scripts plotly du poste de dev : `daily.py`, `all_analyses.py` et `focus_jour.py`.
- `common/` : `stations.py` (chargement des CSV, trous de mesure ; bibliothèque standard) et `page.py` (poste de dev : bascule `.venv`, ouverture dans le navigateur, `AUTOSCALE_Y_JS`).
- `energy/` : calcul embarquable, en bibliothèque standard et sans import de `common/` : `battery_state.py`, `battery_trend.py`, `moving_average.py`, `day_color.py`. Scripts plotly du poste de dev, à laisser hors de la station : `final.py`, `all_analyses.py`, `focus_jour.py`.
- `maquettes/` : maquettes du site en HTML sur données réelles (D-022), Figma seulement sur demande. Un script remplit son gabarit HTML : `user/energy.py` + `energy_template.html` (client), `support/home.py` + `home_template.html` (support).
- `.claude/` : `rules/analyses.md` (se charge seule, voir « Analyses »), `skills/nouvelle-analyse/` (procédure et modèle de fiche), `settings.json` (lecture de `.env` interdite).
- `architecture.drawio` : schéma d'architecture tenu par l'utilisateur. Ne pas le modifier sans demande.
- `maquettes/` : maquettes de page en HTML, sur données réelles (D-022), en deux blocs : `user/` (client) et `support/`. Un script par design, ou directement le HTML. Figma seulement sur demande.
- `out/` : pages et JSON générés. Tout le projet est versionné, sauf `out/`, `.venv/` et `__pycache__/` (D-014).
## Règles de travail
- Une décision projet prise en conversation donne une entrée dans `docs/decisions.md`.
- Toute modification d'une analyse met à jour sa fiche dans le même changement.
- Un savoir métier nouveau va dans `docs/domaine/` (commun) ou `docs/<domaine>/domaine/`.
- Un changement de cap met à jour « État et prochaine étape » ci-dessus : l'état courant, pas un historique.
- Langue : échanges et documents projet en français ; documentation AIMsight en anglais (garder ses termes techniques) ; tout ce qui va au site en anglais, figure état × tendance comprise (D-023).
## Principes (raisons, statuts et options écartées : `docs/decisions.md`)
- **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`).
- Une analyse seule conclut au plus `consistent with`.
- **Livrable** : un graphique HTML par station. En haut, les analyses, un panneau chacune (courbes superposées, D-016) ; dessous, un graphique par série temporelle. Zoom dans le temps seulement, avec l'ordonnée recalée sur la plage visible (D-011, D-013).
- **Destinataire du diagnostic** : le client final et l'ingénieur support, en couches (D-020).
- **Analyses combinées** : chaque analyse est une preuve imparfaite, juste « dans la majorité des cas » ; la combinaison fait le diagnostic (pour Energy, la matrice état × tendance, D-020). Une analyse seule conclut au plus `consistent with`. Préférer des fenêtres larges (plusieurs jours, multiples de 24 h).
- **Livrables** : pour le site, une figure Plotly par station (état en haut, tendance dessous, D-021) et la couleur du jour ; pour comparer, une page HTML par station, un panneau par analyse puis un graphique par série (D-016). Zoom dans le temps seulement, ordonnée recalée sur la plage visible (D-013).
- **Destinataires du diagnostic** : le client final et l'ingénieur support, en couches (D-020).
- **Ouvert** : architecture (à définir plus tard, ne pas la figer ici).
## L'essentiel du domaine (détail : `docs/domaine/`)
@@ -109,20 +122,16 @@ Pour créer une analyse : skill `nouvelle-analyse` (`.claude/skills/nouvelle-ana
- **Chaque conclusion est traçable.** Elle cite les faits calculés et la règle qui l'a produite. Aucun chiffre ni seuil sans source.
- Ne pas confondre « pas de donnée visible » et « station arrêtée » : acquisition, transmission, ingestion et affichage sont des couches distinctes.
- Ne rien construire sur `inlier` binaire : RANSAC sera remplacé par un estimateur pondéré. Utiliser poids continus, `N_eff`, résidus, influence.
- `sigma0` seul et le nombre de références ne sont jamais des critères suffisants.
- Ne pas confondre qualité image d'une cible et qualité du réseau de références, ni petit résidu et transformation bien contrainte.
- Ne pas confondre mouvement en mode commun et mouvement structurel, ni références cohérentes et références physiquement fixes.
- Séparer fait observé, fait dérivé, contexte opérateur, hypothèse et inconnu. Pas de pseudo-probabilités ; vocabulaire : `confirmed` / `strongly supported` / `consistent with` / `possible` / `insufficient evidence` / `not observed`.
- Pas de règle spécifique à un site : les cas résolus deviennent des cas de régression.
- Lecture seule : aucune action sur les stations, la configuration ou le retraitement.
- Pour les déplacements (cas d'usage suivant) :
- ne rien construire sur `inlier` binaire : RANSAC sera remplacé par un estimateur pondéré. Utiliser poids continus, `N_eff`, résidus, influence ;
- `sigma0` seul et le nombre de références ne sont jamais des critères suffisants ;
- ne pas confondre qualité image d'une cible et qualité du réseau de références, ni petit résidu et transformation bien contrainte ;
- ne pas confondre mouvement en mode commun et mouvement structurel, ni références cohérentes et références physiquement fixes.
## Environnement
- `pandas` n'est pas installé ; la bibliothèque standard suffit pour explorer les CSV (`csv`, `datetime.fromisoformat`).
- `.venv/` (Python 3.14) ne contient que plotly, pour le poste de dev. Le code d'analyse reste en bibliothèque standard.
- Prototype expérimental : **pas de tests automatisés** (D-008). Vérifier les changements à la main en lançant `python3 src/energy/all_analyses.py` (et `daily.py` pour le livré) sur VERMONT.
## Conventions
- Échanges et documents projet en français ; la documentation AIMsight est en anglais (garder ses termes techniques).
+1 -1
View File
@@ -5,7 +5,7 @@ Agent de diagnostic **100 % analytique (sans LLM)** pour les stations AIMsight.
## Lancer l'analyse
```bash
python3 src/energy/daily.py
python3 src/energy/final.py
```
Le script analyse `data/` (station VERMONT) et ouvre dans le navigateur `out/VERMONT_daily.html`, l'état et la tendance de la batterie jour par jour : ce sont les analyses livrées, destinées au site de monitoring. La figure Plotly est aussi écrite dans `out/VERMONT_daily.json`.
+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*.
+35 -3
View File
@@ -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** :
@@ -260,7 +260,7 @@ Règles du journal :
- **Décision** :
- **Chaque domaine a son sous-dossier dans chaque couche** : `src/energy/` et `docs/energy/` (analyses, domaine, guide, matrice). Le code commun est dans `src/common/` (`stations.py` : chargement des CSV ; `page.py` : bascule `.venv`, ouverture, `AUTOSCALE_Y_JS`). `maquettes/` reste découpé par public (D-022). Les notes communes restent dans `docs/domaine/`.
- **Les analyses ne sont plus numérotées** : chacune est désignée par sa règle et sa fiche porte son nom (`docs/energy/analyses/daily_battery_state.md`). Correspondance : 01 = `MOVING_AVERAGE_7_DAYS_DROP`, 02 = `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP`, 03 = `DAILY_BATTERY_STATE`, 04 = `DAILY_BATTERY_TREND`. Les entrées du journal antérieures à celle-ci gardent les numéros.
- **Deux scripts d'analyse pour Energy** : `src/energy/daily.py`, les analyses livrées (état et tendance, D-020 et D-021), qui écrit `out/<STATION>_daily.html` et `.json` ; `src/energy/all_analyses.py`, les quatre analyses ensemble pour comparer (D-016), qui écrit `out/<STATION>_energy.html`. `src/energy/focus_jour.py` reste l'outil de focus (D-024). Le résumé texte d'`energy_check.py` (`out/<STATION>_energy.json`) est supprimé.
- **Deux scripts d'analyse pour Energy** : `src/energy/final.py` (`daily.py` jusqu'au 2026-10-13), les analyses livrées (état et tendance, D-020 et D-021), qui écrit `out/<STATION>_daily.html` et `.json` ; `src/energy/all_analyses.py`, les quatre analyses ensemble pour comparer (D-016), qui écrit `out/<STATION>_energy.html`. `src/energy/focus_jour.py` reste l'outil de focus (D-024). Le résumé texte d'`energy_check.py` (`out/<STATION>_energy.json`) est supprimé.
- **La documentation AIMsight d'origine passe de `doc/` à `docs/aimsight/`**, avec la copie du collecteur (`collecteur_system_info.py`, ex-`src/__main__ (3).py`). La roadmap perd le suffixe « (2) ». `cas-d-usage-03-04.drawio` devient `docs/energy/matrice-etat-tendance.drawio`. Les contenus ne changent pas.
- Le modèle de fiche passe dans le skill `nouvelle-analyse` (`modele-fiche.md`).
- **Pourquoi** : demande de l'utilisateur. Encapsuler Energy pour que le domaine suivant (D-002) se range à côté. Ranger les fichiers dispersés (racine, `doc/` à côté de `docs/`, code commun mêlé aux analyses). Energy a convergé vers les analyses livrées : un numéro d'ordre de création n'aide plus, le nom de la règle suffit.
@@ -271,4 +271,36 @@ Règles du journal :
- une numérotation par domaine : elle ne dit pas plus que le nom de la règle.
- **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.
- le code de calcul s'embarque en copiant `src/energy/` sans `final.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.
## D-028 — 2026-10-12 — CLAUDE.md : carte complète du dépôt, état courant, lecture ciblée
- **Statut** : active. Précise D-012.
- **Décision** :
- `CLAUDE.md` nomme chaque dossier et chaque document du dépôt, avec sa taille en lignes, pour que l'agent sache ce qui existe sans l'ouvrir ;
- il dit comment lire sans saturer le contexte : plan d'un fichier long puis la seule section utile, index de ce journal, CSV par script, dossiers à ne pas lire ;
- « État et prochaine étape » donne l'état courant, pas un historique daté ;
- ce qui est déjà dans `.claude/rules/analyses.md` (contrat `run(series)`, disposition des graphiques) n'y est plus répété.
- **Pourquoi** : demande de l'utilisateur. Le CLAUDE.md doit révéler tout le projet sans forcer l'agent à le lire. L'historique daté grossissait à chaque étape alors qu'il est déjà dans `git log` et ce journal ; la doc AIMsight (~3 300 lignes) était à « lire avant de concevoir » sans dire comment la lire par section.
- **Options écartées** : un index des sections de chaque gros document dans `CLAUDE.md` : `grep -n '^#'` le donne à la demande, sans coût permanent.
+2 -2
View File
@@ -1,10 +1,10 @@
# `DAILY_BATTERY_STATE` : état de la batterie jour par jour
- **Statut** : prototype en place (2026-10-12). Phase C : l'état seul, sans verdict. La phase B (niveaux gradués) viendra ensuite (D-018).
- **Script** : `python3 src/energy/daily.py [CSV ou dossiers]` (défaut : `data/`). Il écrit la page livrée, `out/<STATION>_daily.html` + `.json`, dont cette analyse est le panneau du haut (D-021), et l'ouvre dans le navigateur. Elle est aussi le troisième panneau de `python3 src/energy/all_analyses.py` (comparaison, D-016).
- **Script** : `python3 src/energy/final.py [CSV ou dossiers]` (défaut : `data/`). Il écrit la page livrée, `out/<STATION>_daily.html` + `.json`, dont cette analyse est le panneau du haut (D-021), et l'ouvre dans le navigateur. Elle est aussi le troisième panneau de `python3 src/energy/all_analyses.py` (comparaison, D-016).
- **Code** :
- `src/energy/battery_state.py` : calcul, bibliothèque standard uniquement (`run()`, `day_facts()`). Il reçoit les séries chargées par `common.stations.load_stations`, mais n'importe rien d'autre du projet : avec `src/energy/battery_trend.py`, il se livre seul à la plateforme (D-021) ;
- `src/energy/daily.py` : graphique plotly.
- `src/energy/final.py` : graphique plotly.
## Question posée
+2 -2
View File
@@ -1,10 +1,10 @@
# `DAILY_BATTERY_TREND` : tendance de la batterie d'un jour à l'autre
- **Statut** : prototype en place (2026-10-12). Pas de verdict : `anomaly = None`, la tendance est dans `facts.trend`.
- **Script** : `python3 src/energy/daily.py [CSV ou dossiers]` (défaut : `data/`). Il écrit la page livrée, `out/<STATION>_daily.html` + `.json`, dont cette analyse est le panneau du bas (D-021), et l'ouvre dans le navigateur. Elle est aussi le quatrième panneau de `python3 src/energy/all_analyses.py` (comparaison, D-016).
- **Script** : `python3 src/energy/final.py [CSV ou dossiers]` (défaut : `data/`). Il écrit la page livrée, `out/<STATION>_daily.html` + `.json`, dont cette analyse est le panneau du bas (D-021), et l'ouvre dans le navigateur. Elle est aussi le quatrième panneau de `python3 src/energy/all_analyses.py` (comparaison, D-016).
- **Code** :
- `src/energy/battery_trend.py` : calcul, bibliothèque standard uniquement (`run()`). Il s'appuie sur `battery_state.run()` (`DAILY_BATTERY_STATE`) ;
- `src/energy/daily.py` : graphique plotly.
- `src/energy/final.py` : graphique plotly.
## Question posée
+1 -1
View File
@@ -147,7 +147,7 @@ Lecture de chaque case, avec le nombre de jours observés sur VERMONT (184 jours
## 8. Lire les pages HTML
Commandes : `python3 src/energy/daily.py` écrit la page livrée, `python3 src/energy/all_analyses.py` la page de comparaison ; chacune est écrite dans `out/` et ouverte dans le navigateur.
Commandes : `python3 src/energy/final.py` écrit la page livrée, `python3 src/energy/all_analyses.py` la page de comparaison ; chacune est écrite dans `out/` et ouverte dans le navigateur.
- `<STATION>_daily.html` : le graphique destiné au site de monitoring (D-021), soit les panneaux `DAILY_BATTERY_STATE` et `DAILY_BATTERY_TREND` décrits ci-dessous, sur le même axe du temps. Sa figure Plotly est aussi écrite en JSON (`<STATION>_daily.json`), pour `Plotly.newPlot`.
- `<STATION>_energy.html` : la page de comparaison des quatre analyses (`all_analyses.py`), avec ces deux panneaux, et une courbe par mesure dessous.
+2 -2
View File
@@ -1,7 +1,7 @@
"""Maquette côté client « Energy » : page System Summary du site de monitoring, avec une section Diagnostic (D-020 à D-023).
Données réelles VERMONT. Bloc Energy : couleur du dernier jour de la fenêtre, échelle de batterie et tendance face à la veille
(src/energy/day_color.py), puis historique complet (energy.daily.daily_figure, D-021) et guide (partie 1 du manuel), repliés.
(src/energy/day_color.py), puis historique complet (energy.final.daily_figure, D-021) et guide (partie 1 du manuel), repliés.
Écrit out/maquette_user_energy.html et l'ouvre dans le navigateur.
Usage : python3 maquettes/user/energy.py [AAAA-MM-JJ début] [AAAA-MM-JJ fin] (défaut : 2026-09-18 à 2026-09-28)
"""
@@ -17,7 +17,7 @@ sys.path.insert(0, str(ROOT / "src"))
from common.page import AUTOSCALE_Y_JS, open_html # noqa: E402 (bascule seule sur .venv si plotly manque)
from common.stations import load_stations # noqa: E402
from energy import battery_state as bs, battery_trend as bt, day_color as dc # noqa: E402
from energy.daily import daily_figure # noqa: E402
from energy.final import daily_figure # noqa: E402
START = date.fromisoformat(sys.argv[1]) if len(sys.argv) > 1 else date(2026, 9, 18)
END = date.fromisoformat(sys.argv[2]) if len(sys.argv) > 2 else date(2026, 9, 28)
+1 -1
View File
@@ -11,7 +11,7 @@ from common.page import AUTOSCALE_Y_JS, ROOT, open_html # noqa: E402 (bascule
from common.stations import gaps, load_stations # noqa: E402
from plotly.subplots import make_subplots # noqa: E402
from energy import battery_state as bs, battery_trend as bt, moving_average as ma # noqa: E402
from energy.daily import daily_state_panel, daily_trend_panel # noqa: E402
from energy.final import daily_state_panel, daily_trend_panel # noqa: E402
# Zones de BusVoltage selon l'état de la batterie (bandes de fond) : docs/energy/domaine/tensions-selon-l-etat-de-la-batterie.md.
# [V] = VERMONT, 5e-95e centiles horaires ; [M] = manuel ; [E] = experts. Les zones « en charge » et « décharge »
+1 -1
View File
@@ -1,6 +1,6 @@
"""Analyses livrées (D-020) : DAILY_BATTERY_STATE et DAILY_BATTERY_TREND, en une figure pour le site (D-021).
Usage : python3 src/energy/daily.py [CSV ou dossiers...] (défaut : data/)
Usage : python3 src/energy/final.py [CSV ou dossiers...] (défaut : data/)
Écrit out/<STATION>_daily.html (page de démo) et .json (figure Plotly pour le site, Plotly.newPlot), puis les ouvre.
Documentation : docs/energy/analyses/daily_battery_state.md et daily_battery_trend.md
"""
+1 -1
View File
@@ -13,7 +13,7 @@ from common.page import ROOT, open_html # noqa: E402 (bascule seule sur .venv
from common.stations import gaps, load_stations # noqa: E402
import plotly.graph_objects as go # noqa: E402
from energy import battery_state as bs, battery_trend as bt, day_color as dc # noqa: E402
from energy.daily import STATE_STYLE, TREND_STYLE, noon # noqa: E402
from energy.final import STATE_STYLE, TREND_STYLE, noon # noqa: E402
# Statuts : noms et couleurs de la maquette System Summary (maquettes/user/energy_template.html).
COLOR = {"GREEN": ("Green", "#008300"), "ORANGE": ("Orange", "#eda100"), "RED": ("Red", "#d03b3b"),