amazing/README.md

A Maze Ing

Un générateur et solveur de labyrinthe en Python avec interface MLX (2D pixels), accompagné de code robuste, tests et typage statique.

Description

A Maze Ing vise à implémenter un ensemble de fonctionnalités complètes pour la génération, représentation et résolution d’un labyrinthe, dans un contexte pédagogique :

• génération de labyrinthe avec deux algorithmes classiques (DepthFirstSearch et Kruskal);
• représentation textuelle et structurelle de la grille via Cell et Maze;
• solveurs (DepthFirstSearchSolver, AStar) pour retrouver un chemin source/target;
• interface graphique avec mlx pour visualiser en temps réel.

Le but est de coder un moteur de maze complet, testable et maintenable, tout en appliquant des pratiques modernes (typing, tests, CI via Makefile).

Objectifs

• comprendre et placer les algorithmes de génération dans un pipeline complet
• offrir un usage reproductible via config + API
• démontrer la compatibilité avec pytest et mypy
• fournir un produit avec UI interactive et animation de chemin

Instructions

Prérequis

• Python 3.10+
• Numpy, Pydantic, Pytest, Mypyc/ Mypy, Flake8, mlx (via distribution locale mlx-2.2-py3-none-any.whl)

Installation

git clone <url> amazing
cd amazing
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip setuptools
pip install -r requirements.txt  # si présent, sinon :
pip install pydantic numpy pytest mypy
pip install mlx-2.2-py3-none-any.whl

Exécution

• Direct :

  PYTHONPATH=src python3 a_maze_ing.py config.txt
  

• Make :

  make run
  

Tests

PYTHONPATH=src pytest

Lint / mypy

make lint
make lint-strict

ou

PYTHONPATH=src python3 -m mypy --warn-return-any --warn-unused-ignores --ignore-missing-imports --disallow-untyped-defs --check-untyped-defs -p mazegen -p AMazeIng

Structure du projet

• a_maze_ing.py : point d’entrée CLI / application MLX.
• src/AMazeIng.py : modèle Pydantic + orchestration Maze/MazeGenerator/MazeSolver.
• src/mazegen/Cell.py : classe Cell (int bitmask) + méthodes accès.
• src/mazegen/Maze.py : stockage et opérations sur la grille.
• src/mazegen/MazeGenerator.py : interfaces + DepthFirstSearch, Kruskal.
• src/mazegen/MazeSolver.py : DepthFirstSearchSolver, AStar.
• src/parsing/Parsing.py : lecture et validation du config.txt.
• tests/ : tests unitaires.
• Makefile : cibles build/install/run/lint.

Config file (complète)

• config.txt doit contenir au moins :
  • largeur/hauteur
  • entrée et sortie (coordonnées 1-based)
  • nom du solveur, nom du générateur
  • paramètres de visualisation.

(Le parser src/parsing/Parsing.py gère la validation et erreur 1/2/3 etc.)

Algorithme de génération choisi

• Kruskal (fusion d’ensembles) comme méthode principale.
• DepthFirstSearch (backtracking) complémentaire.

Pourquoi Kruskal

• génère un labyrinthe parfait, totalement plein sans cycles, très lisible.
• bonne base pour unperfect_maze (possibilité de briser des murs).
• facile à tester et à raisonner, code modulaire.

Reusable code

• Cell et Maze peuvent servir à n’importe quelle appli de grille / labyrinthes.
• MazeGenerator / MazeSolver sont des interfaces réutilisables pour autres implémentations.
• Parsing est un parser général de config (validation Pydantic).

Usage / features avancées

• supports perfect ou imperfect (avec openning randomisé)
• render loop avec maj dynamique et chemins animés
• switch generator/solver à l’exécution
• couleur de chemin et patterns (42)

Resources

