diff --git a/CHANGELOG.md b/CHANGELOG.md
index 344b9a9..29a2b68 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [Unreleased]
+
+### Added
+
+- **OpenDataLoader PDF engine adapter** — wraps the Java-based [`opendataloader-pdf`](https://github.com/opendataloader-project/opendataloader-pdf) tool (via its bundled-JAR Python wheel). Local, deterministic extraction with typed structural elements (heading, paragraph, table, list, header, footer) and per-element bounding boxes. Install: `pip install docfold[opendataloader]` (also requires Java 11+).
+- **Multi-script benchmark coverage** — `benchmark.py` now generates Arabic (RTL + shaping), Hebrew (RTL, no shaping), and Simplified Chinese (CJK) synthetic PDFs alongside the existing English docs. Fonts are bundled under `tests/fixtures/fonts/` (OFL-1.1, subsetted where relevant) so the benchmark is reproducible without system font packages.
+
## [0.6.0] - 2026-02-20
### Added
diff --git a/README.md b/README.md
index 002f161..7c2d8f9 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,7 @@ Docfold is the open-source extraction engine from [Datatera.ai](https://datatera
| [**MinerU**](https://github.com/opendatalab/MinerU) | ✅ | Local | AGPL | ★★★ | ★★★ | ★★★ | — | — | Slow | Free |
| [**Marker**](https://www.datalab.to/) | ✅ | SaaS | Paid | ★★★ | ★★★ | ★★★ | ✅ | — | Fast | $$ |
| [**PyMuPDF**](https://pymupdf.readthedocs.io/) | ✅ | Local | AGPL | ★★★ | ☆☆☆ | ★☆☆ | — | — | Ultra | Free |
+| [**OpenDataLoader**](https://github.com/opendataloader-project/opendataloader-pdf) | ✅ | Local | Apache | ★★★ | ☆☆☆ | ★★☆ | ✅ | — | Fast | Free |
| [**PaddleOCR**](https://github.com/PaddlePaddle/PaddleOCR) | ✅ | Local | Apache | ★☆☆ | ★★★ | ★★☆ | — | ✅ | Medium | Free |
| [**Tesseract**](https://github.com/tesseract-ocr/tesseract) | ✅ | Local | Apache | ★☆☆ | ★★☆ | ★☆☆ | — | — | Medium | Free |
| [**EasyOCR**](https://github.com/JaidedAI/EasyOCR) | ✅ | Local | Apache | ★☆☆ | ★★★ | ☆☆☆ | — | ✅ | Medium | Free |
@@ -94,6 +95,7 @@ for name, res in results.items():
| [**MinerU**](https://github.com/opendatalab/MinerU) | Local | AGPL-3.0 | PDF | Recommended | `pip install docfold[mineru]` |
| [**Marker API**](https://www.datalab.to/) | SaaS | Paid | PDF, Office, images | N/A | `pip install docfold[marker]` |
| [**PyMuPDF**](https://pymupdf.readthedocs.io/) | Local | AGPL-3.0 | PDF | No | `pip install docfold[pymupdf]` |
+| [**OpenDataLoader**](https://github.com/opendataloader-project/opendataloader-pdf) | Local | Apache-2.0 | PDF | No (needs Java 11+) | `pip install docfold[opendataloader]` |
| [**PaddleOCR**](https://github.com/PaddlePaddle/PaddleOCR) | Local | Apache-2.0 | Images, scanned PDFs | Optional | `pip install docfold[paddleocr]` |
| [**Tesseract**](https://github.com/tesseract-ocr/tesseract) | Local | Apache-2.0 | Images, scanned PDFs | No | `pip install docfold[tesseract]` |
| [**EasyOCR**](https://github.com/JaidedAI/EasyOCR) | Local | Apache-2.0 | Images, scanned PDFs | Optional | `pip install docfold[easyocr]` |
diff --git a/benchmark.py b/benchmark.py
index c795e11..287d5a9 100644
--- a/benchmark.py
+++ b/benchmark.py
@@ -37,6 +37,90 @@ def create_text_pdf(path: str, pages: list[dict]) -> None:
doc.close()
+_FIXTURE_FONT_DIR = os.path.join(
+ os.path.dirname(__file__), "tests", "fixtures", "fonts"
+)
+
+
+def _find_bundled_font(preferred: str, fallbacks: list[tuple[str, str]]) -> tuple[str, str] | None:
+ """Return ``(font_dir, ttf_name)`` for a font that exists on disk.
+
+ Prefers the bundled fixture under ``tests/fixtures/fonts/`` (shipped under
+ OFL-1.1) so the benchmark is reproducible on any host; falls back to
+ system paths only as a safety net.
+ """
+ if os.path.exists(os.path.join(_FIXTURE_FONT_DIR, preferred)):
+ return _FIXTURE_FONT_DIR, preferred
+ for d, fname in fallbacks:
+ if os.path.exists(os.path.join(d, fname)):
+ return d, fname
+ return None
+
+
+def _find_arabic_font() -> tuple[str, str] | None:
+ return _find_bundled_font(
+ "NotoNaskhArabic-Regular.ttf",
+ [
+ ("/usr/share/fonts/truetype/noto", "NotoNaskhArabic-Regular.ttf"),
+ ("/usr/share/fonts/noto", "NotoNaskhArabic-Regular.ttf"),
+ ("/usr/share/fonts/truetype/noto", "NotoSansArabic-Regular.ttf"),
+ ],
+ )
+
+
+def _find_script_font(preferred: str) -> tuple[str, str] | None:
+ """Bundled fonts for non-Arabic scripts — no system fallback because the
+ subsetted TTF is what we tested against."""
+ return _find_bundled_font(preferred, [])
+
+
+def _render_html_pdf(path: str, html_body: str, font_info: tuple[str, str]) -> None:
+ """Generic HTML → PDF renderer using PyMuPDF's ``insert_htmlbox`` with
+ a bundled font archive. Handles shaping / bidi via HarfBuzz under the hood.
+ """
+ import fitz
+
+ font_dir, ttf = font_info
+ doc = fitz.open()
+ page = doc.new_page(width=612, height=792)
+ archive = fitz.Archive(font_dir)
+ css = f"@font-face {{ font-family: 'BenchFont'; src: url({ttf}); }}"
+ page.insert_htmlbox(fitz.Rect(36, 36, 576, 756), html_body, css=css, archive=archive)
+ doc.save(path)
+ doc.close()
+
+
+def create_arabic_pdf(path: str, html_body: str) -> None:
+ """Render an Arabic HTML snippet to PDF using Noto Naskh Arabic."""
+ font_info = _find_arabic_font()
+ if font_info is None:
+ raise RuntimeError(
+ "Arabic font fixture missing: "
+ "tests/fixtures/fonts/NotoNaskhArabic-Regular.ttf"
+ )
+ _render_html_pdf(path, html_body, font_info)
+
+
+def create_script_pdf(path: str, html_body: str, font_ttf: str) -> None:
+ """Render an HTML snippet to PDF using a bundled script-specific font."""
+ font_info = _find_script_font(font_ttf)
+ if font_info is None:
+ raise RuntimeError(f"Font fixture missing: tests/fixtures/fonts/{font_ttf}")
+ _render_html_pdf(path, html_body, font_info)
+
+
+def _extract_ground_truth(pdf_path: str) -> str:
+ """Return PyMuPDF's extracted text — used as ground truth for docs whose
+ authoritative form depends on font shaping (e.g. Arabic).
+ """
+ import fitz
+
+ doc = fitz.open(pdf_path)
+ text = "\n".join(p.get_text() for p in doc)
+ doc.close()
+ return text
+
+
def generate_benchmark_documents(tmpdir: str) -> list[dict]:
"""Generate synthetic PDFs and return metadata with ground truth."""
documents = []
@@ -130,6 +214,78 @@ def generate_benchmark_documents(tmpdir: str) -> list[dict]:
"category": "report",
})
+ # --- Doc 5: Arabic (RTL + shaping) ---
+ # PDFs store Arabic in shaped presentation forms and reverse visual order.
+ # We use PyMuPDF's extraction of the generated PDF as ground truth — this
+ # measures whether *other* engines agree on the same text, not whether
+ # they normalize to logical Unicode (a harder task).
+ doc5_path = os.path.join(tmpdir, "arabic_report.pdf")
+ arabic_html = (
+ '"
+ "
تقرير سنوي 2024
"
+ "
حققت الشركة نموا قياسيا هذا العام بإيرادات تجاوزت التوقعات.
"
+ "
بلغت نسبة رضا العملاء 94 بالمئة.
"
+ "
وصل معدل الاحتفاظ بالموظفين إلى 96 بالمئة.
"
+ "
"
+ "
2024年度报告
"
+ "
公司今年实现了创纪录的增长，收入超出预期。
"
+ "
客户满意度达到了94%。
"
+ "
员工保留率达到96%，创公司历史新高。
"
+ "
"
+ "
דוח שנתי 2024
"
+ "
החברה השיגה צמיחה שיא השנה, עם הכנסות שעלו על הציפיות.
"
+ "
שביעות רצון הלקוחות הגיעה ל-94 אחוז.
"
+ "
שיעור שימור העובדים הגיע ל-96 אחוז.
"
+ "
Hello World
Test document for OpenDataLoader
",
+ text: str = "Hello World\nTest document for OpenDataLoader",
+ stem: str = "test",
+):
+ """Produce a fake ``convert`` that writes output files into ``output_dir``."""
+
+ def fake_convert(input_path, output_dir=None, format=None, **kwargs):
+ assert output_dir is not None, "engine must pass an output_dir"
+ fmts = format if isinstance(format, list) else ([format] if format else [])
+ for fmt in fmts:
+ if fmt == "json":
+ with open(os.path.join(output_dir, f"{stem}.json"), "w") as f:
+ json.dump(json_payload, f)
+ elif fmt in ("markdown", "markdown-with-html", "markdown-with-images"):
+ with open(os.path.join(output_dir, f"{stem}.md"), "w") as f:
+ f.write(markdown)
+ elif fmt == "html":
+ with open(os.path.join(output_dir, f"{stem}.html"), "w") as f:
+ f.write(html)
+ elif fmt == "text":
+ with open(os.path.join(output_dir, f"{stem}.txt"), "w") as f:
+ f.write(text)
+
+ return fake_convert
+
+
+# ---------------------------------------------------------------------------
+# Metadata / capabilities
+# ---------------------------------------------------------------------------
+
+
+class TestOpenDataLoaderEngineMetadata:
+ def test_name(self):
+ from docfold.engines.opendataloader_engine import OpenDataLoaderEngine
+
+ e = OpenDataLoaderEngine()
+ assert e.name == "opendataloader"
+
+ def test_supported_extensions(self):
+ from docfold.engines.opendataloader_engine import OpenDataLoaderEngine
+
+ e = OpenDataLoaderEngine()
+ assert "pdf" in e.supported_extensions
+
+ def test_capabilities(self):
+ from docfold.engines.opendataloader_engine import OpenDataLoaderEngine
+
+ e = OpenDataLoaderEngine()
+ caps = e.capabilities
+ assert caps.bounding_boxes is True
+ assert caps.reading_order is True
+ assert caps.heading_detection is True
+ assert caps.table_structure is True
+
+ def test_is_available_false_when_package_missing(self):
+ from docfold.engines.opendataloader_engine import OpenDataLoaderEngine
+
+ e = OpenDataLoaderEngine()
+ with patch.dict("sys.modules", {"opendataloader_pdf": None}):
+ assert isinstance(e.is_available(), bool)
+
+ def test_is_available_false_when_java_missing(self):
+ from docfold.engines.opendataloader_engine import OpenDataLoaderEngine
+
+ e = OpenDataLoaderEngine()
+ with patch("shutil.which", return_value=None):
+ assert e.is_available() is False
+
+ def test_config_stored(self):
+ from docfold.engines.opendataloader_engine import OpenDataLoaderEngine
+
+ e = OpenDataLoaderEngine(
+ reading_order="xycut",
+ table_method="cluster",
+ include_header_footer=True,
+ password="secret",
+ )
+ assert e._reading_order == "xycut"
+ assert e._table_method == "cluster"
+ assert e._include_header_footer is True
+ assert e._password == "secret"
+
+
+# ---------------------------------------------------------------------------
+# process()
+# ---------------------------------------------------------------------------
+
+
+class TestOpenDataLoaderEngineProcess:
+ @pytest.mark.asyncio
+ async def test_process_markdown_format(self):
+ from docfold.engines import opendataloader_engine
+ from docfold.engines.opendataloader_engine import OpenDataLoaderEngine
+
+ e = OpenDataLoaderEngine()
+ fake_convert = _fake_convert_factory(_odl_json(pages=1))
+
+ with patch.object(opendataloader_engine, "_convert", fake_convert):
+ result = await e.process("test.pdf", output_format=OutputFormat.MARKDOWN)
+
+ assert isinstance(result, EngineResult)
+ assert result.engine_name == "opendataloader"
+ assert result.format == OutputFormat.MARKDOWN
+ assert "Hello World" in result.content
+ assert result.pages == 1
+ assert result.bounding_boxes is not None
+ assert len(result.bounding_boxes) == 2
+ assert result.processing_time_ms >= 0
+
+ @pytest.mark.asyncio
+ async def test_process_json_format(self):
+ from docfold.engines import opendataloader_engine
+ from docfold.engines.opendataloader_engine import OpenDataLoaderEngine
+
+ e = OpenDataLoaderEngine()
+ fake_convert = _fake_convert_factory(_odl_json(pages=1))
+
+ with patch.object(opendataloader_engine, "_convert", fake_convert):
+ result = await e.process("test.pdf", output_format=OutputFormat.JSON)
+
+ assert result.format == OutputFormat.JSON
+ # Content must be valid JSON
+ parsed = json.loads(result.content)
+ assert parsed["number of pages"] == 1
+
+ @pytest.mark.asyncio
+ async def test_process_html_format(self):
+ from docfold.engines import opendataloader_engine
+ from docfold.engines.opendataloader_engine import OpenDataLoaderEngine
+
+ e = OpenDataLoaderEngine()
+ fake_convert = _fake_convert_factory(_odl_json(pages=1))
+
+ with patch.object(opendataloader_engine, "_convert", fake_convert):
+ result = await e.process("test.pdf", output_format=OutputFormat.HTML)
+
+ assert result.format == OutputFormat.HTML
+ assert "" in result.content.lower()
+
+ @pytest.mark.asyncio
+ async def test_type_mapping(self):
+ """heading/paragraph/table/list/list-item should map to canonical types."""
+ from docfold.engines import opendataloader_engine
+ from docfold.engines.opendataloader_engine import OpenDataLoaderEngine
+
+ kids = [
+ {
+ "type": "heading",
+ "id": 1,
+ "page number": 1,
+ "bounding box": [0, 0, 100, 20],
+ "content": "H",
+ },
+ {
+ "type": "paragraph",
+ "id": 2,
+ "page number": 1,
+ "bounding box": [0, 30, 100, 50],
+ "content": "P",
+ },
+ {
+ "type": "table",
+ "id": 3,
+ "page number": 1,
+ "bounding box": [0, 60, 100, 200],
+ "content": "T",
+ },
+ {
+ "type": "list",
+ "id": 4,
+ "page number": 1,
+ "bounding box": [0, 210, 100, 300],
+ "content": "L",
+ },
+ ]
+ e = OpenDataLoaderEngine()
+ fake_convert = _fake_convert_factory(_odl_json(pages=1, kids=kids))
+ with patch.object(opendataloader_engine, "_convert", fake_convert):
+ result = await e.process("test.pdf", output_format=OutputFormat.MARKDOWN)
+
+ types = {b["type"] for b in result.bounding_boxes}
+ assert "SectionHeader" in types
+ assert "Text" in types
+ assert "Table" in types
+ assert "List" in types
+
+ @pytest.mark.asyncio
+ async def test_nested_kids_flattened(self):
+ """Nested kids (e.g. header container) must be flattened into bboxes."""
+ from docfold.engines import opendataloader_engine
+ from docfold.engines.opendataloader_engine import OpenDataLoaderEngine
+
+ nested_kids = [
+ {
+ "type": "header",
+ "id": 10,
+ "page number": 1,
+ "bounding box": [0, 0, 500, 400],
+ "kids": [
+ {
+ "type": "heading",
+ "id": 1,
+ "page number": 1,
+ "bounding box": [0, 0, 100, 20],
+ "content": "Title",
+ },
+ {
+ "type": "paragraph",
+ "id": 2,
+ "page number": 1,
+ "bounding box": [0, 30, 400, 100],
+ "content": "Body",
+ },
+ ],
+ }
+ ]
+ e = OpenDataLoaderEngine()
+ fake_convert = _fake_convert_factory(_odl_json(pages=1, kids=nested_kids))
+
+ with patch.object(opendataloader_engine, "_convert", fake_convert):
+ result = await e.process("test.pdf", output_format=OutputFormat.MARKDOWN)
+
+ # At least the two leaves must be emitted as bounding boxes.
+ assert result.bounding_boxes is not None
+ texts = [b.get("text", "") for b in result.bounding_boxes]
+ assert "Title" in texts
+ assert "Body" in texts
+
+ @pytest.mark.asyncio
+ async def test_bbox_coordinates_preserved(self):
+ from docfold.engines import opendataloader_engine
+ from docfold.engines.opendataloader_engine import OpenDataLoaderEngine
+
+ kids = [
+ {
+ "type": "paragraph",
+ "id": 1,
+ "page number": 2,
+ "bounding box": [12.5, 34.5, 200.0, 90.0],
+ "content": "Hi",
+ }
+ ]
+ e = OpenDataLoaderEngine()
+ fake_convert = _fake_convert_factory(_odl_json(pages=2, kids=kids))
+
+ with patch.object(opendataloader_engine, "_convert", fake_convert):
+ result = await e.process("test.pdf", output_format=OutputFormat.MARKDOWN)
+
+ assert result.bounding_boxes is not None
+ bbox = result.bounding_boxes[0]
+ assert bbox["bbox"] == [12.5, 34.5, 200.0, 90.0]
+ assert bbox["page"] == 2
+ assert bbox["text"] == "Hi"
+
+ @pytest.mark.asyncio
+ async def test_process_surfaces_errors_as_runtime_error(self):
+ from docfold.engines import opendataloader_engine
+ from docfold.engines.opendataloader_engine import OpenDataLoaderEngine
+
+ def boom(*args, **kwargs):
+ raise RuntimeError("java exited 2")
+
+ e = OpenDataLoaderEngine()
+ with patch.object(opendataloader_engine, "_convert", boom):
+ with pytest.raises(RuntimeError, match="opendataloader"):
+ await e.process("test.pdf", output_format=OutputFormat.MARKDOWN)
+
+ @pytest.mark.asyncio
+ async def test_reading_order_option_passed(self):
+ """reading_order kwarg on the engine must reach the underlying convert call."""
+ from docfold.engines import opendataloader_engine
+ from docfold.engines.opendataloader_engine import OpenDataLoaderEngine
+
+ captured: dict = {}
+
+ def capture(input_path, output_dir=None, format=None, **kwargs):
+ captured["kwargs"] = kwargs
+ # Still produce files so parsing succeeds
+ _fake_convert_factory(_odl_json(pages=1))(
+ input_path, output_dir=output_dir, format=format, **kwargs
+ )
+
+ e = OpenDataLoaderEngine(reading_order="xycut", table_method="cluster")
+ with patch.object(opendataloader_engine, "_convert", capture):
+ await e.process("test.pdf", output_format=OutputFormat.MARKDOWN)
+
+ assert captured["kwargs"].get("reading_order") == "xycut"
+ assert captured["kwargs"].get("table_method") == "cluster"
diff --git a/tests/fixtures/fonts/LICENSE.txt b/tests/fixtures/fonts/LICENSE.txt
new file mode 100644
index 0000000..dffd6b1
--- /dev/null
+++ b/tests/fixtures/fonts/LICENSE.txt
@@ -0,0 +1,20 @@
+Benchmark font fixtures — all bundled Noto fonts are licensed under the
+SIL Open Font License, Version 1.1 (OFL-1.1).
+
+Files
+-----
+- NotoNaskhArabic-Regular.ttf — full Noto Naskh Arabic Regular
+- NotoSansCJKsc-Regular-subset.ttf — Noto Sans CJK SC Regular, subsetted to
+ the glyphs used in the Chinese benchmark document only
+- NotoSansHebrew-Regular-subset.ttf — Noto Sans Hebrew Regular, subsetted to
+ the glyphs used in the Hebrew benchmark document only
+
+Sources
+-------
+- https://fonts.google.com/noto/specimen/Noto+Naskh+Arabic
+- https://fonts.google.com/noto/specimen/Noto+Sans+Simplified+Chinese
+- https://fonts.google.com/noto/specimen/Noto+Sans+Hebrew
+- OFL license text: https://scripts.sil.org/OFL
+
+Subsetting was done with fontTools (``fontTools.subset.Subsetter``) preserving
+all OpenType layout features so shaping / bidi still work.
diff --git a/tests/fixtures/fonts/NotoNaskhArabic-Regular.ttf b/tests/fixtures/fonts/NotoNaskhArabic-Regular.ttf
new file mode 100644
index 0000000..00a33b3
Binary files /dev/null and b/tests/fixtures/fonts/NotoNaskhArabic-Regular.ttf differ
diff --git a/tests/fixtures/fonts/NotoSansCJKsc-Regular-subset.ttf b/tests/fixtures/fonts/NotoSansCJKsc-Regular-subset.ttf
new file mode 100644
index 0000000..1cdd83d
Binary files /dev/null and b/tests/fixtures/fonts/NotoSansCJKsc-Regular-subset.ttf differ
diff --git a/tests/fixtures/fonts/NotoSansHebrew-Regular-subset.ttf b/tests/fixtures/fonts/NotoSansHebrew-Regular-subset.ttf
new file mode 100644
index 0000000..9330e17
Binary files /dev/null and b/tests/fixtures/fonts/NotoSansHebrew-Regular-subset.ttf differ