Aller au contenu

ADR-022 — Comparaison d'éval « à périmètre égal » + couverture explicite comme prérequis de campagne
Statut Proposed
Date 01/07/2026
Décideurs Nicolas Léonard, Romain BAZIL (owner pipeline & éval)
Origine Chantier golden dataset / éval — PRs project-analysis #419 (golden = projets 100 % fiabilisés) et #435 (toggle « à périmètre égal ») ; 1ʳᵉ campagne réelle du 01/07/2026

Contexte

Le module d'éval (/admin/eval) compare les workflows d'extraction (declarative-v1, manus-v2, rag-agents-v1, agent-haiku-files-v1) contre un golden dataset — la fitness function de la qualité d'extraction (déclinaison de ADR-001).

Point structurant : une campagne d'éval n'exécute pas les workflows. Elle évalue les section_versions déjà produites par le pipeline. Un workflow n'a donc une « version » pour un projet que s'il a réellement tourné dessus un jour.

La 1ʳᵉ campagne réelle (01/07/2026, 24 projets golden) l'a rendu visible : les workflows n'ont pas tous tourné sur tous les projets — couverture 12 / 24 / 21 / 22. Comparer leur Score moyen revient alors à comparer des moyennes sur des échantillons de projets différents : un workflow évalué sur 12 projets (potentiellement plus faciles, et statistiquement moins robuste) peut sembler meilleur sans l'être. On confond deux grandeurs distinctes :

  1. Couverture — sur combien de projets le workflow a produit une sortie (un signal de robustesse en soi).
  2. Qualité — quand il produit, à quel point c'est juste.

Les agréger sur des périmètres inégaux produit un artefact de mesure, pas un enseignement qualité. Or l'éval sert précisément à trancher « quel workflow est le meilleur » — la comparaison doit donc être à conditions égales.

Décision

Toute conclusion de qualité entre workflows se lit à périmètre égal : sur l'intersection des projets golden évalués par tous les workflows comparés. La couverture reste une métrique séparée et explicite — jamais fondue dans le score.

Deux niveaux, du curatif au préventif :

  1. Lecture — livré (#435) : la page détail d'une campagne recalcule scores, leaderboard, cartes et callout sur l'intersection par défaut dès que la couverture est inégale. Un mode « couverture complète » reste accessible pour juger la couverture, assorti d'un avertissement de non-comparabilité. Recalcul 100 % côté front à partir des eval_results (même sémantique que buildCampaignSummary), sans changement DB.

  2. Amont — cible : la création de campagne rend la couverture visible et opposable — matrice projets × workflows + état de complétude, avec avertissement (ou blocage) tant que la couverture n'est pas pleine, ou proposition de restreindre au périmètre commun. Idéal : chaque workflow comparé tourne sur 100 % des projets golden avant évaluation (couverture pleine → plus de biais du tout). Tant que le pipeline ne réexécute pas les extractions manquantes à la demande, le mode « à périmètre égal » est le filet de sécurité.

Rationale

Isoler la qualité de la couverture (fitness function fiable)

La cascade de fiabilité (ADR-001) exige des signaux dignes de confiance. Un score de qualité biaisé par la taille/composition de l'échantillon n'est pas fiable : il faut neutraliser la variable « couverture » pour isoler la qualité. C'est la condition pour que le golden dataset serve réellement de juge.

« Le doute tue l'automatisation » → rendre le biais visible plutôt que le masquer

Plutôt que d'imposer d'emblée que tous les workflows tournent partout (coûteux en LLM et en temps), on mesure l'inégalité de couverture et on la rend explicite. Le gate à la création empêche de conclure à tort ; le mode « à périmètre égal » garantit qu'aucune lecture injuste ne fait autorité.

Deux questions produit distinctes, deux métriques distinctes

« Quel workflow traite le plus de dossiers ? » (couverture) et « lequel les traite le mieux ? » (qualité) sont deux questions. Les fondre dans une seule colonne, c'est perdre les deux. On les sépare.

Anti-pattern évité

Traiter un nombre de versions inégal comme comparable, c'est comparer des choses non comparables — une variante du raisonnement corrélé dénoncé par le mémo LIDAR (anti-pattern #3). La rigueur du périmètre commun est l'antidote.

Conséquences

Ce qui change

  1. Défaut de lecture : le classement qualité s'affiche à périmètre égal dès qu'il y a inégalité de couverture ; « couverture complète » devient un mode secondaire explicitement étiqueté « non comparable ».
  2. Couverture = citoyen de première classe : elle a sa propre lecture (colonne Versions, tooltip, et à terme matrice de couverture), distincte du score.
  3. Cible création : une campagne devra exposer sa couverture avant de laisser tirer des conclusions (matrice + gate) — objet d'une PR dédiée.

Ce qu'il faut faire

  • Livrer la matrice de couverture + garde-fou à la création (niveau 2 de la décision).
  • Viser, en amont pipeline, la couverture pleine des projets golden par les workflows candidats (idéalement en réexécutant les extractions manquantes) — pour supprimer le biais à la source.
  • Garder la métrique de couverture explicite et lisible, jamais réintroduite dans le score.

Ce qu'il faut éviter

  • Publier un classement sur couverture inégale sans avertissement : c'est l'artefact que cet ADR proscrit.
  • Fondre couverture et qualité dans un indicateur unique.
  • Bloquer durement toute campagne à couverture < 100 % tant que la réexécution à la demande n'existe pas : préférer avertir + périmètre commun, sinon on gèle l'outil.

Alternatives écartées

  • Comparer sur la couverture complète (statu quo) : biais d'échantillon — un workflow sur 12 projets « faciles » bat un workflow sur 24 sans être meilleur. C'est exactement le problème constaté.
  • Exiger 100 % de couverture avant toute campagne (blocage dur, tout de suite) : trop rigide tant que le pipeline ne réexécute pas les extractions manquantes à la demande ; on gèlerait l'éval. D'où le toggle immédiat + un gate progressif.
  • Recalcul « à périmètre égal » côté back : inutile ici — faisable côté front à partir des eval_results déjà chargés, sans migration ni endpoint. (À reconsidérer si d'autres consommateurs en ont besoin.)
  • Ne rendre visible que la couverture, sans recalcul : insuffisant — l'utilisateur continuerait à lire un classement biaisé ; il faut recalculer, pas seulement avertir.

Voir aussi

Sources