[Spec] PPO fiable, Circuit démontrable et comparaison Double DQN

[salim4n]

PPO fiable, Circuit démontrable et comparaison Double DQN

Statut : spécification et découpage validés par le mainteneur.

Problem Statement

Un visiteur doit attendre un apprentissage incertain avant de comprendre l'intérêt du framework. Les commandes ne suffisent pas à distinguer réussite, entraînement et généralisation. Le raccordement actuel de PPO produit des lots unitaires et neutralise l'avantage normalisé : comparer les algorithmes dans ces conditions serait trompeur.

Solution

Fiabiliser PPO, puis proposer sur Circuit une démonstration préentraînée, un entraînement depuis zéro et une évaluation sur un autre circuit. Ajouter ensuite Double DQN et une comparaison reproductible, sans présumer du vainqueur.

User Stories

1. Comme développeur, je veux que PPO apprenne via l'API publique du framework, afin que les exemples correspondent au comportement réel.
2. Comme développeur, je veux distinguer terminaison et troncature pour préserver les cibles d'apprentissage appropriées.
3. Comme utilisateur existant, je veux conserver les environnements utilisant le contrat historique.
4. Comme visiteur, je veux voir une politique préentraînée dès le chargement de la démo.
5. Comme visiteur, je veux savoir que ce modèle est déjà entraîné.
6. Comme visiteur, je veux une erreur explicite si le modèle est indisponible, sans entraînement silencieux de substitution.
7. Comme utilisateur, je veux lancer un entraînement depuis zéro avec une nouvelle politique.
8. Comme utilisateur, je veux arrêter et reprendre l'exécution sans créer de boucles concurrentes.
9. Comme utilisateur, je veux comprendre si une réinitialisation concerne l'épisode ou le modèle.
10. Comme utilisateur, je veux voir les tours réussis, sorties de piste et temps au tour.
11. Comme utilisateur, je veux tester une politique figée sur un circuit inédit.
12. Comme développeur, je veux comparer DQN et Double DQN à budget égal.
13. Comme lecteur des résultats, je veux connaître graines, backend, versions et temps réel.
14. Comme lecteur, je veux voir la dispersion et les échecs, pas seulement le meilleur run.
15. Comme visiteur, je veux que la galerie et sa documentation décrivent les démos réellement disponibles.

Implementation Decisions

• Utiliser la boucle publique d'entraînement comme point principal de validation, avec des tests ciblés des agents pour les équations des cibles.
• Collecter plusieurs transitions PPO avant mise à jour ; gérer le dernier état non terminal, les frontières d'épisodes et les petits lots sans neutraliser systématiquement le signal.
• Étendre le contrat de fin d'épisode de façon compatible ; préserver la signification historique de done pour les consommateurs existants, exposer explicitement les nouveaux signaux aux environnements migrés.
• Séparer les modes démonstration préentraînée, entraînement et évaluation. Seul l'entraînement modifie la politique.
• Identifier les checkpoints par leur version, configuration, provenance et rapport d'évaluation. Aucun checkpoint non évalué n'est présenté comme performant.
• Fixer les circuits d'entraînement, de sélection et de test avant la sélection finale ; conserver les mêmes observations, actions et critères de réussite pour DQN et Double DQN.
• Réutiliser la persistance et les composants existants lorsqu'ils sont compatibles. Un catalogue commun doit alimenter le build et la galerie.
• Garder DQN disponible ; Double DQN sépare sélection et évaluation de la valeur de l'action suivante.
• Budgets proposés pour la comparaison initiale : cinq graines d'entraînement, vingt épisodes d'évaluation par politique, plafond de transitions identique déclaré avant exécution. Présenter les limites de cet échantillon.

Testing Decisions

• Reproduire l'échec PPO via une interaction environnement-agent, puis démontrer l'amélioration d'une politique sur une tâche contrôlée. Ne pas tester seulement la taille d'un buffer.
• Tester terminaison, troncature, frontière de rollout et compatibilité historique. Réutiliser les suites existantes de boucle, auto-configuration, agents et convergence.
• Vérifier que l'inférence et l'évaluation ne modifient pas la politique ; tester les erreurs de chargement et les changements de mode.
• Prouver la différence DQN/Double DQN sur une transition où sélection et évaluation divergent, puis exécuter un benchmark multi-graines.
• Valider visuellement le Circuit dans un navigateur : premier chargement, entraînement, arrêt, réinitialisation, changement de circuit et erreur de checkpoint ; vérifier les erreurs de console.
• Publier les résultats bruts et leur synthèse. Un build vert ne vaut pas preuve d'apprentissage ; aucune promesse de temps de convergence sans mesure.

Out of Scope

Drone progressif, SAC, actions continues, A2C, nouvelles démos, multi-agent, refonte générale des autres démos, déploiement et publication commerciale.

Further Notes

La préparation des tickets et leur implémentation sont des phases distinctes. Aucun benchmark ni contrôle visuel de ce lot n'a encore été exécuté. Les seuils du checkpoint doivent être fixés avant sélection, et l'évaluation peut conclure à une performance insuffisante.