Analyseur d'expériences unifié

Analyse une ou deux expériences LLM. Supporte quatre modes selon les entrées :

Usage

/experiment-analyzer <experiment_id_1> [experiment_id_2] [texte de question] [--output agent|file|notebook]

Arguments : $ARGUMENTS

Outils disponibles

Phase 0 — Résolution du mode et de la sortie

Parser $ARGUMENTS :

1. Extraire une ou deux chaînes au format UUID comme IDs d'expérience (première = baseline/primaire, deuxième = candidate).
2. Extraire le flag --output agent|file|notebook s'il est présent.
3. Le texte restant (après les IDs et flags) est la question, le cas échéant.

Détermination du mode :

• 2 IDs + question → Q&A comparative
• 2 IDs, pas de question → Exploratory comparative
• 1 ID + question → Q&A unique
• 1 ID, pas de question → Exploratory unique

Détermination du mode de sortie :

Si --output a été fourni dans les arguments, utiliser ce mode et ignorer les questions.

Sinon, poser un seul message de clarification combiné avant de procéder. Ne couvrir que ce qui est réellement ambigu :

• Si le mode est ambigu (p. ex., l'utilisateur a posé une question mais n'a fourni que des IDs dans le contexte environnant), demander en langage clair : « Aviez-vous une question spécifique à l'esprit, ou préféreriez-vous une analyse exploratoire ? »
• Toujours demander la destination de sortie si elle n'est pas spécifiée : « Souhaitez-vous que j'enregistre ceci dans un fichier, que je l'exporte vers un notebook Datadog, ou que je l'affiche ici dans le chat ? »

Ne jamais demander plusieurs rondes de clarifications. Un seul message couvre tout ce qui n'est pas résolu.

Modes de sortie :

1. Agent (par défaut) : Afficher le rapport complet dans la conversation.
2. Fichier : Avant de commencer, proposer un chemin : evals/reports/YYYY-MM-DD-<experiment-slug>-analysis.md Le présenter à l'utilisateur et le laisser confirmer ou ajuster. Ensuite, procéder.
3. Notebook : Utiliser mcp__datadog-mcp-core__create_datadog_notebook à la fin. Si l'outil n'est pas disponible, afficher ces instructions de configuration à la place d'échouer :

   Pour activer l'export de notebook Datadog, ajouter le serveur MCP :
     claude mcp add --transport http datadog-mcp https://mcp.datadoghq.com/api/unstable/mcp-server
   Voir : https://docs.datadoghq.com/bits_ai/mcp_server/setup/

   Ensuite, demander : « Souhaitez-vous basculer vers une sortie fichier ou agent à la place ? » Voir Phase 5 pour les détails complets de l'appel notebook.

Après résolution du mode et de la sortie, procéder entièrement automatiquement à travers les Phases 1–5 sans interaction utilisateur supplémentaire.

Phase 1 — Orientation

Comparative : Appeler get_llmobs_experiment_summary pour les deux expériences. Produire une comparaison côte à côte :

