# 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.