quire 0.1.0__tar.gz

quire-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

quire-0.1.0/NOTICE

@@ -0,0 +1,9 @@
+quire
+Copyright 2026 Shariq Farooqui
+
+This product includes software developed by Shariq Farooqui
+(https://github.com/shariq-farooqui/quire).
+
+This product bundles and depends on PaddleOCR, PaddleOCR-VL and PaddlePaddle,
+developed by the PaddlePaddle Authors and licensed under the Apache License,
+Version 2.0. See THIRD_PARTY_LICENSES.md for details.

quire-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: quire
+Version: 0.1.0
+Summary: PDF to clean markdown, powered by PaddleOCR-VL
+Keywords: ocr,pdf,markdown,paddleocr,document-parsing
+Author: Shariq Farooqui
+Author-email: Shariq Farooqui <shariq.farooqui@outlook.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+License-File: THIRD_PARTY_LICENSES.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Dist: paddleocr[doc-parser]==3.4.0
+Requires-Dist: paddlepaddle==3.2.0
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/shariq-farooqui/quire
+Project-URL: Repository, https://github.com/shariq-farooqui/quire
+Project-URL: Issues, https://github.com/shariq-farooqui/quire/issues
+Description-Content-Type: text/markdown
+
+# quire
+
+[![PyPI](https://img.shields.io/pypi/v/quire.svg)](https://pypi.org/project/quire/)
+[![Python versions](https://img.shields.io/pypi/pyversions/quire.svg)](https://pypi.org/project/quire/)
+[![Licence](https://img.shields.io/github/license/shariq-farooqui/quire.svg?label=licence)](https://github.com/shariq-farooqui/quire/blob/main/LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+OCR a PDF into clean markdown, powered by PaddleOCR-VL. Runs locally.
+No server, no containers, no signup.
+
+quire is built to be used through [uvx](https://docs.astral.sh/uv/guides/tools/),
+so there is nothing to install and nothing to clone. If you have
+[uv](https://docs.astral.sh/uv/getting-started/installation/) on your
+machine, you can OCR a PDF in one line.
+
+## Quick start
+
+```
+uvx quire document.pdf
+```
+
+That prints the cleaned markdown straight to stdout. The first run on
+a machine is slow because `uvx` installs quire's dependencies and
+PaddleOCR-VL downloads its model weights. After that it is cached and
+subsequent runs are fast.
+
+## Usage
+
+```
+# markdown to stdout
+uvx quire document.pdf
+
+# save markdown and the full structured json to a directory
+uvx quire document.pdf -o output/
+
+# print the full structured OCR result as json
+uvx quire document.pdf --json
+
+# suppress progress and timing output on stderr
+uvx quire document.pdf -q
+
+# show the version
+uvx quire --version
+```
+
+`-o output/` writes two files:
+
+- `document.md`, the cleaned markdown (same content as stdout)
+- `document_ocr.json`, a structured view with per-page blocks, bounding
+  boxes and block labels
+
+If you end up using quire often and want to drop the `uvx` prefix, you
+can install it once into a persistent uv tool environment:
+
+```
+uv tool install quire
+quire document.pdf
+```
+
+## Output format
+
+The json shape is:
+
+```json
+{
+  "page_count": 42,
+  "page_width": 1191,
+  "page_height": 1684,
+  "markdown": "# Document title\n\n...",
+  "pages": [
+    {
+      "page_index": 0,
+      "blocks": [
+        {
+          "block_label": "doc_title",
+          "block_content": "Document title",
+          "block_bbox": [211, 179, 780, 225],
+          "block_id": 0
+        }
+      ]
+    }
+  ]
+}
+```
+
+Block labels include `doc_title`, `paragraph_title`, `text`, `table`,
+`header` and `image`.
+
+HTML tables produced by PaddleOCR are converted to pipe tables in both
+the markdown and inside table blocks in the json, so the output is
+ready to use without a second cleanup pass.
+
+## Why CPU only
+
+quire ships with the CPU build of PaddlePaddle and runs inference on
+the CPU. This is an intentional limitation of the tool, not an
+oversight.
+
+The Paddle ecosystem publishes its CPU and CUDA builds as two separate
+PyPI packages (`paddlepaddle` and `paddlepaddle-gpu`), each with its
+own wheel index. They share the same `paddle` Python namespace and
+cannot be installed side by side, and Python packaging has no way to
+pick one based on the user's hardware. That means there is no honest
+way for a single uvx command to transparently use the GPU when one is
+available and the CPU when one is not.
+
+The whole point of quire is that `uvx quire document.pdf` just works on
+any machine without compiling or configuring anything. CPU is the only
+path that delivers that. If you need GPU throughput, reach for
+PaddleOCR directly; quire is a zero-setup wrapper, not a performance
+tool.
+
+## Outline helper for regulatory documents
+
+If you work with regulatory or legal PDFs that use Article, Annex,
+Chapter, Part and Section headings, quire ships a second command that
+extracts a quick outline from an existing OCR json:
+
+```
+uvx quire document.pdf -o output/
+uvx quire-outline output/document_ocr.json
+```
+
+It prints the title, reference code, and a list of sections with page
+ranges and word counts. Pass `--json` for a structured version. This
+is a niche helper; ignore it if your PDFs do not use those heading
+conventions.
+
+## Requirements
+
+- Python 3.11 or newer
+- Around 4 GB of free disk for PaddleOCR-VL model weights on first run
+- Linux x86_64 is the smoothest path. macOS and Windows should work as
+  long as PaddlePaddle ships a wheel for your platform.
+
+## Licence
+
+quire is licensed under the Apache License 2.0. It wraps PaddleOCR and
+the PaddleOCR-VL model weights, both developed by the PaddlePaddle
+Authors and distributed under Apache 2.0. See `LICENSE`, `NOTICE` and
+`THIRD_PARTY_LICENSES.md` for details.
+
+quire is an independent community wrapper. It is not affiliated with or
+endorsed by the PaddlePaddle project.

quire-0.1.0/README.md

@@ -0,0 +1,144 @@
+# quire
+
+[![PyPI](https://img.shields.io/pypi/v/quire.svg)](https://pypi.org/project/quire/)
+[![Python versions](https://img.shields.io/pypi/pyversions/quire.svg)](https://pypi.org/project/quire/)
+[![Licence](https://img.shields.io/github/license/shariq-farooqui/quire.svg?label=licence)](https://github.com/shariq-farooqui/quire/blob/main/LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+OCR a PDF into clean markdown, powered by PaddleOCR-VL. Runs locally.
+No server, no containers, no signup.
+
+quire is built to be used through [uvx](https://docs.astral.sh/uv/guides/tools/),
+so there is nothing to install and nothing to clone. If you have
+[uv](https://docs.astral.sh/uv/getting-started/installation/) on your
+machine, you can OCR a PDF in one line.
+
+## Quick start
+
+```
+uvx quire document.pdf
+```
+
+That prints the cleaned markdown straight to stdout. The first run on
+a machine is slow because `uvx` installs quire's dependencies and
+PaddleOCR-VL downloads its model weights. After that it is cached and
+subsequent runs are fast.
+
+## Usage
+
+```
+# markdown to stdout
+uvx quire document.pdf
+
+# save markdown and the full structured json to a directory
+uvx quire document.pdf -o output/
+
+# print the full structured OCR result as json
+uvx quire document.pdf --json
+
+# suppress progress and timing output on stderr
+uvx quire document.pdf -q
+
+# show the version
+uvx quire --version
+```
+
+`-o output/` writes two files:
+
+- `document.md`, the cleaned markdown (same content as stdout)
+- `document_ocr.json`, a structured view with per-page blocks, bounding
+  boxes and block labels
+
+If you end up using quire often and want to drop the `uvx` prefix, you
+can install it once into a persistent uv tool environment:
+
+```
+uv tool install quire
+quire document.pdf
+```
+
+## Output format
+
+The json shape is:
+
+```json
+{
+  "page_count": 42,
+  "page_width": 1191,
+  "page_height": 1684,
+  "markdown": "# Document title\n\n...",
+  "pages": [
+    {
+      "page_index": 0,
+      "blocks": [
+        {
+          "block_label": "doc_title",
+          "block_content": "Document title",
+          "block_bbox": [211, 179, 780, 225],
+          "block_id": 0
+        }
+      ]
+    }
+  ]
+}
+```
+
+Block labels include `doc_title`, `paragraph_title`, `text`, `table`,
+`header` and `image`.
+
+HTML tables produced by PaddleOCR are converted to pipe tables in both
+the markdown and inside table blocks in the json, so the output is
+ready to use without a second cleanup pass.
+
+## Why CPU only
+
+quire ships with the CPU build of PaddlePaddle and runs inference on
+the CPU. This is an intentional limitation of the tool, not an
+oversight.
+
+The Paddle ecosystem publishes its CPU and CUDA builds as two separate
+PyPI packages (`paddlepaddle` and `paddlepaddle-gpu`), each with its
+own wheel index. They share the same `paddle` Python namespace and
+cannot be installed side by side, and Python packaging has no way to
+pick one based on the user's hardware. That means there is no honest
+way for a single uvx command to transparently use the GPU when one is
+available and the CPU when one is not.
+
+The whole point of quire is that `uvx quire document.pdf` just works on
+any machine without compiling or configuring anything. CPU is the only
+path that delivers that. If you need GPU throughput, reach for
+PaddleOCR directly; quire is a zero-setup wrapper, not a performance
+tool.
+
+## Outline helper for regulatory documents
+
+If you work with regulatory or legal PDFs that use Article, Annex,
+Chapter, Part and Section headings, quire ships a second command that
+extracts a quick outline from an existing OCR json:
+
+```
+uvx quire document.pdf -o output/
+uvx quire-outline output/document_ocr.json
+```
+
+It prints the title, reference code, and a list of sections with page
+ranges and word counts. Pass `--json` for a structured version. This
+is a niche helper; ignore it if your PDFs do not use those heading
+conventions.
+
+## Requirements
+
+- Python 3.11 or newer
+- Around 4 GB of free disk for PaddleOCR-VL model weights on first run
+- Linux x86_64 is the smoothest path. macOS and Windows should work as
+  long as PaddlePaddle ships a wheel for your platform.
+
+## Licence
+
+quire is licensed under the Apache License 2.0. It wraps PaddleOCR and
+the PaddleOCR-VL model weights, both developed by the PaddlePaddle
+Authors and distributed under Apache 2.0. See `LICENSE`, `NOTICE` and
+`THIRD_PARTY_LICENSES.md` for details.
+
+quire is an independent community wrapper. It is not affiliated with or
+endorsed by the PaddlePaddle project.

quire-0.1.0/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,32 @@
+# Third-party licenses
+
+quire depends on the following third-party projects. At runtime it loads
+PaddleOCR-VL model weights and calls into PaddleOCR and PaddlePaddle. All
+three are distributed under the Apache License, Version 2.0.
+
+## PaddleOCR
+
+- Project: https://github.com/PaddlePaddle/PaddleOCR
+- Copyright: The PaddlePaddle Authors
+- License: Apache License 2.0
+- License text: https://github.com/PaddlePaddle/PaddleOCR/blob/main/LICENSE
+
+## PaddleOCR-VL (model weights)
+
+- Project: https://huggingface.co/PaddlePaddle/PaddleOCR-VL
+- Copyright: The PaddlePaddle Authors
+- License: Apache License 2.0
+- License text: https://huggingface.co/PaddlePaddle/PaddleOCR-VL/blob/main/LICENSE
+
+## PaddlePaddle
+
+- Project: https://github.com/PaddlePaddle/Paddle
+- Copyright: The PaddlePaddle Authors
+- License: Apache License 2.0
+- License text: https://github.com/PaddlePaddle/Paddle/blob/develop/LICENSE
+
+## The Apache License 2.0
+
+The full text of the Apache License 2.0 is in the LICENSE file at the root
+of this repository and applies to quire itself as well as to each of the
+bundled third-party projects listed above.

quire-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "quire"
+version = "0.1.0"
+description = "PDF to clean markdown, powered by PaddleOCR-VL"
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE", "THIRD_PARTY_LICENSES.md"]
+authors = [
+    { name = "Shariq Farooqui", email = "shariq.farooqui@outlook.com" },
+]
+keywords = ["ocr", "pdf", "markdown", "paddleocr", "document-parsing"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+    "Topic :: Text Processing :: Markup :: Markdown",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "paddleocr[doc-parser]==3.4.0",
+    "paddlepaddle==3.2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/shariq-farooqui/quire"
+Repository = "https://github.com/shariq-farooqui/quire"
+Issues = "https://github.com/shariq-farooqui/quire/issues"
+
+[project.scripts]
+quire = "quire.cli:main"
+quire-outline = "quire.cli:outline_main"
+
+[build-system]
+requires = ["uv_build>=0.11.3,<0.12.0"]
+build-backend = "uv_build"
+
+[[tool.uv.index]]
+name = "paddlepaddle"
+url = "https://www.paddlepaddle.org.cn/packages/stable/cpu/"
+explicit = true
+
+[tool.uv.sources]
+paddlepaddle = { index = "paddlepaddle" }
+
+[tool.uv]
+index-strategy = "unsafe-best-match"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = ["-ra", "--strict-config", "--strict-markers"]
+
+[dependency-groups]
+dev = [
+    "pytest==9.0.3",
+]

quire-0.1.0/src/quire/__init__.py

@@ -0,0 +1,46 @@
+"""quire: PDF to clean markdown, powered by PaddleOCR-VL.
+
+Public API:
+
+- `run_ocr(pdf_path)` runs PaddleOCR-VL on a PDF and returns a
+  structured result.
+- `store_result`, `load_result` round-trip an OCR result through disk.
+- `build_outline` extracts a flat regulatory-style outline from an
+  existing OCR result (mostly useful for legal documents).
+
+Two console scripts are installed by the package: `quire` (the main
+OCR command) and `quire-outline` (the niche outline helper). Both run
+happily under `uvx`.
+"""
+
+from quire.ocr import (
+    OcrBlock,
+    OcrPageResult,
+    OcrResult,
+    load_result,
+    run_ocr,
+    store_result,
+)
+from quire.outline import (
+    Outline,
+    OutlineSection,
+    build_outline,
+    get_pages_text,
+    get_section_text,
+)
+
+__all__ = [
+    "OcrBlock",
+    "OcrPageResult",
+    "OcrResult",
+    "Outline",
+    "OutlineSection",
+    "build_outline",
+    "get_pages_text",
+    "get_section_text",
+    "load_result",
+    "run_ocr",
+    "store_result",
+]
+
+__version__ = "0.1.0"

quire-0.1.0/src/quire/cli.py

@@ -0,0 +1,183 @@
+"""Command line interfaces for the `quire` and `quire-outline` tools."""
+
+import argparse
+import json
+import logging
+import sys
+import time
+from pathlib import Path
+
+from quire import __version__
+from quire.ocr import load_result, run_ocr, store_result
+from quire.outline import build_outline
+
+log = logging.getLogger("quire")
+
+
+def _setup_logging(quiet: bool) -> None:
+    level = logging.WARNING if quiet else logging.INFO
+    logging.basicConfig(level=level, format="%(message)s", stream=sys.stderr)
+
+
+def _file_size_str(path: Path) -> str:
+    size = path.stat().st_size
+    if size < 1024:
+        return f"{size} B"
+    if size < 1024 * 1024:
+        return f"{size / 1024:.1f} KB"
+    return f"{size / (1024 * 1024):.1f} MB"
+
+
+def _ocr_pdf(pdf: Path) -> dict:
+    t0 = time.time()
+    result = run_ocr(pdf)
+    elapsed = time.time() - t0
+    log.info(
+        "OCR done in %.1fs: %d pages, %d blocks",
+        elapsed,
+        result["page_count"],
+        sum(len(p["blocks"]) for p in result["pages"]),
+    )
+    return result
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the `quire` command.
+
+    Parses arguments, runs the PaddleOCR-VL pipeline on the given PDF,
+    and either prints the result to stdout or writes it to a directory
+    depending on the flags. Returns a process exit code.
+    """
+    parser = argparse.ArgumentParser(
+        prog="quire",
+        description="PDF to clean markdown, powered by PaddleOCR-VL.",
+    )
+    parser.add_argument("pdf", type=Path, help="Path to a PDF file")
+    parser.add_argument(
+        "-o",
+        "--output-dir",
+        type=Path,
+        default=None,
+        help="Write <stem>.md and <stem>_ocr.json to this directory",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Print the full OCR result as JSON to stdout instead of markdown",
+    )
+    parser.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        help="Suppress progress and timing output on stderr",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"quire {__version__}",
+    )
+
+    args = parser.parse_args(argv)
+    _setup_logging(args.quiet)
+
+    if not args.pdf.exists():
+        log.error("File not found: %s", args.pdf)
+        return 1
+    if not args.pdf.is_file():
+        log.error("Not a file: %s", args.pdf)
+        return 1
+
+    if args.output_dir is not None and args.json:
+        log.error("--json and --output-dir cannot be combined")
+        return 2
+
+    result = _ocr_pdf(args.pdf)
+
+    if args.output_dir is not None:
+        json_path, md_path = store_result(result, args.output_dir, args.pdf.stem)
+        log.info("  %s (%s)", md_path, _file_size_str(md_path))
+        log.info("  %s (%s)", json_path, _file_size_str(json_path))
+        return 0
+
+    if args.json:
+        json.dump(result, sys.stdout, ensure_ascii=False, indent=2)
+        sys.stdout.write("\n")
+    else:
+        sys.stdout.write(result["markdown"])
+        if not result["markdown"].endswith("\n"):
+            sys.stdout.write("\n")
+
+    return 0
+
+
+def outline_main(argv: list[str] | None = None) -> int:
+    """Entry point for the `quire-outline` command.
+
+    Loads an OCR json produced by `quire`, builds an outline from it and
+    prints it either as a plain text summary or as json. Returns a
+    process exit code.
+    """
+    parser = argparse.ArgumentParser(
+        prog="quire-outline",
+        description=(
+            "Extract an outline from an OCR JSON produced by quire. "
+            "Looks for Article, Annex, Chapter, Part and Section headings, "
+            "so it is most useful on regulatory or legal documents."
+        ),
+    )
+    parser.add_argument(
+        "json_path",
+        type=Path,
+        metavar="OCR_JSON",
+        help="Path to an OCR JSON file produced by 'quire <pdf> -o <dir>'",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_output",
+        help="Print the outline as JSON instead of plain text",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"quire {__version__}",
+    )
+
+    args = parser.parse_args(argv)
+    _setup_logging(quiet=False)
+
+    if not args.json_path.exists():
+        log.error("File not found: %s", args.json_path)
+        return 1
+
+    ocr_result = load_result(args.json_path)
+    outline = build_outline(ocr_result)
+
+    if args.json_output:
+        json.dump(outline, sys.stdout, ensure_ascii=False, indent=2)
+        sys.stdout.write("\n")
+        return 0
+
+    print(f"Title:     {outline['title'] or '(none)'}")
+    print(f"Reference: {outline['reference_code'] or '(none)'}")
+    print(f"Pages:     {outline['page_count']}")
+    print(f"Words:     {outline['total_words']:,}")
+    print(f"Blocks:    {outline['total_blocks']}")
+    types = ", ".join(f"{k}({v})" for k, v in outline["block_type_summary"].items())
+    print(f"Types:     {types}")
+
+    sections = outline["sections"]
+    if sections:
+        print(f"\nSections ({len(sections)}):")
+        for s in sections:
+            title_part = f"  {s['title']}" if s["title"] else ""
+            print(
+                f"  {s['reference']:<20s} (p.{s['start_page']}-{s['end_page']})"
+                f"{title_part}    {s['word_count']:,} words"
+            )
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

quire-0.1.0/src/quire/ocr.py

@@ -0,0 +1,254 @@
+"""PaddleOCR-VL pipeline wrapper and result helpers."""
+
+import copy
+import json
+import logging
+import os
+import re
+import threading
+from html.parser import HTMLParser
+from pathlib import Path
+from typing import TypedDict
+
+os.environ.setdefault("PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK", "True")
+
+log = logging.getLogger(__name__)
+
+_pipeline = None
+_pipeline_lock = threading.Lock()
+
+
+class OcrBlock(TypedDict):
+    """A single layout block detected on a page.
+
+    `block_bbox` is `[x_min, y_min, x_max, y_max]` in the source page's
+    pixel coordinates. `block_label` is one of PaddleOCR-VL's layout
+    categories, for example `doc_title`, `paragraph_title`, `text`,
+    `table`, `header` or `image`.
+    """
+
+    block_label: str
+    block_content: str
+    block_bbox: list[int]
+    block_id: int
+
+
+class OcrPageResult(TypedDict):
+    """The blocks belonging to one page of a PDF. `page_index` is 0-indexed."""
+
+    page_index: int
+    blocks: list[OcrBlock]
+
+
+class OcrResult(TypedDict):
+    """Full structured OCR output for a PDF.
+
+    `markdown` is the cleaned concatenation across all pages, with any
+    HTML tables rewritten as pipe tables. `pages` holds per-page blocks
+    for downstream layout work. `page_width` and `page_height` come
+    from the first page only.
+    """
+
+    page_count: int
+    page_width: int
+    page_height: int
+    markdown: str
+    pages: list[OcrPageResult]
+
+
+def _get_pipeline():
+    global _pipeline
+    if _pipeline is None:
+        with _pipeline_lock:
+            if _pipeline is None:
+                from paddleocr import PaddleOCRVL
+
+                log.info("Loading PaddleOCR-VL pipeline")
+                _pipeline = PaddleOCRVL(device="cpu")
+    return _pipeline
+
+
+class _TableParser(HTMLParser):
+    def __init__(self):
+        super().__init__()
+        self.rows: list[list[str]] = []
+        self._current_row: list[str] = []
+        self._current_cell: list[str] = []
+        self._in_cell = False
+        self._is_header_row = False
+        self._has_header = False
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]):
+        if tag == "tr":
+            self._current_row = []
+            self._is_header_row = False
+        elif tag in ("td", "th"):
+            self._in_cell = True
+            self._current_cell = []
+            if tag == "th":
+                self._is_header_row = True
+
+    def handle_endtag(self, tag: str):
+        if tag in ("td", "th"):
+            self._in_cell = False
+            self._current_row.append("".join(self._current_cell).strip())
+        elif tag == "tr":
+            if self._current_row:
+                self.rows.append(self._current_row)
+                if self._is_header_row:
+                    self._has_header = True
+
+    def handle_data(self, data: str):
+        if self._in_cell:
+            self._current_cell.append(data)
+
+    def to_markdown(self) -> str:
+        if not self.rows:
+            return ""
+        col_count = max(len(row) for row in self.rows)
+        lines = []
+        for i, row in enumerate(self.rows):
+            padded = row + [""] * (col_count - len(row))
+            lines.append("| " + " | ".join(padded) + " |")
+            if i == 0:
+                lines.append("| " + " | ".join("---" for _ in range(col_count)) + " |")
+        return "\n".join(lines)
+
+
+_TABLE_RE = re.compile(r"<table[^>]*>.*?</table>", re.DOTALL | re.IGNORECASE)
+
+
+def run_ocr(pdf_path: Path) -> OcrResult:
+    """Run PaddleOCR-VL on a PDF and return the full structured result.
+
+    Loads the PaddleOCR-VL pipeline on first call, which triggers a
+    model weights download the first time on a given machine and is
+    slow. The pipeline is cached for the rest of the process, so
+    repeated calls inside the same run are fast.
+
+    Each page is processed twice on purpose: once in isolation to keep
+    accurate per-page blocks and bounding boxes, and once concatenated
+    so that cross-page tables and titles merge cleanly in the markdown.
+
+    Args:
+        pdf_path: Path to the PDF file to OCR.
+
+    Returns:
+        An `OcrResult` with page count, first-page dimensions, cleaned
+        markdown and per-page blocks with bounding boxes.
+    """
+    pipeline = _get_pipeline()
+    pages_res = list(pipeline.predict(str(pdf_path)))
+    pages_res_for_concat = copy.deepcopy(pages_res)
+
+    per_page = []
+    for page_res in pages_res:
+        results = list(
+            pipeline.restructure_pages(
+                [copy.deepcopy(page_res)],
+                merge_tables=True,
+                relevel_titles=True,
+                concatenate_pages=False,
+            )
+        )
+        per_page.append(results[-1])
+
+    concatenated = list(
+        pipeline.restructure_pages(
+            pages_res_for_concat,
+            merge_tables=True,
+            relevel_titles=True,
+            concatenate_pages=True,
+        )
+    )
+
+    concat_result = concatenated[0]
+    markdown_raw = concat_result.markdown
+    markdown_text = (
+        markdown_raw["markdown_texts"] if isinstance(markdown_raw, dict) else markdown_raw
+    )
+    markdown = _clean_html_tables(markdown_text)
+
+    first_page_meta = per_page[0].json["res"]
+    page_count = len(pages_res)
+    page_width = first_page_meta.get("width", 0)
+    page_height = first_page_meta.get("height", 0)
+
+    pages = _build_page_blocks(per_page)
+
+    return OcrResult(
+        page_count=page_count,
+        page_width=page_width,
+        page_height=page_height,
+        markdown=markdown,
+        pages=pages,
+    )
+
+
+def _clean_html_tables(markdown: str) -> str:
+    def _replace_table(match: re.Match) -> str:
+        parser = _TableParser()
+        parser.feed(match.group(0))
+        converted = parser.to_markdown()
+        return converted if converted else match.group(0)
+
+    return _TABLE_RE.sub(_replace_table, markdown)
+
+
+def _parse_bbox(bbox) -> list[int]:
+    if isinstance(bbox, list):
+        return bbox
+    if isinstance(bbox, str):
+        try:
+            return json.loads(bbox)
+        except (json.JSONDecodeError, ValueError):
+            return []
+    return []
+
+
+def _build_page_blocks(per_page_results: list) -> list[OcrPageResult]:
+    pages: list[OcrPageResult] = []
+    for page_index, result in enumerate(per_page_results):
+        blocks: list[OcrBlock] = []
+        parsing_res = result.json["res"].get("parsing_res_list", [])
+        for item in parsing_res:
+            content = item.get("block_content", "")
+            if item.get("block_label") == "table" and _TABLE_RE.search(content):
+                content = _clean_html_tables(content)
+            blocks.append(
+                OcrBlock(
+                    block_label=item.get("block_label", ""),
+                    block_content=content,
+                    block_bbox=_parse_bbox(item.get("block_bbox", [])),
+                    block_id=int(item.get("block_id", 0)),
+                )
+            )
+        pages.append(
+            OcrPageResult(
+                page_index=page_index,
+                blocks=blocks,
+            )
+        )
+    return pages
+
+
+def store_result(result: OcrResult, output_dir: Path, stem: str) -> tuple[Path, Path]:
+    """Write an OCR result to disk as two files.
+
+    Creates `<output_dir>/<stem>_ocr.json` with the full structured
+    result and `<output_dir>/<stem>.md` with just the cleaned markdown.
+    The directory is created if it does not already exist.
+
+    Returns the json and markdown paths, in that order.
+    """
+    output_dir.mkdir(parents=True, exist_ok=True)
+    json_path = output_dir / f"{stem}_ocr.json"
+    json_path.write_text(json.dumps(result, ensure_ascii=False, indent=2))
+    md_path = output_dir / f"{stem}.md"
+    md_path.write_text(result["markdown"])
+    return json_path, md_path
+
+
+def load_result(json_path: Path) -> OcrResult:
+    """Read back an OCR result previously saved with `store_result`."""
+    return json.loads(json_path.read_text())

quire-0.1.0/src/quire/outline.py

@@ -0,0 +1,253 @@
+"""Extract a flat outline from an OCR result for regulatory documents.
+
+This module scans the block list of an `OcrResult` for headings that
+match conventional regulatory section patterns such as `Article N`,
+`Annex X`, `Chapter X`, `Part X` and `Section N`, and builds a flat
+list of sections with page ranges and word counts. It is tuned for
+legal and regulatory PDFs and will return an empty section list on
+most other documents.
+"""
+
+import re
+from collections import Counter
+from typing import TypedDict
+
+_SECTION_RE = re.compile(
+    r"^(Article\s+\d+|Annex\s+[A-Z0-9IVXLC]+|ANNEX\s+[A-Z0-9IVXLC]+|"
+    r"Chapter\s+[A-Z0-9IVXLC]+|CHAPTER\s+[A-Z0-9IVXLC]+|"
+    r"Part\s+[A-Z0-9]+|PART\s+[A-Z0-9]+|Section\s+\d+|SECTION\s+\d+)",
+    re.IGNORECASE,
+)
+
+
+class OutlineSection(TypedDict):
+    """A single section in an `Outline`.
+
+    `reference` is the heading as it appeared in the PDF, normalised to
+    Title Case (e.g. `"Article 12"`, `"Annex IV"`). `title` is the
+    following heading if one exists, or an empty string. `start_page`
+    and `end_page` are 1-indexed and inclusive. `body_snippet` is the
+    first 300 characters of the section body, useful for previews.
+    """
+
+    reference: str
+    title: str
+    start_page: int
+    end_page: int
+    word_count: int
+    block_counts: dict[str, int]
+    body_snippet: str
+
+
+class Outline(TypedDict):
+    """A flat outline of a document.
+
+    `reference_code` is a guess at the document's identifier from the
+    first page header (e.g. an EU regulation number). `sections` is a
+    sorted list of section entries. The other fields are global
+    counters across the full document.
+    """
+
+    title: str
+    reference_code: str
+    page_count: int
+    total_words: int
+    total_blocks: int
+    block_type_summary: dict[str, int]
+    sections: list[OutlineSection]
+
+
+def build_outline(ocr_result: dict) -> Outline:
+    """Build an `Outline` from an `OcrResult` dict.
+
+    Walks every block on every page, picks out the document title and
+    reference code from the first couple of pages, then looks for
+    paragraph titles and doc titles matching the regulatory section
+    regex and assembles a sorted list of sections with page ranges and
+    word counts.
+
+    When the same reference appears more than once (a common quirk of
+    PaddleOCR-VL on running headers), the entry with a meaningful body
+    is preferred and the rest are dropped.
+
+    Args:
+        ocr_result: An `OcrResult` dict (or any dict with the same
+            shape) as produced by `quire.run_ocr` or `quire.load_result`.
+
+    Returns:
+        An `Outline` TypedDict. The `sections` list is empty for
+        documents that do not use the expected heading conventions.
+    """
+    pages = ocr_result.get("pages", [])
+    outline: Outline = {
+        "title": "",
+        "reference_code": "",
+        "page_count": ocr_result.get("page_count", len(pages)),
+        "total_words": 0,
+        "total_blocks": 0,
+        "block_type_summary": {},
+        "sections": [],
+    }
+
+    _extract_title(pages, outline)
+    _extract_reference_code(pages, outline)
+    _compute_global_stats(pages, outline)
+    _extract_sections(pages, outline)
+
+    return outline
+
+
+def get_section_text(ocr_result: dict, section: OutlineSection) -> str:
+    """Return the full text of a section as a single joined string.
+
+    Concatenates every non-empty block on pages within the section's
+    `start_page..end_page` range, with one block per line.
+    """
+    pages = ocr_result.get("pages", [])
+    parts: list[str] = []
+    for page in pages:
+        page_num = page.get("page_index", 0) + 1
+        if page_num < section["start_page"] or page_num > section["end_page"]:
+            continue
+        for block in page.get("blocks", []):
+            content = block.get("block_content", "").strip()
+            if content:
+                parts.append(content)
+    return "\n".join(parts)
+
+
+def get_pages_text(ocr_result: dict, start_page: int, end_page: int) -> str:
+    """Return the text of a page range as a single joined string.
+
+    Page numbers are 1-indexed and both bounds are inclusive.
+    """
+    pages = ocr_result.get("pages", [])
+    parts: list[str] = []
+    for page in pages:
+        page_num = page.get("page_index", 0) + 1
+        if page_num < start_page or page_num > end_page:
+            continue
+        for block in page.get("blocks", []):
+            content = block.get("block_content", "").strip()
+            if content:
+                parts.append(content)
+    return "\n".join(parts)
+
+
+def _extract_title(pages: list[dict], outline: Outline) -> None:
+    for page in pages[:3]:
+        for block in page.get("blocks", []):
+            if block.get("block_label") == "doc_title":
+                outline["title"] = block.get("block_content", "").strip()
+                return
+
+
+def _extract_reference_code(pages: list[dict], outline: Outline) -> None:
+    for page in pages[:2]:
+        for block in page.get("blocks", []):
+            if block.get("block_label") == "header":
+                content = block.get("block_content", "").strip()
+                if content and any(c.isdigit() for c in content):
+                    outline["reference_code"] = content.split()[0] if content.split() else content
+                    return
+
+
+def _compute_global_stats(pages: list[dict], outline: Outline) -> None:
+    label_counts: Counter[str] = Counter()
+    total_words = 0
+
+    for page in pages:
+        for block in page.get("blocks", []):
+            label = block.get("block_label", "unknown")
+            label_counts[label] += 1
+            content = block.get("block_content", "")
+            total_words += len(content.split())
+
+    outline["total_words"] = total_words
+    outline["total_blocks"] = sum(label_counts.values())
+    outline["block_type_summary"] = dict(label_counts.most_common())
+
+
+def _extract_sections(pages: list[dict], outline: Outline) -> None:
+    raw_headings: list[dict] = []
+
+    for page in pages:
+        page_num = page.get("page_index", 0) + 1
+        blocks = page.get("blocks", [])
+
+        for i, block in enumerate(blocks):
+            label = block.get("block_label", "")
+            content = block.get("block_content", "").strip()
+            if label not in ("paragraph_title", "doc_title"):
+                continue
+            match = _SECTION_RE.match(content)
+            if not match:
+                continue
+
+            reference = match.group(0)
+            if reference.split()[0].isupper():
+                reference = reference.split()[0].title() + " " + " ".join(reference.split()[1:])
+
+            title = ""
+            body_snippet = ""
+            body_chars = 0
+            for j in range(i + 1, len(blocks)):
+                nxt = blocks[j]
+                nxt_label = nxt.get("block_label", "")
+                nxt_content = nxt.get("block_content", "").strip()
+                if not nxt_content:
+                    continue
+                if nxt_label in ("paragraph_title", "doc_title") and _SECTION_RE.match(nxt_content):
+                    break
+                if nxt_label == "paragraph_title" and not title:
+                    title = nxt_content
+                    continue
+                body_chars += len(nxt_content)
+                if len(body_snippet) < 300:
+                    body_snippet += nxt_content[: 300 - len(body_snippet)] + " "
+
+            raw_headings.append(
+                {
+                    "reference": reference,
+                    "title": title,
+                    "page_num": page_num,
+                    "body_chars": body_chars,
+                    "body_snippet": body_snippet.strip(),
+                }
+            )
+
+    by_ref: dict[str, list[dict]] = {}
+    for h in raw_headings:
+        by_ref.setdefault(h["reference"], []).append(h)
+
+    deduped: list[dict] = []
+    for entries in by_ref.values():
+        with_body = [e for e in entries if e["body_chars"] > 50]
+        chosen = with_body[0] if with_body else entries[-1]
+        deduped.append(chosen)
+
+    deduped.sort(key=lambda s: s["page_num"])
+
+    for i, s in enumerate(deduped):
+        end_page = deduped[i + 1]["page_num"] if i + 1 < len(deduped) else outline["page_count"]
+
+        block_counts: Counter[str] = Counter()
+        word_count = 0
+        for page in pages:
+            pn = page.get("page_index", 0) + 1
+            if s["page_num"] <= pn <= end_page:
+                for block in page.get("blocks", []):
+                    block_counts[block.get("block_label", "text")] += 1
+                    word_count += len(block.get("block_content", "").split())
+
+        outline["sections"].append(
+            OutlineSection(
+                reference=s["reference"],
+                title=s["title"],
+                start_page=s["page_num"],
+                end_page=end_page,
+                word_count=word_count,
+                block_counts=dict(block_counts),
+                body_snippet=s["body_snippet"],
+            )
+        )