mirror of
https://github.com/TheRealOwenRees/chess-endgame-trainer.git
synced 2026-11-18 11:42:07 +00:00
Update domain docs for local tablebase routing (#32)
Redefine Tablebase and Cooldown in GLOSSARY.md for the local<=5 / Lichess 6-7 / cache-only-API split, and add Probe and Position key terms. Add ADR-0005 recording the source split and its latency-vs-footprint trade-off, and mark ADR-0001 superseded.
This commit is contained in:
+18
-5
@@ -63,13 +63,26 @@ promotion (still winning) for conversion puzzles, mate otherwise.
|
||||
|
||||
**Tablebase**:
|
||||
A database of precomputed optimal outcomes for every position with at most
|
||||
seven pieces, queried via the lichess API and cached. The trainer caches only
|
||||
the outcome data it grades on — enough to tell a winning move from a losing
|
||||
one — not every metric the tablebase reports, and refetches anything else.
|
||||
seven pieces. Positions with five or fewer pieces are answered from local
|
||||
Syzygy files; six and seven piece positions come from the lichess API. The
|
||||
trainer keeps only the outcome data it grades on — enough to tell a winning
|
||||
move from a losing one — and caches API answers only; local answers are cheap
|
||||
enough to refetch.
|
||||
|
||||
**Probe**:
|
||||
A single lookup of one position in the tablebase, returning its result and its
|
||||
legal moves. A probe is answered locally or by the API.
|
||||
|
||||
**Position key**:
|
||||
The identity of a tablebase position — board, side to move, castling and
|
||||
en-passant — excluding the move clocks. FENs that differ only in their clocks
|
||||
share a position key.
|
||||
_Avoid_: Full FEN
|
||||
|
||||
**Cooldown**:
|
||||
Rate-limit state entered after a 429 from the lichess tablebase API, during
|
||||
which the trainer blocks play.
|
||||
Rate-limit state entered after a 429 from the lichess API, during which the
|
||||
trainer blocks play for positions that need the API (six or seven pieces).
|
||||
Local positions are unaffected.
|
||||
|
||||
**Cache sweep**:
|
||||
The periodic halving of LFU cache frequencies (weekly) that lets rarely-used
|
||||
|
||||
@@ -1,5 +1,8 @@
|
||||
# Tablebase via the lichess API instead of self-hosting
|
||||
|
||||
_Superseded by ADR-0005: five-or-fewer-piece positions are now probed locally;
|
||||
Lichess remains for six and seven pieces._
|
||||
|
||||
The trainer grades moves against Syzygy tablebases, but self-hosting them is not
|
||||
possible yet, so we query the lichess tablebase API (`tablebase.lichess.ovh`)
|
||||
over HTTP and cache responses. This couples the core play loop to a remote
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
# Answer five-or-fewer-piece positions from local Syzygy, keep six and seven on Lichess, and cache only the API path
|
||||
|
||||
_Status: accepted. Supersedes ADR-0001's "all lookups remote" assumption._
|
||||
|
||||
Relying entirely on the Lichess tablebase API put network latency and rate
|
||||
limits (and a cooldown on 429) in front of every lookup. Hosting everything is
|
||||
not viable either: the 3-4-5-piece Syzygy set is about 939 MB, six pieces about
|
||||
150 GB, seven pieces about 18 TB, and eight or more pieces are outside every
|
||||
tablebase. We route by piece count instead: five or fewer are probed locally
|
||||
from Syzygy WDL+DTZ files, six and seven go to Lichess, and eight or more are
|
||||
rejected without a lookup. A local failure — missing or partial files, probe
|
||||
error — falls back to Lichess, so play only blocks when both sources are
|
||||
unavailable.
|
||||
|
||||
Only the Lichess path is cached. Local probes read from the OS page cache and
|
||||
are cheap, so an application cache would spend memory on answers we can
|
||||
regenerate. Cache entries are keyed by position rather than the full FEN: the
|
||||
result depends only on board, side to move, castling and en-passant, so
|
||||
clock-only differences are the same position, and the 50-move rule is already
|
||||
encoded in the WDL/DTZ values rather than the running halfmove clock.
|
||||
|
||||
The cost is a native build: the local prober is an MIT-licensed C library
|
||||
vendored behind a Rust NIF, so a release build needs the Rust toolchain, and
|
||||
each host points `TABLEBASE_PATH` at its own copy of the files. In exchange the
|
||||
common (≤5-piece) case is answered without the network or rate limits, while
|
||||
the enormous 6-7-piece sets stay off our infrastructure.
|
||||
Reference in New Issue
Block a user