Files
Support-Agent/CLAUDE.md
T
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

131 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
## 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)**, 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
- **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).
- **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)
| 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` |
Pour créer une analyse : skill `nouvelle-analyse` (`.claude/skills/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.
## Documentation (à lire à la demande)
- `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.
- `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/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` ;
- 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 : 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.
- `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.
- `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`.
- `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.
## 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 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).
- **Ouvert** : architecture (à définir plus tard, ne pas la figer ici).
## L'essentiel du domaine (détail : `docs/domaine/`)
- **Données** : un CSV par station et par métrique, `<STATION>_<Metric>_<début> to <fin>.csv`, colonnes `,time_utc,metric`, moyennes horaires en UTC. Une valeur vide signifie qu'il n'y a pas de mesure.
- **Unités** : `BusVoltage` [V], `BusCurrent` [mA], `Power` [mW], `ShuntVoltage` [mV]. Ces trois dernières sont une seule mesure : la **consommation**. **L'apport (panneau ou secteur) n'est pas mesuré.**
- **Batterie LiFePO4 de 12,8 V** :
- entre 30 et 90 % de charge, la tension de nuit reste plate ; elle ne chute qu'au coude (~12,8 V, puis ~12,5 V) ;
- sous 12 V, la station s'éteint et ne redémarre que vers ~12,6 V ;
- ≥ 14,0 V dans la journée signale une charge complète.
- **Les seuils de tension absolus ne se transposent pas d'une station à l'autre** : comparer la station à son propre passé. Exception : les seuils du matériel (fin de charge ~14,0 V, coude 12,8 V), admis pour les analyses d'état (D-018).
- **Un trou n'est pas forcément une coupure** : retard de synchronisation en fin de fichier, début d'historique, cause commune si plusieurs stations ont un trou en même temps.
## Règles non négociables
- **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.
## 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).