Skip to content

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.rs
index 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 when
diff --git a/crates/liteparse-napi/src/types.rs b/crates/liteparse-napi/src/types.rs
index 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.rs
index 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.rs
index 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.ts
index 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.ts
index 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.ts
index 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__.py
index 5b9a6ef..eee674a 100644
--- a/packages/python/liteparse/__init__.py
+++ b/packages/python/liteparse/__init__.py
@@ -2,6 +2,7 @@ from .parser import LiteParse, search_items
from .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.py
index 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_items
from .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.py
index 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
+
+
@dataclass
class LiteParseConfig:
"""Resolved parser configuration."""