Upload analyzer (13).py

analyzer (13).py

@@ -0,0 +1,689 @@
+"""
+Chess game analyzer using Stockfish + Expected Points model.
+
+Classification hierarchy (highest priority first):
+  Book → Brilliant → Great → Miss → Best → Excellent → Good → Inaccuracy → Mistake → Blunder
+"""
+
+import chess
+import chess.pgn
+import chess.engine
+import io
+import math
+import json
+import random
+import shutil
+import os
+
+def _find_stockfish() -> str:
+    """Locate stockfish binary on common paths."""
+    # Try PATH first
+    found = shutil.which("stockfish")
+    if found:
+        return found
+    for path in [
+        "/usr/games/stockfish",
+        "/usr/bin/stockfish",
+        "/usr/local/bin/stockfish",
+        "/opt/homebrew/bin/stockfish",
+        "/opt/homebrew/games/stockfish",
+    ]:
+        if os.path.isfile(path) and os.access(path, os.X_OK):
+            return path
+    return "stockfish"   # Let it fail with a clear error
+
+
+# ── ECO opening book ───────────────────────────────────────────────────────────
+
+def _load_eco_db() -> dict:
+    """
+    Load ECO JSON files (ecoA-D.json) from an eco/ folder next to this file.
+    Keys are FEN strings; values contain name, eco code, and moves.
+    Returns an empty dict gracefully if the folder or files are missing.
+    """
+    db: dict = {}
+    eco_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "eco")
+    if not os.path.isdir(eco_dir):
+        return db
+    for letter in "ABCD":
+        path = os.path.join(eco_dir, f"eco{letter}.json")
+        if not os.path.isfile(path):
+            continue
+        try:
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+            db.update(data)
+        except Exception:
+            pass
+    return db
+
+ECO_DB: dict = _load_eco_db()
+
+def lookup_book(fen_after: str) -> dict | None:
+    """Return opening entry if position is in ECO db, else None."""
+    return ECO_DB.get(fen_after)
+
+# ── Expected Points ────────────────────────────────────────────────────────────
+
+def cp_to_ep(cp: float, k: float = 0.4) -> float:
+    """Convert centipawn score to Expected Points from White's perspective."""
+    return 1.0 / (1.0 + math.exp(-k * (cp / 100.0)))
+
+def score_to_ep_white(score: chess.engine.Score) -> float:
+    """Convert a PovScore (already in White's POV) to EP."""
+    if score.is_mate():
+        m = score.mate()
+        return 1.0 if (m is not None and m > 0) else 0.0
+    cp = score.score()
+    return cp_to_ep(cp if cp is not None else 0)
+
+def get_ep_white(info: dict) -> float:
+    return score_to_ep_white(info["score"].white())
+
+# ── Sacrifice detection ────────────────────────────────────────────────────────
+
+PIECE_VALUES = {
+    chess.PAWN: 1, chess.KNIGHT: 3, chess.BISHOP: 3,
+    chess.ROOK: 5, chess.QUEEN: 9, chess.KING: 99
+}
+
+def _see(board: chess.Board, square: int, attacker: chess.Color, target_val: int) -> int:
+    """
+    Recursive Static Exchange Evaluation.
+    Returns the net material gain for `attacker` if they initiate a capture
+    sequence on `square`, where `target_val` is the value of the piece there.
+    Positive = attacker profits, 0 = even trade, negative = attacker loses.
+    """
+    attackers = board.attackers(attacker, square)
+    if not attackers:
+        return 0
+
+    # Always capture with the least valuable piece first
+    best_sq = min(
+        (sq for sq in attackers if board.piece_at(sq)),
+        key=lambda sq: PIECE_VALUES.get(board.piece_at(sq).piece_type, 99),
+        default=None,
+    )
+    if best_sq is None:
+        return 0
+
+    capturing_piece = board.piece_at(best_sq)
+    capturing_val   = PIECE_VALUES.get(capturing_piece.piece_type, 0)
+
+    # Simulate the capture by manually updating a board copy
+    b2 = board.copy()
+    b2.remove_piece_at(best_sq)
+    b2.set_piece_at(square, chess.Piece(capturing_piece.piece_type, attacker))
+
+    # The other side may now recapture — they'll only do so if it's profitable
+    recapture_gain = _see(b2, square, not attacker, capturing_val)
+
+    # Our gain: captured target_val, but may lose capturing_val if opponent recaptures
+    return target_val - max(0, recapture_gain)
+
+
+def _is_hanging(board: chess.Board, square: int, our_color: chess.Color) -> bool:
+    """
+    Returns True if the piece on `square` is en prise for the opponent —
+    i.e. the opponent comes out ahead if they capture it (SEE > 0).
+    """
+    piece = board.piece_at(square)
+    if piece is None or piece.color != our_color:
+        return False
+    piece_val = PIECE_VALUES.get(piece.piece_type, 0)
+    if piece_val < 3:
+        return False  # Ignore pawns and kings
+    opponent = not our_color
+    return _see(board, square, opponent, piece_val) > 0
+
+
+def check_sacrifice(board: chess.Board, move: chess.Move) -> bool:
+    """
+    Returns True if this move involves a genuine piece sacrifice — either:
+    (a) The moved piece itself lands en prise (SEE favours the opponent), OR
+    (b) A friendly piece is newly left hanging after the move — e.g. a queen
+        that was shielded by the moving piece (pin scenario) is now exposed.
+
+    A knight defended by a pawn attacked by a bishop is NOT a sacrifice:
+    Bxn, pxB = even trade → SEE = 0 → not flagged.
+    """
+    our_color = board.turn
+    piece     = board.piece_at(move.from_square)
+    if piece is None:
+        return False
+
+    piece_val = PIECE_VALUES.get(piece.piece_type, 0)
+
+    # ── (a) Moved-piece sacrifice ──────────────────────────────────────────
+    if piece_val >= 3:
+        # What we already captured by making this move (0 if not a capture)
+        captured = board.piece_at(move.to_square)
+        captured_val = PIECE_VALUES.get(captured.piece_type, 0) if captured else 0
+
+        board_after = board.copy()
+        board_after.push(move)
+        opponent = board_after.turn
+
+        # The opponent's net gain = what they take from us minus what we already took.
+        # e.g. Qxd8 Rxd8: opponent SEE=9, but we already took 9 → net gain=0 → not a sac.
+        # e.g. Bh6 gxh6:  opponent SEE=3, we took nothing   → net gain=3 → is a sac.
+        net_gain_for_opponent = _see(board_after, move.to_square, opponent, piece_val) - captured_val
+        if net_gain_for_opponent > 0:
+            return True
+
+    # ── (b) Piece-left-behind sacrifice (e.g. walking out of a pin) ───────
+    # Collect which friendly pieces were already hanging BEFORE the move,
+    # so we only flag pieces that are *newly* exposed.
+    hanging_before: set[int] = set()
+    for sq in board.pieces(chess.QUEEN,  our_color) | \
+               board.pieces(chess.ROOK,   our_color) | \
+               board.pieces(chess.BISHOP, our_color) | \
+               board.pieces(chess.KNIGHT, our_color):
+        if sq == move.from_square:
+            continue  # This is the piece we're moving — skip
+        if _is_hanging(board, sq, our_color):
+            hanging_before.add(sq)
+
+    board_after = board.copy()
+    board_after.push(move)
+
+    for sq in board_after.pieces(chess.QUEEN,  our_color) | \
+               board_after.pieces(chess.ROOK,   our_color) | \
+               board_after.pieces(chess.BISHOP, our_color) | \
+               board_after.pieces(chess.KNIGHT, our_color):
+        if sq == move.to_square:
+            continue  # Already handled in (a)
+        if sq not in hanging_before and _is_hanging(board_after, sq, our_color):
+            return True  # This piece is newly hanging — it's the real sacrifice
+
+    # ── (c) Deliberately ignored threat ────────────────────────────────────
+    # Our piece was already hanging before this move (opponent attacked it last
+    # turn), and our move neither moved it nor added a defender — we intentionally
+    # left it en prise to play something more important elsewhere.
+    # _is_hanging uses SEE so a piece that is now defended returns False.
+    opponent = board_after.turn
+    for sq in hanging_before:
+        if _is_hanging(board_after, sq, our_color):
+            return True  # Still hanging after our move — deliberate sacrifice
+
+    return False
+
+# ── Move classification ────────────────────────────────────────────────────────
+
+COMMENTS = {
+    "Book": [
+        "A well-known opening move.",
+        "Theory — this position has been played thousands of times.",
+        "A mainline opening move.",
+    ],
+    "Brilliant": [
+        "A stunning sacrifice that seizes a lasting advantage.",
+        "Extraordinary piece sacrifice — the position rewards bold play.",
+        "An unexpected sacrifice with deep positional compensation.",
+    ],
+    "Great": [
+        "A critical move that shifts the balance of the game.",
+        "Finding this move takes real precision — it dramatically improves the position.",
+        "The only move that keeps things in hand. Well found.",
+    ],
+    "Miss": [
+        "A missed opportunity — the opponent's error went unpunished.",
+        "After the opponent's mistake, this fails to press the advantage.",
+        "The position offered a winning shot, but it slipped away here.",
+    ],
+    "Best": [
+        "The engine's top choice. Precise and principled.",
+        "Perfect play — the ideal move in this position.",
+        "Exactly what the position demanded.",
+    ],
+    "Excellent": [
+        "A very strong move that keeps the position under control.",
+        "Nearly best — a fine practical choice.",
+        "A sharp, high-quality response.",
+    ],
+    "Good": [
+        "A solid move that maintains the balance.",
+        "Reasonable play — the position stays roughly equal.",
+        "A sensible continuation with no serious drawbacks.",
+    ],
+    "Inaccuracy": [
+        "A slight imprecision — a better option was available.",
+        "Not a serious error, but leaves something on the table.",
+        "The position allowed for more here.",
+    ],
+    "Mistake": [
+        "An error that hands the opponent a meaningful advantage.",
+        "This weakens the position more than it needed to.",
+        "A significant misstep — the opponent can now press hard.",
+    ],
+    "Blunder": [
+        "A serious blunder that could cost the game.",
+        "A major error — this dramatically changes the evaluation.",
+        "Devastating. The position collapses after this move.",
+    ],
+}
+
+def _net_exchange(board: 'chess.Board', move: chess.Move, our_color: chess.Color) -> int:
+    """
+    Net material result of this move for our_color, accounting for the full
+    exchange sequence via SEE.  Unlike a raw board snapshot, this correctly
+    handles trades and recaptures.
+
+    Returns:
+      positive  — we come out ahead in material (e.g. win-back tactical combo)
+      zero      — even exchange (true trade)
+      negative  — we lose material net (positional / speculative sacrifice)
+
+    Brilliant gate uses this to distinguish:
+      gain <= 0   → real sacrifice for compensation   → Brilliant candidate
+      1 <= gain <= 2 → "cheap" win of a pawn or two   → downgrade to Great
+      gain >= 3   → significant material-winning combo → Brilliant candidate
+    """
+    piece = board.piece_at(move.from_square)
+    if piece is None:
+        return 0
+    piece_val = PIECE_VALUES.get(piece.piece_type, 0)
+
+    # What we capture immediately, if anything
+    captured     = board.piece_at(move.to_square)
+    captured_val = PIECE_VALUES.get(captured.piece_type, 0) if captured else 0
+
+    board_after = board.copy()
+    board_after.push(move)
+    opponent = not our_color
+
+    # How much does opponent gain by recapturing our piece on to_square?
+    opp_gain_dest = max(0, _see(board_after, move.to_square, opponent, piece_val))
+
+    # Net from the primary exchange on the destination square
+    dest_net = captured_val - opp_gain_dest
+
+    # Also account for any piece newly left hanging (path-b sacrifice —
+    # e.g. walking a knight out of a pin, exposing the queen).
+    # We already know check_sacrifice flagged this, so find the newly hanging
+    # piece and subtract its SEE loss.
+    hanging_before: set = set()
+    for sq in (board.pieces(chess.QUEEN,  our_color) |
+               board.pieces(chess.ROOK,   our_color) |
+               board.pieces(chess.BISHOP, our_color) |
+               board.pieces(chess.KNIGHT, our_color)):
+        if sq == move.from_square:
+            continue
+        if _is_hanging(board, sq, our_color):
+            hanging_before.add(sq)
+
+    newly_hanging_loss = 0
+    for sq in (board_after.pieces(chess.QUEEN,  our_color) |
+               board_after.pieces(chess.ROOK,   our_color) |
+               board_after.pieces(chess.BISHOP, our_color) |
+               board_after.pieces(chess.KNIGHT, our_color)):
+        if sq == move.to_square:
+            continue
+        if sq not in hanging_before and _is_hanging(board_after, sq, our_color):
+            p  = board_after.piece_at(sq)
+            pv = PIECE_VALUES.get(p.piece_type, 0)
+            newly_hanging_loss += max(0, _see(board_after, sq, opponent, pv))
+
+    return dest_net - newly_hanging_loss
+
+
+def get_comment(classification: str) -> str:
+    return random.choice(COMMENTS.get(classification, ["—"]))
+
+def classify_move(
+    player_ep_before: float,
+    player_ep_after: float,
+    player_ep_second_best: float | None,
+    is_best: bool,
+    move_rank: int | None,
+    is_sacrifice: bool,
+    opponent_blunder_swing: float | None,
+    ep_before_opponent_blunder: float | None,
+    board_before: 'chess.Board | None' = None,
+    board_after:  'chess.Board | None' = None,
+    our_color:    'chess.Color | None' = None,
+    move:         'chess.Move | None'  = None,
+) -> str:
+    ep_loss = player_ep_before - player_ep_after
+
+    # ── Brilliant ──────────────────────────────────────────────────────────────
+    # Best move + piece sacrifice + lands in a good position + significant material swing.
+    # Two paths to Brilliant:
+    #   1. Normal: wasn't already near-completely-winning (< 0.97).
+    #   2. Was already winning but the sacrifice dramatically improves the position
+    #      (ep jump >= 0.15) -- e.g. forcing bishop sac into a mating attack.
+    # Downgrade to Great if the material net gain is <= 2 pawns: a tiny material
+    # pickup doesn't justify Brilliant even if every other condition is met.
+    if is_best and is_sacrifice:
+        ep_jump         = player_ep_after - player_ep_before
+        already_winning = player_ep_before >= 0.97
+        lands_well      = player_ep_after >= 0.45  # equal or better after sac is fine
+        if lands_well and (not already_winning or ep_jump >= 0.15):
+            # Material gate:
+            #   net <  0  → real material sacrifice (gives up more than gains) → Brilliant
+            #   net 0..2  → equal trade or trivial pickup (e.g. queen swap, +1 pawn) → Great
+            #   net >= 3  → significant material-winning combination → Brilliant
+            # Trades (net=0) and small wins are explicitly excluded from Brilliant.
+            if board_before is not None and our_color is not None and move is not None:
+                net = _net_exchange(board_before, move, our_color)
+                if 0 <= net <= 2:
+                    return "Great"
+            return "Brilliant"
+
+    # ── Great ──────────────────────────────────────────────────────────────────
+    if is_best:
+        was_losing  = player_ep_before < 0.45
+        is_equal    = 0.44 <= player_ep_after <= 0.62
+        is_winning  = player_ep_after > 0.55
+        major_swing = was_losing and (is_equal or is_winning)
+
+        only_good   = (
+            player_ep_second_best is not None
+            and player_ep_before - player_ep_second_best > 0.15
+        )
+
+        if major_swing or only_good:
+            return "Great"
+
+    # ── Miss ───────────────────────────────────────────────────────────────────
+    if (
+        opponent_blunder_swing is not None
+        and opponent_blunder_swing > 0.10
+        and ep_before_opponent_blunder is not None
+        and player_ep_after <= ep_before_opponent_blunder + 0.02
+    ):
+        return "Miss"
+
+    # ── EP table ───────────────────────────────────────────────────────────────
+    ep_loss = max(0.0, ep_loss)   # cap negatives (position improved beyond eval)
+
+    # is_best is checked first — float rounding can produce a tiny non-zero
+    # ep_loss even for the engine's top move, so we must not let the threshold
+    # bands override a confirmed best-move result.
+    if is_best:
+        return "Best"
+    if ep_loss <= 0.02:
+        return "Excellent"
+    if ep_loss <= 0.05:
+        return "Good"
+    if ep_loss <= 0.10:
+        return "Inaccuracy"
+    if ep_loss <= 0.20:
+        return "Mistake"
+    return "Blunder"
+
+# ── Continuation formatting ────────────────────────────────────────────────────
+
+def format_continuation(moves_san: list[str], move_number: int, player_color: str) -> str:
+    """Format a list of SAN continuation moves with proper move numbers.
+
+    After white plays move N  → continuation starts with black at N, then white at N+1
+    After black plays move N  → continuation starts with white at N+1
+    """
+    if not moves_san:
+        return ""
+
+    parts: list[str] = []
+
+    if player_color == "white":
+        # Next is black's response at the same move number
+        next_is_white = False
+        num = move_number
+    else:
+        # Next is white's move, which is move_number + 1
+        next_is_white = True
+        num = move_number + 1
+
+    for i, san in enumerate(moves_san):
+        if next_is_white:
+            parts.append(f"{num}.")
+            parts.append(san)
+            next_is_white = False
+        else:
+            if i == 0:
+                # First black continuation move: needs the "N..." prefix
+                parts.append(f"{num}...")
+            parts.append(san)
+            next_is_white = True
+            num += 1   # After black plays, white's next turn is N+1
+
+    return " ".join(parts)
+
+# ── Main analysis entry point ──────────────────────────────────────────────────
+
+def analyze_game(pgn_text: str, depth: int, progress_cb):
+    """
+    Analyze a full PGN game.  Calls progress_cb({type, message, progress, [data]}).
+    """
+    pgn_io = io.StringIO(pgn_text)
+    game = chess.pgn.read_game(pgn_io)
+
+    if game is None:
+        progress_cb({"type": "error", "message": "Could not parse PGN. Please check the notation."})
+        return
+
+    white = game.headers.get("White", "White")
+    black = game.headers.get("Black", "Black")
+
+    moves_list = list(game.mainline_moves())
+    total = len(moves_list)
+
+    if total == 0:
+        progress_cb({"type": "error", "message": "The PGN contains no moves."})
+        return
+
+    progress_cb({"type": "progress", "message": "Initializing Stockfish engine…", "progress": 0.0})
+
+    sf_path = _find_stockfish()
+    try:
+        engine = chess.engine.SimpleEngine.popen_uci(sf_path)
+    except FileNotFoundError:
+        progress_cb({"type": "error",
+                     "message": f"Stockfish not found (tried '{sf_path}'). Install Stockfish and ensure it is on your PATH."})
+        return
+
+    try:
+        # Build board snapshots: boards[i] is the state BEFORE move i
+        boards: list[chess.Board] = []
+        b = game.board()
+        for mv in moves_list:
+            boards.append(b.copy())
+            b.push(mv)
+        boards.append(b.copy())   # final position after all moves
+
+        # Analyse every position with MultiPV=5
+        multipv: list[list[dict]] = []
+        ep_white: list[float] = []
+
+        for i, board_snap in enumerate(boards):
+            if i < total:
+                msg = f"Analyzing move {i + 1} of {total}…"
+                prog = i / total * 0.90
+            else:
+                msg = "Finalizing analysis…"
+                prog = 0.93
+
+            progress_cb({"type": "progress", "message": msg, "progress": prog})
+
+            infos = engine.analyse(board_snap, chess.engine.Limit(depth=depth), multipv=5)
+            multipv.append(infos)
+            ep_white.append(get_ep_white(infos[0]))
+
+        # Classify each move
+        progress_cb({"type": "progress", "message": "Classifying moves…", "progress": 0.96})
+
+        results = []
+
+        for i, move in enumerate(moves_list):
+            board_snap = boards[i]
+            turn = board_snap.turn
+            color = "white" if turn == chess.WHITE else "black"
+
+            move_san = board_snap.san(move)
+            move_uci = move.uci()
+            fen_before = board_snap.fen()
+            fen_after  = boards[i + 1].fen()
+
+            ep_w_before = ep_white[i]
+            ep_w_after  = ep_white[i + 1]
+
+            if turn == chess.WHITE:
+                player_ep_before = ep_w_before
+                player_ep_after  = ep_w_after
+            else:
+                player_ep_before = 1.0 - ep_w_before
+                player_ep_after  = 1.0 - ep_w_after
+
+            # Best move
+            best_move_obj = multipv[i][0]["pv"][0]
+            best_move_san = board_snap.san(best_move_obj)
+            best_move_uci = best_move_obj.uci()
+            is_best = (move.uci() == best_move_uci)
+
+            # Second-best EP (for "only good move" detection)
+            player_ep_second_best: float | None = None
+            if len(multipv[i]) > 1:
+                ep_sb_w = get_ep_white(multipv[i][1])
+                player_ep_second_best = ep_sb_w if turn == chess.WHITE else 1.0 - ep_sb_w
+
+            # Rank among top-5
+            move_rank: int | None = None
+            for rank, info in enumerate(multipv[i], 1):
+                if info["pv"][0].uci() == move.uci():
+                    move_rank = rank
+                    break
+
+            # Sacrifice?
+            is_sacrifice = check_sacrifice(board_snap, move)
+
+            # Miss detection
+            opponent_blunder_swing: float | None = None
+            ep_before_opponent_blunder: float | None = None
+
+            if i >= 1:
+                ep_w_prev = ep_white[i - 1]
+                if turn == chess.WHITE:
+                    swing = ep_w_before - ep_w_prev
+                    pre_blunder = ep_w_prev
+                else:
+                    swing = (1.0 - ep_w_before) - (1.0 - ep_w_prev)
+                    pre_blunder = 1.0 - ep_w_prev
+
+                if swing > 0.10:
+                    opponent_blunder_swing = swing
+                    ep_before_opponent_blunder = pre_blunder
+
+            # Book move check — if the resulting position is in the ECO db,
+            # classify immediately regardless of EP; opening theory trumps evaluation.
+            book_entry = lookup_book(fen_after)
+            if book_entry:
+                classification = "Book"
+                opening_name   = book_entry.get("name", "")
+                opening_eco    = book_entry.get("eco", "")
+            else:
+                opening_name = ""
+                opening_eco  = ""
+                classification = classify_move(
+                    player_ep_before=player_ep_before,
+                    player_ep_after=player_ep_after,
+                    player_ep_second_best=player_ep_second_best,
+                    is_best=is_best,
+                    move_rank=move_rank,
+                    is_sacrifice=is_sacrifice,
+                    opponent_blunder_swing=opponent_blunder_swing,
+                    ep_before_opponent_blunder=ep_before_opponent_blunder,
+                    board_before=board_snap,
+                    board_after=boards[i + 1],
+                    our_color=turn,
+                    move=move,
+                )
+
+            # Continuation: engine's best line from the position after this move
+            continuation_san: list[str] = []
+            if multipv[i + 1] and "pv" in multipv[i + 1][0]:
+                temp = boards[i + 1].copy()
+                for cont_mv in multipv[i + 1][0]["pv"][:6]:
+                    try:
+                        continuation_san.append(temp.san(cont_mv))
+                        temp.push(cont_mv)
+                    except Exception:
+                        break
+
+            ep_loss = max(0.0, player_ep_before - player_ep_after)
+
+            results.append({
+                "move_number":    (i // 2) + 1,
+                "ply":            i,
+                "color":          color,
+                "san":            move_san,
+                "uci":            move_uci,
+                "from_square":    chess.square_name(move.from_square),
+                "to_square":      chess.square_name(move.to_square),
+                "classification": classification,
+                "ep_loss":        round(ep_loss, 4),
+                "ep_before":      round(player_ep_before, 4),
+                "ep_after":       round(player_ep_after, 4),
+                "best_move_san":  best_move_san if not is_best else None,
+                "best_move_uci":  best_move_uci if not is_best else None,
+                "continuation":   continuation_san,
+                "continuation_fmt": format_continuation(continuation_san,
+                                                         (i // 2) + 1, color),
+                "fen_before":     fen_before,
+                "fen_after":      fen_after,
+                "is_best":        is_best,
+                "comment":        get_comment(classification),
+                "opening_name":   opening_name,
+                "opening_eco":    opening_eco,
+            })
+
+        progress_cb({
+            "type": "complete",
+            "message": "Analysis complete!",
+            "progress": 1.0,
+            "data": {
+                "white":       white,
+                "black":       black,
+                "initial_fen": game.board().fen(),
+                "moves":       results,
+                "summary":     _compute_summary(results),
+            }
+        })
+
+    finally:
+        engine.quit()
+
+
+# ── Summary stats ──────────────────────────────────────────────────────────────
+
+ALL_CLASSIFICATIONS = [
+    "Book", "Brilliant", "Great", "Best", "Excellent", "Good",
+    "Inaccuracy", "Mistake", "Blunder", "Miss",
+]
+
+def _compute_summary(moves: list[dict]) -> dict:
+    """Return per-player classification counts and accuracy."""
+    stats = {}
+    for color in ("white", "black"):
+        player_moves = [m for m in moves if m["color"] == color]
+
+        counts = {cls: 0 for cls in ALL_CLASSIFICATIONS}
+        for m in player_moves:
+            cls = m["classification"]
+            if cls in counts:
+                counts[cls] += 1
+
+        # Accuracy: average fraction of winning chances preserved each move.
+        # For each move: score = ep_after / max(ep_before, 0.01), clamped 0-1.
+        # Gives 100% for Best/Brilliant, degrades proportionally with EP loss.
+        if player_moves:
+            scores = [
+                max(0.0, min(1.0, m["ep_after"] / max(m["ep_before"], 0.01)))
+                for m in player_moves
+            ]
+            accuracy = round(sum(scores) / len(scores) * 100, 1)
+        else:
+            accuracy = 0.0
+
+        stats[color] = {"accuracy": accuracy, "counts": counts}
+
+    return stats