Skip to content

Add verified image evidence for OCR when native PDF text is absent or corrupt #18

Closed

Description

@CompleteDotTech

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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_evidence currently verifies exact source-text offsets; preserve that guarantee. Any schema changes must update both generated/runtime schema trees and consumers.
  5. 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' -q plus 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

  1. added
    enhancementNew feature or request
    area:contractsVersioned schemas, taxonomy, and immutable records
    initiative:paper-graphragPaper extraction, evidence admission, retrieval and real GraphRAG qualification
    area:ocrOCR, image evidence, crop coordinates and transcription verification
    priority:P2Required qualification or integration after foundational correctness work
    on Sep 28, 2026
  2. CompleteDotTech commented on Sep 28, 2026

    @CompleteDotTech
    CollaboratorAuthor

    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_EVIDENCE with admitted=false. Two authored synthetic calls also passed. Five real candidate reviews and one correction were recorded; duration was NOT_MEASURED. The private receipt SHA-256 0d194c973d57285ac767935fb37dea5c21b791078f26927ea44faa697567d790 rehashed all 98 artifacts without drift and binds the public sanitized receipt SHA-256 03abc4b5249b43a0403a216e95d289114a9f56df01602bbc15502d451700f5cb. 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:contractsVersioned schemas, taxonomy, and immutable recordsarea:ocrOCR, image evidence, crop coordinates and transcription verificationenhancementNew feature or requestinitiative:paper-graphragPaper extraction, evidence admission, retrieval and real GraphRAG qualificationpriority:P2Required qualification or integration after foundational correctness work

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions