Skip to content

A fast, helpful, and open-source document parser

docs: add new extraction and complexity capabilities to docs

Logan Markewich39f0bf3ebe27
diff --git a/docs/src/content/docs/liteparse/cli-reference.md b/docs/src/content/docs/liteparse/cli-reference.md
index 6649207..d682275 100644
--- a/docs/src/content/docs/liteparse/cli-reference.md
+++ b/docs/src/content/docs/liteparse/cli-reference.md
@@ -28,11 +28,13 @@ lit parse [options] <file>
| `-o, --output <file>` | Write output to a file instead of stdout | — |
| `--format <format>` | Output format: `json`, `text`, or `markdown` | `text` |
| `--image-mode <mode>` | Markdown image handling: `off`, `placeholder`, or `embed` | `placeholder` |
-| `--image-output-dir <dir>` | Directory to write images to when `--image-mode embed` | — |
+| `--image-output-dir <dir>` | Directory to write extracted images to. Requires `--extract-images` (or `--image-mode embed`, which implies it) | — |
| `--no-links` | Emit link anchor text as plain text (no `[text](url)`) in markdown | — |
+| `--keep-headers-footers` | Keep running header/footer chrome in markdown instead of stripping it | — |
| `--no-ocr` | Disable OCR entirely | — |
| `--ocr-language <lang>` | OCR language code (Tesseract format) | `eng` |
| `--ocr-server-url <url>` | HTTP OCR server URL | — (uses Tesseract) |
+| `--ocr-server-header <header>` | Extra HTTP header for OCR server requests, as `"Name: Value"`. Repeatable | — |
| `--tessdata-path <path>` | Path to tessdata directory | — (uses `TESSDATA_PREFIX` env var) |
| `--num-workers <n>` | Pages to OCR in parallel | CPU cores - 1 |
| `--max-pages <n>` | Maximum pages to parse | `1000` |
@@ -42,6 +44,22 @@ lit parse [options] <file>
| `--password <password>` | Password for encrypted/protected documents | — |
| `-q, --quiet` | Suppress progress output | — |
+### Extraction options
+
+By default, JSON output contains only text, geometry, and page metadata. Each option below is **off by default** and adds a new key to the JSON output. Enable only what you need — every one of them costs parse time and output size.
+
+| Option | Adds to JSON | Description |
+|--------|--------------|-------------|
+| `--extract-images` | `images[]`, `image_error_count` | Extract embedded raster image bytes and metadata. Pair with `--image-output-dir` to write files to disk |
+| `--extract-vector-graphics` | `pages[].vector_graphics` | Vector shapes and lines (`{ shapes, lines }`) with bounding boxes, stroke/fill colors |
+| `--extract-annotations` | `pages[].annotations` | PDF annotations: subtype, contents, timestamps, rects, link URIs |
+| `--extract-form-fields` | `pages[].form_fields` | AcroForm widgets: type, name, value, flags, options, rect |
+| `--extract-structure-tree` | `pages[].structure_tree` | Tagged-PDF logical structure tree (`{ roots }`), including per-element attributes |
+| `--extract-content-bounds` | `pages[].content_bounds` | Bounding box of actual content on the page, as a `Rect` |
+| `--extract-xfa-packets` | `xfa_packets[]` (document level) | Raw XFA packets from XFA-based forms |
+| `--extract-text-metadata` | extra keys on each `text_items[]` entry | Rich per-item typography: `font_height`, `font_ascent`, `font_descent`, `font_weight`, `text_width`, `font_is_buggy`, `mcid`, `fill_color`, `stroke_color`, plus `rotation` |
+| `--complexity` | `pages[].complexity` | Per-page complexity signals, including the nested `layout` object. See the [Document Complexity guide](/liteparse/guides/complexity/) |
+
### Examples
```bash
@@ -54,8 +72,21 @@ lit parse report.pdf --format json -o report.json
# Markdown output (headings, tables, lists, images, links)
lit parse report.pdf --format markdown -o report.md
-# Markdown with embedded images written to disk
-lit parse report.pdf --format markdown --image-mode embed --image-output-dir ./images
+# Markdown with extracted images written to disk
+lit parse report.pdf --format markdown --extract-images --image-output-dir ./images
+
+# Pull form fields and annotations out of a filled-in PDF
+lit parse form.pdf --format json --extract-form-fields --extract-annotations
+
+# Rich typography metadata on every text item
+lit parse report.pdf --format json --extract-text-metadata
+
+# Inline complexity signals (including layout) alongside the parse
+lit parse report.pdf --format json --complexity
+
+# Authenticated OCR server
+lit parse scan.pdf --ocr-server-url https://ocr.internal/ocr \
+ --ocr-server-header "Authorization: Bearer $TOKEN"
# Parse pages 1-5 only, no OCR
lit parse report.pdf --target-pages "1-5" --no-ocr
@@ -98,6 +129,7 @@ lit batch-parse [options] <input-dir> <output-dir>
| `--no-ocr` | Disable OCR entirely | — |
| `--ocr-language <lang>` | OCR language code | `eng` |
| `--ocr-server-url <url>` | HTTP OCR server URL | — (uses Tesseract) |
+| `--ocr-server-header <header>` | Extra HTTP header for OCR server requests, as `"Name: Value"`. Repeatable | — |
| `--tessdata-path <path>` | Path to tessdata directory | — |
| `--num-workers <n>` | Pages to OCR in parallel | CPU cores - 1 |
| `--max-pages <n>` | Maximum pages per file | `1000` |
@@ -107,6 +139,10 @@ lit batch-parse [options] <input-dir> <output-dir>
| `--password <password>` | Password for encrypted/protected documents (applied to all files) | — |
| `-q, --quiet` | Suppress progress output | — |
+`batch-parse` accepts the same [extraction options](#extraction-options) as `lit parse`: `--extract-images`, `--extract-vector-graphics`, `--extract-annotations`, `--extract-form-fields`, `--extract-structure-tree`, `--extract-content-bounds`, `--extract-xfa-packets`, `--extract-text-metadata`, and `--complexity`.
+
+It does **not** accept `--target-pages`, `--preserve-small-text`, `--image-mode`, `--image-output-dir`, `--no-links`, or `--keep-headers-footers`. Use `lit parse` per file when you need those.
+
### Examples
```bash
diff --git a/docs/src/content/docs/liteparse/getting_started.mdx b/docs/src/content/docs/liteparse/getting_started.mdx
index 74c5ec1..ed3bfa2 100644
--- a/docs/src/content/docs/liteparse/getting_started.mdx
+++ b/docs/src/content/docs/liteparse/getting_started.mdx
@@ -84,6 +84,7 @@ lit screenshot document.pdf -o ./screenshots
## Next steps
- [Markdown output](/liteparse/guides/markdown/): Render documents to clean, structured Markdown.
+- [Extraction options](/liteparse/guides/extraction/): Opt in to embedded images, vector graphics, annotations, form fields, and structure trees.
- [Library usage](/liteparse/guides/library-usage/): Use LiteParse programmatically from TypeScript or Python.
- [OCR configuration](/liteparse/guides/ocr/): Configure Tesseract, use an external OCR server, or bring your own.
- [Multi-format support](/liteparse/guides/multi-format/): Parse DOCX, XLSX, PPTX, images, and more.
diff --git a/docs/src/content/docs/liteparse/guides/agent-skill.md b/docs/src/content/docs/liteparse/guides/agent-skill.md
index 8f63f05..7a79909 100644
--- a/docs/src/content/docs/liteparse/guides/agent-skill.md
+++ b/docs/src/content/docs/liteparse/guides/agent-skill.md
@@ -2,7 +2,7 @@
title: Agent Skill
description: Add LiteParse as a skill for coding agents like Claude Code, Cursor, and others.
sidebar:
- order: 7
+ order: 11
---
LiteParse can be installed as a **coding agent skill** using Vercel's [skills](https://github.com/vercel-labs/skills) utility. This gives your coding agent the ability to process documents, generate screenshots, and parse text from files, all locally.
diff --git a/docs/src/content/docs/liteparse/guides/browser-usage.md b/docs/src/content/docs/liteparse/guides/browser-usage.md
index fa32459..1118a13 100644
--- a/docs/src/content/docs/liteparse/guides/browser-usage.md
+++ b/docs/src/content/docs/liteparse/guides/browser-usage.md
@@ -2,7 +2,7 @@
title: Browser Usage (WASM)
description: Run LiteParse entirely in the browser with the WASM package.
sidebar:
- order: 7
+ order: 9
---
LiteParse ships a WebAssembly package that runs entirely in the browser — no server, no cloud calls. It supports PDF parsing and custom OCR engines implemented in JavaScript.
@@ -38,14 +38,18 @@ console.log(result.pages[0]);
- **PDF parsing** from `Uint8Array` input (use `file.arrayBuffer()` to get bytes from a file picker for example)
- **Custom OCR** via the `ocrEngine` callback interface (see below)
-- **Text and JSON output formats**
+- **Text, JSON, and markdown output formats**
+- **Document complexity** via `parser.isComplex(bytes)` — see the [complexity guide](/liteparse/guides/complexity/)
+- **The extraction options** — annotations, form fields, structure trees, vector graphics, and the rest. See [Extraction options](/liteparse/guides/extraction/)
## What doesn't work
- **File path input** — pass `Uint8Array` instead
-- **DOCX/XLSX/PPTX/image conversion** — requires LibreOffice/ImageMagick which aren't available in the browser
+- **DOCX/XLSX/PPTX conversion** — requires LibreOffice, which isn't available in the browser
- **Built-in Tesseract or HTTP OCR** — use the custom `ocrEngine` interface instead
- **Screenshots** — not available in the WASM build
+- **`numWorkers`** — parsing is single-threaded in WASM; the option is not exposed
+- **`imageOutputDir`** — there is no filesystem to write to. Use `extractImages` and read the bytes from the result instead
## OCR in the browser
@@ -82,12 +86,22 @@ All optional, camelCase:
| Option | Type | Default | Description |
|---|---|---|---|
| `ocrLanguage` | `string` | `"eng"` | Language code passed to the OCR engine |
-| `ocrEnabled` | `boolean` | `true` | Run OCR on text-sparse pages |
+| `ocrEnabled` | `boolean` | `false` | Run OCR on text-sparse pages. Off by default in WASM — there is no built-in engine, so this does nothing without `ocrEngine` |
+| `ocrEngine` | `object` | — | Custom JS-side OCR engine (see above) |
+| `ocrFailureFatal` | `boolean` | `true` | When `false`, OCR failures return partial results instead of throwing |
+| `ocrHedgeDelaysMs` | `number[]` | `[]` | Request-hedging schedule for a remote `ocrEngine` |
| `maxPages` | `number` | `1000` | Stop after this many pages |
| `targetPages` | `string` | — | e.g. `"1-5,10,15-20"` |
| `dpi` | `number` | `150` | Render DPI for OCR |
-| `outputFormat` | `"json" \| "text"` | `"json"` | Format used by `parser.format(...)` |
+| `outputFormat` | `"json" \| "text" \| "markdown"` | `"json"` | Shape of `result.text`. Also accepts `"md"`. Throws on any other value |
| `preserveVerySmallText` | `boolean` | `false` | Keep tiny text that's normally filtered |
+| `skipDiagonalText` | `boolean` | `false` | Drop text more than 2° off the nearest right angle |
+| `cropBox` | `{ top, right, bottom, left }` | — | Fraction to crop from each side of every page |
| `password` | `string` | — | Password for protected PDFs |
| `quiet` | `boolean` | `false` | Suppress progress logging |
-| `ocrEngine` | `object` | — | Custom JS-side OCR engine (see above) |
+| `imageMode` | `"off" \| "placeholder" \| "embed"` | `"placeholder"` | How image references appear in markdown. Also accepts `"none"` for `off` |
+| `extractLinks` | `boolean` | `true` | Render `[text](url)` in markdown |
+| `keepHeadersFooters` | `boolean` | `false` | Keep running header/footer chrome in markdown |
+| `emitWordBoxes` | `boolean` | `false` | Per-word sub-boxes on each text item |
+
+The [extraction options](/liteparse/guides/extraction/) — `extractImages`, `extractVectorGraphics`, `extractAnnotations`, `extractFormFields`, `extractStructureTree`, `extractContentBounds`, `extractXfaPackets`, `extractTextMetadata`, `includeComplexity`, and `renderFormFields` — are all available here too, with the same camelCase names and the same `false` defaults.
diff --git a/docs/src/content/docs/liteparse/guides/complexity.mdx b/docs/src/content/docs/liteparse/guides/complexity.mdx
index 1e6d345..de51226 100644
--- a/docs/src/content/docs/liteparse/guides/complexity.mdx
+++ b/docs/src/content/docs/liteparse/guides/complexity.mdx
@@ -2,7 +2,7 @@
title: Document Complexity
description: Use is_complex to decide whether a document needs OCR or heavier parsing before you commit to it.
sidebar:
- order: 9
+ order: 4
---
The `is_complex` command in LiteParse checks whether a document is "complex". This means looking for images, broken/garbled text, large amounts of vector graphics, and sparse text.
@@ -27,9 +27,33 @@ The reasons are derived from a few signals:
| `embedded-images` | Substantial embedded raster figures sit alongside the native text. |
| `garbled` | The native text decodes to garbage and text is likely unreadable. |
| `vector-text` | Text is painted as filled vector outlines outside the text layer, so no native text items represent it. |
+| `annotation-text` | Meaningful text lives in PDF annotations rather than the page content stream. |
> The set of reasons may grow over time as the router learns to recommend heavier pipelines. Treat `reasons` as an open-ended list and route on the values you care about rather than assuming it's exhaustive.
+### Layout signals
+
+Alongside the OCR verdict, each page carries a nested `layout` object describing **how hard the page is to lay out** — multi-column bodies, tables, and dense figures. These are computed after spatial projection, so they see the reconstructed region tree rather than raw text items.
+
+Layout complexity is deliberately **separate from `needs_ocr`**. A crisp, fully-digital two-column paper needs no OCR at all but is layout-complex; layout reasons never make `needs_ocr` true. Route on whichever you actually care about.
+
+| Reason | Meaning |
+|--------|---------|
+| `multi-column` | The page splits into more than one text column. |
+| `table-likely` | Ruled or borderless table structure was detected on the page. |
+| `dense-graphics` | Figures cover a large fraction of the page. |
+
+| Field | Description |
+|-------|-------------|
+| `column_count` | Number of detected text columns. Always ≥ 1. |
+| `ruled_table_count` | Number of tables detected from ruling lines. |
+| `ruled_table_coverage` | Fraction of the page covered by ruled tables (0–1). |
+| `text_table_run_count` | Number of borderless, text-aligned table runs detected. |
+| `figure_count` | Number of detected figure regions. |
+| `figure_coverage` | Fraction of the page covered by figures (0–1). |
+| `is_complex` | Verdict for layout specifically. Equivalent to `reasons` being non-empty. |
+| `reasons` | Every layout reason the page was flagged with (see above). |
+
## CLI
```bash
@@ -54,7 +78,17 @@ The command always prints per-page JSON to **stdout**, a human-readable verdict
"is_garbled": false,
"page_area": 482400.0,
"needs_ocr": true,
- "reasons": ["scanned"]
+ "reasons": ["scanned"],
+ "layout": {
+ "column_count": 2,
+ "ruled_table_count": 1,
+ "ruled_table_coverage": 0.18,
+ "text_table_run_count": 0,
+ "figure_count": 3,
+ "figure_coverage": 0.31,
+ "is_complex": true,
+ "reasons": ["multi-column", "table-likely", "dense-graphics"]
+ }
}
]
```
@@ -87,6 +121,18 @@ lit is-complex document.pdf --compact | jq '[.[] | select(.needs_ocr) | .page_nu
| `--password <PASS>` | Password for encrypted/protected documents. |
| `-q`, `--quiet` | Suppress the stderr logging output. |
+### Inline with a parse
+
+`lit is-complex` is a standalone pre-parse pass. If you're parsing the document anyway and just want the signals alongside the content, pass `--complexity` to `lit parse` instead — it adds a `complexity` object to each page of the JSON output, with the same fields described here.
+
+```bash
+lit parse document.pdf --format json --complexity
+```
+
+This is off by default: computing layout signals requires the full spatial projection, so it only runs when you ask for it.
+
+> `lit is-complex` always populates `layout`. Within `lit parse`, the `complexity` object (and its `layout`) appears only when `--complexity` is set.
+
## Library
The same check is available programmatically. It returns one entry per page.
@@ -102,7 +148,7 @@ const pages = await parser.isComplex("document.pdf");
const complex = pages.some((p) => p.needsOcr);
if (complex) {
- // Route to a heavweight pipeline, like LlamaParse
+ // Route to a heavyweight pipeline, like LlamaParse
...
} else {
// Cheap path — skip OCR entirely
@@ -125,7 +171,7 @@ parser = LiteParse(ocr_enabled=False)
pages = parser.is_complex("document.pdf")
if any(p.needs_ocr for p in pages):
- # Route to a heavweight pipeline, like LlamaParse
+ # Route to a heavyweight pipeline, like LlamaParse
...
else:
# Cheap path — skip OCR entirely
@@ -173,6 +219,7 @@ Every entry includes the raw signals behind the verdict, so you can apply your o
| `uncovered_vector_area` | Filled vector-outline area not covered by native text (pt²). `null`/`undefined` when a cheaper signal already decided the page. |
| `is_garbled` | Whether the native text decodes to garbage. |
| `page_area` | Page area in pt². |
+| `layout` | Nested [layout signals](#layout-signals) for the page. Omitted when layout was not computed. |
## Next steps
diff --git a/docs/src/content/docs/liteparse/guides/extraction.mdx b/docs/src/content/docs/liteparse/guides/extraction.mdx
new file mode 100644
index 0000000..2b078a0
--- /dev/null
+++ b/docs/src/content/docs/liteparse/guides/extraction.mdx
@@ -0,0 +1,367 @@
+---
+title: Extraction Options
+description: Opt-in flags that add images, vector graphics, annotations, form fields, structure trees, and typography metadata to LiteParse output.
+sidebar:
+ order: 3
+---
+
+By default, LiteParse returns text, geometry, and page metadata — nothing else. Everything a PDF *can* carry beyond that (embedded images, vector art, annotations, form fields, tagged-structure trees, per-glyph typography) is **opt-in**, behind its own flag.
+
+This keeps the default output shape small, stable, and cheap to produce. It also means that if you're looking for data you know is in the file and don't see it in the output, you're probably missing a flag.
+
+> Each option costs parse time and output size. Turn on only what you consume.
+
+## Quick reference
+
+| Rust / Python / CLI | Node / WASM | Adds |
+|---------------------|-------------|------|
+| `extract_images` / `--extract-images` | `extractImages` | `images[]`, `image_error_count` |
+| `extract_vector_graphics` / `--extract-vector-graphics` | `extractVectorGraphics` | `pages[].vector_graphics` |
+| `extract_annotations` / `--extract-annotations` | `extractAnnotations` | `pages[].annotations` |
+| `extract_form_fields` / `--extract-form-fields` | `extractFormFields` | `pages[].form_fields` |
+| `extract_structure_tree` / `--extract-structure-tree` | `extractStructureTree` | `pages[].structure_tree` |
+| `extract_content_bounds` / `--extract-content-bounds` | `extractContentBounds` | `pages[].content_bounds` |
+| `extract_xfa_packets` / `--extract-xfa-packets` | `extractXfaPackets` | `xfa_packets[]` |
+| `extract_text_metadata` / `--extract-text-metadata` | `extractTextMetadata` | extra keys on `text_items[]` |
+| `include_complexity` / `--complexity` | `includeComplexity` | `pages[].complexity` |
+| `emit_word_boxes` *(no CLI flag)* | `emitWordBoxes` | `TextItem.words` (bindings only) |
+
+One toggle is **on** by default: `extract_links` (`--no-links` to disable). See the [Markdown guide](/liteparse/guides/markdown/).
+
+## Enabling options
+
+<Tabs>
+<TabItem label="TypeScript" value="typescript">
+
+```typescript
+import { LiteParse } from "@llamaindex/liteparse";
+
+const parser = new LiteParse({
+ outputFormat: "json",
+ extractImages: true,
+ extractFormFields: true,
+ extractAnnotations: true,
+ extractTextMetadata: true,
+});
+
+const result = await parser.parse("form.pdf");
+```
+
+</TabItem>
+<TabItem label="Python" value="python">
+
+```python
+from liteparse import LiteParse
+
+parser = LiteParse(
+ output_format="json",
+ extract_images=True,
+ extract_form_fields=True,
+ extract_annotations=True,
+ extract_text_metadata=True,
+)
+
+result = parser.parse("form.pdf")
+```
+
+</TabItem>
+<TabItem label="Rust" value="rust">
+
+```rust
+use liteparse::{LiteParse, LiteParseConfig, OutputFormat};
+
+let config = LiteParseConfig {
+ output_format: OutputFormat::Json,
+ extract_images: true,
+ extract_form_fields: true,
+ extract_annotations: true,
+ extract_text_metadata: true,
+ ..Default::default()
+};
+
+let result = LiteParse::new(config).parse("form.pdf").await?;
+```
+
+</TabItem>
+<TabItem label="CLI" value="cli">
+
+```bash
+lit parse form.pdf --format json \
+ --extract-images \
+ --extract-form-fields \
+ --extract-annotations \
+ --extract-text-metadata
+```
+
+</TabItem>
+</Tabs>
+
+## Embedded images
+
+`extract_images` decodes embedded raster images and returns their bytes and metadata in a document-level `images` array. Pair it with `image_output_dir` to write each image to disk instead of holding it in memory.
+
+```bash
+lit parse report.pdf --format json --extract-images --image-output-dir ./images
+```
+
+```json
+{
+ "images": [
+ {
+ "id": "p1_i0",
+ "name": "image_p1_0.png",
+ "path": "./images/image_p1_0.png",
+ "page": 1,
+ "bbox": { "x": 72.0, "y": 118.5, "width": 240.0, "height": 160.0 },
+ "width": 800,
+ "height": 533,
+ "rotation": 0.0,
+ "format": "png"
+ }
+ ],
+ "image_error_count": 0
+}
+```
+
+Notes:
+
+- `image_output_dir` **requires** `extract_images` — setting it alone is a config error. `image_mode: "embed"` also implies extraction, for backwards compatibility.
+- `duplicate_of` is set when the same image appears more than once in the document; the duplicate points at the canonical entry's `id` rather than re-storing the pixels.
+- `image_error_count` counts images that failed to decode. It is omitted when zero.
+- This is separate from `image_mode`, which only controls how image *references* are written into markdown. See the [Markdown guide](/liteparse/guides/markdown/).
+
+## Vector graphics
+
+`extract_vector_graphics` reports the vector drawing operations on each page, split into filled/stroked `shapes` and straight `lines`. Useful for finding table rules, underlines, dividers, and chart geometry.
+
+```json
+{
+ "vector_graphics": {
+ "shapes": [
+ {
+ "bbox": { "x": 72.0, "y": 400.0, "width": 180.0, "height": 90.0 },
+ "stroke": true,
+ "stroke_color": "#000000",
+ "fill": false,
+ "has_curve": true
+ }
+ ],
+ "lines": [
+ {
+ "x1": 72.0, "y1": 512.0, "x2": 540.0, "y2": 512.0,
+ "stroke": true,
+ "stroke_width": 0.5,
+ "stroke_color": "#cccccc",
+ "fill": false
+ }
+ ]
+ }
+}
+```
+
+## Annotations
+
+`extract_annotations` returns PDF annotations per page — comments, highlights, and link targets.
+
+```json
+{
+ "annotations": [
+ {
+ "subtype": "Link",
+ "rect": { "x": 72.0, "y": 300.0, "width": 120.0, "height": 12.0 },
+ "uri": "https://example.com"
+ },
+ {
+ "subtype": "Highlight",
+ "contents": "check this figure",
+ "title": "Reviewer 2",
+ "created": "D:20260714093000Z",
+ "quadpoint_rects": [
+ { "x": 72.0, "y": 280.0, "width": 200.0, "height": 11.0 }
+ ]
+ }
+ ]
+}
+```
+
+Only `subtype` is always present; every other key is omitted when the annotation doesn't carry it.
+
+## Form fields
+
+`extract_form_fields` returns AcroForm widgets and their resolved values.
+
+```json
+{
+ "form_fields": [
+ {
+ "id": "f0",
+ "type": "text",
+ "page": 1,
+ "annotation_index": 0,
+ "widget_index": 0,
+ "field_flags": 0,
+ "name": "applicant_name",
+ "value": "Ada Lovelace",
+ "rect": { "x": 150.0, "y": 640.0, "width": 220.0, "height": 18.0 }
+ },
+ {
+ "id": "f1",
+ "type": "checkbox",
+ "page": 1,
+ "annotation_index": 1,
+ "widget_index": 0,
+ "field_flags": 0,
+ "name": "agree_terms",
+ "checked": true
+ }
+ ]
+}
+```
+
+> The widget type is serialized as `type` in JSON, and is `type` on the Node and Python objects. Radio groups and checkbox sets expose `control_count`/`control_index` to tie sibling widgets together, and choice fields expose `options`/`selected_options`.
+
+For **XFA**-based forms (a different, XML-based form technology), use `extract_xfa_packets` instead, which returns the raw XFA packets at document level.
+
+Related: `render_form_fields` draws filled-in field appearances into rendered rasters. It affects [screenshots](/liteparse/guides/visual-citations/) and OCR input pixels, not JSON keys.
+
+## Structure tree
+
+`extract_structure_tree` returns the tagged-PDF logical structure — the authoring-time document outline of paragraphs, headings, tables, and lists. Only present in PDFs that were actually tagged.
+
+```json
+{
+ "structure_tree": {
+ "roots": [
+ {
+ "type": "Document",
+ "children": [
+ {
+ "type": "H1",
+ "marked_content_ids": [0],
+ "actual_text": "Quarterly Report",
+ "children": []
+ },
+ {
+ "type": "P",
+ "marked_content_ids": [1, 2],
+ "children": []
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+`marked_content_ids` join back to the `mcid` field on text items (available with `extract_text_metadata`), letting you map reconstructed text to its authored role.
+
+## Text metadata
+
+`extract_text_metadata` enriches every entry in `text_items[]` with typography detail. Without it, a text item carries only `text`, `x`, `y`, `width`, `height`, `font_name`, and `font_size`.
+
+```json
+{
+ "text": "Quarterly Report",
+ "x": 72.0, "y": 118.5, "width": 180.4, "height": 14.0,
+ "rotation": 0.0,
+ "font_name": "Helvetica-Bold",
+ "font_size": 14.0,
+ "font_height": 14.2,
+ "font_ascent": 11.1,
+ "font_descent": -3.1,
+ "font_weight": 700,
+ "text_width": 180.4,
+ "font_is_buggy": false,
+ "mcid": 0,
+ "fill_color": "#111111"
+}
+```
+
+`font_weight` and `fill_color` are the practical way to detect emphasis and headings yourself when you need more control than markdown output gives you. `font_is_buggy` flags fonts whose metrics LiteParse had to estimate — treat sizes from those items with suspicion.
+
+## Content bounds
+
+`extract_content_bounds` adds a `content_bounds` rect per page: the bounding box of actual content, ignoring the page's declared media box. Use it to crop whitespace or detect pages whose content sits far from the nominal page area.
+
+```json
+{ "content_bounds": { "x": 68.0, "y": 96.0, "width": 476.0, "height": 620.0 } }
+```
+
+## Word boxes
+
+`emit_word_boxes` splits each text item into per-word sub-boxes (`TextItem.words`), for word-level bounding-box attribution.
+
+This one is **library- and bindings-only**. Word boxes are deliberately excluded from `--format json`, because on a text-heavy document they dwarf the rest of the payload. There is no CLI flag; reach for it from Node, Python, Rust, or WASM.
+
+<Tabs>
+<TabItem label="TypeScript" value="typescript">
+
+```typescript
+const parser = new LiteParse({ emitWordBoxes: true });
+const result = await parser.parse("report.pdf");
+
+for (const item of result.pages[0].textItems) {
+ for (const word of item.words ?? []) {
+ console.log(word.text, word.x, word.y, word.width, word.height);
+ }
+}
+```
+
+</TabItem>
+<TabItem label="Python" value="python">
+
+```python
+parser = LiteParse(emit_word_boxes=True)
+result = parser.parse("report.pdf")
+
+for item in result.pages[0].text_items:
+ for word in item.words:
+ print(word.text, word.x, word.y, word.width, word.height)
+```
+
+</TabItem>
+</Tabs>
+
+## Options with no CLI flag
+
+A few config options are only reachable from the library and bindings:
+
+| Option | Description |
+|--------|-------------|
+| `emit_word_boxes` | Per-word sub-boxes (see above). |
+| `crop_box` | Restrict output to a sub-region of each page. A text item is kept only if it falls entirely inside. |
+| `skip_diagonal_text` | Drop text rotated more than 2° off the nearest right angle — watermarks and diagonal stamps. |
+| `detect_screenshot_rects` | Populate `rects` on screenshot results. |
+| `render_form_fields` | Draw form-field appearances into rendered pages. |
+| `ocr_failure_fatal` | When `false`, a systemic OCR failure returns partial results instead of erroring. Defaults to `true`. |
+| `ocr_hedge_delays_ms` | Request-hedging schedule for HTTP OCR servers. No effect on built-in Tesseract. |
+
+`crop_box` takes the fraction to crop from each side. It is an object in Node and WASM, and a `(top, right, bottom, left)` tuple in Python:
+
+<Tabs>
+<TabItem label="TypeScript" value="typescript">
+
+```typescript
+// Drop the top 10% and bottom 5% of every page
+const parser = new LiteParse({
+ cropBox: { top: 0.1, right: 0.0, bottom: 0.05, left: 0.0 },
+});
+```
+
+</TabItem>
+<TabItem label="Python" value="python">
+
+```python
+# (top, right, bottom, left)
+parser = LiteParse(crop_box=(0.1, 0.0, 0.05, 0.0))
+```
+
+</TabItem>
+</Tabs>
+
+## Next steps
+
+- [Document complexity](/liteparse/guides/complexity/): Route documents before you parse them.
+- [Markdown output](/liteparse/guides/markdown/): Images, links, and header/footer handling in markdown.
+- [CLI reference](/liteparse/cli-reference/): Every flag, per command.
+- [API reference](/liteparse/api/): Full `LiteParseConfig` field list.
diff --git a/docs/src/content/docs/liteparse/guides/library-usage.mdx b/docs/src/content/docs/liteparse/guides/library-usage.mdx
index edfb594..e4c17a2 100644
--- a/docs/src/content/docs/liteparse/guides/library-usage.mdx
+++ b/docs/src/content/docs/liteparse/guides/library-usage.mdx
@@ -83,6 +83,8 @@ const parser = new LiteParse({
});
```
+Images, vector graphics, annotations, form fields, structure trees, and per-item typography are all off by default and enabled with their own options. See [Extraction options](/liteparse/guides/extraction/).
+
### Buffer / Uint8Array input
You can pass raw bytes directly instead of a file path:
@@ -108,7 +110,7 @@ Generate page images as buffers — useful for sending to LLMs or saving to disk
```typescript
const parser = new LiteParse();
-const screenshots = parser.screenshot("document.pdf");
+const screenshots = await parser.screenshot("document.pdf");
for (const shot of screenshots) {
console.log(`Page ${shot.pageNum}: ${shot.width}x${shot.height}`);
@@ -116,7 +118,7 @@ for (const shot of screenshots) {
}
// Screenshot specific pages
-const shots = parser.screenshot("document.pdf", [1, 2, 3]);
+const shots = await parser.screenshot("document.pdf", [1, 2, 3]);
```
### Environment variables
@@ -168,6 +170,8 @@ parser = LiteParse(
result = parser.parse("document.pdf")
```
+All options are keyword-only. Images, vector graphics, annotations, form fields, structure trees, and per-item typography are off by default and enabled with their own options — see [Extraction options](/liteparse/guides/extraction/).
+
### Markdown output
Render the document to Markdown — headings, tables, lists, images, and links. The rendered Markdown comes back on `result.text`:
@@ -274,6 +278,8 @@ let config = LiteParseConfig {
let parser = LiteParse::new(config);
```
+`LiteParseConfig` is a plain struct, so `..Default::default()` is the idiomatic way to set only what you need. Images, vector graphics, annotations, form fields, structure trees, and per-item typography are off by default — see [Extraction options](/liteparse/guides/extraction/).
+
### Markdown output
Render the document to Markdown — headings, tables, lists, images, and links. The rendered Markdown comes back on `result.text`:
diff --git a/docs/src/content/docs/liteparse/guides/markdown.md b/docs/src/content/docs/liteparse/guides/markdown.mdx
similarity index 74%
rename from docs/src/content/docs/liteparse/guides/markdown.md
rename to docs/src/content/docs/liteparse/guides/markdown.mdx
index e5f889a..027e7de 100644
--- a/docs/src/content/docs/liteparse/guides/markdown.md
+++ b/docs/src/content/docs/liteparse/guides/markdown.mdx
@@ -31,16 +31,24 @@ By default, raster images are emitted as Markdown placeholders
|------|----------|
| `placeholder` (default) | Emit `![](image_pN_K.png)` references in reading order |
| `off` | Strip images entirely |
-| `embed` | Write each image's PNG bytes to `--image-output-dir` and reference them |
+| `embed` | Emit the same references, and extract the image bytes |
+
+`--image-mode` controls only how image *references* appear in the markdown. It does
+not, on its own, decode any pixels. To actually get image bytes, use
+`--extract-images` (see [Extraction options](/liteparse/guides/extraction/)):
```bash
# Strip images
lit parse document.pdf --format markdown --image-mode off
# Extract embedded images to disk and reference them from the markdown
-lit parse document.pdf --format markdown --image-mode embed --image-output-dir ./images
+lit parse document.pdf --format markdown --extract-images --image-output-dir ./images
```
+`--image-output-dir` requires `--extract-images`. For backwards compatibility
+`--image-mode embed` also turns extraction on, so the older
+`--image-mode embed --image-output-dir ./images` form still works.
+
### Links
Hyperlink annotations are rendered as `[text](url)` by default. Pass
@@ -50,12 +58,22 @@ Hyperlink annotations are rendered as `[text](url)` by default. Pass
lit parse document.pdf --format markdown --no-links
```
+### Headers and footers
+
+Running headers and footers (page numbers, document titles repeated on every
+page) are stripped from markdown output by default, since they interrupt the
+prose when chunked for retrieval. Pass `--keep-headers-footers` to retain them:
+
+```bash
+lit parse document.pdf --format markdown --keep-headers-footers
+```
+
## Library
The rendered Markdown is returned on `result.text`.
<Tabs>
-<TabItem value="typescript" label="TypeScript">
+<TabItem label="TypeScript" value="typescript">
```typescript
import { LiteParse } from "@llamaindex/liteparse";
@@ -70,7 +88,7 @@ console.log(result.text); // rendered Markdown
```
</TabItem>
-<TabItem value="python" label="Python">
+<TabItem label="Python" value="python">
```python
from liteparse import LiteParse
@@ -84,7 +102,7 @@ result = parser.parse("document.pdf")
print(result.text) # rendered Markdown
```
</TabItem>
-<TabItem value="rust" label="Rust">
+<TabItem label="Rust" value="rust">
```rust
use liteparse::config::{ImageMode, LiteParseConfig, OutputFormat};
diff --git a/docs/src/content/docs/liteparse/guides/multi-format.mdx b/docs/src/content/docs/liteparse/guides/multi-format.mdx
index 4c0041a..0cfdd45 100644
--- a/docs/src/content/docs/liteparse/guides/multi-format.mdx
+++ b/docs/src/content/docs/liteparse/guides/multi-format.mdx
@@ -2,7 +2,7 @@
title: Multi-Format Support
description: Parse Word documents, spreadsheets, presentations, and images with LiteParse.
sidebar:
- order: 4
+ order: 6
---
LiteParse automatically converts non-PDF formats to PDF before parsing. This lets you use the same parsing pipeline for Office documents, images, and more.
@@ -67,8 +67,8 @@ lit batch-parse ./documents ./output --recursive
## How it works
1. LiteParse detects the file extension
-2. If it's not a PDF, it converts to PDF using the appropriate tool (LibreOffice or ImageMagick)
+2. If it's not a PDF, it converts to PDF — office documents via LibreOffice, images and SVGs natively in Rust
3. The resulting PDF is parsed normally
4. Temporary conversion files are cleaned up automatically
-If the required conversion tool isn't installed, LiteParse will return an error explaining which dependency is needed.
+Only office formats need an external tool (LibreOffice). If it isn't installed, LiteParse returns an error explaining which dependency is needed.
diff --git a/docs/src/content/docs/liteparse/guides/ocr.md b/docs/src/content/docs/liteparse/guides/ocr.md
index 53d6045..770c17d 100644
--- a/docs/src/content/docs/liteparse/guides/ocr.md
+++ b/docs/src/content/docs/liteparse/guides/ocr.md
@@ -2,7 +2,7 @@
title: OCR Configuration
description: Configure OCR in LiteParse — built-in Tesseract, or bring your own via HTTP servers.
sidebar:
- order: 3
+ order: 5
---
LiteParse uses OCR selectively — only on embedded images or pages where native text extraction didn't find text. This keeps parsing fast while still capturing text from scanned pages and embedded images.
@@ -100,6 +100,19 @@ python server.py
lit parse document.pdf --ocr-server-url http://localhost:8828/ocr
```
+### Authenticated servers
+
+Pass extra HTTP headers on every OCR request with `--ocr-server-header`, repeating the flag for each header:
+
+```bash
+lit parse document.pdf \
+ --ocr-server-url https://ocr.internal/ocr \
+ --ocr-server-header "Authorization: Bearer $TOKEN" \
+ --ocr-server-header "X-Tenant: acme"
+```
+
+In the libraries this is `ocr_server_headers` / `ocrServerHeaders`, taking a map of header name to value. It has no effect unless an OCR server URL is set.
+
### Parallel OCR workers
LiteParse OCRs multiple pages in parallel. By default, it uses one fewer worker than your CPU core count. Override this with:
@@ -126,6 +139,8 @@ Content-Type: multipart/form-data
| `file` | binary | Yes | Image file (PNG, JPG, etc.) |
| `language` | string | No | ISO 639-1 language code (default: `en`) |
+> **Watch the language code.** LiteParse forwards whatever `--ocr-language` is set to, which defaults to the Tesseract-style ISO 639-3 code `eng` — not `en`. Your server should accept both. The bundled EasyOCR and PaddleOCR servers do this by mapping `eng` → `en` before dispatch; do the same in a custom server, or pass `--ocr-language en` explicitly.
+
**Response format:**
```json
@@ -133,7 +148,7 @@ Content-Type: multipart/form-data
"results": [
{
"text": "recognized text",
- "bbox": [x1, y1, x2, y2],
+ "bbox": [12, 40, 220, 62],
"confidence": 0.95
}
]
@@ -152,12 +167,12 @@ Each result contains:
```bash
# Quick test with curl
-curl -X POST http://localhost:8080/ocr \
+curl -X POST http://localhost:8828/ocr \
-F "language=en" | jq .
# Use with LiteParse
-lit parse document.pdf --ocr-server-url http://localhost:8080/ocr
+lit parse document.pdf --ocr-server-url http://localhost:8828/ocr
```
### Common Gotchas
diff --git a/docs/src/content/docs/liteparse/guides/parsing-urls.md b/docs/src/content/docs/liteparse/guides/parsing-urls.md
index 14a2f8c..e7ef5c0 100644
--- a/docs/src/content/docs/liteparse/guides/parsing-urls.md
+++ b/docs/src/content/docs/liteparse/guides/parsing-urls.md
@@ -2,7 +2,7 @@
title: Parsing URLs
description: Parse remote documents by reading URLs.
sidebar:
- order: 6
+ order: 8
---
To parse remote files, LiteParse supports both CLI and library usage for reading bytes and streams. The CLI can download them with any tool you like and pipe the bytes to `lit parse` using `-` as the file argument, while the libraries can fetch the bytes directly and pass them to the parser.
diff --git a/docs/src/content/docs/liteparse/guides/server-usage.md b/docs/src/content/docs/liteparse/guides/server-usage.md
index ba97215..3a64bf5 100644
--- a/docs/src/content/docs/liteparse/guides/server-usage.md
+++ b/docs/src/content/docs/liteparse/guides/server-usage.md
@@ -2,7 +2,7 @@
title: Server Usage
description: Run LiteParse as an HTTP service with liteparse-server.
sidebar:
- order: 8
+ order: 10
---
[`liteparse-server`](https://github.com/run-llama/liteparse-server) is an Express server that exposes [`@llamaindex/liteparse`](https://www.npmjs.com/package/@llamaindex/liteparse) as an HTTP parsing backend. It lets you run LiteParse as a standalone service, which is useful when your application isn't Node.js, when you want to share one parsing instance across multiple clients, or when you need a parsing endpoint behind your own infrastructure.
diff --git a/docs/src/content/docs/liteparse/guides/visual-citations.mdx b/docs/src/content/docs/liteparse/guides/visual-citations.mdx
index 506dff7..a07d69e 100644
--- a/docs/src/content/docs/liteparse/guides/visual-citations.mdx
+++ b/docs/src/content/docs/liteparse/guides/visual-citations.mdx
@@ -2,7 +2,7 @@
title: Visual Citations with Bounding Boxes
description: Use bounding boxes and screenshots to show exactly where information was found in a document.
sidebar:
- order: 5
+ order: 7
---
When building agents or RAG workflows, it is often not enough to parse text and call it done. Frequently, users and applications will require you to show _where_ that text came from.
@@ -11,25 +11,38 @@ LiteParse gives you spatial coordinates for every text item, plus page screensho
## How bounding boxes work
-When you parse a document with JSON output, each page includes **`textItems`** — every extracted text element with its position (`x`, `y`, `width`, `height`) and content.
+When you parse a document with JSON output, each page includes a list of text items — every extracted text element with its position (`x`, `y`, `width`, `height`) and content.
+
+```bash
+lit parse document.pdf --format json
+```
```json
-$ lit parse document.pdf --format json
{
- "pages": [{
- "page": 1,
- "width": 612,
- "height": 792,
- "text": "...",
- "textItems": [
- { "text": "Revenue grew 15%", "x": 72, "y": 200, "width": 150, "height": 12, ... }
- ],
- }]
+ "pages": [
+ {
+ "page": 1,
+ "width": 612,
+ "height": 792,
+ "text": "Revenue grew 15% ...",
+ "text_items": [
+ {
+ "text": "Revenue grew 15%",
+ "x": 72,
+ "y": 200,
+ "width": 150,
+ "height": 12
+ }
+ ]
+ }
+ ]
}
```
Coordinates are in **PDF points** (1 point = 1/72 inch). Origin is the top-left corner of the page, with X increasing right and Y increasing down.
+> JSON output is snake_case (`text_items`, `page`). The Node bindings use camelCase (`textItems`, `pageNum`) and Python uses snake_case (`text_items`, `page_num`). The examples below use each language's own naming.
+
## Library usage
The library lets you parse for bboxes and generate screenshots in a single script. For example, searching for "0°C to 70°C" and showing where it appears:
@@ -112,9 +125,9 @@ async function main() {
const query = "0°C to 70°C";
const hitsByPage = new Map<number, Array<{ x: number; y: number; width: number; height: number }>>();
- for (const page of result.json?.pages || []) {
+ for (const page of result.pages) {
const matches = searchItems(page.textItems, { phrase: query });
- if (matches.length) hitsByPage.set(page.page, matches);
+ if (matches.length) hitsByPage.set(page.pageNum, matches);
}
// Draw all highlights per page into a single image
diff --git a/docs/src/content/docs/liteparse/index.md b/docs/src/content/docs/liteparse/index.md
index a466481..4047bfa 100644
--- a/docs/src/content/docs/liteparse/index.md
+++ b/docs/src/content/docs/liteparse/index.md
@@ -19,12 +19,16 @@ LiteParse is designed specifically for use cases that require fast, accurate tex
- **OCR scanned documents** using built-in Tesseract or plug in your own OCR server
- **Parse Office files and images** with support for DOCX, XLSX, PPTX, PNG, JPG, and more via automatic conversion
- **Screenshot PDF pages** as high-quality images for LLM-based workflows
+- **Pull structured PDF data** — embedded images, vector graphics, annotations, AcroForm fields, and tagged-structure trees
+- **Score document complexity** before you parse, so you can route scanned or multi-column documents to the right pipeline
- **Use from Node.js/TypeScript, Python, Rust, or the browser (WASM)** — whatever fits your stack
## Get started
- [Getting started](/liteparse/getting_started/): Install LiteParse and parse your first document.
- [Markdown output](/liteparse/guides/markdown/): Render documents to clean, structured Markdown.
+- [Extraction options](/liteparse/guides/extraction/): Opt in to images, form fields, annotations, and more.
+- [Document complexity](/liteparse/guides/complexity/): Detect scanned, multi-column, and table-heavy pages up front.
- [Library usage](/liteparse/guides/library-usage/): Use LiteParse from TypeScript or Python code.
- [Browser usage (WASM)](/liteparse/guides/browser-usage/): Run LiteParse in the browser with zero server dependencies.
- [CLI reference](/liteparse/cli-reference/): Complete command and option reference.
diff --git a/packages/python/liteparse/parser.py b/packages/python/liteparse/parser.py
index 54849d7..95a361a 100644
--- a/packages/python/liteparse/parser.py
+++ b/packages/python/liteparse/parser.py
@@ -66,7 +66,7 @@ def _convert_structure_element(element: Any) -> StructureTreeElement:
elif attribute.string_value is not None:
attributes[attribute.name] = attribute.string_value
return StructureTreeElement(
- element_type=element.element_type,
+ type=element.element_type,
id=element.id,
actual_text=element.actual_text,
alt_text=element.alt_text,
@@ -252,7 +252,7 @@ def _convert_native_result(native_result: Any) -> ParseResult:
[
FormField(
id=form.id,
- field_type=form.field_type,
+ type=form.field_type,
page=form.page,
annotation_index=form.annotation_index,
widget_index=form.widget_index,
diff --git a/packages/python/liteparse/types.py b/packages/python/liteparse/types.py
index 3ffad30..4861eeb 100644
--- a/packages/python/liteparse/types.py
+++ b/packages/python/liteparse/types.py
@@ -76,7 +76,9 @@ class DocumentAnnotation:
class FormField:
"""One AcroForm widget and its resolved field metadata."""
id: str
- field_type: str
+ #: Widget type, e.g. ``"text"``, ``"checkbox"``, ``"combobox"``. Named
+ #: ``type`` to match the ``type`` key in JSON output and the Node bindings.
+ type: str
page: int
annotation_index: int
widget_index: int
@@ -93,6 +95,11 @@ class FormField:
options: List[str] = field(default_factory=list)
selected_options: List[str] = field(default_factory=list)
+ @property
+ def field_type(self) -> str:
+ """Deprecated alias for :attr:`type`."""
+ return self.type
+
StructureAttributeValue = Union[bool, float, str]
@@ -100,7 +107,9 @@ StructureAttributeValue = Union[bool, float, str]
@dataclass
class StructureTreeElement:
"""One element in a tagged-PDF logical structure tree."""
- element_type: str
+ #: Structure tag, e.g. ``"P"``, ``"Table"``, ``"H1"``. Named ``type`` to
+ #: match the ``type`` key in JSON output and the Node bindings.
+ type: str
id: Optional[str] = None
actual_text: Optional[str] = None
alt_text: Optional[str] = None
@@ -110,6 +119,11 @@ class StructureTreeElement:
children: List[StructureTreeElement] = field(default_factory=list)
annotations: List[DocumentAnnotation] = field(default_factory=list)
+ @property
+ def element_type(self) -> str:
+ """Deprecated alias for :attr:`type`."""
+ return self.type
+
@dataclass
class StructureTree: