Metadata-Version: 2.4
Name: persona-chess
Version: 0.1.0
Summary: Train lightweight chess personas from PGN files.
Project-URL: Homepage, https://github.com/brutalstein/persona-chess
Project-URL: Repository, https://github.com/brutalstein/persona-chess
Project-URL: Issues, https://github.com/brutalstein/persona-chess/issues
Project-URL: Changelog, https://github.com/brutalstein/persona-chess/blob/main/CHANGELOG.md
Author: Persona Chess Contributors
License: MIT
License-File: LICENSE
Keywords: chess,imitation-learning,machine-learning,persona,pgn
Classifier: Development Status :: 2 - Pre-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: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Provides-Extra: ml
Requires-Dist: peft>=0.13.0; extra == 'ml'
Requires-Dist: safetensors>=0.4.0; extra == 'ml'
Requires-Dist: torch>=2.2.0; extra == 'ml'
Description-Content-Type: text/markdown

# persona-chess

`persona-chess` is a Python library for training lightweight chess personas from PGN
files. The goal is not to find the strongest move. The goal is to predict how a
specific player is likely to move.

The current foundation includes PGN ingestion, player filtering, versioned move
datasets, game-level train/test splits, profile reports, baseline persona models,
JSON artifacts, and a CLI. The model layer is intentionally modular so a
chess-native Transformer + LoRA backend can be added without changing the product
surface.

## Install

After the first PyPI release:

```bash
pip install persona-chess
pip install "persona-chess[ml]"
```

Until then, install directly from GitHub:

```bash
pip install git+https://github.com/brutalstein/persona-chess.git
pip install "persona-chess[ml] @ git+https://github.com/brutalstein/persona-chess.git"
```

For local development:

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

## Python API

```python
from persona_chess import PersonaChess

persona = PersonaChess().fit_pgn("games.pgn", player="Target Player")
persona.save("target-player.persona.json")

prediction = persona.predict("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1")
print(prediction[0].san)
```

## CLI

```bash
persona-chess profile games.pgn "Target Player"
persona-chess train games.pgn "Target Player" --model-type blend --out target-player.persona.json
persona-chess move target-player.persona.json --fen "startpos"
persona-chess export-training games.pgn "Target Player" --out target-player.train.jsonl
persona-chess split games.pgn "Target Player" --train-out train.jsonl --test-out test.jsonl
persona-chess benchmark games.pgn "Target Player" --model-type blend --out benchmark.json
persona-chess prepare-neural games.pgn "Target Player" --manifest-out adapter.manifest.json --move-vocab-out moves.vocab.json --position-vocab-out positions.vocab.json
persona-chess validate-neural adapter.manifest.json moves.vocab.json positions.vocab.json
persona-chess train-neural games.pgn "Target Player" --checkpoint-dir checkpoints/player --use-lora
persona-chess neural-move checkpoints/player --fen "startpos"
```

Built-in model backends:

- `blend`: weighted baseline combining exact position memory, opening book, and phase priors.
- `frequency`: exact position memory with global legal fallback.
- `opening_book`: early-game repertoire memory.
- `phase`: game-phase move prior for opening, middlegame, and endgame positions.

## Project Direction

The planned model path is:

1. A clean PGN-to-position dataset pipeline.
2. Deterministic train/test splitting at game level.
3. Strong baseline models for honest comparison.
4. A chess-native base Transformer trained on large public PGN data.
5. A training JSONL schema with legal move masks and target move indexes.
6. Per-player LoRA adapters trained from personal PGNs.
7. Legal move masking through `python-chess`.
8. Evaluation by move-match accuracy and style similarity metrics.

The neural command currently prepares versioned adapter manifests, move
vocabularies, and position vocabularies. The package also includes an optional
PyTorch Transformer policy skeleton behind the `ml` extra, with PEFT-powered LoRA,
legal-masked policy batches, checkpoint helpers, and checkpoint inference. It is not
enabled for standard installs.

## License

MIT
