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