Delete chess_analyzer.py

chess_analyzer.py

@@ -1,964 +0,0 @@
-#!/usr/bin/env python3
-"""
-Chess Analysis Tool — Chess.com-style move classification using Stockfish.
-"""
-
-import math
-import chess
-import chess.engine
-import chess.pgn
-import chess.polyglot
-import argparse
-import io
-import os
-import sys
-from dataclasses import dataclass, field
-from enum import Enum
-from typing import Optional, List
-
-
-# ─── Expected-score thresholds (Chess.com model) ─────────────────────────────
-# Expected score E = (wins + draws×0.5) / 1000, ranges 0.0–1.0
-# These are Chess.com's exact published cutoffs.
-
-E_EXCELLENT  = 0.02   # 0.00–0.02 loss → Excellent
-E_GOOD       = 0.05   # 0.02–0.05 loss → Good
-E_INACCURACY = 0.10   # 0.05–0.10 loss → Inaccuracy
-E_MISTAKE    = 0.20   # 0.10–0.20 loss → Mistake
-E_BLUNDER    = 1.00   # 0.20+     loss → Blunder
-
-ONLY_MOVE_GAP          = 100    # cp gap to 2nd best to qualify as "only good move"
-MISSED_TACTIC          = 0.15   # e_loss above this → Omission candidate
-SACRIFICE_NET          = 80     # SEE net loss (cp) required to count as a sacrifice
-BOOK_MOVES             = 2      # first N half-moves per side auto-classified as Book
-SEE_MAX_DEPTH          = 12     # recursion cap for SEE (avoids slowdowns in busy positions)
-
-# Special move thresholds
-E_GREAT_TURN           = 0.10   # e must improve by at least this to be "position-turning"
-E_GREAT_TARGET         = 0.55   # and must reach at least this after the move
-E_BRILLIANT_MIN_AFTER  = 0.45   # sac must leave us in an OK position
-E_BRILLIANT_MAX_BEFORE = 0.80   # sac only brilliant if we weren't already winning
-E_MISS_BEST_TARGET     = 0.65   # best move would have been winning
-E_MISS_PLAYED_CAP      = 0.55   # but played move didn't capitalise
-
-# ── Five-state position model ─────────────────────────────────────────────
-# Winning:        e >= 0.72
-# Slightly Winning: 0.60 <= e < 0.72
-# Equal:          0.44 <= e < 0.60
-# Slightly Losing: 0.32 <= e < 0.44
-# Losing:         e < 0.32
-E_WINNING         = 0.72
-E_SLIGHTLY_WINNING = 0.60
-E_EQUAL_LOW       = 0.44   # bottom of equal band
-E_SLIGHTLY_LOSING = 0.32   # below this = losing
-
-MULTIPV         = 5
-DEFAULT_DEPTH   = 18
-DEFAULT_SF_PATH = "stockfish"
-
-
-# ─── Data structures ─────────────────────────────────────────────────────────
-
-class Classification(Enum):
-    BOOK        = "📖 Book"
-    BRILLIANT   = "!! Brilliant"
-    GREAT       = "!  Great"
-    BEST        = "★  Best"
-    EXCELLENT   = "👍 Excellent"
-    GOOD        = "✓  Good"
-    INACCURACY  = "?! Inaccuracy"
-    MISTAKE     = "?  Mistake"
-    BLUNDER     = "?? Blunder"
-    OMISSION    = "✖  Missed Tactic"
-
-
-PIECE_VALUES = {
-    chess.PAWN:   100,
-    chess.KNIGHT: 300,
-    chess.BISHOP: 320,
-    chess.ROOK:   500,
-    chess.QUEEN:  900,
-    chess.KING:   20000,
-}
-
-
-@dataclass
-class EngineMove:
-    move:     chess.Move
-    score:    chess.engine.Score
-    cp:       float
-    pv:       List[chess.Move] = field(default_factory=list)
-    expected: Optional[float]  = None   # WDL-based expected score 0.0–1.0
-
-
-@dataclass
-class MoveAnalysis:
-    move:           chess.Move
-    san:            str
-    classification: Classification
-    cp_loss:        float
-    eval_before:    float
-    eval_after:     float
-    best_move:      Optional[chess.Move]
-    notes:          List[str] = field(default_factory=list)
-    e_loss:         float = 0.0   # expected-score loss (primary severity metric)
-
-
-# ─── Score / WDL helpers ──────────────────────────────────────────────────────
-
-MATE_CP = 10_000
-
-
-def score_to_cp(score: chess.engine.Score) -> float:
-    if score.is_mate():
-        m = score.mate()
-        return (MATE_CP - abs(m)) * (1 if m > 0 else -1)
-    v = score.score()
-    return float(v) if v is not None else 0.0
-
-
-def wdl_to_expected(wdl) -> Optional[float]:
-    """
-    Convert a Stockfish WDL tuple (wins, draws, losses), each 0–1000,
-    to an expected score in [0.0, 1.0] from the side-to-move's perspective.
-    """
-    if wdl is None:
-        return None
-    try:
-        w, d, l = wdl
-        total = w + d + l
-        return (w + d * 0.5) / total if total else None
-    except Exception:
-        return None
-
-
-def cp_to_expected(cp: float) -> float:
-    """Fallback sigmoid: ±100cp ≈ 0.63/0.37, ±300cp ≈ 0.80/0.20."""
-    return 1.0 / (1.0 + math.exp(-cp / 320.0))
-
-
-# ─── Static Exchange Evaluation ───────────────────────────────────────────────
-
-def _least_valuable_attacker(board: chess.Board, square: chess.Square,
-                              color: chess.Color) -> Optional[chess.Square]:
-    attackers = board.attackers(color, square)
-    if not attackers:
-        return None
-    return min(
-        attackers,
-        key=lambda sq: PIECE_VALUES.get(board.piece_at(sq).piece_type, 99999)
-                       if board.piece_at(sq) else 99999
-    )
-
-
-def see(board: chess.Board, square: chess.Square,
-        attacker_color: chess.Color, depth: int = 0) -> int:
-    """
-    Static Exchange Evaluation on `square` for `attacker_color`.
-    Returns net material gain (cp): positive = attacker profits, negative = loses.
-    """
-    if depth >= SEE_MAX_DEPTH:
-        return 0
-
-    attacker_sq = _least_valuable_attacker(board, square, attacker_color)
-    if attacker_sq is None:
-        return 0
-
-    attacker_piece = board.piece_at(attacker_sq)
-    target_piece   = board.piece_at(square)
-    if attacker_piece is None:
-        return 0
-
-    target_val = PIECE_VALUES.get(target_piece.piece_type, 0) if target_piece else 0
-
-    b = board.copy()
-    capture = chess.Move(attacker_sq, square)
-    if not b.is_legal(capture):
-        return 0
-    b.push(capture)
-
-    opponent_gain = see(b, square, not attacker_color, depth + 1)
-    return target_val - max(0, opponent_gain)
-
-
-def see_move(board: chess.Board, move: chess.Move) -> int:
-    """SEE for a specific move. Positive = gain, negative = loss."""
-    piece    = board.piece_at(move.from_square)
-    captured = board.piece_at(move.to_square)
-    if piece is None:
-        return 0
-
-    captured_val = PIECE_VALUES.get(captured.piece_type, 0) if captured else 0
-
-    b = board.copy()
-    if not b.is_legal(move):
-        return 0
-    b.push(move)
-
-    opponent_gain = see(b, move.to_square, b.turn)
-    return captured_val - max(0, opponent_gain)
-
-
-def is_sacrifice(board: chess.Board, move: chess.Move) -> bool:
-    """
-    True if the move results in a verified net material loss >= SACRIFICE_NET.
-    Excludes promotions and profitable captures.
-    """
-    piece = board.piece_at(move.from_square)
-    if piece is None or move.promotion:
-        return False
-    return see_move(board, move) <= -SACRIFICE_NET
-
-
-def is_revealed_sacrifice(board: chess.Board,
-                          move: chess.Move) -> tuple:
-    """
-    Detect a "revealed sacrifice": moving a piece that was shielding a more
-    valuable friendly piece, deliberately leaving that piece exposed.
-    Classic example: unpinning a knight that was pinned to the queen — the
-    knight moves away and the queen is now en prise, but the move is brilliant
-    because of what follows.
-
-    Returns (is_revealed, piece_name, material_at_risk_cp) where:
-      is_revealed       — True if a friendly piece is newly hanging after the move
-      piece_name        — name of the piece left exposed (e.g. "queen")
-      material_at_risk  — how much the opponent can gain by capturing it (SEE)
-    """
-    if move.promotion:
-        return False, "", 0
-
-    color = board.turn
-    b = board.copy()
-    if move not in b.legal_moves:
-        return False, "", 0
-    b.push(move)  # now it's opponent's turn in b
-
-    max_gain  = 0
-    max_piece = ""
-
-    for sq in chess.SQUARES:
-        # Skip the square the piece just moved TO — that square is already
-        # handled by is_sacrifice (SEE on the destination). Including it here
-        # causes ordinary trades (pawn takes pawn, opponent takes back) to be
-        # flagged as revealed sacrifices.
-        if sq == move.to_square:
-            continue
-
-        piece = b.piece_at(sq)
-        if piece is None or piece.color != color or piece.piece_type == chess.KING:
-            continue
-        # How much can the opponent gain by capturing this OTHER piece?
-        gain = see(b, sq, not color)
-        if gain > max_gain:
-            max_gain  = gain
-            max_piece = chess.piece_name(piece.piece_type)
-
-    return max_gain >= SACRIFICE_NET, max_piece, max_gain
-
-
-def is_recapture(board: chess.Board, move: chess.Move,
-                 prev_move: Optional[chess.Move]) -> bool:
-    """True if the move captures back on the square the opponent just moved to."""
-    if prev_move is None:
-        return False
-    return (board.piece_at(move.to_square) is not None
-            and move.to_square == prev_move.to_square)
-
-
-# ─── Tactic helpers ──────────────────────────────────────────────────────────
-
-def creates_fork(board: chess.Board, move: chess.Move) -> bool:
-    """True if the move attacks 2+ valuable opponent pieces simultaneously."""
-    b = board.copy()
-    b.push(move)
-    attacker = b.piece_at(move.to_square)
-    if attacker is None:
-        return False
-    targets = sum(
-        1 for sq in b.attacks(move.to_square)
-        if b.piece_at(sq)
-        and b.piece_at(sq).color != attacker.color
-        and b.piece_at(sq).piece_type in (chess.QUEEN, chess.ROOK,
-                                          chess.KNIGHT, chess.BISHOP, chess.KING)
-    )
-    return targets >= 2
-
-
-def forced_mate_available(lines: List[EngineMove]) -> Optional[int]:
-    """Return mate-in count if the engine's best move forces mate, else None."""
-    if lines and lines[0].score.is_mate():
-        m = lines[0].score.mate()
-        return m if m > 0 else None
-    return None
-
-
-def allows_forced_mate(lines_after: List[EngineMove]) -> Optional[int]:
-    """
-    Return opponent's mate-in count if the played move hands them a forced mate.
-    lines_after[0] is from the OPPONENT's POV: m > 0 means they have forced mate.
-    """
-    if lines_after and lines_after[0].score.is_mate():
-        m = lines_after[0].score.mate()
-        if m > 0:
-            return m
-    return None
-
-
-# ─── PV to SAN ───────────────────────────────────────────────────────────────
-
-def pv_to_san(board: chess.Board, pv: List[chess.Move], max_moves: int = 5) -> List[str]:
-    """Convert a PV list to SAN notation strings."""
-    result = []
-    b = board.copy()
-    for move in pv[:max_moves]:
-        if move not in b.legal_moves:
-            break
-        result.append(b.san(move))
-        b.push(move)
-    return result
-
-
-def _material_for(board: chess.Board, color: chess.Color) -> int:
-    """Total piece value for `color` (pawns included, king excluded)."""
-    return sum(
-        len(board.pieces(pt, color)) * PIECE_VALUES[pt]
-        for pt in (chess.PAWN, chess.KNIGHT, chess.BISHOP, chess.ROOK, chess.QUEEN)
-    )
-
-
-def pv_wins_material_back(board: chess.Board, move: chess.Move,
-                          pv: List[chess.Move], max_moves: int = 8) -> bool:
-    """
-    True if, after playing `move` followed by the PV continuation, the side
-    that made the sacrifice has recovered at least as much material as they lost.
-    Catches "combination sacrifices" — give a piece, win it (or more) back.
-
-    Requires at least 2 PV moves after the sacrifice (the opponent's recapture
-    + one response) to avoid false positives when the opponent hasn't replied yet.
-    """
-    if len(pv) < 2:
-        return False  # not enough continuation to judge
-
-    mover = board.turn
-    mat_before = _material_for(board, mover)
-
-    b = board.copy()
-    if move not in b.legal_moves:
-        return False
-    b.push(move)
-
-    # Play out the PV continuation (starts with opponent's response)
-    for m in pv[:max_moves]:
-        if m not in b.legal_moves:
-            break
-        b.push(m)
-
-    mat_after = _material_for(b, mover)
-    # Won back at least as much as sacrificed (within a pawn of tolerance)
-    return mat_after >= mat_before - PIECE_VALUES[chess.PAWN]
-
-
-# ─── Core classification ──────────────────────────────────────────────────────
-
-def classify_move(
-    board:         chess.Board,
-    move:          chess.Move,
-    lines_before:  List[EngineMove],
-    lines_after:   List[EngineMove],
-    is_book:       bool = False,
-    half_move_idx: int  = 99,
-    prev_move:     Optional[chess.Move] = None,
-) -> MoveAnalysis:
-    san = board.san(move)
-
-    # ── Centipawn evals (kept for notes and CLI output) ───────────────────────
-    eval_before = lines_before[0].cp if lines_before else 0.0
-    eval_after  = (-lines_after[0].cp) if lines_after else eval_before
-    cp_loss     = eval_before - eval_after
-    best_move   = lines_before[0].move if lines_before else None
-
-    # ── Expected score ────────────────────────────────────────────────────────
-    # e_before : current player's expected score BEFORE the move (side-to-move POV)
-    # e_after  : current player's expected score AFTER the move
-    #            lines_after[0].expected is from the OPPONENT's POV → flip with 1 - x
-    e_before    = (lines_before[0].expected
-                   if lines_before and lines_before[0].expected is not None
-                   else cp_to_expected(eval_before))
-    e_after_raw = (lines_after[0].expected
-                   if lines_after and lines_after[0].expected is not None
-                   else None)
-    e_after     = ((1.0 - e_after_raw) if e_after_raw is not None
-                   else cp_to_expected(eval_after))
-    e_loss      = max(0.0, e_before - e_after)
-
-    # ── Five-state position categorisation (computed early for brilliant guard) ─
-    def state(e):
-        if   e >= E_WINNING:          return "winning"
-        elif e >= E_SLIGHTLY_WINNING: return "slightly_winning"
-        elif e >= E_EQUAL_LOW:        return "equal"
-        elif e >= E_SLIGHTLY_LOSING:  return "slightly_losing"
-        else:                         return "losing"
-    state_before = state(e_before)
-    state_after  = state(e_after)
-
-    # ── Auto-Book ─────────────────────────────────────────────────────────────
-    if is_book or ((half_move_idx // 2) + 1) <= BOOK_MOVES:
-        return MoveAnalysis(move, san, Classification.BOOK,
-                            0.0, eval_before, eval_after, best_move,
-                            ["Opening theory"], e_loss=0.0)
-
-    # ── Move rank among engine suggestions ───────────────────────────────────
-    move_rank: Optional[int] = None
-    for i, em in enumerate(lines_before):
-        if em.move == move:
-            move_rank = i
-            break
-
-    notes: List[str] = []
-
-    # ── Tactical context ──────────────────────────────────────────────────────
-    mate_in       = forced_mate_available(lines_before)
-    mate_allowed  = allows_forced_mate(lines_after)
-    move_captures = board.piece_at(move.to_square) is not None
-    move_see      = see_move(board, move)
-    sacrifice     = is_sacrifice(board, move)
-    revealed_sac, revealed_piece, revealed_mat = is_revealed_sacrifice(board, move)
-    recapture     = is_recapture(board, move, prev_move)
-    is_engine_best = (move_rank == 0)
-
-    # After our move, does the engine say WE have forced mate?
-    # lines_after[0].score is from opponent's POV: m < 0 means they are being mated.
-    we_have_mate_after: Optional[int] = None
-    if lines_after and lines_after[0].score.is_mate():
-        m = lines_after[0].score.mate()
-        if m < 0:
-            we_have_mate_after = abs(m)  # we have forced mate in this many moves
-
-    test_board = board.copy()
-    test_board.push(move)
-    gives_checkmate = test_board.is_checkmate()
-
-    # ── BRILLIANT shortcut ───────────────────────────────────────────────────
-    # If the move is a sacrifice (direct or revealed) AND the engine ranks it
-    # in its top 3 (Best or Excellent), classify immediately as Brilliant before
-    # any e_loss checks. A sacrifice that the engine endorses cannot be a Mistake.
-    #
-    # Extra guard for revealed sacrifices: the exposed piece must actually be
-    # threatened in a way the opponent can't easily avoid. We check this by
-    # seeing if the opponent's best response (lines_after[0]) captures the
-    # exposed piece. If they ignore it and play something else, the "sacrifice"
-    # isn't forced and shouldn't be Brilliant.
-    is_forced_revealed = False
-    if revealed_sac and not sacrifice:
-        # Find which square has the exposed piece (highest SEE gain for opponent)
-        b_tmp = board.copy()
-        b_tmp.push(move)
-        exposed_sq = None
-        best_gain  = 0
-        for sq in chess.SQUARES:
-            if sq == move.to_square:
-                continue
-            piece_here = b_tmp.piece_at(sq)
-            if piece_here and piece_here.color == board.turn and piece_here.piece_type != chess.KING:
-                g = see(b_tmp, sq, not board.turn)
-                if g > best_gain:
-                    best_gain  = g
-                    exposed_sq = sq
-
-        # Two cases qualify as a genuine revealed sacrifice:
-        #
-        # A) Opponent's best response IS to take the exposed piece
-        #    (e.g. previous pawn-trade fix — the threat is forced)
-        #
-        # B) The exposed piece IS legally capturable (an opponent piece
-        #    attacks that square), but the engine recommends NOT taking —
-        #    because taking leads to mate or material loss for the opponent.
-        #    This is the "knight captures pinned piece, queen exposed but
-        #    untouchable" pattern.
-        opp_can_capture = (
-            exposed_sq is not None
-            and bool(b_tmp.attackers(not board.turn, exposed_sq))
-        )
-        opp_takes_it = (
-            exposed_sq is not None
-            and lines_after
-            and lines_after[0].move.to_square == exposed_sq
-        )
-        if opp_takes_it:
-            is_forced_revealed = True
-        elif opp_can_capture:
-            # Opponent can take but the engine says don't — verify it's actually
-            # bad for them by simulating the capture and checking the resulting eval.
-            # If after they take, WE have forced mate or our expected score is high,
-            # then deliberately leaving the piece en prise is brilliant.
-            capture_move = None
-            for atk_sq in b_tmp.attackers(not board.turn, exposed_sq):
-                cand = chess.Move(atk_sq, exposed_sq)
-                if b_tmp.is_legal(cand):
-                    capture_move = cand
-                    break
-            if capture_move is not None:
-                b_capture = b_tmp.copy()
-                b_capture.push(capture_move)
-                # After they capture: do WE have forced mate, or is our expected score good?
-                # Use SEE on the capture square from OUR side to check net material
-                our_response_gain = see(b_capture, exposed_sq, board.turn)
-                # If taking leads to: forced mate for us (we_have_mate_after already set),
-                # OR we win significant material back after their capture, it's brilliant
-                if we_have_mate_after is not None or our_response_gain >= SACRIFICE_NET:
-                    is_forced_revealed = True
-        # Also allow: forced mate after the move regardless of capture availability
-        if we_have_mate_after is not None and exposed_sq is not None:
-            is_forced_revealed = True
-
-    if (sacrifice or is_forced_revealed) and move_rank is not None and move_rank <= 2\
-            and state_after not in ('slightly_losing', 'losing'):
-        piece = board.piece_at(move.from_square)
-        piece_name = chess.piece_name(piece.piece_type) if piece else "piece"
-        if we_have_mate_after is not None:
-            label = f"Sacrifice leads to forced mate in {we_have_mate_after}"
-        elif is_forced_revealed and not sacrifice:
-            label = f"Deliberately exposes the {revealed_piece or 'piece'} for a greater gain"
-        elif lines_before and pv_wins_material_back(board, move, lines_before[0].pv[1:]):
-            label = "Wins material back in the combination"
-        else:
-            label = f"Sacrifices the {piece_name} for advantage"
-        notes.append(label)
-        return MoveAnalysis(move, san, Classification.BRILLIANT,
-                            cp_loss, eval_before, eval_after, best_move, notes, e_loss)
-
-    # ── Five-state position categorisation ──────────────────────────────────
-    # ── Transition-based severity floor (negative moves) ─────────────────────
-    # Maps (state_before, state_after) → minimum classification for non-engine-best moves.
-    NEGATIVE_FLOORS = {
-        # Winning → worse
-        ("winning",          "slightly_winning"): ("inaccuracy", "Gave up the winning advantage"),
-        ("winning",          "equal"):            ("mistake",    "Lost a winning advantage"),
-        ("winning",          "slightly_losing"):  ("mistake",    "Threw away a winning position"),
-        ("winning",          "losing"):           ("mistake",    "Threw away a winning position"),
-        # Slightly winning → worse
-        ("slightly_winning", "equal"):            ("inaccuracy", "Gave up the winning advantage"),
-        ("slightly_winning", "slightly_losing"):  ("mistake",    "Lost a winning advantage"),
-        ("slightly_winning", "losing"):           ("mistake",    "Threw away a winning position"),
-        # Equal → worse
-        ("equal",            "slightly_losing"):  ("mistake",    "Position went from equal to losing"),
-        ("equal",            "losing"):           ("mistake",    "Position went from equal to losing"),
-        # Slightly losing → much worse
-        ("slightly_losing",  "losing"):           ("inaccuracy", None),
-    }
-
-    # ── Transition-based positive upgrade (good moves recovering position) ───
-    # Maps (state_before, state_after) → minimum positive classification.
-    POSITIVE_UPGRADES = {
-        ("losing",          "winning"):          "great",
-        ("losing",          "slightly_winning"): "great",
-        ("losing",          "equal"):            "great",
-        ("losing",          "slightly_losing"):  "best",
-        ("slightly_losing", "winning"):          "great",
-        ("slightly_losing", "slightly_winning"): "great",
-        ("slightly_losing", "equal"):            "best",
-        ("equal",           "winning"):          "great",
-        ("equal",           "slightly_winning"): "best",
-        ("slightly_winning","winning"):          "best",
-    }
-
-    min_severity   = None
-    min_pos_upg    = None   # minimum positive upgrade
-    trans_note     = None
-
-    if not is_engine_best:
-        floor = NEGATIVE_FLOORS.get((state_before, state_after))
-        if floor:
-            min_severity, trans_note = floor
-
-    upgrade = POSITIVE_UPGRADES.get((state_before, state_after))
-    if upgrade:
-        min_pos_upg = upgrade
-
-    if trans_note:
-        notes.append(trans_note)
-
-    # ── Context-aware severity cap ────────────────────────────────────────────
-    # Caps how bad a move can be if the resulting position is still decent.
-    if e_after >= E_SLIGHTLY_WINNING and not mate_allowed:
-        max_severity = "inaccuracy"
-    elif e_after >= E_EQUAL_LOW and not mate_allowed:
-        max_severity = "mistake"
-    else:
-        max_severity = "blunder"
-
-    # Wrong recapture choice caps at Inaccuracy
-    if recapture and max_severity in ("blunder", "mistake"):
-        max_severity = "inaccuracy"
-
-    # Floor can override cap (e.g. transition floor is worse than position cap)
-    SEVERITY_ORDER = ["inaccuracy", "mistake", "blunder"]
-    if min_severity and SEVERITY_ORDER.index(min_severity) > SEVERITY_ORDER.index(max_severity):
-        max_severity = min_severity
-
-    # ── BLUNDER ───────────────────────────────────────────────────────────────
-    if mate_allowed and not is_engine_best:
-        notes.append(f"Allows mate in {mate_allowed}")
-        return MoveAnalysis(move, san, Classification.BLUNDER,
-                            cp_loss, eval_before, eval_after, best_move, notes, e_loss)
-
-    if not is_engine_best and max_severity == "blunder":
-        if e_loss >= E_BLUNDER:
-            if not (move_captures and move_see >= -50):
-                notes.append("Hangs material")
-                return MoveAnalysis(move, san, Classification.BLUNDER,
-                                    cp_loss, eval_before, eval_after, best_move, notes, e_loss)
-
-    # ── MISTAKE ───────────────────────────────────────────────────────────────
-    if not is_engine_best and max_severity in ("blunder", "mistake"):
-        if min_severity in ("blunder", "mistake") or e_loss >= E_MISTAKE:
-            return MoveAnalysis(move, san, Classification.MISTAKE,
-                                cp_loss, eval_before, eval_after, best_move, notes, e_loss)
-
-    # ── INACCURACY ────────────────────────────────────────────────────────────
-    if not is_engine_best and move_rank is not None:
-        if min_severity or e_loss >= E_INACCURACY:
-            return MoveAnalysis(move, san, Classification.INACCURACY,
-                                cp_loss, eval_before, eval_after, best_move, notes, e_loss)
-
-    # ── OMISSION ─────────────────────────────────────────────────────────────
-    # Case 1: Missed a forced mate
-    if mate_in and move_rank is not None and move_rank > 0:
-        notes.append(f"Missed mate in {mate_in}")
-        return MoveAnalysis(move, san, Classification.OMISSION,
-                            cp_loss, eval_before, eval_after, best_move, notes, e_loss)
-
-    # Case 2: Missed a fork
-    if e_loss >= MISSED_TACTIC and not is_engine_best:
-        if (lines_before
-                and creates_fork(board, lines_before[0].move)
-                and not creates_fork(board, move)):
-            notes.append("Missed a fork")
-            return MoveAnalysis(move, san, Classification.OMISSION,
-                                cp_loss, eval_before, eval_after, best_move, notes, e_loss)
-
-    # Case 3: Missed opportunity after opponent's mistake
-    # e_before is the expected score for the current player given optimal play from here.
-    # If e_before (= what we'd get with the best move) is winning, but e_after (what we
-    # actually got) is not, we missed the chance to capitalise.
-    if (not is_engine_best
-            and move_rank is not None
-            and e_before >= E_MISS_BEST_TARGET    # best move was winning
-            and e_after  <= E_MISS_PLAYED_CAP     # played move didn't capitalise
-            and e_before <= E_MISS_PLAYED_CAP + E_MISS_BEST_TARGET):  # not already winning before
-        notes.append("Missed opportunity to reach a winning position")
-        return MoveAnalysis(move, san, Classification.OMISSION,
-                            cp_loss, eval_before, eval_after, best_move, notes, e_loss)
-
-    # ── Positive classifications ──────────────────────────────────────────────
-
-    if move_rank is None:
-        return MoveAnalysis(move, san, Classification.GOOD,
-                            cp_loss, eval_before, eval_after, best_move, notes, e_loss)
-
-    if move_rank == 0:
-        if gives_checkmate:
-            notes.append("Checkmate!")
-            return MoveAnalysis(move, san, Classification.BEST,
-                                cp_loss, eval_before, eval_after, best_move, notes, e_loss)
-
-        # ── BRILLIANT ─────────────────────────────────────────────────────────
-        # Guard: a sacrifice that leaves us in a bad position is a blunder, not brilliant.
-        # If the position goes to slightly_losing or losing after the sac, it's not brilliant.
-        sac_is_valid = (sacrifice or is_forced_revealed) and state_after not in ("slightly_losing", "losing")
-        if sac_is_valid:
-            piece = board.piece_at(move.from_square)
-            piece_name = chess.piece_name(piece.piece_type) if piece else "piece"
-            if we_have_mate_after is not None:
-                label = f"Sacrifice leads to forced mate in {we_have_mate_after}"
-            elif is_forced_revealed and not sacrifice:
-                label = f"Deliberately exposes the {revealed_piece or 'piece'} for a greater gain"
-            elif lines_before and pv_wins_material_back(board, move, lines_before[0].pv[1:]):
-                label = "Wins material back in the combination"
-            else:
-                label = f"Sacrifices the {piece_name} for advantage"
-            notes.append(label)
-            return MoveAnalysis(move, san, Classification.BRILLIANT,
-                                cp_loss, eval_before, eval_after, best_move, notes, e_loss)
-
-        # ── GREAT / BEST from position transition ─────────────────────────────
-        if min_pos_upg == "great" and not recapture:
-            label_map = {
-                ("losing",         "winning"):          "Turned a losing position into a winning one",
-                ("losing",         "slightly_winning"): "Escaped a losing position",
-                ("losing",         "equal"):            "Rescued an equal position from a lost game",
-                ("losing",         "slightly_losing"):  "Improved a losing position",
-                ("slightly_losing","winning"):          "Turned the game around completely",
-                ("slightly_losing","slightly_winning"): "Turned the tables",
-                ("slightly_losing","equal"):            "Equalised from a losing position",
-                ("equal",          "winning"):          "Seized the winning advantage",
-                ("equal",          "slightly_winning"): "Gained the winning edge",
-            }
-            trans_label = label_map.get((state_before, state_after), "Strong recovery move")
-            notes.append(trans_label)
-            return MoveAnalysis(move, san, Classification.GREAT,
-                                cp_loss, eval_before, eval_after, best_move, notes, e_loss)
-
-        # ── GREAT ─────────────────────────────────────────────────────────────
-        if not recapture:
-            only_good_move = (
-                len(lines_before) >= 2
-                and (lines_before[0].cp - lines_before[1].cp) >= ONLY_MOVE_GAP
-            )
-            position_turning = (
-                e_after >= E_GREAT_TARGET
-                and (e_after - e_before) >= E_GREAT_TURN
-                and e_before < E_GREAT_TARGET
-            )
-            if only_good_move:
-                gap = int(lines_before[0].cp - lines_before[1].cp)
-                notes.append(f"Only good move (2nd best is {gap} cp worse)")
-                return MoveAnalysis(move, san, Classification.GREAT,
-                                    cp_loss, eval_before, eval_after, best_move, notes, e_loss)
-            if position_turning:
-                notes.append("Turns a losing position around"
-                             if e_before < E_EQUAL_LOW
-                             else "Turns an equal position into a winning one")
-                return MoveAnalysis(move, san, Classification.GREAT,
-                                    cp_loss, eval_before, eval_after, best_move, notes, e_loss)
-
-        return MoveAnalysis(move, san, Classification.BEST,
-                            cp_loss, eval_before, eval_after, best_move, notes, e_loss)
-
-    if move_rank in (1, 2):
-        # ── BRILLIANT (rank 1-2 — Excellent move that is also a sacrifice) ────
-        sac_is_valid = (sacrifice or is_forced_revealed) and state_after not in ("slightly_losing", "losing")
-        if sac_is_valid:
-            piece = board.piece_at(move.from_square)
-            piece_name = chess.piece_name(piece.piece_type) if piece else "piece"
-            if we_have_mate_after is not None:
-                label = f"Sacrifice leads to forced mate in {we_have_mate_after}"
-            elif is_forced_revealed and not sacrifice:
-                label = f"Deliberately exposes the {revealed_piece or 'piece'} for a greater gain"
-            elif lines_before and pv_wins_material_back(board, move, lines_before[0].pv[1:]):
-                label = "Wins material back in the combination"
-            else:
-                label = f"Sacrifices the {piece_name} for advantage"
-            notes.append(label)
-            return MoveAnalysis(move, san, Classification.BRILLIANT,
-                                cp_loss, eval_before, eval_after, best_move, notes, e_loss)
-        return MoveAnalysis(move, san, Classification.EXCELLENT,
-                            cp_loss, eval_before, eval_after, best_move, notes, e_loss)
-
-    return MoveAnalysis(move, san, Classification.GOOD,
-                        cp_loss, eval_before, eval_after, best_move, notes, e_loss)
-
-
-# ─── Analyzer ─────────────────────────────────────────────────────────────────
-
-class ChessAnalyzer:
-    def __init__(self,
-                 stockfish_path: str = DEFAULT_SF_PATH,
-                 depth:   int = DEFAULT_DEPTH,
-                 multipv: int = MULTIPV,
-                 time_ms: Optional[int] = None):
-        self.stockfish_path = stockfish_path
-        self.depth   = depth
-        self.multipv = multipv
-        self.time_ms = time_ms
-        self.engine: Optional[chess.engine.SimpleEngine] = None
-
-    def __enter__(self):
-        self.engine = chess.engine.SimpleEngine.popen_uci(self.stockfish_path)
-        try:
-            self.engine.configure({"UCI_ShowWDL": True})
-        except Exception:
-            pass  # older Stockfish builds silently skip
-        return self
-
-    def __exit__(self, *_):
-        if self.engine:
-            self.engine.quit()
-
-    def _limit(self) -> chess.engine.Limit:
-        if self.time_ms is not None:
-            return chess.engine.Limit(time=self.time_ms / 1000.0)
-        return chess.engine.Limit(depth=self.depth)
-
-    def _top_moves(self, board: chess.Board,
-                   multipv: Optional[int] = None) -> List[EngineMove]:
-        n = multipv if multipv is not None else self.multipv
-        infos = self.engine.analyse(board, self._limit(), multipv=n)
-        result = []
-        for info in infos:
-            if "pv" not in info or not info["pv"]:
-                continue
-            pov_score = info["score"].relative
-            cp        = score_to_cp(pov_score)
-            expected  = wdl_to_expected(info.get("wdl")) or cp_to_expected(cp)
-            result.append(EngineMove(
-                move=info["pv"][0], score=pov_score, cp=cp,
-                pv=list(info["pv"]), expected=expected,
-            ))
-        return result
-
-    def _is_book(self, board: chess.Board, move: chess.Move,
-                 book_path: Optional[str]) -> bool:
-        if not book_path or not os.path.exists(book_path):
-            return False
-        try:
-            with chess.polyglot.open_reader(book_path) as reader:
-                return any(e.move == move for e in reader.find_all(board))
-        except Exception:
-            return False
-
-    def analyze_game(self, pgn_string: str,
-                     book_path: Optional[str] = None) -> List[MoveAnalysis]:
-        game = chess.pgn.read_game(io.StringIO(pgn_string))
-        if game is None:
-            raise ValueError("Could not parse PGN.")
-
-        board  = game.board()
-        moves  = list(game.mainline_moves())
-        total  = len(moves)
-
-        print(f"\n  White: {game.headers.get('White', '?')}")
-        print(f"  Black: {game.headers.get('Black', '?')}")
-        print(f"  Depth: {self.depth}  |  MultiPV: {self.multipv}\n")
-
-        lines_before = self._top_moves(board)
-        prev_move: Optional[chess.Move] = None
-        results: List[MoveAnalysis] = []
-
-        for i, move in enumerate(moves):
-            move_num = (i // 2) + 1
-            dot      = "." if board.turn == chess.WHITE else "..."
-            sys.stdout.write(f"\r  Analyzing {i+1}/{total}  "
-                             f"{move_num}{dot}{board.san(move):<10}   ")
-            sys.stdout.flush()
-
-            book = self._is_book(board, move, book_path)
-
-            board.push(move)
-            lines_after = self._top_moves(board, multipv=1)
-            board.pop()
-
-            analysis = classify_move(board, move, lines_before, lines_after,
-                                     is_book=book, half_move_idx=i,
-                                     prev_move=prev_move)
-            board.push(move)
-            results.append(analysis)
-            prev_move = move
-
-            if i + 1 < total:
-                lines_before = self._top_moves(board)
-
-        print("\r" + " " * 60)
-        return results
-
-    def analyze_position(self, fen: str) -> List[EngineMove]:
-        return self._top_moves(chess.Board(fen))
-
-
-# ─── Reporting ────────────────────────────────────────────────────────────────
-
-COLORS = {
-    Classification.BRILLIANT:  "\033[96m",
-    Classification.GREAT:      "\033[94m",
-    Classification.BEST:       "\033[92m",
-    Classification.EXCELLENT:  "\033[32m",
-    Classification.GOOD:       "\033[37m",
-    Classification.BOOK:       "\033[90m",
-    Classification.INACCURACY: "\033[33m",
-    Classification.MISTAKE:    "\033[91m",
-    Classification.BLUNDER:    "\033[31m",
-    Classification.OMISSION:   "\033[35m",
-}
-RESET = "\033[0m"
-
-
-def print_analysis(analyses: List[MoveAnalysis], pgn_string: str,
-                   white_only: bool = False, black_only: bool = False) -> None:
-    print("=" * 68)
-    print("  GAME ANALYSIS")
-    print("=" * 68)
-
-    for color_label, start_idx in (("White", 0), ("Black", 1)):
-        player_moves = analyses[start_idx::2]
-        counts: dict = {}
-        for a in player_moves:
-            counts[a.classification] = counts.get(a.classification, 0) + 1
-        avg_e_loss = (
-            sum(a.e_loss for a in player_moves
-                if a.classification not in (Classification.BOOK, Classification.BRILLIANT,
-                                            Classification.GREAT, Classification.BEST,
-                                            Classification.EXCELLENT))
-            / max(1, len(player_moves))
-        )
-        print(f"\n  ── {color_label} ──")
-        for cls in Classification:
-            if cls in counts:
-                print(f"    {COLORS.get(cls,'')}{cls.value:<22}{RESET}  ×{counts[cls]}")
-        print(f"    Avg expected score loss: {avg_e_loss:.4f}")
-
-    print("\n" + "=" * 68)
-    print("  MOVE-BY-MOVE")
-    print("=" * 68)
-
-    for i, a in enumerate(analyses):
-        if white_only and i % 2 != 0: continue
-        if black_only and i % 2 != 1: continue
-        move_num = (i // 2) + 1
-        dot      = "." if i % 2 == 0 else "..."
-        color    = COLORS.get(a.classification, "")
-        e_str    = f"  (−{a.e_loss:.3f} EP)" if a.e_loss > 0.005 else ""
-        note_str = f"  — {', '.join(a.notes)}" if a.notes else ""
-        eval_str = f"  [{a.eval_after/100:+.2f}]"
-        print(f"  {move_num:>3}{dot}{a.san:<8}  "
-              f"{color}{a.classification.value:<22}{RESET}"
-              f"{eval_str}{e_str}{note_str}")
-
-
-def print_position_analysis(moves: List[EngineMove], fen: str) -> None:
-    board = chess.Board(fen)
-    turn  = "White" if board.turn == chess.WHITE else "Black"
-    print(f"\n  Position: {fen}\n  Turn: {turn}\n")
-    print(f"  {'Rank':<6} {'Move':<10} {'Eval':>8}  {'E-score':>8}")
-    print("  " + "-" * 40)
-    for i, em in enumerate(moves, 1):
-        san       = board.san(em.move)
-        score_str = f"M{em.score.mate()}" if em.score.is_mate() else f"{em.cp/100:+.2f}"
-        e_str     = f"{em.expected:.3f}" if em.expected is not None else "—"
-        print(f"  {i:<6} {san:<10} {score_str:>8}  {e_str:>8}")
-
-
-# ─── CLI ──────────────────────────────────────────────────────────────────────
-
-def main():
-    parser = argparse.ArgumentParser(
-        description="Chess analysis — Chess.com-style move classification")
-    parser.add_argument("pgn", nargs="?", help="Path to .pgn file")
-    parser.add_argument("--fen",       help="Analyse single position (FEN string)")
-    parser.add_argument("--stockfish", default=DEFAULT_SF_PATH)
-    parser.add_argument("--depth",     type=int, default=DEFAULT_DEPTH)
-    parser.add_argument("--multipv",   type=int, default=MULTIPV)
-    parser.add_argument("--book",      help="Polyglot opening book (.bin)")
-    parser.add_argument("--white",     action="store_true")
-    parser.add_argument("--black",     action="store_true")
-    args = parser.parse_args()
-
-    if not args.pgn and not args.fen:
-        parser.print_help()
-        sys.exit(1)
-
-    try:
-        with ChessAnalyzer(args.stockfish, args.depth, args.multipv) as analyzer:
-            if args.fen:
-                print_position_analysis(analyzer.analyze_position(args.fen), args.fen)
-                return
-            with open(args.pgn) as f:
-                pgn_string = f.read()
-            print_analysis(analyzer.analyze_game(pgn_string, args.book),
-                           pgn_string, args.white, args.black)
-    except FileNotFoundError:
-        print(f"\n  ✗ Stockfish not found at '{args.stockfish}'.")
-        sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()