weakness-report 0.1.0__py3-none-any.whl

weakness_report/__init__.py

@@ -0,0 +1,3 @@
+"""Weakness Report -- what your whole game history says you are bad at."""
+
+__version__ = "0.1.0"

weakness_report/aggregate.py

@@ -0,0 +1,256 @@
+"""The arithmetic: your moves, sliced, counted, and compared against yourself.
+
+Every number here is defined to match ChessAnalyzer's, because the point of
+this app is to aggregate that app's reviews rather than to have a second
+opinion about them:
+
+* **ACPL** is the mean centipawn loss over your moves, **excluding book moves**
+  and moves the engine could not score -- exactly as ``_side_summary`` does it.
+  Including opening theory would flatter anyone with preparation and tell them
+  nothing about their play.
+* **Accuracy** is the mean of the arithmetic and harmonic means of your move
+  accuracies in the bucket, which is what ``phase_accuracy`` does. The
+  harmonic half is what stops one brilliant move from hiding three terrible
+  ones. The function itself is imported rather than copied.
+
+The one number this app adds is **excess loss**, and it is the number the
+whole report is built on:
+
+    excess = moves_in_bucket x (bucket ACPL - your overall ACPL)
+
+which is "how many centipawns this kind of position has cost you *beyond what
+you cost yourself anyway*".  Divided by the number of games, it becomes the
+sentence you actually want: *queenless middlegames cost you 0.4 pawns a game
+more than your average*.
+
+That formula is chosen over the two obvious alternatives on purpose. Ranking
+by bucket ACPL alone crowns whichever bucket has eleven moves in it; ranking
+by total centipawns lost crowns the middlegame every time, because that is
+where most of your moves are. Excess loss is the one that answers "what should
+I work on", because it multiplies how bad you are at something by how often it
+happens to you.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+from . import features as feat
+from .bridge import analyzer
+from .buckets import DIMENSIONS
+
+#: A bucket smaller than this is not evidence.  Both have to be met: forty
+#: moves inside one game is one game's worth of noise.
+MIN_MOVES = 40
+MIN_GAMES = 5
+
+
+def _harmonic_mean(values: list) -> float:
+    """ChessAnalyzer's, when it can be found; the same formula when it cannot.
+
+    This is the only place in the app with a fallback, and it is four lines of
+    arithmetic with no judgement in it, so the two cannot drift in any way
+    that matters.
+    """
+    accuracy_module = analyzer("accuracy")
+    if accuracy_module is not None:
+        return accuracy_module.harmonic_mean(values)
+    positive = [max(value, 0.01) for value in values]
+    if not positive:
+        return 0.0
+    return len(positive) / sum(1.0 / value for value in positive)
+
+
+def bucket_accuracy(accuracies: list) -> float | None:
+    """The accuracy of one bucket, by ChessAnalyzer's per-phase definition."""
+    if not accuracies:
+        return None
+    mean = sum(accuracies) / len(accuracies)
+    return round((mean + _harmonic_mean(accuracies)) / 2.0, 1)
+
+
+def move_rows(games: list, reviews: dict) -> list:
+    """Flatten reviews into one list of *your* moves, ready to slice.
+
+    ``games`` are the records, ``reviews`` maps a game id to its review.  A
+    game with no review is skipped silently; the caller counts those.
+    """
+    rows = []
+    for game in games:
+        review = reviews.get(game.get("id"))
+        if not review:
+            continue
+        you = game.get("you")
+        if you not in ("white", "black"):
+            continue
+
+        opening = review.get("opening") or {}
+        context = {
+            "id": game.get("id"),
+            "url": game.get("url", ""),
+            "you": you,
+            "them": game.get("them", ""),
+            "youElo": game.get("youElo", ""),
+            "themElo": game.get("themElo", ""),
+            "speed": game.get("speed", ""),
+            "result": game.get("result", "*"),
+            "date": game.get("date", ""),
+            "opening": opening,
+        }
+        me = you == "white"
+
+        for row in review.get("moves") or []:
+            if row.get("color") != you:
+                continue
+            rows.append({
+                "ply": row.get("ply"),
+                "moveNumber": row.get("moveNumber"),
+                "san": row.get("san", ""),
+                "phase": row.get("phase", ""),
+                "clock": row.get("clock"),
+                "cpLoss": row.get("cpLoss"),
+                "winLoss": row.get("winLoss"),
+                "accuracy": row.get("accuracy"),
+                "label": row.get("label", ""),
+                "judgment": row.get("judgment"),
+                "inBook": bool(row.get("inBook")),
+                "forced": bool(row.get("forced")),
+                "isBest": bool(row.get("isBest")),
+                "bestSan": row.get("bestSan"),
+                "fenBefore": row.get("fenBefore", ""),
+                "features": feat.describe(row.get("fenBefore", ""), me),
+                "game": context,
+            })
+    return rows
+
+
+def _scored(move: dict) -> bool:
+    """Does this move count towards ACPL? ChessAnalyzer's rule, unchanged."""
+    return not move["inBook"] and move.get("cpLoss") is not None
+
+
+class Tally:
+    """One bucket's running totals."""
+
+    __slots__ = ("moves", "scored", "cp", "accuracies", "games", "labels",
+                 "judgments", "best", "forced")
+
+    def __init__(self):
+        self.moves = 0
+        self.scored = 0
+        self.cp = 0
+        self.accuracies = []
+        self.games = set()
+        self.labels = defaultdict(int)
+        self.judgments = defaultdict(int)
+        self.best = 0
+        self.forced = 0
+
+    def add(self, move: dict) -> None:
+        self.moves += 1
+        self.games.add((move.get("game") or {}).get("id"))
+        if move.get("label"):
+            self.labels[move["label"]] += 1
+        if move.get("judgment"):
+            self.judgments[move["judgment"]] += 1
+        if move.get("isBest"):
+            self.best += 1
+        if move.get("forced"):
+            self.forced += 1
+        if move.get("accuracy") is not None:
+            self.accuracies.append(move["accuracy"])
+        if _scored(move):
+            self.scored += 1
+            self.cp += move["cpLoss"]
+
+    @property
+    def acpl(self):
+        return self.cp / self.scored if self.scored else None
+
+    def to_json(self, name: str, *, baseline, total_games: int) -> dict:
+        acpl = self.acpl
+        excess = (self.scored * (acpl - baseline)
+                  if acpl is not None and baseline is not None else None)
+        return {
+            "bucket": name,
+            "moves": self.moves,
+            "scored": self.scored,
+            "games": len(self.games),
+            "acpl": round(acpl, 1) if acpl is not None else None,
+            "accuracy": bucket_accuracy(self.accuracies),
+            "cpLost": self.cp,
+            "pawnsLost": round(self.cp / 100.0, 2),
+            "excessCp": round(excess, 1) if excess is not None else None,
+            "excessPawnsPerGame": (round(excess / total_games / 100.0, 3)
+                                   if excess is not None and total_games else None),
+            "pawnsPerGame": (round(self.cp / total_games / 100.0, 3)
+                             if total_games else None),
+            "bestShare": (round(100.0 * self.best / self.moves, 1)
+                          if self.moves else None),
+            "labels": dict(sorted(self.labels.items(), key=lambda kv: -kv[1])),
+            "judgments": dict(self.judgments),
+        }
+
+
+def overall(moves: list, total_games: int) -> dict:
+    """Your baseline: the numbers every bucket is compared against."""
+    tally = Tally()
+    for move in moves:
+        tally.add(move)
+    data = tally.to_json("overall", baseline=None, total_games=total_games)
+    data["excessCp"] = 0.0
+    data["excessPawnsPerGame"] = 0.0
+    return data
+
+
+def slice_by(moves: list, dimension, *, baseline: float | None,
+             total_games: int) -> list:
+    """Every bucket of one dimension, biggest share of your loss first."""
+    tallies: dict = {}
+    for move in moves:
+        for name in dimension.buckets_of(move):
+            tallies.setdefault(name, Tally()).add(move)
+
+    rows = [tally.to_json(name, baseline=baseline, total_games=total_games)
+            for name, tally in tallies.items()]
+
+    if dimension.order:
+        position = {name: index for index, name in enumerate(dimension.order)}
+        rows.sort(key=lambda row: (position.get(row["bucket"], 99),
+                                   -row["moves"]))
+    else:
+        rows.sort(key=lambda row: -row["moves"])
+    return rows
+
+
+def build(moves: list, *, total_games: int) -> dict:
+    """Every dimension, sliced, with the baseline they are measured against."""
+    base = overall(moves, total_games)
+    baseline = base["acpl"]
+
+    slices = {}
+    for dimension in DIMENSIONS:
+        rows = slice_by(moves, dimension, baseline=baseline,
+                        total_games=total_games)
+        if not rows:
+            continue
+        slices[dimension.key] = {
+            "key": dimension.key,
+            "label": dimension.label,
+            "note": dimension.note,
+            "buckets": rows,
+        }
+
+    return {"overall": base, "baselineAcpl": baseline, "slices": slices}
+
+
+__all__ = [
+    "MIN_GAMES",
+    "MIN_MOVES",
+    "Tally",
+    "bucket_accuracy",
+    "build",
+    "move_rows",
+    "overall",
+    "slice_by",
+]

