liteparse Documentation

Technical Documentation: run-llama/liteparse

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

LiteParse

|

|

|

|

|

|
Docs

English | 简体中文

Looking for LiteParse V1? Follow this link to the old code

LiteParse is a standalone OSS PDF parsing tool focused exclusively on fast and light parsing. It provides high-quality spatial text parsing with bounding boxes, without proprietary LLM features or cloud dependencies. Everything runs locally on your machine.

Hitting the limits of local parsing?
For complex documents (dense tables, multi-column layouts, charts, handwritten text, or
scanned PDFs), you'll get significantly better results with LlamaParse,
our cloud-based document parser built for production document pipelines. LlamaParse handles the
hard stuff so your models see clean, structured data and markdown.

Sign up for LlamaParse free

Overview Copy Chapter

• Fast Text Parsing: Spatial text parsing using PDFium, ~2-5ms per page
• Flexible OCR System:
  • Built-in: Tesseract (zero setup, bundled with the library)
  • HTTP Servers: Plug in any OCR server (EasyOCR, PaddleOCR, custom)
  • Standard API: Simple, well-defined OCR API specification
• Complexity Detection: Cheaply check whether a document needs OCR or heavier parsing — route, reject, or estimate cost before a full parse
• Screenshot Generation: Generate high-quality page screenshots for LLM agents
• Multiple Output Formats: Markdown, JSON, and Text
• Markdown Output: Structured Markdown with headings, tables, lists, images, and links — great for feeding LLMs and RAG pipelines
• Bounding Boxes: Precise text positioning information
• Multi-language: Use from Rust, Node.js/TypeScript, Python, or the browser (WASM)
• Worker Pool Mode (Python & Node.js): Parse in persistent worker processes for true parallelism (PDFium otherwise serializes concurrent parses) and hard per-parse timeouts — rogue documents are killed, identified by name, and never stall the pipeline
• Multi-platform: Linux, macOS (Intel/ARM), Windows

/* Detailed source-code truncated for AI context efficiency. */

Benchmarks Copy Chapter

LiteParse is measured on multiple public Doc→Markdown benchmarks. All numbers below were produced on
this machine from one command (see Reproducing), with every tool at
its latest release as of 2026-09-09. LiteParse and the "model-free" competitors use no ML model at
all (no LLM, no layout model, no GPU). All tested methods have permissive licenses and can be
run locally with minimal dependencies.

ParseBench

Rule-based scoring, no LLM judge. Each column is ParseBench's canonical per-category metric
(Tables = GriTS/TRM composite; the others are rule pass-rates). Overall is the mean of the five,
as on the ParseBench leaderboard.

Notes:

• Visual Grounding scores layout blocks with bounding boxes (lit parse --extract-blocks).
• Charts is near zero for every tool here — none reconstruct chart data.

opendataloader-bench

NID = reading-order similarity, TEDS = table structure, MHS = heading hierarchy. Overall is the
harness's own mean.

Notes:

• nutrient has no runnable parser in this harness (commercial)
• The corpus is native-text PDFs, so OCR gains come from embedded figures and a handful of
  scanned pages.

olmOCR-bench

Score = average of per-category pass rates. The two math categories require LaTeX output and
are 0% for every tool here; they still count in the average.

Notes:

• headers_footers expects letterhead and footer text to be absent. OCR recovers that text
  from logo and address images on single-page documents, where the repeated-header filter cannot
  fire, so the OCR rows score lower there by design. We chose not to drop text by page position.
  pdf-inspector 1.19 refuses scanned and image-based pages outright (192 of the 1,403), which is
  why it tops this category while scoring nothing on those pages elsewhere.
• old_scans is largely cursive handwriting; Tesseract cannot read it, PaddleOCR partially can.

How the runs are configured

• Same scorer for every tool. Each benchmark's own evaluator, unmodified. The ground truth in
  all three corpora is plain text, so every tool including LiteParse runs with hyperlink syntax
  off (--no-links); everything else is the default lit parse --format markdown.
• OCR modes. No OCR is --no-ocr. Tesseract is the built-in engine with no setup.
  PaddleOCR is the PP-OCRv5 mobile detector and English recognizer served over the
  OCR HTTP API by ocr/rapidocr, which runs the PaddleOCR
  models on ONNX Runtime — the same models as ocr/paddleocr, just 20–40× faster
  per page on CPU-only machines.
• Competitors are the free converters we could run locally, each at its latest release on
  2026-09-09: markitdown 0.1.7, opendataloader-pdf 2.5.7 (its non-hybrid mode),
  pdf-inspector 1.19.0. Each benchmark's own runner for the tool is used as-is. Numbers from public
  leaderboards or LLM-assisted modes are not mixed in.
• Machine: Apple M2 Max, 12 cores, 32 GB. LiteParse rows: v2.14.4 (2026-09-09).

Reproducing the benchmarks Copy Section

./run_benchmarks.sh --liteparse-only                # all three benches, no OCR
./run_benchmarks.sh --liteparse-only --ocr=tesseract
( cd ocr/rapidocr && uv run server.py ) &           # then:
./run_benchmarks.sh --liteparse-only --ocr=paddle
./run_benchmarks.sh --competitors-only              # re-run the free competitors only
./run_benchmarks.sh                                 # everything

Results and a SUMMARY.md land in bench_results/latest/.

Installation Copy Chapter

Install via your preferred package manager. All versions (except WASM) ship with the same lit CLI.

Agent Skill Copy Section

You can use liteparse as an agent skill, downloading it with the skills CLI tool:

npx skills add run-llama/llamaparse-agent-skills --skill liteparse

Or copy-pasting the SKILL.md file to your own skills setup.

See the Agent Skill guide for requirements and usage patterns.

CLI Usage Copy Chapter

The CLI is the same across all installations (npm, pip, cargo install).

Parse Files Copy Section

# Basic parsing
lit parse document.pdf

# Parse to Markdown — headings, tables, lists, images, links
lit parse document.pdf --format markdown -o output.md

# Parse with specific format
lit parse document.pdf --format json -o output.json

# Parse specific pages
lit parse document.pdf --target-pages "1-5,10,15-20"

# Parse without OCR
lit parse document.pdf --no-ocr

# Include page-scoped vector path data in JSON
lit parse document.pdf --format json --extract-vector-graphics

# Include rich per-item PDF text metadata
lit parse document.pdf --format json --extract-text-metadata

# Include page annotations in structured JSON
lit parse document.pdf --format json --extract-annotations

# Include AcroForm widget fields and values (repairs orphaned widgets in memory)
lit parse document.pdf --format json --extract-form-fields

# Parse a remote PDF
curl -sL https://example.com/report.pdf | lit parse -

Markdown Output Copy Section

LiteParse can render documents directly to Markdown. This means reconstructing headings,
tables, lists, images, and links from the spatial layout. This is ideal for
feeding documents to LLMs and RAG pipelines. This mode is purely heuristics and rule-based,
so complex documents may not render perfectly, but it will be fast.

# Render to Markdown
lit parse document.pdf --format markdown -o output.md

# Strip images instead of emitting placeholders
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 --extract-images --image-output-dir ./images

# Extract image bytes and metadata without changing Markdown image handling
lit parse document.pdf --format json --extract-images

# Emit link text as plain text (no [text](url) syntax)
lit parse document.pdf --format markdown --no-links

# Include tagged-PDF logical structure in JSON
lit parse document.pdf --format json --extract-structure-tree

# Include the classified layout blocks (with bounding boxes) in JSON
lit parse document.pdf --format json --extract-blocks

Image handling is controlled by --image-mode:

--extract-images is the only option that enables embedded-image extraction.
--image-output-dir requires it and writes the extracted bytes to disk. JSON output
contains each image's name, path, page bbox, intrinsic pixel dimensions, rotation,
format, and duplicate relationship; pixel bytes are never embedded in JSON. Identical
image resources reuse the same output file.

Library callers can opt in with extract_images: true (Rust), extractImages: true
(Node/WASM), or extract_images=True (Python). It defaults to false. Markdown image
mode controls presentation only; placeholder refs are still discovered without bytes.

Markdown reconstruction quality varies with document complexity. For the
hardest documents (dense tables, multi-column layouts, scans),
LlamaParse
remains the most accurate option.

Vector Graphics Copy Section

Vector path output is opt-in because path-heavy PDFs can produce large payloads.
Enable it with --extract-vector-graphics, Rust/Python
extract_vector_graphics = true, or JavaScript/WASM
extractVectorGraphics: true. Each page then includes vector_graphics
(vectorGraphics in JavaScript) with:

• shapes: path bounding box, stroke/fill paint state and ARGB colors, and
  whether the path contains a Bezier curve.
• lines: compatible horizontal/vertical segments merged using stroke width
  and paint colors, with top-left 72-DPI viewport coordinates.

The representation follows LlamaParse PDFium path extraction; LiteParse calls
the shape rectangle bbox rather than PDFium's coords, and uses width /
height rather than w / h. The field is absent (or None/undefined) by
default. Diagonal and curved segments are represented by their parent shape but
are not emitted as lines.

Tagged PDF structure tree Copy Section

Enable --extract-structure-tree (Rust/Python extract_structure_tree,
JavaScript/WASM extractStructureTree) to add a page-scoped structure_tree.
It preserves every root and recursively exposes element type, ID, actual/alternate
text, title, typed scalar attributes, marked-content IDs, children, and referenced
link annotations. The field is absent by default; enabled untagged pages contain
roots: [].

Layout blocks Copy Section

The Markdown renderer works by classifying each page into blocks — headings,
paragraphs, list items, tables, code, rules, figures — and then rendering them.
Enable --extract-blocks (Rust/Python extract_blocks, JavaScript/WASM
extractBlocks) to get that decomposition as data instead of only as rendered
text, with the coordinates the classifier used.

Each page gains a blocks array in reading order — the same order, and the same
blocks, the Markdown output is built from. Every block carries:

• kind: one of heading, paragraph, list_item, code, table,
  grid_fallback, rule, figure.
• bbox: the region it occupies, in the same top-left 72-DPI viewport space as
  text_items. This is the union of every source line that fed the block, so a
  wrapped heading or a multi-line paragraph reports its whole band.
• Kind-specific fields, omitted when they don't apply: text and level for
  headings; ordered / marker for list items; lines and lang for code;
  header and rows for tables; id / format for figures.

Table cells are objects, not bare strings — each has text and its own bbox,
so a cell can be mapped back to the region of the page it was read from. For
ruled tables that box is the drawn grid cell; for borderless tables it is the
extent of the spans the cell was built from. Cells that exist only to square off
a ragged grid carry no bbox, since they have no ink behind them.

