Liteparse

LiteParse — Local Document Parsing

Overview

LiteParse is a fast, open-source document parser (Rust core, Python/Node bindings) focused on local, layout-aware text extraction with bounding boxes. It does not produce Markdown and does not call cloud LLMs. Outputs are plain text (layout-preserved) or structured JSON with per-page text_items (position, font metadata, optional confidence).

Version note: Examples target liteparse 2.0.0 (PyPI, May 2026). The upstream V1 branch is legacy; this skill documents V2 / main only.

For parser selection vs MarkItDown, the pdf skill, or LlamaParse, see references/choosing_a_parser.md.

When to Use This Skill

Use LiteParse when you need:

• Fast local parsing of PDFs or converted Office/image files without cloud dependencies
• Spatial text with bounding boxes for layout-aware RAG, citation grounding, or figure/table region logic
• OCR on scanned PDFs or images (bundled Tesseract, or a user-run HTTP OCR server)
• Page screenshots (PNG) for multimodal agents that must see charts, figures, or handwriting
• Batch ingestion of literature folders, supplementary PDFs, or protocol libraries
• Page subsets or password-protected PDFs

When Not to Use

Installation

uv pip install "liteparse==2.0.0"

This installs the Python bindings and the `lit` CLI. Verify:

lit --help
python -c "import liteparse; print(liteparse.__version__)"

Optional system tools (for non-PDF inputs):

• LibreOffice — Word, Excel, PowerPoint, OpenDocument, CSV/TSV
• ImageMagick — PNG, JPEG, TIFF, WebP, SVG, etc.

Install commands are in references/ocr_and_formats.md.

Node.js / TypeScript (optional): npm i @llamaindex/liteparse — see references/api_reference.md.

---

Quick Start

Python

from liteparse import LiteParse

parser = LiteParse(quiet=True)
result = parser.parse("paper.pdf")
print(result.text)

for page in result.pages:
    print(f"Page {page.page_num}: {len(page.text_items)} items")

CLI

# Layout-preserved text (default)
lit parse paper.pdf

# Structured JSON with bounding boxes
lit parse paper.pdf --format json -o paper.json

# Disable OCR on text-native PDFs (faster)
lit parse paper.pdf --no-ocr

---

Core Workflows

1. Parse to layout-preserved text

Best for quick full-document text or feeding chunkers that do not need coordinates.

parser = LiteParse(ocr_enabled=True, quiet=True)
result = parser.parse("document.pdf")
full_text = result.text

lit parse document.pdf -o output.txt

2. Parse to structured JSON (bounding boxes)

Use when building layout-aware RAG, highlighting source regions, or joining text with screenshots.

import json
from liteparse import LiteParse

parser = LiteParse(output_format="json", quiet=True)
result = parser.parse("document.pdf")

# Programmatic access
for page in result.pages:
    for item in page.text_items:
        bbox = (item.x, item.y, item.width, item.height)
        # item.text, item.confidence, item.font_name, item.font_size

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

JSON field layout: references/output_formats.md.

3. Parse specific pages

parser = LiteParse(target_pages="1-5,10,15-20", quiet=True)
result = parser.parse("long_paper.pdf")

lit parse long_paper.pdf --target-pages "1-5,10"

4. Parse from bytes or stdin

Useful for uploads, S3 downloads, or piping remote PDFs.

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

curl -sL https://example.com/report.pdf | lit parse -

5. Page screenshots for multimodal agents

Screenshots capture visual content that text extraction alone misses (figures, complex tables, handwriting).

from pathlib import Path

parser = LiteParse(dpi=150, quiet=True)
shots = parser.screenshot("document.pdf", page_numbers=[1, 2, 3])
out = Path("screenshots")
out.mkdir(exist_ok=True)
for s in shots:
    (out / f"page_{s.page_num}.png").write_bytes(s.image_bytes)

lit screenshot document.pdf --target-pages "1,3,5" -o ./screenshots
lit screenshot document.pdf --dpi 300 -o ./screenshots

Combine JSON parse + screenshots when an agent needs both coordinates and pixels for the same pages.

6. Batch-parse a directory

For large corpora, prefer the CLI (parallel OCR workers) or the bundled script.

lit batch-parse ./papers ./parsed --format json --recursive
lit batch-parse ./papers ./parsed --extension .pdf --no-ocr

python scripts/batch_parse_dir.py ./papers ./parsed --format json --recursive

See scripts/batch_parse_dir.py for a Python batch wrapper without network calls.

7. OCR configuration

OCR is on by default. Tesseract is bundled; no extra install for basic English OCR.

