Allsfair

A game of simultaneous, predetermined moves.

Setup (uv)

From the repository root:

uv sync --dev

Local CLI demo

Run:

uv run play_cli.py

Options:

• --show-input show move text while typing (default hides typed moves).

Move format is {from}{troops}{to} such as a3b. Each round: both players enter 3 moves first, then the 3 move pairs resolve one-by-one.

Tests

Run tests with coverage (configured via pyproject.toml):

uv run pytest

ML scaffolding

(Moved here from the retired allsfair-python-function repo. Training and evaluation run offline; production bot inference is served by the allsfair-worker Cloudflare Worker from an exported JSON artifact.)

Train a simple Q-learning bot with mixed self-play, heuristic, and random opponents:

uv run python -m ml.train --episodes 15000 --checkpoint checkpoints/tabular_q.json
uv run python -m ml.train --episodes 15000 --max-rounds 40 --checkpoint checkpoints/tabular_q.json
uv run python -m ml.train --episodes 10000 --resume-from checkpoints/tabular_q.json --checkpoint checkpoints/tabular_q_v2.json

Evaluate the trained bot:

uv run python -m ml.eval --checkpoint checkpoints/tabular_q.json --games 200 --opponent heuristic
uv run python -m ml.eval --checkpoint checkpoints/tabular_q.json --games 200 --opponent random

Play against the trained bot in terminal:

uv run python -m ml.play --checkpoint checkpoints/tabular_q.json --human-player 1

--max-rounds is the recommended limit flag. --step-limit-mode draw enforces strict rules at horizon (no synthetic winner). Use --hybrid to blend learned policy with heuristic fallback for stronger play.

Checkpoints live in checkpoints/ (gitignored — large files).

Inference artifact (JSON, low-memory)

Convert a training checkpoint into a sharded JSON inference artifact for production bot play:

uv run python scripts/build_inference_artifact.py \
  --checkpoint checkpoints/tabular_q_v1.json \
  --output-dir checkpoints/tabular_q_v1_artifact \
  --shards 256

Parity fixtures for the TypeScript port

The production game runs as a TypeScript Cloudflare Worker (allsfair-worker repo). This Python engine remains the source of truth for game rules. After any rules change, regenerate the parity fixtures the TS test suite replays:

uv run python scripts/generate_parity_fixtures.py ../allsfair-worker/test/fixtures/parity.json