Files
aimsight-labeling/docs/archive/2026-11-14-labeler.md
T

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 -p sans ANTHROPIC_API_KEY ni ANTHROPIC_AUTH_TOKEN ; arrêt si apiKeySource ≠ none.
  • Toute heure en UTC, format AAAA-MM-JJTHH:MMZ.
  • Une étiquette "source": "labeler" sans revue n'est pas une vérité ; avec revue, 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ôt detectors en anglais).
  • Pas de test framework : chaque script garde son contrôle --check à assert (comme precedents.py --check).

Review Focus

  1. 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().
  2. 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().
  3. Une station sans mesure ce jour-là : sautée et nommée, pas de séance claude. → Tâche 4, check() sur a_des_mesures.
  4. Un fichier auto/<STATION>.jsonl absent (station nouvelle) : le versement le crée. → Tâche 4, check().
  5. controle.py rouge 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 ligne manque = …) et sa docstring (« étiquette sans revue », ajouter « sauf "source": "labeler" »)

Interfaces :

  • Produit : la règle « revue exigée sauf si e.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 sans revue).
  • É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. Puis python3 controle.py | head -1 : toujours 18 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) -> str rend "labeler, non relue (lot <lot>)" ou "labeler, relue le <revue>" quand e.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 (AssertionError ou TypeError sur avec_labeler).
  • Étape 3 : implémenter : provenance teste source == "labeler" avant revue ; chercher écarte e.get("source") == "labeler" and not e.get("revue") sauf avec_labeler ; --avec-labeler passé par main ; 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" sans revue ne comptent pas)

Interfaces :

  • Produit : read_labels(path, start=None, end=None) -> list[dict] sans les lignes source == "labeler" sans revue.

  • É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 dans CLAUDE.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éécrit fichier (le crée s'il manque) ; garde les lignes telles quelles, sauf celles source == "labeler", lot == jour, sans revue, qui sont remplacées par les proposées sans id (+ "source": "labeler", "lot": jour) ; une proposée avec id prolonge : si cet id est dans le fichier, source == "labeler" et sans revue, sa fin devient celle de la proposée, sinon ValueError("prolongation refusée : <id> …") et rien n'est écrit ; ids par ids.attribuer, avec les ids des lignes remplacées en retires (un id ne se redonne pas) ; écriture par <fichier>.tmp puis os.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 ligne result ;
    • --check : les assert ci-dessous, sans claude ni 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.py n'existe pas, puis NameError).
  • Étape 3 : les liens, le .gitignore, puis labeler.py : docstring (usage, sorties), les fonctions de l'Interface, et main :
    • arguments --jour AAAA-MM-JJ (défaut : hier UTC), --stations A,B (défaut : les dossiers de data/), --check ;
    • par station : dossier = auto/lots/<jour>/<STATION>/ ; fait si dossier/travail/versees.jsonl existe → sautée ; sans mesure ce jour-là → sautée et nommée à la fin ; sinon detecteurs.md, puis claude(dossier, [demande, "--agent", "labeler", "--allowedTools", "Read,Write,Bash", *add_dir]) (--add-dir sur la cible résolue de data, 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.jsonl en sous-processus ; code ≠ 0 → sa sortie imprimée, rien versé ; sinon verser, copie de etiquettes.jsonl dans travail/versees.jsonl, une ligne STATION : n étiquettes versées, coût.
  • Étape 4 : python3 labeler.py --check → ok.
  • Étape 5 : les détecteurs sans l'agent : python3 -c qui importe labeler, charge data/NORDEND et imprime resume_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 ligne labeler.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.md dans ce dossier.

  • Étape 1 : écrire .claude/agents/labeler.md : frontmatter name: labeler, tools: Read, Write, Bash, model: sonnet, omitClaudeMd: true, une description d'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.md et regles-d-etiquetage.md en entier, carte-des-etiquettes.md sommaire 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 chemins labeling/… se lisent ici sans le préfixe labeling/) ; auto/<STATION>.jsonl sur le jour et la veille ; rien de manual/ en direct, ni le code des détecteurs ;
    • les détecteurs : detecteurs.md dit 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 sans revue, en la redonnant avec son id ; sinon commencer au bord et le dire dans l'analyse ;
    • ce qu'il rend : etiquettes.jsonl (format de l'expert), controle.py dessus à 0 erreur ; analyse.md au plan : par étiquette (phénomène de la carte, précédents utiles, famille et pourquoi, mesuré, vu par un détecteur : oui D<n> | non, confiance), ce qu'il a laissé sans étiquette, ce qui lui a manqué dans la documentation ;
    • il ne touche jamais auto/<STATION>.jsonl ni manual/ ; 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'analyse NORDEND_2026-11-04T2112_2026-11-07T1412). Attendu : la séance tourne sur l'abonnement, analyse.md et etiquettes.jsonl dans auto/lots/2026-11-05/NORDEND/, versées avec source et lot, python3 controle.py toujours à 18 erreurs, git diff auto/NORDEND.jsonl ne 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.jsonl et 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-labeler les rend. Le benchmark après, même commande vers $SCRATCH/apres.txt : diff vide.

  • Étape 6 : lire analyse.md face aux étiquettes de l'analyse sur ce jour ; ajuster labeler.md si 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