Files
aimsight-labeling/docs/superpowers/specs/2026-11-14-labeler-design.md
T

155 lines
9.6 KiB
Markdown

# 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/<STATION>.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 "<ce qu'il voit>" --exclure <STATION> <jour>
<jour+1>`), les étiquettes déjà dans `auto/<STATION>.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/<jour>/<STATION>/` : `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/<STATION>.jsonl` comme le fait `verser()` de Diagnostic-App (`app/serveur/analyse.py`) : les autres lignes telles
quelles, celles de ce lot (`"lot": "<jour>"`) 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/<STATION>.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 "<demande>" --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.