Harnais d’évaluation

Le harnais d’évaluation (zeroclaw eval run, crate crates/zeroclaw-eval) exécute des cas d’évaluation de l’agent (fixtures de traces JSON) via la boucle d’agent réelle et note chaque exécution selon des attentes déclaratives. C’est ainsi que ZeroClaw protège le comportement de la boucle d’agent (dispatch des outils, ordre des échanges multi-tours, mise en forme des réponses, refus) contre les régressions.

Il est distinct de [agent.eval], le système de notation de la qualité des réponses intégré à la boucle. Le harnais est configuré sous [eval] et appelé comme sous-commande CLI.

Modes

Taxonomie de la suite

Les suites sont des répertoires de fixtures *.json (voir evals/README.md) :

• evals/regression/ : doit rester à 100 % de réussite. Vérifié en CI via crates/zeroclaw-eval/tests/regression_suite.rs ; un échec bloque la fusion. Il s’agit de la valeur par défaut de [eval].suite_dir.
• evals/capability/ (prévu) : tâches difficiles au taux de réussite faible ; suivies dans le temps, jamais bloquantes.
• evals/live/ (prévu) : cas exécutés contre un fournisseur réel ; jamais lancés en CI par défaut.

En cours

# Rejouer la suite de tests de régression par défaut :
zeroclaw eval run

# Cibler une suite spécifique et générer du JSON lisible par machine :
zeroclaw eval run --suite evals/regression --format json

--suite remplace [eval].suite_dir ; --mode remplace [eval].mode. Le chargement des suites n’est pas récursif : seuls les enfants directs *.json du répertoire de suite sont considérés comme des cas.

Contrat des codes de sortie

zeroclaw eval run quitte avec 0 si et seulement si tous les cas ont réussi, et avec 1 sinon (tout check en échec ou toute erreur d’exécution). C’est la barrière de CI : le code de sortie du processus est le signal. La même décision est exposée sous forme de fonction pure SuiteReport::exit_code(), afin de pouvoir la tester à sa frontière réelle.

Format de casse

Chaque fixture est un LlmTrace : un model_name, une liste de turns de conversation (chacun avec un user_input et des steps de réponse scriptés), et des expects déclaratifs. Un cas est soit positif (un comportement qui doit se produire), soit négatif (un comportement qui ne doit PAS se produire, par exemple tools_not_used, response_not_contains, max_tool_calls: 0). Voir evals/README.md pour les règles de rédaction, notamment le test des deux experts et l’exigence de confidentialité selon laquelle les fixtures n’utilisent que des identités fictives.

Les attentes qui évaluent la frontière de dispatch plutôt que le texte scripté (tool_arguments_contain, tool_results_contain et exact_tool_calls) sont documentées dans crates/zeroclaw-eval/README.md. Utilisez-les dès qu’un cas affirme qu’une valeur a transité par un outil ou qu’un nombre précis d’appels d’outils a eu lieu ; les attentes portant uniquement sur la réponse finale ne peuvent démontrer ni l’un ni l’autre, car le fournisseur de rejeu scripte lui-même cette réponse. La liste des appels enregistrés constitue le fait de dispatch canonique. Les noms d’outils et le succès global en sont dérivés au moment de l’évaluation, de sorte qu’une preuve de frontière plus riche ne crée pas un second résumé des appels d’outils modifiable indépendamment.

Le chargement des fixtures échoue en mode sécurisé (fail closed), car une porte obligatoire ne doit pas certifier un cas qui ne peut pas échouer. LlmTrace::from_file() rejette une fixture qui ne déclare aucun tour de conversation (le replay exécuterait l’agent zéro fois et évaluerait ses attentes sur une exécution vide), une fixture dont le bloc d’attentes est omis ou vide, une fixture contenant une entrée de longueur nulle dans une famille d’attentes à base de chaînes (response_contains, response_not_contains, response_matches, tools_used, tools_not_used), et une fixture comportant une clé inconnue au niveau supérieur ou dans les attentes. Les familles de la frontière de dispatch appliquent le même principe : un tool ou un needle vide, un min_tool_calls: 0 vacuoire, et des bornes de comptage qui se contredisent sont tous rejetés au chargement. Chaque rejet indique la fixture et le champ fautifs.

L’admission ne peut pas détecter une dernière forme de vacuité : une assertion qu’une exécution ne produisant rien satisfait déjà, comme un simple max_tool_calls: 0. Le test de suite protégé évalue chaque fixture versionnée par rapport à une exécution vide et exige qu’au moins une vérification échoue ; un cas qui ne certifie aucun comportement ne peut donc pas rejoindre la porte requise.