From cb35351f8ca0b82ba19fe2a044669f3268f70150 Mon Sep 17 00:00:00 2001 From: Owen Date: Tue, 3 Nov 2026 14:23:46 +0100 Subject: [PATCH] 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. --- config/runtime.exs | 7 + config/test.exs | 3 + lib/chesstrainer/endgames/tablebase.ex | 26 +++- .../endgames/tablebase/backend/fathom.ex | 108 ++++++++++++++ lib/chesstrainer/endgames/tablebase/router.ex | 10 +- lib/chesstrainer/endgames/tablebase/san.ex | 140 ++++++++++++++++++ .../tablebase/backend/fathom_test.exs | 79 ++++++++++ .../endgames/tablebase/router_test.exs | 3 +- .../endgames/tablebase/san_test.exs | 44 ++++++ test/chesstrainer/endgames/tablebase_test.exs | 11 ++ .../live/endgame_live/play_test.exs | 4 +- 11 files changed, 430 insertions(+), 5 deletions(-) create mode 100644 lib/chesstrainer/endgames/tablebase/backend/fathom.ex create mode 100644 lib/chesstrainer/endgames/tablebase/san.ex create mode 100644 test/chesstrainer/endgames/tablebase/backend/fathom_test.exs create mode 100644 test/chesstrainer/endgames/tablebase/san_test.exs diff --git a/config/runtime.exs b/config/runtime.exs index 4f22e79..ac64dc1 100644 --- a/config/runtime.exs +++ b/config/runtime.exs @@ -20,6 +20,13 @@ if System.get_env("PHX_SERVER") do config :chesstrainer, ChesstrainerWeb.Endpoint, server: true end +# Local Syzygy tablebases: set TABLEBASE_PATH to the directory holding the +# .rtbw/.rtbz files. When unset, the local backend stays disabled and lookups +# fall back to Lichess. +if tablebase_path = System.get_env("TABLEBASE_PATH") do + config :chesstrainer, :tablebase_path, tablebase_path +end + # Tablebase cache: size and the UTC time of the daily backup. Environment # variables win over the defaults in config/config.exs so deployments can tune # the cache without a rebuild. Invalid values are reported and ignored rather diff --git a/config/test.exs b/config/test.exs index a386be3..c0bc9b7 100644 --- a/config/test.exs +++ b/config/test.exs @@ -1,5 +1,8 @@ import Config +# Point the local Fathom backend at the committed 3-piece fixtures. +config :chesstrainer, :tablebase_path, Path.expand("../test/fixtures/tablebase", __DIR__) + # Configure your database # # The MIX_TEST_PARTITION environment variable can be used diff --git a/lib/chesstrainer/endgames/tablebase.ex b/lib/chesstrainer/endgames/tablebase.ex index d810f0d..6df7418 100644 --- a/lib/chesstrainer/endgames/tablebase.ex +++ b/lib/chesstrainer/endgames/tablebase.ex @@ -44,6 +44,29 @@ defmodule Chesstrainer.Endgames.Tablebase do def normalize_category(_category), do: :unknown + @doc """ + Normalises a Fathom WDL atom into a trainer result. + + Like `normalize_category/1`, cursed-win and blessed-loss are draws because the + 50-move rule prevents the decisive result. + """ + @spec normalize_wdl(atom()) :: result() + def normalize_wdl(:win), do: :win + def normalize_wdl(:cursed_win), do: :draw + def normalize_wdl(:draw), do: :draw + def normalize_wdl(:blessed_loss), do: :draw + def normalize_wdl(:loss), do: :loss + def normalize_wdl(_wdl), do: :unknown + + @doc """ + Flips an outcome to the other side's perspective. + """ + @spec flip(atom()) :: result() + def flip(:win), do: :loss + def flip(:loss), do: :win + def flip(:draw), do: :draw + def flip(_outcome), do: :unknown + @spec new(String.t()) :: {:ok, t()} | {:cooldown, non_neg_integer()} @@ -68,7 +91,8 @@ defmodule Chesstrainer.Endgames.Tablebase do {:error, :invalid_endgame} {:ok, tablebase} -> - Tablebase.Cache.put(key, tablebase) + # Local probes are cheap; only remote (Lichess) answers are cached. + if Tablebase.Router.remote?(fen), do: Tablebase.Cache.put(key, tablebase) {:ok, tablebase} end end diff --git a/lib/chesstrainer/endgames/tablebase/backend/fathom.ex b/lib/chesstrainer/endgames/tablebase/backend/fathom.ex new file mode 100644 index 0000000..60e9b00 --- /dev/null +++ b/lib/chesstrainer/endgames/tablebase/backend/fathom.ex @@ -0,0 +1,108 @@ +defmodule Chesstrainer.Endgames.Tablebase.Backend.Fathom do + @moduledoc """ + Local Syzygy backend powered by the Fathom NIF. + + Handles positions with up to five pieces. Falls back to the remote backend + (Lichess by default) when the tablebases are not configured, the probe fails, + or Fathom cannot answer the position, so play never blocks. + + The backend is overridable for tests via + `config :chesstrainer, :tablebase_fallback, Module`. + """ + + @behaviour Chesstrainer.Endgames.Tablebase.Backend + + alias Chesstrainer.Endgames.Tablebase + alias Chesstrainer.Endgames.Tablebase.Backend.Lichess + alias Chesstrainer.Endgames.Tablebase.Fathom, as: Nif + alias Chesstrainer.Endgames.Tablebase.Move + alias Chesstrainer.Endgames.Tablebase.San + + @impl true + def probe(fen) do + with {:ok, path} <- tablebase_path(), + {:ok, _largest} <- Nif.init(path), + {:ok, {root, moves}} <- Nif.probe(fen) do + case root do + :failed -> fallback(fen) + _ -> {:ok, to_tablebase(fen, root, moves)} + end + else + _ -> fallback(fen) + end + end + + defp tablebase_path do + case Application.get_env(:chesstrainer, :tablebase_path) do + path when is_binary(path) and path != "" -> {:ok, path} + _ -> :error + end + end + + defp fallback(fen) do + (Application.get_env(:chesstrainer, :tablebase_fallback) || Lichess).probe(fen) + end + + defp to_tablebase(_fen, :checkmate, _moves) do + %Tablebase{category: :loss, checkmate: true, moves: []} + end + + defp to_tablebase(_fen, :stalemate, _moves) do + %Tablebase{category: :draw, checkmate: false, moves: []} + end + + defp to_tablebase(fen, {wdl, _from, _to, _promotes, _ep, _dtz}, moves) do + %Tablebase{ + category: Tablebase.normalize_wdl(wdl), + checkmate: false, + moves: fen |> map_moves(moves) |> sort_moves() + } + end + + defp map_moves(fen, moves) do + Enum.map(moves, fn {wdl, from, to, promotes, _ep, dtz} -> + uci = uci(from, to, promotes) + + %Move{ + category: move_category(wdl), + dtz: dtz, + uci: uci, + san: San.for_uci(fen, uci) + } + end) + end + + # Best move first: highest mover outcome, then sharpest DTZ (lowest for a + # mover who is winning, highest for a mover who is losing). + defp sort_moves(moves) do + Enum.sort_by(moves, fn %Move{category: category, dtz: dtz} -> + rank = mover_rank(Tablebase.flip(category)) + {-rank, if(rank == 0, do: -(dtz || 0), else: dtz || 0)} + end) + end + + # Fathom reports a move's WDL from the mover's perspective; the trainer stores + # the resulting position's category (the opponent's perspective). + defp move_category(wdl), do: Tablebase.flip(Tablebase.normalize_wdl(wdl)) + + defp mover_rank(:win), do: 2 + defp mover_rank(:draw), do: 1 + defp mover_rank(:loss), do: 0 + defp mover_rank(_), do: -1 + + defp uci(from, to, promotes) do + square(from) <> square(to) <> promotion_suffix(promotes) + end + + defp square(square) do + file = rem(square, 8) + rank = div(square, 8) + <> <> Integer.to_string(rank + 1) + end + + defp promotion_suffix(1), do: "q" + defp promotion_suffix(2), do: "r" + defp promotion_suffix(3), do: "b" + defp promotion_suffix(4), do: "n" + defp promotion_suffix(_), do: "" +end diff --git a/lib/chesstrainer/endgames/tablebase/router.ex b/lib/chesstrainer/endgames/tablebase/router.ex index 014699d..8fd4dac 100644 --- a/lib/chesstrainer/endgames/tablebase/router.ex +++ b/lib/chesstrainer/endgames/tablebase/router.ex @@ -11,14 +11,14 @@ defmodule Chesstrainer.Endgames.Tablebase.Router do """ alias Chesstrainer.Endgames.Tablebase + alias Chesstrainer.Endgames.Tablebase.Backend.Fathom, as: FathomBackend alias Chesstrainer.Endgames.Tablebase.Backend.Lichess alias Chesstrainer.FEN @max_local_pieces 5 @max_pieces 7 - # The local Syzygy backend will replace Lichess here once it exists. - @local_backend Lichess + @local_backend FathomBackend @remote_backend Lichess @spec backend(String.t()) :: {:ok, module()} | {:error, :not_covered | :invalid_endgame} @@ -31,6 +31,12 @@ defmodule Chesstrainer.Endgames.Tablebase.Router do end end + @doc """ + True when the position is answered by the remote (Lichess) backend. + """ + @spec remote?(String.t()) :: boolean() + def remote?(fen), do: backend(fen) == {:ok, @remote_backend} + @spec probe(String.t()) :: {:ok, Tablebase.t()} | {:cooldown, non_neg_integer()} | {:error, term()} def probe(fen) do diff --git a/lib/chesstrainer/endgames/tablebase/san.ex b/lib/chesstrainer/endgames/tablebase/san.ex new file mode 100644 index 0000000..7507a6e --- /dev/null +++ b/lib/chesstrainer/endgames/tablebase/san.ex @@ -0,0 +1,140 @@ +defmodule Chesstrainer.Endgames.Tablebase.San do + @moduledoc """ + Generates Standard Algebraic Notation for a UCI move in a position. + + The local Fathom backend returns moves as board squares, so this turns them + into the SAN the trainer displays. Returns `nil` when the move cannot be + parsed or is not legal in the position. + """ + + alias Chex.Game + alias Chex.Piece + + @files ~w(a b c d e f g h)a + @piece_letters %{king: "K", queen: "Q", rook: "R", bishop: "B", knight: "N"} + + @spec for_uci(String.t(), String.t()) :: String.t() | nil + def for_uci(fen, uci) do + with {:ok, game} <- game(fen), + {:ok, from, to, promote} <- parse_uci(uci), + {name, color, _start} <- Map.get(game.board, from), + {:ok, next} <- Game.move(game, {from, to}, promote || :queen) do + build(game, name, color, from, to, promote) <> suffix(next) + else + _ -> nil + end + end + + defp game(fen) do + Game.new(fen) + rescue + _ -> {:error, :invalid_fen} + end + + defp build(game, name, color, from, to, promote) do + if name == :king and abs(file_index(from) - file_index(to)) == 2 do + if file_index(to) > file_index(from), do: "O-O", else: "O-O-O" + else + normal(game, name, color, from, to, promote) + end + end + + defp normal(game, name, color, from, to, promote) do + capture = capture?(game, color, from, to) + capture_marker = if capture, do: "x", else: "" + + prefix = + if name == :pawn do + if capture, do: file(from), else: "" + else + Map.get(@piece_letters, name, "") <> disambiguation(game, name, color, from, to) + end + + prefix <> capture_marker <> square_string(to) <> promotion_suffix(promote) + end + + defp capture?(game, color, from, to) do + case Map.get(game.board, to) do + {_name, ^color, _start} -> false + {_name, _other, _start} -> true + nil -> piece_name(game, from) == :pawn and file_index(from) != file_index(to) + end + end + + # Adds a file/rank/both only when another same-type piece could also reach `to`. + defp disambiguation(game, name, color, from, to) do + others = + game.board + |> Enum.filter(fn {square, {pname, pcolor, _start}} -> + square != from and pname == name and pcolor == color and + to in Piece.possible_moves(game, square) + end) + |> Enum.map(fn {square, _piece} -> square end) + + cond do + others == [] -> + "" + + Enum.all?(others, &(file_index(&1) != file_index(from))) -> + file(from) + + Enum.all?(others, &(rank(&1) != rank(from))) -> + Integer.to_string(rank(from)) + + true -> + file(from) <> Integer.to_string(rank(from)) + end + end + + defp suffix(next) do + cond do + Game.checkmate?(next) -> "#" + Game.in_check?(next, next.active_color) -> "+" + true -> "" + end + end + + defp promotion_suffix(nil), do: "" + defp promotion_suffix(:queen), do: "=Q" + defp promotion_suffix(:rook), do: "=R" + defp promotion_suffix(:bishop), do: "=B" + defp promotion_suffix(:knight), do: "=N" + + defp piece_name(game, square) do + case Map.get(game.board, square) do + {name, _color, _start} -> name + nil -> nil + end + end + + defp parse_uci(uci) when is_binary(uci) do + with <> <- uci, + {:ok, from} <- parse_square(ff, fr), + {:ok, to} <- parse_square(tf, tr), + {:ok, promote} <- parse_promotion(promotion) do + {:ok, from, to, promote} + else + _ -> :error + end + end + + defp parse_uci(_uci), do: :error + + defp parse_square(file, rank) when file in ?a..?h and rank in ?1..?8 do + {:ok, {String.to_existing_atom(<>), rank - ?0}} + end + + defp parse_square(_file, _rank), do: :error + + defp parse_promotion(""), do: {:ok, nil} + defp parse_promotion("q"), do: {:ok, :queen} + defp parse_promotion("r"), do: {:ok, :rook} + defp parse_promotion("b"), do: {:ok, :bishop} + defp parse_promotion("n"), do: {:ok, :knight} + defp parse_promotion(_promotion), do: :error + + defp file_index({file, _rank}), do: Enum.find_index(@files, &(&1 == file)) + defp file({file, _rank}), do: Atom.to_string(file) + defp rank({_file, rank}), do: rank + defp square_string({file, rank}), do: Atom.to_string(file) <> Integer.to_string(rank) +end diff --git a/test/chesstrainer/endgames/tablebase/backend/fathom_test.exs b/test/chesstrainer/endgames/tablebase/backend/fathom_test.exs new file mode 100644 index 0000000..f25659f --- /dev/null +++ b/test/chesstrainer/endgames/tablebase/backend/fathom_test.exs @@ -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 diff --git a/test/chesstrainer/endgames/tablebase/router_test.exs b/test/chesstrainer/endgames/tablebase/router_test.exs index bdfb638..4b25d06 100644 --- a/test/chesstrainer/endgames/tablebase/router_test.exs +++ b/test/chesstrainer/endgames/tablebase/router_test.exs @@ -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 diff --git a/test/chesstrainer/endgames/tablebase/san_test.exs b/test/chesstrainer/endgames/tablebase/san_test.exs new file mode 100644 index 0000000..45a5792 --- /dev/null +++ b/test/chesstrainer/endgames/tablebase/san_test.exs @@ -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 diff --git a/test/chesstrainer/endgames/tablebase_test.exs b/test/chesstrainer/endgames/tablebase_test.exs index 1bb8ffd..764141f 100644 --- a/test/chesstrainer/endgames/tablebase_test.exs +++ b/test/chesstrainer/endgames/tablebase_test.exs @@ -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() == diff --git a/test/chesstrainer_web/live/endgame_live/play_test.exs b/test/chesstrainer_web/live/endgame_live/play_test.exs index ec32b4e..cd527bb 100644 --- a/test/chesstrainer_web/live/endgame_live/play_test.exs +++ b/test/chesstrainer_web/live/endgame_live/play_test.exs @@ -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)