Skip to main content
ai.parse turns a document into text. It is almost always the first step in a document-understanding workflow: point it at an uploaded file, get back clean text plus per-page content, then feed that into ai.extract, ai.split, or a transform.script.

​
When to use it

  • You have a PDF, image, or Office document and need its text. ai.parse handles PDFs, images (PNG/JPG), and Office formats (DOCX, PPTX, XLSX, ODT, and more), normalizing them to one text representation.
  • You need per-page boundaries. The pages array carries page-scoped text so downstream steps can cite evidence by page or split a document into sections.
  • You need document geometry or spatial extraction. Layout-aware OCR also returns normalized pages[].layoutElements and, when the provider supports it, a canonical OpenParser ParsedDocument on structured — blocks, regions, tables, figures, chunks, polygons, and bounding boxes. Pass the whole parse output (not just .text) into downstream ai.extract to enable shared grounded extraction, spatial citations, and lineage sidecars.
  • You need strict data-egress control. Use parseMode: native when embedded PDF text is enough and document bytes must not leave your deployment for OCR or vision. Use parseMode: native-or-ocr when most pages have good embedded text but some pages show objectively detectable extraction anomalies.
  • You need column-aligned native PDF text. Use outputFormat: layout with native extraction when markdown would flatten multi-column tables or forms and you want fixed-width plain text with horizontal gaps preserved.

​
How parsing is chosen

The step picks a strategy based on the document and your config:

​
Native (parseMode: native)

Local extraction only — embedded PDF text is read in the worker with no OCR or vision egress. There are no parsing credits. Raster images (PNG, JPG, TIFF, and similar) are not supported in this mode. describeFigures is incompatible — figure descriptions require a vision pass. Native extraction is not a universal OCR replacement. PDFs can render glyphs without usable Unicode mappings; diagnostics report detectable problems (empty pages, replacement characters, forbidden controls, unassigned/noncharacter code points, heavy private-use) but cannot certify that valid-looking text is semantically correct. If every page is empty or suspect, the step fails instead of returning unusable text or silently calling OCR. Mixed documents keep the native text and attach per-page nativeTextQuality. Office formats and plain text still use native extraction. Paginated word-processing and presentation formats use headless LibreOffice when per-page boundaries are needed. Spreadsheets are read directly: each non-empty sheet becomes a named page, including legacy and macro-enabled Excel workbooks. Formulas and macros are never executed. Blank sheets are omitted and pageIndex counts the returned non-empty sheets, so use pageName when you need the workbook’s sheet identity.

​
Spatial layout text (outputFormat: layout)

Returns the same text and pages[].text fields as other formats, but as fixed-width plain text that preserves column spacing and line breaks from the PDF page layout. Use it for multi-column forms, tables, or address blocks where markdown (the default) would collapse horizontal alignment. Constraints:
  • PDF only — Office files, images, and plaintext fail. There is no Kreuzberg or OCR substitute for those types.
  • Explicit native parse mode — set parseMode: native or parseMode: native-or-ocr. Omitted parseMode, OCR, vision, and nativeText: true reject layout.
  • Native mode is fail-closed — every page is spatial layout text. If extraction fails, the step fails.
  • Hybrid output can mix formats — native-or-ocr keeps layout text on accepted native pages and uses the OCR provider’s markdown on suspect or empty pages.
  • Extractor failure is fail-closed — a Poppler process error never silently routes to Kreuzberg or OCR.
  • Other formats unchanged — markdown, plain, djot, and html behave as before; markdown remains the default.
Local development requires pdftotext on PATH (brew install poppler on macOS, poppler-utils on Linux). Managed deployments include this dependency.

​
Native with OCR fallback (parseMode: native-or-ocr)

Starts with the same local native extraction, then runs page-quality diagnostics on each PDF page. Pages with objectively detectable anomalies — empty text, U+FFFD replacement characters, lone UTF-16 surrogates, forbidden controls, unassigned/noncharacter code points, or heavy private-use areas — trigger the configured OCR engine. Valid-looking wrong mappings and literal ? characters are not flagged; native diagnostics report detectable issues but do not certify semantic correctness. When the OCR provider supports page selection, only fallback pages are processed and billed. Page selection does not imply reduced-byte egress: a provider may still receive the original document bytes. When page selection is unavailable, the provider processes and bills the whole document. Only detected fallback pages replace native pages in the merged output; clean native pages are retained. With outputFormat: layout, retained native pages stay as fixed-width layout text and replaced pages use OCR markdown. You pay OCR credits for pages actually processed by the provider — see output.usage.ocrPagesProcessed (which may reflect a whole-document OCR call even when only some pages replace native text). Per-page provenance is recorded on each page (pages[].provenance).

​
OCR (parseMode: ocr, the default)

Runs optical character recognition for scanned PDFs and images. Select the engine with ocrModel. Document bytes are sent to the OCR provider — billed per page according to the provider’s credit rate.

​
Vision AI (parseMode: vision)

Reads rendered page images with the selected llmModel. Page images are sent to the vision provider — billed per page. Use it for layouts where semantic visual understanding matters. pagesPerBatch and maxConcurrency tune how pages are batched.

