diff --git a/GLOSSARY.md b/GLOSSARY.md index 90b7884..7f22a54 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -105,6 +105,14 @@ carries a start time and a rating baseline for the timer and rating-gain monitor. Ephemeral — it lives only in the running LiveView, never persisted. _Avoid_: Run, game, attempt +**Repeat window**: +The minimum interval before the same endgame may be served to the same user +again. Selection skips endgames attempted inside the window; only when nothing +else is available does the least recently attempted endgame come back. It is +independent of the rating window, which decides whether a replay may move a +rating. +_Avoid_: Cooldown (reserved for tablebase rate-limiting), due date + ## Ratings **Rating**: @@ -128,11 +136,13 @@ systems; the trainer deliberately does not track it. _Avoid_: Variance, inconsistency **Difficulty**: -A choice — `easy`, `medium` or `hard` — that selects which puzzles to serve -relative to the current user's rating: `medium` is near the user's rating, -`easy` below it, `hard` above it. The band width is a configured constant. It is -a property of a session, not of an endgame — the same endgame is easy for one -user and hard for another. +A choice — `easy`, `medium` or `hard` — that biases which puzzles are served +relative to the current user's rating: `medium` centres on the user's rating, +`easy` below it, `hard` above it. Candidates are weighted by how close their +rating is to that centre, so a session draws mostly from near the target but the +whole library stays reachable. The spread is a configured constant. It is a +property of a session, not of an endgame — the same endgame is easy for one user +and hard for another. _Avoid_: Level, rank, tier ## Infrastructure diff --git a/config/config.exs b/config/config.exs index 9991f63..6db7d31 100644 --- a/config/config.exs +++ b/config/config.exs @@ -61,11 +61,16 @@ config :chesstrainer, :ratings, window_days: 7, rd_inflation_c: 10.0 -# Difficulty bands for puzzle sessions. An endgame is "medium" when its rating -# falls within `band_width` of the user's rating, "easy" below that band and -# "hard" above it. Tweak to widen or narrow the served difficulty (e.g. 150 or -# 200). -config :chesstrainer, :puzzles, band_width: 100 +# Puzzle selection. Difficulty is a weighted bias towards a target rating — +# `medium` targets the user's rating, `easy` 200 below it and `hard` 200 above +# it — and `spread` is how many rating points it takes for a puzzle's chance to +# fall off by a factor of e. `repeat_window_days` is how long an attempted +# puzzle stays out of the pool. Tweak `spread` to widen or narrow the served +# difficulty (e.g. 100 or 250). +config :chesstrainer, :puzzles, + spread: 150, + repeat_window_days: 30, + targets: [easy: -200, medium: 0, hard: 200] # Public codes of the endgames pinned to the landing-page puzzle grid, in # display order. When empty (or short) the grid is topped up with a date-seeded diff --git a/lib/chesstrainer/attempts.ex b/lib/chesstrainer/attempts.ex index 74f3766..4b4fc31 100644 --- a/lib/chesstrainer/attempts.ex +++ b/lib/chesstrainer/attempts.ex @@ -106,8 +106,8 @@ defmodule Chesstrainer.Attempts do @doc """ The distinct endgame ids `user_id` has attempted in the last `days` days. - Used by puzzle selection to prefer fresh puzzles; a retry still counts as an - attempt, even though the rating window leaves it unrated. + Used by puzzle selection to skip puzzles inside the repeat window; a retry + still counts as an attempt, even though the rating window leaves it unrated. """ def recent_endgame_ids(user_id, days \\ 30) do cutoff = DateTime.add(DateTime.utc_now(), -days, :day) diff --git a/lib/chesstrainer/puzzles.ex b/lib/chesstrainer/puzzles.ex index 9b13ac0..0b241d1 100644 --- a/lib/chesstrainer/puzzles.ex +++ b/lib/chesstrainer/puzzles.ex @@ -2,14 +2,21 @@ defmodule Chesstrainer.Puzzles do @moduledoc """ Selects endgames to serve as puzzles. - A puzzle is played at one of three difficulties — `:easy`, `:medium` or - `:hard` — defined relative to the current user's rating: `:medium` is within - a configurable band of the user's rating, `:easy` below it and `:hard` above - it. The same endgame is therefore easy for one player and hard for another. + Difficulty is a bias, not a filter. Every endgame is weighted by how close its + rating is to a target derived from the user's rating — the user's own rating + for `:medium`, below it for `:easy` and above it for `:hard` — and one + candidate is drawn from that weighted distribution. Nearby endgames are much + more likely, but the whole library stays reachable, so a thin region around + the user's rating can never leave the pool empty. - Selection prefers endgames the user has not attempted in the last 30 days. - When that pool is empty it falls back to any endgame in the band; the rating - window keeps a recent replay unrated until it expires. + Endgames the user has attempted inside the repeat window are skipped, as is + anything passed in `:exclude_ids` (the puzzles already served in a session). + Only when every candidate is excluded does selection fall back to the least + recently attempted endgame, so the repeat is the most overdue one rather than + an arbitrary one. + + The same endgame is therefore easy for one player and hard for another: a + rating is what makes the two comparable. """ import Ecto.Query, warn: false @@ -17,95 +24,115 @@ defmodule Chesstrainer.Puzzles do alias Chesstrainer.Repo alias Chesstrainer.Accounts.User alias Chesstrainer.Attempts + alias Chesstrainer.Attempts.Attempt alias Chesstrainer.Endgames.Endgame - @default_band_width 100 + @default_spread 150 + @default_repeat_window_days 30 + @default_targets [easy: -200, medium: 0, hard: 200] @difficulties [:easy, :medium, :hard] @doc "The difficulties a session can be played at." def difficulties, do: @difficulties @doc """ - The half-width of the medium band, in rating points. + How far, in rating points, a puzzle's likelihood falls off from the target. - Configured under `:chesstrainer, :puzzles, :band_width`. + A larger spread draws more widely around the target. Configured under + `:chesstrainer, :puzzles, :spread`. """ - def band_width do - :chesstrainer - |> Application.get_env(:puzzles, []) - |> Keyword.get(:band_width, @default_band_width) - end + def spread, do: setting(:spread, @default_spread) @doc """ - The `{min, max}` rating range for `difficulty` relative to `rating`. + The minimum gap, in days, before the same endgame may be served again. - A `nil` bound is open-ended. + Configured under `:chesstrainer, :puzzles, :repeat_window_days`. """ - def difficulty_range(rating, difficulty) when difficulty in @difficulties do - width = band_width() + def repeat_window_days, do: setting(:repeat_window_days, @default_repeat_window_days) - case difficulty do - :easy -> {nil, rating - width} - :medium -> {rating - width, rating + width} - :hard -> {rating + width, nil} - end + @doc """ + The rating `difficulty` aims at, given the player's `rating`. + + The offsets are configured under `:chesstrainer, :puzzles, :targets`. + """ + def difficulty_target(rating, difficulty) when difficulty in @difficulties do + rating + Keyword.fetch!(setting(:targets, @default_targets), difficulty) end @doc """ Picks the next puzzle for `user` at `difficulty`, using `user.rating` as the baseline. - `:exclude_ids` (default `[]`) skips endgames by id — used to avoid repeating - the puzzle just played. Returns `nil` when no endgame exists at all. + `:exclude_ids` (default `[]`) skips endgames by id — used for the puzzles + already served in this session. Returns `nil` when no endgame exists at all. """ def next_endgame(%User{} = user, difficulty, opts \\ []) when difficulty in @difficulties do exclude_ids = Keyword.get(opts, :exclude_ids, []) - band = difficulty_range(user.rating, difficulty) - recent_ids = Attempts.recent_endgame_ids(user.id) + recent_ids = Attempts.recent_endgame_ids(user.id, repeat_window_days()) + target = difficulty_target(user.rating, difficulty) - fresh = - Endgame - |> in_band(band) - |> skip_ids(exclude_ids) - |> skip_ids(recent_ids) - |> random_one() - - fresh || fallback(user.rating, band, exclude_ids) - end - - defp fallback(rating, band, exclude_ids) do Endgame - |> in_band(band) - |> skip_ids(exclude_ids) - |> random_one() + |> on_side_of(user.rating, difficulty) + |> skip_ids(exclude_ids ++ recent_ids) + |> weighted_one(target) |> case do - nil -> nearest(rating, exclude_ids) + nil -> least_recently_attempted(user.id, exclude_ids) endgame -> endgame end end - defp nearest(rating, exclude_ids) do + # Keep the labels honest: "easy" never serves above the user's rating plus the + # spread, and "hard" never below it minus the spread. "medium" is open, which + # is what lets it reach the rest of the library. + defp on_side_of(query, _rating, :medium), do: query + + defp on_side_of(query, rating, :easy), + do: where(query, [e], e.rating <= ^(rating + spread())) + + defp on_side_of(query, rating, :hard), + do: where(query, [e], e.rating >= ^(rating - spread())) + + # Draw one row with probability proportional to + # `exp(-|rating - target| / spread)`: an exponential race, where the row with + # the smallest `-ln(U) / weight` wins. + defp weighted_one(query, target) do + spread = spread() * 1.0 + target = target * 1.0 + + query + |> order_by( + [e], + fragment("-ln(1 - random()) * exp(abs(? - ?) / ?)", e.rating, ^target, ^spread) + ) + |> limit(1) + |> Repo.one() + end + + # Every candidate is excluded, so the repeat window is overruled: serve + # whatever the user has waited longest to see again. + defp least_recently_attempted(user_id, exclude_ids) do + attempted = + Attempt + |> where([a], a.user_id == ^user_id) + |> group_by([a], a.endgame_id) + |> select([a], %{endgame_id: a.endgame_id, last_at: max(a.inserted_at)}) + Endgame |> skip_ids(exclude_ids) - |> order_by([e], asc: fragment("ABS(? - ?)", e.rating, ^rating)) + |> join(:left, [e], a in subquery(attempted), on: a.endgame_id == e.id) + |> order_by([_e, a], asc_nulls_first: a.last_at) + |> order_by([e], fragment("random()")) |> limit(1) |> Repo.one() end - defp random_one(query) do - query - |> order_by([e], fragment("RANDOM()")) - |> limit(1) - |> Repo.one() - end - - defp in_band(query, {nil, max}), do: where(query, [e], e.rating <= ^max) - defp in_band(query, {min, nil}), do: where(query, [e], e.rating >= ^min) - - defp in_band(query, {min, max}), - do: where(query, [e], e.rating >= ^min and e.rating <= ^max) - defp skip_ids(query, []), do: query defp skip_ids(query, ids), do: where(query, [e], e.id not in ^ids) + + defp setting(key, default) do + :chesstrainer + |> Application.get_env(:puzzles, []) + |> Keyword.get(key, default) + end end diff --git a/lib/chesstrainer_web/live/endgame_live/guest_train.ex b/lib/chesstrainer_web/live/endgame_live/guest_train.ex index 885fdbb..84408e3 100644 --- a/lib/chesstrainer_web/live/endgame_live/guest_train.ex +++ b/lib/chesstrainer_web/live/endgame_live/guest_train.ex @@ -135,7 +135,10 @@ defmodule ChesstrainerWeb.EndgameLive.GuestTrain do @impl true def mount(_params, _session, socket) do - socket = assign(socket, :limit, GuestLimits.limit()) + socket = + socket + |> assign(:limit, GuestLimits.limit()) + |> assign(:served_ids, []) cond do signed_in?(socket) -> @@ -217,11 +220,7 @@ defmodule ChesstrainerWeb.EndgameLive.GuestTrain do |> assign(:limit_reached, retry_ms) {:ok, _remaining} -> - endgame = - Endgames.random_endgame(exclude_ids: [socket.assigns.endgame.id]) || - Endgames.random_endgame() - - case endgame do + case random_unserved(socket) do nil -> assign(socket, :empty, :exhausted) endgame -> start_guest_puzzle(socket, socket.assigns.guest_address, endgame) end @@ -234,13 +233,21 @@ defmodule ChesstrainerWeb.EndgameLive.GuestTrain do {:ok, limit_wall(socket, address, retry_ms)} {:ok, _remaining} -> - case Endgames.random_endgame() do + case random_unserved(socket) do nil -> {:ok, empty_pool(socket, address)} endgame -> {:ok, start_guest_puzzle(socket, address, endgame)} end end end + # Prefer an endgame this visitor has not seen in this session. Once the whole + # pool is served — only possible on a very long guest session — start over + # rather than dead-end. + defp random_unserved(socket) do + Endgames.random_endgame(exclude_ids: socket.assigns.served_ids) || + Endgames.random_endgame() + end + defp start_guest_puzzle(socket, address, endgame) do case GuestLimits.take(address) do {:ok, remaining} -> @@ -250,6 +257,7 @@ defmodule ChesstrainerWeb.EndgameLive.GuestTrain do |> assign(:guest_remaining, remaining) |> assign(:limit_reached, nil) |> assign(:empty, nil) + |> assign(:served_ids, [endgame.id | socket.assigns.served_ids]) |> PlayCore.init(endgame, page_title: "Train") {:limit_reached, retry_ms} -> diff --git a/lib/chesstrainer_web/live/endgame_live/train.ex b/lib/chesstrainer_web/live/endgame_live/train.ex index f2b2738..e93d204 100644 --- a/lib/chesstrainer_web/live/endgame_live/train.ex +++ b/lib/chesstrainer_web/live/endgame_live/train.ex @@ -106,7 +106,7 @@ defmodule ChesstrainerWeb.EndgameLive.Train do id="pool-exhausted" class="rounded-xl border border-hairline bg-canvas-raised p-6" > -