{
  "kind": "table",
  "bbox": { "x": 72.0, "y": 310.5, "width": 468.0, "height": 96.0 },
  "header": [
    { "text": "Territory Code", "bbox": { "x": 72.0, "y": 310.5, "width": 120.0, "height": 24.0 } },
    { "text": "Factor",         "bbox": { "x": 192.0, "y": 310.5, "width": 96.0, "height": 24.0 } }
  ],
  "rows": [
    [
      { "text": "001", "bbox": { "x": 72.0, "y": 334.5, "width": 120.0, "height": 24.0 } },
      { "text": "1.25", "bbox": { "x": 192.0, "y": 334.5, "width": 96.0, "height": 24.0 } }
    ]
  ]
}

Document metadata, content bounds, and XFA packets Copy Section

Parse results (Rust/Node/Python APIs) carry the document's /Info creator
and producer entries when present; these are API-only and never appear in
CLI JSON output. Enable extract_document_metadata (JavaScript/WASM
extractDocumentMetadata) to add doc_meta/docMeta, a provenance object
with the /Info creation/modification dates, PDF version and encryption
permissions, signature state, incremental-save markers, trailer ID comparison,
the document catalog's XMP packet (capped at 64 KiB, with xmp_truncated
when it was cut), and source file size. It is off by default because it
streams the whole source file once; it is absent for inputs converted from a
non-PDF format, where the facts would describe the intermediate PDF rather
than your file. xmp needs a structural parse of the document, so it is
skipped (left absent) for sources over 16 MiB and in WASM builds — the other
fields are unaffected.
Enable --extract-content-bounds (Rust/Python
extract_content_bounds, JavaScript/WASM extractContentBounds) to add a
per-page content_bounds: the union bbox of the page's top-level content
objects in viewport coords (absent for empty pages). Enable
--extract-xfa-packets (Rust/Python extract_xfa_packets, JavaScript/WASM
extractXfaPackets) to add xfa_packets with each raw XFA packet's index,
name, byte length, and XML content; non-XFA documents yield an empty list.
All of these are off by default, so default JSON output is unchanged.

Screenshot raster signals Copy Section

Screenshots draw AcroForm field appearances (filled values, checkbox states)
on top of the page raster, so form data is visible in the render and to OCR.
Each screenshot result reports is_solid_fill (blank page after render), and
with detect_screenshot_rects (Node detectScreenshotRects) also rects:
solid same-color rectangles and lines found in the raster in viewport coords,
which covers scanned/flattened pages that carry no vector paths.

Check Complexity Copy Section

Before committing to a full parse, check whether a document actually needs OCR or
heavier processing. This is a cheap, text-layer-only pass — useful for routing
documents to different pipelines, rejecting ones you can't handle, or estimating cost.

# Print the complexity verdict and per-page JSON
lit is-complex document.pdf

# Use as a shell predicate — only parse with --no-ocr when the document is simple
lit is-complex document.pdf --quiet && lit parse document.pdf --no-ocr

# List the pages that need OCR
lit is-complex document.pdf --compact | jq '[.[] | select(.needs_ocr) | .page_number]'

It always prints per-page JSON to stdout, a human-readable verdict to stderr, and
exits non-zero when any page needs OCR. Each page carries a needs_ocr verdict and a
list of reasons (scanned, no-text, sparse-text, embedded-images, garbled,
vector-text, annotation-text).

Batch Parsing Copy Section

Parse an entire directory of documents:

lit batch-parse ./input-directory ./output-directory

Generate Screenshots Copy Section

Screenshots are essential for LLM agents to extract visual information that text alone cannot capture.

# Screenshot all pages
lit screenshot document.pdf -o ./screenshots

# Screenshot specific pages
lit screenshot document.pdf --target-pages "1,3,5" -o ./screenshots

# Custom DPI
lit screenshot document.pdf --dpi 300 -o ./screenshots

CLI Reference Copy Section

Parse Command

/* Detailed source-code truncated for AI context efficiency. */

Batch Parse Command

lit batch-parse [OPTIONS] <input-dir> <output-dir>

Options:
      --format <format>        Output format: json|text|markdown [default: text]
      --no-ocr                 Disable OCR
      --ocr-language <lang>    OCR language [default: eng]
      --ocr-server-url <url>   HTTP OCR server URL
      --tessdata-path <path>   Path to tessdata directory
      --max-pages <n>          Max pages per file [default: 1000]
      --dpi <dpi>              Rendering DPI [default: 150]
      --recursive              Recursively search input directory
      --extension <ext>        Only process files with this extension (e.g., ".pdf")
      --password <password>    Password for encrypted documents
      --num-workers <n>        Concurrent OCR workers
  -q, --quiet                  Suppress progress output
  -h, --help                   Print help

Screenshot Command

lit screenshot [OPTIONS] <file>

Options:
  -o, --output-dir <dir>       Output directory [default: ./screenshots]
      --target-pages <pages>   Pages to screenshot (e.g., "1,3,5" or "1-5")
      --dpi <dpi>              Rendering DPI [default: 150]
      --password <password>    Password for encrypted documents
  -q, --quiet                  Suppress progress output
  -h, --help                   Print help

Is-Complex Command

lit is-complex [OPTIONS] <file>

Options:
      --compact                Emit dense, whitespace-free JSON instead of pretty-printed
      --max-pages <n>          Max pages to check [default: 1000]
      --target-pages <pages>   Pages to check (e.g., "1-5,10,15-20")
      --password <password>    Password for encrypted documents
  -q, --quiet                  Suppress the stderr verdict
  -h, --help                   Print help

Prints per-page JSON to stdout and a COMPLEX/SIMPLE verdict to stderr; exits non-zero
when any page needs OCR, so it composes as a shell predicate.

OCR Setup Copy Chapter

Default: Tesseract Copy Section

Tesseract is bundled and works out of the box:

lit parse document.pdf                    # OCR enabled by default
lit parse document.pdf --ocr-language fra # Specify language
lit parse document.pdf --no-ocr           # Disable OCR

For offline or air-gapped environments, set TESSDATA_PREFIX to a directory containing pre-downloaded .traineddata files:

export TESSDATA_PREFIX=/path/to/tessdata
lit parse document.pdf --ocr-language eng

Or pass the path directly:

lit parse document.pdf --tessdata-path /path/to/tessdata

Optional: HTTP OCR Servers Copy Section

For higher accuracy or better performance, you can use an HTTP OCR server. We provide ready-to-use example wrappers for popular OCR engines:

• EasyOCR
• PaddleOCR

You can integrate any OCR service by implementing the simple LiteParse OCR API specification (see OCR_API_SPEC.md).

The API requires:

• POST /ocr endpoint
• Accepts file and language parameters
• Returns JSON: { results: [{ text, bbox: [x1,y1,x2,y2], confidence }] }

Multi-Format Input Support Copy Chapter

LiteParse supports automatic conversion of various document formats to PDF before parsing.

Supported Input Formats Copy Section

Office Documents (via LibreOffice)

• Word: .doc, .docx, .docm, .odt, .rtf, .pages
• PowerPoint: .ppt, .pptx, .pptm, .odp, .key
• Spreadsheets: .xls, .xlsx, .xlsm, .ods, .csv, .tsv, .numbers

Install LibreOffice for automatic conversion:

# macOS
brew install --cask libreoffice

# Ubuntu/Debian
apt-get install libreoffice

# Windows
choco install libreoffice-fresh

On Windows, you may need to add LibreOffice's program directory (usually C:\Program Files\LibreOffice\program) to your PATH.

Images (native support)

• Formats: .jpg, .jpeg, .png, .gif, .bmp, .tiff, .webp, .svg

![NOTE]

As of v2.8.0, imagemagick is no longer required to convert images to PDF. Conversion is natively
handled by the rust code.

Environment Variables Copy Chapter

Development Copy Chapter

The project is a Rust workspace with the core library and language-specific binding crates.

crates/
├── liteparse/          # Core library + CLI binary
├── liteparse-napi/     # Node.js bindings (napi-rs)
├── liteparse-python/   # Python bindings (PyO3)
├── liteparse-wasm/     # WASM bindings (wasm-bindgen)
├── pdfium/             # PDFium Rust wrapper
└── pdfium-sys/         # PDFium FFI bindings
packages/
├── node/               # npm package (TS wrapper + native binary)
├── python/             # PyPI package (Python wrapper + native binary)
└── wasm/               # WASM npm package

Building Copy Section

# Build the CLI
cargo build --release -p liteparse

# Build Node.js bindings
cd packages/node && npm run build

# Build Python bindings
cd packages/python && maturin develop --release

# Build WASM
cd packages/wasm && npm run build

We provide a fairly rich AGENTS.md/CLAUDE.md that we recommend using to help with development + coding agents.

License Copy Chapter

Apache 2.0

Credits Copy Chapter

Built on top of:

• PDFium - PDF rendering and text extraction
• Tesseract - OCR engine (via tesseract-rs)
• EasyOCR - HTTP OCR server (optional)
• PaddleOCR - HTTP OCR server (optional)
• napi-rs - Node.js native bindings
• PyO3 - Python native bindings
• wasm-bindgen - WebAssembly bindings

Overview (`dataset_eval_utils/README.md`) Copy Section

LiteParse Eval Utils

Utilities for generating and evaluating datasets for PDF parsing performance. Compares text extraction quality across multiple PDF parsers using LLM-based QA evaluation.

Setup Copy Chapter

Requires Python 3.12+.

# Install the package (from the dataset_eval_utils directory)
pip install -e .

You'll need an ANTHROPIC_API_KEY environment variable set for the LLM-based evaluation and dataset processing tools.

Dataset Copy Chapter

An existing dataset that was generated and evaluated using this framework can be found on huggingface.

You can download the dataset using the Hugging Face CLI:

hf download run-llama/liteparse-eval-dataset --repo-type dataset --local-dir ./liteparse-eval-dataset

CLI Tools Copy Chapter

`lp-process` — Generate Ground Truth Datasets Copy Section

Processes PDF and image files using Claude's vision capabilities to generate structured QA ground truth data.

lp-process /path/to/documents --output-dir ./ground_truth

Options:

• --output-dir — Directory to save output JSON files (default: ./output)
• --model — Claude model to use (default: claude-sonnet-4-5-20250929)
• --api-key — Anthropic API key (or set ANTHROPIC_API_KEY env var)

Each output JSON file contains document metadata and QA pairs extracted from the document pages.

`lp-evaluate` — Run QA Evaluation Copy Section

Evaluates parser text extraction quality by having an LLM answer questions from extracted text and judging correctness against ground truth answers.

lp-evaluate \
  --data-dir ./documents \
  --ground-truth-dir ./ground_truth \
  --parse-provider liteparse \
  --output ./results/run1

Options:

• --data-dir — Directory containing source PDF documents (required)
• --ground-truth-dir — Directory containing ground truth JSON files (required)
• --output — Path to save results (JSON + HTML report)
• --parse-provider — Parser to evaluate: liteparse, pymupdf, pypdf, markitdown (default: liteparse)
• --llm-provider — LLM for answering questions: anthropic (default: anthropic)