• Documentation python : https://docs.python.org/3/
• Mypy : https://mypy.readthedocs.io/
• Pydantic : https://docs.pydantic.dev/
• Algorithme labyrinthe : https://en.wikipedia.org/wiki/Maze_generation_algorithm
• A* : https://en.wikipedia.org/wiki/A*_search_algorithm
• Tutoriel DFS / Kruskal maze : https://weblog.jamisbuck.org/2011/1/16/maze-generation-depth-first-search

IA utilisée

• Copilot Chat (Raptor mini) : aide à :
  • correction d’erreurs mypy / import module
  • refactorisation import from mazegen.Cell import Cell
  • création du README complet
  • recommandations de workflow et tests

Équipe et gestion de projet

• Dev unique ou équipe réduite (à préciser) :
  • Rôles : dev, tests, doc, releases.
• Planning anticipé :
  • 1 semaine : structure + model
  • 1 semaine : générateur + solveur
  • 1 semaine : interface MLX + tests
  • 1 semaine : typage / CI / docs
• Ce qui a bien marché :
  • architecture modulaire, tests automatisés
  • apprentissage sur typage et mypy
• Améliorations possibles :
  • ajout d’une UI web/SDL
  • stubs type pour mlx
  • config utilisateur plus riche / JSON

Outils

• Python 3.10
• pytest, mypy, flake8
• uv/make
• Mlx (graphique)
• Git + GitHub

---

Carte de sortie : ce README inclut toutes les parties demandées et est orienté projet complet A-Z.

🚀 Installation

1. Cloner le dépôt :

   git clone <url> amazing
   cd amazing
   

2. Créer un environnement :

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -U pip setuptools
   pip install -r requirements.txt  # si présent ; sinon pip install pydantic numpy pytest mypy
   

▶️ Exécution

• Mode commande :

  PYTHONPATH=src python3 a_maze_ing.py config.txt
  

• Avec Makefile :

  make run
  

Le programme ouvre une fenêtre MLX et affiche le labyrinthe généré ; contrôles :

• 1 : regénérer
• 2 : afficher le chemin
• 3 : changer la couleur
• 4 : quitter

🧪 Tests

• Lancer tous les tests :

  PYTHONPATH=src pytest
  

• Fichiers de tests existants :
  • tests/test_Cell.py
  • tests/test_Depth.py
  • tests/test_Maze.py
  • tests/test_MazeGenerator.py
  • tests/test_MazeSolver.py
  • tests/test_parsing.py

🧹 Lint / typage

• Flake8 + MyPy (configuration dans Makefile)

  make lint
  make lint-strict
  

• Sur le projet, utilisez ces commandes :

  PYTHONPATH=src python3 -m mypy --warn-return-any --warn-unused-ignores --ignore-missing-imports --disallow-untyped-defs --check-untyped-defs -p mazegen -p AMazeIng
  

Problèmes connus

• mypy en mode strict détecte :
  • mlx non typé, donc no-untyped-call (bibliothèque native sans stub)
  • AMazeIng identifié comme module installé sans py.typed pour l’autocomplétion stricte.

🛠️ Architecture

• Cell : gestion binaire des murs (N, E, S, W).
• MazeGenerator.DepthFirstSearch : génération récursive avec backtracking.
• MazeGenerator.Kruskal : génération via graphe d’ensembles disjoints.
• MazeSolver.DepthFirstSearchSolver : recherche DFS.
• MazeSolver.AStar : recherche A* avec heuristique Manhattan.

📝 Notes

• Préférer des imports relatifs depuis src :
  • from mazegen.Cell import Cell plutôt que from mazegen import Cell pour éviter les conflits module is not valid as type.
  • from parsing.Parsing import DataMaze pour la configuration.
• Le code est déjà prêt pour packaging avec pyproject.toml / setup.cfg.

📦 Distribution

• Makefile contient cible build générant 1 roue .whl via uv build.
• install|run sont inclus.

---

Projet maintenu en mode éducatif. Contribution bienvenue via issues et PR.