PokemonRedRLModel

From-scratch reinforcement learning agent for Pokémon Red, built against PyBoy + Gymnasium + Stable-Baselines3 and sized for a 6-core desktop. The full implementation plan, phase gates, and design decisions live in docs/plan.md.

Layout

Source lives in this repo (OneDrive-synced, git-tracked). Heavy artifacts live outside OneDrive:

C:\ml\pokered\
  .venv\               Python 3.12 virtualenv
  roms\PokemonRed.gb   supplied by the developer, never committed
  runs\                checkpoints
  tb\                  TensorBoard logs

Setup

Always use the venv's explicit interpreter path. Bare python on this machine resolves to 3.14, which has no wheels for the compiled dependencies.

To rebuild the environment exactly, use the lockfile:

py -3.12 -m venv C:\ml\pokered\.venv
C:\ml\pokered\.venv\Scripts\python.exe -m pip install --upgrade pip
C:\ml\pokered\.venv\Scripts\pip.exe install -r requirements.lock --extra-index-url https://download.pytorch.org/whl/cu126

For a fresh (unpinned) install, everything goes in one command with the CUDA index as an extra:

C:\ml\pokered\.venv\Scripts\pip.exe install pyboy gymnasium "stable-baselines3[extra]" numpy scikit-image einops pytest tensorboard torch --extra-index-url https://download.pytorch.org/whl/cu126

Do not install torch first and the rest afterwards. That was tried: SB3's resolver required a newer torch and silently replaced the CUDA build with the CPU-only PyPI wheel (imports fine, trains on CPU). A single resolution pass with --extra-index-url picks the +cu126 wheel because its local version outranks the plain one. Verify with the Gate 0 check in docs/plan.md, which asserts Python 3.12 and torch.cuda.is_available().

ROM: place your legally obtained copy at C:\ml\pokered\roms\PokemonRed.gb. Required sha1: ea9bcae617fdf159b045185467ae58b2e4a48b9a.

Version control

All git write operations (add, commit, push, everything) are performed by Carter only. AI coding agents working in this repo are restricted to read-only git commands. See docs/plan.md §10.

Attribution

src/pokered_rl/data/map_data.json is MIT-licensed third-party data — see THIRD_PARTY.md. Everything else is original code.