- Every station's auto labels reviewed by an analyst (/review-auto-labels), then a cross-review per family across all stations (new skill /cross-review-labels), a finishing pass, and descriptions rewritten in words (no numeric values). - The three never-labeled ranges (WILDSTRUBEL 07/09-01/10, NORDEND 16/08-01/10) labeled and reviewed: 991 auto labels on 11 stations, labeling/controle.py at 0 errors. - Labeling knowledge gathered in labeling/: regles-d-etiquetage.md (new), familles.md (settled boundaries), connaissances/ (notes moved from docs/, links updated), the label map rebuilt from reviewed labels, events and cases; events tied to their stations (PS_DES_COUDRES is JUNGFRAU). The labeler and reviewers read only labeling/. - labels-map reads auto labels and events; decision D-130; living plan points 73-75. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
234 lines
18 KiB
Markdown
234 lines
18 KiB
Markdown
# Enquête à la demande : un agent qui explique un événement de mesure
|
||
|
||
- **Date** : 2026-10-13.
|
||
- **Statut** : exploratoire. Rien n'est construit ; ce document fixe une direction et un démarrage par étapes. Décision liée : D-042 (`docs/decisions.md`).
|
||
- **Place** : une approche **auxiliaire** du rapport `docs/agents/rapport-exploratoire.md` (D-027), plus simple, qui ne le remplace pas. Les deux partagent le même cadre (§3).
|
||
- **Principe de travail** : commencer simple, ne complexifier que si le besoin apparaît.
|
||
|
||
---
|
||
|
||
## 1. Objet
|
||
|
||
Le diagnostic actuel porte sur les **états** de la caméra (batterie, disque, 4G, température). Le cas d'usage suivant porte sur les **données qu'elle mesure** : positions et déplacements des cibles, état de la compensation, qualité des références. On monte d'un cran : il faut départager un mouvement réel de l'ouvrage d'un artefact de mesure.
|
||
|
||
**Le problème.** Le client voit toutes les données mais ne sait pas les interpréter. Lors d'un événement sur le terrain, il ne peut pas dire s'il est problématique ou anodin. Aucune méthode n'aide à ce diagnostic : il contacte le support, qui enquête à la main.
|
||
|
||
**Le but.** Répondre au client automatiquement, avec preuves et explications, pour qu'il n'ait plus à solliciter le support.
|
||
|
||
**Le moyen.** Quand un événement pose question, un agent (Claude, via l'API d'Anthropic) reçoit la question et enquête avec un harnais : connaissance métier, outils en lecture, cas résolus. Il rend un diagnostic dont chaque preuve est traçable.
|
||
|
||
### Ce qui distingue cette approche du rapport exploratoire
|
||
|
||
| | Rapport exploratoire (D-027) | Enquête à la demande (ce document) |
|
||
|---|---|---|
|
||
| Déclenchement | Chaque jour, pour chaque station | Un événement qui pose question |
|
||
| Unité de travail | Une session par (agent, station, jour) | Une session par question |
|
||
| Rôle de l'agent | Annoter la couleur du jour, capter l'inconnu | Expliquer un événement précis |
|
||
| Données | États de la station (Energy d'abord) | Données de mesure (déplacements), plus les états en contexte |
|
||
| Infrastructure | Cron, SQL, flotte entière | Un script lancé à la main au départ |
|
||
|
||
Les docs AIMsight décrivent déjà ce processus : le *support query workflow* (§13 de `AIMsight_agentic_support_project_context.md`) et l'*explainer* d'événements (§4 de `AIMsight_reference_quality_event_explainer_roadmap.md`). La différence : l'agent mène l'enquête lui-même au lieu d'expliquer un dossier préparé d'avance.
|
||
|
||
---
|
||
|
||
## 2. Choix retenus
|
||
|
||
| Question | Choix | Raison |
|
||
|---|---|---|
|
||
| Qui reçoit le diagnostic | Le **support d'abord** (il relit, corrige et envoie), puis **le client directement** pour les classes sans enjeu pour l'ouvrage | Asymétrie du risque : dire « anodin » à tort est plus grave qu'une fausse alerte (§5) |
|
||
| Qui déclenche l'enquête | Le **support à la main**, puis un **bouton client** sur le site, puis une **détection automatique** | Tester sur de vrais tickets sans toucher au site ; les critères automatiques viendront des tickets, pas d'un seuil inventé |
|
||
| Forme de l'agent | Un **enquêteur avec des outils typés** (approche 2, §8) | Il creuse ce qui est utile, et chaque preuve renvoie à un appel d'outil |
|
||
| Sources de données | **Pas encore connues** (CSV, HDF5, images, SQL) : les outils sont définis par **famille de preuves**, pas par format | Comme l'API indépendante de l'estimateur de la roadmap (§10) |
|
||
| Cadre technique | Celui de D-027 : harnais maison, *Tool Runner* du SDK `anthropic`, agent en dossier déclaratif | Un seul cadre pour les deux approches |
|
||
| Modèle | Opus 5.5 (`claude-opus-5-5`), niveau d'effort fixé explicitement (son défaut est `medium`) | À mesurer sur les premiers rejeux |
|
||
|
||
---
|
||
|
||
## 3. Le harnais
|
||
|
||
L'agent est un dossier déclaratif, comme prévu par D-027 (emplacement proposé : `agents/enquete/agent.md`). Il a trois pièces.
|
||
|
||
### 3.1 La connaissance (prompt système, mis en cache)
|
||
|
||
- **Les règles communes** : vocabulaire `confirmed` / `strongly supported` / `consistent with` / `possible` / `insufficient evidence` / `not observed` ; fait observé ≠ fait dérivé ≠ hypothèse ; aucun seuil inventé ; rien construit sur `inlier` binaire ; `sigma0` jamais suffisant seul ; mode commun ≠ mouvement structurel (règles de `CLAUDE.md`).
|
||
- **La méthode**, par sections ciblées des docs AIMsight, pas les fichiers entiers :
|
||
- la chaîne de dépendance (§4 du contexte support) ;
|
||
- les familles d'hypothèses (§12) ;
|
||
- les classifications de l'*explainer* (§4.3 de la roadmap) ;
|
||
- le *workflow* en 8 étapes (§13).
|
||
- **Des pointeurs vers `docs/`**, qui reste la seule source : `labeling/connaissances/colonnes-des-deplacements.md`, puis les notes de domaine à venir.
|
||
- **Volume** : de l'ordre de 30 à 60 k tokens, à mesurer. Mis en cache, ce bloc est relu à chaque tour pour 0,20 $ par million de tokens.
|
||
|
||
### 3.2 Les outils (lecture seule)
|
||
|
||
On commence petit. Chaque outil répond « source indisponible » quand la donnée manque ; l'agent le reporte dans ses inconnus au lieu de conclure. Les outils de calcul renvoient des **valeurs**, pas des verdicts : un seuil de décision ne s'invente pas (§9).
|
||
|
||
| Outil | Rôle |
|
||
|---|---|
|
||
| `inventory(station, fenêtre)` | Ce qui existe : points, références, colonnes, sources, trous de mesure (étape 3 du *workflow*) |
|
||
| `get_series(station, colonnes, fenêtre)` | Un résumé chiffré compact et un graphique en image. Un LLM lit mal des centaines de lignes de nombres, il lit bien un graphique |
|
||
| `compare_before_after(station, colonnes, instant)` | Par colonne, avant et après l'instant : écart, persistance, retour à la normale (UC5 du contexte support) |
|
||
| `common_mode(station, fenêtre)` | Part des cibles touchées, accord de signe, score de mode commun (famille *Spatial response*, §4.2 de la roadmap) : ce qui sépare l'ouvrage de la compensation |
|
||
| `get_system_health(station, fenêtre)` | Les couleurs du jour **déjà livrées** (Energy, Storage, Cellular, Temperature) : le bas de la chaîne de dépendance, réutilisé tel quel depuis `src/<domaine>/day_color.py` |
|
||
| `get_image(station, instant)` | La photo de la caméra, que l'agent regarde (l'API accepte une image dans un résultat d'outil). Brouillard, neige, végétation, cible masquée : ce qu'aucun script ne voit simplement. Seulement si une source d'images existe |
|
||
| `submit_diagnosis(...)` | La fin obligatoire, au format du §5 |
|
||
|
||
Opus 5.5 refuse qu'on force l'appel d'un outil (`tool_choice` `any` ou `tool`). `submit_diagnosis` est donc appelé sur instruction, avec un schéma strict (`strict: true`).
|
||
|
||
**Volontairement absents** (comme dans D-027) : SQL libre, Bash, accès web, bac à sable de code (§8).
|
||
|
||
### 3.3 La base d'events
|
||
|
||
- **Un fichier par cas résolu** : la question du client, les preuves, le brouillon de l'agent, le diagnostic final validé par le support, l'écart entre les deux. C'est la forme prévue par le contexte support (§13 étape 8, §17).
|
||
- **Au début**, tous les events tiennent dans le prompt, en cache : pas d'outil de recherche. Un outil `find_cases` viendra quand il y en aura trop.
|
||
- **Premier cas** : Barcelone (§15 de la roadmap, §16.1 du contexte support), rédigé d'après les docs comme cas documentaire, sans données.
|
||
- **La base se remplit seule** : une enquête validée par le support devient un event (§5).
|
||
|
||
---
|
||
|
||
## 4. Déroulé d'une enquête
|
||
|
||
### Lancement (déclenchement par le support)
|
||
|
||
```bash
|
||
python3 agents/enquete.py WEISSHORN 2026-10-02T08:00 --points target_06 --question ticket.txt
|
||
```
|
||
|
||
- Le support donne la station, l'instant et les points : plus fiable que de les faire deviner à l'agent dans le texte du client. Le texte du client part tel quel dans le premier message.
|
||
- Le code ajoute la fenêtre par défaut : de quelques jours avant l'événement jusqu'à l'heure de la question.
|
||
- **Borne dans le temps** : l'enquête lit les données **après** l'événement (c'est la seule façon de savoir s'il est revenu à la normale), mais rien après l'heure de la question. Un ticket passé se rejoue donc à l'identique, ce qui permet de juger l'agent.
|
||
|
||
### Les étapes demandées à l'agent (d'après le §13 du contexte support)
|
||
|
||
1. **Inventaire** (`inventory`) : ce qui est disponible, ce qui manque, et ce qui, en manquant, limite le diagnostic.
|
||
2. **Le bas de la chaîne d'abord** (`get_system_health`) : une station coupée ou une liaison tombée explique un trou ou un saut sans que l'ouvrage y soit pour rien.
|
||
3. **Les faits** (`compare_before_after`, `common_mode`, `get_series`, `get_image`) : amplitude, persistance, retour à la normale, nombre de cibles touchées.
|
||
4. **Les hypothèses candidates**, prises dans les familles du §12 et classées sur les seules preuves.
|
||
5. **La réfutation de l'hypothèse principale** : chercher la preuve qui la contredirait. Exemple : on pense à un mouvement de l'ouvrage. Les références ont-elles bougé ? La transformation a-t-elle sauté ? Toutes les cibles ont-elles bougé ensemble ? Cette tentative est **obligatoire** et figure dans la sortie.
|
||
6. **`submit_diagnosis`**. « Rien d'anormal » est une conclusion valable.
|
||
|
||
### Garde-fous (tenus par le code, pas par le modèle)
|
||
|
||
- **Journal de session** : chaque appel d'outil est enregistré avec ses entrées et sa sortie, sous un identifiant.
|
||
- **Preuves vérifiées** : chaque preuve du diagnostic cite l'identifiant d'un appel du journal. Le code refuse un diagnostic qui cite un identifiant inexistant, ce qui empêche les faits inventés.
|
||
- **Budget** : un plafond par enquête, en tokens et en appels. S'il est atteint, l'agent conclut avec ce qu'il a (`insufficient evidence` si besoin) plutôt que d'être coupé en plein raisonnement.
|
||
|
||
---
|
||
|
||
## 5. Sortie et relecture
|
||
|
||
### Ce que rend `submit_diagnosis` (d'après §14-15 du contexte support)
|
||
|
||
| Champ | Contenu |
|
||
|---|---|
|
||
| `classification` | Une liste fermée : mouvement de l'ouvrage, événement de compensation (caméra ou références), solution de références faible, parallaxe ou modèle inadapté, cible dégradée, problème système (acquisition, transport), rien d'anormal, indéterminé. Classes du §4.3 de la roadmap, complétées du bas de la chaîne |
|
||
| `affected_layer` | La couche de la chaîne de dépendance |
|
||
| `qualifier` | `confirmed` … `insufficient evidence` |
|
||
| `evidence` | Les faits, chacun avec l'identifiant de l'appel d'outil qui le prouve |
|
||
| `refutation` | Ce qui a été vérifié contre l'hypothèse principale, et le résultat |
|
||
| `alternatives` | Les autres explications, et pourquoi elles ne sont pas écartées |
|
||
| `unknowns` | Les preuves manquantes qui limitent la conclusion |
|
||
| `next_check` | La vérification suivante la plus discriminante |
|
||
| `client_draft` | Un brouillon de réponse au client : court, sans jargon ni mécanisme, comme la vue client |
|
||
|
||
### La règle d'asymétrie (tenue par le code)
|
||
|
||
Le brouillon ne peut dire « sans conséquence pour l'ouvrage » que si :
|
||
- l'explication « artefact » (compensation, cible, système) est au moins `strongly supported` ;
|
||
- **et** le mouvement de l'ouvrage a été réfuté explicitement.
|
||
|
||
Sinon, le code remplace la conclusion du brouillon par une formule neutre (« événement en cours d'analyse par notre support »). La règle sert dès le départ (le support ne recopie pas une fausse assurance) et délimitera plus tard ce qui part directement au client.
|
||
|
||
### La relecture par le support
|
||
|
||
- **Un dossier par enquête** (emplacement proposé : `agents/enquetes/<date>_<station>/`) : le journal des appels, le diagnostic en JSON, une page HTML de relecture (diagnostic, preuves avec leurs graphiques, brouillon client).
|
||
- **Le support relit, corrige le brouillon et l'envoie lui-même**, puis remplit une courte validation : accepté tel quel, ou corrigé (en quoi), et le diagnostic final.
|
||
- **Une enquête validée devient un event** de la base (§3.3), sans autre étape.
|
||
- **Mesures qui décident de la suite** : le taux d'accord entre l'agent et le support (classification, qualificatif, brouillon envoyé tel quel ou réécrit), puis le temps gagné par ticket.
|
||
- **Langue, par défaut** : la partie technique en anglais (termes AIMsight), le brouillon dans la langue du client.
|
||
|
||
---
|
||
|
||
## 6. Démarrage par étapes
|
||
|
||
Deux axes à ne pas confondre : **qui déclenche** (le support, puis le client, puis la détection automatique) et **qui reçoit** (le support, puis le client pour certaines classes). Chaque étape répond à une question, et sa réponse décide si la suivante est nécessaire.
|
||
|
||
1. **Le harnais sur les données existantes.** Cas d'usage UC3 (« pourquoi pas de données entre X et Y ? ») rejoué sur les coupures connues : les 11 coupures de la liaison de NORDEND, les incidents isolés de WEISSHORN. *Question* : la tuyauterie tient-elle (preuves vérifiées, réfutation, page de relecture), et à quel coût ? N'attend pas les données de déplacement.
|
||
2. **Rejeu d'events de déplacement résolus**, dès qu'un export contient un événement expliqué (Barcelone idéalement). On branche `compare_before_after` et `common_mode` sur les CSV. *Question* : l'agent retrouve-t-il le diagnostic de l'expert, sans sur-conclure ?
|
||
3. **Le support s'en sert sur ses vrais tickets.** *Question* : quel taux d'accord, quel temps gagné ?
|
||
4. **Le bouton client sur le site** : la demande arrive au support déjà enquêtée. *Question* : les clients s'en servent-ils, et pour quels événements ?
|
||
5. **Réponse directe au client** pour les classes sans enjeu pour l'ouvrage, si l'accord mesuré le justifie. Ensuite seulement, la **détection automatique**, sur des critères tirés des tickets réels. C'est là que les deux approches se rejoignent : une surveillance quotidienne (D-027) qui repère un événement peut lancer une enquête.
|
||
|
||
---
|
||
|
||
## 7. Coût, risques, prérequis
|
||
|
||
### Coût (hypothèse, à mesurer à l'étape 1)
|
||
|
||
Prix d'Opus 5.5 : 4 $ par million de tokens en entrée, 20 $ en sortie, 0,20 $ en lecture de cache, 5 $ en écriture de cache (1,25 × l'entrée, durée de vie de 5 minutes). Une image de 1280 × 720 coûte environ 1 200 tokens.
|
||
|
||
Hypothèse par enquête : 45 k tokens de connaissance, une dizaine de tours, 50 k tokens nouveaux (résultats d'outils, images), 20 k tokens de sortie (raisonnement compris). Les tickets étant espacés, le cache est **froid** au début de chaque enquête.
|
||
|
||
| Poste | Calcul | Coût |
|
||
|---|---|---|
|
||
| Écriture du cache (connaissance) | 45 k × 5 $/M | 0,23 $ |
|
||
| Écriture du cache (résultats d'outils, images) | 50 k × 5 $/M | 0,25 $ |
|
||
| Lectures du cache | 10 tours × ~60 k × 0,20 $/M | 0,12 $ |
|
||
| Sortie | 20 k × 20 $/M | 0,40 $ |
|
||
| **Par enquête** | | **~1 $ (0,5 à 2 $)** |
|
||
|
||
Le volume suit celui des tickets : le coût n'est pas limitant face au temps d'un ingénieur support.
|
||
|
||
### Risques
|
||
|
||
| Risque | Parade |
|
||
|---|---|
|
||
| Fausse assurance (« anodin » à tort) | Règle d'asymétrie tenue par le code (§5) ; relecture par le support jusqu'à l'étape 5 |
|
||
| Faits inventés | Chaque preuve cite un appel du journal, vérifié par le code (§4) |
|
||
| Sur-conclusion sur des données incomplètes | `inventory` en premier ; `unknowns` obligatoire ; `insufficient evidence` admis |
|
||
| Graphique mal lu | Résumé chiffré à côté de l'image ; calculs déterministes dans les outils |
|
||
| Trop peu de cas pour juger | Rejeu des tickets passés ; chaque enquête validée devient un event |
|
||
| Données client chez Anthropic | Accepté (D-027) ; conditions de conservation à valider avec la direction |
|
||
|
||
### Prérequis
|
||
|
||
- **Étape 1** : une clé API Anthropic (la même que pour D-027).
|
||
- **Étape 2** : un export de déplacements avec un événement connu et son explication.
|
||
- **`get_image`** : une source d'images, peut-être l'API REST de la caméra (attendue pour le dev container, D-038).
|
||
|
||
---
|
||
|
||
## 8. Options écartées
|
||
|
||
| Option | Raison |
|
||
|---|---|
|
||
| **1. Dossier de preuves, puis rédaction** (l'*explainer* de la roadmap, un seul appel au LLM) | L'agent ne peut pas creuser (autre cible, autre période, image) ; le dossier doit tout prévoir d'avance. Il reste le premier message de l'enquête, en version réduite |
|
||
| **3. Enquêteur avec un bac à sable de code** | Calculs non relus, risque de seuils inventés, difficile à auditer devant un client inquiet pour son ouvrage. Reste un recours si l'agent lit mal les séries |
|
||
| Réponse directe au client dès le départ | Le risque de fausse assurance serait d'emblée chez le client |
|
||
| Détection automatique dès le départ | Il faudrait fixer des critères sur les déplacements avant d'avoir vu un seul ticket |
|
||
| L'agent extrait station, instant et points du texte du client | Source d'erreur évitable tant que le support lance l'enquête ; à revoir avec le bouton client, qui fournit ces champs |
|
||
| Recherche d'events (RAG) dès le départ | Inutile tant que les events tiennent dans le prompt |
|
||
|
||
---
|
||
|
||
## 9. Questions ouvertes
|
||
|
||
1. **Sources de données** : lesquelles (CSV, HDF5, images, SQL), et quand ?
|
||
2. **Premier cas avec données** : Barcelone ou un autre événement expliqué ?
|
||
3. **Liste des classifications** : à valider avec l'expert, avec la façon de nommer chaque classe pour le client.
|
||
4. **Seuils des outils de calcul** : `compare_before_after` et `common_mode` renvoient des valeurs ; d'où viendront les seuils qui disent « saut » ou « mode commun » (expert, docs AIMsight, cas résolus) ?
|
||
5. **Critère d'ouverture au client** : quel taux d'accord avec le support, sur combien de tickets ?
|
||
6. **Page de relecture** : son format, et la forme de la validation par le support.
|
||
7. **Volume de tickets** : combien par semaine (coût total, cache froid ou non) ?
|
||
8. **Emplacement du code et des dossiers d'enquête** : `agents/enquete/` et `agents/enquetes/` proposés ; versionner les dossiers d'enquête (données client, dépôt privé, D-014) ?
|
||
|
||
---
|
||
|
||
## Annexe : références
|
||
|
||
- `docs/aimsight/AIMsight_agentic_support_project_context.md` : §4 (chaîne de dépendance), §10 (règles épistémiques), §12 (familles d'hypothèses), §13 (*support query workflow*), §14-15 (format de réponse), §16-17 (cas de régression), §23 (cas d'usage UC1 à UC8).
|
||
- `docs/aimsight/AIMsight_reference_quality_event_explainer_roadmap.md` : §4 (*explainer*, familles de preuves, classifications), §10 (API indépendante de l'estimateur), §15 (Barcelone).
|
||
- `docs/agents/rapport-exploratoire.md` : le cadre commun (D-027).
|
||
- `docs/decisions.md` : D-014 (dépôt privé), D-020 (destinataires en couches), D-027 (couche d'agents), D-038 (dev container), D-042 (cette direction).
|
||
- API Claude (fonctionnalités citées) : *Tool Runner* du SDK `anthropic`, outils stricts (`strict: true`), images dans un résultat d'outil, *prompt caching*, *task budgets*.
|