17 KiB
Le labeler : plan de construction
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal : un agent labeler qui étiquette un jour UTC station par station, à faible effort, et verse ses étiquettes
dans auto/<STATION>.jsonl avec "source": "labeler", écartées de la vérité tant qu'elles ne sont pas relues.
Architecture : labeler.py (bibliothèque standard) tire les événements des détecteurs du jour, lance
claude -p --agent labeler par station, contrôle puis verse ses étiquettes. Trois garde-fous lisent le champ source :
controle.py, precedents.py, et score.read_labels dans le dépôt ~/detectors.
Tech Stack : Python 3, bibliothèque standard ; Claude Code (claude -p) sur l'abonnement ; les outils de lecture de
Diagnostic-App par des liens.
Spec : docs/superpowers/specs/2026-11-14-labeler-design.md
Global Constraints
- Bibliothèque standard pour
labeler.py; matplotlib et PIL seulement par.venv/bin/python(les outils de lecture). claude -psansANTHROPIC_API_KEYniANTHROPIC_AUTH_TOKEN; arrêt siapiKeySource≠none.- Toute heure en UTC, format
AAAA-MM-JJTHH:MMZ. - Une étiquette
"source": "labeler"sansrevuen'est pas une vérité ; avecrevue, elle compte comme les autres. - Le labeler n'écrit jamais dans
manual/; ne modifie jamais une étiquette relue, de l'expert ou d'une analyse. - Pas de règle propre à une station, une cible ou une date ; lecture seule sur
data/. - Commits par chemin, jamais
git add -A; langue : français (le dépôtdetectorsen anglais). - Pas de test framework : chaque script garde son contrôle
--checkàassert(commeprecedents.py --check).
Review Focus
- Reverser un lot (relancer après un plantage, ou après avoir supprimé le dossier) : les étiquettes du lot sont
remplacées, jamais doublées ; une étiquette du lot relue entre-temps reste. → Tâche 4,
check(). - Une prolongation qui vise une étiquette interdite (relue, d'une analyse, id inconnu) : refusée avec un message,
rien n'est versé pour la station. → Tâche 4,
check(). - Une station sans mesure ce jour-là : sautée et nommée, pas de séance
claude. → Tâche 4,check()sura_des_mesures. - Un fichier
auto/<STATION>.jsonlabsent (station nouvelle) : le versement le crée. → Tâche 4,check(). controle.pyrouge sur le fichier proposé : rien n'est versé, le lot n'est pas marqué fait, le message le dit. → Tâche 4,main(vérifié à la tâche 5).
Tâche 1 : controle.py n'exige pas revue d'une étiquette du labeler
Files :
- Modify :
controle.py:41(la lignemanque = …) et sa docstring (« étiquette sansrevue», ajouter « sauf"source": "labeler"»)
Interfaces :
-
Produit : la règle «
revueexigée sauf sie.get("source") == "labeler"», dont dépend le versement (tâche 4). -
Étape 1 : écrire le contrôle qui échoue
T=$(mktemp -d) && mkdir $T/auto && cp controle.py $T/ && cat > $T/auto/X.jsonl <<'EOF'
{"id": "X-1", "debut": "2026-11-12T01:00Z", "fin": "2026-11-12T02:00Z", "categorie": "Visibility", "description": "a", "source": "labeler", "lot": "2026-11-12"}
{"id": "X-2", "debut": "2026-11-12T03:00Z", "fin": "2026-11-12T04:00Z", "categorie": "Visibility", "description": "b"}
EOF
python3 $T/controle.py X | head -2
- Étape 2 : l'exécuter. Attendu aujourd'hui :
2 erreurs(X#1 et X#2 sansrevue). - Étape 3 : changer la ligne
manque:{"revue", "id"}devient{"id"} | (set() if e.get("source") == "labeler" else {"revue"}). - Étape 4 : relancer. Attendu :
1 erreurs,X#2 champ manquant : ['revue']seulement. Puispython3 controle.py | head -1: toujours18 erreurs. - Étape 5 : commit
git commit -m "controle.py : revue non exigée d'une étiquette du labeler" -- controle.py
Tâche 2 : precedents.py écarte par défaut les étiquettes du labeler non relues
precedents.py, README.md et .gitignore ne sont pas encore commités (le RAG, travail en cours de l'utilisateur) :
le commit de cette tâche les ajoute en entier. Le dire à l'utilisateur avant de commiter.
Files :
- Modify :
precedents.py(provenance,chercher,check,main, docstring)
Interfaces :
-
Produit :
provenance(source: str, e: dict) -> strrend"labeler, non relue (lot <lot>)"ou"labeler, relue le <revue>"quande.get("source") == "labeler";chercher(requete, toutes, vecteurs, q, k=8, famille=None, exclure=None, avec_labeler=False); option CLI--avec-labeler. -
Étape 1 : ajouter à
check()
assert provenance("auto", {"source": "labeler", "lot": "2026-11-12"}) == "labeler, non relue (lot 2026-11-12)"
assert provenance("auto", {"source": "labeler", "revue": "2026-11-13"}) == "labeler, relue le 2026-11-13"
c = {**e, "station": "U", "categorie": "C", "description": "c", "source": "labeler"}
vec[cle(texte(c))] = [0.0, 1.0]
assert [x["categorie"] for _, x in chercher("", [a, b, c], vec, [0.0, 1.0])] == ["B", "A"]
assert [x["categorie"] for _, x in chercher("", [a, b, c], vec, [0.0, 1.0], avec_labeler=True)] == ["C", "B", "A"]
assert [x["categorie"] for _, x in chercher("", [a, b, {**c, "revue": "2026-11-13"}], vec, [0.0, 1.0])][0] == "C"
- Étape 2 :
python3 precedents.py --check→ échoue (AssertionErrorouTypeErrorsuravec_labeler). - Étape 3 : implémenter :
provenancetestesource == "labeler"avantrevue;chercherécartee.get("source") == "labeler" and not e.get("revue")saufavec_labeler;--avec-labelerpassé parmain; une ligne dans la docstring. - Étape 4 :
python3 precedents.py --check→ok. - Étape 5 : commit
git commit -m "precedents.py : le RAG des étiquettes ; celles du labeler non relues écartées par défaut" -- precedents.py README.md .gitignore
Tâche 3 : detectors, score.read_labels écarte les étiquettes du labeler non relues
Dans le dépôt ~/detectors (partagé ; en anglais ; branche courante main). read_labels est la seule entrée de
score.py et regression.py.
Files :
- Modify :
~/detectors/skills/wf-improve/scripts/score.py:44-50(read_labels, sa docstring) - Modify :
~/detectors/CLAUDE.md(une ligne : les étiquettes"source": "labeler"sansrevuene comptent pas)
Interfaces :
-
Produit :
read_labels(path, start=None, end=None) -> list[dict]sans les lignessource == "labeler"sansrevue. -
Étape 1 : écrire le contrôle qui échoue
cd ~/detectors && T=$(mktemp) && printf '%s\n' \
'{"debut": "2026-11-12T01:00Z", "fin": "2026-11-12T02:00Z", "categorie": "Visibility", "description": "a", "source": "labeler"}' \
'{"debut": "2026-11-12T01:00Z", "fin": "2026-11-12T02:00Z", "categorie": "Visibility", "description": "b", "source": "labeler", "revue": "2026-11-13"}' \
'{"debut": "2026-11-12T01:00Z", "fin": "2026-11-12T02:00Z", "categorie": "Visibility", "description": "c"}' > $T && \
python3 -c "import sys; sys.path.insert(0, 'skills/wf-improve/scripts'); import score; print(sorted(e['description'] for e in score.read_labels('$T')))"
- Étape 2 : l'exécuter. Attendu aujourd'hui :
['a', 'b', 'c']. - Étape 3 : ajouter la condition au filtre de
read_labels; une ligne dansCLAUDE.md. - Étape 4 : relancer →
['b', 'c']. - Étape 5 : commit dans
~/detectors:git commit -m "score.read_labels: skip unreviewed labeler labels (source labeler, no revue)" -- skills/wf-improve/scripts/score.py CLAUDE.md
Tâche 4 : labeler.py, le lot sans l'agent
Files :
- Create :
labeler.py - Modify :
.gitignore(data,detectors,agent-tools,.venv,.claude/skills/lire-les-donnees,auto/lots/*/*/travail/,auto/lots/*/*/seance.jsonl) - Liens (hors de git) :
data -> ~/aimsight-data/data,detectors -> ~/detectors,agent-tools -> ~/Diagnostic-App/agent-tools,.venv -> ~/Diagnostic-App/.venv,.claude/skills/lire-les-donnees -> ~/Diagnostic-App/.claude/skills/lire-les-donnees
Interfaces :
-
Consomme :
ids.attribuer(station, etiquettes, retires=()) -> int;controle.py <fichier.jsonl>(code de sortie 0 = sans erreur) ;detectors/scripts:categories.events(mesures, fin, dossier),data.load(dossier),data.iso. -
Produit :
evenements(station: str, mesures: dict, d: datetime) -> list[dict]: les étiquettes des détecteurs coupées au jour, reprises de~/Optimizer/batch.py,etiquettes()(copie, pas d'import d'Optimizer) ;a_des_mesures(mesures: dict, d: datetime) -> bool: au moins une mesure dans[d, d+1j);resume_detecteurs(station: str, jour: str, evs: list[dict]) -> str:detecteurs.md, une ligne par événement (D<n> HH:MM → HH:MM famille : texte), « aucune étiquette des détecteurs » sinon ;verser(fichier: Path, station: str, jour: str, proposees: list[dict]) -> int: réécritfichier(le crée s'il manque) ; garde les lignes telles quelles, sauf cellessource == "labeler",lot == jour, sansrevue, qui sont remplacées par les proposées sansid(+"source": "labeler","lot": jour) ; une proposée avecidprolonge : si cet id est dans le fichier,source == "labeler"et sansrevue, safindevient celle de la proposée, sinonValueError("prolongation refusée : <id> …")et rien n'est écrit ; ids parids.attribuer, avec les ids des lignes remplacées enretires(un id ne se redonne pas) ; écriture par<fichier>.tmppuisos.replace; rend le nombre d'étiquettes ajoutées ou prolongées ;lire(chemin: Path) -> list[dict]: les lignes JSON d'un fichier,[]s'il manque ;claude(dossier: Path, args: list[str]) -> dict | None: repris de~/Optimizer/batch.py,claude(), flux dans<dossier>/seance.jsonl, rend la ligneresult;--check: lesassertci-dessous, sansclaudeni données.
-
Étape 1 : écrire
check()(les cas du Review Focus 1, 2, 4 et 3)
def check():
with tempfile.TemporaryDirectory() as t:
f = Path(t) / "X.jsonl"
e = lambda d, **k: {"debut": f"2026-11-12T0{d}:00Z", "fin": f"2026-11-12T0{d + 1}:00Z", "categorie": "Visibility", "description": f"d{d}", **k}
assert verser(f, "X", "2026-11-12", [e(1), e(3)]) == 2 # fichier absent : créé
es = lire(f)
assert [x["id"] for x in es] == ["X-1", "X-2"] and all(x["source"] == "labeler" and x["lot"] == "2026-11-12" for x in es)
assert verser(f, "X", "2026-11-12", [e(5)]) == 1 # reverser : remplacé, pas doublé
assert [(x["id"], x["description"]) for x in lire(f)] == [("X-3", "d5")]
f.write_text("".join(json.dumps(x) + "\n" for x in [
{"id": "X-7", **e(1), "source": "labeler", "lot": "2026-11-11"},
{"id": "X-8", **e(2), "source": "labeler", "lot": "2026-11-12", "revue": "2026-11-13"},
{"id": "X-9", **e(4), "analyse": "A"}]))
assert verser(f, "X", "2026-11-12", [{**e(1), "id": "X-7", "fin": "2026-11-12T05:00Z"}, e(6)]) == 2
es = {x["id"]: x for x in lire(f)}
assert es["X-7"]["fin"] == "2026-11-12T05:00Z" and "X-8" in es and "X-10" in es # prolongée ; relue gardée
for interdit in ("X-8", "X-9", "X-99"): # relue, analyse, inconnue
avant = f.read_text()
try:
verser(f, "X", "2026-11-12", [{**e(1), "id": interdit}]); assert False
except ValueError:
assert f.read_text() == avant
d = datetime(2026, 11, 12, tzinfo=timezone.utc)
assert a_des_mesures({"A": [{"t": d + timedelta(hours=3)}]}, d)
assert not a_des_mesures({"A": [{"t": d - timedelta(hours=1)}, {"t": d + timedelta(days=1)}]}, d)
print("ok")
- Étape 2 :
python3 labeler.py --check→ échoue (labeler.pyn'existe pas, puisNameError). - Étape 3 : les liens, le
.gitignore, puislabeler.py: docstring (usage, sorties), les fonctions de l'Interface, etmain:- arguments
--jour AAAA-MM-JJ(défaut : hier UTC),--stations A,B(défaut : les dossiers dedata/),--check; - par station :
dossier = auto/lots/<jour>/<STATION>/; fait sidossier/travail/versees.jsonlexiste → sautée ; sans mesure ce jour-là → sautée et nommée à la fin ; sinondetecteurs.md, puisclaude(dossier, [demande, "--agent", "labeler", "--allowedTools", "Read,Write,Bash", *add_dir])(--add-dirsur la cible résolue dedata,detectors,agent-tools) ; la demande donne station, jour, dossier ; - après la séance : sans
etiquettes.jsonl→ message, station suivante ;python3 controle.py <dossier>/etiquettes.jsonlen sous-processus ; code ≠ 0 → sa sortie imprimée, rien versé ; sinonverser, copie deetiquettes.jsonldanstravail/versees.jsonl, une ligneSTATION : n étiquettes versées, coût.
- arguments
- Étape 4 :
python3 labeler.py --check→ok. - Étape 5 : les détecteurs sans l'agent :
python3 -cqui importelabeler, chargedata/NORDENDet imprimeresume_detecteurs("NORDEND", "2026-11-06", evenements(…)). Attendu : les mêmes heures et familles que~/Optimizer/batches/2026-11-06/detecteurs/NORDEND.jsonl(lecture seule, Optimizer est en cours de travail). - Étape 6 : commit
git commit -m "labeler.py : le lot du labeler, détecteurs, séance et versement" -- labeler.py .gitignore
Tâche 5 : l'agent labeler, et un lot réel
Files :
- Create :
.claude/agents/labeler.md - Modify :
CLAUDE.md(le labeler, le lot, les liens),README.md(une lignelabeler.py,auto/lots/)
Interfaces :
-
Consomme :
labeler.py(tâche 4) ; ce qu'il donne à l'agent :auto/lots/<jour>/<STATION>/detecteurs.md, la station, le jour ; ce qu'il attend :etiquettes.jsonl,analyse.mddans ce dossier. -
Étape 1 : écrire
.claude/agents/labeler.md: frontmattername: labeler,tools: Read, Write, Bash,model: sonnet,omitClaudeMd: true, unedescriptiond'une phrase. Corps, dans l'esprit de~/Diagnostic-App/.claude/agents/analyste.md(le reprendre, l'alléger), en français :- qui il est : l'étiqueteur large et léger ; ses étiquettes ne sont pas relues ; mieux vaut une étiquette sûre ;
- ce qu'est une anomalie (repris tel quel de l'analyste) ;
- ce qu'il lit :
familles.mdetregles-d-etiquetage.mden entier,carte-des-etiquettes.mdsommaire et sections 2 à 4, puis les fiches des phénomènes rencontrés seulement ;connaissances/chaine-de-mesure.md,colonnes-des-deplacements.md,les-trous.md;.claude/skills/lire-les-donnees/SKILL.md(ses cheminslabeling/…se lisent ici sans le préfixelabeling/) ;auto/<STATION>.jsonlsur le jour et la veille ; rien demanual/en direct, ni le code des détecteurs ; - les détecteurs :
detecteurs.mddit où regarder, jamais une preuve ; puis balayer tout le jour (plages.py,ensemble.py) pour ce qu'ils n'ont pas vu ; - les précédents :
python3 precedents.py "<ce qu'il voit>" --exclure <STATION> <jour>T00:00Z <jour+1>T00:00Z; - léger : pas de rapport, pas de script à lui,
--sortie <dossier>/travail, cinq images au plus ; - le bord : prolonger une étiquette de la veille seulement si elle est à lui (
"source": "labeler") et sansrevue, en la redonnant avec sonid; sinon commencer au bord et le dire dans l'analyse ; - ce qu'il rend :
etiquettes.jsonl(format de l'expert),controle.pydessus à 0 erreur ;analyse.mdau plan : par étiquette (phénomène de la carte, précédents utiles, famille et pourquoi, mesuré, vu par un détecteur : ouiD<n>| non, confiance), ce qu'il a laissé sans étiquette, ce qui lui a manqué dans la documentation ; - il ne touche jamais
auto/<STATION>.jsonlnimanual/; réponse finale en une ligne : le nombre d'étiquettes.
-
Étape 2 : le benchmark avant :
python3 detectors/skills/wf-improve/scripts/regression.py --labels auto --data data > $SCRATCH/avant.txt(~3 min). -
Étape 3 : un lot réel sur une station et un jour qui ont des étiquettes de l'expert ou d'une analyse (ex.
python3 labeler.py --jour 2026-11-05 --stations NORDEND, la plage de l'analyseNORDEND_2026-11-04T2112_2026-11-07T1412). Attendu : la séance tourne sur l'abonnement,analyse.mdetetiquettes.jsonldansauto/lots/2026-11-05/NORDEND/, versées avecsourceetlot,python3 controle.pytoujours à 18 erreurs,git diff auto/NORDEND.jsonlne montre que des lignes ajoutées. -
Étape 4 : relancer la même commande → la station est sautée (lot fait). Supprimer
auto/lots/2026-11-05/NORDEND/travail/versees.jsonlet relancer → les étiquettes du lot sont remplacées, pas doublées. -
Étape 5 :
python3 precedents.py "<une description du lot>"ne rend pas ses étiquettes ;--avec-labelerles rend. Le benchmark après, même commande vers$SCRATCH/apres.txt:diffvide. -
Étape 6 : lire
analyse.mdface aux étiquettes de l'analyse sur ce jour ; ajusterlabeler.mdsi une consigne a manqué (une passe, pas une campagne). -
Étape 7 : commit
git commit -m "L'agent labeler et son premier lot (NORDEND, 2026-11-05)" -- .claude/agents/labeler.md CLAUDE.md README.md auto/lots/2026-11-05/NORDEND auto/NORDEND.jsonl