table-proof-py 0.1.0__tar.gz

table_proof_py-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.venv*/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage*
+htmlcov/
+dist/
+build/
+*.egg-info/
+.DS_Store
+artifacts/
+.cache/
+coverage.xml
+/report.html
+/report.json
+/model-cache/

table_proof_py-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+- Add source-PDF audits for extracted table cells.
+- Add Docling JSON and object adapters with rich-reference resolution.
+- Add JSON and HTML evidence reports.
+- Add an optional local Table Transformer path.
+- Add unit, property, integration, and distribution tests.
+- Add pinned regression fixtures and a comparative benchmark.
+- Add the MVP plan and dataset acceptance criteria.
+- Add a PyPI release workflow and archive content examination.
+- Use the `table-proof-py` distribution name on PyPI.

table_proof_py-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contribute
+
+## Install
+
+Use Python 3.12 for development. From the repository root, run:
+
+```sh
+python3.12 -m venv .venv
+.venv/bin/python -m pip install -e '.[dev]'
+```
+
+## Before a commit
+
+```sh
+.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 benchmarks.run \
+  --methods tableproof token_multiset_control structural_validity_control \
+  --output artifacts/local-benchmark.json
+.venv/bin/python -m build
+.venv/bin/python -m twine check dist/*
+```
+
+The default tests do not download model weights. Read the [vision guide](docs/VISION.md) for a real-model run.
+
+## Add a defect case
+
+1. Reduce the source to the smallest useful public example.
+2. Record its license and attribution.
+3. Record the extractor version and exact command.
+4. Preserve the actual extracted output.
+5. Label the wrong cells against the original source.
+6. Add a correct control from the same layout.
+7. Record unsupported evidence explicitly.
+
+Do not submit confidential documents. Use an authorized public source or an independent synthetic reproduction.
+
+## Change a detector
+
+Add a regression test that fails before the change. Include a correct table that exercises the same rule.
+
+Keep uncertain evidence separate from an error finding. A broader detector must not silently convert uncertainty to success.
+
+Update the architecture and report documents when behavior changes. Write short sentences with one meaning per term.
+
+## Dependencies
+
+Keep heavy model packages in the vision extra. Keep model downloads explicit.
+
+For the measured competitor comparison, use the isolated benchmark lock file. Do not replace a competitor with a local approximation.

table_proof_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eduard Smirnov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

