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**:
|
**Tablebase**:
|
||||||
A database of precomputed optimal outcomes for every position with at most
|
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
|
seven pieces. Positions with five or fewer pieces are answered from local
|
||||||
the outcome data it grades on — enough to tell a winning move from a losing
|
Syzygy files; six and seven piece positions come from the lichess API. The
|
||||||
one — not every metric the tablebase reports, and refetches anything else.
|
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**:
|
**Cooldown**:
|
||||||
Rate-limit state entered after a 429 from the lichess tablebase API, during
|
Rate-limit state entered after a 429 from the lichess API, during which the
|
||||||
which the trainer blocks play.
|
trainer blocks play for positions that need the API (six or seven pieces).
|
||||||
|
Local positions are unaffected.
|
||||||
|
|
||||||
**Cache sweep**:
|
**Cache sweep**:
|
||||||
The periodic halving of LFU cache frequencies (weekly) that lets rarely-used
|
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
|
# 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
|
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`)
|
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
|
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