Files
Support-Agent/CLAUDE.md
T
maximeandClaude Opus 5.5 3082f75429 Add analysis 04 entry point and documentation
src/analyse_04.py launches the common page; sheet 04 moves to
"prototype en place" with VERMONT results; CLAUDE.md, the analyses
rule, README and sheet 01 list the fourth panel and extend the
"no verdict" contract exception to analysis 04.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 11:36:26 +02:00

118 lines
12 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)**, 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** : l'analyse 01 est en place sur VERMONT et produit un graphique HTML. C'est un prototype expérimental, sans tests automatisés.
- **Point ouvert de l'analyse 01** : l'accoutumance. Après plus de 30 jours de déficit, l'anomalie peut disparaître (voir sa fiche).
- **2026-10-12** : analyse 02 (`MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP`, suggestion d'un collègue) en place, en panneau sous la 01 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 pour la 01.
- **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** : analyse 03 `DAILY_BATTERY_STATE` en place (phase C, état seul).
- **2026-10-12** : analyse 04 `DAILY_BATTERY_TREND` en place (tendance markovienne : chaque jour face à la veille, mieux / stable / pire).
- **Prochaine étape** : phase B de l'analyse 03 (niveaux gradués à partir des séries d'états et des tendances de la 04, voir les pistes des fiches), puis la combinaison des analyses.
## Analyses
| N° | Nom | Question | Statut | Fiche |
|---|---|---|---|---|
| 01 | `MOVING_AVERAGE_7_DAYS_DROP` | La tension moyenne sur 7 jours décroche-t-elle de son propre passé récent (> 0,2 V) ? | prototype en place | `docs/analyses/analyse_01.md` |
| 02 | `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP` | Même question, sur la seule mesure de 00:00 UTC de chaque jour | prototype en place | `docs/analyses/analyse_02.md` |
| 03 | `DAILY_BATTERY_STATE` | Chaque jour : pleine charge, charge partielle (incertain), sous le plateau ou aucune charge ? | prototype en place | `docs/analyses/analyse_03.md` |
| 04 | `DAILY_BATTERY_TREND` | Chaque jour, face à la veille : mieux, stable ou pire (changement d'état, sinon écart de fin de nuit) ? | prototype en place | `docs/analyses/analyse_04.md` |
Pour créer une analyse : skill `nouvelle-analyse` (`.claude/skills/nouvelle-analyse/`).
## Commandes
- `python3 src/analyse_01.py` : point d'entrée de l'analyse 01. Il analyse `data/`, écrit `out/<STATION>_energy.html` (panneaux des analyses 01 à 04, D-016) et l'ouvre dans le navigateur (via `explorer.exe` sous WSL). Il bascule seul sur `.venv` si plotly manque.
- `python3 src/analyse_02.py` : point d'entrée de l'analyse 02 ; il lance la même page.
- `python3 src/analyse_03.py` : point d'entrée de l'analyse 03 ; il lance la même page.
- `python3 src/analyse_04.py` : point d'entrée de l'analyse 04 ; il lance la même page.
- `python3 src/energy_check.py data/` : résumé texte + `out/<STATION>_energy.json` (`out/` est ignoré par git).
- `.venv/bin/python src/energy_plot.py data/` : graphique seul (plotly.js est chargé depuis le CDN).
## 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/analyses/analyse_NN.md` : fiche vivante de chaque analyse (principe, constantes et sources, résultats, limites, options écartées, historique). Modèle : `docs/analyses/_modele.md`.
- `docs/domaine/` : le savoir métier, une note par question.
- `ce-que-mesure-la-station.md` : format CSV, métriques et unités, consommation mesurée mais pas l'apport.
- `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).
- `pieges-des-donnees.md` : trou ≠ coupure, signatures d'une coupure, seuils absolus, cycle jour/nuit.
- `cas-annotes-par-l-expert.md` : diagnostics experts des 5 stations.
- `colonnes-des-deplacements.md` : colonnes des déplacements (cas d'usage suivant).
- **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/` ;
- 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/analyses/analyse_NN.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).
- `doc/` : documentation AIMsight, à lire avant de concevoir. Ne pas re-demander à l'utilisateur ce qui y figure.
- `AIMsight_reference_quality_event_explainer_roadmap (2).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). Le doc de contexte la cite sans le suffixe « (2) ».
- `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 "doc/<fichier>.pdf" -`.
- `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/analyse_NN.py` : point d'entrée de chaque analyse. Code partagé : `src/energy_check.py` (analyses 01 et 02, bibliothèque standard uniquement, embarquable), `src/battery_state.py` (analyse 03, idem), `src/battery_trend.py` (analyse 04, idem) et `src/energy_plot.py` (plotly, poste de dev).
- `src/__main__ (3).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.
- `architecture.drawio` : schéma d'architecture tenu par l'utilisateur. Ne pas le modifier sans 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, 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 : analyses 03 en phase C et 04, 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).
- **Ouvert** : architecture (à définir plus tard, ne pas la figer ici), destinataire du diagnostic (client final ou ingénieur support).
## 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/analyse_01.py` sur VERMONT.
## Conventions
- Échanges et documents projet en français ; la documentation AIMsight est en anglais (garder ses termes techniques).