table_proof_py-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: table-proof-py
+Version: 0.1.0
+Summary: Audit PDF table cell associations against source evidence
+Project-URL: Homepage, https://github.com/eduard-s/table-proof
+Project-URL: Repository, https://github.com/eduard-s/table-proof
+Project-URL: Issues, https://github.com/eduard-s/table-proof/issues
+Author: Eduard Smirnov
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pdfplumber<0.12,>=0.11.4
+Requires-Dist: pydantic<3,>=2.11
+Provides-Extra: dev
+Requires-Dist: build<2,>=1; extra == 'dev'
+Requires-Dist: docling-core<3,>=2.48; extra == 'dev'
+Requires-Dist: hypothesis<7,>=6; extra == 'dev'
+Requires-Dist: jsonschema<5,>=4; extra == 'dev'
+Requires-Dist: mypy<2,>=1.15; extra == 'dev'
+Requires-Dist: pytest-cov<8,>=6; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Requires-Dist: reportlab<5,>=4; extra == 'dev'
+Requires-Dist: ruff<1,>=0.14; extra == 'dev'
+Requires-Dist: twine<7,>=6; extra == 'dev'
+Provides-Extra: vision
+Requires-Dist: timm<2,>=1; extra == 'vision'
+Requires-Dist: torch>=2.6; extra == 'vision'
+Requires-Dist: transformers<5,>=4.50; extra == 'vision'
+Description-Content-Type: text/markdown
+
+# TableProof
+
+[![CI](https://github.com/eduard-s/table-proof/actions/workflows/ci.yml/badge.svg)](https://github.com/eduard-s/table-proof/actions/workflows/ci.yml)
+
+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
+
+```sh
+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:
+
+```sh
+python -m pip install 'table-proof-py[vision]'
+```
+
+## Try the real regression case
+
+The recorded regression pair contains this error:
+
+| Source row | Affected extracted row | Result |
+| --- | --- | --- |
+| `BBB → 20.0 mg` | `CCC → 20.0 mg` | Row label differs from the source region. |
+| `CCC → 30.0 mg` | `BBB → 30.0 mg` | Row label differs from the source region. |
+
+The regression fixtures are in the source repository. Run these commands:
+
+```sh
+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](https://github.com/eduard-s/table-proof/blob/main/benchmarks/results.md) and [fixture provenance](https://github.com/eduard-s/table-proof/blob/main/benchmarks/README.md).
+
+## Python API
+
+```python
+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](https://github.com/eduard-s/table-proof/blob/main/docs/VISION.md).
+
+## Results and limits
+
+| Status | Meaning | CLI exit code |
+| --- | --- | --- |
+| `no_findings` | The selected checks found no error in the supplied evidence. | `0` |
+| `review` | At least one check found a suspected error. | `1` |
+| `uncertain` | Evidence is missing, ambiguous, or unsupported. | `3` |
+| `error` | The command did not process the input. | `2` |
+
+`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](https://github.com/eduard-s/table-proof/blob/main/benchmarks/results.md) 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](https://github.com/eduard-s/table-proof/blob/main/docs/VISION.md) before a model accuracy claim.
+
+## Development
+
+```sh
+.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](https://github.com/eduard-s/table-proof/blob/main/docs/MVP_PLAN.md)
+- [Architecture and Python stack](https://github.com/eduard-s/table-proof/blob/main/docs/ARCHITECTURE.md)
+- [API and report contract](https://github.com/eduard-s/table-proof/blob/main/docs/API.md)
+- [Datasets and evaluation plan](https://github.com/eduard-s/table-proof/blob/main/docs/DATASETS.md)
+- [Benchmark reproduction](https://github.com/eduard-s/table-proof/blob/main/benchmarks/README.md)
+- [Optional vision model](https://github.com/eduard-s/table-proof/blob/main/docs/VISION.md)
+- [Development and contribution](https://github.com/eduard-s/table-proof/blob/main/CONTRIBUTING.md)
+- [Release instructions](https://github.com/eduard-s/table-proof/blob/main/PUBLISHING.md)
+
+## License
+
+MIT. See [LICENSE](https://github.com/eduard-s/table-proof/blob/main/LICENSE) and [third-party notices](https://github.com/eduard-s/table-proof/blob/main/THIRD_PARTY.md).

table_proof_py-0.1.0/PUBLISHING.md

@@ -0,0 +1,85 @@
+# Publish TableProof
+
+The distribution name is `table-proof-py`. The Python import is `table_proof`. The command is `table-proof`.
+
+PyPI rejected `table-proof` because it was too similar to an existing project. Use `table-proof-py` for installation and publisher configuration.
+
+Version `0.1.0` is an alpha release. The current benchmark does not establish broad accuracy.
+
+The first release needs a pending trusted publisher for this repository. Later releases use that same publisher.
+
+## Local distribution
+
+```sh
+.venv/bin/python -m build
+.venv/bin/python -m twine check dist/*
+.venv/bin/python scripts/examine_distribution.py
+python3 -m venv .venv-wheel
+.venv-wheel/bin/python -m pip install dist/*.whl
+.venv-wheel/bin/python -m table_proof --version
+.venv-wheel/bin/python scripts/wheel_smoke.py
+```
+
+The wheel smoke test uses the recorded regression pair. It needs only the runtime dependencies.
+
+The archive examination rejects cache files, model weights, symbolic links, and unexpected paths. The source archive contains only selected project files.
+
+## Configure the first publication
+
+1. Sign in to the PyPI account that will own `table-proof-py`.
+2. Open [PyPI Publishing](https://pypi.org/manage/account/publishing/).
+3. Add a pending GitHub publisher with these values:
+
+| Field | Value |
+| --- | --- |
+| PyPI project name | `table-proof-py` |
+| GitHub owner | `eduard-s` |
+| GitHub repository | `table-proof` |
+| Workflow filename | `publish-python.yml` |
+| Environment | `pypi` |
+
+4. Create the `pypi` environment in this repository's GitHub settings.
+5. Examine the environment rules for the release account.
+
+The ToolBoundary publisher does not authorize this repository. This workflow uses GitHub OIDC and needs no stored PyPI token.
+
+A pending publisher does not reserve the package name. Read the [PyPI guide](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/).
+
+## Rehearse the release
+
+1. Open the repository's **Actions** page.
+2. Select **Publish Python**.
+3. Select **Run workflow** on `main`.
+4. Examine the distribution job and its artifacts.
+
+A manual run makes and examines the distributions. It does not publish them. Publication starts only from a pushed version tag.
+
+## Publish version 0.1.0
+
+After the publisher configuration and release examination, run these commands:
+
+```sh
+git switch main
+git pull --ff-only
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The tag must match the version in `pyproject.toml`. The workflow runs tests before publication.
+
+The publish job uses the exact distribution artifacts from the successful preparation job. It runs separately from the package tests.
+
+Read the [PyPI publication guide](https://docs.pypi.org/trusted-publishers/using-a-publisher/) for the authentication process.
+
+## Examine the public package
+
+After publication, run these commands from the repository root:
+
+```sh
+python3 -m venv .venv-published
+.venv-published/bin/python -m pip install --index-url https://pypi.org/simple 'table-proof-py==0.1.0'
+.venv-published/bin/python -m table_proof --version
+.venv-published/bin/python scripts/wheel_smoke.py
+```
+
+After publication, examine the PyPI page. Add its link to the README, profile, and website. Keep benchmark limitations visible.

table_proof_py-0.1.0/README.md

@@ -0,0 +1,140 @@
+# TableProof
+
+[![CI](https://github.com/eduard-s/table-proof/actions/workflows/ci.yml/badge.svg)](https://github.com/eduard-s/table-proof/actions/workflows/ci.yml)
+
+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
+
+```sh
+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:
+
+```sh
+python -m pip install 'table-proof-py[vision]'
+```
+
+## Try the real regression case
+
+The recorded regression pair contains this error:
+
+| Source row | Affected extracted row | Result |
+| --- | --- | --- |
+| `BBB → 20.0 mg` | `CCC → 20.0 mg` | Row label differs from the source region. |
+| `CCC → 30.0 mg` | `BBB → 30.0 mg` | Row label differs from the source region. |
+
+The regression fixtures are in the source repository. Run these commands:
+
+```sh
+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](https://github.com/eduard-s/table-proof/blob/main/benchmarks/results.md) and [fixture provenance](https://github.com/eduard-s/table-proof/blob/main/benchmarks/README.md).
+
+## Python API
+
+```python
+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](https://github.com/eduard-s/table-proof/blob/main/docs/VISION.md).
+
+## Results and limits
+
+| Status | Meaning | CLI exit code |
+| --- | --- | --- |
+| `no_findings` | The selected checks found no error in the supplied evidence. | `0` |
+| `review` | At least one check found a suspected error. | `1` |
+| `uncertain` | Evidence is missing, ambiguous, or unsupported. | `3` |
+| `error` | The command did not process the input. | `2` |
+
+`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](https://github.com/eduard-s/table-proof/blob/main/benchmarks/results.md) 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](https://github.com/eduard-s/table-proof/blob/main/docs/VISION.md) before a model accuracy claim.
+
+## Development
+
+```sh
+.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](https://github.com/eduard-s/table-proof/blob/main/docs/MVP_PLAN.md)
+- [Architecture and Python stack](https://github.com/eduard-s/table-proof/blob/main/docs/ARCHITECTURE.md)
+- [API and report contract](https://github.com/eduard-s/table-proof/blob/main/docs/API.md)
+- [Datasets and evaluation plan](https://github.com/eduard-s/table-proof/blob/main/docs/DATASETS.md)
+- [Benchmark reproduction](https://github.com/eduard-s/table-proof/blob/main/benchmarks/README.md)
+- [Optional vision model](https://github.com/eduard-s/table-proof/blob/main/docs/VISION.md)
+- [Development and contribution](https://github.com/eduard-s/table-proof/blob/main/CONTRIBUTING.md)
+- [Release instructions](https://github.com/eduard-s/table-proof/blob/main/PUBLISHING.md)
+
+## License
+
+MIT. See [LICENSE](https://github.com/eduard-s/table-proof/blob/main/LICENSE) and [third-party notices](https://github.com/eduard-s/table-proof/blob/main/THIRD_PARTY.md).

table_proof_py-0.1.0/THIRD_PARTY.md

@@ -0,0 +1,13 @@
+# Third-party materials
+
+TableProof uses the MIT license for its original code and generated fixtures.
+
+The benchmark adapts a public Docling-core regression reproducer and its proposed fix. Read [the benchmark notices](benchmarks/THIRD_PARTY.md).
+
+The optional Table Transformer checkpoint remains a separate download. Its [model card](https://huggingface.co/microsoft/table-transformer-structure-recognition-v1.1-all) supplies its metadata.
+
+The [upstream project](https://github.com/microsoft/table-transformer) provides model code, datasets, and evaluation resources. Dataset terms remain separate from TableProof's license.
+
+pdfmux is an optional benchmark dependency. Its upstream code runs in an isolated environment. TableProof does not distribute a copied pdfmux implementation.
+
+Each dependency distribution retains its own license files. The benchmark manifests record licenses for included source materials.

table_proof_py-0.1.0/benchmarks/DOCLING_LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 International Business Machines
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.