Développement Piloté par les Évaluations pour les Applications Python LLM

Vous créez un pipeline d'évaluation automatisé qui teste une application IA basée sur Python de bout en bout — en l'exécutant de la même manière qu'un utilisateur réel le ferait, avec des entrées réelles — puis en évaluant les sorties à l'aide d'évaluateurs et en produisant des résultats de réussite/échec via pixie test.

Ce que vous testez est l'application elle-même — son traitement des requêtes, l'assemblage du contexte (comment elle rassemble les données, construit les prompts, gère l'état de la conversation), le routage et le formatage des réponses. L'application utilise un LLM, ce qui rend les sorties non-déterministes — c'est pourquoi vous utilisez des évaluateurs (LLM-as-judge, scores de similarité) au lieu de assertEqual — mais l'élément testé est le code de l'application, pas le LLM.

Lors de l'évaluation, le code propre de l'application s'exécute réellement — routage, assemblage du prompt, appels LLM, formatage des réponses — rien n'est mocké ou stubé. Mais les données que l'application lit à partir de sources externes (bases de données, caches, APIs tierces, flux vocaux) sont remplacées par des valeurs spécifiées par le test via des instrumentations. Cela signifie que chaque cas de test contrôle exactement les données que l'application voit, tout en exerçant l'intégralité du chemin du code d'application.

Règle : Les appels LLM de l'application doivent aller à un vrai LLM. Ne remplacez pas, ne mocquez pas, ne stubez pas ou n'interceptez pas le LLM avec une implémentation fictive. Le LLM est le composant générateur de valeur central — le remplacer rend l'eval tautologique (vous contrôlez à la fois les entrées et les sorties, donc les scores sont sans signification). Si la suite de tests du projet contient des motifs de mocking LLM, ce sont pour les tests unitaires du projet — N'ADOPTEZ PAS ces motifs pour le Runnable eval.

Le livrable est une exécution fonctionnelle de pixie test avec des scores réels — pas un plan, pas juste une instrumentation, pas juste un dataset.

Cette compétence porte sur l'exécution du travail, pas sa description. Lisez le code, modifiez les fichiers, exécutez les commandes, produisez un pipeline fonctionnel.

Avant de commencer

D'abord, activez l'environnement virtuel. Identifiez le bon environnement virtuel pour le projet et activez-le. Une fois l'environnement virtuel actif, exécutez le setup.sh inclus dans les ressources de la compétence. Le script met à jour la compétence eval-driven-dev et le paquet Python pixie-qa à la dernière version, initialise le répertoire de travail pixie s'il ne l'est pas déjà, et démarre un serveur web en arrière-plan pour afficher les mises à jour utilisateur.

Gestion des erreurs de configuration — ce que vous pouvez ignorer par rapport à ce qui doit réussir :

• La mise à jour de la compétence échoue → OK pour continuer. La version existante de la compétence est suffisante.
• La mise à niveau de pixie-qa échoue mais était déjà installée → OK pour continuer avec la version existante.
• pixie-qa N'EST PAS installé et l'installation échoue → ARRÊTEZ. Demandez de l'aide à l'utilisateur. Le workflow ne peut pas procéder sans le paquet pixie.
• pixie init échoue → ARRÊTEZ. Demandez de l'aide à l'utilisateur.
• pixie start (serveur web) échoue → ARRÊTEZ. Demandez de l'aide à l'utilisateur. Consultez server.log dans le répertoire racine de pixie pour les diagnostics. Causes courantes : conflit de port, dépendance manquante, environnement lent. NE PAS procéder sans le serveur web — l'utilisateur en a besoin pour voir les résultats d'évaluation.

Le workflow

Suivez les étapes 1–6 directement sans vous arrêter. Ne demandez pas de confirmation à l'utilisateur aux étapes intermédiaires — vérifiez chaque étape vous-même et continuez.

Comment travailler — lisez ceci avant de faire quoi que ce soit d'autre :

• Une étape à la fois. Lisez uniquement les instructions de l'étape actuelle. NE LISEZ PAS les étapes 2–6 en travaillant sur l'étape 1.
• Lisez les références uniquement quand une étape vous le dit. Chaque étape nomme un fichier de référence spécifique. Lisez-le quand vous atteignez cette étape — pas avant.
• Créez les artefacts immédiatement. Après avoir lu le code pour une sous-étape, écrivez le fichier de sortie pour cette sous-étape avant de continuer. N'accumulez pas la compréhension à travers plusieurs sous-étapes avant d'écrire quoi que ce soit.
• Vérifiez, puis continuez. Chaque étape a un point de contrôle. Vérifiez-le, puis passez à l'étape suivante. Ne planifiez pas les étapes futures en vérifiant l'étape actuelle.

Quand s'arrêter et demander de l'aide :

Certains blocages ne peuvent et ne doivent pas être contournés. Quand vous rencontrez l'un des éléments suivants, arrêtez immédiatement et demandez de l'aide à l'utilisateur — ne tentez pas de contournements :

• L'application ne s'exécute pas en raison de variables d'environnement manquantes ou de configuration : L'application nécessite des variables d'environnement ou une configuration qui ne sont pas définies et ne peuvent pas être déduites. NE PAS contourner ceci en mockant, fakeant ou remplaçant les composants de l'application — l'eval doit exercer le code de production réel. Demandez à l'utilisateur de corriger la configuration de l'environnement.
• Défaillances d'import d'application indiquant un projet cassé : Si les modules principaux de l'application ne peuvent pas être importés en raison de dépendances système manquantes ou de versions Python incompatibles (pas juste des paquets pip manquants que vous pouvez installer), demandez à l'utilisateur de corriger la configuration du projet.
• Point d'entrée ambigu : Si l'application a plusieurs points d'entrée également plausibles et l'analyse du projet ne clarifie pas lequel compte le plus, demandez à l'utilisateur lequel cibler.

Les blocages que vous DEVRIEZ résoudre vous-même (ne pas demander) : paquets Python manquants (les installer), paquet pixie manquant (l'installer), conflits de port (choisir un port différent), problèmes de permissions de fichiers (les corriger).

Exécutez les étapes 1–6 en séquence. Si le prompt de l'utilisateur clarifie que les étapes antérieures sont déjà faites (par ex. « exécuter les tests existants », « réexécuter les evals »), passez à l'étape appropriée. En cas de doute, commencez par l'étape 1.

Étape 1 : Comprendre l'application et définir les critères d'évaluation

D'abord, vérifiez le prompt de l'utilisateur pour les exigences spécifiques. Avant de lire le code de l'application, examinez ce que l'utilisateur a demandé :

• Documents ou spécifications référencés : Le prompt mentionne-t-il un fichier à suivre (par ex. « suivre la spec dans EVAL_SPEC.md », « utiliser la méthodologie dans REQUIREMENTS.md ») ? Si oui, lisez d'abord ce fichier — il peut spécifier des datasets, des dimensions d'évaluation, des critères de passage ou une méthodologie qui remplacent vos défauts.
• Datasets spécifiés ou sources de données : Le prompt référence-t-il des fichiers de données spécifiques (par ex. « utiliser les questions de eval_inputs/research_questions.json », « utiliser les scénarios dans call_scenarios.json ») ? Si oui, lisez ces fichiers — vous devez les utiliser comme base pour votre dataset d'eval, et non fabriquer des alternatives génériques.
• Dimensions d'évaluation spécifiées : Le prompt nomme-t-il des aspects de qualité spécifiques à évaluer (par ex. « évaluer sur la factualité, complétude et biais », « tester la vérification d'identité et la correction des appels d'outils ») ? Si oui, chaque dimension nommée doit avoir un évaluateur correspondant dans votre fichier de test.

Si le prompt spécifie l'un des éléments ci-dessus, ils ont priorité. Lisez-les et intégrez-les avant de continuer.

L'étape 1 a trois sous-étapes. Chacune lit son propre fichier de référence et produit son propre fichier de sortie. Complétez chaque sous-étape entièrement avant de commencer la suivante.

Sous-étape 1a : Analyse du projet

Référence : Lisez references/1-a-project-analysis.md maintenant.

Avant d'examiner la structure du code ou les points d'entrée, comprenez ce que ce logiciel fait dans le monde réel — son objectif, ses utilisateurs, la complexité des entrées réelles, et où il échoue. Cette compréhension pilote chaque décision en aval : quels points d'entrée importent le plus, quels critères d'eval définir, quelles entrées de trace utiliser, et quelles entrées de dataset créer. Écrivez le fichier de contexte détaillé avant de continuer. Remarque : le projet peut contenir tests/, fixtures/, examples/, des serveurs mock et de la documentation — ce sont l'infrastructure de développement propre du projet, PAS des sources de données pour votre pipeline d'eval. Ignorez-les en sourçant les entrées de trace et le contenu du dataset.

Point de contrôle : pixie_qa/00-project-analysis.md écrit — couvrant ce que le logiciel fait, utilisateurs cibles, inventaire des capacités (au moins 3 capacités si le projet les a), caractéristiques d'entrée réalistes, et problèmes difficiles / modes de défaillance (au moins 2).

Sous-étape 1b : Point d'entrée et flux d'exécution

Référence : Lisez references/1-b-entry-point.md maintenant.

Lisez le code source pour comprendre comment l'application démarre et comment un utilisateur réel l'invoque. Utilisez l'inventaire des capacités de pixie_qa/00-project-analysis.md pour prioriser les points d'entrée — concentrez-vous sur le(s) point(s) d'entrée qui exercent les capacités les plus précieuses, pas juste le premier trouvé. Écrivez le fichier de contexte détaillé avant de continuer.

Point de contrôle : pixie_qa/01-entry-point.md écrit — couvrant le point d'entrée, le flux d'exécution, l'interface utilisateur et les exigences env.

Sous-étape 1c : Critères d'évaluation

Référence : Lisez references/1-c-eval-criteria.md maintenant.

Définissez les cas d'usage de l'application et les critères d'eval. Dérivez les cas d'usage de l'inventaire des capacités dans pixie_qa/00-project-analysis.md. Dérivez les critères d'eval des problèmes difficiles / modes de défaillance — pas des dimensions de qualité génériques. Les cas d'usage pilotent la création du dataset (étape 4) ; les critères d'eval pilotent la sélection des évaluateurs (étape 3). Écrivez le fichier de contexte détaillé avant de continuer.

Point de contrôle : pixie_qa/02-eval-criteria.md écrit — couvrant les cas d'usage, critères d'eval et leur portée d'applicabilité. NE LISEZ PAS encore les instructions de l'étape 2.

Étape 2 : Instrumenter, exécuter l'application et capturer une trace de référence

L'étape 2 a trois sous-étapes. Chacune lit son propre fichier de référence. Complétez chaque sous-étape avant de commencer la suivante.

Sous-étape 2a : Instrumenter avec wrap

Référence : Lisez references/2a-instrumentation.md maintenant.

Ajoutez des appels wrap() aux limites des données de l'application afin que le harnais d'eval puisse injecter des entrées contrôlées et capturer les sorties. Cela rend l'application testable sans changer sa logique.

Point de contrôle : Appels wrap() ajoutés à toutes les limites de données. Chaque critère d'eval de pixie_qa/02-eval-criteria.md a un point de données correspondant.

Sous-étape 2b : Implémenter le Runnable

Référence : Lisez references/2b-implement-runnable.md maintenant.

Écrivez une classe Runnable qui permet au harnais d'eval d'invoquer l'application exactement comme un utilisateur réel le ferait. Le Runnable doit être simple — il câble simplement le point d'entrée réel de l'application à l'interface du harnais. Si cela devient compliqué, quelque chose ne va pas.

Point de contrôle : pixie_qa/run_app.py écrit. Le Runnable appelle le point d'entrée réel de l'application avec une configuration LLM réelle — pas de mocking, pas de faking, pas de remplacement de composants.

Sous-étape 2c : Capturer et vérifier une trace de référence

Référence : Lisez references/2c-capture-and-verify-trace.md maintenant.

Exécutez l'application via le Runnable et capturez une trace. La trace prouve que l'instrumentation et le Runnable fonctionnent correctement, et fournit les formes de données nécessaires pour la création du dataset à l'étape 4.

Point de contrôle : pixie_qa/reference-trace.jsonl existe. Toutes les entrées wrap attendues et les entrées llm_span attendues apparaissent. pixie format montre tous les points de données nécessaires à l'évaluation. NE LISEZ PAS encore les instructions de l'étape 3.

Étape 3 : Définir les évaluateurs

Référence : Lisez references/3-define-evaluators.md maintenant pour les sous-étapes détaillées.

Objectif : Transformer les critères d'eval qualitatifs de l'étape 1c en fonctions de scoring concrètes et exécutables. Chaque critère mappe soit sur un évaluateur intégré, soit sur un évaluateur agent (le défaut pour tout critère sémantique ou qualitatif), soit sur une fonction personnalisée manuelle (uniquement pour les vérifications mécaniques/déterministes comme regex ou existence de champ). L'artefact de mapping d'évaluateur établit un pont entre les critères et le dataset, assurant que chaque dimension de qualité a un scoreur. Sélectionnez les évaluateurs qui mesurent les problèmes difficiles identifiés dans pixie_qa/00-project-analysis.md — pas juste des dimensions de qualité génériques.

Point de contrôle : Tous les évaluateurs implémentés. pixie_qa/03-evaluator-mapping.md écrit avec le mapping critère-à-évaluateur et la rationale de décision. NE LISEZ PAS encore les instructions de l'étape 4.

Étape 4 : Construire le dataset

Référence : Lisez references/4-build-dataset.md maintenant pour les sous-étapes détaillées.

Objectif : Créer les scénarios de test qui lient tout — le runnable (étape 2), les évaluateurs (étape 3) et les cas d'usage (étape 1c). Chaque entrée du dataset définit quoi envoyer à l'application, quelles données l'application doit voir à partir des services externes, et comment scorer le résultat. Utilisez la trace de référence de l'étape 2 comme source de vérité pour les formes de données et les noms de champs. Couvrez les entrées de l'inventaire des capacités dans pixie_qa/00-project-analysis.md et incluez des entrées ciblant les modes de défaillance identifiés là. NE PAS utiliser les propres fixtures de test du projet, serveurs mock ou données d'exemple comme contenu d'eval_input du dataset — sourcez des données réelles à la place. Chaque wrap(purpose="input") dans l'application doit avoir du contenu pré-capturé dans l'eval_input de chaque entrée — NE LAISSEZ PAS eval_input vide quand l'application a des wraps d'input.

Point de contrôle : Dataset JSON créé à pixie_qa/datasets/<name>.json avec des entrées diverses couvrant tous les cas d'usage. Audit de réalisme du dataset réussi — les entrées utilisent des données réelles à l'échelle représentative, aucune contamination de fixtures de test du projet, au moins une entrée cible un mode de défaillance avec un résultat incertain, et chaque eval_input a du contenu capturé pour tous les wraps d'input. NE LISEZ PAS encore les instructions de l'étape 5.

Étape 5 : Exécuter pixie test et corriger les problèmes mécaniques

Référence : Lisez references/5-run-tests.md maintenant pour les sous-étapes détaillées.

Objectif : Exécuter le pipeline complet de bout en bout et le faire fonctionner sans erreurs mécaniques. Cette étape traite strictement de la correction des problèmes de configuration et de données dans les composants QA pixie (dataset, runnable, évaluateurs personnalisés) — PAS de la correction de l'application elle-même ou de l'évaluation de la qualité des résultats. Une fois que pixie test se termine sans erreurs et produit des scores d'évaluateurs réels pour chaque entrée, cette étape est terminée.

Point de contrôle : pixie test s'exécute jusqu'à la fin. Chaque entrée du dataset a des scores d'évaluateurs (résultats EvaluationResult ou PendingEvaluation réels). Pas d'erreurs de configuration, pas d'échecs d'import, pas d'erreurs de validation de données.

Si le test génère une erreur, c'est un bug mécanique dans vos composants QA — corrigez et réexécutez. Mais une fois que les tests produisent des scores, continuez. NE PASSEZ PAS à l'évaluation de la qualité des résultats ici — c'est l'étape 6.

Procédez toujours à l'étape 6 après que les tests produisent des scores. L'analyse est l'étape finale essentielle — sans elle, les évaluations en attente ne sont jamais complétées et l'utilisateur obtient des scores bruts non interprétés sans idées actionnables. NE PAS vous arrêter ici et demander à l'utilisateur s'il faut continuer.

Règle de cycle pour les exécutions itératives : Chaque invocation réussie de pixie test crée un répertoire concret pixie_qa/results/<test_id> et commence un nouveau cycle d'analyse. Avant de modifier le code d'application, les prompts, les datasets, les évaluateurs ou de réexécuter pixie test, complétez l'étape 6 pour ce répertoire de résultats exact. Ne sautez pas les cycles antérieurs et n'analysez que la dernière exécution.

Étape 6 : Analyser les résultats

Référence : Lisez references/6-analyze-outcomes.md maintenant — elle contient le processus d'analyse complet en trois phases, les directives d'écriture et les exigences de format de sortie.

Objectif : Analyser les résultats de pixie test dans un processus structuré et piloté par les données pour produire des idées actionnables sur la qualité des cas de test, la qualité des évaluateurs et la qualité de l'application. Cette étape complète les évaluations en attente, écrit l'analyse par entrée et par dataset, et produit un plan d'action priorisé. Chaque affirmation doit être soutenue par des données concrètes de l'exécution d'évaluation — pas de spéculation, pas d'improvisation.

Artefacts d'analyse persistée : Dans ce workflow épuré, persistez l'analyse uniquement au niveau du dataset et du test-run. Ces artefacts utilisent toujours une version détaillée (pour la consommation par agent : points de données, traces de preuves, chaînes de raisonnement) plus une version résumée (pour la révision humaine : TLDR concis lisible en moins de 2 minutes). Ne créez pas de fichiers d'analyse par entrée.

Porte de complétion difficile : L'étape 6 n'est pas complète jusqu'à ce que tout ce qui suit soit vrai :

• Chaque entrée "status": "pending" dans chaque pixie_qa/results/<test_id>/dataset-*/entry-*/evaluations.jsonl a été remplacée par un résultat scoré contenant score et reasoning.
• Chaque répertoire de dataset a analysis.md et analysis-summary.md.
• La racine du test-run a action-plan.md et action-plan-summary.md.
• Vous avez exécuté le script de vérification de l'étape 6 du répertoire resources/ de cette compétence contre pixie_qa/results/<test_id>, et il rapporte le succès.

Explicitement pas suffisant :

• Écrire un seul fichier au niveau supérieur tel que pixie_qa/06-analysis.md
• Dire que les évaluations en attente sont à l'utilisateur de les réviser dans l'UI web
• Dire qu'une entrée « réussit probablement » sans mettre à jour evaluations.jsonl

Gestion du serveur web

pixie-qa exécute un serveur web en arrière-plan pour afficher le contexte, les traces et les résultats d'eval à l'utilisateur. Il est automatiquement démarré par le script de configuration (via pixie start, qui lance un processus détaché en arrière-plan et revient immédiatement).

Quand l'utilisateur a terminé le workflow eval-driven-dev, informez-le que le serveur web est toujours en cours d'exécution et vous pouvez le nettoyer avec :

pixie stop

IMPORTANT : après l'arrêt du serveur web, l'interface web devient inaccessible. Arrêtez donc le serveur uniquement si l'utilisateur confirme qu'il a terminé avec toutes les fonctionnalités de l'interface web. S'il veut continuer à utiliser l'interface web, NE PAS arrêter le serveur.

Et chaque fois que vous redémarrez le workflow, exécutez toujours le script setup.sh dans les ressources à nouveau pour assurer que le serveur web est en cours d'exécution :