--- license: apache-2.0 library_name: pytorch tags: [chess, reinforcement-learning, information-theory, alphazero, ppo] pipeline_tag: other --- # Shannon's Gambit (`legacyaravind/shannons-gambit`) A self-improving chess intelligence. This repo holds the served network plus the checkpoint ladder (`ladder.json`) and the Inference Endpoint handler. The full system lives at [github.com/aravinds-kannappan/Chess-Gambit-RL](https://github.com/aravinds-kannappan/Chess-Gambit-RL). ## What the system is A **multi-agent** engine: each position is routed to the method that owns it. | Agent | Where it plays | Method | | --- | --- | --- | | **MDP** | solved endgames (KRvK, KQvK) | exact Bellman value iteration (optimal) | | **PPO** | low-material regime | on-policy actor-critic RL | | **Reward (DQN)** | low-material regime | off-policy, potential-based shaping | | **Neural** | opening / middlegame | this network: AlphaZero-lite self-play + behavioural cloning | A phase router (`agents/router.py`) dispatches each move to the right agent. The network in this repo is the general full-board player and the bootstrap for self-play; it also serves the policy/value/WDL/rating predictions. ## Stockfish is the benchmark, never a player The agents never call Stockfish to choose a move. A separate backend evaluator (`eval/benchmark.py`) uses Stockfish only as a calibrated yardstick: it throttles Stockfish to known Elo bands (`UCI_LimitStrength` + `UCI_Elo`, with a `Skill Level` fallback below the floor), plays each agent a gauntlet, and fits a **calibrated Elo** (Bradley-Terry MLE). It also reports centipawn loss and top-1 agreement. That rating is the level each agent plays at and climbs as it learns. ## The network Multi-head residual network trained on real Lichess games. Heads: policy (next move), value + win/draw/loss (outcome), and player rating (Elo). ### Final supervised training metrics ```json { "loss_policy": 0.2169, "loss_value": 0.0305, "loss_wdl": 0.0295, "loss_rating": 0.0312, "policy_acc": 0.966, "wdl_acc": 0.9903, "rating_mae_elo": 21.1, "epoch": 15 } ``` ### Input / output * Input: 18x8x8 board planes (see `shannons_gambit/data/encode.py`). * Output: policy logits over 4672 moves, scalar value in [-1, 1], WDL logits, standardised rating. ## How it is served * **HF Space** (Docker + FastAPI): trains continuously by self-play and serves `/move`, `/predict`, `/watch-move`, `/ladder`, plus `/calibrate` (Stockfish-assessed Elo). New generations are versioned back to this repo so the ladder survives restarts. * **Inference Endpoint**: `handler.py` here loads `model.pt` and returns best move, WDL, value and rating for a FEN. ```python import requests requests.post( "https:// .endpoints.huggingface.cloud", headers={"Authorization": "Bearer "}, json={"inputs": {"fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"}}, ).json() ``` ## Honest limitations * The MDP, PPO and reward agents are endgame specialists (validated against the exactly-solved table); the network carries the opening and middlegame. * On a free CPU, self-play is slow and the Elo ladder grows over hours; GPU bursts accelerate it. Any Elo is only meaningful once anchored by the Stockfish benchmark. License: Apache-2.0.
