RookForge ML

rookforge-ml is a Python toolkit for building chess bot training pipelines. It provides training-friendly board encoders, an AlphaZero-style policy action space, PGN/FEN data helpers, and optional PyTorch integration without making PyTorch a required dependency.

The package is intentionally small in v1: it uses python-chess for rules correctness and focuses on reliable tensor interfaces that can feed neural networks and RL experiments.

Install

pip install rookforge-ml

For local development:

pip install -e ".[dev]"

For PyTorch helpers:

pip install -e ".[torch]"

Quick Start

import chess

from chess_tools.actions import legal_mask, move_to_index
from chess_tools.encoding import encode_board

board = chess.Board()
planes = encode_board(board)
mask = legal_mask(board)
policy_index = move_to_index(chess.Move.from_uci("e2e4"), board)

print(planes.shape)  # (106, 8, 8) by default
print(mask.shape)    # (4672,)
print(policy_index)

Core APIs

• chess_tools.encoding: AlphaZero-style board and history encoders.
• chess_tools.actions: 64 * 73 policy action encoding, legal masks, and UCI helpers.
• chess_tools.data: PGN/FEN readers and streaming supervised samples.
• chess_tools.torch: optional PyTorch dataset/collation utilities.

Development

python -m pip install -e ".[dev,benchmark]"
python -m ruff check .
python -m pytest
python -m pytest tests/test_benchmarks.py --benchmark-only --benchmark-min-rounds=5
python -m build
python -m twine check dist/*

The GitHub Actions workflow runs lint, tests, package build, metadata checks, and a benchmark smoke job.

Release

Revoke any token that was pasted into a terminal log or chat, then create a fresh PyPI API token. For token authentication, Twine must use __token__ as the username. The release script sets that for child Twine uploads when TWINE_PASSWORD starts with pypi-.

$env:TWINE_PASSWORD = "pypi-YOUR_NEW_API_TOKEN"

.\scripts\release.ps1 -Part patch -Upload

Useful variants:

.\scripts\release.ps1 -DryRun
.\scripts\release.ps1 -Version 0.2.0 -Upload
.\scripts\release.ps1 -Part patch -Upload -Repository testpypi
.\scripts\release.ps1 -Part patch -Upload -RunBenchmarks

If PyPI returns 400 Bad Request, the script runs Twine with --verbose so the server response should include the actual reason. Common causes are a version that was already uploaded, a package name that PyPI considers too similar to an existing project, or invalid metadata that Twine did not catch locally.

The PyPI distribution name is rookforge-ml; the Python import package remains chess_tools.

Design Notes

• Board planes are encoded from the side-to-move perspective.
• Current position planes come first, then older history planes.
• The policy action space uses 56 queen-like moves, 8 knight moves, and 9 underpromotion moves per origin square.
• python-chess remains the source of truth for legal move generation and game rules.