Files
Support-Agent/CLAUDE.md
T
maximeandClaude Opus 5.5 57ea286014 Fill CLAUDE.md with project context
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>
2026-10-09 17:05:11 +02:00

8.2 KiB
Raw Blame History

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).