Wire Fathom into the local tablebase backend (#30)

Add Backend.Fathom: probes positions with five or fewer pieces via the Fathom NIF, maps WDL/DTZ to the trainer structs (flipping per-move perspective), generates SAN, sorts moves best-first, and falls back to Lichess on any failure. The local directory is configured with TABLEBASE_PATH; local answers are no longer cached.

Add Tablebase.normalize_wdl/1 and flip/1, plus tests for the WDL mapping, SAN, checkmate, fallback, and a cache-free end-to-end local probe.
This commit is contained in:
2026-11-03 14:23:46 +01:00
parent e60c161a3a
commit cb35351f8c
11 changed files with 430 additions and 5 deletions
@@ -0,0 +1,79 @@
defmodule Chesstrainer.Endgames.Tablebase.Backend.FathomTest.Stub do
@moduledoc false
alias Chesstrainer.Endgames.Tablebase
def probe(_fen), do: {:ok, %Tablebase{category: :draw, checkmate: false, moves: []}}
end
defmodule Chesstrainer.Endgames.Tablebase.Backend.FathomTest do
# Not async: the local backend reads app config and Fathom keeps global state.
use ExUnit.Case, async: false
alias Chesstrainer.Endgames.Tablebase
alias Chesstrainer.Endgames.Tablebase.Backend.Fathom, as: FathomBackend
alias Chesstrainer.Endgames.Tablebase.Cache, as: TablebaseCache
alias Chesstrainer.FEN
@krk "4k3/8/8/8/8/8/8/R3K3 w - - 0 1"
@mate "7k/6Q1/5K2/8/8/8/8/8 b - - 0 1"
test "probes a KRvK position locally" do
assert {:ok, %Tablebase{} = tablebase} = FathomBackend.probe(@krk)
assert tablebase.category == :win
refute tablebase.checkmate
assert length(tablebase.moves) == 15
assert Enum.all?(tablebase.moves, &(&1.category == :loss))
best = hd(tablebase.moves)
assert best.uci == "a1a7"
assert best.dtz == 23
assert best.san == "Ra7"
end
test "detects checkmate" do
assert {:ok, %Tablebase{category: :loss, checkmate: true, moves: []}} =
FathomBackend.probe(@mate)
end
test "answers through Tablebase.new without a cached entry" do
# A draw-returning fallback proves the win came from Fathom, not Lichess.
previous = Application.get_env(:chesstrainer, :tablebase_fallback)
on_exit(fn ->
if previous,
do: Application.put_env(:chesstrainer, :tablebase_fallback, previous),
else: Application.delete_env(:chesstrainer, :tablebase_fallback)
end)
Application.put_env(:chesstrainer, :tablebase_fallback, __MODULE__.Stub)
TablebaseCache.delete(FEN.position_key(@krk))
assert {:ok, %Tablebase{category: :win, moves: moves}} = Tablebase.new(@krk)
assert length(moves) == 15
end
describe "fallback" do
setup do
previous_path = Application.get_env(:chesstrainer, :tablebase_path)
previous_fallback = Application.get_env(:chesstrainer, :tablebase_fallback)
on_exit(fn ->
Application.put_env(:chesstrainer, :tablebase_path, previous_path)
if previous_fallback do
Application.put_env(:chesstrainer, :tablebase_fallback, previous_fallback)
else
Application.delete_env(:chesstrainer, :tablebase_fallback)
end
end)
end
test "falls back when the tablebases are not configured" do
Application.put_env(:chesstrainer, :tablebase_path, nil)
Application.put_env(:chesstrainer, :tablebase_fallback, __MODULE__.Stub)
assert {:ok, %Tablebase{category: :draw}} = FathomBackend.probe(@krk)
end
end
end
@@ -1,6 +1,7 @@
defmodule Chesstrainer.Endgames.Tablebase.RouterTest do
use ExUnit.Case, async: true
alias Chesstrainer.Endgames.Tablebase.Backend.Fathom, as: FathomBackend
alias Chesstrainer.Endgames.Tablebase.Backend.Lichess
alias Chesstrainer.Endgames.Tablebase.Router
@@ -11,7 +12,7 @@ defmodule Chesstrainer.Endgames.Tablebase.RouterTest do
describe "backend/1" do
test "routes five or fewer pieces to the local slot" do
assert Router.backend(@three) == {:ok, Lichess}
assert Router.backend(@three) == {:ok, FathomBackend}
end
test "routes six and seven pieces to the remote slot" do
@@ -0,0 +1,44 @@
defmodule Chesstrainer.Endgames.Tablebase.SanTest do
use ExUnit.Case, async: true
alias Chesstrainer.Endgames.Tablebase.San
@start "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
test "pawn and piece moves" do
assert San.for_uci(@start, "e2e4") == "e4"
assert San.for_uci(@start, "g1f3") == "Nf3"
end
test "captures" do
after_e4_d5 = "rnbqkbnr/ppp1pppp/8/3p4/4P3/8/PPPP1PPP/RNBQKBNR w KQkq d6 0 2"
assert San.for_uci(after_e4_d5, "e4d5") == "exd5"
end
test "castling" do
fen = "r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1"
assert San.for_uci(fen, "e1g1") == "O-O"
assert San.for_uci(fen, "e1c1") == "O-O-O"
end
test "promotion and check" do
assert San.for_uci("8/P7/8/8/8/4k3/8/4K3 w - - 0 1", "a7a8q") == "a8=Q"
assert San.for_uci("4k3/P7/8/8/8/8/8/4K3 w - - 0 1", "a7a8q") == "a8=Q+"
end
test "disambiguates by file when two pieces can reach the square" do
fen = "4k3/8/8/8/8/8/8/1N1NK3 w - - 0 1"
assert San.for_uci(fen, "b1c3") == "Nbc3"
assert San.for_uci(fen, "d1c3") == "Ndc3"
end
test "checkmate suffix" do
fen = "6k1/5ppp/8/8/8/8/8/4R1K1 w - - 0 1"
assert San.for_uci(fen, "e1e8") == "Re8#"
end
test "returns nil for an invalid move" do
assert San.for_uci(@start, "e2e5") == nil
assert San.for_uci(@start, "zzzz") == nil
end
end
@@ -33,6 +33,17 @@ defmodule Chesstrainer.Endgames.TablebaseTest do
end
end
describe "normalize_wdl/1" do
test "maps Fathom WDL atoms, treating 50-move-rule draws as draws" do
assert Tablebase.normalize_wdl(:win) == :win
assert Tablebase.normalize_wdl(:loss) == :loss
assert Tablebase.normalize_wdl(:draw) == :draw
assert Tablebase.normalize_wdl(:cursed_win) == :draw
assert Tablebase.normalize_wdl(:blessed_loss) == :draw
assert Tablebase.normalize_wdl(:unknown) == :unknown
end
end
describe "struct shape" do
test "Tablebase carries only the fields the trainer reads" do
assert %Tablebase{} |> Map.from_struct() |> Map.keys() |> Enum.sort() ==
@@ -177,7 +177,9 @@ defmodule ChesstrainerWeb.EndgameLive.PlayTest do
describe "tablebase availability" do
test "blocks the attempt when the tablebase is cooling down", %{conn: conn} do
endgame = endgame_fixture()
# Six pieces routes to Lichess, so the cooldown applies (five or fewer
# would be answered locally).
endgame = endgame_fixture(fen: "8/8/5p2/1P1K1k2/8/2r5/8/7R w - - 0 1")
TablebaseCache.delete(FEN.position_key(endgame.fen))
Ratelimiters.lichess_add_cooldown()
on_exit(fn -> Ratelimiters.lichess_reset_cooldown() end)