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
+7
View File
@@ -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
+3
View File
@@ -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
+25 -1
View File
@@ -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
@@ -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)
<<?a + file>> <> 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
@@ -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
+140
View File
@@ -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 <<ff, fr, tf, tr, promotion::binary>> <- 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(<<file>>), 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
@@ -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)