Agent Benchmark System — Lot A : moteur backend (fixtures, engine, scoring, API)

[simodev25]

Problème

Kairos Mesh n'a aucun moyen objectif de comparer les performances des modèles LLM par agent de trading. Le choix du modèle repose sur l'intuition. Les limitations documentées incluent : pas de sélection par agent par run, pas de mémoire cross-run, pas d'alerting.

Objectif

Livrer un sous-système de benchmark dédié (architecture ALT-2 validée par @architect) permettant de :

• Figer des scénarios de marché reproductibles (fixtures versionnées)
• Exécuter les agents de trading avec différents modèles LLM sur ces fixtures
• Scorer objectivement les réponses (schema validity, completeness, tool policy, reference consistency, stability)
• Exposer les résultats via API REST

Périmètre (IN)

• 4 tables : benchmark_fixture, benchmark_run, benchmark_case, benchmark_attempt
• 3 types de scénarios : single-agent, debate bundle (bullish+bearish+trader), full pipeline
• Moteur d'exécution : réutilise ALL_AGENT_FACTORIES, build_toolkit(), build_model(), build_formatter() du noyau pipeline
• Scoring V1 objectif : schema validity, completeness, tool policy compliance, reference consistency, stability (N runs)
• BenchmarkModelSpec explicite (pas de réutilisation de AgentModelSelector)
• API REST : CRUD fixtures, lancement de runs, consultation des résultats
• Migration Alembic pour les 4 tables
• Tests unitaires couvrant engine + scoring + API

Hors périmètre (OUT)

• Frontend / dashboard (Lot B)
• Juge LLM pour "coherence" et "reasoning depth" (Lot C/V2)
• Intégration CI automatisée des benchmarks
• Modification du pipeline de trading live

Critères d'acceptation

• Les 4 tables sont créées via migration Alembic
• Un fixture single-agent peut être créé, lu, mis à jour et supprimé via API
• Un benchmark run single-agent s'exécute et produit des scores pour chaque métrique V1
• Le scoring est déterministe : 2 exécutions identiques produisent le même score
• Un benchmark run debate-bundle exécute bullish+bearish+trader en séquence
• Les résultats sont consultables via API avec filtres par agent, modèle, fixture
• Le moteur réutilise le noyau pipeline partagé (ALL_AGENT_FACTORIES, build_toolkit(), build_model())
• Aucune régression sur les tests existants du pipeline de trading
• Tests unitaires couvrent : création de fixture, exécution single-agent, scoring, API CRUD

Dépendances

• Noyau pipeline partagé : registry.py, agents.py, toolkit.py, model_factory.py
• Table LlmCallLog existante (lecture seule pour corrélation)

Risques

• Drift entre benchmark et pipeline live si le noyau partagé diverge → mitigé par extraction de shared core
• Coût LLM des runs de benchmark → configurer des limites par run

Décisions architecturales (session précédente)

• ALT-2 : sous-système dédié adossé au noyau pipeline partagé (ADR à rédiger)
• Fixtures versionnées : figent inputs + prompts + skills + tool config + hash
• BenchmarkModelSpec explicite au lieu de AgentModelSelector
• Scoring V1 objectif uniquement (pas de juge LLM)