ChessHacks Starter Bot

This is a starter bot for ChessHacks. It includes a basic bot and devtools. This is designed to help you get used to what the interface for building a bot feels like, as well as how to scaffold your own bot.

Directory Structure

/devtools is a Next.js app that provides a UI for testing your bot. It includes an analysis board that you can use to test your bot and play against your own bot. You do not need to edit, or look at, any of this code (unless you want to). This file should be gitignored. Find out why here.

/src is the source code for your bot. You will need to edit this code to implement your own bot.

serve.py is the backend that interacts with the Next.js and your bot (/src/main.py). It also handles hot reloading of your bot when you make changes to it. This file, after receiving moves from the frontend, will communicate the current board status to your bot as a PGN string, and will send your bot's move back to the frontend. You do not need to edit any of this code (unless you want to).

While developing, you do not need to run either of the Python files yourself. The Next.js app includes the serve.py file as a subprocess, and will run it for you when you run npm run dev.

The backend (as a subprocess) will deploy on port 5058 by default.

This architecture is very similar to how your bot will run once you deploy it. For more information about how to deploy your bot to the ChessHacks platform, see the docs.

Setup

Start by creating a Python virtual environment and installing the dependencies:

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

or however you want to set up your Python.

Then, install the dependencies for the Next.js app:

cd devtools
npm install

Afterwards, make a copy of .env.template and name it .env.local (NOT .env). Then fill out the values with the path to your Python environment, and the ports you want to use.

Copy the .env.local file to the devtools directory as well.

Installing devtools (if you did not run npx chesshacks create)

If you started from your own project and only want to add the devtools UI, you can install it with the CLI:

npx chesshacks install

This will add a devtools folder to your current directory and ensure it is gitignored. If you want to install into a subdirectory, you can pass a path:

npx chesshacks install my-existing-bot

In both cases, you can then follow the instructions in Setup and Running the app from inside the devtools folder.

Running the app

Lastly, simply run the Nextjs app inside of the devtools folder.

cd devtools
npm run dev

Troubleshooting

First, make sure that you aren't running any python commands! These devtools are designed to help you play against your bot and see how its predictions are working. You can see Setup and Running the app above for information on how to run the app. You should be running the Next.js app, not the Python files directly!

If you get an error like this:

Traceback (most recent call last):
  File "/Users/obama/dev/chesshacks//src/main.py", line 1, in <module>
    from .utils import chess_manager, GameContext
ImportError: attempted relative import with no known parent package

you might think that you should remove the period before utils and that will fix the issue. But in reality, this will just cause more problems in the future! You aren't supposed to run main.py on your own—it's designed for serve.py to run it for you within the subprocess. Removing the period would cause it to break during that step.

Logs

Once you run the app, you should see logs from both the Next.js app and the Python subprocess, which includes both serve.py and main.py. stdouts and stderrs from both Python files will show in your Next.js terminal. They are designed to be fairly verbose by default.

HMR (Hot Module Reloading)

By default, the Next.js app will automatically reload (dismount and remount the subprocess) when you make changes to the code in /src OR press the manual reload button on the frontend. This is called HMR (Hot Module Reloading). This means that you don't need to restart the app every time you make a change to the Python code. You can see how it's happening in real-time in the Next.js terminal.

Training an ML chess bot on Modal

This repo now includes a simple neural-network chess bot and a Modal training pipeline.

Data source

• The training script streams public human games from the Lichess standard database, which is released under CC0.
• By default it uses lichess_db_standard_rated_2024-03.pgn.zst, but you can override the URL with the LICHESS_PGN_URL environment variable.

Model architecture

• A lightweight feedforward policy network that scores (board, move) pairs.
• Board features: piece planes (12 × 8 × 8), side to move, castling rights, en passant file, and normalized move count.
• Move features: from/to square coordinates, capture/promotion flags, and promotion type.

Training on Modal

Prerequisites:

• A Modal account and the modal CLI installed.

Steps:

1. From the repo root (or my-chesshacks-bot directory), run:

   modal run my-chesshacks-bot/train_modal.py::train

   This will:

   • Build a Modal image with torch, python-chess, zstandard, and requests
   • Stream games from Lichess
   • Train the policy network
   • Save the weights to /models/policy_latest.pt in the persistent volume chess-policy-models

2. After training, download the model to your local repo:

   modal volume get chess-policy-models /models/policy_latest.pt my-chesshacks-bot/model/policy_latest.pt

3. When you run the devtools UI, src/main.py will automatically load the model from my-chesshacks-bot/model/policy_latest.pt (or from the path in CHESS_MODEL_PATH if set) and use it to select moves. If no model file is found, the bot falls back to a random legal move policy.