diff --git a/README.md b/README.md new file mode 100644 index 0000000..9491251 --- /dev/null +++ b/README.md @@ -0,0 +1,70 @@ +# Bookmark + +A camera-driven book intake and checkout inventory system, built for +[Books in Hand](https://git.opensourcesolarpunk.com/books-in-hand), a +nonprofit that keeps books out of landfills and in people's hands. + +Bookmark replaces manual book logging with a guided, camera-based workflow: +a volunteer places a book on a marked platform, the system photographs the +front and back, sorts it into a size category for tax/reporting purposes, +and later backfills the catalogue with title, author, and ISBN — all +running on local hardware, no cloud dependency. + +This project is fully open source and is being built and donated as +volunteer/client work — it isn't part of any commercial product line. + +## Status + +**Early / active development.** The intake station (Phase 1) is being +built now. Not yet runnable end-to-end. + +| Phase | What it does | Status | +|---|---|---| +| 1 — Intake station | Camera capture, guided front/back flow, deterministic size bucketing, CSV catalogue | In progress | +| 2 — Batch OCR/ISBN backfill | Barcode decode + local vision-LLM fallback to fill in title/author/ISBN | Planned | +| 3 — Checkout station | Track books leaving inventory, reusing the intake identification pipeline | Planned | + +## How it works (Phase 1) + +1. A downward-facing webcam looks at a fixed platform with printed + nested size-boundary markers (small / medium / large). +2. A volunteer centers the book; capture fires automatically or on a + button press (configurable). +3. The system photographs the front, determines size — **deterministically**, + by checking which physical markers are covered, not by any AI/ML step — + then prompts the volunteer to flip the book and photographs the back. +4. Every book gets a row in a CSV catalogue: images, size bucket, and a + status that later pipeline stages (OCR backfill, checkout) update. + +Full design rationale lives in `AGENTS.md` (also readable as `CLAUDE.md` — +same file, symlinked for compatibility with different AI coding tools). + +## Why this matters for a nonprofit + +- **No cloud costs, no vendor lock-in.** Everything runs on donated + hardware; no per-book or per-scan fees. +- **Deterministic where it counts.** Size-bucket counts feed Books in + Hand's year-end tax and 501(c)(3) reporting — that number is computed + from physical measurements, not inferred by a model, so it can't drift + or hallucinate. +- **Volunteer-friendly.** The intake flow is designed to be usable by + volunteers with no technical background — guided steps, big buttons, + no login required. + +## Development + +Requires Python 3.11+. + +```bash +python3 -m venv .venv +.venv/bin/pip install -e ".[dev]" +.venv/bin/pytest -v +``` + +Full setup, calibration, and end-to-end testing instructions will land +here once the intake station is runnable (tracked in the project's +implementation plan). + +## License + +MIT — see `LICENSE`.