Outputs:

• <output>.json — Aggregate results with pass rates
• <output>_detailed.json — Per-document results with extracted text and individual QA results
• <output>_report.html — Interactive HTML report with PDF previews and QA breakdowns

`lp-benchmark` — Performance Benchmarking Copy Section

Measures parse latency and memory usage across providers.

lp-benchmark ./documents --providers pymupdf liteparse --warmup-runs 0

Takes a directory of PDFs (searched recursively), not a single file.

Options:

• --providers — Providers to benchmark (default: all local providers)
• --warmup-runs — Full passes over the corpus before timing starts (default: 5).
  Each warmup run parses every document, so on a large corpus this dominates
  wall time; use 0 for a quick measurement.
• --output — Path to save JSON results

Reports per-document latency plus TOTAL / AVG-per-doc / MS-per-page rows.

Parser Providers Copy Chapter

Evaluation Pipeline Copy Chapter

1. Extract text from PDF using the selected parser provider
2. Answer questions — LLM reads the extracted text and answers ground truth questions
3. Judge answers — A separate LLM judge evaluates whether predicted answers are semantically equivalent to expected answers
4. Aggregate — Pass rates are computed per-document and overall

Overview (`ocr/README.md`) Copy Section

ocr/

Example OCR server implementations that conform to the LiteParse OCR API specification.

These servers allow you to use alternative OCR engines instead of the built-in Tesseract.js.

Why Use an External OCR Server? Copy Chapter

Recommendations:

• Quick start: Use built-in Tesseract (no setup)
• Asian languages: Use PaddleOCR (best CJK support)
• Multilingual / broad scripts: Use Surya (strong multilingual accuracy)
• General use: EasyOCR (good balance)

Available Servers Copy Chapter

[easyocr/](./easyocr/) Copy Section

Flask server wrapping EasyOCR library.

• Port: 8828
• Good general-purpose OCR
• 80+ languages

[paddleocr/](./paddleocr/) Copy Section

Flask server wrapping PaddleOCR library.

• Port: 8829
• Excellent for Chinese, Japanese, Korean
• 2-3x faster than EasyOCR

[suryaocr/](./suryaocr/) Copy Section

FastAPI server wrapping Surya OCR 2.

• Port: 8830
• Multilingual foundation model (90+ languages)
• Block-level output; GPU recommended

Quick Start Copy Chapter

# Start EasyOCR server
cd ocr/easyocr
uv run server.py

# OR start PaddleOCR server
cd ocr/paddleocr
uv run server.py

# OR start Surya OCR server
cd ocr/suryaocr
uv run server.py

Then use with LiteParse:

# CLI
lit parse document.pdf --ocr-server-url http://localhost:8828/ocr

# Code
const parser = new LiteParse({
  ocrServerUrl: 'http://localhost:8828/ocr',
  ocrLanguage: 'en',
});

API Specification Copy Chapter

All servers implement the same API (defined in OCR_API_SPEC.md):

Endpoint: POST /ocr

Request:

• Content-Type: multipart/form-data
• Fields:
  • file - Image file
  • language - Language code (e.g., 'en', 'zh', 'ja')

Response:

{
  "results": [
    {
      "text": "recognized text",
      "bbox": [x1, y1, x2, y2],
      "confidence": 0.95
    }
  ]
}

Creating a Custom OCR Server Copy Chapter

To implement your own OCR server:

1. Create a Flask/FastAPI/Express server

2. Accept POST /ocr with multipart form data

3. Return JSON with results array containing:

   • text - Recognized text string
   • bbox - Bounding box as [x1, y1, x2, y2]
   • confidence - Confidence score (0-1)

4. (Optional) Implement GET /health endpoint

See the existing servers as reference implementations.

Language Codes Copy Chapter

Most servers accept ISO 639-1 codes (e.g., 'en', 'zh', 'ja') and map them internally:

Overview (`crates/liteparse/README.md`) Copy Section

LiteParse

Rust library and CLI for fast, lightweight PDF and document parsing with spatial text extraction. Runs entirely locally with zero cloud dependencies.

LiteParse is also available for Node.js/TypeScript, Python, and the browser (WASM). See the project README for all options.

Installation Copy Chapter

Add to your Cargo.toml:

[dependencies]
liteparse = "2"

Or install the CLI:

cargo install liteparse

Quick Start Copy Chapter

use liteparse::{LiteParse, LiteParseConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let parser = LiteParse::new(LiteParseConfig::default());
    let result = parser.parse("document.pdf").await?;

    println!("{}", result.text);

    for page in &result.pages {
        println!("Page {}: {} text items", page.page_num, page.text_items.len());
    }

    Ok(())
}

Configuration Copy Chapter

use liteparse::{LiteParse, LiteParseConfig, OutputFormat};

let config = LiteParseConfig {
    ocr_enabled: true,                    // Enable OCR (default: true)
    ocr_language: "eng".to_string(),      // Tesseract language code
    ocr_server_url: None,                 // HTTP OCR server URL (optional)
    tessdata_path: None,                  // Path to tessdata directory (optional)
    max_pages: 1000,                      // Max pages to parse
    target_pages: Some("1-5,10".into()),  // Specific pages (optional)
    dpi: 150.0,                           // Rendering DPI
    output_format: OutputFormat::Json,    // Json | Text | Markdown
    extract_annotations: false,           // Include page annotations in output
    extract_structure_tree: false,        // Include tagged-PDF logical structure
    preserve_very_small_text: false,      // Keep tiny text
    extract_text_metadata: false,         // Opt in to rich PDF text metadata
    password: None,                       // Password for protected documents
    quiet: false,                         // Suppress progress output
    ..Default::default()
};

let parser = LiteParse::new(config);

Set extract_annotations: true to populate ParsedPage::annotations with
annotation subtype, contents, author/title, PDF date strings, viewport-space
rectangle and quadpoint rectangles, and external link URI. It is independent
of extract_links, which controls Markdown link rendering. The field is
None when extraction is disabled.

Set extract_structure_tree: true to populate ParsedPage::structure_tree with
the complete tagged-PDF hierarchy: all roots, element type/ID, actual and alternate
text, title, typed scalar attributes, MCIDs, recursive children, and referenced link
annotations. Disabled pages use None; enabled untagged pages have no roots.

Markdown Output Copy Chapter

LiteParse can render documents directly to Markdown, including headings, tables, lists,
images, and links reconstructed from the spatial layout. Set
output_format: OutputFormat::Markdown; the rendered Markdown is returned on
result.text. Two related knobs control Markdown rendering:

• image_mode (ImageMode::Placeholder default | Off | Embed) — how raster
  images are surfaced in the output.
• extract_images (default false) — return embedded image bytes and metadata
  without changing Markdown image handling. This is the only option that enables
  extraction.
• image_output_dir — write extracted image files and return their names/paths;
  requires extract_images: true. Duplicate image resources reuse the same file.
• extract_links (default true) — render hyperlink annotations as
  [text](url); set false for plain anchor text.

use liteparse::config::{ImageMode, LiteParseConfig, OutputFormat};

let config = LiteParseConfig {
    output_format: OutputFormat::Markdown,
    image_mode: ImageMode::Placeholder,
    extract_images: true,
    image_output_dir: Some("./images".into()),
    extract_links: true,
    ..Default::default()
};
let result = LiteParse::new(config).parse("document.pdf").await?;
println!("{}", result.text); // rendered Markdown

Reconstruction quality varies with document complexity.

Parsing from Bytes Copy Chapter

use liteparse::types::PdfInput;

let pdf_bytes: Vec<u8> = std::fs::read("document.pdf")?;
let result = parser.parse_input(PdfInput::Bytes(pdf_bytes)).await?;
println!("{}", result.text);

Document Complexity Copy Chapter

Before committing to a full parse, check whether a document needs OCR or heavier
processing. is_complex is a cheap, text-layer-only pass that returns a
PageComplexityStats per page with a needs_ocr verdict and the signals behind it —
useful for routing documents to different pipelines, rejecting ones you can't handle, or
estimating cost.

use liteparse::types::PdfInput;

let parser = LiteParse::new(LiteParseConfig::default());
let pages = parser.is_complex(PdfInput::Path("document.pdf".into())).await?;

if pages.iter().any(|p| p.needs_ocr) {
    // Route to the OCR-enabled pipeline, inspect `p.reasons`, etc.
    for page in pages.iter().filter(|p| p.needs_ocr) {
        println!("Page {} needs OCR: {:?}", page.page_number, page.reasons);
    }
}

reasons is a Vec<ComplexityReason> (Scanned, NoText, SparseText,
EmbeddedImages, Garbled, VectorText, AnnotationText); new variants may be added over time, so match
leniently.

Custom OCR Engine Copy Chapter

Implement the OcrEngine trait to plug in your own OCR backend:

use liteparse::ocr::OcrEngine;
use std::sync::Arc;

let parser = LiteParse::new(LiteParseConfig::default())
    .with_ocr_engine(Arc::new(my_engine));

For a native ONNX backend, enable oar-ocr and supply a detection model,
recognition model, and matching character dictionary:

use liteparse::ocr::oar::OarOcrEngine;
use liteparse::{LiteParse, LiteParseConfig};
use std::path::Path;
use std::sync::Arc;

let models = Path::new("models");
let engine = OarOcrEngine::from_models(
    models.join("pp-ocrv6_small_det.onnx"),
    models.join("pp-ocrv6_small_rec.onnx"),
    models.join("ppocrv6_dict.txt"),
)?;

let parser = LiteParse::new(LiteParseConfig::default())
    .with_ocr_engine(Arc::new(engine));
# Ok::<(), Box<dyn std::error::Error>>(())

For opt-in model downloads, enable oar-ocr-auto-download and use a preset. On
first use, oar-ocr downloads the detection model, recognition model, and
matching dictionary from ModelScope, verifies their SHA-256 digests, and caches
them under $OAR_HOME (default ~/.oar):

use liteparse::ocr::oar::OarOcrEngine;

// Smallest / fastest PP-OCRv6 configuration.
let engine = OarOcrEngine::ppocr_v6_tiny()?;
# Ok::<(), Box<dyn std::error::Error>>(())

Presets cover the current and previous PP-OCR generations, from fastest to most
accurate: ppocr_v6_tiny, ppocr_v6_small, and ppocr_v6_medium. Each wires the correct
detector/recognizer/dictionary trio. For PP-OCRv4, a language-specific
recognizer, or a custom mix, use from_models with a matching dictionary.

To mix a detector, recognizer, and dictionary yourself, pass registered bare
file names to from_models. Pair the recognizer with its matching dictionary —
the tiny recognizer needs ppocrv6_tiny_dict.txt, while the larger models use
ppocrv6_dict.txt; a mismatched dictionary silently produces garbled text:

