maze-ml/README.md

maze-ml

100 neural-network agents learn to navigate a maze using a Genetic Algorithm — animated in real time with pygame.

Inspired by the "AI learns to..." YouTube Shorts format.

Quick start

pip install -r requirements.txt
python main.py

Options

Flag	Default	Description
--fast	off	Train without rendering, show result at end
--generations	200	Number of GA generations
--maze-size	25	Maze dimensions (NxN)
--seed	random	Maze seed for reproducibility
--speed	60	FPS cap for visual mode

Architecture

• config.py — all hyperparameters as a dataclass
• maze.py — iterative DFS maze generation (bitmask cells)
• agent.py — Agent + tiny NeuralNet (8→12→4, pure numpy)
• genetic.py — tournament selection, uniform crossover, gaussian mutation
• visualizer.py — pygame renderer with trail decay, fitness-ranked colors, HUD
• main.py — training loop + argparse

How it works

Each generation, 100 agents simultaneously traverse the maze controlled by small neural networks (8 inputs → 12 hidden → 4 outputs). Fitness rewards progress toward the goal and reaching it. The top 30% of agents are selected as parents for the next generation via tournament selection.

After ~20–50 generations, agents learn to reliably navigate the maze.