Step 3: Lichess and chess.com player lookup

lookup/lichess.py: name search via autocomplete API, profile fetch,
game retrieval as ndjson or PGN (classical/rapid/blitz, configurable).

lookup/chesscom.py: profile + stats fetch, monthly game archive
retrieval as JSON or PGN, username guesser that derives candidates
from 'Last, First' or 'First Last' format and tries each against
the API until one resolves.

26 new tests covering profile slimming, search, game parsing, username
guessing, month generation, HTTP error handling, and find_profile fallback.
All HTTP calls mocked — no network required.

README updated with Step 3 usage docs and Python API examples.

https://claude.ai/code/session_01VQfqug9MDEyRFydkmES4n2

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

Author: jlhe97

README.md

@@ -134,10 +134,61 @@ for game in games:
     print(game["pgn"])
 ```
 
+## Step 3 — Online profile lookup (Lichess & chess.com)
+
+Given a player name from the tournament entry list, find their online profiles and fetch recent games.
+
+### Lichess
+
+```bash
+# Search by name → candidate usernames
+python -m lookup.lichess search "Magnus Carlsen"
+
+# Fetch profile by known username
+python -m lookup.lichess profile DrNykterstein
+
+# Fetch recent games (PGN or JSON)
+python -m lookup.lichess games DrNykterstein
+python -m lookup.lichess games DrNykterstein --max 20 --output json
+python -m lookup.lichess games DrNykterstein --perf classical
+```
+
+### chess.com
+
+chess.com has no public search endpoint. Use `find` to try common username
+patterns derived from the player name, or `profile` if the username is known.
+
+```bash
+# Guess username from name and try each candidate
+python -m lookup.chesscom find "Carlsen, Magnus"
+
+# Fetch profile by known username
+python -m lookup.chesscom profile MagnusCarlsen
+
+# Fetch recent games (last 3 months by default)
+python -m lookup.chesscom games MagnusCarlsen
+python -m lookup.chesscom games MagnusCarlsen --months 6 --output json
+```
+
+### Python API
+
+```python
+from lookup.lichess import search, get_games
+from lookup.chesscom import find_profile, games_as_pgn
+
+# Lichess
+candidates = search("Smith, John")  # returns list of profile dicts
+pgn = get_games("username", max=50)
+
+# chess.com
+profile = find_profile("Smith, John")  # tries username guesses, returns first match
+pgn = games_as_pgn("username", months=3)
+```
+
 ## Roadmap
 
 - [x] Step 1 — Scrape tournament entry lists (kingregistration, chessaction)
 - [x] Step 2 — Index ChessBase MegaDatabase for fast player lookups
-- [ ] Step 3 — Look up each player on USCF / chess.com / Lichess
+- [x] Step 3 — Look up each player on Lichess and chess.com
 - [ ] Step 4 — Analyse openings and tendencies
 - [ ] Step 5 — Generate per-opponent dossier report

lookup/__init__.py

@@ -0,0 +1,177 @@
+"""
+chess.com player lookup and game retrieval.
+
+chess.com has no public search endpoint — a username must be known.
+Use `guess_usernames(name)` to generate common patterns to try.
+
+Usage:
+  python -m lookup.chesscom profile Magnus_Carlsen
+  python -m lookup.chesscom games Magnus_Carlsen
+  python -m lookup.chesscom games Magnus_Carlsen --months 3 --output json
+
+API used (no auth required):
+  https://api.chess.com/pub/player/{username}               — profile
+  https://api.chess.com/pub/player/{username}/stats         — ratings
+  https://api.chess.com/pub/player/{username}/games/{y}/{m} — monthly archives
+"""
+
+import sys
+import json
+import argparse
+import calendar
+from datetime import date, timedelta
+
+import requests
+
+_BASE = "https://api.chess.com/pub"
+_HEADERS = {
+    "User-Agent": "chess-dossier-builder/1.0",
+}
+
+
+def _get(url: str) -> requests.Response:
+    resp = requests.get(url, headers=_HEADERS, timeout=15)
+    resp.raise_for_status()
+    return resp
+
+
+def guess_usernames(name: str) -> list[str]:
+    """
+    Generate plausible chess.com usernames from a 'Last, First' or 'First Last' name.
+    Returns candidates ordered by likelihood — caller should try each with get_profile().
+    """
+    name = name.strip()
+    if "," in name:
+        last, _, first = name.partition(",")
+        last, first = last.strip(), first.strip()
+    else:
+        parts = name.split()
+        first, last = parts[0], parts[-1]
+
+    f, l = first.lower(), last.lower()
+    return [
+        f"{f}{l}", f"{l}{f}", f"{f}_{l}", f"{l}_{f}",
+        f"{f[0]}{l}", f"{l}{f[0]}", f"{f}.{l}",
+        f"{f}", f"{l}",
+    ]
+
+
+def get_profile(username: str) -> dict:
+    """Fetch profile and ratings for a chess.com username. Raises on 404."""
+    profile = _get(f"{_BASE}/player/{username}").json()
+    try:
+        stats = _get(f"{_BASE}/player/{username}/stats").json()
+    except requests.HTTPError:
+        stats = {}
+
+    return _slim_profile(username, profile, stats)
+
+
+def find_profile(name: str) -> dict | None:
+    """
+    Try guessed usernames until one resolves. Returns first match or None.
+    """
+    for username in guess_usernames(name):
+        try:
+            return get_profile(username)
+        except requests.HTTPError:
+            continue
+    return None
+
+
+def get_games(username: str, months: int = 3) -> list[dict]:
+    """
+    Fetch games from the last `months` monthly archives.
+    Returns a flat list of game dicts (chess.com native format).
+    """
+    games = []
+    for year, month in _recent_months(months):
+        try:
+            data = _get(f"{_BASE}/player/{username}/games/{year}/{month:02d}").json()
+            games.extend(data.get("games", []))
+        except requests.HTTPError:
+            continue
+    return games
+
+
+def games_as_pgn(username: str, months: int = 3) -> str:
+    """Fetch games from recent archives and return as a single PGN string."""
+    pgns = []
+    for year, month in _recent_months(months):
+        try:
+            data = _get(f"{_BASE}/player/{username}/games/{year}/{month:02d}/pgn").text
+            pgns.append(data)
+        except requests.HTTPError:
+            continue
+    return "\n\n".join(pgns)
+
+
+def _recent_months(n: int) -> list[tuple[int, int]]:
+    months = []
+    d = date.today().replace(day=1)
+    for _ in range(n):
+        months.append((d.year, d.month))
+        d = (d - timedelta(days=1)).replace(day=1)
+    return months
+
+
+def _slim_profile(username: str, profile: dict, stats: dict) -> dict:
+    ratings = {}
+    for key, label in (
+        ("chess_classical", "classical"),
+        ("chess_rapid", "rapid"),
+        ("chess_blitz", "blitz"),
+        ("chess_bullet", "bullet"),
+    ):
+        if key in stats and "last" in stats[key]:
+            ratings[label] = stats[key]["last"]["rating"]
+
+    return {
+        "username": username,
+        "display_name": profile.get("name") or profile.get("username", username),
+        "title": profile.get("title"),
+        "ratings": ratings,
+        "url": profile.get("url", f"https://www.chess.com/member/{username}"),
+        "country": profile.get("country", "").split("/")[-1],
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="chess.com player lookup.")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_profile = sub.add_parser("profile", help="Fetch profile by username")
+    p_profile.add_argument("username")
+
+    p_find = sub.add_parser("find", help="Guess username from a player name")
+    p_find.add_argument("name", help="Player name e.g. 'Carlsen, Magnus'")
+
+    p_games = sub.add_parser("games", help="Fetch recent games by username")
+    p_games.add_argument("username")
+    p_games.add_argument("--months", type=int, default=3)
+    p_games.add_argument("--output", choices=["json", "pgn"], default="pgn")
+
+    args = parser.parse_args()
+
+    if args.cmd == "profile":
+        print(json.dumps(get_profile(args.username), indent=2))
+
+    elif args.cmd == "find":
+        result = find_profile(args.name)
+        if result:
+            print(json.dumps(result, indent=2))
+        else:
+            print(f"No chess.com profile found for '{args.name}'.", file=sys.stderr)
+            sys.exit(1)
+
+    elif args.cmd == "games":
+        if args.output == "pgn":
+            print(games_as_pgn(args.username, months=args.months))
+        else:
+            games = get_games(args.username, months=args.months)
+            print(f"Fetched {len(games)} game(s).", file=sys.stderr)
+            print(json.dumps(games, indent=2))
+
+
+if __name__ == "__main__":
+    main()

lookup/chesscom.py

@@ -0,0 +1,143 @@
+"""
+Lichess player lookup and game retrieval.
+
+Usage:
+  python -m lookup.lichess search "Magnus Carlsen"
+  python -m lookup.lichess profile thibault
+  python -m lookup.lichess games thibault
+  python -m lookup.lichess games thibault --max 20 --output json
+
+API used (no auth required):
+  https://lichess.org/api/users/autocomplete  — name → username candidates
+  https://lichess.org/api/user/{username}     — profile + ratings
+  https://lichess.org/api/games/user/{username} — PGN/ndjson game stream
+"""
+
+import sys
+import json
+import argparse
+import time
+
+import requests
+
+_BASE = "https://lichess.org/api"
+_HEADERS = {
+    "User-Agent": "chess-dossier-builder/1.0",
+    "Accept": "application/json",
+}
+_RATE_DELAY = 1.0  # seconds between requests to stay within rate limits
+
+
+def _get(path: str, params: dict | None = None, accept: str = "application/json") -> requests.Response:
+    headers = {**_HEADERS, "Accept": accept}
+    resp = requests.get(f"{_BASE}{path}", headers=headers, params=params, timeout=15)
+    resp.raise_for_status()
+    return resp
+
+
+def search(name: str, max_results: int = 5) -> list[dict]:
+    """
+    Search for Lichess users by display name or username.
+    Returns a list of candidate profiles (id, username, title, ratings).
+    """
+    resp = _get("/users/autocomplete", params={"term": name, "object": "true"})
+    data = resp.json()
+    users = data if isinstance(data, list) else data.get("result", [])
+    return [_slim_profile(u) for u in users[:max_results]]
+
+
+def get_profile(username: str) -> dict:
+    """Fetch full profile for a known username."""
+    resp = _get(f"/user/{username}")
+    return _slim_profile(resp.json())
+
+
+def get_games(username: str, max: int = 50,
+              perf_types: str = "classical,rapid,blitz") -> list[dict]:
+    """
+    Fetch up to `max` recent games for a Lichess user.
+    Returns a list of dicts with PGN and metadata.
+    """
+    time.sleep(_RATE_DELAY)
+    resp = requests.get(
+        f"{_BASE}/games/user/{username}",
+        headers={**_HEADERS, "Accept": "application/x-ndjson"},
+        params={"max": max, "perfType": perf_types, "clocks": "false", "evals": "false"},
+        timeout=30,
+        stream=True,
+    )
+    resp.raise_for_status()
+
+    games = []
+    for line in resp.iter_lines():
+        if line:
+            games.append(json.loads(line))
+    return games
+
+
+def games_as_pgn(username: str, max: int = 50,
+                 perf_types: str = "classical,rapid,blitz") -> str:
+    """Fetch games and return as a single PGN string."""
+    time.sleep(_RATE_DELAY)
+    resp = requests.get(
+        f"{_BASE}/games/user/{username}",
+        headers={**_HEADERS, "Accept": "application/x-chess-pgn"},
+        params={"max": max, "perfType": perf_types, "clocks": "false", "evals": "false"},
+        timeout=30,
+    )
+    resp.raise_for_status()
+    return resp.text
+
+
+def _slim_profile(data: dict) -> dict:
+    perfs = data.get("perfs", {})
+    return {
+        "username": data.get("id") or data.get("username", ""),
+        "display_name": data.get("username", ""),
+        "title": data.get("title"),
+        "ratings": {
+            k: perfs[k]["rating"]
+            for k in ("classical", "rapid", "blitz", "bullet")
+            if k in perfs and "rating" in perfs[k]
+        },
+        "url": f"https://lichess.org/@/{data.get('id') or data.get('username', '')}",
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Lichess player lookup.")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_search = sub.add_parser("search", help="Search users by name")
+    p_search.add_argument("name")
+    p_search.add_argument("--max", type=int, default=5)
+
+    p_profile = sub.add_parser("profile", help="Fetch profile by username")
+    p_profile.add_argument("username")
+
+    p_games = sub.add_parser("games", help="Fetch recent games by username")
+    p_games.add_argument("username")
+    p_games.add_argument("--max", type=int, default=50)
+    p_games.add_argument("--output", choices=["json", "pgn"], default="pgn")
+    p_games.add_argument("--perf", default="classical,rapid,blitz")
+
+    args = parser.parse_args()
+
+    if args.cmd == "search":
+        results = search(args.name, max_results=args.max)
+        print(json.dumps(results, indent=2))
+
+    elif args.cmd == "profile":
+        print(json.dumps(get_profile(args.username), indent=2))
+
+    elif args.cmd == "games":
+        if args.output == "pgn":
+            print(games_as_pgn(args.username, max=args.max, perf_types=args.perf))
+        else:
+            games = get_games(args.username, max=args.max, perf_types=args.perf)
+            print(f"Fetched {len(games)} game(s).", file=sys.stderr)
+            print(json.dumps(games, indent=2))
+
+
+if __name__ == "__main__":
+    main()