diff --git a/lib/chesstrainer/endgames/motif_themes.ex b/lib/chesstrainer/endgames/motif_themes.ex new file mode 100644 index 0000000..87372ba --- /dev/null +++ b/lib/chesstrainer/endgames/motif_themes.ex @@ -0,0 +1,198 @@ +defmodule Chesstrainer.Endgames.MotifThemes do + @moduledoc """ + Derives objective motif themes by probing each endgame's position. + + Motifs describe the kind of problem, independent of the material family: an + endgame can be a rook endgame and an only-move puzzle at the same time. Every + motif is proved from the local Syzygy tables — one probe returns the root WDL, + the DTZ and every legal move with its own WDL — so nothing here is a guess and + nothing calls the remote backend. + + Motif links are recorded as `derived` and refreshed as a whole. Material + families, curated links and community links are untouched because the refresh + is scoped to the motif themes. + + Loss endgames are skipped: only-move is undefined when every move loses, and + the library no longer contains them. + """ + + import Ecto.Query, warn: false + + alias Chesstrainer.Endgames.Endgame + alias Chesstrainer.Endgames.Tablebase + alias Chesstrainer.Endgames.Tablebase.Backend.Fathom, as: FathomBackend + alias Chesstrainer.Repo + alias Chesstrainer.Themes + + @motifs [ + only_move: %{ + name: "only move", + description: + "Exactly one legal move keeps the result, so the puzzle is about finding the single accurate move." + }, + underpromotion: %{ + name: "underpromotion", + description: + "The result can only be preserved by promoting to a rook, bishop or knight; promoting to a queen does not work." + }, + fifty_move_draw: %{ + name: "50-move draw", + description: + "The result turns on the fifty-move rule: the win needs more moves than the halfmove clock allows, so the defender can claim a draw." + } + ] + + @type motif :: :only_move | :underpromotion | :fifty_move_draw + + @doc "The motif themes, in a stable order." + def motifs, do: @motifs + + @doc """ + Returns the motifs for one probed position. + + `moves` are Fathom move tuples `{wdl, from, to, promotes, ep, dtz}` and carry + the mover's perspective, so they are compared with the root WDL directly. + `halfmove_clock` comes from the FEN; the probe itself runs with `rule50 = 0`. + """ + @spec motifs_for(atom(), integer() | nil, [tuple()], non_neg_integer()) :: [motif()] + def motifs_for(wdl, dtz, moves, halfmove_clock) do + outcome = Tablebase.normalize_wdl(wdl) + + preserving = + Enum.filter(moves, fn {move_wdl, _from, _to, _promotes, _ep, _dtz} -> + Tablebase.normalize_wdl(move_wdl) == outcome + end) + + [] + |> maybe_only_move(outcome, moves, preserving) + |> maybe_underpromotion(preserving) + |> maybe_fifty_move(wdl, dtz, halfmove_clock) + end + + @doc """ + Creates or corrects the motif themes, keyed by motif. + + An existing theme with the same name is reused and its kind and description + are corrected, so a theme seeded as a technique becomes a motif without + losing its existing links. + """ + @spec ensure_themes() :: %{motif() => Chesstrainer.Themes.Theme.t()} + def ensure_themes do + Map.new(@motifs, fn {motif, attrs} -> + {:ok, theme} = Themes.get_or_create(attrs.name, "endgame", kind: :motif) + {motif, ensure_motif_theme(theme, attrs)} + end) + end + + @doc """ + Refreshes every endgame's derived motif links. + + Returns the number of links written, the number of endgames skipped because + the local tables could not answer them, and a count per motif. Re-running is + idempotent. + """ + @spec derive() :: %{ + links: non_neg_integer(), + skipped: non_neg_integer(), + by_motif: %{motif() => non_neg_integer()}, + themes: non_neg_integer() + } + def derive do + themes = ensure_themes() + motif_ids = Enum.map(themes, fn {_motif, theme} -> theme.id end) + + initial_counts = Map.new(@motifs, fn {motif, _attrs} -> {motif, 0} end) + + {links, skipped, by_motif} = + Endgame + |> where([e], e.result in [:win, :draw]) + |> select([e], {e.id, e.fen}) + |> Repo.all() + |> Enum.reduce({[], 0, initial_counts}, fn {id, fen}, {links, skipped, counts} -> + case probe(fen) do + {:ok, %{wdl: wdl, dtz: dtz, moves: moves}} -> + motifs = motifs_for(wdl, dtz, moves, halfmove_clock(fen)) + + links = + Enum.reduce(motifs, links, fn motif, acc -> + [{id, Map.fetch!(themes, motif).id} | acc] + end) + + counts = + Enum.reduce(motifs, counts, fn motif, acc -> + Map.update!(acc, motif, &(&1 + 1)) + end) + + {links, skipped, counts} + + {:error, _reason} -> + {links, skipped + 1, counts} + end + end) + + :ok = Themes.replace_theme_links(motif_ids, links) + + %{links: length(links), skipped: skipped, by_motif: by_motif, themes: map_size(themes)} + end + + defp ensure_motif_theme(theme, attrs) do + if theme.kind == :motif and (theme.description || "") == attrs.description do + theme + else + {:ok, updated} = + Themes.update_theme(theme, %{kind: :motif, description: attrs.description}) + + updated + end + end + + defp probe(fen), do: probe_module().probe_local_detail(fen) + + defp probe_module do + Application.get_env(:chesstrainer, :motif_probe, FathomBackend) + end + + defp maybe_only_move(acc, outcome, moves, preserving) do + if outcome in [:win, :draw] and length(moves) > 1 and length(preserving) == 1 do + [:only_move | acc] + else + acc + end + end + + defp maybe_underpromotion(acc, preserving) do + underpromotes? = + Enum.any?(preserving, fn {_wdl, _from, _to, promotes, _ep, _dtz} -> + promotes in [2, 3, 4] + end) + + queen_promotes? = + Enum.any?(preserving, fn {_wdl, _from, _to, promotes, _ep, _dtz} -> + promotes == 1 + end) + + if underpromotes? and not queen_promotes?, do: [:underpromotion | acc], else: acc + end + + defp maybe_fifty_move(acc, wdl, dtz, halfmove_clock) do + table_draw? = wdl in [:cursed_win, :blessed_loss] + + clock_exhausted? = + wdl == :win and is_integer(dtz) and dtz > 100 - halfmove_clock + + if table_draw? or clock_exhausted?, do: [:fifty_move_draw | acc], else: acc + end + + defp halfmove_clock(fen) do + case String.split(fen, " ") do + [_board, _active, _castling, _ep, clock, _fullmove] -> + case Integer.parse(clock) do + {value, _rest} -> value + :error -> 0 + end + + _ -> + 0 + end + end +end diff --git a/lib/chesstrainer/endgames/tablebase/backend/fathom.ex b/lib/chesstrainer/endgames/tablebase/backend/fathom.ex index fd3f1e0..1e74ff5 100644 --- a/lib/chesstrainer/endgames/tablebase/backend/fathom.ex +++ b/lib/chesstrainer/endgames/tablebase/backend/fathom.ex @@ -80,6 +80,38 @@ defmodule Chesstrainer.Endgames.Tablebase.Backend.Fathom do end end + @doc """ + Probes the local tablebase and returns the raw root outcome and move list. + + Unlike `probe_result_local/1`, this keeps the per-move tuples and the raw WDL + atom, including `:cursed_win` and `:blessed_loss`, which the motif derivation + needs. It never falls back to the remote backend or consults the cache. + + Returns `{:error, :unsupported}` when the local files cannot answer the + position, including a partial tablebase set where Fathom reports `:failed`. + """ + @spec probe_local_detail(String.t()) :: + {:ok, %{wdl: atom(), dtz: integer(), moves: [tuple()]}} + | {:error, :not_configured | :terminal | :unsupported} + def probe_local_detail(fen) do + with {:ok, largest} <- Local.check(), + pieces when is_integer(pieces) <- FEN.piece_count(fen), + true <- pieces <= largest || {:error, :unsupported}, + {:ok, {root, moves}} <- Nif.probe(fen) do + case root do + :failed -> {:error, :unsupported} + :checkmate -> {:error, :terminal} + :stalemate -> {:error, :terminal} + {wdl, _from, _to, _promotes, _ep, dtz} -> {:ok, %{wdl: wdl, dtz: dtz, moves: moves}} + end + else + {:error, :not_configured} = error -> error + {:error, :unsupported} = error -> error + {:error, _reason} -> {:error, :unsupported} + nil -> {:error, :unsupported} + end + end + defp fallback(fen) do (Application.get_env(:chesstrainer, :tablebase_fallback) || Lichess).probe(fen) end diff --git a/lib/chesstrainer/release.ex b/lib/chesstrainer/release.ex index ee96518..12de476 100644 --- a/lib/chesstrainer/release.ex +++ b/lib/chesstrainer/release.ex @@ -18,6 +18,28 @@ defmodule Chesstrainer.Release do {:ok, _, _} = Ecto.Migrator.with_repo(repo, &Ecto.Migrator.run(&1, :down, to: version)) end + @doc """ + Derives material family themes for the whole library. + + Runs in the release without starting the web application: `with_repo/2` + starts just the repository, which is all the derivation needs. + """ + def derive_material, do: with_repo(&Chesstrainer.Endgames.MaterialThemes.derive/0) + + @doc """ + Derives motif themes from the local tablebase for the whole library. + """ + def derive_motifs, do: with_repo(&Chesstrainer.Endgames.MotifThemes.derive/0) + + defp with_repo(fun) do + load_app() + + for repo <- repos() do + {:ok, result, _} = Ecto.Migrator.with_repo(repo, fn _repo -> fun.() end) + result + end + end + defp repos do Application.fetch_env!(@app, :ecto_repos) end diff --git a/lib/mix/tasks/themes.derive_motifs.ex b/lib/mix/tasks/themes.derive_motifs.ex new file mode 100644 index 0000000..6042f44 --- /dev/null +++ b/lib/mix/tasks/themes.derive_motifs.ex @@ -0,0 +1,32 @@ +defmodule Mix.Tasks.Themes.DeriveMotifs do + use Mix.Task + + @shortdoc "Tags every endgame with its tablebase-proved motifs" + + @moduledoc """ + Derives only-move, underpromotion and 50-move-draw motifs from the local + Syzygy tablebase. + + mix themes.derive_motifs + + The pass never calls the remote tablebase. Positions the local files cannot + answer are skipped and reported. Re-running is idempotent: only links to the + motif themes are replaced, so material, curated and community links survive. + """ + + @impl Mix.Task + def run(_args) do + Mix.Task.run("app.start") + + %{links: links, skipped: skipped, by_motif: by_motif, themes: themes} = + Chesstrainer.Endgames.MotifThemes.derive() + + Mix.shell().info( + "Motif themes: #{themes} themes, #{links} link(s) written, #{skipped} endgame(s) skipped." + ) + + for {motif, count} <- Enum.sort(by_motif) do + Mix.shell().info(" #{motif}: #{count}") + end + end +end diff --git a/test/chesstrainer/endgames/motif_themes_test.exs b/test/chesstrainer/endgames/motif_themes_test.exs new file mode 100644 index 0000000..bea7e10 --- /dev/null +++ b/test/chesstrainer/endgames/motif_themes_test.exs @@ -0,0 +1,170 @@ +defmodule Chesstrainer.Endgames.MotifThemesTest.Stub do + @moduledoc false + + def probe_local_detail(fen), do: Map.fetch!(Process.get(:motif_stub), fen) +end + +defmodule Chesstrainer.Endgames.MotifThemesTest do + use Chesstrainer.DataCase + + import Ecto.Query + + alias Chesstrainer.Endgames + alias Chesstrainer.Endgames.MotifThemes + alias Chesstrainer.Repo + alias Chesstrainer.Themes + + setup do + previous = Application.get_env(:chesstrainer, :motif_probe) + Application.put_env(:chesstrainer, :motif_probe, __MODULE__.Stub) + + on_exit(fn -> + if previous, + do: Application.put_env(:chesstrainer, :motif_probe, previous), + else: Application.delete_env(:chesstrainer, :motif_probe) + end) + + :ok + end + + describe "motifs_for/4" do + test "detects an only move for wins and draws" do + assert [:only_move] = MotifThemes.motifs_for(:win, 5, [move(:win), move(:draw)], 0) + + assert [:only_move] = + MotifThemes.motifs_for(:draw, 5, [move(:draw), move(:loss), move(:loss)], 0) + end + + test "does not report an only move when several moves preserve the result" do + assert [] = MotifThemes.motifs_for(:win, 5, [move(:win), move(:win)], 0) + end + + test "does not report an only move for a forced single move or a lost position" do + assert [] = MotifThemes.motifs_for(:win, 5, [move(:win)], 0) + assert [] = MotifThemes.motifs_for(:loss, 5, [move(:loss), move(:loss)], 0) + end + + test "requires an underpromotion while no queen promotion preserves the result" do + assert [:underpromotion] = + MotifThemes.motifs_for(:win, 5, [move(:win, 4), move(:win), move(:draw, 1)], 0) + + assert [] = MotifThemes.motifs_for(:win, 5, [move(:win, 4), move(:win, 1)], 0) + assert [] = MotifThemes.motifs_for(:win, 5, [move(:draw, 4), move(:win), move(:win)], 0) + end + + test "detects the 50-move rule from the raw WDL" do + assert [:fifty_move_draw] = + MotifThemes.motifs_for(:cursed_win, 120, [move(:cursed_win)], 0) + + assert [:fifty_move_draw] = + MotifThemes.motifs_for(:blessed_loss, 120, [move(:blessed_loss)], 0) + end + + test "detects the 50-move rule when the clock runs out before the next zeroing move" do + assert [:fifty_move_draw] = MotifThemes.motifs_for(:win, 60, [move(:win)], 50) + assert [] = MotifThemes.motifs_for(:win, 40, [move(:win)], 50) + assert [] = MotifThemes.motifs_for(:win, 100, [move(:win)], 0) + end + + test "a position can carry several motifs" do + assert [:underpromotion, :only_move] = + MotifThemes.motifs_for(:win, 5, [move(:win, 4), move(:draw)], 0) + end + end + + describe "derive/0" do + @win_fen "8/8/3k4/8/8/3K1R2/8/8 w - - 0 1" + @draw_fen "4k3/8/8/8/8/4p3/4P3/4K3 w - - 0 1" + @loss_fen "8/8/3k4/8/8/3K4/8/6q1 w - - 0 1" + + test "links the motifs reported for each endgame and skips losses" do + win = create_endgame!(@win_fen, :win) + draw = create_endgame!(@draw_fen, :draw) + loss = create_endgame!(@loss_fen, :loss) + + stub(%{ + win.fen => {:ok, %{wdl: :win, dtz: 5, moves: [move(:win), move(:draw)]}}, + draw.fen => {:ok, %{wdl: :cursed_win, dtz: 120, moves: [move(:cursed_win)]}} + }) + + assert %{links: 2, skipped: 0, themes: 3} = MotifThemes.derive() + + assert theme_names(win) == ["only move"] + assert theme_names(draw) == ["50-move draw"] + assert theme_names(loss) == [] + + assert Enum.all?(Themes.list_themes(), &(&1.kind == :motif)) + assert Enum.all?(Themes.list_themes(), &(&1.description not in [nil, ""])) + end + + test "reports endgames the local tables cannot answer" do + endgame = create_endgame!(@win_fen, :win) + stub(%{endgame.fen => {:error, :unsupported}}) + + assert %{links: 0, skipped: 1} = MotifThemes.derive() + assert theme_names(endgame) == [] + end + + test "is idempotent and leaves material, curated and community links alone" do + win = create_endgame!(@win_fen, :win) + stub(%{win.fen => {:ok, %{wdl: :win, dtz: 5, moves: [move(:win), move(:draw)]}}}) + + {:ok, lucena} = Themes.create_theme(%{name: "Lucena", category: :endgame}) + + {:ok, rook_endgame} = + Themes.create_theme(%{name: "rook endgame", kind: :material, category: :endgame}) + + {:ok, _} = Themes.tag_endgames(lucena, [win.id], :curated) + :ok = Themes.sync_derived_themes(win.id, [rook_endgame.id]) + + MotifThemes.derive() + first = link_rows(win.id) + MotifThemes.derive() + + assert link_rows(win.id) == first + assert {lucena.id, "curated"} in first + assert {rook_endgame.id, "derived"} in first + assert length(first) == 3 + end + + test "corrects an existing technique theme into a motif theme" do + {:ok, existing} = Themes.create_theme(%{name: "only move", category: :endgame}) + endgame = create_endgame!(@win_fen, :win) + stub(%{endgame.fen => {:ok, %{wdl: :win, dtz: 5, moves: [move(:win), move(:draw)]}}}) + + MotifThemes.derive() + + theme = Themes.get_theme!(existing.id) + assert theme.kind == :motif + assert theme.description =~ "Exactly one legal move" + end + end + + defp stub(responses), do: Process.put(:motif_stub, responses) + + defp move(wdl, promotes \\ 0, dtz \\ 0), do: {wdl, 0, 0, promotes, 0, dtz} + + defp create_endgame!(fen, result) do + {:ok, endgame} = + Endgames.create_endgame(%{fen: fen, color: :white, result: result, rating: 1500}) + + endgame + end + + defp theme_names(endgame) do + endgame + |> Map.fetch!(:id) + |> link_rows() + |> Enum.map(fn {theme_id, _source} -> Themes.get_theme!(theme_id).name end) + |> Enum.sort() + end + + defp link_rows(endgame_id) do + Repo.all( + from l in "endgames_themes", + where: l.endgame_id == type(^endgame_id, :binary_id), + select: {l.theme_id, l.source}, + order_by: l.theme_id + ) + end +end diff --git a/test/chesstrainer/endgames/tablebase/backend/fathom_test.exs b/test/chesstrainer/endgames/tablebase/backend/fathom_test.exs index f055228..505a7e9 100644 --- a/test/chesstrainer/endgames/tablebase/backend/fathom_test.exs +++ b/test/chesstrainer/endgames/tablebase/backend/fathom_test.exs @@ -6,6 +6,11 @@ defmodule Chesstrainer.Endgames.Tablebase.Backend.FathomTest.Stub do def probe(_fen), do: {:ok, %Tablebase{category: :draw, checkmate: false, moves: []}} end +defmodule Chesstrainer.Endgames.Tablebase.Backend.FathomTest.ExplodingFallback do + @moduledoc false + def probe(_fen), do: raise("the remote tablebase must not be called") +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 @@ -18,6 +23,7 @@ defmodule Chesstrainer.Endgames.Tablebase.Backend.FathomTest do @krk "4k3/8/8/8/8/8/8/R3K3 w - - 0 1" @mate "7k/6Q1/5K2/8/8/8/8/8 b - - 0 1" + @kpk "8/8/3k4/8/8/3KP3/8/8 w - - 0 1" test "probes a KRvK position locally" do assert {:ok, %Tablebase{} = tablebase} = FathomBackend.probe(@krk) @@ -82,4 +88,37 @@ defmodule Chesstrainer.Endgames.Tablebase.Backend.FathomTest do assert {:ok, %Tablebase{category: :draw}} = FathomBackend.probe(@krk) end end + + describe "probe_local_detail/1" do + test "returns the raw root WDL, DTZ and every legal move" do + assert {:ok, %{wdl: :win, dtz: dtz, moves: moves}} = + FathomBackend.probe_local_detail(@krk) + + assert is_integer(dtz) + assert length(moves) == 15 + assert Enum.all?(moves, &(elem(&1, 0) in [:win, :cursed_win, :draw, :blessed_loss, :loss])) + end + + test "returns terminal for a finished position" do + assert {:error, :terminal} = FathomBackend.probe_local_detail(@mate) + end + + test "returns unsupported when the local files cannot answer the position" do + assert {:error, :unsupported} = FathomBackend.probe_local_detail(@kpk) + end + + test "never calls the remote backend" do + 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__.ExplodingFallback) + + assert {:error, :unsupported} = FathomBackend.probe_local_detail(@kpk) + end + end end