154 lines
9.6 KiB
Markdown
154 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.
|