Step 4: opening repertoire and tendency analysis

analysis/openings.py: parses PGN games, extracts first N half-moves
as the opening key, groups by colour, computes frequency and W/D/L
with win_pct per line, sorted by frequency. Configurable depth and
top-N limit.

analysis/stats.py: overall W/D/L by colour, average game length,
top opening responses vs 1.e4 and 1.d4 as Black.

Fixed "loss"+"s" → "losss" KeyError in both modules (use explicit
mapping instead of string concatenation).

32 new tests covering opening line extraction, result mapping,
repertoire analysis, stats aggregation, vs_e4/vs_d4 filtering.

README updated with Step 4 docs, example output, and Python API.

https://claude.ai/code/session_01VQfqug9MDEyRFydkmES4n2

Co-authored-by: Claude <noreply@anthropic.com>

Author: jlhe97

README.md

@@ -187,10 +187,65 @@ profile = find_profile("Smith, John")  # tries username guesses, returns first m
 pgn = games_as_pgn("username", months=3)
 ```
 
+## Step 4 — Opening and tendency analysis
+
+Given a list of PGN strings and a player name, produces a full opening
+repertoire breakdown and broad tendency statistics.
+
+### Opening repertoire
+
+```bash
+python -m analysis.openings games.pgn "Smith, John"
+python -m analysis.openings games.pgn "Smith, John" --depth 8 --top 10
+```
+
+Output (JSON):
+```json
+{
+  "as_white": [
+    {"line": "1. e4 e5 2. Nf3 Nc6 3. Bb5", "count": 18, "wins": 10, "draws": 5, "losses": 3, "win_pct": 55.6}
+  ],
+  "as_black": [
+    {"line": "1. e4 c5 2. Nf3 d6 3. d4 cxd4", "count": 12, "wins": 6, "draws": 4, "losses": 2, "win_pct": 50.0}
+  ]
+}
+```
+
+### Tendency statistics
+
+```bash
+python -m analysis.stats games.pgn "Smith, John"
+```
+
+Output (JSON):
+```json
+{
+  "total": 50,
+  "as_white": {"count": 27, "wins": 14, "draws": 8, "losses": 5, "win_pct": 51.9},
+  "as_black": {"count": 23, "wins": 10, "draws": 9, "losses": 4, "win_pct": 43.5},
+  "overall":  {"wins": 24, "draws": 17, "losses": 9, "win_pct": 48.0},
+  "avg_length": 38.4,
+  "vs_e4": [...],
+  "vs_d4": [...]
+}
+```
+
+### Python API
+
+```python
+from analysis.openings import analyse_openings
+from analysis.stats import analyse_stats
+
+pgn_strings = [game["pgn"] for game in games]  # from megabase or lookup
+
+openings = analyse_openings(pgn_strings, "Smith, John", depth=6, top=10)
+stats    = analyse_stats(pgn_strings, "Smith, John")
+```
+
 ## Roadmap
 
 - [x] Step 1 — Scrape tournament entry lists (kingregistration, chessaction)
 - [x] Step 2 — Index ChessBase MegaDatabase for fast player lookups
 - [x] Step 3 — Look up each player on Lichess and chess.com
-- [ ] Step 4 — Analyse openings and tendencies
+- [x] Step 4 — Analyse openings and tendencies
 - [ ] Step 5 — Generate per-opponent dossier report

analysis/__init__.py

@@ -0,0 +1,159 @@
+"""
+Opening repertoire analysis.
+
+Given a list of PGN strings and a player name, produces ranked opening
+lines for each colour with frequency and W/D/L breakdown.
+
+Usage:
+  python -m analysis.openings games.pgn "Smith, John"
+  python -m analysis.openings games.pgn "Smith, John" --depth 8 --top 10
+"""
+
+import io
+import sys
+import json
+import argparse
+from collections import defaultdict
+
+import chess.pgn
+
+
+def _parse_game(pgn_text: str) -> chess.pgn.Game | None:
+    try:
+        return chess.pgn.read_game(io.StringIO(pgn_text))
+    except Exception:
+        return None
+
+
+def _opening_line(game: chess.pgn.Game, depth: int) -> str:
+    """Return the first `depth` half-moves as a SAN string, e.g. '1. e4 e5 2. Nf3'."""
+    board = game.board()
+    parts = []
+    node = game
+    half = 0
+    while node.variations and half < depth:
+        node = node.variations[0]
+        move_num = board.fullmove_number
+        is_white = board.turn == chess.WHITE
+        san = board.san(node.move)
+        if is_white:
+            parts.append(f"{move_num}. {san}")
+        else:
+            parts.append(san)
+        board.push(node.move)
+        half += 1
+    return " ".join(parts)
+
+
+def _result_for_player(game: chess.pgn.Game, player: str) -> str:
+    """Return 'win', 'draw', or 'loss' from the given player's perspective."""
+    headers = game.headers
+    result = headers.get("Result", "*")
+    white = headers.get("White", "")
+    black = headers.get("Black", "")
+
+    player_l = player.lower()
+    is_white = player_l in white.lower()
+    is_black = player_l in black.lower()
+
+    if result == "1-0":
+        if is_white:   return "win"
+        if is_black:   return "loss"
+    elif result == "0-1":
+        if is_black:   return "win"
+        if is_white:   return "loss"
+    elif result in ("1/2-1/2", "½-½"):
+        return "draw"
+    return "unknown"
+
+
+def _tally(records: dict) -> dict:
+    """Sort opening records by count and compute win_pct."""
+    rows = []
+    for line, r in records.items():
+        total = r["wins"] + r["draws"] + r["losses"]
+        rows.append({
+            "line": line,
+            "count": total,
+            "wins": r["wins"],
+            "draws": r["draws"],
+            "losses": r["losses"],
+            "win_pct": round(100 * r["wins"] / total, 1) if total else 0.0,
+        })
+    return sorted(rows, key=lambda x: x["count"], reverse=True)
+
+
+def analyse_openings(pgn_strings: list[str], player: str,
+                     depth: int = 6, top: int = 0) -> dict:
+    """
+    Analyse opening repertoire for `player` across the given PGN games.
+
+    Returns:
+      {
+        "as_white": [{"line": "1. e4", "count": 30, "wins": 15, ...}, ...],
+        "as_black": [...],
+      }
+    Sorted by frequency. Pass top > 0 to limit to N lines per colour.
+    """
+    white_lines: dict[str, dict] = defaultdict(lambda: {"wins": 0, "draws": 0, "losses": 0})
+    black_lines: dict[str, dict] = defaultdict(lambda: {"wins": 0, "draws": 0, "losses": 0})
+
+    player_l = player.lower()
+
+    for pgn_text in pgn_strings:
+        game = _parse_game(pgn_text)
+        if game is None:
+            continue
+
+        headers = game.headers
+        white = headers.get("White", "").lower()
+        black = headers.get("Black", "").lower()
+
+        is_white = player_l in white
+        is_black = player_l in black
+        if not is_white and not is_black:
+            continue
+
+        line = _opening_line(game, depth)
+        result = _result_for_player(game, player)
+        if result == "unknown":
+            continue
+
+        key = {"win": "wins", "draw": "draws", "loss": "losses"}[result]
+        bucket = white_lines if is_white else black_lines
+        bucket[line][key] += 1
+
+    as_white = _tally(white_lines)
+    as_black = _tally(black_lines)
+
+    if top:
+        as_white = as_white[:top]
+        as_black = as_black[:top]
+
+    return {"as_white": as_white, "as_black": as_black}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Analyse opening repertoire from a PGN file.")
+    parser.add_argument("pgn_file", help="PGN file containing the player's games")
+    parser.add_argument("player", help="Player name to analyse")
+    parser.add_argument("--depth", type=int, default=6,
+                        help="Half-moves to use as opening key (default: 6)")
+    parser.add_argument("--top", type=int, default=10,
+                        help="Show top N openings per colour (default: 10, 0 = all)")
+    args = parser.parse_args()
+
+    with open(args.pgn_file, encoding="utf-8", errors="replace") as fh:
+        content = fh.read()
+
+    # Split multi-game PGN by blank line before each [Event tag
+    import re
+    raw_games = re.split(r"\n(?=\[)", content.strip())
+    print(f"Parsing {len(raw_games)} game(s)…", file=sys.stderr)
+
+    result = analyse_openings(raw_games, args.player, depth=args.depth, top=args.top)
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

analysis/openings.py

@@ -0,0 +1,140 @@
+"""
+Broad player tendency statistics.
+
+Usage:
+  python -m analysis.stats games.pgn "Smith, John"
+"""
+
+import io
+import sys
+import json
+import argparse
+import re
+
+import chess.pgn
+
+from analysis.openings import _parse_game, _result_for_player, analyse_openings
+
+
+def _game_length(game: chess.pgn.Game) -> int:
+    """Return the number of half-moves played."""
+    return sum(1 for _ in game.mainline_moves())
+
+
+def analyse_stats(pgn_strings: list[str], player: str) -> dict:
+    """
+    Compute broad tendencies for `player` across the given PGN games.
+
+    Returns:
+      {
+        "total": 50,
+        "as_white": {"count": 25, "wins": 12, "draws": 8, "losses": 5, "win_pct": 48.0},
+        "as_black": {"count": 25, "wins": 10, "draws":  9, "losses": 6, "win_pct": 40.0},
+        "overall":  {"wins": 22, "draws": 17, "losses": 11, "win_pct": 44.0},
+        "avg_length": 35.2,
+        "vs_e4": [...],   # top opening lines as Black vs 1. e4
+        "vs_d4": [...],   # top opening lines as Black vs 1. d4
+      }
+    """
+    player_l = player.lower()
+
+    buckets = {
+        "white": {"wins": 0, "draws": 0, "losses": 0},
+        "black": {"wins": 0, "draws": 0, "losses": 0},
+    }
+    lengths: list[int] = []
+    valid_pgns: list[str] = []
+
+    for pgn_text in pgn_strings:
+        game = _parse_game(pgn_text)
+        if game is None:
+            continue
+
+        headers = game.headers
+        white = headers.get("White", "").lower()
+        black = headers.get("Black", "").lower()
+
+        is_white = player_l in white
+        is_black = player_l in black
+        if not is_white and not is_black:
+            continue
+
+        result = _result_for_player(game, player)
+        if result == "unknown":
+            continue
+
+        key = {"win": "wins", "draw": "draws", "loss": "losses"}[result]
+        colour = "white" if is_white else "black"
+        buckets[colour][key] += 1
+        lengths.append(_game_length(game))
+        valid_pgns.append(pgn_text)
+
+    def _pct(wins, total):
+        return round(100 * wins / total, 1) if total else 0.0
+
+    w = buckets["white"]
+    b = buckets["black"]
+    white_total = w["wins"] + w["draws"] + w["losses"]
+    black_total = b["wins"] + b["draws"] + b["losses"]
+    total = white_total + black_total
+    overall_wins = w["wins"] + b["wins"]
+    overall_draws = w["draws"] + b["draws"]
+    overall_losses = w["losses"] + b["losses"]
+
+    # Black repertoire vs 1.e4 and 1.d4
+    e4_games = [p for p in valid_pgns if _first_white_move(p) == "e4"]
+    d4_games = [p for p in valid_pgns if _first_white_move(p) == "d4"]
+
+    vs_e4 = analyse_openings(e4_games, player, depth=8, top=5)["as_black"]
+    vs_d4 = analyse_openings(d4_games, player, depth=8, top=5)["as_black"]
+
+    return {
+        "total": total,
+        "as_white": {
+            "count": white_total,
+            "wins": w["wins"], "draws": w["draws"], "losses": w["losses"],
+            "win_pct": _pct(w["wins"], white_total),
+        },
+        "as_black": {
+            "count": black_total,
+            "wins": b["wins"], "draws": b["draws"], "losses": b["losses"],
+            "win_pct": _pct(b["wins"], black_total),
+        },
+        "overall": {
+            "wins": overall_wins, "draws": overall_draws, "losses": overall_losses,
+            "win_pct": _pct(overall_wins, total),
+        },
+        "avg_length": round(sum(lengths) / len(lengths), 1) if lengths else 0.0,
+        "vs_e4": vs_e4,
+        "vs_d4": vs_d4,
+    }
+
+
+def _first_white_move(pgn_text: str) -> str | None:
+    """Return the UCI destination square of White's first move (e.g. 'e4')."""
+    game = _parse_game(pgn_text)
+    if game is None:
+        return None
+    for move in game.mainline_moves():
+        return chess.square_name(move.to_square)
+    return None
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Compute player tendency stats from a PGN file.")
+    parser.add_argument("pgn_file", help="PGN file containing the player's games")
+    parser.add_argument("player", help="Player name to analyse")
+    args = parser.parse_args()
+
+    with open(args.pgn_file, encoding="utf-8", errors="replace") as fh:
+        content = fh.read()
+
+    raw_games = re.split(r"\n(?=\[)", content.strip())
+    print(f"Parsing {len(raw_games)} game(s)…", file=sys.stderr)
+
+    result = analyse_stats(raw_games, args.player)
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()