Skip to content

feat(docscout)!: read and verify extraction values from page images - #86

Merged
wolfy-j merged 16 commits into
mainfrom
feat/docscout-page-contract
Nov 12, 2026
Merged

wolfy-j merged 16 commits into
mainfrom
feat/docscout-page-contract

Conversation

@wolfy-j

@wolfy-j wolfy-j commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Extractors opt into physical page images with stages.extract.reads = "pages" and a per-call max_pages ceiling. Extraction and visual verification consume the authorized, revision-bound uploads contract, require vision before document work and include base64 image bytes in the existing context budget. Shared or unproven section boundaries return typed failures. Completeness remains unavailable, with visual_completeness_unavailable, unless verification receives every eligible page in the field's section intersected with the run's page range; unavailable completeness preserves successful support verification, matching main when optional completeness context cannot be admitted. Unavailable quote or value support still leaves the value unverified.

Images already read for a source revision are reused across extraction groups and field checks within that run. The run-local holder retains at most 16 MiB of image bytes and evicts least recently used pages beyond that cap. Active request images are separate from that holder cap. Stages access the holder sequentially. Replaced entries subtract their previous bytes before insertion. The holder is never persisted and ends with the run; model requests still carry their required images. A run stays pinned to its discovered source revision; a source replaced mid-run returns revision_mismatch on the next uncached read.

Runs and evaluation scores persist explicit visual checks and image identities. The UI saves the setting and displays visual verification after saved-result reload. Page-mode admission errors show their API message; text-mode pre-run error handling and result labels remain unchanged.

Supersedes #65. This reimplementation credits the opt-in setting and synthetic vision fixtures from #65 (2c52c33), replaces its internal uploads helper route, and preserves main's range, provenance and request budgeting behavior.

The breaking ! specifically changes the evidence contract for opt-in image results: evidence has page, image_checksum and source_revision instead of the previously mandatory chunk_id. Consumers assuming every evidence item has a chunk ID must handle the image variant. Text evidence is unchanged. Optional visual metadata is absent from text results. No schema migration or historical rewrite is required. The uploads dependency remains *; integration resolves published uploads 0.3.16 and LLM 0.5.19 without a local uploads replacement.

Setting-off identity is proven at the fixture level for backend request bodies, call records, outcomes, field summaries and stored results. The captured baseline covers absent and explicit text reads, Verify enabled/disabled, and completeness policy absent/false, normalizing generated chunk IDs and latency. This is fixture coverage, not a claim of exhaustive equivalence.

Validation:

  • Official runtime v0.3.59a: the complete native gate passes 383 tests on each engine. Focused regressions pass on SQLite and PostgreSQL, including the four-page extraction/two-page verification case, repeat-read counts, replacement accounting, 16 MiB eviction, new-run isolation, successful support with unavailable completeness, unreadable-support rejection and text identity.
  • UI suite passes 148 tests. Typecheck, Lua lint and static rebuild through make build pass.
  • Browser guard covers a scanned PDF through a synthetic vision provider, setting save, persisted runs and evaluations, unavailable completeness after partial visual coverage, budget and boundary failures, and nonvision refusal on both engines.
  • Coverage tests, generated scenario-map check and UI guard audit pass.

KickSide added 16 commits November 11, 2026 19:23
Read authorized revision-bound pages through the uploads contract. Admit vision models before document work and include image bytes in the existing context budget. Persist visual verification in runs and evaluations.

BREAKING CHANGE: page-image evidence uses page, image_checksum and source_revision instead of chunk_id. Text-mode requests, results and saved configurations keep their existing shape.
@wolfy-j
wolfy-j merged commit 0cc372d into main Nov 12, 2026
16 checks passed
@github-actions github-actions Bot mentioned this pull request 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