retro-gamer: train agents to play retro games
==============================================

``retro-gamer`` is a Python package for training reinforcement learning
agents to play games implemented with the
`retro-games <https://retro-games.readthedocs.io/en/latest/>`__
framework. It is designed as a learning tool: rather than writing the
learning algorithm yourself, you describe the game to the trainer in a
structured way, adjust the training parameters, and then observe—through
a detailed log—how the trainer uses your description to build and run a
learning model.

The central idea is that the game becomes an *object to think with*
about reinforcement learning. The choices you make—which characters to
tell the trainer about, what counts as a reward, whether to treat the
board as a spatial scene or a readout—have direct, observable
consequences for how learning proceeds. Working out *why* a training run
behaves as it does is the kind of reasoning that leads to lasting
understanding of the underlying concepts.

.. _installation:

Installation
------------

Prerequisites
~~~~~~~~~~~~~

``retro-gamer`` requires Python 3.11 or higher and a game implemented
with `retro-games <https://retro-games.readthedocs.io/en/latest/>`__.
The retro-games framework must also be installed; see its documentation
for instructions.

If you are working through a Making With Code lab, ``retro-gamer`` is
already installed in your project environment — skip ahead to
:ref:`installation`.

**Add to a project** using ``uv`` or ``pip``:

.. code-block:: console

   % uv add retro-gamer
   % pip install retro-gamer

**Install as a global tool** (available everywhere, no project needed):

.. code-block:: console

   % uv tool install retro-gamer

Verify the installation by checking the command-line tool:

.. code-block:: console

   % retro-gamer --help
   Usage: retro-gamer [OPTIONS] COMMAND [ARGS]...

     Train and run RL agents for retro games.

   Commands:
     create  Create a new training run directory with config.toml.
     info    Print a summary of a training run.
     play    Watch a trained agent play the game.
     train   Train (or resume training) a DQN agent.

.. toctree::
   :maxdepth: 1
   :caption: Contents:

   introduction
   background
   walkthrough
   troubleshooting
   reference
   integration
   api
   contributing