diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..63d127c --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,15 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "permissions": { + "allow": [ + "Bash(python3 controle.py:*)", + "Bash(python3 ids.py:*)", + "Bash(python3 precedents.py:*)", + "Bash(docker start ollama-bge-m3)" + ], + "deny": [ + "Edit(./manual/**)", + "Write(./manual/**)" + ] + } +} diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..4351c77 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,16 @@ +# CLAUDE.md + +labeling : les étiquettes des déplacements AIMsight et le savoir pour les poser, en un seul exemplaire sur le poste (`README.md`). Diagnostic-App y lit et écrit, Optimizer y lit seulement, tous deux par un lien `labeling -> ~/labeling` ; on commite ici. + +- **Les étiquettes** : `manual/.jsonl` (l'expert), `auto/.jsonl` (les agents, relues par `revue`), une par ligne, `{"id", "debut", "fin", "categorie", "description", ...}`. Les analyses de Diagnostic-App : `auto/analyses/__/`. +- **Le savoir** : `familles.md` (les familles, leurs frontières), `regles-d-etiquetage.md` (bornes, un seul événement, description, cause dite), `carte-des-etiquettes.md` (les phénomènes, par son sommaire), `connaissances/`. +- **Les outils**, bibliothèque standard : `python3 controle.py [STATION | fichier.jsonl]` (les règles), `python3 ids.py [STATION]` (l'id stable des nouvelles), `python3 precedents.py "" [--exclure STATION DEBUT FIN] [--famille F] [--k N]` (le RAG ; Ollama `docker start ollama-bge-m3` ; `--check` sans lui). +- **Vérifier** : `python3 controle.py` (aujourd'hui 18 erreurs attendues : les étiquettes versées par l'app sans `revue`) et `python3 precedents.py --check`. + +Règles : +- **`manual/` est à l'expert** : aucun agent n'y écrit. +- Une étiquette ajoutée à `auto/` passe par `ids.py` puis `controle.py` ; un id ne change jamais. +- Toute heure est en UTC ; descriptions en mots, sans valeur chiffrée. +- Pas de règle propre à une station, une cible ou une date dans les règles et les familles. +- Commits par chemin, jamais `git add -A` : Diagnostic-App écrit ici en même temps. +- Langue : français. diff --git a/docs/superpowers/specs/2026-11-14-labeler-design.md b/docs/superpowers/specs/2026-11-14-labeler-design.md new file mode 100644 index 0000000..d8e2a62 --- /dev/null +++ b/docs/superpowers/specs/2026-11-14-labeler-design.md @@ -0,0 +1,154 @@ +# Le labeler : conception + +2026-11-14. Statut : proposée. Les choix marqués « Mon choix » sont à vérifier en lisant. + +## L'intention + +Produire des étiquettes LLM de bonne qualité **à faible effort**, en grand nombre, sans qu'un analyste fasse l'analyse +approfondie de chaque plage. On donne au labeler un lot ; avec l'aide des détecteurs, il l'étiquette comme l'analyste le +ferait, en moins approfondi. Il sera moins bon que l'analyste, et c'est accepté : le gain est l'effort. + +Il s'améliore sans qu'on le touche : par les précédents (le RAG, `precedents.py`), qui s'enrichissent des étiquettes de +l'expert et des étiquettes relues, et par les progrès des détecteurs, qui lui montrent mieux où regarder. + +C'est l'une des tâches séparées de la chaîne : l'**analyste** (Diagnostic-App, approfondi, une plage choisie), le +**labeler** (ici, large, un lot), l'**optimiseur** (Optimizer, les détecteurs). Le scanner d'Optimizer fait aujourd'hui un +petit étiquetage de loin ; quand le labeler tournera, Optimizer pourra lire ses étiquettes à la place (un autre chantier, +dans Optimizer, plus tard). + +## Objectifs, non-objectifs, anti-objectifs + +- **Objectifs** : une commande par lot ; des étiquettes aux règles de `regles-d-etiquetage.md` (0 erreur à `controle.py`), + versées dans `auto/` avec leur provenance ; un coût par station-jour très en dessous de l'analyste ; chaque lot laisse + une trace lisible (ce qui justifie chaque étiquette, ce qui a manqué dans la documentation). +- **Non-objectifs** : le rapport de diagnostic pour l'utilisateur (c'est l'analyste) ; l'amélioration des détecteurs ; + une page dans l'app ; la relecture des étiquettes ; sortir les outils de lecture de Diagnostic-App. +- **Anti-objectifs** (un échec, même si ça tourne) : + - les étiquettes du labeler, non relues, comptées comme vérité par le benchmark des détecteurs ou par `wf-improve` : + les détecteurs se mesureraient à leur propre reflet ; + - le labeler qui recopie les détecteurs : leurs ratés deviennent les siens, et rien ne les corrige plus ; + - ses erreurs qui reviennent comme exemples à suivre : des précédents « labeler » non relus présentés comme ceux de + l'expert ; + - une étiquette de `manual/` ou une étiquette relue de `auto/` modifiée par le labeler. + +## Les approches + +**Où il vit.** +- **Retenue : dans `~/labeling`**, à côté des étiquettes qu'il écrit et du savoir qu'il lit : plus logique. +- Écartée : un dépôt `~/labeler` à part, comme Optimizer : plus séparé, mais un dépôt de plus pour un agent qui ne fait + qu'écrire ici. +- Écartée : un agent de plus dans Diagnostic-App : les tâches restent mêlées dans l'app. + +**Où vont ses étiquettes.** +- **Retenue : dans `auto/.jsonl`, avec `"source": "labeler"`**, toutes les étiquettes au même endroit ; ceux qui + ne doivent pas les compter les écartent par ce champ. +- Écartée : un dossier `labeler/` à part : aucun code partagé à toucher, mais un troisième endroit où chercher les + étiquettes. + +## Ce qui est décidé + +### Le lot + +Un jour UTC, toutes les stations de `data/` qui ont des mesures ce jour-là, ou celles de `--stations A,B`. Une séance +`claude -p --agent labeler` par station (le contexte d'une station-jour, pas celui de onze). Le jour par défaut : le +dernier jour UTC complet ; `--jour AAAA-MM-JJ` pour un autre. + +```bash +python3 labeler.py # hier, toutes les stations +python3 labeler.py --jour 2026-11-12 --stations NORDEND,JUNGFRAU +``` + +Un lot déjà fait pour une station (son dossier a `etiquettes.jsonl` versé) ne se refait pas ; supprimer le dossier pour +refaire. + +### Les détecteurs, où regarder + +`labeler.py` lance `categories.events` (le lien `detectors`) sur le jour, avec 3 jours d'historique, comme `batch.py` +d'Optimizer, et écrit leurs événements pour l'agent (heures, famille, texte) dans le dossier du lot. Le labeler les lit +comme **des endroits où regarder**, jamais comme une preuve : chaque étiquette se fonde sur ce qu'il a lu dans les +données. Puis il **balaie tout le jour** pour ce que les détecteurs n'ont pas vu (`plages.py`, `ensemble.py`, comme le dit +`lire-les-donnees`). Son analyse dit, pour chaque étiquette, si un détecteur l'avait vue. + +### L'agent + +`.claude/agents/labeler.md`, sur Sonnet. Il reprend de l'analyste (`~/Diagnostic-App/.claude/agents/analyste.md`) ce +qui fait une étiquette juste : ce qu'est une anomalie (`corr_x`, `corr_y` qui bougent ou manquent ; le thermique +toujours), ce qu'il lit (`familles.md` et `regles-d-etiquetage.md` en entier, la carte par son sommaire et ses sections 2 +à 4, `connaissances/` au besoin), les précédents (`python3 precedents.py "" --exclure +`), les étiquettes déjà dans `auto/.jsonl` sur le jour (elles restent ; il ne refait pas une étiquette +juste ; un événement commencé la veille se prolonge). + +Ce qui le rend léger, face à l'analyste : pas de rapport ; les fiches de la carte seulement pour les phénomènes +rencontrés ; un budget d'images (quelques-unes par station, pour trancher une famille) ; les outils de +`lire-les-donnees` sans scripts à lui. + +Il rend, dans son dossier : +- `etiquettes.jsonl` : au format de l'expert (`debut`, `fin`, `categorie`, `description`) ; `controle.py` sur ce fichier + doit dire 0 erreur ; +- `analyse.md` : par étiquette, le phénomène de la carte, les précédents utiles, la famille et pourquoi, ce qui est + mesuré, vu par un détecteur ou non, la confiance ; ce qu'il a laissé sans étiquette ; ce qui lui a manqué dans la + documentation. + +### Le dossier d'un lot + +`auto/lots///` : `detecteurs.md` (les événements des détecteurs), `etiquettes.jsonl`, `analyse.md`, +`travail/` (figures et sorties des outils) et `seance.jsonl` (le flux `stream-json`, avec son coût), ces deux derniers hors +de git. + +### Le versement + +`labeler.py`, pas l'agent, verse : après `controle.py` à 0 erreur sur le fichier proposé, il réécrit +`auto/.jsonl` comme le fait `verser()` de Diagnostic-App (`app/serveur/analyse.py`) : les autres lignes telles +quelles, celles de ce lot (`"lot": ""`) remplacées par les nouvelles, avec `"source": "labeler"` et `"lot"`, les ids +par `ids.attribuer`, et l'écriture par un fichier provisoire puis `os.replace`. Reverser un lot le remplace donc, sans +doublon. L'agent n'écrit jamais dans `auto/.jsonl` ni dans `manual/`. *(Mon choix ; ponytail : le verrou de +Diagnostic-App ne vaut que dans son serveur ; un versement de l'app à la même seconde sur la même station peut se perdre. +Un verrou de fichier partagé si cela arrive.)* + +**Le bord du lot** (`regles-d-etiquetage.md` : un événement qui touche le bord prolonge l'étiquette du lot voisin) : le +labeler peut prolonger une étiquette de la veille seulement si elle est à lui et non relue ; il la donne dans son +`etiquettes.jsonl` avec son `id`, et `labeler.py` remplace sa `fin`. Une étiquette voisine de l'expert, de l'analyste ou +relue ne se touche pas : la sienne commence au bord du lot et son analyse le dit. *(Mon choix.)* + +### Écarter ses étiquettes non relues + +Une étiquette `"source": "labeler"` sans `revue` n'est pas une vérité. Une fois relue (`revue` posée), elle compte comme +toute étiquette relue. +- **`detectors`, `skills/wf-improve/scripts/score.py`, `read_labels`** : la fonction par laquelle passent `score.py`, + `regression.py` et `wf-improve` ; elle laisse de côté ces étiquettes. Un commit dans le dépôt partagé `~/detectors` : + Diagnostic-App et Optimizer l'ont aussitôt. +- **`controle.py`** : `revue` n'est pas exigée d'une étiquette `"source": "labeler"` ; tout le reste l'est. +- **`precedents.py`** : provenance « labeler, non relue » (ou « labeler, relue le … ») ; ses étiquettes non relues sont + écartées par défaut, `--avec-labeler` pour les voir : le labeler n'apprend pas de ses propres erreurs, l'analyste non + plus. *(Mon choix.)* + +### Les règles + +- Les agents tournent sur l'abonnement Claude, jamais sur une clé d'API : `labeler.py` lance `claude -p` sans + `ANTHROPIC_API_KEY` ni `ANTHROPIC_AUTH_TOKEN` et s'arrête si le message d'ouverture dit `apiKeySource` ≠ `none`, comme + `batch.py` d'Optimizer. +- Toute heure en UTC ; pas de règle propre à une station, une cible ou une date ; lecture seule sur `data/` ; ne jamais + recopier les identifiants des métriques. + +### La séance + +Comme l'analyste : `claude -p "" --agent labeler --output-format stream-json --verbose --allowedTools +Read,Write,Bash --permission-mode acceptEdits`, avec `--add-dir` sur la cible réelle de chaque lien (`data`, `detectors`, +`agent-tools`), lancée depuis `~/labeling`. La demande donne la station, le jour, le dossier du lot. + +### Les liens + +Hors de git (`.gitignore`), comme dans Optimizer : +`data -> ~/aimsight-data/data`, `detectors -> ~/detectors`, et, pour les outils de lecture, `agent-tools -> +~/Diagnostic-App/agent-tools`, `.claude/skills/lire-les-donnees -> ~/Diagnostic-App/.claude/skills/lire-les-donnees`, +`.venv -> ~/Diagnostic-App/.venv`. Le skill cite `labeling/connaissances/…` : le labeler lance tout depuis `~/labeling`, +d'où ces chemins se lisent par `connaissances/…` (son agent le dit). + +## Laissé au constructeur + +- Le texte de `labeler.md`, dans l'esprit de l'analyste et du scanner. +- Comment `labeler.py` tire les événements de `categories.events` (reprendre la logique de `batch.py`, `etiquettes()`, + sans importer d'Optimizer). +- Le budget exact d'images et la façon de le faire tenir. +- La vérification : un lot réel sur une ou deux stations, `controle.py`, puis + `regression.py --labels labeling/auto --data data` inchangé avant et après le versement.