Files

T

Eric Wagoner 2109e3544a Resolve stage: matching, version resolution, fixtures; BGG API auth

bggpipe resolve works end to end: search -> exact/fuzzy candidate
scoring -> auto/ambiguous/unmatched classification with owned-count
tie-breaks (mixed base/expansion candidates never auto-match), version
scoring from edition cues (never guessed; no cues -> version_unknown),
idempotent matches.csv appends.

Discovered mid-build: BGG now requires registered-application Bearer
tokens on the XML API (2025 policy change) and returns 401 otherwise.
Client sends Authorization from BGG_API_TOKEN and raises an actionable
BGGAuthError; CLAUDE.md and the bgg-api skill are updated to match.
Live fixture recording is blocked until registration is approved, so
tests replay hand-crafted stub fixtures via a network-refusing
transport; scripts/record_fixtures.py re-records real XML under the
same cache keys once a token exists. One live read-only smoke test is
skipped unless --run-live.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-08-01 12:33:32 -04:00

3.0 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

bggpipe — a resumable, idempotent CLI pipeline: shelf photos → Claude vision title + edition-cue extraction → BoardGameGeek ID and version matching → human review → collection diff → upload to BGG via Playwright → metadata enrichment (games.json). Full design: @bgg-shelf-pipeline-spec.md. The repo is greenfield — no code exists yet. Follow the spec's "Suggested Build Order" when scaffolding; re-run /init once code exists.

Stack (decided, not yet scaffolded)

Python 3.12+, deps via uv (uv add, uv run), CLI framework typer, tests pytest, lint/format ruff.
Browser automation: Playwright (not Selenium). Needs uv run playwright install chromium after install.
Vision: Anthropic API, latest Sonnet model.

Hard rules (from spec — never violate)

≤1 request every 2 seconds to any BGG endpoint; jittered backoff on 429/503. Upload stage: 2–4 s randomized delay between games.
Credentials never touch disk or logs. ANTHROPIC_API_KEY, BGG_USERNAME, BGG_PASSWORD, BGG_API_TOKEN come from env vars only. Playwright storage state is credential-adjacent — keep it gitignored.
The XML API requires a registered app token (Authorization: Bearer, from BGG_API_TOKEN) — unregistered requests get 401. Until Eric's registration at boardgamegeek.com/applications is approved, tests run on the stub fixtures in tests/fixtures/bgg_cache/; re-record them with scripts/record_fixtures.py once the token exists.
Every stage is idempotent and resumable — killing mid-run and restarting must lose no work; re-runs skip already-processed items.
Use only the XML API2 and the public website — no undocumented BGG endpoints (BGG tightened access policies in 2025).
BGG has no write API: writes drive the real website with a logged-in Playwright session.

Domain gotchas

Base game vs. expansion vs. new edition is the top failure mode — bias matching toward ambiguous over auto-match ("Wingspan Europe" must not match base Wingspan).
Editions/versions matter: Eric owns multiple editions of some games — each is a separate collection entry (keyed by collid on BGG). Never guess a version: no legible cues → version_unknown and a version-less collection entry.
Normalize titles (casefold, strip punctuation/articles, special chars like é/&/:) identically on both sides of a match; dedupe across photos but keep source_photos provenance.
Detailed BGG API behavior (202 queueing, collection-endpoint quirks, endpoints): use the bgg-api skill. If the spec's BGG behavior changes, update the bgg-api skill to match — they must not drift.

Git

Remote is self-hosted Gitea 1.26 (git.kestrelsnest.social), not GitHub — gh CLI does not work here.
Commit data/matches.csv, data/to_add.csv, data/upload_log.csv, data/titles.json, data/games.json. Never commit data/bgg_cache/, photos/, Playwright storage state, or .env.

3.0 KiB Raw Blame History Unescape Escape