torre 0.3.0__py3-none-any.whl

torre/__init__.py

@@ -0,0 +1,6 @@
+"""Torre: the chess studio's Python side (server, coach, engines, lessons, puzzles).
+
+Run the studio with `python -m torre.server.studio`, the command line with `python -m torre`.
+"""
+
+__version__ = '0.3.0'

torre/__main__.py

@@ -0,0 +1,4 @@
+"""`python -m torre ...`: the command line (cli.py)."""
+from torre.cli import main
+
+raise SystemExit(main())

torre/analysis/__init__.py

@@ -0,0 +1 @@
+"""Engines, analysis and scoring: Stockfish runs, move grades, motifs, stats, reports and exports."""

torre/analysis/analyze.py

@@ -0,0 +1,337 @@
+"""Analyze games with Stockfish: Lichess-style judgments and accuracy.
+
+Reads:  data/games.jsonl
+Writes: data/analysis.jsonl  (resume-safe; one record per game)
+
+Moves are judged the way Lichess does it, by the drop in winning chances
+(inaccuracy / mistake / blunder), and game accuracy uses Lichess's formula;
+see scoring.py. Moves matching the engine's choice are tagged "best", and
+sound sacrifices "brilliant". Centipawn loss (capped at +/-1500, mate beyond
+the cap) is still recorded for the ACPL statistics.
+
+Records from an older SCORING_VERSION are re-analyzed first. analyze_archive is
+the whole pipeline (analysis, then puzzles mined from the new analyses) behind
+`torre analyze` and the studio's background analysis.
+
+Usage: .venv/Scripts/python analyze.py [--depth 12] [--limit N]  (the same as torre analyze)
+"""
+
+import io
+import json
+import logging
+import sys
+import threading
+from pathlib import Path
+
+import chess
+import chess.engine
+import chess.pgn
+
+from torre.analysis import scoring
+from torre.analysis import engines
+from torre import jsonio
+GAMES_FILE = Path("data/games.jsonl")
+ANALYSIS_FILE = Path("data/analysis.jsonl")
+
+# v3: shared eight-grade classification, opening provenance and runner-up evaluations.
+SCORING_VERSION = 3
+EVAL_CAP = 1500
+DEFAULT_DEPTH = 12
+MATED_CP = 100_000  # stored cp for a checkmated side (White POV sign)
+# Appends to analysis files and their compaction take turns (within this process).
+ANALYSIS_LOCK = threading.Lock()
+log = logging.getLogger(__name__)
+
+
+def phase_of(fullmove: int) -> str:
+    if fullmove <= 10:
+        return "opening"
+    if fullmove <= 30:
+        return "middlegame"
+    return "endgame"
+
+
+def evaluate(engine, board: chess.Board, depth: int, alternatives=None):
+    """White-POV [cp, mate] for `board`, plus the engine's best move (uci)."""
+    if board.is_checkmate():
+        if alternatives is not None:
+            alternatives.append(None)
+        return [-MATED_CP if board.turn == chess.WHITE else MATED_CP, None], None
+    if board.is_stalemate() or board.is_insufficient_material():
+        if alternatives is not None:
+            alternatives.append(None)
+        return [0, None], None
+    infos = engine.analyse(board, chess.engine.Limit(depth=depth), multipv=2)
+    info = infos[0]
+    if alternatives is not None:
+        runner = infos[1]['score'].white() if len(infos) > 1 else None
+        alternatives.append([runner.score(), runner.mate()] if runner is not None else None)
+    score = info["score"].white()
+    pv = info.get("pv") or []
+    best = pv[0].uci() if pv else None
+    if score.is_mate():
+        return [None, score.mate()], best
+    return [score.score(), None], best
+
+
+def legacy_cp(ev, pov: chess.Color) -> int:
+    """Capped centipawns from `pov`, mate beyond the cap (the ACPL scale)."""
+    cp, mate = ev
+    sign = 1 if pov == chess.WHITE else -1
+    if mate is not None or abs(cp) >= MATED_CP:
+        winning = (mate if mate is not None else cp) * sign > 0
+        return (EVAL_CAP + 1000) if winning else -(EVAL_CAP + 1000)
+    return max(-EVAL_CAP, min(EVAL_CAP, cp * sign))
+
+
+def judge_ply(board: chess.Board, move: chess.Move, before, after):
+    """(win_before, win_after, judgment, brilliant) for `move` played in
+    `board`, from the mover's point of view. `before` / `after` are the stored
+    White-POV evals around the move."""
+    white = board.turn == chess.WHITE
+    win_before, win_after = scoring.win_pct(*before), scoring.win_pct(*after)
+    if not white:
+        win_before, win_after = 100 - win_before, 100 - win_after
+    if after[0] is not None and abs(after[0]) >= MATED_CP:  # the move gives checkmate
+        return win_before, win_after, None, False
+    cls = scoring.judge(before, after, white)
+    brilliant = cls is None and scoring.is_brilliant(board, move, win_before, win_after)
+    return win_before, win_after, cls, brilliant
+
+
+def analyze_game(engine, rec: dict, depth: int) -> dict:
+    game = chess.pgn.read_game(io.StringIO(rec["pgn"]))
+    user_color = chess.WHITE if rec["user_color"] == "white" else chess.BLACK
+    standard_start = game.board().fen() == chess.STARTING_FEN
+
+    # Evaluate the start position and the position after every ply.
+    moves = list(game.mainline_moves())
+    board = game.board()
+    evals, best_moves, alternatives = [], [], []
+    for mv in moves:
+        ev, best = evaluate(engine, board, depth, alternatives)
+        evals.append(ev)
+        best_moves.append(best)
+        board.push(mv)
+    final_ev, _ = evaluate(engine, board, depth)
+    evals.append(final_ev)
+
+    win = [scoring.win_pct(*ev) for ev in evals]
+    acc_timeline = [scoring.win_pct(scoring.STANDARD_START_CP)] + win[1:] if standard_start else win
+    accuracy = scoring.game_accuracy(acc_timeline, white_starts=game.board().turn == chess.WHITE)
+
+    user_moves, all_grades = [], []
+    board = game.board()
+    for i, mv in enumerate(moves):
+        mover = board.turn
+        graded = scoring.classify(board, mv,
+            {'cp': evals[i][0], 'mate': evals[i][1], 'best': best_moves[i], 'alternative': alternatives[i]},
+            {'cp': evals[i + 1][0], 'mate': evals[i + 1][1]})
+        all_grades.append(graded)
+        if mover == user_color:
+            win_before, win_after, cls, brilliant = judge_ply(board, mv, evals[i], evals[i + 1])
+            before = legacy_cp(evals[i], mover)
+            cpl = max(0, before - legacy_cp(evals[i + 1], mover))
+            user_moves.append({
+                "ply": i + 1,
+                "move_number": board.fullmove_number,
+                "san": board.san(mv),
+                "fen": board.fen(),
+                "phase": phase_of(board.fullmove_number),
+                "eval_before": before,
+                "cpl": cpl,
+                "win_before": round(win_before, 1),
+                "win_after": round(win_after, 1),
+                **graded,
+            })
+        board.push(mv)
+
+    counts = {"inaccuracy": 0, "mistake": 0, "blunder": 0}
+    for m in user_moves:
+        if m["class"]:
+            counts[m["class"]] += 1
+
+    worst = sorted((m for m in user_moves if m["class"]), key=lambda m: m["win_after"] - m["win_before"])[:5]
+    opp = "black" if user_color == chess.WHITE else "white"
+    rounded = lambda x: None if x is None else round(x, 1)
+
+    return {
+        "id": rec["id"],
+        "scoring_version": SCORING_VERSION,
+        "move_grades": all_grades,
+        "alternatives": alternatives,
+        "grades": {name: sum(scoring.grade(m) == name for m in user_moves) for name in scoring.GRADES},
+        "date": rec.get("date"),
+        "type": rec.get("type"),
+        "opponent": rec.get("opponent"),
+        "user_color": rec["user_color"],
+        "user_result": rec.get("user_result"),
+        "user_accuracy": rec.get("user_accuracy"),
+        "accuracy": rounded(accuracy[rec["user_color"]]),
+        "opp_accuracy": rounded(accuracy[opp]),
+        "opp_rating": rec.get("opp_rating"),
+        "user_rating": rec.get("user_rating"),
+        "user_move_count": len(user_moves),
+        "avg_cpl": round(sum(m["cpl"] for m in user_moves) / max(1, len(user_moves)), 1),
+        **counts,
+        "best": sum(m["best"] for m in user_moves),
+        "brilliant": sum(m["brilliant"] for m in user_moves),
+        "phase_counts": {
+            ph: {
+                "moves": sum(1 for m in user_moves if m["phase"] == ph),
+                "cpl": sum(m["cpl"] for m in user_moves if m["phase"] == ph),
+                "blunders": sum(1 for m in user_moves if m["phase"] == ph and m["class"] == "blunder"),
+                "mistakes": sum(1 for m in user_moves if m["phase"] == ph and m["class"] == "mistake"),
+            }
+            for ph in ("opening", "middlegame", "endgame")
+        },
+        "worst_moves": worst,
+        "key_moments": scoring.key_moments(user_moves),
+        "moves": [{k: m[k] for k in ("ply", "san", "class", "best", "brilliant", "great", "book", "accuracy")} for m in user_moves],
+        "evals": evals,
+        "best_moves": best_moves,
+    }
+
+
+def review_moves(record):
+    """Player moves with the same flags as the full grading timeline, when available."""
+    timeline = record.get('move_grades') or []
+    return [{**m, **(timeline[m['ply'] - 1] if 0 < m['ply'] <= len(timeline) else {})}
+            for m in record.get('moves') or []]
+
+
+def _latest(rows) -> dict:
+    """One record per game id, preferring the current scoring version, then the latest written."""
+    records = {}
+    for rec in rows:
+        if not isinstance(rec, dict) or "id" not in rec:
+            continue
+        gid = rec["id"]
+        old = records.get(gid)
+        if old is None or rec.get("scoring_version") == SCORING_VERSION or old.get("scoring_version") != SCORING_VERSION:
+            records[gid] = rec
+    return records
+
+
+def latest(analysis_file: Path = ANALYSIS_FILE) -> dict:
+    """The analysis records by game id (see _latest), without changing the file. Shared: read-only."""
+    return jsonio.cached(Path(analysis_file), _latest_in)
+
+
+def _latest_in(path):
+    return _latest(jsonio.read_jsonl(path))
+
+
+def compact(analysis_file: Path = ANALYSIS_FILE) -> dict:
+    """Rewrite the analysis file with one record per game (see _latest), in one atomic step and
+    never while this process appends to it. Returns the records by id."""
+    analysis_file = Path(analysis_file)
+    with ANALYSIS_LOCK:
+        if not analysis_file.exists():
+            return {}
+        lines, rows = 0, []
+        with analysis_file.open(encoding="utf-8") as f:
+            for line in f:
+                lines += 1
+                try:
+                    rows.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+        records = _latest(rows)
+        if lines != len(records):
+            try:
+                jsonio.write_atomic(analysis_file, "".join(json.dumps(r) + "\n" for r in records.values()))
+            except OSError:  # the file stays as it is: readers already skip the duplicates
+                log.warning("Could not compact %s", analysis_file, exc_info=True)
+    return records
+
+
+def pending(games_file: Path = GAMES_FILE, analysis_file: Path = ANALYSIS_FILE):
+    """Games still to analyze (outdated records first), and how many are current. Read-only:
+    the analysis file is compacted by the analysis run, never here."""
+    records = latest(analysis_file)
+    done = {gid for gid, rec in records.items() if rec.get("scoring_version") == SCORING_VERSION}
+    outdated = set(records) - done
+    games = [rec for rec in jsonio.read_jsonl(Path(games_file))
+             if isinstance(rec, dict) and "id" in rec and rec["id"] not in done]
+    # Outdated records first, then the newest games: recent mistakes are the ones worth drilling.
+    games.sort(key=lambda r: r.get("date") or "", reverse=True)
+    games.sort(key=lambda r: r["id"] not in outdated)
+    return games, len(done), len(outdated)
+
+
+def run(games, engine_path, analysis_file: Path = ANALYSIS_FILE, depth=DEFAULT_DEPTH, threads=8,
+        progress=None, should_stop=lambda: False):
+    """Analyze `games`, appending each record as it finishes. `progress` is
+    called as progress(index, game, result_or_None, error_or_None)."""
+    engine = chess.engine.SimpleEngine.popen_uci(str(engine_path))
+    engine.configure({"Threads": threads, "Hash": 512})
+    try:
+        for i, rec in enumerate(games, 1):
+            if should_stop():
+                break
+            try:
+                result = analyze_game(engine, rec, depth)
+            except Exception as e:  # one unreadable game must not stop the run
+                if progress:
+                    progress(i, rec, None, e)
+                continue
+            # Opened per record, so compact() can replace the file between two of them.
+            with ANALYSIS_LOCK, Path(analysis_file).open("a", encoding="utf-8") as out:
+                out.write(json.dumps(result) + "\n")
+            if progress:
+                progress(i, rec, result, None)
+    finally:
+        engine.quit()
+        compact(analysis_file)
+
+
+def analyze_archive(games, engine_path, games_file, analysis_file, pack_file, *, depth=DEFAULT_DEPTH, threads=8,
+                    batch=None, mine=True, progress=None, mine_progress=None, on_mine=None, should_stop=lambda: False):
+    """Analyze `games` (pending()'s list), then mine the new analyses into the "From your games"
+    puzzles in `pack_file` (my_puzzles.py). Returns (pack, games mined), the pack being None
+    when nothing was mined.
+
+    With `batch`, mining follows every `batch` games, so a long run stopped halfway already feeds
+    the puzzles and drills. Each engine takes up to `threads` from engines.POOL.budget.
+    progress(index, game, result, error) follows each game and mine_progress (my_puzzles.run's)
+    each mined one. on_mine('start', None) comes before each mining pass, then
+    on_mine('done', (pack, mined)) or on_mine('failed', exc): a failed pass is then reported
+    and the run goes on; without on_mine it is raised.
+    """
+    from torre.learning import my_puzzles  # it imports this module
+    batch = batch or len(games) or 1
+    pack, total = None, 0
+    for start in range(0, max(len(games), 1), batch):
+        chunk = games[start:start + batch]
+        if chunk:
+            with engines.POOL.budget.reserve(threads) as granted:
+                run(chunk, engine_path, analysis_file, depth=depth, threads=granted, should_stop=should_stop,
+                    progress=progress and (lambda i, *rest, at=start: progress(at + i, *rest)))
+        if mine:
+            if on_mine:
+                on_mine('start', None)
+            try:
+                with engines.POOL.budget.reserve(threads) as granted:
+                    pack, mined = my_puzzles.run(games_file, analysis_file, pack_file=pack_file, engine_path=engine_path,
+                                                 threads=granted, progress=mine_progress)
+            except Exception as exc:  # a failed mine never hides the analysis itself
+                if not on_mine:
+                    raise
+                on_mine('failed', exc)
+            else:
+                total += mined
+                if on_mine:
+                    on_mine('done', (pack, mined))
+        if should_stop():
+            break
+    return pack, total
+
+
+def main(argv=None):
+    from torre import cli as torre
+    return torre.main(['analyze', *(sys.argv[1:] if argv is None else argv)])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

