Repository navigation
Add verified image evidence for OCR when native PDF text is absent or corrupt #18
Description
Problem and verified cause
The OCR path currently cannot reliably repair the native text it depends on. In olmocr_assess, each OCR paragraph is located by matching it to native PDF lines, and its boxes are marked as native-alignment estimates. assess_document then requires native alignment before proposing evidence. Missing text, broken encodings, or corrected mathematical notation can therefore produce a valid-looking OCR transcription with no acceptable native span.
The September 28 diagnosis confirmed this mechanism in code; it did not establish a successful image-based replacement. Retrieval case f076 separately demonstrates the empty-native-text condition: its first page is an image-only cover. It is a searchability case, not evidence that an abstract exists on that page. Existing PDF reviews in pdf_admission.py record attributed attestations, not signatures or independent human qualification.
Intended behavior and scope
Keep native text evidence for healthy PDFs. Add a separately typed image/crop evidence route that can propose and review transcriptions against original visual evidence, then support an explicit application handoff. An OCR guess must never acquire fabricated native offsets, estimated boxes presented as observed geometry, or graph publication authority.
Implement and document:
- Versioned records binding original PDF, physical page, rendered image and crop hashes; image dimensions; crop coordinates and coordinate system; renderer/rotation/scale transforms; OCR model/converter revision and configuration; raw output hash; transcription; and review disposition.
- Validation that a crop is derived from the identified page image, including rotation and scale round trips and out-of-page rejection. Distinguish observed image locations from model estimates.
- An attributed verification/review receipt binding the exact transcription, crop and source identity. Hashes prove identity and integrity; review must assess transcription accuracy, reading order, boundaries and notation. Changed source bytes or edits invalidate prior review.
- A documented admission handoff into the existing text evidence contract: if reviewed transcription becomes a text representation, its offsets are offsets in that immutable derived representation, with an auditable image lineage.
Catalog.verify_evidencecurrently verifies exact source-text offsets; preserve that guarantee. Any schema changes must update both generated/runtime schema trees and consumers. - Explicit held states for unreviewed or ambiguous text, absent/partial abstracts, uncertain equations, generation truncation, character/request limits and source-scope mismatch. OCR style loss must not be mistaken for native typography.
PyMuPDF OCR documentation explains why original bold/italic/color cannot be assumed after OCR. MinerU2.5 motivates separating layout analysis from crop recognition. These are design references, not measured success on our corpus.
Acceptance and deliverables
- Synthetic image-only and broken-encoding PDFs reach a source-review state without native text or fake offsets; a reviewed correct transcription can complete the documented evidence handoff.
- Rotated/cropped pages, repeated text, mismatched page/image hashes, edited transcriptions, hallucinated words, altered equations and out-of-bounds boxes are covered by positive/negative integration cases.
- A real authorized subset exercises both image-only and corrupt-native conditions. Report transcription/boundary/notation errors, accepted coverage and review workload separately; uncertain examples remain held.
- Native evidence regression checks pass; image-backed success is reported separately from the historical first-page native-span metric.
- Deliver versioned contracts, implementation, public synthetic fixtures, review instructions, migration/compatibility notes and a sanitized hash-bound experiment receipt. Keep raw PDFs, crop images, private text and labels external.
- Run existing focused checks
python -m unittest discover -s tests -p 'test_parallel_source*v4.py' -qplus meaningful new image/admission tests and required release/package validation.
Inputs and authority
Implementation and synthetic tests need no paid API or production writes. The real subset requires authorized source images, a licensed installed OCR model or an explicitly approved provider/account/budget, and attributed reviewers qualified for ambiguous notation. Record missing inputs as blocked or NOT RUN. Assistant review must be labeled as such. This issue authorizes neither automatic OCR admission nor production graph publication; use existing review and trust boundaries.
Tracking and completion dependencies
Parent: #12. Milestone: Paper extraction and GraphRAG qualification.
Completion prerequisites: #13, #14. These are native blocked-by links; design, fixtures and other independent implementation work may proceed in parallel.
Required by: #20.
Activity
CompleteDotTech commentedon Sep 28, 2026
Acceptance audit complete for the bounded reviewed-image evidence route, after prerequisite #14 closed. PR #30 is merged at b8dc4b0; its integration validation ran 660 tests (654 pass, six skip), package validation passed and all three postmerge main jobs passed in run 36450469487. On current merged d7af957, a separate reviewer reran all 19 focused image tests and read back the exact implementation, source/image/crop/raw OCR and catalog lineage.
The authorized exposed four-page diagnostic made four real local OCR calls: raw acceptance 0/4, three cases held, and one explicitly assistant-corrected f059 transcription reached
REVIEWED_TEXT_EVIDENCEwithadmitted=false. Two authored synthetic calls also passed. Five real candidate reviews and one correction were recorded; duration was NOT_MEASURED. The private receipt SHA-2560d194c973d57285ac767935fb37dea5c21b791078f26927ea44faa697567d790rehashed all 98 artifacts without drift and binds the public sanitized receipt SHA-25603abc4b5249b43a0403a216e95d289114a9f56df01602bbc15502d451700f5cb. Memory-only current-tree replay reproduced the five real handoff states/catalog digests. No new OCR call, independent human review, unseen-paper claim, paid call or graph write was made in that replay.All six #18 acceptance checkboxes are complete for this image-evidence implementation and exposed real subset. Native extraction metrics remain separate. Closing #18 does not pass #19 image-enabled promotion, #20 unseen qualification, or #23 the real paper-to-cited-answer pilot; those issues remain open.