Accuracy/speed numbers above are measured vs Azure Document Intelligence on a held-out insurance corpus.

🐍 Public API

extract(
    file,                     # path — PDF, image, or any supported format
    *,
    feature="all",            # what to return (str | list | phrase)
    show=False,               # draw the page: True | "inline" | "window" | "out.png"
    # composable add-ons — each True / False / "auto":
    styles="auto", signatures="auto", formulas="auto",
    handwriting="auto", classify="auto", fields="auto",
    ocr="auto", ocr_images="auto",
    document_type=None,       # "auto" | "invoice" | "contract"  (alias: mode=)
    queries=None,             # ["total due", …] → {query: value}
    language=None,            # OCR language: "en" | "es" | … | "auto"
    output_format="dict",     # "dict" | "json" | "markdown" | "text"
    output_dir=None,          # bundle: JSON + attachments/ PNGs + relative paths
    pages=None,               # [1,2,5] | "1-5,8" | None
    backend="auto",           # "auto" | "cpu" | "gpu" | "llm"
    reading_order="auto", include_bbox=False, config=None,
)

Key options:

🍳 Examples

import paradox_pdf as pdx

doc = pdx.extract("annual_report.pdf")

# Top-level structure
print(doc.keys())
# dict_keys(['source', 'total_pages', 'total_elements', 'total_images',
#            'type_summary', 'elements'])

# Walk the heading tree
def walk(nodes, depth=0):
    for n in nodes:
        text = (n.get("text") or "").strip()[:80]
        print(f"{'  '*depth}{n['type']:14s} {text}")
        walk(n.get("children", []), depth + 1)

walk(doc["elements"])

doc = pdx.extract("contract.pdf", pages=[1, 2, 5])
# or
doc = pdx.extract_pages("contract.pdf", pages=range(10, 20))

text = pdx.extract_text("contract.pdf")

tables = pdx.extract_tables("contract.pdf")

for t in tables:
    rows, cols = t["shape"]
    cells = t["cells"]
    print(f"Table {rows}×{cols}, {len(cells)} cells")

    for c in cells:
        p = c["p"]
        if len(p) == 2:                          # simple cell
            r, col = p
            print(f"  ({r},{col}): {c['t']!r}")
        else:                                    # merged cell
            r, col, rowspan, colspan = p
            print(f"  ({r},{col}) span {rowspan}×{colspan}: {c['t']!r}")

{"p": [row, col], "t": "Some cell text"}                       # simple
{"p": [row, col, rowspan, colspan], "t": "Header cell"}        # merged

doc = pdx.extract_to_file(
    "contract.pdf",
    output="out/contract.json",
    images_dir="out/images/",
)

from pathlib import Path
import paradox_pdf as pdx

for pdf in Path("inbox/").glob("*.pdf"):
    doc = pdx.extract_to_file(pdf, output=f"out/{pdf.stem}.json", no_images=True)
    print(f"{pdf.name:40s}  {doc['total_pages']}p  {doc['total_elements']} elements")

from paradox_pdf import extract, PipelineConfig

cfg = PipelineConfig(
    render_dpi=300,                    # higher DPI for vision pipeline
    scan_text_threshold=80,            # treat pages with <80 chars as scanned
    cv_border_missing_threshold=0.40,  # be stricter about declaring borders absent
    yolo_confidence=0.30,              # stricter YOLO detections
)

doc = extract("noisy_scan.pdf", config=cfg)

PDF_RENDER_DPI=300 PDF_YOLO_CONFIDENCE=0.3 python my_script.py

# Force the digital pipeline even if a page looks scanned (faster, no OCR)
doc = pdx.extract("digital_only.pdf", force_mode="heuristic")

# Force the vision pipeline (OCR every page, even digital ones)
doc = pdx.extract("scanned.pdf", force_mode="vision")

doc = pdx.extract("contract.pdf", no_images=True)
print(doc["type_summary"])
# {'TITLE': 1, 'H1': 4, 'H2': 11, 'PARAGRAPH': 67, 'TABLE': 3, 'SIGNATURE': 2}

import paradox_pdf as pdx

LEVEL = {"TITLE": 1, "SUBTITLE": 2, "H1": 3, "H2": 4, "H3": 5, "H4": 6}

