diff --git a/docs/superpowers/plans/2026-11-14-labeler.md b/docs/superpowers/plans/2026-11-14-labeler.md new file mode 100644 index 0000000..255971c --- /dev/null +++ b/docs/superpowers/plans/2026-11-14-labeler.md @@ -0,0 +1,257 @@ +# 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/.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/.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** + +```bash +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 )"` ou + `"labeler, relue le "` 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()`** + +```python + 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** + +```bash +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 ` (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 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 : …")` 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 `.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 + `/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) + +```python +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///` ; 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 /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///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/.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 "" --exclure T00:00Z T00:00Z` ; + - léger : pas de rapport, pas de script à lui, `--sortie /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` | non, confiance), ce qu'il a laissé sans étiquette, ce qui lui a manqué dans la documentation ; + - il ne touche jamais `auto/.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 ""` 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`