Explainable Chess Engine

A minimalist DL chess engine with explainability.

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Objectives
   • Roadmap
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. License
5. Contact

About The Project

This project aim to build a minimalist Deep Learning chess engine with explainability. The goal is to create a chess engine that can explain its decisions in a human-readable way. This project will be a great way to learn about chess engines, deep learning, and explainability in AI.

Objectives

• Build a Deep Learning framework optimized for training with chess data.
• Monitor the performance of the training framework to optimize training time, CPU/GPU usage, and memory usage.
• Demonstrate proficiency in PyTorch, Tensorflow, Keras and Jax.
• Build the best model with the minimal number of parameters for several ELO levels.
• Create a human-readable explanation of the model's decisions.
• Implement a chess engine that can play against human or AI players using the model.

Roadmap

• Create the project structure
• Pytorch Framework
  • Custom pytorch dataset for chess data
    • Read any board state at any game number in a PGN file
    • Convert board, moves and game result to tensor
    • Batch all operations
    • Tests
  • Training loop & utilities for training
    • Training loop
    • Logging & Tensorboard
    • Evaluation
    • Save & Load model
    • Tests for training framework
• Tensorflow Framework
  • Custom TFRecords for chess data
    • Read any board state at any game number in a PGN file
    • Convert board, moves and game result to tensor
    • Batch all operations
    • Tests
• Chess Engine
  • Beam Search using the DL models
  • Implement matches
  • Evaluate against Stockfish
  • Tests for the chess engine
• Explainability
  • Beam Search visualization
  • Board evaluation visualization
• Deployment
  • Dockerize the project
  • Deploy on Lichess
  • Deploy on HuggingFace

Getting Started

Prerequisites

You need to have Python 3.11 installed on your machine.

Installation

1. Clone the repo

   git clone https://github.com/dechantoine/explainable-chess-engine.git

2. Install the project dependencies using Poetry.

   poetry install

Test package

Run unit tests

poetry run python -m pytest

Run performance tests

poetry run python -m profiling.profile dataset --n_test=10 --data_dir=data --save_dir=profile

poetry run python -m profiling.profile match --n_test=10 --save_dir=profile --max_workers=8

Visualize performance tests

poetry run snakeviz profile/dataset.prof

Usage

Train a model

poetry run python -m src.train.train rl --run_name=run_name --dataset_num_workers=8 --dataloaders_num_workers=2 --train_size=0.9 --n_epochs=20 --batch_size=64 --lr=0.1 --gamma=0.99 --log_sampling=0.05 --eval_sampling=1.0 --checkpoint_dir=checkpoints --log_dir=logdir

Launch Tensorboard

poetry run tensorboard --logdir=logdir

Launch Gradio demo

poetry run python -m demos.app

Deployment

Deploy on HuggingFace Spaces

poetry run python -m scripts.deploy_space

Contact

@dechantoine - dechantoine@gmail.com