eric/bggpipe
1
0
Fork 0
Code Issues Pull Requests Releases 2 Activity

Quick start finishes the move off git clone; Windows stops being banned

Browse Source 
Eric caught two leftovers. The Quick start still opened with git clone
— the exact path the last commit built two warning layers against —
and now leads with uv tool install into a directory of your own, with
the stage commands dropping their uv run prefix to match (the clone
recipe moves to Development, its one remaining legitimate home, with
a pointer to run real pipelines elsewhere).

And the requirements line claimed macOS or Linux. Nothing in the code
is platform-specific — pure Python, pathlib throughout, and uv,
FastAPI, and Playwright all support Windows — so the honest statement
is: Windows works but is untested, with one real caveat named in
place: the owner-only chmod on .env and browser session state is
POSIX-only, so Windows users keep those files in an account-protected
directory.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016jXZFSTZQKzAC8fqpWSz9g
This commit is contained in:
Eric Wagoner
2026-08-06 00:54:10 -04:00
co-authored by Claude Fable 5
parent 53ebb15840
commit 52fb52ea3b
1 changed files with 26 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+26 -27
View File
@@ -73,20 +73,21 @@ Every stage is idempotent and resumable: kill it mid-run, restart, lose nothing.
## Requirements
- macOS or Linux, Python 3.12+, [uv](https://docs.astral.sh/uv/)
- Python 3.12+ and [uv](https://docs.astral.sh/uv/), on macOS, Linux, or Windows. (Development happens on macOS; Windows is untested but nothing is platform-specific. One caveat: the owner-only file permissions bggpipe sets on `.env` and browser session state are POSIX-only — on Windows, keep those files in a directory protected by your account.)
- A vision model for extraction — an [Anthropic API key](https://console.anthropic.com/) by default, or any OpenAI-compatible endpoint: OpenAI, OpenRouter, or a free local runtime like [Ollama](https://ollama.com/) with a vision-capable model. `config.toml` carries a `[vision.<provider>]` block for each; `vision_provider` picks one. Local models read spines noticeably worse than frontier ones — expect a longer proofread pass on the Titles page, not a broken pipeline.
- A BoardGameGeek account **and a registered BGG application** — as of BGG's [2025 API policy](https://boardgamegeek.com/using_the_xml_api), the XML API requires a Bearer token from a registered app. Register a free non-commercial application at [boardgamegeek.com/applications](https://boardgamegeek.com/applications) (approval can take a week or more, so **apply on day one**), then create a token. Each user needs their own; tokens must not be shared.
## Quick start
```sh
git clone https://git.kestrelsnest.social/eric/bggpipe.git
cd bggpipe
uv sync # installs Python deps
uv run bggpipe init # guided setup: folders, credentials, browser download
uv tool install git+https://git.kestrelsnest.social/eric/bggpipe
mkdir shelves && cd shelves # any directory of your own — NOT a clone of this repo
bggpipe init # guided setup: folders, credentials, browser download
```
The `init` wizard is idempotent — re-run it anytime to check status or add keys you skipped. It prompts for the credentials below (hidden input, saved to a `.env` it creates with owner-only permissions) and offers the one-time Playwright Chromium download. Prefer doing it by hand? `cp .env.example .env`, fill it in, and run `uv run playwright install chromium` yourself.
Your photos and every pipeline artifact live in the directory where you run it, and `uv tool upgrade bggpipe` picks up fixes without going anywhere near your data ([why this matters](#bring-your-own-shelves)).
The `init` wizard is idempotent — re-run it anytime to check status or add keys you skipped. It prompts for the credentials below (hidden input, saved to a `.env` it creates with owner-only permissions) and offers the one-time Playwright Chromium download. Prefer doing it by hand? Copy [.env.example](.env.example) beside your data, fill it in, and run `playwright install chromium` yourself.
Secrets live in environment variables only, never in config files, code, or logs. `.env` is gitignored. If you use [direnv](https://direnv.net/), the committed `.envrc` loads `.env` automatically after a one-time `direnv allow`; otherwise export the variables yourself (e.g. `set -a; source .env; set +a`).
@@ -100,15 +101,17 @@ Secrets live in environment variables only, never in config files, code, or logs
Non-secret knobs (`photos_dir`, `data_dir`, the per-provider vision blocks, the rate limit) live in `config.toml`. From here you can drive everything from the browser:
```sh
uv run bggpipe web # opens http://127.0.0.1:8377/ — the whole app in the browser
bggpipe web # opens http://127.0.0.1:8377/ — the whole app in the browser
```
(Working from a development clone instead? Prefix commands with `uv run`.)
### From your phone
The app is localhost-only by default. To use it from a phone or tablet on your network — proofreading from the couch, or shooting shelf photos straight into the pipeline — serve it to the LAN instead:
```sh
uv run bggpipe web --lan # localhost + your network, behind an access key
bggpipe web --lan # localhost + your network, behind an access key
```
Startup prints a pairing link (`?k=...`) and a QR code: point the phone's camera at the terminal and tap. Pairing is one-time per device — the key persists across restarts (`data/.lan_key`; delete it to revoke every paired device) and the cookie lasts a year. Save the page to the phone's home screen for the full-screen treatment, piper icon included.
@@ -118,13 +121,13 @@ To photograph shelves from the phone: on the Photos page, tap the drop zone and
Seven pages in one local app — Pipeline, Photos, Titles, Review, Queue, Library, and Help, each pictured above. The real upload sits behind a confirmation (and behind a stub-data lock if synthetic fixtures ever regenerate). Prefer the terminal? Every stage is also a command, and the two interfaces share all state:
```sh
uv run bggpipe extract # photos → titles.json (+ retake prompts)
uv run bggpipe resolve # titles → BGG ids/versions in matches.csv
uv run bggpipe review --web # review UI only
uv run bggpipe diff # compare against your BGG collection
uv run bggpipe upload --dry-run # ALWAYS inspect this first
uv run bggpipe upload --limit 1 # then one game, then small batches
uv run bggpipe enrich # full metadata → data/games.json
bggpipe extract # photos → titles.json (+ retake prompts)
bggpipe resolve # titles → BGG ids/versions in matches.csv
bggpipe review --web # review UI only
bggpipe diff # compare against your BGG collection
bggpipe upload --dry-run # ALWAYS inspect this first
bggpipe upload --limit 1 # then one game, then small batches
bggpipe enrich # full metadata → data/games.json
```
Each stage skips work it has already done; `--force`/`--refresh` flags redo it. `review` without `--web` runs in the terminal instead. `upload` also has `--retry-failed`, `--verify` (re-fetches your collection and cross-checks the log), and runs a **headed** browser by default — BGG's Cloudflare check blocks headless ones, and a first login may need one human click before the session is saved locally and reused.
@@ -143,16 +146,7 @@ Straight-on, one shelf (or part of one) per shot, close enough that spine text i
## Bring your own shelves
Install bggpipe as a tool and run it in its own directory — **not inside a clone of this repo**:
```sh
uv tool install git+https://git.kestrelsnest.social/eric/bggpipe
mkdir ~/shelves && cd ~/shelves
bggpipe init # folders, credentials, one-time browser install
bggpipe web # or run stages from the terminal
```
Everything the pipeline produces — photos, matches, review decisions, your upload log — lives in the directory where you run it. A bug fix is `uv tool upgrade bggpipe`, which by construction cannot touch your data.
The [Quick start](#quick-start) install — as a tool, run in a directory of your own — is the only supported way to use bggpipe on your collection. Everything the pipeline produces (photos, matches, review decisions, your upload log) lives where you run it, and a bug fix is `uv tool upgrade bggpipe`, which by construction cannot touch your data.
**Why not clone and run?** This repo doubles as its author's live pipeline: `data/` ships with their real artifacts, committed and updated often. Run inside a clone and *your* data lands at git-tracked paths — the next `git pull` will refuse to merge, and the usual remedies (`git reset --hard`, `git checkout .`, `git stash`, `git clean -fdx`) would destroy your review decisions, hand-written games, upload log, and photos. bggpipe detects this arrangement and warns at `init` and on the web dashboard; don't ignore it. Clone only to develop (see [Development](#development)), and keep your own pipeline runs elsewhere.
@@ -168,12 +162,17 @@ No token yet? `extract` works immediately (it only needs the Anthropic key), and
## Development
```sh
uv run pytest # offline test suite (stub fixtures, no network)
git clone https://git.kestrelsnest.social/eric/bggpipe.git
cd bggpipe
uv sync # installs Python deps
uv run pytest # offline test suite (recorded fixtures, no network)
uv run pytest --run-live # + a read-only live-API smoke test (needs token)
uv run ruff check src tests # lint
uv run bggpipe review --web --dev # review UI with code hot-reload
uv run bggpipe web --dev # the app with code hot-reload
```
Run your own *pipeline* from a different directory (see [Bring your own shelves](#bring-your-own-shelves)) — the clone's `data/` is the author's live data, and the app will warn if you point it at git-tracked paths.
The review UI live-follows the data files — run `extract` or `resolve` in another terminal and the page updates itself. Architecture and contributor guidance: [CLAUDE.md](CLAUDE.md) and the [full spec](bgg-shelf-pipeline-spec.md); BGG automation notes: [docs/bgg-upload-flow.md](docs/bgg-upload-flow.md).
## A note on being a good BGG citizen