textreflow

Layout regions in, ordered prose out. A layout detector (Docling, YOLO, Surya, LayoutParser, PaddleOCR, …) tells you where the title, the paragraphs and the tables are on each page. It does not tell you the order to read them in, or that the paragraph cut off at the bottom of the left column continues at the top of the right one. textreflow is the step in between:

PDF ──▶ layout detector ──▶ regions ──▶ textreflow ──▶ typed blocks ──▶ chunker

• Column-aware reading order. Full-width bands (title, abstract, wide figures) first, then the left column top to bottom, then the right.
• Paragraphs rebuilt across regions, columns and page breaks. A paragraph stays open until a sentence ends, and a figure, caption or footnote in between does not close it.
• De-hyphenation from the document itself. construc- + tion becomes construction, but Edge- + centric stays Edge-centric when that compound appears unbroken somewhere else in the same document.
• Structure kept as block types: title, section, authors, caption, table, formula, footnote, list.
• Page furniture removed from the flow (running heads, page numbers, text inside figures) and returned separately, not thrown away.
• No dependencies. Standard library only. No detector is bundled, so nothing AGPL comes along with it.

pip install textreflow

Use

from textreflow import assemble, render_txt

layout = {"pages": [{"page": 0, "width": 612, "regions": [
    {"label": "Text", "bbox": [40, 100, 290, 700], "lines": ["Models have demon-"]},
    {"label": "Text", "bbox": [320, 60, 570, 200], "lines": ["strated it."]},
]}]}

blocks, dropped = assemble(layout)
blocks   # [{"type": "paragraph", "page": 0, "text": "Models have demonstrated it."}]
dropped  # {"page_headers": [], "page_footers": [], "picture_text": []}

print(render_txt(blocks))   # tagged text: "# " title, "## " section, [TABLE] … [/TABLE], …

From Docling (install it yourself; textreflow only reads the document object):

from docling.document_converter import DocumentConverter
from textreflow import assemble
from textreflow.adapters.docling import from_docling

doc = DocumentConverter().convert("paper.pdf").document
blocks, dropped = assemble(from_docling(doc))

The blocks are exactly the input that grain-growth-chunking takes, so the two chain directly:

from grain_growth import chunk_document
chunks, skipped = chunk_document(blocks, filename="paper")

The input contract

For each page: its number, its width, and the regions found on it. A region has a label, a bounding box, and its text as lines.

{"pages": [
    {"page": 0,                                  # 0-based
     "width": 612.0,                             # same units as bbox
     "regions": [
         {"label": "Text",
          "bbox": [40.0, 100.0, 290.0, 200.0],   # x0, y0, x1, y1, top-left origin
          "lines": ["The construc-", "tion of graphs"]}],
     "swallowed_text": [                         # optional
         {"label": "Picture", "text": "axis"}]}]}

Regions can arrive in any order, because reading order is worked out from the boxes. Any unit works (PDF points, pixels) as long as bbox and width use the same one. lines must already be in reading order within the region: grouping words into lines is the detector's job. Put text found inside pictures in swallowed_text if you want it reported in dropped. Other keys (conf, height, …) are ignored.

Check a layout before you trust the output. A wrong label does not crash anything: the region is quietly read as prose.

from textreflow import validate_layout
validate_layout(layout)                 # raises ValueError on the first problems
validate_layout(layout, strict=False)   # returns every problem as a list

Column geometry can be tuned: assemble(layout, full_width_fraction=0.6, single_column_fraction=0.7). The defaults are the values used in the evaluation below.

Evidence

The measure is the share of paragraphs (over 40 characters) that begin with a lower-case letter. Each of these is a continuation the parser failed to join to the paragraph before it. Measured on 60 arXiv papers:

Same detector, same boxes: replacing only Docling's assembly step with textreflow cuts mid-sentence paragraphs about five-fold, from 12.5% to 2.4%.

Source: evals/Reports/parser_quality_60.json in the Anneal repository, produced by evals/scripts/parser_quality_probe.py.

What this does not show:

• These are pooled percentages over all paragraphs. They are not a paired per-paper test and have no confidence interval, so the size of the effect per document is not established.
• An earlier 5-paper run gave 17.4% against 2.9%. That smaller sample overstated Docling's failure rate. Use the 60-paper figures above.
• The metric catches only missed merges. A wrong merge (two paragraphs joined because the first did not end in ., ! or ?) does not show up in it.
• The heuristics were developed on arXiv-style one- and two-column papers. Three-column layouts, right-to-left scripts and forms have not been evaluated.

Development

pip install -e ".[test]"
pytest -q                      # 40 tests, no network, no detector needed

Citing

If this is useful in your work, please cite it. CITATION.cff in this repository gives GitHub's "Cite this repository" button everything it needs:

Choudhary, M. (2026). textreflow: reading order and paragraph reconstruction for document layout detectors (version 1.0.0) [Software]. https://github.com/mudit-choudhary/textreflow

ORCID: 0009-0003-8880-0925.

Licence

Apache-2.0. See LICENSE and NOTICE.