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,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