torre/analysis/board_view.py

@@ -0,0 +1,195 @@
+"""Boards as the app sees them: a position from a start and a move list, what the board page
+draws for it (state), and games read from PGN."""
+import io
+
+import chess
+import chess.pgn
+
+from torre.analysis import opening_book
+from torre.server.routes import BadRequest
+
+
+def moves_of(payload):
+    """The request's "moves": a list of UCI strings (none when absent)."""
+    moves = payload.get('moves', [])
+    if not isinstance(moves, list) or not all(isinstance(uci, str) for uci in moves):
+        raise BadRequest('"moves" must be a list of moves.')
+    return moves
+
+
+def position(payload):
+    fen = payload.get('initialFen') or chess.STARTING_FEN
+    if not isinstance(fen, str):
+        raise BadRequest('This position is not a valid chess position.')
+    board = chess.Board(fen)
+    if not board.is_valid():
+        raise ValueError('This position is not a valid chess position.')
+    for uci in moves_of(payload):
+        move = chess.Move.from_uci(uci)
+        if move not in board.legal_moves:
+            raise ValueError('The move history contains an illegal move.')
+        board.push(move)
+    return board
+
+
+def line_sans(payload):
+    """SAN for a line of UCI moves, cut at the first illegal one (with an error)."""
+    board = position({'initialFen': payload.get('initialFen')})
+    moves = []
+    for uci in moves_of(payload):
+        try:
+            move = chess.Move.from_uci(uci)
+        except (ValueError, TypeError):
+            move = None
+        if move is None or move not in board.legal_moves:
+            return {'moves': moves, 'error': 'This line contains an illegal move. It was cut at the last legal one.'}
+        moves.append({'uci': move.uci(), 'san': board.san(move)})
+        board.push(move)
+    return {'moves': moves}
+
+
+def illegal_reason(board, from_square, to_square):
+    """Why the side to move cannot play from `from_square` to `to_square`, as a rule a learner can
+    read: (reason, details) or None when the move is legal or there is nothing to explain (an empty
+    square, the other side's piece, or the mover's own piece in the way, which selects it instead).
+
+    Reasons: pinned (the piece shields its king from `attacker`), inCheck (the king is in check from
+    `attacker` and this does not answer it), kingAttacked (the king would step onto a square
+    `attacker` covers), exposesKing (it would uncover the king to `attacker`), castleInCheck,
+    castleThroughCheck, castleRights, castleBlocked, pathBlocked (`blocker` stands in the way),
+    pawnForward (pawns capture diagonally, never straight ahead), pawnDiagonal (a pawn moves
+    diagonally only to capture), pawnDouble (two squares only from the starting rank), movement
+    (that piece never moves that way)."""
+    piece = board.piece_at(from_square)
+    if piece is None or piece.color != board.turn:
+        return None
+    target = board.piece_at(to_square)
+    if target is not None and target.color == board.turn:
+        return None
+    king = board.king(board.turn)
+    name = chess.piece_name(piece.piece_type)
+    moves = [m for m in (chess.Move(from_square, to_square, promotion=p) for p in (None, chess.QUEEN)) if board.is_pseudo_legal(m)]
+    if any(board.is_legal(m) for m in moves) or (board.piece_type_at(from_square) == chess.KING and any(
+            m.from_square == from_square and m.to_square == to_square for m in board.generate_castling_moves())):
+        return None
+    castle = piece.piece_type == chess.KING and chess.square_rank(from_square) == chess.square_rank(to_square) \
+        and abs(chess.square_file(from_square) - chess.square_file(to_square)) == 2
+    if castle:
+        rook_file = 7 if chess.square_file(to_square) > chess.square_file(from_square) else 0
+        rook = chess.square(rook_file, chess.square_rank(from_square))
+        if not board.has_castling_rights(board.turn) or not (board.castling_rights & chess.BB_SQUARES[rook]):
+            return 'castleRights', {}
+        if board.is_check():
+            return 'castleInCheck', {}
+        step = 1 if rook_file == 7 else -1
+        between = range(chess.square_file(from_square) + step, rook_file, step)
+        if any(board.piece_at(chess.square(f, chess.square_rank(from_square))) for f in between):
+            return 'castleBlocked', {}
+        return 'castleThroughCheck', {}
+    if moves:
+        move = moves[0]
+        after = board.copy(stack=False)
+        after.push(move)
+        king_after = after.king(board.turn)
+        attackers = sorted(after.attackers(not board.turn, king_after))
+        attacker = {'attacker': chess.square_name(attackers[0])} if attackers else {}
+        if piece.piece_type == chess.KING:
+            return 'kingAttacked', attacker
+        if board.is_check():
+            return 'inCheck', {'attacker': chess.square_name(sorted(board.checkers())[0])}
+        if board.is_pinned(board.turn, from_square):
+            return 'pinned', {'piece': name, **attacker}
+        return 'exposesKing', attacker
+    if piece.piece_type == chess.PAWN:
+        forward = 8 if board.turn == chess.WHITE else -8
+        start_rank = 1 if board.turn == chess.WHITE else 6
+        files = chess.square_file(to_square) - chess.square_file(from_square)
+        if files == 0 and to_square - from_square in (forward, 2 * forward):
+            if to_square - from_square == 2 * forward and chess.square_rank(from_square) != start_rank:
+                return 'pawnDouble', {}
+            return 'pawnForward', {}
+        if abs(files) == 1 and to_square - from_square in (forward - 1, forward + 1):
+            return 'pawnDiagonal', {}
+        return 'movement', {'piece': name}
+    # A slider aimed along its own line, with something between.
+    if piece.piece_type in (chess.BISHOP, chess.ROOK, chess.QUEEN) and to_square in chess.SquareSet(chess.BB_RAYS[from_square][to_square]):
+        diagonal = chess.square_file(from_square) != chess.square_file(to_square) and chess.square_rank(from_square) != chess.square_rank(to_square)
+        fits = piece.piece_type == chess.QUEEN or (piece.piece_type == chess.BISHOP) == diagonal
+        between = chess.SquareSet(chess.between(from_square, to_square)) & board.occupied
+        if fits and between:
+            return 'pathBlocked', {'piece': name, 'blocker': chess.square_name(min(between, key=lambda s: chess.square_distance(s, from_square)))}
+    return 'movement', {'piece': name}
+
+
+def board_guidance(board):
+    """Attacks describe control; planning paths also respect blockers and king safety."""
+    plans = {}
+    for color in (chess.WHITE, chess.BLACK):
+        hypothetical = board.copy(stack=False)
+        hypothetical.turn = color
+        if color != board.turn:
+            hypothetical.ep_square = None
+        for move in hypothetical.legal_moves:
+            target = hypothetical.piece_at(move.to_square)
+            if target and target.piece_type == chess.KING:
+                continue
+            origin = chess.square_name(move.from_square)
+            destination = chess.square_name(move.to_square)
+            if destination not in plans.setdefault(origin, []):
+                plans[origin].append(destination)
+    control = {chess.square_name(square): {
+        'white': [chess.square_name(s) for s in board.attackers(chess.WHITE, square)],
+        'black': [chess.square_name(s) for s in board.attackers(chess.BLACK, square)],
+    } for square in chess.SQUARES}
+    return {'plans': plans, 'control': control}
+
+
+def state(board):
+    outcome = board.outcome(claim_draw=True)
+    return {
+        **board_guidance(board),
+        'fen': board.fen(), 'turn': 'white' if board.turn else 'black',
+        'pieces': {chess.square_name(s): p.symbol() for s, p in board.piece_map().items()},
+        'legal': [m.uci() for m in board.legal_moves],
+        'check': chess.square_name(board.king(board.turn)) if board.is_check() else None,
+        'result': outcome.result() if outcome else None,
+        'termination': outcome.termination.name.replace('_', ' ').lower() if outcome else None,
+    }
+
+
+def parse_pgn(pgn):
+    if not isinstance(pgn, str) or not pgn.strip():
+        raise ValueError('Paste a PGN game to import.')
+    game = chess.pgn.read_game(io.StringIO(pgn))
+    if game is None or game.errors:
+        raise ValueError('Could not read this PGN. Check the headers and move notation.')
+    board = game.board()
+    initial = board.fen()
+    if not board.is_valid():
+        raise ValueError('The PGN starts from an invalid position.')
+    moves = []
+    for node in game.mainline():
+        move, clock = node.move, node.clock()
+        moves.append({'uci': move.uci(), 'san': board.san(move), **({'clock': round(clock, 1)} if clock is not None else {})})
+        board.push(move)
+    if not moves and not pgn.lstrip().startswith('['):
+        raise ValueError('No chess moves were found. Paste PGN headers and move notation.')
+    return {'initialFen': initial, 'moves': moves, 'headers': dict(game.headers), 'opening': opening_book.recognize(game)}
+
+
+def with_clocks(detail, record):
+    """Clocks for a game whose PGN has none, from the chess.com timestamps saved with it (tenths of a
+    second left after each move, from the extension export and the callback API)."""
+    stamps, moves = record.get('move_timestamps'), detail['moves']
+    if isinstance(stamps, str):  # the callback API sends "5991,5980,...", the extension a list
+        try:
+            stamps = [float(stamp) for stamp in stamps.split(',')]
+        except ValueError:
+            return detail
+    # Live games carry one more value than moves, after the last: each move's clock is still in order.
+    if not isinstance(stamps, list) or len(stamps) not in (len(moves), len(moves) + 1) or any('clock' in move for move in moves):
+        return detail
+    stamps = stamps[:len(moves)]
+    if not all(isinstance(stamp, (int, float)) and stamp >= 0 for stamp in stamps):
+        return detail
+    return {**detail, 'moves': [{**move, 'clock': round(stamp / 10, 1)} for move, stamp in zip(moves, stamps)]}

