Chipiron

Chipiron is a Python framework for game-playing agents, generic tree search and learned state evaluators. It supports chess, Morpion Solitaire (5T), checkers and integer reduction. Game-specific code lives under src/chipiron/environments/; Morpion's evaluator/training/bootstrap implementation is under its morpion/ subdirectory.

The proposed canonical line is maintenance/chipiron-canonicalization, intended to become main after review. GitHub's current main is historical until that PR is merged. The integration preserves all generic-game history and the cleaned September evaluator work; see the ancestry and audit.

Store new experiments, models, datasets and run logs outside this checkout, using configuration-driven paths. See artifact policy, dependency provenance, and the small maintenance backlog. The dependency document also records the unpublished Coral prerequisite that currently blocks release.

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, installed from PyPI as parsley-coco and imported in Python as parsley.

• 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
git switch maintenance/chipiron-canonicalization  # until its reviewed merge into main
cp .env.example .env  # optional local path overrides; never commit this file
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

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

The canonical quality gate is tox. It builds and installs the wheel with published dependencies, verifies installed import paths and evaluator/checkpoint contracts, selects tests without the integration or external_data markers, and checks repository-wide Ruff format/lint. Pylint, mypy and Pyright report inherited debt; the static-analysis ratchet fails on new diagnostics or baseline growth. A ratchet pass does not mean zero static-analysis errors.

tox

If tox is not installed in your active Python 3.13 environment:

python -m pip install -e '.[dev]'

Useful focused runs:

tox -e tooling
tox -e py313
tox -e ruff
tox -e static
# Optional strict reports, which still fail on inherited debt:
tox -e lint
tox -e typecheck

Tool versions for Ruff, Pylint, mypy, Pyright, tox, Black, build, and pre-commit are pinned in pyproject.toml. tox -e tooling checks that CI and pre-commit stay aligned with those pins.

For local IDEs, pre-commit, or manual commands outside tox, install the same development extras into your active Python 3.13 environment:

python -m pip install -e '.[test,lint,typecheck,dev]'

Then you can run the normal fast test selection directly:

python -m pytest -m "not integration and not external_data"

Ruff does not auto-fix in the default quality gates. To rewrite files intentionally, run explicit fix commands:

python -m ruff check --fix src/chipiron tests
python -m ruff format src/chipiron tests

Coverage

Some integration tests spawn subprocesses, including full Chipiron runs. To ensure coverage is collected from those processes, coverage is configured in pyproject.toml with patch = ["subprocess"].

The pytest defaults already enable coverage. To spell out the same command:

python -m pytest --cov=chipiron --cov-config=pyproject.toml --cov-report=term-missing

If coverage appears empty, ensure:

• tests are not bypassing Python execution
• subprocesses are standard Python processes

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, use the extras declared in pyproject.toml:

python -m pip install -e '.[test,lint,typecheck,dev]'

This includes tools for:

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

The pre-commit hooks use the pinned Ruff from your active Python environment, so install the development extras before installing the hooks:

pre-commit install

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.