use liteparse::ocr::oar::OarOcrEngine;

let engine = OarOcrEngine::from_models(
    "pp-ocrv6_small_det.onnx",
    "pp-ocrv6_small_rec.onnx",
    "ppocrv6_dict.txt",
)?;
# Ok::<(), Box<dyn std::error::Error>>(())

All three artifacts also accept in-memory bytes, so the whole pipeline can be
embedded with include_bytes! rather than shipped as files. Use OAROCRBuilder
with OarOcrEngine::from_builder for model-specific settings or optional
orientation and rectification models. The fallible constructors return
liteparse::LiteParseError. All constructors use conservative batch sizes and
serialize page inference to avoid multiplying inference memory across
concurrently scheduled pages.
OcrOptions::language is not interpreted: the recognition model and character
dictionary define the supported languages, and a configured ocr_language
triggers a one-time warning to make that explicit.

Features Copy Chapter

• tesseract (default) — Built-in Tesseract OCR via tesseract-rs. Disable with default-features = false if you don't need OCR or want to use an HTTP OCR server instead.
• oar-ocr — Optional native ONNX backend via oar-ocr. Local or in-memory models; non-WASM Rust API only.
• oar-ocr-auto-download — Enables SHA-256-verified download and caching of registered model file names through oar-ocr.
• oar-ocr-cuda, oar-ocr-tensorrt, oar-ocr-directml, oar-ocr-coreml, oar-ocr-webgpu, oar-ocr-openvino — Forward the selected ONNX Runtime execution provider to oar-ocr.

The Node.js, Python, and WASM bindings build LiteParse with default features
disabled and do not expose these OAR features, so their published binaries do
not inherit the OAR model or runtime dependency footprint.

Supported Formats Copy Chapter

• PDF (.pdf)
• Microsoft Office (.docx, .xlsx, .pptx, etc.) — requires LibreOffice
• OpenDocument (.odt, .ods, .odp) — requires LibreOffice
• Images (.png, .jpg, .tiff, etc.)

CLI Copy Chapter

The crate also builds the lit CLI binary:

lit parse document.pdf
lit parse document.pdf --format json -o output.json
lit parse document.pdf --format markdown -o output.md
lit screenshot document.pdf -o ./screenshots
lit batch-parse ./input ./output
lit is-complex document.pdf

See lit --help for all options.

License Copy Chapter

Apache-2.0

Overview (`ocr/easyocr/README.md`) Copy Section

EasyOCR Service

This is a simple Flask server that wraps EasyOCR to conform to the LiteParse OCR API specification (see ../../OCR_API_SPEC.md).

Build and Run Copy Chapter

# install and run (in one command)
uv run server.py

Usage Copy Chapter

The service exposes a single endpoint:

• POST /ocr - Perform OCR on an uploaded image

Parameters Copy Section

• file - Image file (multipart/form-data)
• language - Language code (e.g., 'en', 'fr', 'de')

Example Copy Section

curl -X POST -F "[email protected]" -F "language=en" http://localhost:8828/ocr

Response Format Copy Section

{
  "results": [
    {
      "text": "recognized text",
      "bbox": [x1, y1, x2, y2],
      "confidence": 0.95
    }
  ]
}

This conforms to the LiteParse OCR API specification.

Supported Languages Copy Chapter

EasyOCR supports 80+ languages. Common language codes:

• en - English
• fr - French
• de - German
• es - Spanish
• zh - Chinese
• ja - Japanese
• ko - Korean
• ar - Arabic

Full list: https://www.jaided.ai/easyocr/

Use with LiteParse Copy Chapter

Once the server is running, use it with LiteParse OSS:

# Parse with EasyOCR
lit parse document.pdf --ocr-server-url http://localhost:8828/ocr

# With specific language
lit parse document.pdf --ocr-server-url http://localhost:8828/ocr --ocr-language zh

Or in code:

import { LiteParse } from 'liteparse';

const parser = new LiteParse({
  ocrServerUrl: 'http://localhost:8828/ocr',
  ocrLanguage: 'en',
});

const result = await parser.parse('document.pdf');

Testing Copy Chapter

If you make changes to the server, make sure to adapt and run tests:

uv run pytest test_server.py

Overview (`ocr/paddleocr/README.md`) Copy Section

PaddleOCR Service

This is a simple Flask server that wraps PaddleOCR to conform to the LiteParse OCR API specification (see ../../OCR_API_SPEC.md).

PaddleOCR is especially fast and accurate for Chinese, Japanese, and Korean languages.

Build and Run Copy Chapter

# install and run (in one command)
uv run server.py

Usage Copy Chapter

The service exposes a single endpoint:

• POST /ocr - Perform OCR on an uploaded image

Parameters Copy Section

• file - Image file (multipart/form-data)
• language - Language code (e.g., 'en', 'zh', 'ja', 'ko')

Example Copy Section

curl -X POST -F "[email protected]" -F "language=zh" http://localhost:8829/ocr

Response Format Copy Section

{
  "results": [
    {
      "text": "recognized text",
      "bbox": [x1, y1, x2, y2],
      "confidence": 0.95
    }
  ]
}

This conforms to the LiteParse OCR API specification.

Supported Languages Copy Chapter

PaddleOCR supports 80+ languages with excellent support for CJK:

• en - English
• zh / zh-cn - Chinese (Simplified)
• zh-tw / zh-hant - Chinese (Traditional)
• ja - Japanese
• ko - Korean
• fr - French
• de - German
• es - Spanish
• pt - Portuguese
• ru - Russian
• ar - Arabic
• hi - Hindi/Devanagari

Full list: https://github.com/PaddlePaddle/PaddleOCR

Performance Copy Chapter

PaddleOCR is optimized for speed and accuracy:

• Fast: 2-3x faster than EasyOCR
• Accurate: Especially for Asian languages (Chinese, Japanese, Korean)
• Lightweight: Smaller model sizes

Use with LiteParse Copy Chapter

Once the server is running, use it with LiteParse:

# Parse with PaddleOCR
lit parse document.pdf --ocr-server-url http://localhost:8829/ocr

# With specific language
lit parse document.pdf --ocr-server-url http://localhost:8829/ocr --ocr-language zh

Or in code:

import { LiteParse } from 'liteparse';

const parser = new LiteParse({
  ocrServerUrl: 'http://localhost:8829/ocr',
  ocrLanguage: 'zh',
});

const result = await parser.parse('document.pdf');

Testing Copy Chapter

If you make changes to the server, make sure to adapt and run tests:

uv run pytest test_server.py

GPU Support Copy Chapter

For GPU acceleration, set use_gpu=True in server.py.

Notes Copy Chapter