parser = LiteParse(
    ocr_enabled=True,
    ocr_language="eng",       # Tesseract codes: fra, deu, etc.
    num_workers=4,            # parallel OCR (default: CPU cores - 1)
    dpi=150,                  # higher DPI → better OCR, slower
)

lit parse scan.pdf --ocr-language fra
lit parse scan.pdf --no-ocr
lit parse scan.pdf --ocr-server-url http://localhost:8080/ocr

Offline / air-gapped: set TESSDATA_PREFIX to a directory of .traineddata files, or pass --tessdata-path. Details: references/ocr_and_formats.md.

8. Encrypted PDFs

parser = LiteParse(password="secret", quiet=True)
result = parser.parse("protected.pdf")

lit parse protected.pdf --password secret

9. Search text items by phrase

Merge adjacent items and return combined bounding boxes for a phrase (e.g. section titles).

from liteparse import search_items

page = result.get_page(1)
matches = search_items(page.text_items, "Materials and Methods", case_sensitive=False)

---

Multi-Format Inputs

Files are converted to PDF internally, then parsed. If conversion tools are missing, parsing fails with an actionable error — install the dependency and retry.

---

Performance Tips

• `--no-ocr` on born-digital PDFs — largest speedup
• `target_pages` — parse only methods/supplement sections
• `num_workers` — scale OCR across CPU cores
• `max_pages` — cap very large files (default 1000)
• `lit batch-parse` — directory-scale jobs with --recursive and --extension
• Lower `dpi` (e.g. 100) when OCR quality is already sufficient

---

Reference Files

---

Troubleshooting

---

Resources

• GitHub: https://github.com/run-llama/liteparse
• Docs: https://developers.llamaindex.ai/liteparse/
• PyPI: https://pypi.org/project/liteparse/2.0.0/
• npm: https://www.npmjs.com/package/@llamaindex/liteparse
• OCR API spec: https://github.com/run-llama/liteparse/blob/main/OCR_API_SPEC.md

LiteParse API Reference

Targets liteparse 2.0.0 (Python) and @llamaindex/liteparse (Node). Rust crate: liteparse = "2".

Python: LiteParse

from liteparse import LiteParse, ParseResult, ParsedPage, TextItem, ScreenshotResult, search_items

Constructor options

parse(file_data)

Input: file path (str / Path) or raw PDF bytes (bytes).

Returns: ParseResult

@dataclass
class ParseResult:
    pages: List[ParsedPage]
    text: str              # full document text (layout-preserved)

    @property
    def num_pages(self) -> int

    def get_page(self, page_num: int) -> Optional[ParsedPage]  # 1-indexed

@dataclass
class ParsedPage:
    page_num: int
    width: float
    height: float
    text: str
    text_items: List[TextItem]

@dataclass
class TextItem:
    text: str
    x: float
    y: float
    width: float
    height: float
    font_name: Optional[str]
    font_size: Optional[float]
    confidence: Optional[float]   # 0.0–1.0 when from OCR

Raises: FileNotFoundError, ParseError

screenshot(file_path, *, page_numbers=None)

Input: path to document (PDF or convertible format).

Returns: List[ScreenshotResult] with PNG bytes.

@dataclass
class ScreenshotResult:
    page_num: int
    width: int
    height: int
    image_bytes: bytes

Non-PDF formats are converted when LibreOffice/ImageMagick are installed.

get_config()

Returns resolved LiteParseConfig dataclass.

search_items(items, phrase, *, case_sensitive=False)

Search a list of TextItem for a phrase that may span multiple items. Returns merged TextItem objects with combined bounding boxes.

from liteparse import search_items

matches = search_items(page.text_items, "Figure 1", case_sensitive=False)

---

TypeScript / Node.js

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

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

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

Constructor options (camelCase)

Parse from bytes

import { readFile } from 'fs/promises';

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

Screenshots

const screenshots = parser.screenshot('document.pdf', [1, 2, 3]);
for (const s of screenshots) {
  // s.pageNum, s.width, s.height, s.imageBuffer (PNG)
}

Install: npm i @llamaindex/liteparse (includes lit CLI).

Browser/edge: @llamaindex/liteparse-wasm — see upstream WASM README.

---

Rust (library)

use liteparse::{LiteParse, LiteParseConfig};

let parser = LiteParse::new(LiteParseConfig::default());
let result = parser.parse("document.pdf").await?;

Custom OCR: implement OcrEngine trait and .with_ocr_engine(Arc::new(engine)).

CLI: cargo install liteparse

Choosing a Document Parser

Use this guide to pick the right tool in the scientific-agent-skills repo (or LlamaParse for cloud escalation).

flowchart TD
  start[User has a document task]
  start --> q1{Need PDF merge split forms or encryption utilities?}
  q1 -->|yes| pdfSkill[pdf skill]
  q1 -->|no| q2{Need Markdown audio video EPUB or Azure table extraction?}
  q2 -->|yes| markitdown[markitdown skill]
  q2 -->|no| q3{Need bounding boxes fast local parse or page PNGs for agents?}
  q3 -->|yes| liteparse[liteparse skill]
  q3 -->|no| q4{Complex tables handwriting or production cloud pipeline?}
  q4 -->|yes| llamaparse[LlamaParse cloud]
  q4 -->|no| liteparse

Comparison table

Decision rules

Choose LiteParse when

• You need coordinates for citations, highlighting, or layout-aware chunking.
• You want fast local parsing without API keys.
• You are building multimodal workflows (parse JSON + page screenshots).
• You are batch-processing folders of PDFs for a literature review pipeline.
• Scanned PDFs need OCR with optional custom HTTP OCR backends.

Choose MarkItDown when

• The downstream step expects Markdown (RAG, summarization, notebook ingestion).
• Inputs include HTML, EPUB, audio, YouTube, or you want Azure Document Intelligence for tables.
• You do not need per-span bounding boxes.

Choose the pdf skill when

• The task is PDF file operations: merge, split, rotate, watermark, fill forms, encrypt/decrypt.
• You only need simple text extraction without spatial layout or OCR orchestration.

Choose LlamaParse when

• Documents have dense tables, multi-column layouts, charts, or handwriting beyond what local parsers handle well.
• You are building a production document pipeline and accept cloud dependency and signup.

Link: https://docs.cloud.llamaindex.ai/llamaparse/overview

Combining tools

Common pipelines:

1. LiteParse → chunk + embed — JSON/text for vector store; bboxes for UI highlights. 2. LiteParse screenshots + vision model — figures and tables; text JSON for search. 3. LiteParse text → MarkItDown-style post-processing — only if you must have Markdown; otherwise use LiteParse text directly. 4. pdf skill merge → LiteParse parse — assemble supplementary PDFs, then extract.

Avoid running LiteParse and MarkItDown on the same file unless you have distinct consumers (coordinates vs Markdown).

LiteParse CLI Reference (lit)

The `lit` command ships with liteparse (Python), @llamaindex/liteparse (npm), and cargo install liteparse (Rust). Behavior is the same across installs.

lit --help
lit parse --help
lit batch-parse --help
lit screenshot --help

---

lit parse

Parse a single file or stdin.

lit parse [OPTIONS] <file>

Examples

lit parse document.pdf
lit parse document.pdf --format json -o output.json
lit parse document.pdf --target-pages "1-5,10" --no-ocr
lit parse scan.pdf --ocr-language fra --dpi 200
lit parse protected.pdf --password secret
curl -sL https://example.com/paper.pdf | lit parse - -o paper.txt

---

lit batch-parse

Parse every supported file in a directory.

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

Examples

lit batch-parse ./papers ./parsed
lit batch-parse ./papers ./parsed --format json --recursive
lit batch-parse ./pdfs ./out --extension .pdf --no-ocr

Output files mirror input basenames with .txt or .json extension.

---

lit screenshot

Render pages to PNG files.

lit screenshot [OPTIONS] <file>

Examples

lit screenshot document.pdf -o ./screenshots
lit screenshot document.pdf --target-pages "1,3,5" --dpi 300

---

Environment variables

OCR and Supported Input Formats

Built-in OCR (Tesseract)

• Default: OCR enabled on parse.
• Engine: Tesseract bundled with the library (zero extra setup for typical English PDFs).
• Disable when PDFs have selectable text: --no-ocr or ocr_enabled=False.

lit parse document.pdf
lit parse document.pdf --ocr-language fra
lit parse document.pdf --no-ocr

parser = LiteParse(ocr_enabled=True, ocr_language="eng", num_workers=4)

Language codes

Use Tesseract codes (not ISO alone): eng, fra, deu, spa, chi_sim, etc. Map HTTP OCR language=en separately (see below).

Offline / air-gapped environments

Pre-download .traineddata files, then either:

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

or:

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

---

HTTP OCR servers (optional)

For higher accuracy or GPU-backed OCR, run a server implementing the LiteParse OCR API and point LiteParse at it:

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

parser = LiteParse(ocr_server_url="http://localhost:8080/ocr")

API contract (summary)

