# 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`.