The Problem
PDF-to-Markdown conversion requires handling complex layouts, tables, and cross-page content merging without introducing markup artifacts. The codebase contains 35 files across eval/ and ocrflux/ directories, but suffers from high cognitive load that makes targeted changes risky. Static analysis found 12 levels of deep nesting across ocrflux/table_format.py, ocrflux/work_queue.py, and eval/eval_html_table_merge.py, plus 445 duplicated 6-line blocks repeated across 13 files. These patterns indicate that even modest modifications carry unintended ripple effects.
What This Does
OCRFlux converts PDFs and images to clean Markdown text. The repository splits into two projects: eval/ (12 files, 11 code) containing evaluation scripts for different table/parsing strategies, and ocrflux/ (11 files, 10 code) containing the core toolkit. Key files include ocrflux/pipeline.py (20 functions, called from 1 other file, calls into 3) which defines build_page_to_markdown_query, build_element_merge_detect_query, and build_html_table_merge_query. Entry point main in eval/eval_element_merge_detect.py:17 reaches 53 functions. The internal call graph has 76 resolved edges between self-referencing functions, with process_task and build_document_text each called from 3 places. Two benchmarks are shipped: OCRFlux-bench-single and OCRFlux-pubtabnet-single, though these datasets are not included in training/evaluation data.
How It Is Wired
Execution starts at main in eval/eval_element_merge_detect.py:17, which fans out to evaluate (called from 2 places) and parallel_process (called from 2 places). batch_evaluate then calls evaluate and parallel_process each 4 times. The most connected module is eval/parallel (Ca 8, Ce 0), while ocrflux/pipeline (Ca 0, Ce 6) and ocrflux/client (Ca 0, Ce 3) each have instability score 1. ocrflux/pipeline.py at 692 lines is the widest blast radius - a change ripples through 3 called modules and 1 caller. eval/parallel.py has 15 branch points over 42 lines, and ocrflux/table_format.py similarly high branching density. No circular dependencies were found across 23 analyzed files.
How To Use It
The repository has pyproject.toml and Dockerfile present. No lockfile exists for dependency reproducibility. CI is configured via GitHub Actions (.github/workflows/docker.yml). The README references an online demo at <https://ocrflux.pdfparser.io/>. For local installation, pyproject.toml implies pip or uv usage, but no specific pip install command or environment variable names are documented in the evidence. Docker build is supported via the Dockerfile. No committed secrets were found, and a LICENSE file is present.
Code Health & Issues
Static analysis identified 22 findings across 6 distinct categories:
[HIGH/cognitive_load] Deep nesting x12-ocrflux/table_format.py,ocrflux/work_queue.py,eval/eval_html_table_merge.py- max indentation depth 6, control flow hard to follow[HIGH/clarity] Duplicated code blocks-eval/eval_element_merge_detect.py,eval/eval_page_to_markdown.py,eval/eval_html_table_merge.py,eval/eval_page_to_markdown_nanonets.py- 445 repeated 6-line blocks across 13 files[MEDIUM/cognitive_load] Oversized file-ocrflux/pipeline.py- 692 code lines, hard to hold in one head; change ripples widely[MEDIUM/resource_safety] File opened without context manager-ocrflux/image_utils.py-open(...)not wrapped inwith, handle may leak on error[MEDIUM/resilience] Broad exception handling x5-ocrflux/image_utils.py,ocrflux/check.py,ocrflux/client.py- bare/Exception-wideexceptswallows errors indiscriminately[MEDIUM/cognitive_load] High branching density x2-eval/parallel.py,ocrflux/table_format.py- 15 branch points over 42 lines
SDLC observations: No test files detected repository-wide. Dependencies declared without lockfile in pyproject.toml. CI present (GitHub Actions). License present. No committed secrets found.
The Bottom Line
This repo delivers functional PDF-to-Markdown conversion with cross-page table merging and ships two evaluation benchmarks, but the codebase carries significant technical debt. Twelve levels of deep nesting, 445 duplicated blocks, and a 692-line pipeline file create high maintenance cost. The absence of tests and dependency lockfile further limits production readiness. Teams needing PDF conversion who have capacity to address code health issues can extract value, but those requiring stable, out-of-the-box integration should look elsewhere.