From 946fc38756dc30bd70c9ae2c7117c8e9e2722803 Mon Sep 17 00:00:00 2001 From: Owen Rees Date: Tue, 17 Nov 2026 21:18:11 +0100 Subject: [PATCH] Derive disjoint material family themes from each endgame's Key (#193) Every endgame now belongs to exactly one material family derived from its Key: pawn, rook, rook and pawn, queen, queen and pawn, minor piece, minor piece and pawn, basic mate, king and pawn, or bare king other. The bare-king families are split out because those positions teach a mating or promotion technique rather than a general material class. Family membership is objective, so a derivation pass owns links to its themes: refreshing rewrites them as derived and removes a curated link that contradicts the family, while technique themes are untouched. Re-running is idempotent. A mix task applies the mapping to the whole library. Seeds add the king technique themes for later human tagging. Closes #186 --- lib/chesstrainer/endgames/material_themes.ex | 215 ++++++++++++++++++ lib/chesstrainer/themes.ex | 42 ++++ lib/mix/tasks/themes.derive_material.ex | 31 +++ priv/repo/seeds/endgames/win.ex | 3 +- priv/repo/seeds/themes.ex | 4 + .../endgames/material_themes_test.exs | 173 ++++++++++++++ 6 files changed, 466 insertions(+), 2 deletions(-) create mode 100644 lib/chesstrainer/endgames/material_themes.ex create mode 100644 lib/mix/tasks/themes.derive_material.ex create mode 100644 test/chesstrainer/endgames/material_themes_test.exs diff --git a/lib/chesstrainer/endgames/material_themes.ex b/lib/chesstrainer/endgames/material_themes.ex new file mode 100644 index 0000000..a4b153b --- /dev/null +++ b/lib/chesstrainer/endgames/material_themes.ex @@ -0,0 +1,215 @@ +defmodule Chesstrainer.Endgames.MaterialThemes do + @moduledoc """ + Derives each endgame's material family from its canonical Key. + + Every endgame belongs to exactly one family, so the themes behave as a + partition: selecting several in a filter produces their union, never an + ambiguous intersection. A lone king against heavy or pawn material is split + out because those positions teach a specific technique — basic mate or + promotion — rather than a general material class. + + Families are derived, never judged. They are stored with source `derived`, so + a refresh replaces them without touching curated or community themes. + Positions with no legal content (`K v K`) and rows without a Key are skipped. + """ + + import Ecto.Query, warn: false + + alias Chesstrainer.Endgames.Endgame + alias Chesstrainer.Repo + alias Chesstrainer.Themes + + @families [ + basic_mate: %{ + name: "basic mate", + description: + "A lone king against the queen or a rook, with no pawns: the puzzle is about delivering mate." + }, + king_and_pawn: %{ + name: "king and pawn", + description: + "A lone king against king and pawns: the puzzle is about promotion, or holding the draw." + }, + bare_king_other: %{ + name: "bare king other", + description: + "A lone king against minor pieces, or against pawns and pieces: usually a technique exercise with little counterplay." + }, + queen_and_pawn: %{ + name: "queen and pawn", + description: "Queens and pawns on the board." + }, + queen_endgame: %{ + name: "queen endgame", + description: "Queens on the board, with no pawns." + }, + rook_and_pawn: %{ + name: "rook and pawn", + description: "Rooks and pawns, with no queens." + }, + rook_endgame: %{ + name: "rook endgame", + description: "Rooks, with no queens and no pawns." + }, + minor_piece_and_pawn: %{ + name: "minor piece and pawn", + description: "Bishops and knights with pawns, with no queens or rooks." + }, + minor_piece_endgame: %{ + name: "minor piece endgame", + description: "Bishops and knights, with no queens, rooks or pawns." + }, + pawn_endgame: %{ + name: "pawn endgame", + description: "Kings and pawns only." + } + ] + + @type family :: + :basic_mate + | :king_and_pawn + | :bare_king_other + | :queen_and_pawn + | :queen_endgame + | :rook_and_pawn + | :rook_endgame + | :minor_piece_and_pawn + | :minor_piece_endgame + | :pawn_endgame + + @doc "The material families, in a stable order." + def families, do: @families + + @doc """ + Returns the material family for a Key. + + Returns `:kings_only` for `"K v K"` and `:unknown` when the Key is missing or + not shaped like `" v "`. + """ + @spec family(String.t() | nil) :: family() | :kings_only | :unknown + def family(key) when is_binary(key) do + case String.split(key, " v ") do + [a, b] -> + cond do + bare?(a) and bare?(b) -> :kings_only + bare?(a) -> bare_king_family(counts(b)) + bare?(b) -> bare_king_family(counts(a)) + true -> material_family(merge(counts(a), counts(b))) + end + + _ -> + :unknown + end + end + + def family(_key), do: :unknown + + @doc """ + Creates or corrects the material themes, keyed by family. + + 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 material theme + without losing its existing links. + """ + @spec ensure_themes() :: %{family() => Chesstrainer.Themes.Theme.t()} + def ensure_themes do + Map.new(@families, fn {family, attrs} -> + {:ok, theme} = Themes.get_or_create(attrs.name, "endgame", kind: :material) + {family, ensure_material_theme(theme, attrs)} + end) + end + + @doc """ + Refreshes every endgame's derived material theme. + + Returns the number of endgames tagged, the number skipped (kings only or no + Key) and the number of material themes. Re-running is idempotent. + """ + @spec derive() :: %{ + tagged: non_neg_integer(), + skipped: non_neg_integer(), + themes: non_neg_integer() + } + def derive do + themes = ensure_themes() + material_ids = Enum.map(themes, fn {_family, theme} -> theme.id end) + + {links, skipped} = + Endgame + |> select([e], {e.id, e.key}) + |> Repo.all() + |> Enum.reduce({[], 0}, fn {id, key}, {links, skipped} -> + case family(key) do + family when family in [:kings_only, :unknown] -> + {links, skipped + 1} + + family -> + {[{id, Map.fetch!(themes, family).id} | links], skipped} + end + end) + + :ok = Themes.replace_theme_links(material_ids, links) + + %{tagged: length(links), skipped: skipped, themes: map_size(themes)} + end + + defp ensure_material_theme(theme, attrs) do + if theme.kind == :material and (theme.description || "") == attrs.description do + theme + else + {:ok, updated} = + Themes.update_theme(theme, %{kind: :material, description: attrs.description}) + + updated + end + end + + defp bare?(side), do: side == "K" + + defp bare_king_family(counts) do + cond do + count(counts, "P") == 0 and (count(counts, "Q") > 0 or count(counts, "R") > 0) -> + :basic_mate + + count(counts, "P") > 0 and count(counts, "Q") == 0 and count(counts, "R") == 0 -> + :king_and_pawn + + true -> + :bare_king_other + end + end + + defp material_family(counts) do + cond do + count(counts, "Q") > 0 and count(counts, "P") > 0 -> + :queen_and_pawn + + count(counts, "Q") > 0 -> + :queen_endgame + + count(counts, "R") > 0 and count(counts, "P") > 0 -> + :rook_and_pawn + + count(counts, "R") > 0 -> + :rook_endgame + + count(counts, "B") + count(counts, "N") > 0 and count(counts, "P") > 0 -> + :minor_piece_and_pawn + + count(counts, "B") + count(counts, "N") > 0 -> + :minor_piece_endgame + + count(counts, "P") > 0 -> + :pawn_endgame + + true -> + :kings_only + end + end + + defp counts(side), do: Enum.frequencies(String.graphemes(side)) + + defp merge(left, right), do: Map.merge(left, right, fn _piece, a, b -> a + b end) + + defp count(counts, piece), do: Map.get(counts, piece, 0) +end diff --git a/lib/chesstrainer/themes.ex b/lib/chesstrainer/themes.ex index 0f61a83..756bdaf 100644 --- a/lib/chesstrainer/themes.ex +++ b/lib/chesstrainer/themes.ex @@ -221,6 +221,48 @@ defmodule Chesstrainer.Themes do end end + @doc """ + Replaces every link to `scoped_theme_ids` with the derived links in `links`. + + This is for themes that are objectively derived: the pass owns its themes + entirely, so a link's previous source is irrelevant and every link is + rewritten as `derived`. Links to themes outside `scoped_theme_ids` — curated + or community — are untouched. + + The operation is a full refresh for the given themes, so it can move an + endgame between families when a rule changes. `links` is a list of + `{endgame_id, theme_id}` pairs. + """ + @spec replace_theme_links([term()], [{Ecto.UUID.t(), term()}]) :: :ok + def replace_theme_links(scoped_theme_ids, links) when is_list(links) do + now = DateTime.utc_now() |> DateTime.truncate(:second) + + Repo.transaction(fn -> + if scoped_theme_ids != [] do + Repo.delete_all( + from l in "endgames_themes", + where: l.theme_id in ^scoped_theme_ids + ) + end + + links + |> Enum.map(fn {endgame_id, theme_id} -> + %{ + endgame_id: Ecto.UUID.dump!(endgame_id), + theme_id: theme_id, + source: "derived", + inserted_at: now + } + end) + |> Enum.chunk_every(5_000) + |> Enum.each(fn rows -> + Repo.insert_all("endgames_themes", rows, on_conflict: :nothing) + end) + end) + + :ok + end + @doc """ Replaces the derived theme links for one endgame. diff --git a/lib/mix/tasks/themes.derive_material.ex b/lib/mix/tasks/themes.derive_material.ex new file mode 100644 index 0000000..a3a65d8 --- /dev/null +++ b/lib/mix/tasks/themes.derive_material.ex @@ -0,0 +1,31 @@ +defmodule Mix.Tasks.Themes.DeriveMaterial do + use Mix.Task + + @shortdoc "Tags every endgame with its material family theme" + + @moduledoc """ + Derives each endgame's material family from its Key and stores the result as + a derived theme. + + mix themes.derive_material + + Every endgame belongs to exactly one family, so the themes partition the + library. Re-running is idempotent: only derived links are replaced, and + curated or community links are untouched. + + Positions that are kings only, or that have no Key, are reported as skipped. + """ + + @impl Mix.Task + def run(_args) do + Mix.Task.run("app.start") + + %{tagged: tagged, skipped: skipped, themes: themes} = + Chesstrainer.Endgames.MaterialThemes.derive() + + Mix.shell().info( + "Material themes: #{themes} themes, #{tagged} endgames tagged, " <> + "#{skipped} skipped (kings only or no Key)." + ) + end +end diff --git a/priv/repo/seeds/endgames/win.ex b/priv/repo/seeds/endgames/win.ex index a4344d7..9bb2a99 100644 --- a/priv/repo/seeds/endgames/win.ex +++ b/priv/repo/seeds/endgames/win.ex @@ -6,8 +6,7 @@ defmodule Chesstrainer.Repo.Seeds.Endgames.Win do color: :white, message: "Rook vs king endgame", notes: "Basic rook endgame", - result: :win, - themes: ["rook endgame"] + result: :win }, %{ fen: "8/8/8/1P4p1/5k2/5p2/P6K/8 b - - 0 0", diff --git a/priv/repo/seeds/themes.ex b/priv/repo/seeds/themes.ex index d770e99..8d6941c 100644 --- a/priv/repo/seeds/themes.ex +++ b/priv/repo/seeds/themes.ex @@ -8,6 +8,10 @@ defmodule Chesstrainer.Repo.Seeds.Themes do "Lucena", "Philidor", "opposition", + "key squares", + "triangulation", + "shouldering", + "king activity", "promotion", "stalemate" ] diff --git a/test/chesstrainer/endgames/material_themes_test.exs b/test/chesstrainer/endgames/material_themes_test.exs new file mode 100644 index 0000000..2d15b33 --- /dev/null +++ b/test/chesstrainer/endgames/material_themes_test.exs @@ -0,0 +1,173 @@ +defmodule Chesstrainer.Endgames.MaterialThemesTest do + use Chesstrainer.DataCase + + import Ecto.Query + + alias Chesstrainer.Endgames + alias Chesstrainer.Endgames.MaterialThemes + alias Chesstrainer.Repo + alias Chesstrainer.Themes + + @kr_v_k "8/8/3k4/8/8/3K1R2/8/8 w - - 0 1" + @kp_v_k "8/8/3k4/8/8/3KP3/8/8 w - - 0 1" + @kbn_v_k "8/8/3k4/8/8/3KBN2/8/8 w - - 0 1" + @krp_v_k "8/8/3k4/8/8/3KR2P/8/8 w - - 0 1" + @kp_v_kp "4k3/8/8/8/8/4p3/4P3/4K3 w - - 0 1" + @kq_v_kp "8/8/3k4/8/8/3K1Q1p/8/8 w - - 0 1" + @kq_v_kq "3q4/8/3k4/8/8/3K1Q2/8/8 w - - 0 1" + @kn_v_kp "8/8/3k4/8/8/3KN2p/8/8 w - - 0 1" + @kb_v_kb "8/8/3k1b2/8/8/3K1B2/8/8 w - - 0 1" + @krp_v_kr "8/8/3k4/8/8/3KR2P/8/5r2 w - - 0 1" + @kr_v_kr "8/8/3k4/8/8/3K1R2/8/5r2 b - - 0 1" + @k_v_k "8/8/3k4/8/8/3K4/8/8 w - - 0 1" + + describe "family/1" do + test "classifies a lone king against heavy or pawn material" do + assert MaterialThemes.family("KQ v K") == :basic_mate + assert MaterialThemes.family("KR v K") == :basic_mate + assert MaterialThemes.family("KP v K") == :king_and_pawn + assert MaterialThemes.family("KPP v K") == :king_and_pawn + assert MaterialThemes.family("KBN v K") == :bare_king_other + assert MaterialThemes.family("KRP v K") == :bare_king_other + end + + test "classifies material presence into one family" do + assert MaterialThemes.family("KP v KP") == :pawn_endgame + assert MaterialThemes.family("KQ v KP") == :queen_and_pawn + assert MaterialThemes.family("KQ v KQ") == :queen_endgame + assert MaterialThemes.family("KRP v KR") == :rook_and_pawn + assert MaterialThemes.family("KR v KR") == :rook_endgame + assert MaterialThemes.family("KN v KP") == :minor_piece_and_pawn + assert MaterialThemes.family("KB v KB") == :minor_piece_endgame + end + + test "flags content-free and malformed keys" do + assert MaterialThemes.family("K v K") == :kings_only + assert MaterialThemes.family(nil) == :unknown + assert MaterialThemes.family("not a key") == :unknown + end + end + + describe "derive/0" do + test "creates every material family as a material theme" do + MaterialThemes.derive() + + themes = Themes.list_themes() + + assert length(themes) == length(MaterialThemes.families()) + assert Enum.all?(themes, &(&1.kind == :material)) + assert Enum.all?(themes, &(&1.description not in [nil, ""])) + end + + test "tags every endgame with exactly one family" do + pawn = create_endgame!(@kp_v_kp) + rook = create_endgame!(@kr_v_kr) + rook_and_pawn = create_endgame!(@krp_v_kr) + queen_and_pawn = create_endgame!(@kq_v_kp) + queen = create_endgame!(@kq_v_kq) + minor_and_pawn = create_endgame!(@kn_v_kp) + minor = create_endgame!(@kb_v_kb) + mate = create_endgame!(@kr_v_k) + promotion = create_endgame!(@kp_v_k) + bare_minor = create_endgame!(@kbn_v_k) + bare_other = create_endgame!(@krp_v_k) + kings_only = create_endgame!(@k_v_k) + + assert %{tagged: 11, skipped: 1} = MaterialThemes.derive() + + assert ["pawn endgame"] = theme_names(pawn) + assert ["rook endgame"] = theme_names(rook) + assert ["rook and pawn"] = theme_names(rook_and_pawn) + assert ["queen and pawn"] = theme_names(queen_and_pawn) + assert ["queen endgame"] = theme_names(queen) + assert ["minor piece and pawn"] = theme_names(minor_and_pawn) + assert ["minor piece endgame"] = theme_names(minor) + assert ["basic mate"] = theme_names(mate) + assert ["king and pawn"] = theme_names(promotion) + assert ["bare king other"] = theme_names(bare_minor) + assert ["bare king other"] = theme_names(bare_other) + assert [] = theme_names(kings_only) + end + + test "corrects an existing technique theme and claims its links as derived" do + {:ok, existing} = Themes.create_theme(%{name: "rook endgame", category: :endgame}) + endgame = create_endgame!(@kr_v_kr, [existing]) + + MaterialThemes.derive() + + theme = Themes.get_theme!(existing.id) + assert theme.kind == :material + assert theme.description =~ "Rooks" + + assert [{theme_id, "derived"}] = link_rows(endgame.id) + assert theme_id == existing.id + end + + test "removes a curated link to a material theme that contradicts the family" do + {:ok, rook} = Themes.create_theme(%{name: "rook endgame", category: :endgame}) + mate = create_endgame!(@kr_v_k, [rook]) + + MaterialThemes.derive() + + assert ["basic mate"] = theme_names(mate) + end + + test "is idempotent" do + endgame = create_endgame!(@kq_v_kp) + + MaterialThemes.derive() + first = link_rows(endgame.id) + MaterialThemes.derive() + + assert link_rows(endgame.id) == first + assert length(first) == 1 + end + + test "leaves curated and community links to other themes alone" do + {:ok, lucena} = Themes.create_theme(%{name: "Lucena", category: :endgame}) + endgame = create_endgame!(@kr_v_kr) + insert_link(endgame.id, lucena.id, "community") + + MaterialThemes.derive() + + rows = link_rows(endgame.id) + assert {lucena.id, "community"} in rows + assert length(rows) == 2 + end + end + + defp create_endgame!(fen, themes \\ []) do + {:ok, endgame} = + Endgames.create_endgame(%{fen: fen, color: :white, result: :win, rating: 1500}, themes) + + 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 + + defp insert_link(endgame_id, theme_id, source) do + Repo.insert_all("endgames_themes", [ + %{ + endgame_id: Ecto.UUID.dump!(endgame_id), + theme_id: theme_id, + source: source, + inserted_at: DateTime.utc_now() |> DateTime.truncate(:second) + } + ]) + end +end