chipiron 0.2.2

chipiron plays chess

Chipiron

Chipiron is a Python library that plays chess

Acknowledgments

• Built on top of python-chess and its Rust version shakmaty
• Integrates code from chessboardjs in the website

Play Online against Chipiron

Play at this website !

---

Related Projects

Chipiron integrates and builds upon other personal repositories:

• shakmaty_python_binding: Python bindings for the Rust chess library shakmaty.

• parsley_coco: A generic parsing library.

• chipiron-website: Source code for the website where you can play against Chipiron online.

---

Quickstart

git clone https://github.com/victorgabillon/chipiron.git
cd chipiron
make init
python3 -m chipiron.scripts.main_chipiron

---

Requirements

• Python 3.13
• pip
• curl
• tkinter
• make
• libxcb-cursor0
• zstd (for decompressing Lichess PGN databases)
• cc (or else to build some rust dependencies)

Optional:

• Stockfish chess engine (can be installed with make stockfish)

Installation

Using Make

This will install Python dependencies, download syzygy tables, retrieve datasets, and GUI images:

make init

Optional: Install Stockfish Chess Engine

If you want to use the integrated Stockfish player for stronger AI opponents:

make stockfish

This downloads and installs Stockfish 16 (~40MB) to the correct location for chipiron integration.

(Optional) Using Conda

Click here for detailed instructions with conda

git clone https://github.com/victorgabillon/chipiron.git
cd chipiron
conda create --name chipiron3.13 python==3.13
conda activate chipiron3.13
conda install -c conda-forge tk=*=xft_* # to fix graphical problems with tkinter
make init

---

Docker

The Chipiron Docker image is published to Docker Hub.

Simply pull the image

docker pull victorgabillon/chipiron:latest

Or, build the Docker image:

docker build -t chipiron-x11 .

To run the Docker container with GUI:

sudo docker run --rm \
  -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  --network=host \
  -u $(id -u):$(id -g) \
  <image_name>

Usage

Every script should be run via main_chipiron.py and run from the ROOT_FOLDER. The type of script can be specified via the argument --script_name. Yaml config file can be specified via --config_file_name.

Base case with a GUI to play against chipiron or watch it play

Starts a gui to choose your options of play.

python3 -m chipiron.scripts.main_chipiron

Other Scripts:

One match:

This allows to play a match between two players.

python3 -m chipiron.scripts.main_chipiron --script_name one_match --config_file_name src/chipiron/scripts/one_match/inputs/base/exp_options.yaml

League

This allows to run a league of selected players and compute their Elo ratings.

python3 -m chipiron.scripts.main_chipiron --script_name league

Lean a NN from a labelled dataset

This learns Neural Networks from a database of labelled boards.

python3 -m chipiron.scripts.main_chipiron --script_name learn_nn --config_file_name src/chipiron/scripts/learn_nn_supervised/exp_options.yaml

---

Documentation

Full documentation is available at chipiron.readthedocs.io.

To build and view the documentation locally:

cd docs
make clean
make html
xdg-open _build/html/index.html

---

Testing

Run all tests with:

tox

or

pytest

Integration Testing

For complete end-to-end validation, use the integration test scripts that test the entire installation process in a clean environment:

# Python version (comprehensive logging and reporting)
python scripts/integration_test.py

# Shell version (lightweight and fast)
./scripts/integration_test.sh

# Test with custom repository
python scripts/integration_test.py --repo-url https://github.com/your-fork/chipiron.git

# Keep temporary files for debugging
python scripts/integration_test.py --keep-temp --verbose

These scripts:

• Create a temporary conda environment
• Clone the repository fresh
• Run complete makefile installation
• Test all components (Stockfish, Syzygy tables, GUI, chess functionality)
• Generate detailed reports

See scripts/README.md for detailed documentation.

---

Contributing

Please open issues or pull requests on GitHub.

Development Requirements:

For development and testing, additional dependencies are listed in requirements_dev.txt:

pip install -r requirements_dev.txt

This includes tools for:

• Type checking (mypy)
• Linting (pylint, ruff)
• Testing (pytest, tox)
• Documentation building (sphinx)
• Code formatting and development tools

For the prehook to work pleas run

pre-commit install # precommit is supposed to be pip-installed from requirements_dev.txt

---

License

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.

---

Contact

For questions or support, please open an issue.