04 Enquêter

Point de départ

Le Module 03 a produit une trace Chat de référence pour How many active customers do we have? avec un désaccord volontaire :

Gardez l'ID ou l'URL et les deux décomptes de la feuille. N'utilisez pas le diagnostic curl non noté du Module 03.

Pourquoi une enquête humaine est nécessaire

Un 👎 indique où regarder, pas ce qui a échoué. L'utilisateur peut avoir voulu autre chose, la demande peut être ambiguë, le SQL invalide ou deux définitions métier différentes. Promouvoir chaque signal négatif directement dans un dataset doré transformerait des suppositions en vérité.

Ici, un relecteur consigne d'abord ce qui est observable, teste les explications possibles, puis seulement note un diagnostic et une correction. Cette décision revue — et non le 👎 — constitue la vérité transmise au Module 05.

Objectif

Terminer une tâche d'annotation production-investigation-<session> pour la racine chat_turn du Module 03. Elle doit contenir une observation, une catégorie d'échec, le SQL corrigé exact, l'approbation pour le dataset doré et la provenance de production.

Étape 1 — Trouver l'incident exact

Dans Langfuse, ouvrez Tracing et filtrez le score Boolean user-thumbs = false. Ouvrez la trace réunissant :

• nom ou observation racine chat_turn ;
• question How many active customers do we have? ;
• le config_id gagnant et l'ID du Module 03 ;
• metadata policyversion=policy-v1 ; et
• scores sql-execution-success=true et user-thumbs=false.

Le service émet policy_version, mais OpenTelemetry retire l'underscore ; la clé Langfuse est policyversion.

Étape 2 — Créer les trois configurations de score

Il s'agit volontairement d'une étape de revue humaine uniquement dans l'interface. Le dépôt ne contient aucune commande qui crée ou termine la tâche à votre place.

Avant la file, ouvrez Settings → Scores → Create et créez :

Respectez exactement noms et tirets. Créer les configurations d'abord est le plus sûr, car l'ensemble de leurs ID associés à la file est figé lors de sa création. En cas d'omission, créez une nouvelle file suffixée. Les configurations restent modifiables : les changements pris en charge doivent passer par une mise à jour auditée et ne réécrivent pas les scores existants.

Étape 3 — Créer la file et cibler la racine logique

Ouvrez Annotations → Queues → Create, puis :

1. Nommez-la production-investigation-<session> en remplaçant <session> par un identifiant de session court et unique.
2. Associez les trois configurations de l'étape 2.
3. Créez la file.
4. Revenez à la trace du Module 03, sélectionnez la racine chat_turn, ouvrez Annotate et choisissez la file.
5. Ouvrez la tâche et confirmez que sa cible est chat_turn, pas llm_call.

La file ne peut plus changer ses ID associés. Recréez-la seulement si cet ensemble est faux ; utilisez une mise à jour auditée pour une modification prise en charge d'une configuration déjà associée.

Étape 4 — Coder ouvertement ce qui est observable

Le Module 03 a dévoilé le scénario préparé. Mettez ce savoir entre parenthèses et appliquez le processus d'un incident inconnu : examinez question, SQL, décompte, modèle et prompt, et les deux scores avant de nommer une cause. Saisissez une note fondée uniquement sur les preuves dans observed-issue, par exemple :

The answer returned a count and its SQL executed. The observed count differs from the
second reference count recorded in Module 03. The generated query uses a 90-day
customer signup window, and the trace metadata reports policy-v1.

Ce texte n'accuse encore ni le modèle, ni le moteur SQL, ni l'utilisateur, ni la politique. Cette séparation empêche d'introduire le diagnostic préparé avant la vérification.

Étape 5 — Examiner toutes les preuves

Sur la racine chat_turn, vérifiez :

• metadata policyversion=policy-v1 ;
• SQL utilisant v_customers et une fenêtre de 90 jours sur signup_date ;
• résultat structuré contenant le décompte observé au Module 03 ;
• score opérationnel Boolean sql-execution-success=true ; et
• signal utilisateur Boolean user-thumbs=false.

Le SQL suit les instructions policy-v1 de la publication et le score d'exécution est correct dans son périmètre étroit. Aucun de ces faits ne prouve encore que la politique publiée correspond à la définition gouvernée actuelle.

Étape 6 — Tester les deux politiques côte à côte

Depuis ClickHouse_Demos/workshops/agent_arena, exécutez les deux définitions en lecture seule :

source .env
.venv/bin/python - <<'PY'
from arena.config import load_config
from agents.chclient import ROClickHouseClient

queries = {
    "policy-v1": """SELECT count() FROM v_customers
WHERE signup_date >= today() - INTERVAL 90 DAY""",
    "policy-v2": """SELECT uniqExact(customer_id) FROM v_orders
WHERE order_ts >= now() - INTERVAL 30 DAY
AND status NOT IN ('cancelled', 'returned')""",
}
client = ROClickHouseClient(load_config().clickhouse)
for version, sql in queries.items():
    result = client.query(sql)
    print(f"{version}: {result.rows[0][0]}")
PY

Les deux décomptes doivent correspondre à la feuille et différer. Vous pouvez désormais diagnostiquer une définition métier publiée obsolète : la trace annonce policy-v1, son SQL la suit et la requête actuelle vérifiée applique policy-v2.

Étape 7 — Annoter, corriger, approuver et terminer

Dans la tâche, enregistrez :

Basculez Corrected Output en plain-text mode, puis saisissez exactement :

SELECT uniqExact(customer_id) FROM v_orders
WHERE order_ts >= now() - INTERVAL 30 DAY
AND status NOT IN ('cancelled', 'returned')

Langfuse enregistre la correction, mais ne l'exécute pas. Le client de l'étape 6 doit avoir exécuté ce texte exact avant approbation. Si vous le modifiez, réexécutez-le. Choisissez ensuite Complete ou Complete + next. Une correction mal formée, inexécutable ou non vérifiée ne doit pas devenir vérité dorée.

Étape 8 — Consigner la provenance pour le Module 05

Copiez ces valeurs dans la feuille, en gardant les ID privés :

source_trace_id, failure_category et source_policy_version sont obligatoires pour un enregistrement doré issu de la production. annotation_id est facultatif au runtime, mais consignez-le lorsque l'interface l'affiche afin de préserver l'auditabilité.

Comment vérifier que vous avez terminé

• Vous avez examiné l'unique trace Chat du Module 03 avec user-thumbs=false.
• La cible est la racine chat_turn, jamais l'enfant llm_call.
• La file production-investigation-<session> contient les trois configurations correctement typées.
• observed-issue décrit le comportement avant le diagnostic.
• Vous avez exécuté les deux SQL et confirmé des décomptes différents.
• La tâche terminée contient stale-business-policy, le SQL exact et approved-for-golden=true.
• La feuille préserve la provenance sans publier d'ID ou d'URL réels.
• Vous pouvez expliquer pourquoi un 👎 priorise une revue sans devenir vérité de référence.

Passez au Module 05 — Boucler la boucle pour promouvoir la correction, comparer les politiques et prévenir en ligne la même classe d'échec.