docvortex 0.4.1__tar.gz → 0.4.2__tar.gz

docvortex-0.4.2/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: docvortex
+Version: 0.4.2
+Summary: A fast, multi-format document parsing and conversion engine
+License-Expression: MIT
+Project-URL: Repository, https://github.com/myhloli/DocVortex
+Project-URL: Issues, https://github.com/myhloli/DocVortex/issues
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: click>=8.1.7
+Requires-Dist: loguru>=0.7.2
+Requires-Dist: numpy>=1.21.6
+Requires-Dist: pillow>=11.0.0
+Requires-Dist: pypdfium2<6,>=5.10.1
+Requires-Dist: pypdf>=5.6.0
+Requires-Dist: pydantic<3,>=2.12.5
+Requires-Dist: metafile-render<1.0.0,>=0.3.0
+Requires-Dist: ftfy<7,>=6.3.1
+Requires-Dist: fonttools<5,>=4
+Requires-Dist: beautifulsoup4<5,>=4.13.5
+Requires-Dist: lxml<7,>=4
+Requires-Dist: nh3<0.4,>=0.3.6
+Requires-Dist: python-docx<2,>=1.2.0
+Requires-Dist: pypptx-with-oxml<2,>=1.0.3
+Requires-Dist: mammoth<2,>=1.11.0
+Requires-Dist: openpyxl<4,>=3.1.5
+Requires-Dist: olefile<1,>=0.47
+Requires-Dist: pylatexenc<3,>=2.10
+Requires-Dist: latex2mathml<4,>=3.81.0
+Requires-Dist: mathml2omml==0.0.2
+Requires-Dist: resvg_py<0.6,>=0.5.0
+Requires-Dist: reportlab
+Requires-Dist: ziamath<0.14,>=0.13
+Requires-Dist: magika<1.1.0,>=0.6.2
+Requires-Dist: opencv-python>=4.11.0.86
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: markdown; extra == "test"
+Requires-Dist: jsonschema<5,>=4; extra == "test"
+Provides-Extra: dev
+Requires-Dist: ruff==0.14.2; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/myhloli/DocVortex/main/docs/images/docvortex-logo.jpg" alt="DocVortex logo" width="200">
+
+# DocVortex
+
+**Native document parsing. One structure, many outputs.**
+
+[![PyPI](https://img.shields.io/pypi/v/docvortex?color=008cff)](https://pypi.org/project/docvortex/)
+[![Python](https://img.shields.io/pypi/pyversions/docvortex)](https://pypi.org/project/docvortex/)
+[![CI](https://github.com/myhloli/DocVortex/actions/workflows/ci.yml/badge.svg)](https://github.com/myhloli/DocVortex/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/myhloli/DocVortex/blob/main/LICENSE.md)
+
+**English** · [简体中文](https://github.com/myhloli/DocVortex/blob/main/README_zh-CN.md)
+
+[Quick start](#quick-start) · [Formats](#supported-formats) · [Documentation](#documentation)
+
+</div>
+
+## Documents in. Possibilities out.
+
+DocVortex is a standalone Python engine for parsing and converting documents.
+It reads native text and document structure into a unified representation,
+then exports the result in the formats your workflow needs.
+
+- **Multi-format input** — read text PDFs, Office files, OpenDocument files, EPUB, HTML, OFD and CSV.
+- **Parse once, export many times** — reuse the same result for Markdown, HTML, LaTeX, DOCX, EPUB, PDF and structured JSON.
+- **Portable results** — save document structure and image assets in a Bundle, then export again without the source file.
+- **Composable APIs** — use the complete pipeline or integrate analysis, postprocessing and rendering separately.
+
+Native parsing works without an OCR or VLM inference service. Use DocVortex
+directly through its CLI or Python SDK, independently of MinerU.
+
+![DocVortex pipeline: native documents become a unified representation, then Markdown, HTML, LaTeX, DOCX, EPUB, PDF or structured JSON.](https://raw.githubusercontent.com/myhloli/DocVortex/main/docs/images/docvortex-overview.jpg)
+
+## Quick start
+
+Requires **Python 3.10–3.14**.
+
+### Install
+
+```bash
+pip install docvortex
+```
+
+### Command line
+
+Convert a text PDF to Markdown:
+
+```bash
+docvortex convert report.pdf --format markdown --output output/report.md
+```
+
+Replace `report.pdf` with a local file in any supported input format.
+Use `--format` to choose the output; run `docvortex convert --help` for options.
+
+### Python
+
+Parse a document once and export it twice:
+
+```python
+import docvortex
+
+result = docvortex.parse("report.pdf")
+result.export("output/report.md", output_format="markdown")
+result.export("output/report.docx", output_format="docx")
+```
+
+The result owns its document structure and assets, so further exports do not
+reopen or reparse the source. Existing output files are protected by default;
+use `overwrite=True` in Python or `--overwrite` in the CLI to replace them.
+
+## Supported formats
+
+### Native inputs · 15 formats
+
+| Document family | Formats |
+| --- | --- |
+| PDF with native text | PDF |
+| Word & rich text | DOC, DOCX, RTF |
+| Presentations | PPT, PPTX |
+| Spreadsheets | XLS, XLSX, CSV |
+| OpenDocument | ODT, ODS, ODP |
+| E-books & web documents | EPUB, HTML |
+| Open Fixed-layout Document | OFD |
+
+### Outputs · 7 formats
+
+| Output | `--format` / `output_format` |
+| --- | --- |
+| Markdown | `markdown` |
+| HTML | `html` |
+| LaTeX | `latex` |
+| Word document | `docx` |
+| EPUB e-book | `epub` |
+| PDF | `pdf` |
+| Structured JSON | `structured_content` |
+
+PPT/PPTX and XLS/XLSX are input formats only. Structured JSON is an export
+format; the [document JSON protocol](https://github.com/myhloli/DocVortex/blob/main/docs/JSON_PROTOCOL.md)
+separately defines the analysis and intermediate representations.
+
+## Save now, export later
+
+A Bundle packages the parsed document and its image assets for reuse across
+processes or machines. Load it whenever you need another output format:
+
+```python
+import docvortex
+
+result = docvortex.parse("report.pdf")
+result.save_bundle("output/report.bundle")
+
+restored = docvortex.load_bundle("output/report.bundle")
+restored.export("output/report.epub", output_format="epub")
+```
+
+The restored result works without the original file. See the
+[usage guide](https://github.com/myhloli/DocVortex/blob/main/docs/USAGE.md#portable-bundles)
+for Bundle contents, asset handling and overwrite rules.
+
+Need only the title, authors or other source properties?
+[`docvortex.extract_metadata()`](https://github.com/myhloli/DocVortex/blob/main/docs/METADATA.md)
+reads metadata without parsing the document body.
+
+## Choose the right workflow
+
+- **Text PDFs:** native parsing uses the document's existing text and structure. Scanned pages requiring OCR need an external OCR or inference service.
+- **PDF classification:** `docvortex classify report.pdf` returns `txt` or `ocr`. Classification is explicit and does not start inference; parsing does not automatically switch backends.
+- **PDF export:** PDF sources with page geometry default to block layout restoration, with selectable text and region images for tables/charts. Other sources and older results use semantic reflow. Use `--pdf-layout original|reflow` to select explicitly; fonts, line breaks and drawing instructions are not reproduced losslessly. See [PDF output layout](docs/USAGE.md#pdf-output-layout).
+
+## Documentation
+
+| Guide | What you will find |
+| --- | --- |
+| [Usage](https://github.com/myhloli/DocVortex/blob/main/docs/USAGE.md) | Stage APIs, PDF pages, classification, images and Bundles |
+| [Agent skill](skills/docvortex/SKILL.md) | CLI and Python SDK workflows for agents; copy the entire `skills/docvortex` folder to reuse |
+| [Examples](https://github.com/myhloli/DocVortex/blob/main/demo/README.md) | Local PDF and Office samples with a runnable demo |
+| [Metadata](https://github.com/myhloli/DocVortex/blob/main/docs/METADATA.md) | Source properties and per-format coverage |
+| [JSON protocol](https://github.com/myhloli/DocVortex/blob/main/docs/JSON_PROTOCOL.md) | Document schemas, extensions and protocol migration |
+| [HTML protocol](https://github.com/myhloli/DocVortex/blob/main/docs/HTML_PROTOCOL.md) | Semantic markers and round trips |
+| [Public SDK & migration](https://github.com/myhloli/DocVortex/blob/main/docs/sdk-0.4.md) | Supported integration boundaries and the 0.4 upgrade |
+| [Rendering ownership](https://github.com/myhloli/DocVortex/blob/main/docs/RENDER_OWNERSHIP.md) | DocVortex exports and MinerU-specific renderers |
+
+## Development
+
+From a local checkout:
+
+```bash
+uv venv
+uv pip install -e ".[test,dev]"
+uv run --no-project python -m pytest -q
+uv run --no-project ruff check src
+uv run --no-project ruff format --check src
+uv build
+```
+
+Bug reports and contributions are welcome. When reporting a parsing issue,
+include a reproducible command and a sample document you can share in
+[GitHub Issues](https://github.com/myhloli/DocVortex/issues).
+
+## License
+
+DocVortex project code is released under the
+[MIT License](https://github.com/myhloli/DocVortex/blob/main/LICENSE.md).

docvortex-0.4.2/README.md

@@ -0,0 +1,165 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/myhloli/DocVortex/main/docs/images/docvortex-logo.jpg" alt="DocVortex logo" width="200">
+
+# DocVortex
+
+**Native document parsing. One structure, many outputs.**
+
+[![PyPI](https://img.shields.io/pypi/v/docvortex?color=008cff)](https://pypi.org/project/docvortex/)
+[![Python](https://img.shields.io/pypi/pyversions/docvortex)](https://pypi.org/project/docvortex/)
+[![CI](https://github.com/myhloli/DocVortex/actions/workflows/ci.yml/badge.svg)](https://github.com/myhloli/DocVortex/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/myhloli/DocVortex/blob/main/LICENSE.md)
+
+**English** · [简体中文](https://github.com/myhloli/DocVortex/blob/main/README_zh-CN.md)
+
+[Quick start](#quick-start) · [Formats](#supported-formats) · [Documentation](#documentation)
+
+</div>
+
+## Documents in. Possibilities out.
+
+DocVortex is a standalone Python engine for parsing and converting documents.
+It reads native text and document structure into a unified representation,
+then exports the result in the formats your workflow needs.
+
+- **Multi-format input** — read text PDFs, Office files, OpenDocument files, EPUB, HTML, OFD and CSV.
+- **Parse once, export many times** — reuse the same result for Markdown, HTML, LaTeX, DOCX, EPUB, PDF and structured JSON.
+- **Portable results** — save document structure and image assets in a Bundle, then export again without the source file.
+- **Composable APIs** — use the complete pipeline or integrate analysis, postprocessing and rendering separately.
+
+Native parsing works without an OCR or VLM inference service. Use DocVortex
+directly through its CLI or Python SDK, independently of MinerU.
+
+![DocVortex pipeline: native documents become a unified representation, then Markdown, HTML, LaTeX, DOCX, EPUB, PDF or structured JSON.](https://raw.githubusercontent.com/myhloli/DocVortex/main/docs/images/docvortex-overview.jpg)
+
+## Quick start
+
+Requires **Python 3.10–3.14**.
+
+### Install
+
+```bash
+pip install docvortex
+```
+
+### Command line
+
+Convert a text PDF to Markdown:
+
+```bash
+docvortex convert report.pdf --format markdown --output output/report.md
+```
+
+Replace `report.pdf` with a local file in any supported input format.
+Use `--format` to choose the output; run `docvortex convert --help` for options.
+
+### Python
+
+Parse a document once and export it twice:
+
+```python
+import docvortex
+
+result = docvortex.parse("report.pdf")
+result.export("output/report.md", output_format="markdown")
+result.export("output/report.docx", output_format="docx")
+```
+
+The result owns its document structure and assets, so further exports do not
+reopen or reparse the source. Existing output files are protected by default;
+use `overwrite=True` in Python or `--overwrite` in the CLI to replace them.
+
+## Supported formats
+
+### Native inputs · 15 formats
+
+| Document family | Formats |
+| --- | --- |
+| PDF with native text | PDF |
+| Word & rich text | DOC, DOCX, RTF |
+| Presentations | PPT, PPTX |
+| Spreadsheets | XLS, XLSX, CSV |
+| OpenDocument | ODT, ODS, ODP |
+| E-books & web documents | EPUB, HTML |
+| Open Fixed-layout Document | OFD |
+
+### Outputs · 7 formats
+
+| Output | `--format` / `output_format` |
+| --- | --- |
+| Markdown | `markdown` |
+| HTML | `html` |
+| LaTeX | `latex` |
+| Word document | `docx` |
+| EPUB e-book | `epub` |
+| PDF | `pdf` |
+| Structured JSON | `structured_content` |
+
+PPT/PPTX and XLS/XLSX are input formats only. Structured JSON is an export
+format; the [document JSON protocol](https://github.com/myhloli/DocVortex/blob/main/docs/JSON_PROTOCOL.md)
+separately defines the analysis and intermediate representations.
+
+## Save now, export later
+
+A Bundle packages the parsed document and its image assets for reuse across
+processes or machines. Load it whenever you need another output format:
+
+```python
+import docvortex
+
+result = docvortex.parse("report.pdf")
+result.save_bundle("output/report.bundle")
+
+restored = docvortex.load_bundle("output/report.bundle")
+restored.export("output/report.epub", output_format="epub")
+```
+
+The restored result works without the original file. See the
+[usage guide](https://github.com/myhloli/DocVortex/blob/main/docs/USAGE.md#portable-bundles)
+for Bundle contents, asset handling and overwrite rules.
+
+Need only the title, authors or other source properties?
+[`docvortex.extract_metadata()`](https://github.com/myhloli/DocVortex/blob/main/docs/METADATA.md)
+reads metadata without parsing the document body.
+
+## Choose the right workflow
+
+- **Text PDFs:** native parsing uses the document's existing text and structure. Scanned pages requiring OCR need an external OCR or inference service.
+- **PDF classification:** `docvortex classify report.pdf` returns `txt` or `ocr`. Classification is explicit and does not start inference; parsing does not automatically switch backends.
+- **PDF export:** PDF sources with page geometry default to block layout restoration, with selectable text and region images for tables/charts. Other sources and older results use semantic reflow. Use `--pdf-layout original|reflow` to select explicitly; fonts, line breaks and drawing instructions are not reproduced losslessly. See [PDF output layout](docs/USAGE.md#pdf-output-layout).
+
+## Documentation
+
+| Guide | What you will find |
+| --- | --- |
+| [Usage](https://github.com/myhloli/DocVortex/blob/main/docs/USAGE.md) | Stage APIs, PDF pages, classification, images and Bundles |
+| [Agent skill](skills/docvortex/SKILL.md) | CLI and Python SDK workflows for agents; copy the entire `skills/docvortex` folder to reuse |
+| [Examples](https://github.com/myhloli/DocVortex/blob/main/demo/README.md) | Local PDF and Office samples with a runnable demo |
+| [Metadata](https://github.com/myhloli/DocVortex/blob/main/docs/METADATA.md) | Source properties and per-format coverage |
+| [JSON protocol](https://github.com/myhloli/DocVortex/blob/main/docs/JSON_PROTOCOL.md) | Document schemas, extensions and protocol migration |
+| [HTML protocol](https://github.com/myhloli/DocVortex/blob/main/docs/HTML_PROTOCOL.md) | Semantic markers and round trips |
+| [Public SDK & migration](https://github.com/myhloli/DocVortex/blob/main/docs/sdk-0.4.md) | Supported integration boundaries and the 0.4 upgrade |
+| [Rendering ownership](https://github.com/myhloli/DocVortex/blob/main/docs/RENDER_OWNERSHIP.md) | DocVortex exports and MinerU-specific renderers |
+
+## Development
+
+From a local checkout:
+
+```bash
+uv venv
+uv pip install -e ".[test,dev]"
+uv run --no-project python -m pytest -q
+uv run --no-project ruff check src
+uv run --no-project ruff format --check src
+uv build
+```
+
+Bug reports and contributions are welcome. When reporting a parsing issue,
+include a reproducible command and a sample document you can share in
+[GitHub Issues](https://github.com/myhloli/DocVortex/issues).
+
+## License
+
+DocVortex project code is released under the
+[MIT License](https://github.com/myhloli/DocVortex/blob/main/LICENSE.md).

{docvortex-0.4.1 → docvortex-0.4.2}/docs/JSON_PROTOCOL.md

@@ -91,3 +91,45 @@ publication, date, authoring-software, and qualified count fields are shared by
 The schema version remains 2.0. New readers accept absent source properties in existing documents;
 old strict readers require an upgrade to accept this addition. No legacy data is rewritten or
 silently enriched. See [source metadata](METADATA.md) for field and format semantics.
+
+## Optional PDF layout geometry
+
+Native PDF analysis adds `extensions.docvortex_layout` and deterministic
+postprocessing preserves it in Middle JSON and result bundles:
+
+```json
+{"docvortex_layout":{"version":1,"pages":[{"page_idx":0,"width_pt":595.28,"height_pt":841.89}]}}
+```
+
+`page_idx` is the original zero-based source index, including for page selections.
+Dimensions are finite positive PDF points (72 points per inch), in the same
+visible-page orientation as normalized block bboxes. Page rotation is already
+accounted for; consumers must not rotate these coordinates again. Blank pages
+also have geometry. Producers should provide an entry for each result page.
+Duplicate indices, unsupported extension versions, and missing/invalid dimensions
+cannot be used for original PDF layout. Extra source-page entries may be retained
+when selecting a subset of an existing result.
+
+Pages may also contain `image_rotations`, such as `{"3":270}`: keys are source
+block indices encoded as strings, and values are the 0/90/180/270-degree angles
+used to turn region crops upright. The original-layout renderer reverses this
+crop transform when placing the image. This preserves rotated table images
+without duplicating image data or adding rotated-text reconstruction.
+
+This uses the existing JSON extension mechanism; Model/Middle/bundle schema
+versions remain 2.0. Older documents without this extension remain readable.
+OFD geometry is not collected in this version. Other producers can supply the
+same extension for PDF results without depending on a live PDFDocument.
+
+Host analyzers can reuse `docvortex.document.pdf.layout.extract_layout_geometry`
+before closing their existing PDFDocument, then `attach_layout_image_rotations`
+after block filtering. Preserve crop angles before removing inference-only
+metadata. `remap_layout_geometry` maps local indices to source indices;
+`merge_layout_extensions` merges cached page batches while requiring other
+extensions to match and retaining the winning page's crop orientation.
+MinerU uses these helpers for all PDF tiers alongside `extensions.mineru`.
+
+Since 0.4.2, native PDF display equations have `content: ""` at the final output
+boundary and keep their image payload, bbox and detected equation-number region.
+Detection still uses internal text evidence. Inline formulas and model-assisted
+non-Flash formulas are unchanged; existing results are not rewritten.