torre/analysis/bot_report.py

@@ -0,0 +1,79 @@
+"""How a game against a bot was really played, phase by phase: the after-game card that shows
+whether the bot kept to the strength it was set to.
+
+A bot plays every move at the rating it was given (one rating, or one per phase; see
+api_board._phase_elo), and weak bots now and then play a deliberate weaker move (a "slip",
+engines.strength_options). Neither changes during a game on its own. This module puts numbers
+on that, from the engine's review of the finished game:
+
+    phases   accuracy and errors for you and the bot in the opening, middlegame and endgame
+             (game_stats.position_phase; Lichess accuracy, game_stats.aggregate_accuracy)
+    slips    the bot's deliberate weaker moves and how each turned out: one can land on a
+             good move by chance, which is why a weak bot sometimes looks strong
+    ratings  the rating the bot was set to in each phase it played
+    retry    your costliest mistake, with the position before it, to play again from there
+
+All evals are White-POV [cp, mate] pairs, one per position (the start and after every move).
+"""
+import chess
+
+from torre.analysis import game_stats
+from torre.analysis import scoring
+SIDES = ('you', 'bot')
+
+
+def _pair(ev):
+    """An engine_lines entry or a [cp, mate] pair as (cp, mate), mate taking the place of cp."""
+    if isinstance(ev, dict):
+        return (None, ev['mate']) if ev.get('mate') is not None else (ev.get('cp'), None)
+    return tuple(ev)
+
+
+def report(initial_fen, ucis, player_color, evals, notes=()):
+    """The card for a finished game. `evals` holds len(ucis) + 1 White-POV evals; `notes` the
+    bot's own record of its moves ({ply, slip, elo}), as the play page saved them."""
+    board = chess.Board(initial_fen)
+    evals = [_pair(ev) for ev in evals]
+    if len(evals) != len(ucis) + 1:
+        raise ValueError('The review does not cover the whole game.')
+    you = chess.WHITE if player_color == 'white' else chess.BLACK
+    win = [game_stats.win_pct(*ev) for ev in evals]
+    weights = game_stats.volatility_weights(win)
+    by_ply = {n['ply']: n for n in notes if isinstance(n, dict) and isinstance(n.get('ply'), int)}
+    rows = {phase: {side: [] for side in SIDES} for phase in game_stats.PHASES}
+    slips, ratings, phase, worst = [], {}, None, None
+    for i, uci in enumerate(ucis):
+        move = chess.Move.from_uci(uci)
+        phase = game_stats.position_phase(board, phase)
+        mover = board.turn
+        side = 'you' if mover == you else 'bot'
+        before, after = (win[i], win[i + 1]) if mover == chess.WHITE else (100 - win[i], 100 - win[i + 1])
+        judged = scoring.judge(evals[i], evals[i + 1], mover == chess.WHITE)
+        rows[phase][side].append({'accuracy': game_stats.move_accuracy(before, after), 'weight': weights[i], 'class': judged})
+        if side == 'you' and judged in ('mistake', 'blunder') and (worst is None or before - after > worst['drop']):
+            worst = {'ply': i + 1, 'san': board.san(move), 'class': judged, 'fen': board.fen(), 'drop': before - after}
+        note = by_ply.get(i + 1)
+        if side == 'bot' and note:
+            if isinstance(note.get('elo'), int):
+                ratings.setdefault(phase, set()).add(note['elo'])
+            if note.get('slip'):
+                slips.append({'ply': i + 1, 'san': board.san(move), 'phase': phase, 'class': judged})
+        board.push(move)
+
+    def summary(moves):
+        if not moves:
+            return None
+        accuracy = game_stats.aggregate_accuracy([(m['accuracy'], m['weight']) for m in moves])
+        return {'moves': len(moves), 'accuracy': round(accuracy, 1),
+                **{e: sum(m['class'] == e for m in moves) for e in game_stats.ERRORS}}
+
+    overall = {side: summary([m for phase in game_stats.PHASES for m in rows[phase][side]]) for side in SIDES}
+    return {
+        'phases': {phase: {side: summary(rows[phase][side]) for side in SIDES} for phase in game_stats.PHASES},
+        'overall': overall,
+        'slips': slips,
+        # A slip that came out fine (no error by the judgment rules) is luck, not a stronger bot.
+        'luckySlips': sum(1 for s in slips if s['class'] is None),
+        'ratings': {phase: sorted(values) for phase, values in ratings.items()},
+        'retry': {k: v for k, v in worst.items() if k != 'drop'} if worst else None,
+    }