feat(ocr): parser service (routing + per-page merge)

[JonnyTran]

Summary

Phase 1 task from the retrieval plan: contexts/ocr/parsers/service.py.

• PageParser Protocol: parse_pages(pdf_bytes, pages, *, ocr) -> dict[int, list[LayoutBlock]]
• ParseTask(pages, parser, ocr, bbox=None), ParsePlan (+ pages_by_parser, ocr_pages for the later LayoutMetadata write)
• ParserService.plan(): triage pages_needing_ocr → liteparse with OCR; other pages → pymupdf if installed, else liteparse without OCR. pdf_inspector is explicit-only.
• ParserService.parse(): runs each task, merges blocks per page by (top, left); region tasks (bbox) keep only blocks mostly contained in the region (CONTAINMENT_THRESHOLD).
• build_document(blocks, page_sizes=…) → DoclingDocument via the existing docling_builder.

Parsers are injected as a mapping; pymupdf.py/pdf_inspector.py/registry.py are unchanged (their PageParser refactor and liteparse.py are separate tasks). ocr_jobs.py untouched.

Test plan

• tests/unit/contexts/ocr/test_parser_service.py: routing table (scanned / digital / no-pymupdf / fully scanned / unknown triage / page allowlist), task dispatch with ocr flag, cross-task per-page merge order, region containment filter, unknown parser error, build_document provenance and empty-page registration.
• uv run pytest tests/unit/contexts/ocr --noconftest (storage/layout_store lance tests deselected; known-failing locally): 112 passed, 1 skipped.

Summary by CodeRabbit

• New Features
  • Added PDF parsing that automatically selects OCR for scanned pages and standard extraction for digital pages.
  • Added support for restricting parsing to selected pages or regions.
  • Combined extracted content across pages into a single structured document while preserving page information and document provenance.
  • Empty pages are retained in the resulting document, including their page dimensions.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
extralit-frontend	Ignored	Preview	Sep 16, 2026 7:01am UTC

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 16c68421-95f5-435b-afba-374250d0df76

📥 Commits

Reviewing files that changed from the base of the PR and between fa0fad8 and caea4a3.

📒 Files selected for processing (2)

• extralit-server/src/extralit_server/contexts/ocr/parsers/service.py
• extralit-server/tests/unit/contexts/ocr/test_parser_service.py

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

This change adds an OCR parser service. It plans page routing, executes registered parsers, filters and merges layout blocks, and builds a DoclingDocument with page metadata and provenance. Unit tests cover planning, parsing, filtering, and document construction.

Changes

OCR parser service

Layer / File(s)	Summary
Parser planning contracts extralit-server/src/extralit_server/contexts/ocr/parsers/service.py, extralit-server/tests/unit/contexts/ocr/test_parser_service.py	Defines PageParser, ParseTask, and ParsePlan. Routes scanned pages to liteparse with OCR and digital pages to pymupdf when available. Uses liteparse without OCR as the fallback.
Parsing and document assembly extralit-server/src/extralit_server/contexts/ocr/parsers/service.py, extralit-server/tests/unit/contexts/ocr/test_parser_service.py	Runs planned tasks, applies bounding-box containment filtering, merges blocks in reading order, and builds a DoclingDocument with page sizes, provenance, and empty pages registered.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant ParserService
  participant triage
  participant PageParser
  participant build_document
  ParserService->>triage: derive page routing metadata
  ParserService->>PageParser: parse planned pages with OCR flag
  PageParser-->>ParserService: return page blocks
  ParserService->>build_document: merge blocks and register pages
  build_document-->>ParserService: return DoclingDocument

Loading

Merge Risk: ⚪ Minimal · up to caea4

The OCR parser routing and document assembly changes have no identified merge-blocking issue.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 7.69% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 26 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding an OCR parser service for routing and per-page merging.
Description check	✅ Passed	The description provides a clear summary of the implementation and a specific test plan with reported results. It does not include all template sections, such as related tickets, PR type checkboxes, d…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/ocr-parser-service

Warning

Git: CodeRabbit could not clone the repository, so clone-backed analysis was skipped and this review may be incomplete. Verify repository clone access, such as SSH credentials, before requesting another full review. If clone access is intentionally unavailable, use path_filters to narrow the review scope.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}