[PierreMesure]

LightOnOCR-3 adds block grounding, image descriptions, and chart tables, but Docling currently only has a LightOnOCR-2 preset. This adds the official 0.8B, 1B, and 4B models as lightonocr3_08b, lightonocr3_1b, and lightonocr3_4b presets. The existing lightonocr preset continues to use v2.

The new presets use the grounding prompt and a native LIGHTONOCR_MARKDOWN response format. The parser accepts markers on their own lines and inline with content, scales 0–1000 coordinates to the source page, and preserves Markdown text, HTML tables, image descriptions, and chart tables. It reuses the existing rich HTML fragment mapper. Empty-prompt transcription is also supported. Transformers decoding removes special tokens; local inference requires Transformers 5.5.4 or later.

Boxes remain block-level: derived children and list items do not receive synthetic coordinates. Continuation labels keep their base class without merging blocks. Separate captions are not linked by proximity. No unverified MLX export is configured.

Rebased onto main at 1ee1db0f648c4bd2d25146f5dd100d1b75d94d7d after #4964 merged. This branch uses the upstream heading and formula helpers without changing them. The LightOn mapper records raw heading depths when the pipeline maps a page, and the pipeline normalizes the joined document once. Direct mapper calls normalize their page by default. Regression tests cover pages with and without a depth-1 section.

The shared Markdown renderer and its tests remain identical to #4908. They include the currency-range fix: Price $5-$10 and $x$. keeps the price as text and creates only the x formula. Native inline parsing preserves tildes, alert markers, pipe-table text, and bare URLs. Full-page GFM table parsing stays enabled for LightOn.

Validation of current code on Python 3.12 with the locked docling-core 2.103.1:

• Shared Markdown, LightOn, heading, preset, and optional-dependency suites: 193 passed, 2 skipped.
• Combined feat: add LightOnOCR-3 presets and grounded output parsing #4789 and fix: preserve native VLM inline math through exports #4908 parser/pipeline suites in an isolated worktree: 267 passed, 1 skipped. The branches merge together without conflicts.
• UV_NO_SYNC=1 make validate and hooks on every file in this PR: passed.
• New Linux CI runs are pending after the rebase.

Earlier validation included real 0.8B CPU inference through VlmConvertModel.process_images for grounding and empty-prompt transcription on a synthetic lease page, using Transformers 5.18.0, bfloat16, eight CPU threads, and compilation disabled. This inference was not rerun for the rebase. The 1B and 4B checkpoints, GPU/MLX inference, API-server inference, and the full repository suite were not run locally.

Fixes #4788.

[github-actions]

✅ DCO Check Passed

Thanks @PierreMesure, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

🟢 Merge protection satisfied — ready to merge.

Show 1 satisfied protection

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

[github-actions]

AI triage (advisory)

Checked commit 7173aab508. The analysis read the diff only. It did not run code from this pull request.

The PR adds three LightOnOCR-3 presets (lightonocr3_08b, lightonocr3_1b, lightonocr3_4b). It adds a LIGHTONOCR_MARKDOWN response format and a parser for grounded output with block bounding boxes. It also adds a math-aware Markdown parser helper, docs, and tests.

CI safety: no concern found. A maintainer must still approve CI.

2 related pull request(s) in the same code

PR	State	Signal	Assessment
#4908	open	changes the same code	related: Both PRs add the same docling/utils/markdown_math.py helper and tests/test_markdown_math.py, so they will conflict on those files. This PR adds LightOnOCR-3 support, and the candidate fixes inline math for native VLM exports. They solve different problems.
#4934	open	changes the same code	related: Both PRs edit stage_model_specs.py and the CLI skill reference. This PR adds LightOnOCR-3 presets. The candidate adds an MLX engine for Nemotron 3.5 Parse. The changes are in different places and do different things.

_{The ai:* labels are advisory. They do not approve CI and they do not add tests:full. A new push runs this check again.}

[codecov]

Codecov Report

❌ Patch coverage is 95.27559% with 6 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
docling/utils/lightonocr_utils.py	95.45%	1 Missing and 2 partials ⚠️
docling/utils/markdown_math.py	93.61%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

[PierreMesure]

Fixed the CI failure in 436888e.

The VLM job had one failure: TestPresetEngineIntegration.test_response_format_consistency did not include ResponseFormat.LIGHTONOCR_MARKDOWN in its explicit list of valid formats. The three new presets use that format, so the assertion failed. The code-checks / check and ci-status failures followed from this job.