• Échelle : total des événements et taux d'erreur pour chacun
• Métriques : quelles métriques existent dans chacun ; lesquelles sont partagées
• Dimensions : quelles dimensions existent dans chacun ; lesquelles sont partagées
• Drapeaux rouges immédiats (taux d'erreur élevé, métriques manquantes, données rares)
• Améliorations ou régressions évidentes visibles au niveau du résumé

Unique : Appeler get_llmobs_experiment_summary pour l'expérience. Déterminer :

• Total des événements, nombre d'erreurs, taux d'erreur
• Métriques disponibles (classer en exact-match vs rubric/qualité)
• Dimensions disponibles pour segmentation
• Tout drapeau rouge immédiat

Phase 2 — Découverte de signaux + liens UI

Comparative : En utilisant uniquement les métriques et dimensions partagées, identifier :

• Segments où la candidate surpasse la baseline
• Segments où la candidate régresse
• Types d'erreur présents dans l'un mais rares dans l'autre
• Décalages de distribution ou lacunes de couverture
• Compromis (p. ex., rappel plus élevé, précision plus basse)

Générer des liens UI de comparaison Datadog :

• URL de base : https://app.datadoghq.com/llm/experiment-comparison
• Paramètres requis : baselineExperimentId, experimentIds (candidate%2Cbaseline), tableView=all
• Optionnel (inclure si détectable) : project, compareDatasetId, selectedEvaluation
• Priorité selectedEvaluation : overall/overall_score/rubric metric → métrique primaire → première métrique partagée
• Générer 2–4 liens : comparaison primaire, vue de régression, vue d'étalonnage (si applicable), vue du pire segment (uniquement si supporté — ne jamais fabriquer de filtres)

Unique : Mesurer les performances par métrique sur toutes les dimensions. Identifier :

• Segments les moins performants (par métrique × dimension)
• Tout segment avec des taux de réussite surprenants
• Taux de réussite globaux et variance

Générer un lien UI d'expérience Datadog :

• https://app.datadoghq.com/llm/experiments/{experiment_id}

Phase 3 — Approfondissements

Exécuter automatiquement tous les approfondissements nécessaires. Ne pas demander d'approbation ou faire de pause.

Modes Q&A : Concentrer les approfondissements sur ce qui est nécessaire pour répondre directement à la question. Extraire des événements spécifiques, segmenter par dimensions pertinentes, inspecter les exemples.

Modes Exploratory : Investiguer les signaux les plus intéressants largement :

• Analyse de delta par segment et par classe (comparative) ou analyse de taux de réussite (unique)
• Analyse de chevauchement d'erreur vs modes de défaillance uniques
• Échantillonnage et inspection qualitative des défaillances représentatives (2–5 par problème)
• Analyse des thèmes d'erreur en cluster

Règles :

• Préférer les analyses bon marché et hautement signifiantes en premier ; ne pas arrêter tôt.
• Masquer ou caviardé les PII dans tous les résultats.
• Éviter les actions destructives.

Pour chaque événement échantillonné, générer un lien span direct : https://app.datadoghq.com/llm/experiments/{experiment_id}?selectedTab=overview&sp=[{"p":{"experimentId":"{experiment_id}","spanId":"{span_id}"},"i":"experiment-details"}]&spanId={span_id}

Pour chaque segment Deep Dive, générer un lien direct pour afficher ces événements dans l'expérience (candidate) : https://app.datadoghq.com/llm/experiments/{experiment_id}?selectedTab=overview&filter[{dimension}]={value} Si vous n'êtes pas sûr que le format d'URL de filtre fonctionne pour cette dimension, omettre les paramètres de filtre et établir un lien vers la racine de l'expérience à la place. Ne jamais fabriquer d'URL de filtre.

Phase 4 — Synthèse

Exploratory comparative :

• Victoires claires où la candidate améliore la baseline
• Régressions claires ou risques que la candidate introduit
• Zones neutres ou inchangées
• Hypothèses de cause profonde (1–4), liées à la preuve
• Recommandations priorisées : envoyer tel quel / bloquer / conditionner par segment / combiner les comportements

Q&A comparative :

• Réponse directe à la question avec un verdict clair
• Preuve justificative (métriques, pourcentages, exemples d'événements)
• Contexte pertinent (p. ex., mises en garde, limitations des données)

Exploratory unique :

• Évaluation des performances globales
• Segments les moins performants et causes profonde
• Hypothèses sur les raisons des défaillances
• Expériences suivantes recommandées

Q&A unique :

• Réponse directe à la question avec un verdict clair
• Preuve justificative des données d'expérience

Tous les modes : utiliser les deltas/taux quantifiés partout où possible. Caviardé les PII.

Phase 5 — Livraison de sortie

Agent : Présenter le rapport complet dans la conversation en utilisant le format de rapport ci-dessous.

Fichier : Écrire le rapport au chemin pré-confirmé. Confirmer avec : « Rapport enregistré à <chemin>. »

Notebook : Appeler mcp__datadog-mcp-core__create_datadog_notebook avec les paramètres suivants :

• name (par mode) : | Mode | Nom | |------|-----| | Exploratory comparative | Experiment Analysis: {baseline_short} (Baseline) vs {candidate_short} (Candidate) — YYYY-MM-DD | | Q&A comparative | Experiment Q&A: {baseline_short} vs {candidate_short} — YYYY-MM-DD | | Exploratory unique | Experiment Analysis: {experiment_short} — YYYY-MM-DD | | Q&A unique | Experiment Q&A: {experiment_short} — YYYY-MM-DD | où short = 8 premiers caractères de l'UUID.

• cells : le rapport complet comme cellule markdown unique — [{ "type": "markdown", "text": "<full report markdown>" }]. Omettre le titre de niveau supérieur # Experiment Analysis Report du contenu de la cellule — il est déjà affiché comme titre du notebook.

• time : { "live_span": "1h" }

Une fois le notebook créé, afficher l'URL dans le chat : "Rapport exporté vers notebook : <url>"

Si l'outil n'est pas disponible, suivre les instructions de secours en Phase 0.

Phase 6 — Suivi conversationnel

Après livraison du rapport, ajouter une section de suivi :

---
## Vous voulez explorer davantage ?

Voici quelques directions selon les résultats :

1. [Question spécifique dérivée des résultats réels — p. ex., « Vous voulez que j'approfondisse pour comprendre pourquoi les scénarios SQL ont régressé dans la candidate ? »]
2. [Autre suivi spécifique — p. ex., « Dois-je comparer les motifs d'erreur entre les deux clusters défaillants ? »]
3. [Une troisième option si pertinent]

Avez-vous d'autres questions sur cette analyse ?

Rester actif après le rapport. Répondre aux questions de suivi en utilisant les mêmes outils MCP, en référençant les résultats déjà rassemblés. Ne pas re-lancer les analyses déjà effectuées sauf si de nouvelles questions l'exigent.

Format de rapport

Règles de liens :

• IDs d'expérience : Partout où un UUID d'expérience complet apparaît, le rendre comme lien Markdown vers https://app.datadoghq.com/llm/experiments/{full_uuid}.
• En-têtes de colonne de tableau comparative : Dans le tableau d'orientation et dans chaque tableau ultérieur ayant des colonnes Baseline/Candidate, envelopper l'en-tête entier en tant que lien — pas seulement l'ID court. Format : [Baseline \{short_id}`]({baseline_url})etCandidate `{short_id}``. Cela rend la cellule d'en-tête entière cliquable, pas seulement l'ID.

# Experiment Analysis Report

> **Question :** {texte de la question originale}
> _(Q&A modes uniquement — omettre pour les modes Exploratory)_

## Summary & Recommendations

[Comparative : **Baseline** : [`{baseline_short}`]({baseline_url}) | **Candidate** : [`{candidate_short}`]({candidate_url}) | **Compare** : [`{baseline_short}-{candidate_short}`](https://app.datadoghq.com/llm/experiment-comparison?baselineExperimentId={baseline_id}&experimentIds={candidate_id}%2C{baseline_id}&tableView=all&selectedEvaluation=pass) — Single : **Experiment** : [`{experiment_short}`]({experiment_url}). Toujours la première ligne de cette section.]

[Résumé exécutif de 2–3 phrases directement sous la ligne des liens. Commencer par « Ceci est une analyse de type **{Mode}**... » où {Mode} est l'un des éléments suivants : Exploratory comparative, Q&A comparative, Exploratory unique, Q&A unique. Inclure le/les objectif(s) de l'expérience, l'échelle et le résultat clé avec des chiffres spécifiques.]

[Si le rapport utilise des valeurs de dimension opaques (p. ex. étiquettes de catégories comme b1/b2/b3/bx), ajouter une sous-section `### Dataset Categories` ici. Inclure : une phrase expliquant d'où viennent les catégories (c.-à-d. étiquettes du groupage de questions du dataset d'évaluation par outils/sources de données requis), puis une puce par valeur avec son nom en gras et une brève description. Déduire les descriptions des motifs de questions entrantes, des tags de capacité et des appels d'outils attendus. Omettre cette sous-section si toutes les valeurs de dimension sont auto-explicatives.]

[Victoires, régressions, zones neutres, actions priorisées. Pour Q&A : verdict + justification.]

## Orientation

[Tableau côte à côte pour comparative ; tableau récapitulatif pour unique. Inclure : événements, taux d'erreur, métriques, dimensions. Les IDs d'expérience dans les en-têtes de colonne doivent être des liens Markdown.]

## What Changed

[Modes comparatifs uniquement. Tableau des différences entre baseline et candidate : modèle, profil d'outils/compétences, dataset, schéma d'évaluateur et toute autre différence de métadonnées détectable à partir des données du résumé.
Si aucune différence n'est détectable, écrire : « Aucune différence de configuration détectée entre les expériences. »]

## [Signals | Answer to Question]

[Pour exploratory : tableau rangé des signaux/segments avec deltas de métriques et comptages d'impact.]
[Pour Q&A : réponse directe avec verdict, puis preuve justificative.]

## Deep Dive Findings

### [Titre du problème/résultat]

**Segment** : `[dimension=value]` | **Impact** : N événements | **Severity** : métrique pass rate = X% | [View events](https://app.datadoghq.com/llm/experiments/{experiment_id}?selectedTab=overview&filter[{dimension}]={value})

**What's happening** : [1–2 phrases : observation clé et impact métrique uniquement]

**Representative examples** :
- [Span link] : [input → output → expected, ce qui s'est mal passé]

**Root cause hypothesis** : [Catégorie] : [Explication liée à la preuve]

**Recommendation** : [Étape concrète et réalisable suivante]

---
[Répéter pour chaque problème majeur]

## UI Links

[Tous les liens UI Datadog générés avec libellés]

Règles de fonctionnement

• Ne rien supposer à propos de l'expérience (modèle, tâche, métriques, schéma, dimensions). Déduire tout en inspectant les données.
• Fonder toutes les conclusions sur une preuve spécifique : IDs d'événement, comptages, pourcentages.
• Montrer les calculs : inclure les comptages et les taux, pas seulement des affirmations qualitatives.
• Éviter les explications spéculatives non soutenues par la preuve observée.
• Caviardé ou masquer les PII dans tous les résultats visibles par l'utilisateur.
• Ne jamais afficher les appels d'outils internes, les schémas ou les détails d'implémentation à l'utilisateur.