Skip to content

Receipts and unknown pages

Every Result contains extracted pages and a receipt. A receipt is the record of what docgate actually did; it is the right place to check completeness, cost, degraded providers, render clamps, and unread pages.

result = docgate.read("bundle.pdf", providers=[vision])

print(result.receipt.complete)
print(result.receipt.spent)
print(result.receipt.degraded)
print(result.receipt.unknown)

Stable JSON for operations

Receipt.to_dict() returns a versioned, JSON-safe operational record. Decimal amounts are strings to preserve precision. It never contains document text, images, source paths, filenames, or provider secrets.

import json

event = result.receipt.to_dict()
print(json.dumps(event))

Result.to_dict() also excludes transcription text by default. Applications that intentionally need text in the serialized result must opt in with result.to_dict(include_text=True).

The top-level schema_version starts at "1.0". New optional fields may be added within a schema version; removing or changing the meaning or type of an existing field requires a new schema version.

Command line

The CLI uses the same local-only planner and receipt contract:

docgate plan bundle.pdf --need "experience letter" --selection top_k \
  --max-paid-pages 2 --json

docgate read notes.docx --json
docgate read notes.docx --json --include-text

docgate read exits with code 2 when the receipt is incomplete, which makes unknown pages enforceable in shell scripts and CI. The CLI does not configure remote providers in v0.2; use the Python API when OCR or vision calls are required.

No ambiguous unread pages

An empty string is not used to represent a page docgate could not read. Instead, each such page is an immutable Unknown record with a page number, an UnknownReason, and detail. receipt.complete is true only when no unknown records exist.

Reason Meaning
render_failed The selected PDF page could not be rasterized.
providers_failed No provider was configured or the provider ladder was exhausted.
budget_exhausted A hard budget stopped selected work before an extra attempt.
skipped_by_plan The local selection policy excluded the page.
oversized Reserved reason for an oversized input condition.
encrypted The document could not be read because it is encrypted.
corrupt Local extraction failed for a page.

Applications decide what to do with incomplete output: retry later, request a different file, route a page to a manual process, or halt a workflow. docgate does not turn the receipt into a business verdict.

Other receipt fields

  • spent and quotes describe the provider estimates accepted during this run.
  • cached_pages records successful cache reuse. Cache hits have no provider estimate in the receipt.
  • degraded lists provider failures, open breakers, and quality-gate rejections with provider and fallback information.
  • clamps records any raster output reduced to honor the pixel bound.
  • wall_seconds and peak_memory_mb report run-level operational metadata.

Result.text joins completed page text with blank lines. It intentionally does not manufacture placeholders for unknown pages; use result.pages together with receipt.unknown whenever ordering and provenance matter.