Files
aimsight-optimizer/docs/superpowers/specs/2026-11-13-optimizer-design.md
T

9.2 KiB

Optimizer : conception

2026-11-13. Statut : approuvée ; les trois étapes construites, la tâche VS Code à faire ; premier essai de bout en bout le 2026-11-14 (docs/essais/2026-11-05.md).

L'intention

Faire converger les détecteurs en continu, à faible coût. Chaque jour pompé devient un batch de 24 h : les détecteurs passent sur toutes les stations (gratuit : 3,5 s pour 3 jours de NORDEND) ; un scanner léger regarde leurs étiquettes et les données de loin, note chaque irrégularité dans un rapport ; s'il en a noté, /detectors:wf-improve améliore les détecteurs, sous le garde-fou du benchmark.

Le mode ciblé de Diagnostic-App reste tel quel : une analyse approfondie d'un événement, puis « Optimiser les détecteurs ». Optimizer en est la version large et légère : il voit toutes les stations, mais de loin, et ne remarque que des irrégularités.

Objectifs, non-objectifs, anti-objectifs

  • Objectifs : une commande par batch, toutes les stations ; un scanner bon marché (une figure et une liste d'étiquettes par station) ; une seule séance d'amélioration par batch, sur toutes ses irrégularités ; chaque batch laisse une trace lisible.
  • Non-objectifs : le pompage (il est dans le dépôt aimsight-data), l'étiquetage pour l'expert, une page web, les outils de lecture, le contrat des détecteurs.
  • Anti-objectifs (un échec, même si ça tourne) : une séance légère qui fait reculer les détecteurs sur les étiquettes revues, donc défait un gain du mode ciblé ; un scanner dont le coût approche celui de l'analyste ; des étiquettes du scanner mêlées à labeling/auto/.

Les approches

  • Retenue : le scanner corrige les étiquettes des détecteurs. Les étiquettes des détecteurs du batch sont copiées ; le scanner applique chaque irrégularité à la copie (retire une fausse alerte, ajoute un oubli, corrige une famille ou une borne) et la note dans son rapport. La copie corrigée est la vérité de wf-improve, son rapport le contexte : le score du batch ne montre que les corrections.
  • Écartée : wf-improve qui lirait un rapport sans étiquettes. Plus de score sur la plage pour l'upgrader ni pour le validator, et deux façons d'améliorer à tenir.
  • Écartée : le scanner signale seulement, l'amélioration reste l'analyse de l'app. La boucle ne se ferme pas seule.

La compatibilité avec le mode ciblé

  • Le même dépôt detectors (une seule copie, ~/detectors, par un lien), et le même plugin : Diagnostic-App et Optimizer en sont deux appelants.
  • La même vérité de référence : labeling/auto/ (le dépôt ~/labeling, partagé avec Diagnostic-App), où l'app verse les étiquettes de ses analyses. Le benchmark de chaque séance légère porte donc sur les cas ciblés : une séance qui en ferait reculer un est refusée par le validator ; et inversement.
  • Les étiquettes du scanner à part, dans le dossier du batch, jamais versées dans labeling/auto/ (elles ne sont pas revues).
  • Un ajout au plugin, compatible : aujourd'hui wf-improve prend une seule station ; un batch en a plusieurs, le même jour. Le plugin accepte en plus un dossier d'étiquettes, une par station (<STATION>.jsonl, comme REFERENCE), avec la même plage pour toutes ; regression.py prend --from/--to pour mesurer ce jour-là. La requête d'une seule station, celle de l'app, ne change pas. Une seule séance sur toutes les stations coûte moins que plusieurs, et pousse l'upgrader vers un mécanisme qui revient d'une station à l'autre plutôt que vers un cas.
  • Git : detectors est un lien vers la seule copie du poste : un commit du batch se voit aussitôt dans l'app, et inversement ; avec --push, le batch pousse après. Deux séances ne tournent pas en même temps sur les détecteurs.

Un batch

Le jour : par défaut le dernier jour UTC complet ; --jour AAAA-MM-JJ pour un autre. Un batch déjà fait (son dossier existe) ne se refait pas.

  1. Les détecteurs (script, sans LLM) : categories.events sur le jour, avec ses 3 jours d'historique, pour chaque station de data/ qui a des mesures ce jour-là. Leurs événements deviennent des étiquettes (id, debut, fin, categorie = la famille, description = le texte de l'événement), coupées au jour : batches/<jour>/detecteurs/<STATION>.jsonl, copiées dans batches/<jour>/verite/. Pour chaque station, une figure batches/<jour>/figures/<STATION>.png : corr_x et corr_y des cibles sur les 24 h, les étiquettes en bandes colorées par famille, et une bande des mesures manquantes ou rejetées (error_value au-dessus du seuil).

  2. Le scan (claude -p, agent scanner, Sonnet) : pour chaque station, il lit la liste de ses étiquettes et regarde sa figure ; une image de la caméra au besoin, quelques-unes au plus pour tout le batch. Il ne lit jamais les CSV. Chaque irrégularité :

    • raté : les courbes bougent ou manquent, aucune étiquette ;
    • trop : une étiquette sur des courbes plates, mesures présentes et acceptées ;
    • bornes : l'étiquette commence trop tard, finit trop tôt, déborde sur du calme ;
    • famille : la forme dit une autre famille (une onde diurne, une seule cible qui s'écarte, un trou) ;

    il la note dans batches/<jour>/rapport.md (station, heures, cas, ce qu'il voit) et l'applique à verite/<STATION>.jsonl. Il finit par **Verdict**: rien à corriger | irrégularités. Le script vérifie ensuite la vérité (JSON, clés, famille connue de labeling/familles.md).

  3. L'amélioration, si le scanner a corrigé une station et la vérité est sans erreur : claude -p --plugin-dir detectors "/detectors:wf-improve …" avec DATA: data, STATIONS: les stations corrigées, LABELS: batches/<jour>/verite, le jour, REFERENCE: --labels labeling/auto --data data, FAMILIES: labeling/familles.md, CONTEXT: batches/<jour>/rapport.md, OUT: batches/<jour>/improve/. Son bilan, improve/summary.md, est celui du batch ; ses agents gardent leurs scripts dans improve/tools/.

Le déclenchement : une tâche VS Code « batch », et une ligne après le pompage dans le Planificateur de tâches de Windows.

L'ordre de grandeur : une figure coûte environ 1 500 tokens ; pour 13 stations, une vingtaine de milliers, plus les listes d'étiquettes et quelques images, sur Sonnet. wf-improve coûte ce qu'il coûte dans l'app, et seulement les jours où le scanner a noté quelque chose.

Les limites : le scanner voit les courbes de loin, il rate ce que la figure ne montre pas (une dérive lente, un capteur noyé parmi vingt) ; une étiquette qui passe minuit est coupée au jour, ses bornes hors du jour ne se jugent pas, et un saut du soir qui revient après minuit reste « not back yet » : les détecteurs ne lisent rien après le jour, comme score.py (avec quelques heures de plus, leurs statistiques changent sur tout le jour, et la vérité ne serait plus « les détecteurs et les seules corrections du scanner »). Ses erreurs ne font pas reculer les détecteurs ailleurs : le benchmark sur les étiquettes revues les arrête.

Le dépôt

Optimizer/
  README.md, CLAUDE.md
  batch.py                  le batch et ses figures (matplotlib, .venv ; claude sur le PATH)
  .claude/agents/scanner.md
  detectors -> ~/detectors  le dépôt detectors, hors de git
  data -> ~/aimsight-data/data           hors de git, lecture seule
  labeling -> ~/labeling                  hors de git, lecture seule (familles.md, auto/)
  batches/<jour>/           detecteurs/, verite/, detecteurs.md, rapport.md, improve/ ; figures/, scan.jsonl,
                            improve.jsonl hors de git
  outils/                   scripts de lecture pour contrôler un batch à la main (venus de l'audit du premier essai)
  docs/essais/              un journal par essai de bout en bout

La figure, telle que construite : par pas de 15 min (une station qui mesure par rafales, comme SUSTENHORN, ou à deux cadences, comme NADELHORN, s'y lit comme les autres ; dans chaque pas, l'écart le plus grand, pour qu'un pic d'une mesure reste ; une mesure rejetée n'y est pas tracée, la courbe s'interrompt) ; les cibles en bruits propres autour de leur médiane du jour, calmes entre ±5 ; les références non tracées (certaines valent 0 par construction), mais leurs rejets comptés à part, en noir, dans le panneau des rejets. Les étiquettes des détecteurs vont de la mesure d'avant l'événement à celle d'après (sauf No data, déjà d'une mesure à l'autre) : à vérité intacte, le score de plage est à 100 %.

Mes choix, à corriger

  • Le scanner sur Sonnet ; wf-improve sur le modèle par défaut, comme dans l'app.
  • Une seule séance d'amélioration par batch, sur toutes les stations corrigées.
  • Pas de push sans --push.
  • Le dépôt en français, comme Diagnostic-App (le dépôt detectors reste en anglais).

L'ordre de construction

  1. Le dépôt (liens, CLAUDE.md), l'étape 1 et la figure ; un coup d'œil sur un jour réel.
  2. Le scanner, sur ce jour ; on lit son rapport ensemble.
  3. L'ajout au plugin, l'amélioration, la tâche VS Code.

Laissé au constructeur

La mise en page de la figure, le nombre d'images de la caméra permises au scanner, le format exact d'une ligne du rapport.