Project goal, decisions taken so far (energy health first, analytics only, embedded target, no synthetic data), annotated data cases, domain essentials from doc/ and non-negotiable diagnostic rules. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
88 lines
8.2 KiB
Markdown
88 lines
8.2 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 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**.
|
||
|
||
État : phase de conception. Pas de code. Langage : **Python**. Relancer `/init` quand du code existe.
|
||
|
||
## Fichiers
|
||
|
||
- `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/` : séries réelles et diagnostics experts (voir plus bas).
|
||
- `architecture.drawio` : schéma d'architecture tenu par l'utilisateur. Ne pas le modifier sans demande.
|
||
|
||
## Décisions prises (2026-10-09)
|
||
|
||
- **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 » (« pourquoi D-300-A a sauté ? ») viendra ensuite, sur le même socle.
|
||
- **Premier cas d'usage : santé énergétique des stations** (tension batterie, interruptions de mesure ; stations solaires et sur secteur). Ici, le trou de données *est* l'anomalie. L'interprétation des déplacements viendra ensuite.
|
||
- **Données** : des CSV simulent la future base de données ; Parquet/HDF5 viendront ensuite. Les schémas CSV historiques varient.
|
||
- **Pas de données synthétiques** : ne pas générer de CSV simulés ni de générateur de scénarios (refus explicite de l'utilisateur).
|
||
- **Pas de LLM** : détection, classement et explication par méthodes analytiques et règles. L'explication est générée à partir des faits calculés.
|
||
- **Embarqué** : le code doit pouvoir tourner sur la station, qui fonctionne souvent sur batterie et panneau solaire. Il faut donc un calcul léger et des dépendances minimales.
|
||
- **Ouvert** : architecture (à définir plus tard, ne pas la figer ici), destinataire du diagnostic (client final ou ingénieur support), unités des métriques système.
|
||
|
||
## Données (`data/`)
|
||
|
||
- Un CSV par station et par métrique : `<STATION>_<Metric>_<début> to <fin>.csv`. Colonnes `,time_utc,metric` (index sans nom, horodatage UTC, pas d'une heure). Une valeur `metric` vide = pas de mesure.
|
||
- Diagnostics experts (vérité de référence) dans `data/metadata.md` (avec le contexte matériel et un instantané de l'état système, unités `[unknown]`) et dans `data/d.md`.
|
||
- Cas annotés (tension batterie `BusVoltage`) :
|
||
|
||
| Station | Alimentation | Diagnostic expert | Signature observée |
|
||
|---|---|---|---|
|
||
| JUNGFRAU | solaire | sain | aucun trou, max quotidien ~14,1–14,2 V, jours nuageux sans montée diurne |
|
||
| VERMONT | solaire | interruptions nocturnes (déficit) | max quotidien plafonne ~13,2–13,5 V dès le 20/09, coupures nocturnes dès le 27/09 vers ~12,2 V |
|
||
| WILDSTRUBEL | solaire | décharge profonde sous 12 V (UVLO désactivé ?), coupure ~12 j, puis interruptions nocturnes | max quotidien en baisse dès le 04/09, 11,53 V le 09/09 puis 298 h sans mesure |
|
||
| FLORIDA | secteur | sain, sans interruption | ~14,2–14,4 V sans cycle jour/nuit (une baisse ponctuelle à 13,0 V le 10/07). Quelques trous courts à tension normale : ce ne sont pas des coupures d'alimentation |
|
||
| MISSISSIPPI | secteur | coupures secteur : la batterie sert d'UPS puis le système se déconnecte | chute 14,2 → ~13,1 V, lente baisse, coude vers 12,5 V, puis décrochage ; nombreuses coupures déc. 2025–juin 2026, lectures jusqu'à 10,3 V |
|
||
|
||
- Pièges :
|
||
- Des valeurs vides **en fin de fichier** peuvent être un retard de synchronisation (`last_sync`), pas une coupure (WILDSTRUBEL, MISSISSIPPI le 09/10).
|
||
- Des trous **simultanés sur plusieurs stations** (FLORIDA et MISSISSIPPI le 22/07 à 14:00 et le 22/08 à 17:00) pointent plutôt vers une cause commune hors station.
|
||
- Un trou avec une tension normale avant et après n'est pas un problème d'énergie.
|
||
|
||
## Domaine : l'essentiel
|
||
|
||
Énergie (metadata + manuel de la station) :
|
||
- Batterie LiFePO4 de 12,8 V nominal (environ 7 ou 21 Ah). Panneau solaire 12 V, ~100 W conseillé. Entrée max 26 V.
|
||
- Sur secteur, la batterie reste connectée et sert d'UPS.
|
||
- Après une décharge profonde (< 12 V), la station reste éteinte jusqu'à ~12,6 V avant de redémarrer. L'UVLO doit couper avant la décharge profonde.
|
||
- Mesure quasi statique typiquement toutes les 15 min. Remède attendu en cas de déficit : réactiver le mode veille profonde (sleep) entre les mesures. Le « Continuous mode » (LED allumées) augmente la consommation.
|
||
|
||
Colonnes CSV des déplacements (cas d'usage suivant), préfixées par la cible (ex. `target_06_rch`) :
|
||
- `rch` / `rcv` : déplacement corrigé du mouvement caméra [mm], le signal principal.
|
||
- `x` / `y` : position brute dans l'image [px].
|
||
- `rx` / `ry` : déplacement relatif avant correction caméra. **Ce n'est pas** `x - x0`.
|
||
- `error` : erreur de reconnaissance de la cible, **pas** une incertitude. Seuil par défaut 0.7.
|
||
- `camera_pan|tilt|rotation` [deg], `camera_scale`, `camera_sigma0` (résidu du fit du réseau de références).
|
||
- `inlier_{ch}`, `reproj_err_{ch}` : contribution et résidu de chaque référence.
|
||
- Sharpness, FWHM, Dominance, Peak Intensity, Flux, SNR : **uniquement dans l'export HDF5**.
|
||
|
||
Causes à départager pour une anomalie de déplacement : mouvement réel de l'ouvrage, mouvement de la caméra, instabilité de la compensation (cas Barcelone), dégradation locale d'une cible, parallaxe / modèle inadapté.
|
||
|
||
## 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 tests de régression.
|
||
- Lecture seule : aucune action sur les stations, la configuration ou le retraitement.
|
||
|
||
## Environnement
|
||
|
||
- `pandas` n'est pas installé dans l'environnement de dev ; la bibliothèque standard suffit pour explorer les CSV (`csv`, `datetime.fromisoformat`).
|
||
|
||
## Conventions
|
||
|
||
- Échanges et documents projet en français ; la documentation AIMsight est en anglais (garder ses termes techniques).
|