Route tablebase lookups through a piece-count backend seam (#27)

Add a Backend behaviour, a Lichess implementation, and a Router that picks a backend by piece count: five or fewer to the local slot, six or seven to the remote slot, and eight or more short-circuited as not covered with no network call. Both slots point at Lichess for now; the local Syzygy backend replaces the local slot when it lands.

Map :not_covered to the existing 'not covered by the tablebase' message.
This commit is contained in:
2026-11-03 12:51:08 +01:00
parent ec657c3424
commit 515196857f
8 changed files with 151 additions and 1 deletions
+4 -1
View File
@@ -2,6 +2,9 @@ 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
@@ -51,7 +54,7 @@ defmodule Chesstrainer.Endgames.Tablebase do
{:ok, tablebase}
_ ->
case Tablebase.Parser.from_fen(fen) do
case Tablebase.Router.probe(fen) do
{:error, reason} ->
{:error, reason}
@@ -0,0 +1,17 @@
defmodule Chesstrainer.Endgames.Tablebase.Backend do
@moduledoc """
A backend answers a tablebase probe for one position.
The router chooses a backend by piece count, so the play flow never depends on
which one answered. Every backend returns the same shape.
"""
alias Chesstrainer.Endgames.Tablebase
@type result ::
{:ok, Tablebase.t()}
| {:cooldown, non_neg_integer()}
| {:error, term()}
@callback probe(String.t()) :: result()
end
@@ -0,0 +1,12 @@
defmodule Chesstrainer.Endgames.Tablebase.Backend.Lichess do
@moduledoc """
The Lichess tablebase API backend (covers up to seven pieces).
"""
@behaviour Chesstrainer.Endgames.Tablebase.Backend
alias Chesstrainer.Endgames.Tablebase.Parser
@impl true
def probe(fen), do: Parser.from_fen(fen)
end
@@ -0,0 +1,42 @@
defmodule Chesstrainer.Endgames.Tablebase.Router do
@moduledoc """
Chooses a tablebase backend by piece count.
Positions with five or fewer pieces go to the local slot; six or seven go to
the remote slot. The local slot currently points at Lichess until the local
Syzygy backend lands, so this ships without changing today's behaviour.
Positions with eight or more pieces are beyond every tablebase and are
rejected without a network call.
"""
alias Chesstrainer.Endgames.Tablebase
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
@remote_backend Lichess
@spec backend(String.t()) :: {:ok, module()} | {:error, :not_covered | :invalid_endgame}
def backend(fen) do
case FEN.piece_count(fen) do
count when is_integer(count) and count <= @max_local_pieces -> {:ok, @local_backend}
count when is_integer(count) and count <= @max_pieces -> {:ok, @remote_backend}
count when is_integer(count) -> {:error, :not_covered}
_ -> {:error, :invalid_endgame}
end
end
@spec probe(String.t()) ::
{:ok, Tablebase.t()} | {:cooldown, non_neg_integer()} | {:error, term()}
def probe(fen) do
case backend(fen) do
{:ok, backend} -> backend.probe(fen)
{:error, reason} -> {:error, reason}
end
end
end
@@ -572,6 +572,10 @@ defmodule ChesstrainerWeb.EndgameLive.Play do
"This position is not covered by the tablebase."
end
defp blocked_reason({:error, :not_covered}) do
"This position is not covered by the tablebase."
end
defp blocked_reason({:error, reason}) do
"The tablebase is unavailable (#{inspect(reason)})."
end
@@ -0,0 +1,40 @@
defmodule Chesstrainer.Endgames.Tablebase.RouterTest do
use ExUnit.Case, async: true
alias Chesstrainer.Endgames.Tablebase.Backend.Lichess
alias Chesstrainer.Endgames.Tablebase.Router
@three "8/8/3k4/8/8/3K1R2/8/8 w - - 0 1"
@six "8/8/5p2/1P1K1k2/8/2r5/8/7R w - - 0 0"
@seven "6k1/5p2/6p1/8/7p/8/6PP/6K1 b - - 0 1"
@ten "3k4/2n2B2/1KP5/2B2p2/5b1p/7P/8/8 b - - 0 1"
describe "backend/1" do
test "routes five or fewer pieces to the local slot" do
assert Router.backend(@three) == {:ok, Lichess}
end
test "routes six and seven pieces to the remote slot" do
assert Router.backend(@six) == {:ok, Lichess}
assert Router.backend(@seven) == {:ok, Lichess}
end
test "marks eight or more pieces as not covered" do
assert Router.backend(@ten) == {:error, :not_covered}
end
test "marks a malformed FEN as invalid" do
assert Router.backend("not a fen") == {:error, :invalid_endgame}
end
end
describe "probe/1" do
test "rejects a position with more than seven pieces without a network call" do
assert Router.probe(@ten) == {:error, :not_covered}
end
test "rejects a malformed FEN" do
assert Router.probe("not a fen") == {:error, :invalid_endgame}
end
end
end
@@ -150,5 +150,12 @@ defmodule Chesstrainer.Endgames.TablebaseTest do
assert {:ok, ^tablebase} = Tablebase.new(fen)
end
test "returns {:error, :not_covered} for a position with more than seven pieces" do
fen = "3k4/2n2B2/1KP5/2B2p2/5b1p/7P/8/8 b - - 0 1"
TablebaseCache.delete(fen)
assert Tablebase.new(fen) == {:error, :not_covered}
end
end
end
@@ -57,6 +57,21 @@ defmodule ChesstrainerWeb.EndgameLive.PlayTest do
})
end
# >7-piece positions short-circuit to "not covered" before any backend, but
# the changeset now rejects them, so insert one directly to exercise the path.
defp insert_out_of_range_endgame do
fen = "3k4/2n2B2/1KP5/2B2p2/5b1p/7P/8/8 b - - 0 1"
{:ok, key} = Chesstrainer.Key.from_fen(fen)
Chesstrainer.Repo.insert!(%Chesstrainer.Endgames.Endgame{
fen: fen,
color: :black,
key: key,
result: :win,
rating: 1500
})
end
# Plays one optimal move, applies the opponent's reply, then a losing move,
# leaving a three-ply failed attempt to review.
defp seeded_attempt(conn) do
@@ -170,6 +185,16 @@ defmodule ChesstrainerWeb.EndgameLive.PlayTest do
play_move(view, endgame, "d1", "d7", "Qd7+")
assert render(view) =~ "cannot be graded"
end
test "blocks an out-of-range endgame as not covered", %{conn: conn} do
endgame = insert_out_of_range_endgame()
{:ok, view, _html} = live(conn, ~p"/endgames/#{endgame}/play")
html = render(view)
assert html =~ "Tablebase unavailable"
assert html =~ "not covered by the tablebase"
end
end
describe "chess_fen_invalid" do