weakness_report/batch.py

@@ -0,0 +1,303 @@
+"""Reviewing a few hundred games, once.
+
+This is the expensive half of the app and everything here exists to make it
+cost as little as possible and to make the result mean something.
+
+**Reviews are kept per game, not per report.**  Adding fifty games to a
+history of four hundred costs fifty reviews.  Re-running the same report costs
+nothing at all.
+
+**Batches are searched to a fixed depth, and with one thread.**  This is the
+one place where this app deliberately differs from ChessAnalyzer's defaults,
+and the reason is worth stating:
+
+* A **movetime** budget makes every number depend on how busy the machine was.
+  That is tolerable for one game you are reading move by move -- ChessAnalyzer
+  says as much about its own presets -- and it is not tolerable for a figure
+  averaged over four hundred games, because re-running the report next week
+  would move every number in it and you would have no way to tell a real
+  change from a noisy laptop.
+* **Threads > 1** makes Stockfish non-deterministic even at a fixed depth: the
+  search is split across threads and the order they finish in changes the
+  result. One thread is slower and gives the same answer twice.
+
+Together they make a report **reproducible**, which is what lets you run it
+again in three months and believe the difference. Both are settings, so you
+can trade either away for speed.
+
+**Adopting other reviews.**  ChessAnalyzer may already have reviewed some of
+these games. Those are free -- but only comparable if they were searched the
+same way, so by default a review is adopted when its engine settings match
+this batch and re-done when they do not. ``adopt="any"`` takes them regardless
+and the report says the mix out loud; ``adopt="none"`` ignores them.
+"""
+
+from __future__ import annotations
+
+import time
+
+from .bridge import FeatureUnavailable, analyzer, require_analyzer
+
+#: Fixed depths rather than movetimes. See the module docstring.
+PRESETS = {
+    "sweep": {
+        "label": "Sweep",
+        "depth": 10,
+        "multipv": 2,
+        "detail": "Roughly a second a game per 10 moves. Finds blunders and "
+                  "big patterns; too shallow to trust a 5-centipawn gap.",
+    },
+    "standard": {
+        "label": "Standard",
+        "depth": 14,
+        "multipv": 3,
+        "detail": "The sensible default for a few hundred games. Comparable "
+                  "to ChessAnalyzer's Standard preset in strength.",
+    },
+    "deep": {
+        "label": "Deep",
+        "depth": 18,
+        "multipv": 3,
+        "detail": "Several times slower. Worth it for a history you intend to "
+                  "keep and compare against later.",
+    },
+}
+
+DEFAULT_PRESET = "standard"
+
+#: One thread by default, for reproducibility rather than speed.
+DEFAULT_THREADS = 1
+DEFAULT_HASH_MB = 256
+
+ADOPT_MODES = ("matching", "any", "none")
+
+
+class BatchError(RuntimeError):
+    """A batch could not run, with a message worth showing."""
+
+
+def settings_for(preset: str = DEFAULT_PRESET, *, engine_id=None,
+                 threads: int = DEFAULT_THREADS, hash_mb: int = DEFAULT_HASH_MB):
+    """A ChessAnalyzer ``Settings`` pinned to a depth. Raises without the app."""
+    review = require_analyzer("review", "Reviewing games")
+    chosen = PRESETS.get(preset) or PRESETS[DEFAULT_PRESET]
+    return review.Settings(
+        engine_id=engine_id,
+        preset=preset if preset in PRESETS else DEFAULT_PRESET,
+        movetime=0.0,                 # unused: depth wins in EngineOptions
+        depth=chosen["depth"],
+        multipv=chosen["multipv"],
+        threads=max(1, int(threads)),
+        hash_mb=max(16, int(hash_mb)),
+    )
+
+
+def signature(settings) -> str:
+    """How a review made with these settings will identify itself."""
+    return settings.options().key()
+
+
+def review_signature(review: dict) -> str:
+    """The settings key a saved review was made with, or ``""``."""
+    key = ((review or {}).get("engine") or {}).get("settingsKey") or ""
+    # "Stockfish 18|t1_h256_pv3_d14" -- the half after the bar is the options.
+    return key.split("|", 1)[1] if "|" in key else key
+
+
+def acceptable(existing: dict | None, wanted: str, adopt: str) -> bool:
+    """Can this saved review stand in for one made with the current settings?
+
+    Only if it was searched the same way. Getting this wrong is exactly the
+    quiet failure this app is built to avoid: a report mixing depth-10 and
+    depth-18 numbers looks no different from one that does not, and every
+    figure in it is wrong. So changing the preset re-reviews -- and because
+    the position cache is keyed by settings too, the second preset is the
+    only thing actually paid for.
+
+    ``adopt="any"`` turns the check off for anyone who would rather have the
+    speed. The report then says out loud that its settings were mixed.
+    """
+    if existing is None:
+        return False
+    if adopt == "any":
+        return True
+    return review_signature(existing) == wanted
+
+
+def outstanding(store, games: list, *, preset: str = DEFAULT_PRESET,
+                threads: int = DEFAULT_THREADS,
+                hash_mb: int = DEFAULT_HASH_MB, adopt: str = "matching") -> dict:
+    """How many of these games actually need the engine at these settings."""
+    try:
+        wanted = signature(settings_for(preset, threads=threads, hash_mb=hash_mb))
+    except FeatureUnavailable:
+        wanted = ""
+    ready = sum(1 for game in games
+                if acceptable(store.load_review(game.get("id")), wanted, adopt))
+    return {"total": len(games), "ready": ready,
+            "outstanding": len(games) - ready, "signature": wanted}
+
+
+def _record_for(game: dict):
+    """A ChessAnalyzer record for one of our games, keeping our own id."""
+    sources = require_analyzer("sources", "Reviewing games")
+    return sources.record_from_pgn(
+        game["pgn"], source=game.get("source", "pgn"),
+        game_id=game["id"], url=game.get("url", ""))
+
+
+def eval_cache(store):
+    """The position cache, ours rather than ChessAnalyzer's.
+
+    Sharing that app's cache file would be a write into another app's folder,
+    which this repository's apps do not do to each other. The cost is that the
+    first batch cannot reuse positions ChessAnalyzer has already seen; the
+    benefit is that neither app can corrupt the other's data.
+    """
+    library = analyzer("library")
+    if library is None:
+        return None
+    path = store.cache_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return library.EvalCache(path)
+
+
+def run(store, games: list, *, preset: str = DEFAULT_PRESET, engine_id=None,
+        threads: int = DEFAULT_THREADS, hash_mb: int = DEFAULT_HASH_MB,
+        adopt: str = "matching", progress=None, should_stop=None) -> dict:
+    """Make sure every game has a review. Returns what it had to do.
+
+    ``progress(done, total, message)`` is called per game, and ``should_stop``
+    is checked between games and inside each one, so a cancelled batch keeps
+    every review it has already finished.
+    """
+    if adopt not in ADOPT_MODES:
+        raise BatchError(f"adopt must be one of: {', '.join(ADOPT_MODES)}")
+
+    review_module = require_analyzer("review", "Reviewing games")
+    engines = require_analyzer("engines", "Reviewing games")
+
+    settings = settings_for(preset, engine_id=engine_id, threads=threads,
+                            hash_mb=hash_mb)
+    wanted = signature(settings)
+    cache = eval_cache(store)
+
+    counts = {"total": len(games), "already": 0, "adopted": 0, "reviewed": 0,
+              "failed": 0, "skipped": 0}
+    signatures: dict = {}
+    failures: list = []
+    started = time.time()
+
+    try:
+        for index, game in enumerate(games):
+            if should_stop and should_stop():
+                counts["skipped"] = len(games) - index
+                break
+
+            game_id = game.get("id")
+            if progress:
+                progress(index, len(games),
+                         f"{game.get('white', '?')} vs {game.get('black', '?')}")
+
+            existing = store.load_review(game_id)
+            if acceptable(existing, wanted, adopt):
+                counts["already"] += 1
+                found = review_signature(existing)
+                signatures[found] = signatures.get(found, 0) + 1
+                continue
+
+            offered = game.get("existingReview")
+            if offered and adopt != "none" and acceptable(offered, wanted, adopt):
+                store.save_review(game_id, offered)
+                counts["adopted"] += 1
+                found = review_signature(offered)
+                signatures[found] = signatures.get(found, 0) + 1
+                continue
+
+            try:
+                result = review_module.review(
+                    _record_for(game), settings, cache=cache,
+                    should_stop=should_stop)
+            except review_module.ReviewCancelled:
+                counts["skipped"] = len(games) - index
+                break
+            except Exception as exc:                          # noqa: BLE001
+                # One unreviewable game must not lose the batch. Record it and
+                # carry on; the report counts what it actually has.
+                counts["failed"] += 1
+                failures.append({"id": game_id, "reason": str(exc)[:200]})
+                continue
+
+            store.save_review(game_id, result)
+            counts["reviewed"] += 1
+            signatures[wanted] = signatures.get(wanted, 0) + 1
+
+        if cache is not None:
+            cache.save()
+    finally:
+        # python-chess runs each engine on a non-daemon thread, and CPython
+        # joins those before atexit runs -- so a process that leaves one open
+        # prints its last line and then hangs for ever with no traceback.
+        # Every entry point must do this. See ChessAnalyzer's README.
+        try:
+            engines.close()
+        except Exception:                                     # noqa: BLE001
+            pass
+
+    return {
+        "counts": counts,
+        "settings": settings.json(),
+        "signature": wanted,
+        "signatures": signatures,
+        "uniform": len(signatures) <= 1,
+        "failures": failures[:20],
+        "elapsed": round(time.time() - started, 1),
+    }
+
+
+def load_reviews(store, games: list) -> dict:
+    """``{game id: review}`` for every game that has one on disk."""
+    out = {}
+    for game in games:
+        review = store.load_review(game.get("id"))
+        if review is not None:
+            out[game["id"]] = review
+    return out
+
+
+def estimate(games: list, preset: str = DEFAULT_PRESET, *,
+             already: int = 0) -> dict:
+    """A rough time for a batch, so the button can say what it will cost.
+
+    Deliberately crude and labelled as such: engine speed varies by an order
+    of magnitude across machines, and a number with a plus-or-minus on it is
+    more honest than a spinner with no number at all.
+    """
+    chosen = PRESETS.get(preset) or PRESETS[DEFAULT_PRESET]
+    seconds_each = {10: 3.0, 14: 12.0, 18: 60.0}.get(chosen["depth"], 12.0)
+    outstanding = max(0, len(games) - already)
+    return {
+        "games": len(games),
+        "outstanding": outstanding,
+        "secondsPerGame": seconds_each,
+        "seconds": int(outstanding * seconds_each),
+        "rough": True,
+    }
+
+
+__all__ = [
+    "ADOPT_MODES",
+    "acceptable",
+    "DEFAULT_PRESET",
+    "PRESETS",
+    "BatchError",
+    "FeatureUnavailable",
+    "estimate",
+    "eval_cache",
+    "load_reviews",
+    "outstanding",
+    "review_signature",
+    "run",
+    "settings_for",
+    "signature",
+]

