Files
chess-endgame-trainer/lib/chesstrainer/endgames/tablebase.ex
T
owenrees fddb94e2bd Add admin bulk FEN importer (#156)
* change position of theme picker

* Add admin bulk FEN importer

Paste FENs, resolve results from the local Syzygy tablebase only, preview each line's status, and bulk insert with themes and a batch rating.
2026-11-12 22:44:13 +01:00

115 lines
3.6 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.Endgames.Tablebase.Backend.Fathom, as: FathomBackend
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
@doc """
Probes a FEN using only the local Syzygy tablebase and returns the result
from the side-to-move's perspective.
Unlike `new/1` this never falls back to the remote backend and never reads or
writes the cache. It is the primitive behind the admin bulk importer, so an
imported result always comes from our own tablebases.
"""
@spec probe_local_result(String.t()) ::
{:ok, result()}
| {:error, :not_configured | :illegal | :terminal | :unsupported}
def probe_local_result(fen), do: FathomBackend.probe_result_local(fen)
@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