TableProof

TableProof finds suspected errors in extracted PDF tables. It compares cell text and row or column positions with source evidence.

Every number can survive extraction while its row label changes. TableProof reports the disputed cell and its original PDF region.

This is an alpha Python library. It needs Python 3.11 or later.

Installation

python -m pip install table-proof-py
table-proof source.pdf docling-export.json --html report.html --json report.json

docling-export.json is a Docling document export with table cells and source coordinates.

For the optional local vision model, install the extra dependencies:

python -m pip install 'table-proof-py[vision]'

Try the real regression case

The recorded regression pair contains this error:

The regression fixtures are in the source repository. Run these commands:

git clone https://github.com/eduard-s/table-proof.git
cd table-proof
python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/table-proof \
  benchmarks/fixtures/docling_5198/source.pdf \
  benchmarks/fixtures/docling_5198/affected.json \
  --html report.html --json report.json

The command exits with code 1. It reports two swapped row labels in the affected fixture.

Replace affected.json with fixed.json to examine the paired control. That command exits with code 0.

The fixture reproduces a real Docling defect on a generated PDF. It does not represent an independent production document.

Read the benchmark results and fixture provenance.

Python API

import json
from pathlib import Path

from table_proof import audit_tables

fixture = Path("benchmarks/fixtures/docling_5198")
document = json.loads((fixture / "affected.json").read_text())
report = audit_tables(fixture / "source.pdf", document)

print(report.status)
report.export_json("report.json")
report.export_html("report.html", source_pdf=str(fixture / "source.pdf"))

The adapter accepts Docling JSON, a DoclingDocument, or a conversion result with a document field. Docling is optional at runtime.

Rich cells can contain text references. The adapter resolves the references that control the rendered table. It does not trust stale cell text.

What the MVP does

• Compares cell tokens with PDF words in the cell region.
• Detects reversed row or column positions and invalid cell spans.
• Reports missing source text, incomplete geometry, and ambiguous word assignments.
• Produces JSON findings and local HTML evidence.
• Preserves the source PDF and extraction.
• Supports an optional, pinned Table Transformer model for independent structure evidence.

The default path uses PDF text and geometry. It makes no network requests.

The optional model runs locally. It needs an explicit download option before its first use. Read the vision guide.

Results and limits

no_findings does not prove semantic accuracy. An empty table list returns uncertain.

Start with digital PDFs and tables that occupy one page. Scans and multi-page tables need other methods.

The tool does not certify units or source facts. It does not repair data automatically. Detector scores are not calibrated error probabilities.

The small development benchmark compares TableProof with local controls and pinned upstream pdfmux code. Its cases establish a reproducible regression result. They do not establish broad superiority on real documents.

On the included public paper, TableProof flags six missing headers. It returns uncertainty for a clipped superscript in another parser output.

The optional vision model recovers the table grid but adds no error detection on that public example. Read the recorded model results before a model accuracy claim.

Development

.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/ruff check .
.venv/bin/ruff format --check .
.venv/bin/mypy src/table_proof
.venv/bin/pytest --cov=table_proof --cov-report=term-missing
.venv/bin/python -m build
.venv/bin/python -m twine check dist/*

Use Python 3.12 for the type analysis. CI runs tests on Python 3.11 through 3.14.

Documents

• MVP plan and acceptance criteria
• Architecture and Python stack
• API and report contract
• Datasets and evaluation plan
• Benchmark reproduction
• Optional vision model
• Development and contribution
• Release instructions

License

MIT. See LICENSE and third-party notices.