​
Legacy document-wide native text (nativeText: true)

When set on OCR or Vision configs, the worker tries embedded PDF text first and falls back to the selected parser for the whole document if native text is missing. This is legacy behavior — prefer explicit parseMode: native or native-or-ocr for predictable egress and billing.

​
Figure descriptions (describeFigures: true)

Optional vision pass after text extraction. With OCR or hybrid native+OCR, figureModel chooses the caption model; with Vision AI, the selected llmModel is reused. Unavailable in Native mode. The layout scan and caption calls are billed separately and send page images to the vision provider. Paginated Office formats are converted to PDF first (via headless LibreOffice) so they get true per-page boundaries instead of a single blob. Spreadsheets stay workbook-native to avoid cropping wide sheets.

​
Data egress and cost

There is one combined text output — the worker does not emit separate native and OCR text streams.

​
Example

For a digital PDF with one page of garbled embedded text, most pages stay native in the merged output. OpenParser currently processes the whole document for OCR, so every page incurs OCR processing and credits. Azure can process and bill only the anomalous page, but the current Azure adapter still uploads the original PDF bytes; page selection is not a subset-egress guarantee.

​
Configuration

Configuration goes inside the step’s with: block.
​
string
required
Storage reference or template expression for the document
​
"ocr" | "vision" | "native" | "native-or-ocr"
Base parser for PDF/image inputs. OCR is the default; vision uses the selected LLM. native extracts PDF embedded text only and never calls OCR or vision. native-or-ocr extracts native text, runs page-quality diagnostics, and requests OCR when pages have detectable anomalies (empty, U+FFFD, lone surrogates, forbidden controls, unassigned/noncharacter, heavy PUA). Page selection, subset egress, and billing are provider-dependent. Valid-looking wrong text and literal ”?” are not flagged. Text and Office files always use local parsing.
​
string
OCR provider ID for PDF/image parsing
​
string
LLM provider ID for vision-based parsing
​
"none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"
Reasoning effort for models that support it. Omit to use the selected model’s default.
​
string
Vision model used only for the optional figure-description pass
​
"none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"
Reasoning effort for models that support it. Omit to use the selected model’s default.
​
number
default:"3"
Max concurrent VLM batch requests
​
number
default:"5"
Number of page images per VLM request
​
number
default:"1"
Scale factor for rendering PDF pages before VLM parsing. Higher values produce sharper images at larger payload sizes.
​
integer
default:"85"
JPEG quality for rendered PDF page images sent to VLM parsing. Higher values reduce compression artifacts at larger payload sizes.
​
string
Custom extraction prompt
​
array<string>
OCR language hints
​
"plain" | "markdown" | "djot" | "html" | "layout"
default:"markdown"
Format for extracted text. markdown (default) keeps structure; plain is unstyled text; djot/html preserve more markup. layout is native-PDF spatial text with column gaps preserved as spaces. It requires parseMode: native or parseMode: native-or-ocr and a PDF, omitted parseMode and nativeText: true are not enough. Native mode is layout-only and fail-closed. native-or-ocr keeps layout text on accepted native pages and uses OCR markdown on suspect or empty pages, so the document can mix fixed-width layout and markdown. Extractor failure never falls back to another parser. Office, plaintext, and images fail. OCR/vision cannot request layout.
​
boolean
default:"false"
Extract native/embedded text from PDFs without OCR/VLM. Faster and uses no credits. Falls back to OCR/VLM if the PDF has no embedded text.
​
boolean
Opt-in (default off). After text extraction, detect which pages contain figures with an in-worker layout model, then caption those pages with a vision model and append &lt;figure>description&lt;/figure> to their text, so image-only pages (property photos, signatures, charts) become findable by text-based steps like ai.split. Note: the layout scan runs over all pages, and the caption step and its vision calls are billed. Skipped for plaintext.
​
string
Custom instruction for the figure-description pass, e.g. “Describe each figure; label a handwritten signature as &lt;figure>signature&lt;/figure> and a stamp as &lt;figure>stamp&lt;/figure>; for property photos note the room or exterior shown.” Applied only when describeFigures runs.

​
Output

After a run, inspect processingStrategy for the resolved path: native, ocr, vision, or hybrid (native pages merged with OCR on fallback pages). Each page may include provenance (native or ocr) and nativeTextQuality when native diagnostics ran — diagnostics report detectable anomalies only, not semantic correctness. usage.ocrPagesProcessed counts pages billed through the OCR provider on hybrid runs. structured carries an OpenParser ParsedDocument (openparser@1) when the parser produced one. Downstream ai.extract validates it at runtime; invalid or absent structured data keeps text-only extraction and text grounding. Per-page provenance badges in Studio run detail are planned; until then use these output fields in templates, CLI inspection, or the execution JSON view.
Combined text from all pages
Model used (for LLM/OCR parsers)
How this result was produced: native (local PDF text only), ocr, vision, or hybrid (native pages merged with OCR on fallback pages).
Canonical structured document with ordered blocks, regions, bounding boxes, tables, figures, and chunks when supported by the parser