Skip to main content

pdfpeek

PDF to text — with a confidence score.

Tests PyPI Python License: MIT

Most PDF tools dump text and leave you guessing whether it worked. pdfpeek runs a 10-stage pipeline and tells you exactly how confident it is in every extraction.

$ pdfpeek extract report.pdf

  pdfpeek  →  report.pdf

  ✔  Triage                2 page(s)  text_native: 1  hybrid: 1
  ✔  Extraction            47 blocks
  ✔  Warnings              1 warning(s)

  Confidence   0.893
  Time         1.4s

  Output  →  report.txt

Install

# Born-digital PDFs only (~50 MB)
pip install pdfpeek

# + Scanned PDF support via Tesseract (~100 MB)
pip install pdfpeek[ocr]

# + AI layout detection via surya (~5 GB)
pip install pdfpeek[layout]

Tesseract (system package) is required for [ocr]:

  • macOS: brew install tesseract
  • Ubuntu/Debian: sudo apt install tesseract-ocr
  • Windows: UB-Mannheim installer

Usage

CLI

# Extract to plain text (default)
pdfpeek extract document.pdf

# Extract to markdown
pdfpeek extract document.pdf --format markdown --out result.md

# Batch a whole folder
pdfpeek extract ./pdfs/ --out ./txts/

# Password-protected PDF
pdfpeek extract encrypted.pdf --password secret

# Inspect a PDF before extracting
pdfpeek info document.pdf

Python API

from pdf_engine import extract

result = extract("document.pdf")

print(result.text)             # extracted text
print(result.confidence)       # 0.0 – 1.0 document-level confidence
print(result.warnings)         # any issues found during extraction

# Full structured output
for page in result.ir.pages:
    for block in page.blocks:
        print(block.text, block.confidence.final, block.block_type)

How it works

pdfpeek runs every PDF through a 10-stage pipeline:

Stage Name What it does
0 Triage Classifies each page: text-native, scanned, or hybrid
1 Extraction Pulls embedded text with phantom-layer detection
2 Layout Detects block types (heading, body, table, figure) via surya
3 Reading Order XY-cut partitioning, RTL-aware
4 Tables Explicit (ruled) and implicit (whitespace) table detection
5 OCR Tesseract + surya for scanned/hybrid pages
6 Assembly Merges pymupdf and surya outputs; de-duplicates
7 Cross-page Strips headers/footers; builds heading hierarchy
8 Post-processing Rejoins hyphenation; corrects OCR errors
9 Confidence Scores every block on text quality, method trust, order, and type

Each block gets a confidence score from 0 to 1. The document score is the mean of all block scores.


Comparison

pdfpeek pdfplumber pypdf unstructured
Born-digital ✅ ✅ ✅ ✅
Scanned (OCR) ✅ [ocr] ❌ ❌ ✅
Hybrid pages ✅ ⚠️ partial ❌ ✅
Confidence score ✅ ❌ ❌ ❌
Install size 50 MB ~20 MB ~5 MB 5 GB+
Python API ✅ ✅ ✅ ✅
CLI ✅ ❌ ❌ ✅

Confidence scoring

Every TextBlock has a BlockConfidence with four dimensions:

Dimension Set by Meaning
text_quality Stage 9 Fraction of printable, non-garbled characters
method_score Stage 9 Trust in the extraction method (pymupdf=1.0, tesseract=0.7)
order_quality Stage 3 Confidence in reading-order placement
type_quality Stage 2 Confidence in block-type classification
final Stage 9 Geometric mean of the four above

A document-level score above 0.8 means reliable extraction. Below 0.6 means you should check the output manually or try [layout].


Known limitations (v0.1)

  • Very complex multi-column layouts (magazines, newspapers) may have reading-order issues
  • Non-English OCR error correction is not yet implemented
  • Documents > 1000 pages will be slow (surya processes ~2–3 pages/sec)
  • Equations, handwriting, and deeply nested table-in-sidebar structures are best-effort

These are on the roadmap for v0.2.


Contributing

git clone https://github.com/ibrah5em/pdfpeek
cd pdfpeek
pip install -e ".[ocr,dev]"
pytest tests/

PRs welcome. Please add a test for any bug fix.


License

MIT — see LICENSE.

Metadata

Release files for pdfpeek 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pdfpeek 0.1.0
File Size Uploaded Provenance Actions
pdfpeek-0.1.0.tar.gz 133.9 kB Without provenance Details for pdfpeek-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pdfpeek 0.1.0
File Interpreter ABI Platform Actions
pdfpeek-0.1.0-py3-none-any.whl Python 3 none any Details for pdfpeek-0.1.0-py3-none-any.whl

Total release size: 214.8 kB

Release files / pdfpeek-0.1.0.tar.gz

Download URL pdfpeek-0.1.0.tar.gz
Size 133.9 kB
Tags Source
SHA-256 checksum
How to use checksums
b258c5a46fe2334de2744888447d61be22575fc5239dc4349550cd46c2c8515c
BLAKE2b-256 checksum
How to use checksums
d1a836d14b75dd7c9057c99fbe86adc66cd43f332cf4ba8c7a88ab7774c234b6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Release files / pdfpeek-0.1.0-py3-none-any.whl

Download URL pdfpeek-0.1.0-py3-none-any.whl
Size 80.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
94d85745b07be11f5bbfcc2d6768bf5408a3a3a1934106aef72051728c23ffa9
BLAKE2b-256 checksum
How to use checksums
d598fba113226ecc0d7e9a9d47f9ee582bb44ff3ac9f26267eb6b45a40dc7e24
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Security for pdfpeek 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page