pdf-untangle 0.0.1

Untangle garbled PDF text: layout-aware extraction that reconstructs reading order, strips page furniture, and splits documents into structured, citable sections
Documentation

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:

  1. extract — PDF → positioned text runs (pluggable backends)
  2. layout — runs → ordered lines/blocks: reading order, column detection, header/footer stripping, de-hyphenation, page-flow merge
  3. 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 = pdf_untangle::Profile::builtin("cnmi-rules")?;
let doc = pdf_untangle::extract(Path::new("rules.pdf"), &profile)?;
for p in doc.provisions { println!("{}: {}", p.citation, p.heading.unwrap_or_default()); }

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.