Reflow

State-of-the-art PDF/DOCX to semantic HTML converter with strong layout preservation.

Install

pip install -e .

Optional ML features (layout detection, OCR, table transformer):

pip install -e '.[ml]'

Quick Start

reflow convert input.pdf -o output.html

With OCR and guardrails:

reflow convert input.pdf \
	--ocr \
	--max-pages 200 \
	--max-output-mb 50 \
	--max-raster-mp 40 \
	--device cpu \
	-o output.html

Reliability Guardrails

Reflow now supports resource limits to make production behavior predictable:

• max_pages: fail fast when document scope is too large.
• max_output_bytes: fail fast when generated HTML exceeds configured size.
• max_raster_megapixels: caps raster operations to avoid memory spikes.
• Atomic output writes: output files are written safely via temp-file replace.

Observability

• Structured diagnostics callback (diagnostics_callback) can capture stage timings and pipeline stats.
• CLI prints timing/stats summary by default (--emit-stats / --no-emit-stats).

Edge Case Handling

• Invalid page selections are validated against document page count.
• Scanned pages can trigger OCR automatically when no extractable text is found.
• Layout/table/OCR model failures degrade gracefully with warnings instead of hard crash.
• Broken text encoding spans are rasterized to preserve visual fidelity.

API

import reflow

html = reflow.convert(
		"sample.pdf",
		ocr=True,
		layout_detection=True,
		table_recognition=True,
		max_pages=100,
		max_output_bytes=20 * 1024 * 1024,
)

Testing

pytest -q

With coverage gate (same as CI):

pytest --cov=reflow --cov-report=term-missing --cov-fail-under=80

Golden snapshot tests:

pytest -m golden

Update golden snapshots intentionally:

REFLOW_UPDATE_GOLDENS=1 pytest -m golden

Benchmarking

Single document:

reflow benchmark sample.pdf --repeat 3 --output-json bench.json

Directory benchmark:

reflow benchmark ./pdfs --glob "*.pdf" --repeat 2 --output-json bench.json

Benchmark output includes min/median/max latency, output-size stats, and per-run stage diagnostics.

CI

GitHub Actions CI is configured in .github/workflows/ci.yml and runs tests with coverage threshold enforcement.

Notes

• Python 3.12+
• Best results for complex layouts require optional ML dependencies.