doctags

Overview ¶

Package doctags parses DocTags, the output format of the granite-docling vision-language models, into this repo's doc model.

DocTags is why granite-docling was chosen over an OCR model that emits prose. A model that writes Markdown has already thrown away what it knew: which run of text was a heading, which was a caption, where the table's row boundaries were. Re-deriving that from the Markdown means running heading heuristics over generated text, which is the layout problem again with a worse input. DocTags carries the structure explicitly, so this package is a parser rather than a second round of inference — and that is the whole argument for the format.

It is also the reason this package can be finished and tested before any model runs. Nothing here talks to an engine, loads weights, or opens a socket: the input is a string. docling publishes DocTags documents and the Markdown it renders them to as MIT-licensed fixtures, and testdata/docling holds seven of them, so the grammar is measured against its author's own expectations rather than against what a local model happened to emit on a given day.

The grammar, as it actually appears ¶

The vocabulary is pinned from docling_core/types/doc/tokens.py at the commit in testdata/manifest.json, not from prose documentation — the model card documents neither the tag set nor the coordinate system. A document is:

<doctag>
<page_header><loc_15><loc_104><loc_30><loc_350>arXiv:2206.01062v1</page_header>
<section_header_level_1><loc_88><loc_53><loc_413><loc_75>DocLayNet</section_header_level_1>
<page_break>
...
</doctag>

Every element may carry exactly four location tokens immediately after its open tag, and may carry none at all. Elements nest: a <picture> holds its <caption>, and an <otsl> table holds both its cells and its caption. <page_break> is a bare marker with no closing tag, and it is what separates pages.

Coordinates are a 500-unit grid, top-down ¶

A <loc_N> is not pixels and not points. tokens.py's get_location_token computes round(500*val) clamped to [0,499] from a fraction of the page, and get_location emits exactly four of them in x0,y0,x1,y1 order, min/max-sorted. So the numbers are twelfths-of-a-percent of the page in each axis, independent of the DPI the page was rasterized at — which is the property that makes them usable at all, since the raster this text came from was resolution-capped by render.Fit and the model resized it again.

The Y axis runs downward, as it does in every raster convention and in none of PDF: geom's package comment is explicit that user space has its origin at the lower left. Measured rather than assumed — the page_header in barchart.dt is at loc_14 to loc_20, i.e. at the very top of its page, and a page header is not at the bottom. So this package flips it, and the flip is the one piece of arithmetic here that would silently produce a plausible wrong answer: a document parsed without it reads correctly and has every block's rectangle mirrored, which no text comparison would catch.