Command line

Installing the package provides an tetrak-ocr command.

tetrak-ocr backends

List every backend and whether this environment can run it. ✓ means installed and usable; · means the optional extra is missing.

$ tetrak-ocr backends
 ✓ tesseract
 ✓ tesseract-auto
 · claude  (extra not installed)
 ✓ auto-local

tetrak-ocr ocr

Transcribe a single file to stdout, or to --output.

tetrak-ocr ocr scan.jpg
tetrak-ocr ocr scan.jpg --backend tesseract-auto
tetrak-ocr ocr programme.pdf --backend marker --output programme.md
tetrak-ocr ocr faded.jpg --contrast 3.5 --psm 6

--contrast, --psm and --auto tune Tesseract per image. Any backend that does not use them says so rather than dropping them silently.

tetrak-ocr batch

Three directories, resolved against your current working directory — so run it from the folder holding your scans:

scans/       input — put files here
processed/   output — transcript plus the original, side by side
triage/      quarantine — files whose transcript was too poor to trust

tetrak-ocr batch --backend auto-local

For each supported file in scans/, the pipeline runs OCR, writes processed/<name>.md, and moves the original to processed/<name>.<ext>. Keeping the transcript beside its source means a transcript is never orphaned from the image it came from.

Only extensions the chosen backend supports are picked up — EasyOCR and PaddleOCR skip PDFs, because they cannot read them.

The triage queue

auto-local refuses to return a transcript whose quality score falls below the floor. When that happens the batch pipeline diverts the file to triage/ along with a manifest recording which backends were tried, their scores, and an excerpt of each transcript — so you can decide whether to rescan, send it to Claude, or transcribe by hand. --quality-gate applies the same threshold to any single named backend. The reasoning is on from findings to design.

Dry runs

tetrak-ocr batch --backend tesseract --dry-run

Lists what would be processed without touching anything — and, just as useful, what would be skipped because the chosen backend cannot read it. The batch pipeline filters scans/ by the backend’s supported extensions, so a PDF simply vanishes under easyocr or paddle; a dry run is where that becomes visible.

No OCR runs and nothing is moved, but the chosen backend’s package does have to be installed — the file list depends on which extensions that backend declares it can read.

Tuning Tesseract

tetrak-ocr batch --backend tesseract --contrast 3.0 --psm 6
tetrak-ocr batch --backend tesseract --auto

--contrast and --psm apply only to Tesseract; passing them with another backend prints a note rather than silently ignoring them. --auto picks both per image, and is usually better than either default — see the engines.

tetrak-ocr evaluate

Benchmark backends against the evaluation corpus. Flags are passed straight through to the harness.

tetrak-ocr evaluate --backend tesseract-auto
tetrak-ocr evaluate --all
tetrak-ocr evaluate --all --save

This one needs a checkout — the corpus is not shipped in the package, so running it elsewhere reports that rather than failing obscurely.