def to_markdown(nodes, out=None):
    out = out if out is not None else []
    for n in nodes:
        t = n.get("type")
        text = (n.get("text") or "").strip()
        if t in LEVEL and text:
            out.append("#" * LEVEL[t] + " " + text)
        elif t == "PARAGRAPH":
            out.append(text)
        elif t == "TABLE":
            out.append(f"_<table {n['shape'][0]}x{n['shape'][1]}>_")
        out.append("")
        to_markdown(n.get("children", []), out)
    return "\n".join(out)

doc = pdx.extract("contract.pdf", no_images=True)
print(to_markdown(doc["elements"]))

🗂️ Output schema

{
  "source": "contract.pdf",
  "total_pages": 12,
  "total_elements": 145,
  "total_images": 4,
  "type_summary": {"TITLE": 1, "PARAGRAPH": 67, "TABLE": 3, "...": "..."},
  "elements": [
    {
      "type": "TITLE",
      "marks": ["BOLD"],
      "text": "**Annual Report — Q4 2025**",
      "ref": "(p1,l1):(p12,l8)",
      "children": [
        {"type": "PARAGRAPH", "text": "...", "ref": "(p1,l2):(p1,l2)"},
        {"type": "H1",
         "text": "**1. Financial Summary**",
         "ref": "(p1,l3):(p2,l4)",
         "children": [
           {"type": "TABLE",
            "shape": [5, 4],
            "cells": [
              {"p": [0, 0], "t": "Category"},
              {"p": [0, 1, 1, 3], "t": "Studio Minimum Rates"}
            ],
            "ref": "(p1,l4):(p1,l4)"}
         ]}
      ]
    }
  ]
}

ref field

Every element gets a ref of the form "(pX,lY):(pX,lY)" where:

• pX = page number (1-based),
• lY = element index within that page (1-based).
• The first tuple is the start; the second is the end of the element's last descendant.

Element types (excerpt)

TITLE, SUBTITLE, H1–H4, PARAGRAPH, TABLE, LIST (with items[]), TOC (with entries[]), IMAGE, SIGNATURE, AMENDMENT_DEL, EXHIBIT, APPENDIX, FOOTER, HEADER, PAGE_NUMBER, plus 50+ more. Full list: pdf_tagger/catalog.py.

Inline marks

Marks are preserved both in marks: [...] (per-element) and inline in the text:

Top-level keys

Always present: source · source_format · total_pages · total_elements · total_images · type_summary · elements · document_metadata (title/author/dates + language/language_name) · bookmarks · embedded_files · page_links · page_annotations.

Added by the matching feature/add-on:

Per-element extras

bbox (with include_bbox=True, PDF points) · latex (formulas) · handwritten_text (handwriting) · ocr_text (ocr_images=True) · language (per element) · color / highlight · attachment (bundle, relative path) · src/width/height (images) · TABLE shape+cells · FORM_FIELD name/field_type/value/label.

⌨️ CLI

The same package installs a paradox-pdf command.

Plug-and-play (single file, any format) — mirrors the feature= API:

paradox-pdf invoice.pdf --want fields          # key→value JSON to stdout
paradox-pdf scan.png     --want tables --show  # tables + save annotated PNG
paradox-pdf report.pdf   --want markdown -o out.md
paradox-pdf invoice.pdf  --want "the total amount due"
paradox-pdf doc.pdf      --want text,tables    # comma list → JSON dict

Batch / full-JSON mode (folders, parallel):

paradox-pdf contract.pdf                       # → output/contract.json
paradox-pdf contract.pdf -o result.json
paradox-pdf docs/ -o extracted/ -w 8           # parallel folder
paradox-pdf --pages 1-5 contract.pdf
paradox-pdf --no-images contract.pdf

Run paradox-pdf --help for the full set of flags.

⚙️ How it works

                 ┌─────────────────┐
PDF ─────────────► scan_detector   │  per page (<50 chars → vision)
                 └────────┬────────┘
            ┌─────────────┴─────────────┐
            ▼                           ▼
   ┌──────────────────┐        ┌──────────────────────┐
   │ Heuristic        │        │ Vision               │
   │ (PyMuPDF fonts)  │        │ YOLO + RapidOCR      │
   │                  │        │ + Table Transformer  │
   │                  │        │ + HDBSCAN borderless │
   │                  │        │ + TexTAR (marks)     │
   └────────┬─────────┘        └──────────┬───────────┘
            └─────────────┬───────────────┘
                          ▼
              ┌────────────────────────┐
              │ Section tree builder   │
              │ Post-processing passes │
              └───────────┬────────────┘
                          ▼
                       JSON dict

