38 lines
1.4 KiB
Markdown
38 lines
1.4 KiB
Markdown
# 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.
|