Metadata-Version: 2.4
Name: rookforge-ml
Version: 0.1.1
Summary: Training-oriented chess encoders, action spaces, and dataset utilities.
Project-URL: Homepage, https://github.com/Nickm1128/ChessTools
Project-URL: Repository, https://github.com/Nickm1128/ChessTools
Author: Nick M
License-Expression: MIT
License-File: LICENSE
Keywords: chess,machine-learning,pytorch,reinforcement-learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment :: Board Games
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: chess>=1.11.0
Requires-Dist: numpy>=1.24
Provides-Extra: benchmark
Requires-Dist: pytest-benchmark>=4.0; extra == 'benchmark'
Provides-Extra: data
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: torch
Requires-Dist: torch>=2.2; extra == 'torch'
Description-Content-Type: text/markdown

# 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

```bash
pip install rookforge-ml
```

For local development:

```bash
pip install -e ".[dev]"
```

For PyTorch helpers:

```bash
pip install -e ".[torch]"
```

## Quick Start

```python
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

```bash
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-`.

```powershell
$env:TWINE_PASSWORD = "pypi-YOUR_NEW_API_TOKEN"

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

Useful variants:

```powershell
.\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.