You've finished every puzzle at this difficulty

+

You've played every puzzle available right now

There are no more {difficulty_label(@session.difficulty)} puzzles right now. Try again, or pick another difficulty. @@ -161,7 +161,7 @@ defmodule ChesstrainerWeb.EndgameLive.Train do

Choose a difficulty

- Difficulty bands are ±{Puzzles.band_width()} around your rating. + Easy draws easier endgames, hard draws harder ones — your rating sets the centre.

<.link @@ -190,7 +190,7 @@ defmodule ChesstrainerWeb.EndgameLive.Train do
- <%= for {difficulty, label, description} <- difficulty_options(@user_rating) do %> + <%= for {difficulty, label, description} <- difficulty_options() do %> <.button id={"difficulty-#{difficulty}"} phx-click="start_session" @@ -315,7 +315,8 @@ defmodule ChesstrainerWeb.EndgameLive.Train do started_at_ms: System.system_time(:millisecond), baseline: socket.assigns.user_rating, count: 0, - sum_ms: 0 + sum_ms: 0, + served_ids: [endgame.id] } socket @@ -333,13 +334,16 @@ defmodule ChesstrainerWeb.EndgameLive.Train do if session do case Puzzles.next_endgame(selection_user(socket), session.difficulty, - exclude_ids: [socket.assigns.endgame.id] + exclude_ids: session.served_ids ) do nil -> assign(socket, :pool, %{difficulty: session.difficulty}) endgame -> + session = %{session | served_ids: [endgame.id | session.served_ids]} + socket + |> assign(:session, session) |> assign(:pool, nil) |> assign(:puzzle_started_mono, System.monotonic_time(:millisecond)) |> assign(:puzzle_counted, false) @@ -395,13 +399,11 @@ defmodule ChesstrainerWeb.EndgameLive.Train do defp parse_difficulty(_value), do: :medium - defp difficulty_options(rating) do - width = Puzzles.band_width() - + defp difficulty_options do [ - {:easy, "Easy", "below #{round(rating - width)}"}, - {:medium, "Medium", "#{round(rating - width)}–#{round(rating + width)}"}, - {:hard, "Hard", "above #{round(rating + width)}"} + {:easy, "Easy", "easier than your rating"}, + {:medium, "Medium", "around your rating"}, + {:hard, "Hard", "harder than your rating"} ] end diff --git a/test/chesstrainer/puzzles_test.exs b/test/chesstrainer/puzzles_test.exs index b60f174..29d5aef 100644 --- a/test/chesstrainer/puzzles_test.exs +++ b/test/chesstrainer/puzzles_test.exs @@ -7,6 +7,7 @@ defmodule Chesstrainer.PuzzlesTest do alias Chesstrainer.Accounts.Scope alias Chesstrainer.Attempts alias Chesstrainer.Puzzles + alias Chesstrainer.Repo # The shared `endgame_fixture/1` picks one of six FENs at random-ish, which # can collide when one test creates several endgames under async load. Pin @@ -22,71 +23,103 @@ defmodule Chesstrainer.PuzzlesTest do endgame_fixture(fen: Enum.fetch!(@fens, index), rating: rating) end - describe "difficulty_range/2" do - test "is centred on the rating and open-ended at the extremes" do - assert Puzzles.difficulty_range(1500, :medium) == {1400, 1600} - assert Puzzles.difficulty_range(1500, :easy) == {nil, 1400} - assert Puzzles.difficulty_range(1500, :hard) == {1600, nil} + defp attempt_days_ago(user, endgame, days) do + {:ok, attempt} = Attempts.record_attempt(Scope.for_user(user), endgame, :solved) + + attempt + |> Ecto.Changeset.change( + inserted_at: DateTime.utc_now() |> DateTime.add(-days, :day) |> DateTime.truncate(:second) + ) + |> Repo.update!() + end + + describe "difficulty_target/2" do + test "centres on the rating and offsets easy and hard" do + assert Puzzles.difficulty_target(1500, :medium) == 1500 + assert Puzzles.difficulty_target(1500, :easy) == 1300 + assert Puzzles.difficulty_target(1500, :hard) == 1700 + end + end + + describe "selection settings" do + test "uses the configured spread and repeat window" do + assert Puzzles.spread() == 150 + assert Puzzles.repeat_window_days() == 30 end end describe "next_endgame/3" do - test "medium picks an endgame within the band" do + test "draws far more often from near the user's rating" do user = user_fixture() - in_band = endgame_at(1550, 0) - _out_of_band = endgame_at(1900, 1) + near = endgame_at(1500, 0) + _far = endgame_at(4000, 1) - assert Puzzles.next_endgame(user, :medium).id == in_band.id + for _ <- 1..50 do + assert Puzzles.next_endgame(user, :medium).id == near.id + end end - test "easy picks an endgame below the user's rating" do + test "easy never serves above the user's rating plus the spread" do user = user_fixture() easy = endgame_at(1300, 0) - _medium = endgame_at(1500, 1) + _too_hard = endgame_at(3000, 1) assert Puzzles.next_endgame(user, :easy).id == easy.id end - test "hard picks an endgame above the user's rating" do + test "hard never serves below the user's rating minus the spread" do user = user_fixture() hard = endgame_at(1700, 0) - _medium = endgame_at(1500, 1) + _too_easy = endgame_at(100, 1) assert Puzzles.next_endgame(user, :hard).id == hard.id end - test "falls back to the nearest endgame when the band is empty" do - user = user_fixture() - only = endgame_at(2200, 0) - - assert Puzzles.next_endgame(user, :medium).id == only.id - end - - test "prefers endgames not attempted in the last 30 days" do + test "prefers endgames not attempted inside the repeat window" do user = user_fixture() attempted = endgame_at(1500, 0) fresh = endgame_at(1500, 1) - {:ok, _} = Attempts.record_attempt(Scope.for_user(user), attempted, :solved) + attempt_days_ago(user, attempted, 1) assert Puzzles.next_endgame(user, :medium).id == fresh.id end - test "falls back to a recent endgame once the fresh pool is empty" do + test "serves an endgame again once its attempt is outside the repeat window" do user = user_fixture() only = endgame_at(1500, 0) - {:ok, _} = Attempts.record_attempt(Scope.for_user(user), only, :solved) + attempt_days_ago(user, only, 31) assert Puzzles.next_endgame(user, :medium).id == only.id end - test "skips excluded ids" do + test "falls back to the least recently attempted endgame when all are excluded" do user = user_fixture() - excluded = endgame_at(1500, 0) + older = endgame_at(1500, 0) + newer = endgame_at(1500, 1) + + attempt_days_ago(user, older, 20) + attempt_days_ago(user, newer, 10) + + assert Puzzles.next_endgame(user, :medium).id == older.id + end + + test "skips endgames already served in the session" do + user = user_fixture() + served = endgame_at(1500, 0) other = endgame_at(1500, 1) - assert Puzzles.next_endgame(user, :medium, exclude_ids: [excluded.id]).id == other.id + assert Puzzles.next_endgame(user, :medium, exclude_ids: [served.id]).id == other.id + end + + test "returns nil when every endgame has been served and attempted" do + user = user_fixture() + only = endgame_at(1500, 0) + + attempt_days_ago(user, only, 1) + + assert Puzzles.next_endgame(user, :medium, exclude_ids: [only.id]) == nil end test "returns nil when no endgames exist" do diff --git a/test/chesstrainer_web/live/endgame_live/train_test.exs b/test/chesstrainer_web/live/endgame_live/train_test.exs index 6e5d887..889f23e 100644 --- a/test/chesstrainer_web/live/endgame_live/train_test.exs +++ b/test/chesstrainer_web/live/endgame_live/train_test.exs @@ -170,6 +170,18 @@ defmodule ChesstrainerWeb.EndgameLive.TrainTest do assert Enum.any?(endgames, &(&1.id == second.id)) end + test "does not serve the same puzzle twice in a session", %{conn: conn} do + {view, [only]} = start_medium_session(conn, 1) + + solve_current(view) + view |> element("#next-puzzle-button") |> render_click() + + assigns = :sys.get_state(view.pid).socket.assigns + assert has_element?(view, "#pool-exhausted") + assert assigns.endgame.id == only.id + assert assigns.session.served_ids == [only.id] + end + test "keeps next puzzle available while reviewing", %{conn: conn} do {view, endgames} = start_medium_session(conn, 2) first = :sys.get_state(view.pid).socket.assigns.endgame