01

Where deterministic parsing wins

Digital PDFs and Office files often contain text, coordinates, styles, and object relationships that can be extracted directly. Deterministic code produces repeatable results, supports regression testing, and avoids model calls. It is usually the right first path for clean, high-volume cohorts.

Deterministic does not mean simplistic. Reading-order algorithms, font analysis, table rules, and native Office parsers can recover substantial structure without generation.

02

Where OCR and vision are necessary

A scan contains pixels, not usable text. OCR recognizes characters and boxes. Complex diagrams, formulas, and visually encoded relationships may require layout models or vision-language reasoning when deterministic evidence is insufficient.

Model-backed output carries different risks: nondeterminism, model drift, higher latency, provider cost, and potential egress. Record model and route metadata and reserve spend before the call.

  • OCR for image-only text and scanned pages.
  • Layout analysis for regions and reading order when geometry is ambiguous.
  • Vision-language processing for approved complex tables, formulas, or figures.
  • Human review when uncertainty has material consequences.
03

Use a cascade, not a binary switch

Inspect format, size, embedded text, and requested output. Start on the lowest-cost route expected to meet the cohort’s quality target. Escalate only on evidence such as empty output, scan detection, missing structure, or an explicit high-fidelity requirement.

A rescue route should not hide the first failure. Store both attempts and explain which result was published. This produces actionable evaluation data and prevents expensive fallback from becoming an invisible default.

04

Govern routing as product policy

Capability must be granted by workspace. Untrusted callers should not select provider names or arbitrary models. Apply daily and tenant limits, host allowlists, timeouts, and retry caps.

Review route distributions and quality by cohort. If a deterministic path meets the target for most documents, protect it; if a scan cohort repeatedly fails, improve or reroute that cohort deliberately.

05

The file to send

The trial runs the deterministic path. Send a text-based PDF and leave fastMode, highFidelity, and suspectedScanned unset.

Those flags, and an image file name, return HTTP 403: Trial workspaces use deterministic parsing only. AI image, Fast, and Layout-aware processing require an approved paid workspace. A PDF of page images without those flags can still reach local OCR on an empty page.

  • result.manifest.decision.route is container for this PDF.
  • Read metadata.warnings before treating the text as a clean text-layer result.
  • The request does not name an internal model.
export DOCPARSE_URL="https://docparse.genedai.me"
export DOCPARSE_API_KEY="your_key"

curl -fsS -X POST \
  "$DOCPARSE_URL/v1/parse?wait=true" \
  -H "Authorization: Bearer $DOCPARSE_API_KEY" \
  -F "file=@document.pdf" \
  -F "mode=both" \
  -o result.json

jq -r '.result.markdown' result.json
jq '.result.document.schemaVersion, .result.document.pages[0].blockIds' result.json
jq '.result.manifest.decision.route, .result.manifest.parserVersion' result.json

Frequently asked questions

Questions this guide answers

Is AI parsing always more accurate?

No. It may help with visually complex or scanned documents, while deterministic extraction can be more stable and precise for native digital structure.

Can a parser automatically detect scans?

It can use embedded-text evidence and page imagery as signals, but detection should be evaluated and route decisions should remain observable.

What is a parser cascade?

A cascade starts with an appropriate low-cost route and escalates to OCR or vision only when source evidence, requested fidelity, or validation indicates it is needed.