• POST {base_url}/ocr (typically http://host:8080/ocr)
• Content-Type: multipart/form-data
• Fields: file (image bytes, required), language (optional, ISO 639-1, default en)
• Response JSON:

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

• Origin top-left; bbox axis-aligned in pixels.
• Full spec: https://github.com/run-llama/liteparse/blob/main/OCR_API_SPEC.md

Reference server implementations (upstream repo)

• ocr/easyocr/ — EasyOCR wrapper
• ocr/paddleocr/ — PaddleOCR wrapper

You only need a server if you choose HTTP OCR; Tesseract is sufficient for many workflows.

---

Supported input formats

PDF (native)

.pdf — no conversion step.

Office documents (LibreOffice)

Requires LibreOffice installed and on PATH.

Install LibreOffice:

# macOS
brew install --cask libreoffice

# Ubuntu/Debian
sudo apt-get install libreoffice

# Windows (Chocolatey)
choco install libreoffice-fresh

On Windows, add LibreOffice program directory to PATH (often C:\Program Files\LibreOffice\program).

Images (ImageMagick)

Requires ImageMagick.

Install ImageMagick:

# macOS
brew install imagemagick

# Ubuntu/Debian
sudo apt-get install imagemagick

# Windows
choco install imagemagick.app

---

Conversion pipeline

Office / image → (LibreOffice or ImageMagick) → PDF → PDFium extract → optional OCR → grid projection → text + JSON

If conversion fails, install the missing tool and retry. Plain-text-only paths cannot be screenshot-rendered.

LiteParse Output Formats

Text output (--format text)

• CLI: layout-preserved plain text written to stdout or -o file.
• Python: ParseResult.text — full document; each ParsedPage.text — page-level text.
• Reading order follows reconstructed spatial layout (grid projection), not raw PDF content stream order.

Use text output when feeding chunkers, summarizers, or keyword search that do not need coordinates.

---

JSON output (--format json)

CLI

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

The CLI serializes the native parse result. Structure aligns with the Python object model below.

Python object model

After parser.parse(path), use result.pages and result.text. To emit JSON manually:

import json
from dataclasses import asdict

# Simple serialization pattern (adapt fields as needed)
def page_to_dict(page):
    return {
        "page_num": page.page_num,
        "width": page.width,
        "height": page.height,
        "text": page.text,
        "text_items": [
            {
                "text": item.text,
                "x": item.x,
                "y": item.y,
                "width": item.width,
                "height": item.height,
                "font_name": item.font_name,
                "font_size": item.font_size,
                "confidence": item.confidence,
            }
            for item in page.text_items
        ],
    }

payload = {
    "text": result.text,
    "pages": [page_to_dict(p) for p in result.pages],
}
json.dump(payload, open("out.json", "w"), indent=2)

Example JSON shape

{
  "text": "Full document text...\n",
  "pages": [
    {
      "page_num": 1,
      "width": 612.0,
      "height": 792.0,
      "text": "Page 1 text...",
      "text_items": [
        {
          "text": "Introduction",
          "x": 72.0,
          "y": 100.0,
          "width": 120.0,
          "height": 14.0,
          "font_name": "Times-Bold",
          "font_size": 12.0,
          "confidence": null
        },
        {
          "text": "scanned phrase",
          "x": 80.0,
          "y": 400.0,
          "width": 200.0,
          "height": 12.0,
          "font_name": null,
          "font_size": null,
          "confidence": 0.94
        }
      ]
    }
  ]
}

Exact CLI JSON keys may match upstream serialization; treat text_items geometry as authoritative for grounding.

---

Bounding box coordinate system

• Origin (0, 0) is top-left of the page.
• x increases right; y increases down.
• Each TextItem uses (x, y, width, height) — top-left corner plus size in page units (typically PDF points).
• HTTP OCR servers return [x1, y1, x2, y2]; LiteParse normalizes into x, y, width, height internally.

Convert corner box to width/height

x1, y1, x2, y2 = bbox
x, y, width, height = x1, y1, x2 - x1, y2 - y1

---

Confidence scores

• Present on OCR-derived text_items (since upstream v1.4.0).
• Range 0.0–1.0 when set; null for native PDF text extraction.
• Filter low-confidence items in downstream pipelines if needed.

---

Phrase search across items

Use search_items() when a query spans multiple text_items:

from liteparse import search_items

hits = search_items(page.text_items, "Supplementary Table 1")
for hit in hits:
    # hit.text — matched phrase
    # hit.x, hit.y, hit.width, hit.height — merged bbox

---

Layout-aware RAG patterns

1. Chunk by page — page.text or group text_items by vertical bands. 2. Ground citations — store (page_num, x, y, width, height) with each chunk. 3. Multimodal — pair JSON chunks with screenshot() PNGs for the same page_num. 4. Quality gate — drop items with confidence below threshold on OCR-heavy pages.