• First request may be slow as PaddleOCR downloads models
• Models are cached after first use
• Default port is 8829 (different from EasyOCR's 8828)

Overview (`ocr/suryaocr/README.md`) Copy Section

Surya OCR Service

A FastAPI server wrapping Surya OCR 2 to
conform to the LiteParse OCR API specification (see ../../OCR_API_SPEC.md).

Surya 2 is a multilingual OCR foundation model with strong accuracy across many
languages — a single model handles all languages with no per-language setup.

Build and Run Copy Chapter

# install and run (in one command)
uv run server.py

The first run downloads Surya model weights from Hugging Face and may take a few
minutes; weights are cached afterward.

Inference backend (required) Copy Chapter

Surya 2 is a VLM-backed model: text recognition runs through a separate
inference backend, which you must provide. Surya does not bundle it.

• CPU / local (llama.cpp): install the llama-server binary so Surya's
  llamacpp backend can spawn it:
  • macOS: brew install llama.cpp
  • Linux: brew install llama.cpp, or download a release from
    https://github.com/ggml-org/llama.cpp/releases and put llama-server on
    your PATH (or set LLAMA_CPP_BINARY=/path/to/llama-server).
• GPU (vllm): set SURYA_INFERENCE_BACKEND=vllm (requires a CUDA GPU).
• External server: point SURYA_INFERENCE_URL at an already-running Surya
  inference server to attach without spawning one locally.

Without a backend, startup succeeds and GET /health works, but POST /ocr
returns a 500 with "llama-server binary not found".

Docker (GPU, single image) Copy Chapter

The provided Dockerfile builds one image that runs both the API and the
model server on a GPU. It is based on the official CUDA llama.cpp image
(ghcr.io/ggml-org/llama.cpp:server-cuda), which ships a qwen35-capable
llama-server (Surya 2's custom GGUF architecture) with libggml-cuda and the
CUDA runtime. Surya spawns llama-server from PATH inside the same container,
so no sidecar or separate inference service is needed.

# Build
docker build -t suryaocr-liteparse:cuda .

# Run (requires the NVIDIA container runtime)
docker run --rm --gpus all -p 8830:8830 \
  -v "$HOME/.cache/suryaocr-models:/models" \
  suryaocr-liteparse:cuda

• --gpus all exposes the host GPUs; all model layers are offloaded
  (LLAMA_CPP_NGL=99).
• The -v …:/models mount caches weights (HF_HOME=/models). The first
  POST /ocr downloads the GGUF weights from Hugging Face and spawns
  llama-server (a few minutes); subsequent requests reuse the cache and the
  running server.

The image bakes in the backend configuration: SURYA_INFERENCE_BACKEND=llamacpp,
LLAMA_CPP_NGL=99, and SURYA_GUIDED_LAYOUT=false. The last one is required on
the upstream llama-server build: Surya's layout step is the only request that
sends a grammar, and its regex pattern breaks llama.cpp's
json-schema→GBNF converter (failed to parse grammar), which otherwise yields
empty results. With guided layout off, layout runs as free generation (Surya
parses the output itself) and the rest of the pipeline never uses a grammar.

To use a CUDA GPU via vLLM instead of bundled llama.cpp, set
SURYA_INFERENCE_BACKEND=vllm (see the backend section above).

Verify it is up:

curl http://localhost:8830/health
curl -X POST -F "[email protected]" http://localhost:8830/ocr

Usage Copy Chapter

The service exposes:

• POST /ocr — Perform OCR on an uploaded image
• GET /health — Health check

Parameters Copy Section

• file — Image file (multipart/form-data)
• language — Language code (accepted for API compatibility; ignored, since
  Surya 2 is multilingual)

Example Copy Section

curl -X POST -F "[email protected]" http://localhost:8830/ocr

Response Format Copy Section

{
  "results": [
    {
      "text": "recognized text",
      "bbox": [x1, y1, x2, y2],
      "confidence": 0.95,
      "polygon": [[x1, y1], [x2, y2], [x3, y3], [x4, y4]]
    }
  ]
}

Results are block-level (one entry per detected layout block), with each
block's HTML stripped to plain text. This conforms to the LiteParse OCR API spec.

Supported Languages Copy Chapter

Surya 2 is a single multilingual model — no language parameter is required
(the language field is accepted but ignored).

Per Surya's own benchmark, it scores an 87.2% overall pass rate across 91
languages, with 38 of the 91 languages scoring ≥ 90% and 76 scoring ≥ 80%,
covering text accuracy, layout, tables, math, and reading order. It has strong
performance across both Latin and non-Latin scripts.

• Full 91-language results: https://github.com/datalab-to/surya/blob/master/static/docs/multilingual.md
• Project overview: https://github.com/datalab-to/surya

Device / GPU Copy Chapter

There are two device knobs, for two different parts of the pipeline:

• LLAMA_CPP_NGL controls how many layers of the VLM (the model that reads
  text) the llamacpp backend offloads to the GPU. 99 offloads everything;
  0 keeps it on CPU. The Docker image sets 99.

• TORCH_DEVICE controls the device for Surya's helper torch models
  (e.g. layout). Surya auto-detects, or you can force it:

  bash Copy

  TORCH_DEVICE=cuda uv run server.py   # GPU
  TORCH_DEVICE=cpu  uv run server.py   # CPU

For a turnkey GPU deployment, prefer the Docker image above — it wires both up.

Use with LiteParse Copy Chapter

lit parse document.pdf --ocr-server-url http://localhost:8830/ocr

Or in code:

import { LiteParse } from 'liteparse';

const parser = new LiteParse({
  ocrServerUrl: 'http://localhost:8830/ocr',
});

const result = await parser.parse('document.pdf');

Testing Copy Chapter

uv run pytest test_server.py

Tests mock the Surya predictor, so they run without downloading any models.

Notes Copy Chapter

• First request/startup may be slow while models download.
• Default port is 8830 (easyocr 8828, paddleocr 8829).
• Output is block-granular; Surya 2 has no per-line text API.

Overview (`packages/node/README.md`) Copy Section

LiteParse Node.js

Node.js/TypeScript bindings for LiteParse — fast, lightweight PDF and document parsing with spatial text extraction.

Installation Copy Chapter

npm i @llamaindex/liteparse

This also installs the lit CLI command (use npm i -g for global access).

Quick Start Copy Chapter

import { LiteParse } from '@llamaindex/liteparse';

const parser = new LiteParse();
const result = await parser.parse('document.pdf');
console.log(result.text);
console.log(`Source document pages: ${result.totalPages}`);

// Access structured data
for (const page of result.pages) {
  console.log(`Page ${page.pageNum}: ${page.textItems.length} text items`);
}

CommonJS is supported as well:

const { LiteParse } = require('@llamaindex/liteparse');

(async () => {
  const parser = new LiteParse();
  const result = await parser.parse('document.pdf');
  console.log(result.text);
})();

Bounded-memory parsing Copy Section

For documents with many text items, consume page batches without retaining
earlier results:

const parser = new LiteParse();
for await (const batch of parser.parseBatches('large.pdf', { batchSize: 20 })) {
  await processPages(batch.result.pages);
}

Each batch is an ordinary parse result covering batch.startPage through
batch.endPage, and becomes collectible as soon as you advance the iterator.
A non-PDF source is converted once, not once per batch.

Cross-page passes only see the pages in their own batch, so repeated
header/footer removal and image deduplication are batch-local and the output
can differ from parse(). Prefer parse() unless the size of the
materialized result is the problem.

Markdown Output Copy Chapter

LiteParse can render documents directly to Markdown including headings, tables, lists,
images, and links reconstructed from the spatial layout. Great for feeding LLMs
and RAG pipelines. The rendered Markdown is returned on result.text:

const parser = new LiteParse({
  outputFormat: 'markdown',     // "json" | "text" | "markdown"
  imageMode: 'placeholder',     // "placeholder" | "off" | "embed"
  extractLinks: true,           // render [text](url) link syntax (default: true)
});
const result = await parser.parse('document.pdf');
console.log(result.text); // rendered Markdown

Reconstruction quality varies with document complexity.

Configuration Copy Chapter

All options are passed to the constructor:

/* Detailed source-code truncated for AI context efficiency. */

When extractImages is true, image extraction is enabled. imageOutputDir requires
that explicit opt-in and writes the extracted bytes to disk. Each
result.images entry includes its page bbox, intrinsic pixel dimensions, rotation,
format, name, and path. Valid source JPEGs are preserved, exact duplicates reuse
one file, and JSON CLI output contains metadata only (no base64 image data).
imageMode controls Markdown presentation only and does not imply extraction. With
extractImages: false, lightweight Markdown placement refs are still collected and
result.images stays empty.

The Node CLI uses the same snake_case JSON schema as the Rust CLI; camelCase is
reserved for the programmatic Node API.

When extractAnnotations is enabled, each parsed page has an annotations
array containing the subtype, contents, author/title, PDF date strings,
viewport-space rectangle and quadpoint rectangles, and URI for external link
annotations. It is independent of extractLinks, which controls Markdown link
rendering. The field is omitted when extraction is disabled.

When extractStructureTree is enabled, each page has a structureTree containing
all tagged-PDF roots and recursive elements with type, ID, actual/alternate text,
title, typed attributes, MCIDs, children, and referenced link annotations. Untagged
pages have an empty roots array; the field is omitted when disabled.

Every result also carries the document's /Info creator/producer when
present. With extractDocumentMetadata, result.docMeta adds a provenance
object with dates, PDF version/security, signature state, incremental-save
markers, trailer ID comparison, the catalog's XMP packet (capped at 64 KiB;
skipped for sources over 16 MiB), and source size — off by default since it
streams the whole file, and absent for inputs converted from a non-PDF
format. These are API-level only, not in CLI JSON. With extractContentBounds
each page carries a contentBounds union bbox of its top-level content
objects. With extractXfaPackets, result.xfaPackets lists each raw XFA
packet (index, name, content length, XML content); non-XFA documents yield an
empty array. Screenshots draw form-field appearances into the raster and
report isSolidFill per page, plus detected solid rects when
detectScreenshotRects is enabled.

Parsing from Bytes Copy Chapter

Pass a Buffer or Uint8Array directly — useful for HTTP responses or in-memory data:

import { readFile } from 'fs/promises';

const pdfBytes = await readFile('document.pdf');
const result = await parser.parse(pdfBytes);
console.log(result.text);

Worker Pool and Hard Timeouts Copy Chapter

PDFium is not thread-safe, so all parses inside one process serialize on a
process-global lock — even Promise.all over multiple parse() calls runs
them one at a time.

For high-throughput services, or for cases when you need to enforce a
runtime timeout, run parses in a pool of persistent worker processes instead:

import { LiteParse, ParseTimeoutError } from '@llamaindex/liteparse';

const parser = new LiteParse({ poolSize: 4, parseTimeoutMs: 15_000 });
await parser.warmUp(); // optional: pre-initialize workers (~45ms total)

try {
  const result = await parser.parse('document.pdf');
} catch (e) {
  if (e instanceof ParseTimeoutError) {
    console.warn(`killed rogue document: ${e.source} (deadline ${e.timeoutMs}ms)`);
  }
}

parser.close(); // frees workers immediately; an idle pool never blocks exit

Screenshots Copy Chapter

Generate PNG screenshots of document pages:

const screenshots = parser.screenshot('document.pdf', [1, 2, 3]);
for (const s of screenshots) {
  console.log(`Page ${s.pageNum}: ${s.width}x${s.height}`);
  // s.imageBuffer contains PNG bytes
}

Document Complexity Copy Chapter

Before committing to a full parse, check whether a document needs OCR or heavier
processing. isComplex is a cheap, text-layer-only pass that returns one entry per page
with a needsOcr verdict and the signals behind it — useful for routing documents to
different pipelines, rejecting ones you can't handle, or estimating cost.

const parser = new LiteParse();
const pages = await parser.isComplex('document.pdf');

if (pages.some((p) => p.needsOcr)) {
  // Route to the OCR-enabled pipeline
  const result = await parser.parse('document.pdf');
} else {
  // Cheap path — skip OCR entirely
  const result = await new LiteParse({ ocrEnabled: false }).parse('document.pdf');
}

// Inspect why specific pages were flagged
for (const page of pages.filter((p) => p.needsOcr)) {
  console.log(`Page ${page.pageNumber}: ${page.reasons.join(', ')}`);
}

reasons is one of "scanned", "no-text", "sparse-text", "embedded-images",
"garbled", "vector-text", or "annotation-text". Raw bytes work here too.

Supported Formats Copy Chapter

• PDF (.pdf)
• Microsoft Office (.docx, .xlsx, .pptx, etc.) — requires LibreOffice
• OpenDocument (.odt, .ods, .odp) — requires LibreOffice
• Images (.png, .jpg, .tiff, etc.)
• And more!

CLI Copy Chapter

The npm package includes the lit CLI:

lit parse document.pdf
lit parse document.pdf --format json -o output.json
lit parse document.pdf --format json --extract-annotations
lit parse document.pdf --format json --extract-form-fields
lit screenshot document.pdf -o ./screenshots
lit batch-parse ./input ./output
lit is-complex document.pdf

Overview (`packages/python/README.md`) Copy Section

LiteParse Python

Python bindings for LiteParse — fast, lightweight PDF and document parsing with spatial text extraction.

Installation Copy Chapter

pip install liteparse

This also installs the lit CLI command.

Quick Start Copy Chapter

from liteparse import LiteParse

parser = LiteParse()
result = parser.parse("document.pdf")
print(result.text)
print(f"Source document pages: {result.total_pages}")

# Access structured data
for page in result.pages:
    print(f"Page {page.page_num}: {len(page.text_items)} text items")

Markdown Output Copy Chapter

LiteParse can render documents directly to Markdown including headings, tables, lists,
images, and links reconstructed from the spatial layout. Great for feeding LLMs
and RAG pipelines. The rendered Markdown is returned on result.text:

parser = LiteParse(
    output_format="markdown",   # "json" | "text" | "markdown"
    image_mode="placeholder",   # "placeholder" | "off" | "embed"
    extract_links=True,         # render [text](url) link syntax (default: True)
)
result = parser.parse("document.pdf")
print(result.text)  # rendered Markdown

Reconstruction quality varies with document complexity.

Configuration Copy Chapter

All options are passed to the constructor:

/* Detailed source-code truncated for AI context efficiency. */

When extract_images=True, image extraction is enabled. image_output_dir
requires that explicit opt-in and writes the extracted bytes to disk. Each
result.images entry includes its page bbox, intrinsic pixel dimensions, rotation,
format, name, and path. Valid source JPEGs are preserved, exact duplicates
reuse one file, and JSON CLI output contains metadata only (no base64 image data).
image_mode controls Markdown presentation only and does not imply extraction.
With extract_images=False, lightweight Markdown placement refs are still collected
and result.images stays empty.

When extract_annotations is enabled, each parsed page has an annotations
list containing the subtype, contents, author/title, PDF date strings,
viewport-space rectangle and quadpoint rectangles, and URI for external link
annotations. It is independent of extract_links, which controls Markdown
link rendering. The field is None when extraction is disabled.

When extract_structure_tree=True, each page has a structure_tree containing
all tagged-PDF roots and recursive elements with type, ID, actual/alternate text,
title, typed attributes, MCIDs, children, and referenced link annotations. Untagged
pages have an empty roots list; the field is None when disabled.

Every result also carries creator/producer from the PDF /Info
dictionary. With extract_document_metadata=True, result.doc_meta adds a
provenance object with dates, PDF version/security, signature state,
incremental-save markers, trailer ID comparison, the catalog's XMP packet
(capped at 64 KiB; skipped for sources over 16 MiB), and source size. It is off by default because it streams the whole source file,
and it is None for inputs converted from a non-PDF format. These document
fields are API-only and do not alter default CLI JSON.

Parsing from Bytes Copy Chapter

Pass raw PDF bytes directly — useful for web uploads or downloaded files:

with open("document.pdf", "rb") as f:
    result = parser.parse(f.read())
print(result.text)

Worker Pool and Hard Timeouts Copy Chapter

PDFium is not thread-safe, so in-process parses serialize on a process-global
lock. For high-throughput services, or cases where you need to enforce a timeout,
run parses in a pool of persistent worker processes instead:

from liteparse import LiteParse, ParseTimeoutError

parser = LiteParse(pool_size=4, parse_timeout=15)
parser.warm_up()  # optional: pre-initialize workers (~60ms total)

try:
    result = parser.parse("document.pdf")
except ParseTimeoutError as e:
    print(f"killed rogue document: {e.source} (deadline {e.timeout}s)")

parser.close()  # or use `with LiteParse(...) as parser:`

Screenshots Copy Chapter

Generate PNG screenshots of document pages:

screenshots = parser.screenshot("document.pdf", page_numbers=[1, 2, 3])
for s in screenshots:
    print(f"Page {s.page_num}: {s.width}x{s.height}")
    with open(f"page_{s.page_num}.png", "wb") as f:
        f.write(s.image_bytes)

Document Complexity Copy Chapter

Before committing to a full parse, check whether a document needs OCR or heavier
processing. is_complex is a cheap, text-layer-only pass that returns one entry per page
with a needs_ocr verdict and the signals behind it — useful for routing documents to
different pipelines, rejecting ones you can't handle, or estimating cost.

parser = LiteParse()
pages = parser.is_complex("document.pdf")

if any(p.needs_ocr for p in pages):
    # Route to the OCR-enabled pipeline
    result = parser.parse("document.pdf")
else:
    # Cheap path — skip OCR entirely
    result = LiteParse(ocr_enabled=False).parse("document.pdf")

# Inspect why specific pages were flagged
for page in pages:
    if page.needs_ocr:
        print(f"Page {page.page_number}: {', '.join(page.reasons)}")

reasons is one of "scanned", "no-text", "sparse-text", "embedded-images",
"garbled", "vector-text", or "annotation-text". Raw bytes work here too.

Supported Formats Copy Chapter

• PDF (.pdf)
• Microsoft Office (.docx, .xlsx, .pptx, etc.) — requires LibreOffice
• OpenDocument (.odt, .ods, .odp) — requires LibreOffice
• Images (.png, .jpg, .tiff, etc.)
• And more!

CLI Copy Chapter

The Python package includes the lit CLI:

lit parse document.pdf
lit parse document.pdf --format json -o output.json
lit parse document.pdf --format json --extract-annotations
lit parse document.pdf --format json --extract-form-fields
lit screenshot document.pdf -o ./screenshots
lit batch-parse ./input ./output
lit is-complex document.pdf

Overview (`packages/wasm/README.md`) Copy Section

@llamaindex/liteparse-wasm

Browser/WebAssembly build of LiteParse — a fast, lightweight PDF parser with spatial text extraction.

This package runs entirely in the browser. No server, no cloud calls.

Install Copy Chapter

npm install @llamaindex/liteparse-wasm

Quick start Copy Chapter

import init, { LiteParse } from "@llamaindex/liteparse-wasm";

// Load the wasm module (point at the file shipped with the package).
await init();

const parser = new LiteParse({
  ocrEnabled: false, // OCR requires a JS-side engine (see below)
  outputFormat: "json",
});

// `data` is a Uint8Array (e.g. from fetch / File / drag-drop).
const bytes = new Uint8Array(await file.arrayBuffer());
const result = await parser.parse(bytes);

console.log(result.text);          // full document text
console.log(result.pages[0]);      // per-page items with bboxes

Document complexity Copy Chapter

Before committing to a full parse, check whether a document needs OCR or heavier
processing. isComplex is a cheap, text-layer-only pass that returns one entry per page
with a needsOcr verdict and the signals behind it — useful for routing documents or
deciding whether the JS-side OCR engine is worth wiring up.

const parser = new LiteParse({ ocrEnabled: false });
const bytes = new Uint8Array(await file.arrayBuffer());
const pages = await parser.isComplex(bytes);

if (pages.some((p) => p.needsOcr)) {
  // This document would benefit from OCR — see "OCR in the browser" below
  for (const page of pages.filter((p) => p.needsOcr)) {
    console.log(`Page ${page.pageNumber}: ${page.reasons.join(", ")}`);
  }
}

reasons is one of "scanned", "no-text", "sparse-text", "embedded-images",
"garbled", "vector-text", or "annotation-text".

Config options Copy Chapter

All optional, camelCase:

OCR in the browser Copy Chapter

The native HTTP-OCR and Tesseract backends are not available in the browser.
To use OCR, set ocrEnabled: true and supply an ocrEngine object with a
recognize method. Supplying ocrEngine alone does not enable OCR.

const parser = new LiteParse({
  ocrEnabled: true,
  ocrLanguage: "eng",
  // Use more than 1 only if the engine supports concurrent jobs.
  numWorkers: 2,
  ocrEngine: {
    /**
     * @param imageData PNG-encoded image bytes
     * @param width  rendered page width  in pixels
     * @param height rendered page height in pixels
     * @param language e.g. "eng"
     * @returns array of { text, bbox: [x1,y1,x2,y2], confidence }
     */
    async recognize(imageData, width, height, language) {
      // e.g. call a worker that wraps tesseract.js, or a remote OCR service
      return [
        { text: "Hello", bbox: [10, 20, 80, 40], confidence: 0.98 },
      ];
    },
  },
});

LiteParse keeps at most numWorkers calls to recognize active. When one call
finishes, LiteParse prepares and starts the next page without waiting for the
other calls. An OCR engine can send the calls to a Web Worker pool or to
concurrent HTTP requests. Results stay assigned to their source pages when
jobs finish out of order. Active calls can keep up to numWorkers rendered
page rasters in memory, so use a small value for high-DPI documents.

A failed recognize call only affects its own page. With ocrFailureFatal: true (the default), parse() rejects only when every OCR call failed and at
least one failed page had little native text. If parsing fails, OCR calls that
have already started can continue.

Building from source Copy Chapter

Requires Rust + wasm-pack:

# from packages/wasm
npm run build           # web target (default)
npm run build:bundler   # for webpack/rollup/vite
npm run build:nodejs    # for node.js

Output goes to pkg/.

License Copy Chapter

Apache-2.0

Src Content Docs Liteparse Index (`docs/src/content/docs/liteparse/index.md`) Copy Section

title: What is LiteParse? sidebar: order: 0 Copy Chapter

LiteParse is an open-source document parsing library that parses text with spatial layout information and bounding boxes. Written in Rust for speed and reliability, it runs entirely on your machine with no cloud dependencies, no LLMs, and no API keys.

LiteParse is designed specifically for use cases that require fast, accurate text parsing: real-time applications, coding agents, and local workflows. It provides a simple CLI and library API for parsing PDFs, Office documents, and images, with built-in OCR support.

What can LiteParse do? Copy Chapter

• Parse PDFs with precise spatial layout. Text comes back positioned where it appears on the page
• Render to Markdown with headings, tables, lists, images, and links — clean structured output for LLMs and RAG pipelines
• Extract bounding boxes for every text line, ready for downstream processing or visualization
• 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 Copy Chapter

• Getting started: Install LiteParse and parse your first document.
• Markdown output: Render documents to clean, structured Markdown.
• Extraction options: Opt in to images, form fields, annotations, and more.
• Document complexity: Detect scanned, multi-column, and table-heavy pages up front.
• Library usage: Use LiteParse from TypeScript or Python code.
• Browser usage (WASM): Run LiteParse in the browser with zero server dependencies.
• Agent skill: Give Claude Code, Cursor, or Codex the ability to parse documents locally.
• CLI reference: Complete command and option reference.
• API reference: Detailed API documentation (rust) for all public types and functions. The same types apply across all language bindings.

Src Content Docs Liteparse Cli Reference (`docs/src/content/docs/liteparse/cli-reference.md`) Copy Section

title: CLI Reference sidebar: order: 5 Copy Chapter

LiteParse provides the lit CLI with four commands: parse, batch-parse, screenshot, and is-complex. The CLI is the same whether installed via npm, pip, or built from Rust source.

`lit parse` Copy Chapter

Parse a single document.

lit parse [options] <file>

Arguments Copy Section

Options Copy Section

Extraction options Copy Section

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.

Examples Copy Section

# Basic text parsing
lit parse report.pdf

# JSON output with bounding boxes
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 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

# High-DPI rendering with French OCR
lit parse report.pdf --dpi 300 --ocr-language fra

# Use an external OCR server
lit parse report.pdf --ocr-server-url http://localhost:8828/ocr

# Pipe output to another tool
lit parse report.pdf -q | wc -l

# Parse a remote file via stdin
curl -sL https://example.com/report.pdf | lit parse --no-ocr -

`lit batch-parse` Copy Chapter

Parse multiple documents in a directory.

lit batch-parse [options] <input-dir> <output-dir>

Arguments Copy Section

Options Copy Section

batch-parse accepts the same extraction options as lit parse: --extract-images, --extract-vector-graphics, --extract-annotations, --extract-form-fields, --extract-structure-tree, --extract-blocks, --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 Copy Section

# Parse all supported files in a directory
lit batch-parse ./documents ./output

# Recursively parse only PDFs
lit batch-parse ./documents ./output --recursive --extension ".pdf"

# Batch parse with JSON output and no OCR
lit batch-parse ./documents ./output --format json --no-ocr

`lit screenshot` Copy Chapter

Generate page images from a document (PDF, DOCX, XLSX, images, etc.).

lit screenshot [options] <file>

Arguments Copy Section

Options Copy Section

Examples Copy Section

# Screenshot all pages of a PDF
lit screenshot document.pdf -o ./pages

# Screenshot a Word document (requires LibreOffice)
lit screenshot report.docx -o ./pages

# First 5 pages at high DPI
lit screenshot document.pdf --target-pages "1-5" --dpi 300 -o ./pages

# Specific pages only
lit screenshot document.pdf --target-pages "1,5,10" -o ./pages

`lit is-complex` Copy Chapter

Check whether a document needs OCR or heavier parsing — a cheap pre-parse pass over the text layer only (no rasterization, no OCR). See the Document Complexity guide for details.

lit is-complex [options] <file>

The command prints per-page JSON to stdout, a human-readable verdict to stderr, and exits non-zero when any page needs OCR — so it works as a shell predicate or a jq source.

Arguments Copy Section

Options Copy Section

Examples Copy Section

# Print the complexity verdict and per-page JSON
lit is-complex document.pdf

# Use as a shell predicate: only parse with --no-ocr when simple
lit is-complex document.pdf --quiet && lit parse document.pdf --no-ocr

# List the page numbers that need OCR
lit is-complex document.pdf --compact | jq '[.[] | select(.needs_ocr) | .page_number]'

Global options Copy Chapter

These options are available on all commands:

Src Content Docs Liteparse Getting Started (`docs/src/content/docs/liteparse/getting_started.mdx`) Copy Section

title: Getting Started sidebar: order: 1 Copy Chapter

LiteParse is available for Node.js, Python, and as a standalone Rust binary.

All versions (except WASM) ship the same CLI and core library capabilities.

Installation Copy Chapter

npm i @llamaindex/liteparse

pip install liteparse

cargo install liteparse

npm i @llamaindex/liteparse-wasm

# Parse a PDF and print text to stdout
lit parse document.pdf

# Save output to a file
lit parse document.pdf -o output.txt

# Get structured JSON with bounding boxes
lit parse document.pdf --format json -o output.json

# Render to Markdown (headings, tables, lists, images, links)
lit parse document.pdf --format markdown -o output.md

# Parse only specific pages
lit parse document.pdf --target-pages "1-5,10,15-20"

lit batch-parse ./pdfs ./outputs

lit screenshot document.pdf -o ./screenshots

npx skills add run-llama/llamaparse-agent-skills --skill liteparse

npm install @llamaindex/liteparse-wasm

import init, { LiteParse } from "@llamaindex/liteparse-wasm";

// Load the WASM module
await init();

const parser = new LiteParse({
  ocrEnabled: false,
  outputFormat: "json",
});

// data is a Uint8Array (e.g. from <input type="file"> or fetch)
const bytes = new Uint8Array(await file.arrayBuffer());
const result = await parser.parse(bytes);

console.log(result.text);
console.log(result.pages[0]);

const parser = new LiteParse({
  ocrEnabled: true,
  ocrLanguage: "eng",
  // Use more than 1 only if the engine supports concurrent jobs.
  numWorkers: 2,
  ocrEngine: {
    /**
     * @param imageData PNG-encoded image bytes
     * @param width  rendered page width in pixels
     * @param height rendered page height in pixels
     * @param language e.g. "eng"
     * @returns array of { text, bbox: [x1, y1, x2, y2], confidence }
     */
    async recognize(imageData, width, height, language) {
      // e.g. call a Web Worker wrapping tesseract.js, or a remote OCR service
      return [
        { text: "Hello", bbox: [10, 20, 80, 40], confidence: 0.98 },
      ];
    },
  },
});

lit is-complex document.pdf

// stdout
[
  {
    "page_number": 1,
    "text_length": 0,
    "text_coverage": 0.0,
    "has_substantial_images": false,
    "image_block_count": 0,
    "image_coverage": 0.0,
    "largest_image_coverage": 0.0,
    "full_page_image": true,
    "uncovered_vector_area": null,
    "is_garbled": false,
    "page_area": 482400.0,
    "needs_ocr": true,
    "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"]
    }
  }
]

# stderr
COMPLEX — 1/1 page(s) need OCR

# Only parse with --no-ocr when the document is simple
lit is-complex document.pdf --quiet && lit parse document.pdf --no-ocr

lit is-complex document.pdf --compact | jq '[.[] | select(.needs_ocr) | .page_number]'

lit parse document.pdf --format json --complexity

import { LiteParse } from "@llamaindex/liteparse";

const parser = new LiteParse({ ocrEnabled: false });
const pages = await parser.isComplex("document.pdf");

const complex = pages.some((p) => p.needsOcr);
if (complex) {
  // Route to a heavyweight pipeline, like LlamaParse
  ...
} else {
  // Cheap path — skip OCR entirely
  const result = await parser.parse("document.pdf");
}

// Inspect why specific pages were flagged
for (const page of pages.filter((p) => p.needsOcr)) {
  console.log(`Page ${page.pageNumber}: ${page.reasons.join(", ")}`);
}

from liteparse import LiteParse

parser = LiteParse(ocr_enabled=False)
pages = parser.is_complex("document.pdf")

if any(p.needs_ocr for p in pages):
    # Route to a heavyweight pipeline, like LlamaParse
    ...
else:
    # Cheap path — skip OCR entirely
    result = parser.parse("document.pdf")

# Inspect why specific pages were flagged
for page in pages:
    if page.needs_ocr:
        print(f"Page {page.page_number}: {', '.join(page.reasons)}")

