High Score Duel (Python)

Projet de strategie IA pour un jeu de duel en 3 tours, avec moteur deterministe, IA heuristiques, modeles neuronaux et boucle d'apprentissage continu.

Auteur

• Auteur principal et mainteneur: Thomas Faucherre

Vision du projet

L'objectif est de fournir un socle propre pour:

• experimenter des politiques de decision IA sur un jeu court;
• comparer proprement des strategies via benchmark;
• industrialiser la generation, l'entrainement et la validation de NN;
• conserver la compatibilite avec les anciens points d'entree.

Demarrage rapide

Prerequis

• Python 3.10+

Installation

py -3 -m pip install -r requirements.txt

Pour l'interface Qt:

py -3 -m pip install PySide6

Lancer l'application

py -3 main.py

Lancer l'interface graphique Qt

py -3 scripts/gui_qt.py

Structure professionnelle du repository

high_score_duel/
  ai/                      # AI policies and registry
  learning/                # NN creation, data generation, training, continual learning
  cli.py                   # interactive application entrypoint
  game_engine.py           # deterministic game simulation
  tournament.py            # large-scale AI benchmarking
ia/                        # legacy wrappers for backward compatibility
scripts/                   # operational scripts (benchmark, continuous learning)
docs/                      # architecture, theory, methods, operations, presentation
tests/                     # unit tests

Documentation technique

Les descriptifs techniques et commentaires de code sont en anglais.

• Architecture systeme: docs/ARCHITECTURE.md
• Theorie du probleme: docs/THEORY.md
• Methodes de generation des NN: docs/NN_GENERATION_METHODS.md
• Interface graphique Qt: docs/GUI.md
• Procedures operationnelles: docs/OPERATIONS.md
• Presentation executive technique: docs/presentations/PROJECT_PRESENTATION.md
• Hub documentation: docs/README.md
• Resultats candidats et win-rates: RESULTS.md
• Nouveau candidat compact: models/NN_LITE_SOTA_V4.json

Resume theorique (NN)

Pipeline general:

1. generation de dataset synthetique a partir d'un teacher policy
2. projection du state vers un vecteur de features compact (10 dimensions)
3. apprentissage supervise multi-classe (3 actions)
4. evaluation par score tournoi: (wins + 0.5 * draws) / total
5. acceptance/revert en apprentissage continu selon gain minimum

Commandes essentielles

Tests unitaires

py -3 -m unittest discover -s tests -v

Benchmark IA

py -3 scripts/benchmark_ais.py --games 1200 --jobs 6 --seed 42 --names RANDOM REACTIVE SMARTY CONDITIONAL ADVANCED_STRATEGY ELITE_THRESHOLD ALGORITHMIC_META NN_ELITE_V1

Entrainer le candidat compact SOTA

py -3 scripts/train_lite_sota.py --benchmark-games 2000

Apprentissage continu

py -3 scripts/continuous_learning.py --model NN_ELITE_V1 --cycles 30 --epochs-per-cycle 4 --samples 5000

Qualite et gouvernance

• Auteurs: AUTHORS.md
• Changelog: CHANGELOG.md
• CI: .github/workflows/ci.yml

Compatibilite

Ces wrappers restent disponibles:

• main.py
• nn_creator.py
• nn_trainer.py
• ia/*
• scripts/gui_qt.py

Le code neuf doit cibler high_score_duel/*.