Skip to content

feat(docscout): read extraction values from page images - #65

Closed
wolfy-j wants to merge 1 commit into
fix/docscout-verified-semanticsfrom
feat/docscout-page-images
Closed

wolfy-j wants to merge 1 commit into
fix/docscout-verified-semanticsfrom
feat/docscout-page-images

Conversation

@wolfy-j

@wolfy-j wolfy-j commented Nov 11, 2026

Copy link
Copy Markdown
Contributor

Stacked on #62 (which carries #61, #59, #55, #53). Base branch: fix/docscout-verified-semantics.

What

stages.extract.reads: text | pages (unset = text, today's behaviour) and stages.extract.max_pages (1-32, required when reads: pages).

With reads: pages:

  • Read step loads the upload's page images after the content provider has admitted the caller to the upload, and reports how many pages have one.
  • Map, Prefetch, Scout, Deep run on the text as before, but only choose pages. Deep writes no analysis prose because nothing reads it.
  • Extract sends page images in page order, each under a [Page N] label, then the field lines. No passages, scout notes or analyses go in. Evidence is {page: enum of sent pages, quote}.
    • All-pages path: when a call's eligible pages with an image fit max_pages, it reads them all, with or without passages. This bypasses the empty-passage gate.
    • Long inputs: each field ranks the passages visible to it (cited, then found by its own searches, then by search rank). Fields take passages in turns while their distinct pages fit max_pages, using the existing F4 allocate. A field none of whose own pages fit gets page_budget_cut. Recall on long inputs therefore still depends on the text.
    • search_within: sections is a page-level boundary: a field reads only the pages that hold chunks of its region (from chunk page spans). A page shared by two regions is visible to both.
  • Verify follows the extract modality.
    • Visual support check, batched under max_pages images and the model window. It shows the cited pages, plus the next page for text and list values, with field description, value, quotes and their pages. Per field it answers quote_on_page, states_value (yes | no | unreadable) and, for text and lists, complete. verified requires both yes. Otherwise the cause is quote_not_on_page, support_rejected or support_unreadable.
    • Without check_support, a value read from pages is unverified (unchecked).
    • With check_quotes, each quote is matched against the processed text of its page. evidence.text_agreement is agrees | differs | no_text. It is recorded only and never gates.
    • Shape and format checks are unchanged.
  • Trace: call records gain pages and excluded_pages.
  • ai.structured accepts content parts (text and prompt.image_base64), so the request stays provider-neutral. The openai_compat mapper converts image parts to image_url.

Design notes

  • Page source. This uses the page images uploads produces today. There is no new platform contract.
    • Sources: kickside.uploads.rasterize:page_images.page_set, which covers rendered pages for pages that needed OCR and uniquely numbered page-sized doc2md scans. This is the same definition the rasterizer and OCR share. kickside.uploads:trusted_reader.image_bytes reads the bytes, and source_image covers an image upload.
    • Both are trusted libraries. DocScout reads them only for the upload whose content kickside.contract:content_provider has already admitted the caller to, in the same run.
    • Known gap, left visible: no checksum binds the page images to the Markdown revision. The content provider has no page manifest yet.
  • Pages without an image are reported, never read from text. In pages mode verified means model-supported visual evidence, and requests carry no document text. A text fallback would change both meanings per page without any visible signal.
    • A missing value whose eligible pages lack an image carries page_image_unavailable, naming the pages.
    • A found value is not gated by other pages lacking an image. This matches the budget rule: a field is flagged when nothing it needed could be read.
  • Model capability. Capability metadata is not used as a gate. The llm module has no vision gate on structured output, and media parts stay unestimated in its admission check. Image count is bounded by max_pages, and a provider refusal surfaces as a call error.
  • Run modality. It comes from run state: a run reads pages exactly when the read step loaded its page images.
  • Schema builders. shapes.group_schema and the new page_group_schema share one builder and differ only in the evidence locator.

Not in this PR

  • source_page for uploads sliced from another upload. A Markdown upload created from part of another upload has no page images, and uploads records no parent-page map for it. The parent upload id is used only to freeze execution identity (platform/uploads/src/uploads.lua freeze_current_identity). trusted_reader.image_bytes reads only artifacts of the same upload, and content_provider exposes get_content and get_info only. Such an upload reports page_image_unavailable for every page until uploads carries a child page map with authorized parent artifacts.

Tests

New suite docscout_pages with synthetic PNG pages (generated in Lua, printed text in a tEXt chunk) and a vision fixture model. The fixture reads the page images and refuses any request that carries document text or puts a page after the field text. Coverage:

  • all-pages reading, including a value no text search finds
  • no document text in the request
  • text_agreement agrees, differs and no_text
  • a missing page image (page_image_unavailable, no text fallback)
  • no images at all
  • visual verdicts (rejected, unreadable, quote not on page)
  • continuation page for text values
  • unchecked without the support check
  • contract validity
  • Deep without analysis
  • long-input ranking and the page budget cut
  • section page boundary
  • image upload original as page 1
  • max_pages required with pages

Red on the base: the configuration schema rejects reads. Gates: lint clean; SQLite 212/212, Postgres 212/212 (base 195); UI vitest 110/110, vue-tsc clean, static rebuilt. check-package-bindings.py fails the same way as on main (package_selected includes kickside.security.groups:members).

stages.extract.reads: pages reads values from the upload's page images,
with max_pages page images per call. Text stages only choose pages;
verification checks each value against its cited page image and records
whether the quote agrees with the page's processed text.
@wolfy-j

wolfy-j commented Nov 12, 2026

Copy link
Copy Markdown
Contributor Author

Superseded by #86, merged and released.

@wolfy-j wolfy-j closed this Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant