A fast, helpful, and open-source document parser
add to bindings
Logan Markewich4eca456ef062
diff --git a/crates/liteparse-napi/src/lib.rs b/crates/liteparse-napi/src/lib.rsindex 22d8cfd..cb87613 100644--- a/crates/liteparse-napi/src/lib.rs+++ b/crates/liteparse-napi/src/lib.rs@@ -3,7 +3,10 @@ use napi_derive::napi;mod types;-use types::{JsLiteParseConfig, JsPageInput, JsParseResult, JsScreenshotResult, JsTextItem};+use types::{+ JsLiteParseConfig, JsPageComplexityStats, JsPageInput, JsParseResult, JsScreenshotResult,+ JsTextItem,+};/// Main LiteParse parser class.#[napi]@@ -59,6 +62,31 @@ impl LiteParse {Ok(JsParseResult::from_rust(&result, &self.config))}+ /// Determine per-page complexity. Returns one entry per parsed page with+ /// signals (text coverage, images, garbled text, vector area) and a+ /// `needsOcr` verdict — a cheap pre-OCR check to decide whether a document+ /// needs advanced parsing. Accepts a file path (string) or raw PDF bytes.+ #[napi]+ pub async fn is_complex(+ &self,+ input: Either<String, Buffer>,+ ) -> Result<Vec<JsPageComplexityStats>> {+ use liteparse::types::PdfInput;++ let pdf_input = match input {+ Either::A(path) => PdfInput::Path(path),+ Either::B(buf) => PdfInput::Bytes(buf.to_vec()),+ };++ let stats = self+ .inner+ .is_complex(pdf_input)+ .await+ .map_err(|e| Error::from_reason(e.to_string()))?;++ Ok(stats.iter().map(JsPageComplexityStats::from_rust).collect())+ }+/// Take screenshots of document pages. Returns PNG image buffers.////// Non-PDF files are automatically converted to PDF before rendering whendiff --git a/crates/liteparse-napi/src/types.rs b/crates/liteparse-napi/src/types.rsindex aae2fd8..cedf048 100644--- a/crates/liteparse-napi/src/types.rs+++ b/crates/liteparse-napi/src/types.rs@@ -358,6 +358,40 @@ pub struct JsScreenshotResult {pub image_buffer: napi::bindgen_prelude::Buffer,}+#[napi(object)]+#[derive(Clone)]+pub struct JsPageComplexityStats {+ pub page_number: u32,+ pub text_length: u32,+ pub text_coverage: f64,+ pub has_substantial_images: bool,+ pub image_block_count: u32,+ pub image_coverage: f64,+ pub largest_image_coverage: f64,+ pub uncovered_vector_area: Option<f64>,+ pub is_garbled: bool,+ pub page_area: f64,+ pub needs_ocr: bool,+}++impl JsPageComplexityStats {+ pub fn from_rust(stats: &liteparse::ocr_merge::PageComplexityStats) -> Self {+ Self {+ page_number: stats.page_number as u32,+ text_length: stats.text_length as u32,+ text_coverage: stats.text_coverage as f64,+ has_substantial_images: stats.has_substantial_images,+ image_block_count: stats.image_block_count as u32,+ image_coverage: stats.image_coverage as f64,+ largest_image_coverage: stats.largest_image_coverage as f64,+ uncovered_vector_area: stats.uncovered_vector_area.map(|v| v as f64),+ is_garbled: stats.is_garbled,+ page_area: stats.page_area as f64,+ needs_ocr: stats.needs_ocr,+ }+ }+}+impl JsParseResult {pub fn from_rust(result: &ParseResult, _config: &LiteParseConfig) -> Self {Self {diff --git a/crates/liteparse-python/src/lib.rs b/crates/liteparse-python/src/lib.rsindex 8341da7..26985c3 100644--- a/crates/liteparse-python/src/lib.rs+++ b/crates/liteparse-python/src/lib.rs@@ -234,6 +234,61 @@ impl PyScreenshotResult {}}+#[pyclass(frozen, from_py_object)]+#[derive(Clone)]+struct PyPageComplexityStats {+ #[pyo3(get)]+ page_number: usize,+ #[pyo3(get)]+ text_length: usize,+ #[pyo3(get)]+ text_coverage: f32,+ #[pyo3(get)]+ has_substantial_images: bool,+ #[pyo3(get)]+ image_block_count: usize,+ #[pyo3(get)]+ image_coverage: f32,+ #[pyo3(get)]+ largest_image_coverage: f32,+ #[pyo3(get)]+ uncovered_vector_area: Option<f32>,+ #[pyo3(get)]+ is_garbled: bool,+ #[pyo3(get)]+ page_area: f32,+ #[pyo3(get)]+ needs_ocr: bool,+}++#[pymethods]+impl PyPageComplexityStats {+ fn __repr__(&self) -> String {+ format!(+ "PageComplexityStats(page_number={}, text_length={}, text_coverage={:.2}, needs_ocr={})",+ self.page_number, self.text_length, self.text_coverage, self.needs_ocr+ )+ }+}++impl PyPageComplexityStats {+ fn from_rust(stats: &liteparse::ocr_merge::PageComplexityStats) -> Self {+ Self {+ page_number: stats.page_number,+ text_length: stats.text_length,+ text_coverage: stats.text_coverage,+ has_substantial_images: stats.has_substantial_images,+ image_block_count: stats.image_block_count,+ image_coverage: stats.image_coverage,+ largest_image_coverage: stats.largest_image_coverage,+ uncovered_vector_area: stats.uncovered_vector_area,+ is_garbled: stats.is_garbled,+ page_area: stats.page_area,+ needs_ocr: stats.needs_ocr,+ }+ }+}+// ---------------------------------------------------------------------------// Config// ---------------------------------------------------------------------------@@ -440,6 +495,30 @@ impl LiteParse {Ok(PyParseResult::from_rust(result))}+ /// Determine per-page complexity for a document at the given path. Returns+ /// a list of PageComplexityStats — a cheap pre-OCR check with per-page+ /// signals and a `needs_ocr` verdict.+ fn is_complex(&self, py: Python<'_>, input: String) -> PyResult<Vec<PyPageComplexityStats>> {+ let pdf_input = PdfInput::Path(input);+ let stats = py+ .detach(|| self.runtime.block_on(self.inner.is_complex(pdf_input)))+ .map_err(|e| PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(e.to_string()))?;+ Ok(stats.iter().map(PyPageComplexityStats::from_rust).collect())+ }++ /// Determine per-page complexity for a document from raw bytes.+ fn is_complex_bytes(+ &self,+ py: Python<'_>,+ data: Vec<u8>,+ ) -> PyResult<Vec<PyPageComplexityStats>> {+ let pdf_input = PdfInput::Bytes(data);+ let stats = py+ .detach(|| self.runtime.block_on(self.inner.is_complex(pdf_input)))+ .map_err(|e| PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(e.to_string()))?;+ Ok(stats.iter().map(PyPageComplexityStats::from_rust).collect())+ }+/// Take screenshots of document pages. Returns a list of ScreenshotResult.////// Non-PDF files are automatically converted to PDF before rendering when@@ -517,6 +596,7 @@ fn _liteparse(m: &Bound<'_, PyModule>) -> PyResult<()> {m.add_class::<PyParsedPage>()?;m.add_class::<PyTextItem>()?;m.add_class::<PyScreenshotResult>()?;+ m.add_class::<PyPageComplexityStats>()?;m.add_function(wrap_pyfunction!(run_cli, m)?)?;m.add_function(wrap_pyfunction!(search_items, m)?)?;Ok(())diff --git a/crates/liteparse-wasm/src/lib.rs b/crates/liteparse-wasm/src/lib.rsindex 2176725..fc26dca 100644--- a/crates/liteparse-wasm/src/lib.rs+++ b/crates/liteparse-wasm/src/lib.rs@@ -395,6 +395,58 @@ impl LiteParse {serde_wasm_bindgen::to_value(&js_result).map_err(|e| JsError::new(&format!("serialize result failed: {}", e)))}++ /// Determine per-page complexity for the given PDF bytes. Returns+ /// `Promise<PageComplexityStats[]>` — a cheap pre-OCR check with per-page+ /// signals and a `needsOcr` verdict.+ #[wasm_bindgen(js_name = isComplex)]+ pub async fn is_complex(&self, data: Vec<u8>) -> Result<JsValue, JsError> {+ let stats = self+ .inner+ .is_complex(PdfInput::Bytes(data))+ .await+ .map_err(|e| JsError::new(&format!("is_complex failed: {}", e)))?;++ let js_stats: Vec<JsPageComplexityStats> =+ stats.iter().map(JsPageComplexityStats::from_rust).collect();++ serde_wasm_bindgen::to_value(&js_stats)+ .map_err(|e| JsError::new(&format!("serialize result failed: {}", e)))+ }+}++#[derive(Serialize)]+#[serde(rename_all = "camelCase")]+struct JsPageComplexityStats {+ page_number: usize,+ text_length: usize,+ text_coverage: f32,+ has_substantial_images: bool,+ image_block_count: usize,+ image_coverage: f32,+ largest_image_coverage: f32,+ uncovered_vector_area: Option<f32>,+ is_garbled: bool,+ page_area: f32,+ needs_ocr: bool,+}++impl JsPageComplexityStats {+ fn from_rust(stats: &liteparse::ocr_merge::PageComplexityStats) -> Self {+ Self {+ page_number: stats.page_number,+ text_length: stats.text_length,+ text_coverage: stats.text_coverage,+ has_substantial_images: stats.has_substantial_images,+ image_block_count: stats.image_block_count,+ image_coverage: stats.image_coverage,+ largest_image_coverage: stats.largest_image_coverage,+ uncovered_vector_area: stats.uncovered_vector_area,+ is_garbled: stats.is_garbled,+ page_area: stats.page_area,+ needs_ocr: stats.needs_ocr,+ }+ }}// ---------------------------------------------------------------------------diff --git a/packages/node/src/cli.ts b/packages/node/src/cli.tsindex 89a4926..91b5f58 100644--- a/packages/node/src/cli.ts+++ b/packages/node/src/cli.ts@@ -141,6 +141,76 @@ program}});+program+ .command("is-complex")+ .description(+ "Check if a document is 'complex' enough to require OCR or other advanced parsing",+ )+ .argument("<file>", "Path to the document file")+ .option("--json", "Output the result as JSON")+ .option("--max-pages <n>", "Max pages to parse", parseInt)+ .option(+ "--target-pages <pages>",+ 'Pages to check (e.g., "1-5,10,15-20")',+ )+ .option("--password <password>", "Password for encrypted documents")+ .option("-q, --quiet", "Suppress progress output")+ .action(async (file: string, opts: Record<string, unknown>) => {+ try {+ const config: Partial<LiteParseConfig> = {};+ if (opts.maxPages) config.maxPages = opts.maxPages as number;+ if (opts.targetPages) config.targetPages = opts.targetPages as string;+ if (opts.password) config.password = opts.password as string;+ if (opts.quiet) config.quiet = true;++ const parser = new LiteParse(config);+ const stats = await parser.isComplex(file);++ const complexPages = stats.filter((s) => s.needsOcr).length;++ if (opts.json) {+ process.stdout.write(JSON.stringify(stats));+ process.stdout.write("\n");+ } else {+ const verdict = complexPages > 0 ? "COMPLEX" : "SIMPLE";+ console.log(+ `${verdict} — ${complexPages}/${stats.length} page(s) need OCR`,+ );+ console.log(+ ["page", "text", "cov", "images", "garbled", "vector", "ocr"].join(+ "\t",+ ),+ );+ for (const s of stats) {+ const vector =+ s.uncoveredVectorArea !== undefined+ ? s.uncoveredVectorArea.toFixed(0)+ : "-";+ console.log(+ [+ s.pageNumber,+ s.textLength,+ s.textCoverage.toFixed(2),+ s.hasSubstantialImages ? "yes" : "no",+ s.isGarbled ? "yes" : "no",+ vector,+ s.needsOcr ? "yes" : "no",+ ].join("\t"),+ );+ }+ }++ // Exit non-zero when any page needs OCR, so the command is usable as a+ // shell predicate (e.g. `is-complex doc.pdf && parse --no-ocr`).+ if (complexPages > 0) process.exit(1);+ } catch (err) {+ console.error(+ `Error: ${err instanceof Error ? err.message : String(err)}`,+ );+ process.exit(1);+ }+ });+program.command("screenshot").description("Generate screenshots of document pages")diff --git a/packages/node/src/lib.ts b/packages/node/src/lib.tsindex 593cfed..2af2bad 100644--- a/packages/node/src/lib.ts+++ b/packages/node/src/lib.ts@@ -7,6 +7,7 @@ import {type NativePageInput,type NativeTextItem,type NativeExtractedImage,+ type NativePageComplexityStats,} from "./native.js";// ---------------------------------------------------------------------------@@ -119,6 +120,32 @@ export interface ScreenshotResult {imageBuffer: Buffer;}+/**+ * Per-page complexity signals from {@link LiteParse.isComplex}, used to decide+ * whether a document needs OCR or other advanced parsing.+ */+export interface PageComplexityStats {+ pageNumber: number;+ textLength: number;+ /** Fraction of the page area covered by native text (0–1). */+ textCoverage: number;+ hasSubstantialImages: boolean;+ imageBlockCount: number;+ /** Summed image-bbox area over page area, clamped to 1. */+ imageCoverage: number;+ /** Largest single image's area over page area, clamped to 1. */+ largestImageCoverage: number;+ /**+ * Filled vector-outline area not covered by native text, in pt². `undefined`+ * when a cheaper signal already decided the page, so this walk was skipped.+ */+ uncoveredVectorArea?: number;+ isGarbled: boolean;+ pageArea: number;+ /** Verdict: whether this page should be sent through OCR. */+ needsOcr: boolean;+}+// ---------------------------------------------------------------------------// LiteParse class// ---------------------------------------------------------------------------@@ -203,6 +230,31 @@ export class LiteParse {};}+ /**+ * Determine per-page complexity without running a full parse. Returns one+ * entry per page with signals and a `needsOcr` verdict — a cheap pre-OCR+ * check to decide whether a document needs advanced parsing.+ */+ async isComplex(input: LiteParseInput): Promise<PageComplexityStats[]> {+ const nativeInput =+ typeof input === "string" ? input : Buffer.from(input);+ const stats: NativePageComplexityStats[] =+ await this._native.isComplex(nativeInput);+ return stats.map((s) => ({+ pageNumber: s.pageNumber,+ textLength: s.textLength,+ textCoverage: s.textCoverage,+ hasSubstantialImages: s.hasSubstantialImages,+ imageBlockCount: s.imageBlockCount,+ imageCoverage: s.imageCoverage,+ largestImageCoverage: s.largestImageCoverage,+ uncoveredVectorArea: s.uncoveredVectorArea ?? undefined,+ isGarbled: s.isGarbled,+ pageArea: s.pageArea,+ needsOcr: s.needsOcr,+ }));+ }+async screenshot(input: LiteParseInput,pageNumbers?: number[],diff --git a/packages/node/src/native.ts b/packages/node/src/native.tsindex 7808617..c692838 100644--- a/packages/node/src/native.ts+++ b/packages/node/src/native.ts@@ -102,9 +102,24 @@ export interface NativeScreenshotResult {imageBuffer: Buffer;}+export interface NativePageComplexityStats {+ pageNumber: number;+ textLength: number;+ textCoverage: number;+ hasSubstantialImages: boolean;+ imageBlockCount: number;+ imageCoverage: number;+ largestImageCoverage: number;+ uncoveredVectorArea?: number;+ isGarbled: boolean;+ pageArea: number;+ needsOcr: boolean;+}+export interface LiteParseNative {parse(input: string | Buffer): Promise<NativeParseResult>;parsePages(pages: NativePageInput[]): NativeParseResult;+ isComplex(input: string | Buffer): Promise<NativePageComplexityStats[]>;screenshot(input: string | Buffer,pageNumbers?: number[] | null,diff --git a/packages/python/liteparse/__init__.py b/packages/python/liteparse/__init__.pyindex 5b9a6ef..eee674a 100644--- a/packages/python/liteparse/__init__.py+++ b/packages/python/liteparse/__init__.py@@ -2,6 +2,7 @@ from .parser import LiteParse, search_itemsfrom .types import (ExtractedImage,LiteParseConfig,+ PageComplexityStats,ParseResult,ParsedPage,TextItem,@@ -17,6 +18,7 @@ __all__ = ["ParsedPage","TextItem","ScreenshotResult",+ "PageComplexityStats","ExtractedImage","ParseError","search_items",diff --git a/packages/python/liteparse/parser.py b/packages/python/liteparse/parser.pyindex 5500c0a..6fc7552 100644--- a/packages/python/liteparse/parser.py+++ b/packages/python/liteparse/parser.py@@ -9,6 +9,7 @@ from liteparse._liteparse import search_items as _native_search_itemsfrom .types import (ExtractedImage,LiteParseConfig,+ PageComplexityStats,ParsedPage,ParseError,ParseResult,@@ -177,6 +178,56 @@ class LiteParse:except Exception as e:raise ParseError(str(e)) from e+ def is_complex(+ self,+ file_data: Union[str, Path, bytes],+ ) -> List[PageComplexityStats]:+ """+ Determine per-page complexity without running a full parse.++ Returns one entry per page with signals (text coverage, images, garbled+ text, vector area) and a ``needs_ocr`` verdict — a cheap pre-OCR check to+ decide whether a document needs advanced parsing.++ Args:+ file_data: Path to the document file, or raw PDF bytes.++ Returns:+ List of PageComplexityStats, one per page.++ Raises:+ ParseError: If the check fails.+ FileNotFoundError: If the file doesn't exist.+ """+ try:+ if isinstance(file_data, bytes):+ native_stats = self._native.is_complex_bytes(file_data)+ else:+ file_path = Path(file_data)+ if not file_path.exists():+ raise FileNotFoundError(f"File not found: {file_path}")+ native_stats = self._native.is_complex(str(file_path.absolute()))+ return [+ PageComplexityStats(+ page_number=s.page_number,+ text_length=s.text_length,+ text_coverage=s.text_coverage,+ has_substantial_images=s.has_substantial_images,+ image_block_count=s.image_block_count,+ image_coverage=s.image_coverage,+ largest_image_coverage=s.largest_image_coverage,+ uncovered_vector_area=s.uncovered_vector_area,+ is_garbled=s.is_garbled,+ page_area=s.page_area,+ needs_ocr=s.needs_ocr,+ )+ for s in native_stats+ ]+ except FileNotFoundError:+ raise+ except Exception as e:+ raise ParseError(str(e)) from e+def screenshot(self,file_path: Union[str, Path],diff --git a/packages/python/liteparse/types.py b/packages/python/liteparse/types.pyindex d562df0..d75cede 100644--- a/packages/python/liteparse/types.py+++ b/packages/python/liteparse/types.py@@ -71,6 +71,22 @@ class ScreenshotResult:image_bytes: bytes+@dataclass+class PageComplexityStats:+ """Per-page complexity signals used to decide whether a document needs OCR."""+ page_number: int+ text_length: int+ text_coverage: float+ has_substantial_images: bool+ image_block_count: int+ image_coverage: float+ largest_image_coverage: float+ uncovered_vector_area: Optional[float]+ is_garbled: bool+ page_area: float+ needs_ocr: bool++@dataclassclass LiteParseConfig:"""Resolved parser configuration."""