pdf-untangle
Untangle garbled PDF text: layout-aware extraction that reconstructs reading order, strips page furniture, repairs hyphenation and page-break flow, and — with a declarative profile — splits a document into structured, citable sections. A library and a CLI in one crate.
The problem
A PDF stores text as thousands of individually positioned glyphs: "put an 'R'
at (72, 640) in 11pt bold." There are no paragraphs, headings, columns, or
reading order in the file. Naive extraction gives you the familiar mishmash —
lines interleaved out of order, page headers jammed mid-sentence, words split
by hyphens, two columns shuffled together. pdf-untangle reconstructs the
logical document, in three layers:
- extract — PDF → positioned text runs (pluggable backends)
- layout — runs → ordered lines/blocks: reading order, column detection, header/footer stripping, de-hyphenation, page-flow merge
- structure — blocks → discrete sections ("provisions"), driven by a TOML profile: heading patterns, a citation template, history/date formats. All document-family knowledge is data, not code.
Built for (and battle-tested on) legal PDFs — court rules and statutes that many U.S. jurisdictions publish only as PDF — but the engine is generic.
Status
Phase 0 scaffold. The public API shape, profile system, and output model are in place and tested; the extraction/layout/structure layers land next. See docs/DESIGN.md for the full design and phased plan with checkboxes.
CLI (planned surface)
pdf-untangle extract rules.pdf --profile cnmi-rules -o out.jsonl
pdf-untangle text rules.pdf # clean reading-ordered text, no profile
pdf-untangle inspect rules.pdf --page 3 # runs/blocks dump for profile authoring
pdf-untangle profiles # list built-ins (works today)
pdf-untangle check rules.pdf --profile x # coverage + integrity dry-run
Two invariants make output trustworthy: line-coverage accounting (every
input line is consumed, skipped by rule, or reported — silent text loss is
impossible) and structure-integrity checks (citation-sequence sanity, TOC
cross-checks). Each record carries a confidence score derived from both.
Library (planned surface)
let profile = builtin?;
let doc = extract?;
for p in doc.provisions
Non-goals (v1)
Scanned/image PDFs (OCR is on the v2 roadmap), table extraction as structured data, and fetching PDFs from the network — bring your own bytes.
License
MIT OR Apache-2.0, at your option.