weakness_report/board.py

@@ -0,0 +1,78 @@
+"""Board diagrams for the browser, drawn server-side as SVG.
+
+A worst moment is only understandable as a picture, and this app shows a dozen
+of them.  python-chess draws the board itself, so this needs nothing beyond
+the core dependency.
+
+Unlike the sibling apps there is nothing to play here: a weakness report is a
+document about games already finished, so the board is a diagram and stays
+one.  The palette matches the rest of the repository so a position looks the
+same on screen as it does in the printed report.
+"""
+
+from __future__ import annotations
+
+import chess
+import chess.svg
+
+BOARD_COLORS = {
+    "square light": "#f0d9b5",
+    "square dark": "#b58863",
+    "square light lastmove": "#cdd26a",
+    "square dark lastmove": "#aaa23a",
+    "margin": "#f7f2e8",
+    "coord": "#5c4a33",
+    "arrow green": "#15781baa",
+    "arrow red": "#882020aa",
+    "arrow yellow": "#e68f00aa",
+    "arrow blue": "#003088aa",
+}
+
+
+def _arrow(uci: str, colour: str):
+    if not uci or len(uci) < 4:
+        return None
+    try:
+        move = chess.Move.from_uci(uci[:5])
+    except ValueError:
+        return None
+    return chess.svg.Arrow(move.from_square, move.to_square, color=colour)
+
+
+def board_svg(fen: str, *, size: int = 320, flipped: bool = False,
+              arrows: str = "", coordinates: bool = True) -> str:
+    """One position.
+
+    ``arrows`` is the compact query form ``red:e2e4,green:g1f3``. Throughout
+    this app **red is the move you played** and **green is the move the engine
+    wanted**, which is the only pair of colours a reader needs to learn.
+    """
+    board = chess.Board(fen)
+
+    shapes = []
+    for item in filter(None, (arrows or "").split(",")):
+        colour, _, uci = item.partition(":")
+        arrow = _arrow(uci, colour or "green")
+        if arrow is not None:
+            shapes.append(arrow)
+
+    return chess.svg.board(
+        board, size=size,
+        orientation=chess.BLACK if flipped else chess.WHITE,
+        arrows=shapes, coordinates=coordinates,
+        check=board.king(board.turn) if board.is_check() else None,
+        colors=BOARD_COLORS)
+
+
+def uci_of(fen: str, san: str) -> str:
+    """The UCI for a SAN move in a position, or ``""``. Used to draw arrows."""
+    if not san:
+        return ""
+    try:
+        board = chess.Board(fen)
+        return board.parse_san(san).uci()
+    except (ValueError, AssertionError):
+        return ""
+
+
+__all__ = ["BOARD_COLORS", "board_svg", "uci_of"]