The fix adds the missing format to that list. The existing test still checks presets across all three stage types. All 11 new LightOnOCR-3 tests already passed in the core CI job.

Local validation on Python 3.12:

• Reproduced the same assertion failure before the fix.
• Ran the full VLM suite selected by .github/scripts/pytest_marker_selection.py, with CI=true: 106 passed, 6 skipped. The skips match the original CI job.
• Ran tests/test_lightonocr3_vlm.py, tests/test_chandra_vlm.py, tests/test_unlimited_ocr_markdown.py, tests/test_vlm_convert_model.py, and tests/test_vlm_pipeline_streaming.py: 76 passed.
• UV_NO_SYNC=1 make validate: all applicable hooks passed, using the installed locked development environment.

Local Python 3.10 testing stopped at import because the locked SciPy wheel could not load on this Mac. Python 3.10 validation of the fix remains for Linux CI. No dependency or production-code changes were needed.

[github-actions]

AI first review (advisory): blocker found

This review covers the full diff at 436888e88f. It read the code and did not run it.

docling/utils/lightonocr_utils.py imports marko at module level, but marko is only in the optional format-markdown extra. A docling-slim[models-vlm-inline] install fails on the first page with a bare ModuleNotFoundError. Check this dependency first. The parser logic and tests look consistent with the existing Chandra mapper.

_{A maintainer makes the merge decision. This review never approves the pull request.}

[github-actions]

blocker: marko is an optional dependency, but the new parser imports it with no guard

pyproject.toml lists marko only in the format-markdown extra. The models-vlm-inline extra does not include it. The lazy import in VlmPipeline._finalize_page_document (docling/pipeline/vlm_pipeline.py) runs this module on the first page.

Trigger: a docling-slim[models-vlm-inline] install, with no format-web or format-markdown, runs lightonocr3_*.

Result: inference runs on the page. Then parsing raises a bare ModuleNotFoundError: marko, and the conversion fails.

The repository already handles this case. MarkdownDocumentBackend raises an ImportError with an install hint. docling/utils/dots_utils.py:78-84 does the same.

Fix: import marko inside parse_lightonocr_markdown. On ImportError, raise a message that tells the user to run pip install 'docling-slim[format-markdown]'. You can also add format-markdown to the dependencies of models-vlm-inline. The full docling package is not affected, because it includes format-web.

[PierreMesure]

Confirmed and fixed in fa841f3.

The regression test blocks marko in a fresh interpreter, using the existing optional-dependency test helper. Before the fix, the parser import failed with ModuleNotFoundError. With the fix, the module imports successfully and a parsing call raises ImportError with pip install 'docling-slim[format-markdown]'. The original import error is preserved as the cause.

The import now runs inside parse_lightonocr_markdown, as suggested. The LightOnOCR-3 documentation also states the Markdown-extra requirement for slim installations. The dependency remains optional.

Validation on Python 3.12:

• Optional-dependency tests selected with -k 'lightonocr or marko': 3 passed, including the new regression test.
• LightOnOCR-3, Chandra, Unlimited OCR, VLM conversion, and streaming tests: 76 passed.
• UV_NO_SYNC=1 make validate: all applicable hooks passed, including Ruff, ty, Tach, module coverage, and file-size checks.

Full Linux CI has not yet validated this commit.

[github-actions]

AI first review (advisory): no blocker found

This review covers the changes since 436888e88f at fa841f325b. It read the code and did not run it.

The earlier blocker (module-level marko import failing on docling-slim[models-vlm-inline] installs) is fixed: marko is now imported lazily inside parse_lightonocr_markdown and raises an ImportError with the correct install hint. The regression test and docs update look consistent. No new issues found in the incremental changes.

Earlier findings

• fixed (blocker): marko is an optional dependency but the new parser imports it with no guard

_{A maintainer makes the merge decision. This review never approves the pull request.}

[PierreMesure]

Fixed three parser defects in 493f6fa:

• LaTeX preservation: formula blocks bypass Markdown transformations and store LaTeX without outer math delimiters, so export adds exactly one pair. Inline math is protected from Markdown escaping and emphasis; code spans remain literal.
• Section heading levels: grounded title blocks with Markdown section headings become section headers. Their levels are converted to Docling's title-relative numbering, so ## exports as ##. Formatted heading children keep one block-level coordinate owner.
• Inline code fences: fence detection runs after extracting the grounding marker. A fence on the marker line now protects the code and ends before the next block. The following text keeps its label and coordinates instead of becoming code or a spurious picture.

