Engine · PDF tools

OCR extraction

Follow an image through a reader, then keep the text, its source and any unread pages together.

Workflow

  1. REFUSED · invalid pagesInvalid identities, page order or metadata are rejected before the reader runs.
  2. Validate ordered pagesCreate PageInput records for known source bytes. ordered_pages rejects an empty set, duplicate identities, invalid language or transform metadata and gaps in the one-based page order before any reader is called.
  3. Read the next imageRoutedOcr accepts image pages and calls recognize_or_read. Recognized text and rough text remain different read results. A plain-text fixture reader is useful for deterministic tests but must not be called image recognition.
  4. TEXT · attach page citationNonempty text is retained with its page citation and original bytes. Confidence may be absent; it must not be manufactured from a rough read. Citation metadata identifies the page, not a guarantee that every character is right.
  5. ABSTAINED · no text foundAn empty reader result creates an abstained page with no citations. The batch may still be complete: complete means the pages were handled, not that every page yielded text.
  6. STOP · preserve earlier pagesRefusal marks the current page unsupported and remaining pages skipped, returning partial. WorkerUnavailable marks the remaining pages unavailable. Earlier page results are retained. Invalid reader result types or confidence are refused.
  7. More pages?Continue page by page only while the adapter remains usable. Keep all page outcomes in order so the caller can distinguish extracted text from abstention and incomplete work.
  8. Return text and page outcomesConsume the explicit aggregate and per-page statuses. A later workflow may analyze this text or turn it into a searchable PDF; neither is performed simply by receiving an OCR result.

Failure boundaries

  • Invalid page order/identityRequest refused: Reader not called
  • Reader returns no textPage abstained: No fabricated citation
  • Unsupported pagePartial result: Earlier reads retained
  • Reader unavailableUnavailable result: Earlier evidence retained

engine.pdf.ocr