AI Plays Pokémon (PTP-01X)

Autonomous Pokémon AI benchmarking system using PyBoy 2.7.0 emulator with RAM-based game state reading, GOAP hierarchical planning, and LLM-driven decision making.

Quick Start

# Setup
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run tests
pytest tests/ -v

# Start RAM map viewer
python ram_map_server.py
# Then open http://localhost:8099

# Run autonomous game loop
python cron_runner.py

Architecture

• RAM Reader (src/core/ram_reader.py) — Reads game state directly from emulator memory (instant, no LLM cost)
• Emulator (src/core/emulator.py) — PyBoy wrapper with read_u8/read_u16, tick, screenshot
• GOAP Planner (src/core/goap.py) — Hierarchical goal-oriented action planning
• State Machine (src/core/state_machine.py) — 50+ gameplay states with hierarchical transitions
• State Window (src/core/state_window.py) — AI decision context window for LLM prompts
• Vision Pipeline (src/core/vision/) — Screenshot preprocessing, sprite detection, OCR, location detection
• Database (src/core/db/) — SQLite session metrics, screenshots, AI thoughts, commands
• Cron Runner (cron_runner.py) — Autonomous game loop with RAM reader or vision cartographer

Test Suite

# Full suite (3357 tests, 8 skipped)
pytest tests/ -v

# Fast run (skip ROM/API tests)
pytest tests/ -x -q --tb=short -k "not rom and not live"

# With coverage
pytest tests/ -v --cov=src --cov-report=html --cov-report=term-missing

# Parallel
pytest tests/ -n auto -v

Lint & Type Check

ruff check src/
ruff check --fix src/
mypy --strict src/

Key Files

ROM

Place Pokémon Red .gb ROM at data/rom/pokemon_red.gb.