Files
chess-endgame-trainer/lib/chesstrainer/endgames/tablebase.ex
T
owenrees cb35351f8c 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.
2026-11-03 14:23:46 +01:00

101 lines
3.0 KiB
Elixir

defmodule Chesstrainer.Endgames.Tablebase do
@moduledoc """
All endgame tablebase related functions.
Lookups are routed by piece count through `Tablebase.Router`, which picks the
backend that can answer the position.
The cached value carries only what the trainer reads: `category`,
`checkmate`, and `moves`. Cursed-win/blessed-loss are normalised to `:draw` at
parse time, and distance fields (`dtm`/`dtc`/`dtw`) are not kept because the
local Syzygy backend cannot produce them.
"""
alias Chesstrainer.Endgames.Tablebase
alias Chesstrainer.FEN
@type result :: :win | :draw | :loss | :unknown
@type t :: %__MODULE__{
category: result,
checkmate: boolean(),
moves: [Tablebase.Move.t()]
}
defstruct category: nil,
checkmate: false,
moves: nil
@doc """
Normalises a Lichess tablebase category string into a trainer result.
`cursed-win` and `blessed-loss` are wins/losses only when the 50-move rule is
ignored, so they are draws in play. Unrecognised values become `:unknown`
rather than minting arbitrary atoms.
"""
@spec normalize_category(term()) :: result()
def normalize_category(category) when category in ["win", "syzygy-win", "maybe-win"], do: :win
def normalize_category(category) when category in ["draw", "cursed-win", "blessed-loss"],
do: :draw
def normalize_category(category) when category in ["loss", "syzygy-loss", "maybe-loss"],
do: :loss
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()}
| {:error, :invalid_endgame}
| {:error, term()}
def new(fen) do
key = FEN.position_key(fen)
case Tablebase.Cache.get(key) do
{:ok, tablebase} ->
{:ok, tablebase}
_ ->
case Tablebase.Router.probe(fen) do
{:error, reason} ->
{:error, reason}
{:cooldown, remaining_ms} ->
{:cooldown, remaining_ms}
{:ok, tablebase} when tablebase.category == :unknown ->
{:error, :invalid_endgame}
{:ok, 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
end
end