About this project

PageLedger is an open-source Python library and CLI tool that provides auditable, page-level tracking for OCR and document extraction runs. It wraps around text extraction and OCR engines, recording provenance, quality signals, costs, and review state for every page processed. Core capabilities include: - **Page-level ledgers**: Each extraction run is stored as a directory of JSON, YAML, Markdown, and raw output files—inspectable without a database or running service. - **Built-in adapters**: Supports plain text files, PDF text layers, and Tesseract OCR out of the box. Additional engines can be added via the adapter protocol. - **Budget tracking**: Records page counts, token usage, elapsed time, and cost estimates, distinguishing reported charges from configured limits. - **Quality signals**: Assigns per-page quality grades and warnings to help identify pages needing review. These are not accuracy scores but evidence-based flags. - **Review and rerun queues**: Flagged pages can be rerun or held for human review. `review-job` records reviewer decisions bound to the source document. - **Resumable runs**: Interrupted runs and document jobs retain checkpoint evidence. Use `pageledger resume` to verify saved responses and reuse them without re-extracting. - **Run comparison**: `pageledger compare-runs` enables side-by-side analysis of different extraction attempts on the same source. - **Normalized records**: `align` can revise structured records (tables, JSON, CSV) against declared columns and arithmetic checks without re-extraction. Installation requires Python 3.10+ and is available on PyPI. The `pageledger[pdf]` extra adds PDF support; scanned PDFs additionally require Poppler and Tesseract, which can be verified with `pageledger doctor`. The tool originated from a Soviet census digitization project and is designed for archives, historians, and research teams that need to trace extracted output back to source pages and reconstruct how results were produced. A 60-page validation report documents what automated checks catch and where human review remains necessary.