Added 16 test cases to tests/test_lightonocr3_vlm.py, covering document structure, Markdown exports, coordinates, LaTeX escapes and multiline formulas, inline math versus code, and backtick/tilde fences. The initial regression run reproduced all three defect classes before the production fix.

Validation on Python 3.12:

• Full VLM selection plus LightOnOCR-3, Chandra, Unlimited OCR, VLM conversion, streaming, and the missing-Markdown regression: 199 passed, 6 skipped.
• Optional-dependency tests selected with -k 'marko or lightonocr': 3 passed.
• UV_NO_SYNC=1 make validate: all applicable hooks passed, including Ruff, ty, Tach, module coverage, and file-size checks.

The shared Chandra mapper and dependency declarations are unchanged. Full Linux CI has not yet validated this commit.

[PierreMesure]

Shared follow-up fixes are now tracked and implemented in focused PRs:

• fix: preserve VLM section heading depth in exports #4906 / Chandra and Nemotron section headings export one level too deep #4902: correct heading depth in the shared Chandra HTML mapper and Nemotron adapter.
• fix: normalize Nemotron formula delimiters before export #4907 / Nemotron formula exports contain nested LaTeX delimiters #4903: share LaTeX delimiter normalization and use it for Nemotron formulas.
• fix: preserve native VLM inline math through exports #4908 / Nemotron and DOTS exports alter inline LaTeX from model responses #4904: share math-aware Markdown rendering for DOTS and Nemotron native text blocks.
• fix: preserve multiline DeepSeek and Unlimited OCR blocks #4909 / DeepSeek and Unlimited OCR discard continuation lines in text blocks #4905: preserve multiline text and captions in the collector used by DeepSeek and Unlimited OCR.

This PR now reuses the shared math renderer and delimiter normalizer in de76b6b. The HTML mapper correction is applied at the shared component, and the LightOn-only heading compensation has been removed. The shared implementations are identical to the corresponding follow-up PRs, so the math and heading logic need not remain duplicated in lightonocr_utils.py.

Validation of this refactor: 199 passed, 6 skipped across the VLM and related parser/pipeline tests, plus all applicable make validate hooks. Tests ran on Python 3.12. Full Linux CI has not yet validated this commit.

[PierreMesure]

Kept the shared Markdown renderer and its tests identical to #4908 in ab79d5b. This addresses the confirmed GFM side effect reported on that PR: native inline parsing must preserve literal tildes and native block text. Full-page GFM parsing remains enabled for LightOn tables.

The shared-parser and LightOn test suites pass: 36 passed, 1 skipped. UV_NO_SYNC=1 make validate passes.

[PierreMesure]

Rebased onto current main (1ee1db0f) after #4964 merged. Removed the obsolete shared-helper changes. The mapper now supports normalize_heading_levels=False, the pipeline uses that mode, and LIGHTONOCR_MARKDOWN is included in the formats normalized once after joining pages. New tests cover standalone headings and two-page joins with and without a depth-1 section.

Synced the shared renderer and its tests with #4908, including the currency-range review fix, while retaining full-page GFM tables. Updated the heading documentation and PR description.

Validation: 193 passed, 2 skipped for the focused LightOn/shared/preset/optional-dependency suites; 267 passed, 1 skipped in a clean combined merge with #4908. make validate and hooks on all changed PR files pass. New CI is pending.

@cau-git, it's ready to review! 😊

[cau-git]

@PierreMesure Thanks, the integration follows the other VLM adapters well.

Before merge:

1. markdown_math.py now differs from fix: preserve native VLM inline math through exports #4908 (parser cache, render_math fallback). Please merge fix: preserve native VLM inline math through exports #4908 first, then rebase and drop the copy here.
2. Headings with math lose their text (## Theorem $x$ gives empty item.text). This is the same issue as in fix: preserve native VLM inline math through exports #4908 and docling-core#924.
3. Please add the presets to docs/usage/model_catalog.md, and LightOnOCR to the list in "Heading depths in native layout output".
4. Please add LightOn to tests/test_vlm_heading_exports.py instead of a separate heading test file.
5. Optional: give chart pictures the OTHER_CHART class, like Nemotron 3.5, so chart data is kept. Optional: add one real model output under tests/data when you have one.

Since docling-core#924 is merged, #4908 should become mergeable and then this one too.