For tables, three detectors run in parallel — vector lines (PyMuPDF), Table Transformer, OpenCV border morphology — and the highest-quality result wins by IoU 0.5 NMS scored on fill_rate + source_bonus − merge_penalty. Merged cells are detected by missing inner borders (≥35% pixel coverage threshold) for bordered tables, and by cell-width ratio (>1.6× column pitch) for borderless ones.

Reading order (new in 0.5.0)

PP-DocLayoutV2 is a two-stage model: an RT-DETR detector emits boxes + class labels, and a pointer network trained end-to-end re-ranks them into reading order using class-label embeddings + 2D positional encodings + geometric bias. Paradox preserves that prediction by default — earlier releases discarded it by re-sorting on y0, which produced the wrong order on multi-column papers.

Override with the reading_order kwarg:

pdx.extract("paper.pdf")                          # auto → pointer-net when available
pdx.extract("paper.pdf", reading_order="native")  # require pointer-net (errors otherwise)
pdx.extract("paper.pdf", reading_order="geometric")  # recursive XY-Cut on bboxes only
pdx.extract("paper.pdf", reading_order="y")       # legacy 0.4.x behaviour (snapshot tests)

On the multi-column real-PDF bench (Las Condes journal, Nature Sci Reports, etc.) the pointer-net order matches the human-validated ground truth on 11/20–14/14 pages where naive y sort matched only 4/15–9/14. Pages without the detector (digital text path, YOLOv10 legacy fallback) automatically fall back to geometric XY-Cut.

Digital hierarchy via PP-DocLayoutV2 (new in 0.5.1, improved in 0.5.2)

On the digital (non-scanned) path, paradox normally classifies block types with font_classifier — font flags + size hierarchy + indentation. That works well when titles use a visibly larger font, but misses cases where a title is bold-and-same-size, or where an article subtitle, footnote, or caption is not encoded with a font-rank signal.

Three modes, ordered by trust:

# Default — heuristic only (unchanged from 0.4.x).
pdx.extract("doc.pdf")

# Recommended — tier-aware hybrid. PP for hierarchy signals (TITLE /
# FOOTNOTE / CAPTION / HEADER), heuristic for body text, sanity-checked
# TABLE/FIGURE so PP cannot promote a sectioned CV layout into a fake table.
pdx.extract("doc.pdf", digital_layout_detector="hybrid")

# Trust PP-DocLayoutV2 unconditionally. Good for clean papers; can
# over-classify TABLE on CVs/forms because the visual layout fools it.
pdx.extract("doc.pdf", digital_layout_detector="paddlex")

Validated on three real PDFs — hybrid is strictly better than the other two:

PyMuPDF still extracts text + marks (digital signals stay perfect). PP-DocLayoutV2's pointer-network rank is preserved through the dispatcher in all three modes, so the reading order of multi-column pages is correct regardless of how types are decided.

Costs ~1 s/page on CPU.

Performance notes

• Digital page: ~0.05 s on CPU.
• Scanned page: ~10 s on CPU, much faster on GPU (PyTorch detects and uses CUDA automatically).
• First run: HuggingFace models are downloaded once (~500 MB total).

If you see multi-minute startup per document with the vision pipeline, set HF_HUB_OFFLINE=1 after the first download — HuggingFace's online metadata revalidation on slow networks is the bottleneck, not the actual inference:

HF_HUB_OFFLINE=1 python my_script.py

Or in code:

import os
os.environ["HF_HUB_OFFLINE"] = "1"
import paradox_pdf as pdx

Repository layout

paradox_pdf/         Public Python API (extract, extract_text, …)
pdf_tagger/          Core extraction (font classifier, vision layout, marks)
pdf_grid/            Vector-line table detection
scripts/             CLI implementation
docs/                Configuration reference, API reference, research notes
examples/            Sample PDFs + expected outputs
_dev/                Test suites, fixtures, benchmarks (not shipped in wheel)