Metadata-Version: 2.4
Name: pgntools
Version: 0.1.0
Summary: Standalone PGN utilities for chess: repertoire trees, Stockfish annotation, play chances, glyphs and game search
Author-email: Valentin Kantor <kantorvv@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/pgntools/pgntools
Project-URL: Repository, https://github.com/pgntools/pgntools
Project-URL: Issues, https://github.com/pgntools/pgntools/issues
Keywords: chess,pgn,stockfish,repertoire,opening-tree,annotation
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Games/Entertainment :: Board Games
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-chess
Dynamic: license-file

# pgntools

[![PyPI](https://img.shields.io/pypi/v/pgntools.svg)](https://pypi.org/project/pgntools/)
[![Python versions](https://img.shields.io/pypi/pyversions/pgntools.svg)](https://pypi.org/project/pgntools/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/pgntools/pgntools/blob/main/LICENSE)

Standalone PGN utilities for chess, built on [python-chess](https://python-chess.readthedocs.io/) and Stockfish. Tools chain together: build a repertoire from many games, evaluate it, weigh the branches for a trainer, and trace tree lines back to their source games.

## Install

```bash
pip install pgntools
```

That gives you a `pgntools` command with one subcommand per tool, plus a short command per tool:

```bash
pgntools --help              # lists every tool
pgntools findseq --help      # a tool's own arguments
pgn-findseq --help           # the same tool, short form
```

`python -m pgntools.<tool>` works as well and always has — the three routes run the same code.

**Stockfish is not installed by pip.** `annotate` and `playchance` need the binary on the machine; the other four tools never touch an engine. Install it from your package manager or from [stockfishchess.org](https://stockfishchess.org/download/), then point the tools at it:

```bash
pgntools annotate -f repertoire.pgn --engine /path/to/stockfish   # explicit, per run
export STOCKFISH_PATH=/path/to/stockfish                          # or for the whole shell
```

With neither given, the tools look for a `stockfish` on your `$PATH`.

## Tools

| Tool | What it does |
|---|---|
| `repertoire` | Merges all games of a `.pgn`/`.zip` into one variations tree (trimmed `--tail` plies past each line's last branch), optionally pruning moves played in fewer than `--min-games` games, with optional per-move game counts (`--counts`) and percentages (`--prc`). |
| `annotate` | Adds a Stockfish `[%eval]` to every move of a variations tree, marks the engine's best move `!` (adding it as a variation if missing) and every other move with its `loss` and `?!`/`?`/`??`. Resumable — stop with Ctrl-C, rerun to continue. |
| `playchance` | Weighs each choice at every junction of a variations PGN with a lichess-tools play chance `prc:N` (sums to 100), from one MultiPV search per junction. Rerunning with other `--spread`/`--min-prc`/`--max-loss` re-weighs without searching again. |
| `glyphs` | Engine-free NAG annotator for an eval'd PGN (e.g. a game-anal analysis export): `??`/`?`/`?!` by loss thresholds, missed mates, plus `!`, only-move `□` and sacrifice `!!`/`!?` glyphs. |
| `gamequery` | Given a move line of a merged repertoire tree, finds the original games that played it. |
| `findseq` | Searches a multigame `.pgn`/`.zip` for the games whose mainline contains a SAN move sequence, at any ply. |

## Usage

```bash
pgntools repertoire -f capablanca_all.pgn -t 2 --counts --min-games 10 -o capablanca.repertoire.pgn
pgntools annotate   -f capablanca.repertoire.pgn -d 25 -s 60
pgntools playchance -f capablanca.repertoire.pgn -d 25 -s 60 --side black
pgntools glyphs     -f game.analysed.full.pgn
pgntools gamequery  -f capablanca_all.pgn -t capablanca.repertoire.pgn -l "e4 e5 Nf3"
pgntools findseq    -f capablanca_all.pgn -q "Be2 Bd7; Be3 e6"
```

Every tool takes its input with `-f/--pgnfile` and writes an output path derived from the input unless `-o/--output` says otherwise. Full argument tables and implementation notes live in `.claude/rules/pgntools-<tool>.md` in the repository.

## Working on pgntools

```bash
git clone https://github.com/pgntools/pgntools.git
cd pgntools
python -m venv venv && venv/bin/pip install -r requirements.txt
venv/bin/python -m unittest discover -s tests -t .           # the full suite
venv/bin/python -m pgntools.repertoire -f pgns/capablanca_all.pgn   # a tool, uninstalled
```

Engine-dependent tests skip themselves when no Stockfish binary is found. `pip install -e .` additionally puts the `pgntools` and `pgn-<tool>` commands on your `PATH` from the checkout.

## License

MIT — see [LICENSE](https://github.com/pgntools/pgntools/blob/main/LICENSE).