import { LiteParse } from "@llamaindex/liteparse-wasm";

const parser = new LiteParse();
const pages = await parser.isComplex(pdfBytes); // Uint8Array

const complex = pages.some((p) => p.needsOcr);

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");

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")

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?;

lit parse form.pdf --format json \
  --extract-images \
  --extract-form-fields \
  --extract-annotations \
  --extract-text-metadata

lit parse report.pdf --format json --extract-images --image-output-dir ./images

{
  "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
}

{
  "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": [
    {
      "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 }
      ]
    }
  ]
}

{
  "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
    }
  ]
}

{
  "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": []
          }
        ]
      }
    ]
  }
}

lit parse document.pdf --format json --extract-blocks

{
  "kind": "heading",
  "text": "Quarterly Report",
  "level": 1,
  "bbox": { "x": 72.0, "y": 114.88, "width": 284.0, "height": 21.0 }
}

{
  "kind": "table",
  "bbox": { "x": 67.9, "y": 511.1, "width": 458.4, "height": 111.0 },
  "header": [
    { "text": "Title of each class", "bbox": { "x": 132.7, "y": 511.1, "width": 64.0, "height": 8.0 } },
    { "text": "Trading symbol(s)",   "bbox": { "x": 288.7, "y": 511.1, "width": 35.0, "height": 8.0 } }
  ],
  "rows": [
    [
      { "text": "Common Stock", "bbox": { "x": 67.9, "y": 522.4, "width": 193.0, "height": 9.5 } },
      { "text": "AAPL",         "bbox": { "x": 293.8, "y": 522.4, "width": 24.0, "height": 9.5 } }
    ]
  ]
}

import pandas as pd
from liteparse import LiteParse

result = LiteParse(extract_blocks=True).parse("10-k.pdf")

for page in result.pages:
    for block in page.blocks or []:
        if block.kind == "table":
            df = pd.DataFrame(
                [[c.text for c in row] for row in block.rows],
                columns=[c.text for c in block.header or []],
            )

import { LiteParse } from "@llamaindex/liteparse";

const { pages } = await new LiteParse({ extractBlocks: true }).parse("10-k.pdf");

for (const page of pages) {
  for (const block of page.blocks ?? []) {
    if (block.kind !== "table") continue;
    const grid = [block.header ?? [], ...block.rows].map((r) => r.map((c) => c.text));
  }
}

{
  "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"
}

{ "content_bounds": { "x": 68.0, "y": 96.0, "width": 476.0, "height": 620.0 } }

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);
  }
}

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)

// 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 },
});

# (top, right, bottom, left)
parser = LiteParse(crop_box=(0.1, 0.0, 0.05, 0.0))

// Page 3 was scanned upside down, page 7 sideways (content rotated 90° clockwise)
const parser = new LiteParse({
  pageOrientationCorrections: [
    { page: 3, angle: 180 },
    { page: 7, angle: 90 },
  ],
});

# (page, angle) pairs
parser = LiteParse(page_orientation_corrections=[(3, 180), (7, 90)])

npm install @llamaindex/liteparse
# or
pnpm add @llamaindex/liteparse

import { LiteParse } from "@llamaindex/liteparse";

const parser = new LiteParse({ ocrEnabled: true });
const result = await parser.parse("document.pdf");

// Full document text with layout preserved
console.log(result.text);

// Per-page data
for (const page of result.pages) {
  console.log(`Page ${page.pageNum}: ${page.textItems.length} text items`);
}

const parser = new LiteParse({ outputFormat: "json" });
const result = await parser.parse("document.pdf");

for (const page of result.pages) {
  for (const item of page.textItems) {
    console.log(`[${item.x}, ${item.y}] ${item.width}×${item.height} "${item.text}"`);
  }
}

const parser = new LiteParse({
  outputFormat: "markdown",   // "json" | "text" | "markdown"
  imageMode: "placeholder",   // "placeholder" | "off" | "embed"
  extractLinks: true,         // render [text](url) link syntax (default: true)
});
const result = await parser.parse("document.pdf");
console.log(result.text); // rendered Markdown

const parser = new LiteParse({
  ocrEnabled: true,
  ocrServerUrl: "http://localhost:8828/ocr",
  ocrLanguage: "fra",
  dpi: 300,
  outputFormat: "json",
  targetPages: "1-10",
  password: "secret",
});

import { readFile } from "fs/promises";

const parser = new LiteParse();

// From a file read
const pdfBytes = await readFile("document.pdf");
const result = await parser.parse(pdfBytes);

// From an HTTP response
const response = await fetch("https://example.com/document.pdf");
const buffer = Buffer.from(await response.arrayBuffer());
const result2 = await parser.parse(buffer);

const parser = new LiteParse();
const screenshots = await parser.screenshot("document.pdf");

for (const shot of screenshots) {
  console.log(`Page ${shot.pageNum}: ${shot.width}x${shot.height}`);
  // shot.imageBuffer contains the raw PNG data
}

// Screenshot specific pages
const shots = await parser.screenshot("document.pdf", [1, 2, 3]);

pip install liteparse

from liteparse import LiteParse

parser = LiteParse()
result = parser.parse("document.pdf")

# Full document text
print(result.text)

# Per-page data
for page in result.pages:
    print(f"Page {page.page_num}: {len(page.text_items)} text items")

parser = LiteParse(
    ocr_enabled=True,
    ocr_server_url="http://localhost:8828/ocr",
    ocr_language="fra",
    dpi=300,
    target_pages="1-5",
    password="secret",
)
result = parser.parse("document.pdf")

