feat: initial maze-ml GA visualizer

README.md

@@ -0,0 +1,37 @@
+# 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
+
+```bash
+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.