/reading-business-cards

name: reading-business-cards
description: "Preprocesses photographed sheets of many business cards — slicing each into overlapping high-resolution tiles and de-glaring them with container tooling (OpenCV/ImageMagick) — then reads every card via cheap parallel temperature-0 API calls (Haiku or Sonnet) using a distilled extraction prompt, and writes deduped contact fields to a CSV. Use when a user has photos or scans holding multiple business cards per image, mentions glare or unreadable cards, batch card transcription, contact extraction, or wants to read many cards without an expensive in-conversation pass. Triggers on 'business cards', 'card scan', 'extract contacts', 'read these cards', 'card glare', 'too many cards per photo'."
metadata:
  version: 2.3.0

Reading Business Cards

Turn photos or scans that pack many business cards into one image into a clean contact list. The job is two stages, in order: **preprocess with the script, then read the tiles it produces.** Read the tiles, not the original sheet — the original is too low-resolution per card once the model downscales it.

Why preprocess first

The model downscales any input image to ~1568px on the long edge before it sees it. A phone photo of 50-60 cards is often 4000-6000px; downscaled to one image, each card lands ~150px wide — unreadable, which forces you onto a more expensive model. The script cuts the sheet into overlapping **tiles**, each near the downscale cap (~1300px), so every card in a tile keeps 500px+ of real resolution. That resolution recovery is what lets a cheaper model (Sonnet) read cards that only the expensive one (Opus) could read before — and it lets Opus read cards from far fewer tiles. **The grid is sized to the reader model** (see Stage 1): pass `--model` and the script tiles aggressively for Haiku, moderately for Sonnet, and least for Opus, because a stronger reader has a lower resolution floor. The floor is set by the *pixels*, not the model's intelligence: at ~220px/card (a whole dense sheet) even Opus reads only company and some names, not phone/email — so even Opus needs a few tiles for fine print on dense sheets.

De-glaring (illumination flattening + local contrast) is applied to each tile. It corrects uneven lighting and the haze off glossy cards and plastic binder sleeves. It cannot recover text where glare has clipped pixels to pure white — that data is gone (see Limits).

Stage 1 — Tile the sheets

The person only provides the images and the goal ("read these cards"). Derive every parameter yourself; do not ask them to choose grid sizes or flags.

Real sheets are messy: cards scattered at angles, packed in binder sleeves, overlapping, piled. Detecting individual card boundaries fails on all of these. **Tiling ignores card boundaries** — it slices the sheet into a grid of overlapping rectangles. Each tile holds a few cards at high resolution; the overlap means a card split by one tile's edge is whole in its neighbour.

Run it sized to whichever model will read the tiles — pass `--model` and the script measures each sheet's native card size, then derives the coarsest grid whose cards still clear that model's OCR floor:

python3 scripts/prep_cards.py /mnt/user-data/uploads --out /home/claude/cards_work --model opus

`--model opus|sonnet|haiku` (or a full model id string) sets the floor: Opus tiles least, Haiku most. Default is `sonnet` (the safe middle). On a dense ~660px-card sheet this yields roughly 6 tiles/sheet for Opus, 9-12 for Sonnet, 12-20 for Haiku. If the reader is the in-conversation model (the no-key path, below), set `--model` to match whatever you're running. Overrides: `--target-px` forces an explicit tile size, `--card-px` overrides the auto card-size estimate, `--floor-px` overrides the per-model floor.

It prints the grid it chose per image (e.g. `auto 3x2 from 4284x5712 [model=opus floor=350 card~668px -> target 2993]`) and writes tiles to `cards_work/tiles/` (`<sheet>__r{R}_c{C}.png`) plus a `manifest.json`. If a sheet's cards are smaller than the model's floor even at native resolution, it warns — that sheet needs a re-shoot, not a finer grid.

Then **verify and self-adjust by inspection** — this is your judgment, not the person's:

• View one representative tile. If the cards in it are crisp and fully legible,

proceed to read them all.

• If cards look small or dense (text fuzzy), rerun with a smaller cap for a finer

grid: `--target-px 1100`.

• If cards are clipped in half at tile edges, rerun with more overlap:

`--overlap 0.2`.

• If the cards are matte and text-only and a light haze remains, rerun with

`--binarize`. Skip binarize for color or logo-heavy cards — it flattens them.

De-glaring (illumination flatten + local contrast) is on by default and is non-destructive. Decide on the extra flags by looking at a tile, then commit to the full read.

Stage 2 — Read and extract

There are two ways to read the tiles. **In-session reading is the universal path and works for everyone, key or no key:** view the tiles with the `view` tool and transcribe them in this conversation, applying the rules in `prompts/haiku_extract.md` (one row per fully-visible card, skip edge-clipped cards that are whole in a neighbour, never invent, `confidence` low when unsure). The coarse model-sized grid is what makes this tractable — a dozen tiles per sheet, not eighty — and the conversation model reading them is exactly the model that reads cards well. Cost here is the subscription's usage allowance, not per-token dollars; the coarser the grid (Opus), the fewer reads.

**The API runner is an optional optimization, only when an API key is present** (`API_KEY` in env / `/mnt/project/claude.env`). It sends each tile to a model in a separate parallel call (temperature 0 on legacy models; current models reject sampling parameters) using the distilled prompt, dedupes, and writes the CSV — reading outside the chat context, so it is cheaper per token and runs many til