parser = LiteParse(
    output_format="markdown",   # "json" | "text" | "markdown"
    image_mode="placeholder",   # "placeholder" | "off" | "embed"
    extract_links=True,         # render [text](url) link syntax (default: True)
)
result = parser.parse("document.pdf")
print(result.text)  # rendered Markdown

with open("document.pdf", "rb") as f:
    pdf_bytes = f.read()

result = parser.parse(pdf_bytes)
print(result.text)

screenshots = parser.screenshot("document.pdf", page_numbers=[1, 2, 3])
for s in screenshots:
    print(f"Page {s.page_num}: {s.width}x{s.height}")
    # s.image_bytes contains PNG data

[dependencies]
liteparse = "2"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

use liteparse::{LiteParse, LiteParseConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let parser = LiteParse::new(LiteParseConfig::default());
    let result = parser.parse("document.pdf").await?;

    // Full document text
    println!("{}", result.text);

    // Per-page data
    for page in &result.pages {
        println!("Page {}: {} text items", page.page_number, page.text_items.len());
    }
    Ok(())
}

use liteparse::{LiteParse, LiteParseConfig};
use liteparse::types::PdfInput;

let parser = LiteParse::new(LiteParseConfig::default());
let pdf_bytes = std::fs::read("document.pdf")?;
let result = parser.parse_input(PdfInput::Bytes(pdf_bytes)).await?;

use liteparse::{LiteParse, LiteParseConfig, OutputFormat};

let config = LiteParseConfig {
    ocr_enabled: true,
    ocr_language: "fra".to_string(),
    dpi: 300.0,
    target_pages: Some("1-10".to_string()),
    output_format: OutputFormat::Json,
    password: Some("secret".to_string()),
    ..Default::default()
};
let parser = LiteParse::new(config);

use liteparse::config::{ImageMode, LiteParseConfig, OutputFormat};
use liteparse::LiteParse;

let config = LiteParseConfig {
    output_format: OutputFormat::Markdown,
    image_mode: ImageMode::Placeholder,
    extract_links: true,
    ..Default::default()
};
let result = LiteParse::new(config).parse("document.pdf").await?;
println!("{}", result.text); // rendered Markdown

let parser = LiteParse::new(LiteParseConfig::default());
let screenshots = parser.screenshot("document.pdf", None).await?;

for shot in &screenshots {
    println!("Page {}: {}x{}", shot.page_num, shot.width, shot.height);
    // shot.image_bytes contains the raw PNG data
}

// Screenshot specific pages
let shots = parser.screenshot("document.pdf", Some(vec![1, 2, 3])).await?;

use liteparse::LiteParse;
use liteparse::ocr::OcrEngine;
use std::sync::Arc;

let parser = LiteParse::new(Default::default())
    .with_ocr_engine(Arc::new(my_engine));

npm install @llamaindex/liteparse-wasm

import init, { LiteParse } from "@llamaindex/liteparse-wasm";

// Initialize the WASM module (required once before use)
await init();

const parser = new LiteParse({ ocrEnabled: false });

// Pass a Uint8Array (e.g. from fetch, File input, or drag-drop)
const bytes = new Uint8Array(await file.arrayBuffer());
const result = await parser.parse(bytes);

console.log(result.text);          // full document text
console.log(result.pages[0]);      // per-page items with bboxes

const parser = new LiteParse({
  ocrEnabled: true,
  ocrLanguage: "fra",
  dpi: 300,
  outputFormat: "json",
  targetPages: "1-10",
  maxPages: 100,
  password: "secret",
  quiet: false,
});

const parser = new LiteParse({ outputFormat: "markdown" });
const result = await parser.parse(bytes);
console.log(result.text); // rendered Markdown

const parser = new LiteParse({
  ocrEnabled: true,
  ocrLanguage: "eng",
  ocrEngine: {
    /**
     * @param imageData - PNG-encoded image bytes
     * @param width     - rendered page width in pixels
     * @param height    - rendered page height in pixels
     * @param language  - e.g. "eng"
     * @returns array of recognized text regions
     */
    async recognize(imageData, width, height, language) {
      // e.g. call tesseract.js in a worker, or a remote OCR service
      return [
        { text: "Hello", bbox: [10, 20, 80, 40], confidence: 0.98 },
      ];
    },
  },
});

# Render a document to Markdown
lit parse document.pdf --format markdown -o output.md

# Print Markdown to stdout
lit parse document.pdf --format markdown

# 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 --extract-images --image-output-dir ./images

lit parse document.pdf --format markdown --no-links

lit parse document.pdf --format markdown --keep-headers-footers

import { LiteParse } from "@llamaindex/liteparse";

const parser = new LiteParse({
  outputFormat: "markdown",   // "json" | "text" | "markdown"
  imageMode: "placeholder",   // "placeholder" | "off" | "embed" (default: "placeholder")
  extractLinks: true,         // render [text](url) link syntax (default: true)
});
const result = await parser.parse("document.pdf");
console.log(result.text); // rendered Markdown

from liteparse import LiteParse

parser = LiteParse(
    output_format="markdown",   # "json" | "text" | "markdown"
    image_mode="placeholder",   # "placeholder" | "off" | "embed"
    extract_links=True,         # render [text](url) link syntax (default: True)
)
result = parser.parse("document.pdf")
print(result.text)  # rendered Markdown

use liteparse::config::{ImageMode, LiteParseConfig, OutputFormat};
use liteparse::LiteParse;

let config = LiteParseConfig {
    output_format: OutputFormat::Markdown,
    image_mode: ImageMode::Placeholder,
    extract_links: true,
    ..Default::default()
};
let result = LiteParse::new(config).parse("document.pdf").await?;
println!("{}", result.text); // rendered Markdown

# macOS
brew install --cask libreoffice

# Ubuntu/Debian
apt-get install libreoffice

# Windows
choco install libreoffice-fresh

lit parse report.docx
lit parse slides.pptx --format json
lit parse spreadsheet.xlsx -o output.txt
lit parse scan.png

lit batch-parse ./documents ./output --recursive

lit parse document.pdf

lit parse document.pdf --ocr-language fra    # French
lit parse document.pdf --ocr-language deu    # German
lit parse document.pdf --ocr-language jpn    # Japanese

# Via environment variable
export TESSDATA_PREFIX=/path/to/tessdata
lit parse document.pdf --ocr-language eng

# Or via CLI flag
lit parse document.pdf --tessdata-path /path/to/tessdata

Error opening data file tessdata/eng.traineddata
Please make sure the TESSDATA_PREFIX environment variable is set to your "tessdata" directory.
Failed loading language 'eng'

lit parse document.pdf --no-ocr

# Start the EasyOCR server (requires Python)
git clone https://github.com/run-llama/liteparse.git
cd liteparse/ocr/easyocr
pip install -r requirements.txt
python server.py

# Parse with EasyOCR in another terminal
lit parse document.pdf --ocr-server-url http://localhost:8828/ocr

# Start the PaddleOCR server (requires Python)
git clone https://github.com/run-llama/liteparse.git
cd liteparse/ocr/paddleocr
pip install -r requirements.txt
python server.py

# Parse with PaddleOCR in another terminal
lit parse document.pdf --ocr-server-url http://localhost:8828/ocr

lit parse document.pdf \
  --ocr-server-url https://ocr.internal/ocr \
  --ocr-server-header "Authorization: Bearer $TOKEN" \
  --ocr-server-header "X-Tenant: acme"

lit parse document.pdf --num-workers 8

POST /ocr
Content-Type: multipart/form-data

{
  "results": [
    {
      "text": "recognized text",
      "bbox": [12, 40, 220, 62],
      "confidence": 0.95
    }
  ]
}

# Quick test with curl
curl -X POST http://localhost:8828/ocr \
  -F "[email protected]" \
  -F "language=en" | jq .

# Use with LiteParse
lit parse document.pdf --ocr-server-url http://localhost:8828/ocr

# Parse a remote PDF
curl -sL https://example.com/report.pdf | lit parse -

# With options
curl -sL https://example.com/report.pdf | lit parse --no-ocr --format json -

# Save to a file
curl -sL https://example.com/report.pdf | lit parse -o report.txt -

import { LiteParse } from "@llamaindex/liteparse";

const response = await fetch("https://example.com/report.pdf");
const buffer = Buffer.from(await response.arrayBuffer());

const parser = new LiteParse({ ocrEnabled: false });
const result = await parser.parse(buffer);
console.log(result.text);

git clone https://github.com/run-llama/liteparse-server
cd liteparse-server

bun run start-slim:bun
# or with Node
npm run start-slim:node

docker pull ghcr.io/run-llama/liteparse-server:main

docker run -p 5000:5000 ghcr.io/run-llama/liteparse-server:main

# Build the image
docker build -f slim.Dockerfile -t liteparse-server-slim .

# Run exposing port 5000
docker run -p 5000:5000 liteparse-server-slim

{
  "index": 0,
  "mimetype": "image/png",
  "data": "<base64>",
  "page_number": 1,
  "height": 1056,
  "width": 816
}

curl -X POST http://localhost:5000/parse \
  -F "file=@path/to/document.pdf"

curl -X POST "http://localhost:5000/parse?text=true" \
  -F "file=@path/to/document.pdf"

curl -X POST http://localhost:5000/parse \
  -F "file=@path/to/document.pdf" \
  -F 'config={"ocrEnabled":true}'

curl -X POST "http://localhost:5000/screenshots?pages=1,2,3" \
  -F "file=@path/to/document.pdf"

lit parse document.pdf --format json

{
  "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
        }
      ]
    }
  ]
}

import { LiteParse, searchItems } from "@llamaindex/liteparse";

const parser = new LiteParse({ outputFormat: "json" });
const result = await parser.parse("report.pdf");

for (const page of result.pages) {
  const matches = searchItems(page.textItems, { phrase: "0°C to 70°C" });
  for (const match of matches) {
    console.log(`Found "${match.text}" at (${match.x}, ${match.y}) ${match.width}×${match.height}`);
  }
}

from liteparse import LiteParse, search_items

parser = LiteParse()
result = parser.parse("report.pdf")

for page in result.pages:
    matches = search_items(page.text_items, "0°C to 70°C")
    for match in matches:
        print(f'Found "{match.text}" at ({match.x}, {match.y}) {match.width}×{match.height}')

const scaleFactor = dpi / 72; // PDF points -> pixels at your chosen DPI

function itemToPixels(item, dpi = 150) {
  const scale = dpi / 72;
  return {
    x: item.x * scale,
    y: item.y * scale,
    width: item.width * scale,
    height: item.height * scale,
  };
}

/* Detailed source-code truncated for AI context efficiency. */

lit parse document.pdf --format json -o result.json

lit screenshot document.pdf -o ./screenshots