A fast, helpful, and open-source document parser
merge main
Logan Markewich8a7141557b31
diff --cc cli/parse.tsindex ff2a08a,5104e20..5b72400--- a/cli/parse.ts+++ b/cli/parse.ts@@@ -27,9 -28,15 +28,16 @@@ interface ParseCommandOptionspreciseBbox?: boolean;preserveSmallText?: boolean;password?: string;+ experimental?: boolean;config?: string;quiet?: boolean;+ debug?: boolean;+ debugTrace?: boolean;+ debugVisualize?: boolean;+ debugOutput?: string;+ debugTextFilter?: string[];+ debugPage?: string;+ debugRegion?: string;}interface ScreenshotCommandOptions {@@@ -83,9 -90,21 +91,22 @@@ progra.option("--no-precise-bbox", "Disable precise bounding boxes").option("--preserve-small-text", "Preserve very small text").option("--password <password>", "Password for encrypted/protected documents")+ .option("--experimental", "Use experimental Rust-based PDF engine").option("--config <file>", "Config file (JSON)").option("-q, --quiet", "Suppress progress output")+ .addOption(new Option("--debug", "Enable grid projection debug logging").hideHelp())+ .addOption(new Option("--debug-trace", "Enable detailed render decision tracing").hideHelp())+ .addOption(new Option("--debug-visualize", "Generate grid visualization PNGs").hideHelp())+ .addOption(new Option("--debug-output <path>", "Output directory for debug files").hideHelp())+ .addOption(+ new Option("--debug-text-filter <texts...>", "Filter debug output by text content").hideHelp()+ )+ .addOption(+ new Option("--debug-page <num>", "Filter debug output to specific page number").hideHelp()+ )+ .addOption(+ new Option("--debug-region <coords>", 'Filter to bounding region "x1,y1,x2,y2"').hideHelp()+ ).action(async (file: string, options: ParseCommandOptions) => {try {const quiet = options.quiet || false;@@@ -128,9 -147,27 +149,28 @@@preciseBoundingBox: options.preciseBbox !== false,preserveVerySmallText: options.preserveSmallText || false,password: options.password,+ experimental: options.experimental || false,};+ // Build debug config if any debug flags are set+ if (options.debug || options.debugTrace || options.debugVisualize) {+ let regionFilter: { x1: number; y1: number; x2: number; y2: number } | undefined;+ if (options.debugRegion) {+ const [x1, y1, x2, y2] = options.debugRegion.split(",").map(Number);+ regionFilter = { x1, y1, x2, y2 };+ }+ config.debug = {+ enabled: true,+ trace: options.debugTrace,+ visualize: options.debugVisualize,+ visualizePath: options.debugOutput ?? "./debug-output",+ outputPath: options.debugOutput ? `${options.debugOutput}/debug.log` : undefined,+ textFilter: options.debugTextFilter,+ pageFilter: options.debugPage ? parseInt(options.debugPage) : undefined,+ regionFilter,+ };+ }+// Create parserconst parser = new LiteParse(config);diff --cc src/core/parser.tsindex a711aca,f066049..2ed7cf2--- a/src/core/parser.ts+++ b/src/core/parser.ts@@@ -160,71 -157,61 +160,72 @@@ export class LiteParselog(`Loaded PDF with ${doc.numPages} pages`);- let processedPages: import("./types.js").ParsedPage[];-- if (this.config.experimental && this.pdfEngine instanceof LiteParseRsEngine) {- // Rust pipeline: extract + grid projection in one shot- processedPages = await this.pdfEngine.parseDocument(- doc,- this.config.maxPages,- this.config.targetPages- );- } else {- // TypeScript pipeline: extract, OCR, then grid projection- const pages = await this.pdfEngine.extractAllPages(- doc,- this.config.maxPages,- this.config.targetPages- );+ try {- // Extract pages- const pages = await this.pdfEngine.extractAllPages(- doc,- this.config.maxPages,- this.config.targetPages,- { extractImages: this.config.ocrEnabled }- );-- // run BEFORE grid projection- if (this.ocrEngine) {- await this.runOCR(doc, pages, log);- }++ let processedPages: import("./types.js").ParsedPage[];++++ if (this.config.experimental && this.pdfEngine instanceof LiteParseRsEngine) {++ // Rust pipeline: extract + grid projection in one shot++ processedPages = await this.pdfEngine.parseDocument(++ doc,++ this.config.maxPages,++ this.config.targetPages++ );++ } else {++ // TypeScript pipeline: extract, OCR, then grid projection++ const pages = await this.pdfEngine.extractAllPages(++ doc,++ this.config.maxPages,++ this.config.targetPages,++ { extractImages: this.config.ocrEnabled }++ );+- // run BEFORE grid projection- if (this.ocrEngine) {- await this.runOCR(doc, pages, log);- }++ // run BEFORE grid projection++ if (this.ocrEngine) {++ await this.runOCR(doc, pages, log);++ }-- // Process pages with complete grid projection (after OCR)- processedPages = projectPagesToGrid(pages, this.config);- }- const processedPages = await projectPagesToGrid(pages, this.config);++ // Process pages with complete grid projection (after OCR)++ const processedPages = await projectPagesToGrid(pages, this.config);- // Build bounding boxes if enabled- if (this.config.preciseBoundingBox) {- for (const page of processedPages) {- page.boundingBoxes = buildBoundingBoxes(page.textItems);- }- }- // Build bounding boxes if enabled- if (this.config.preciseBoundingBox) {- for (const page of processedPages) {- page.boundingBoxes = buildBoundingBoxes(page.textItems);++ // Build bounding boxes if enabled++ if (this.config.preciseBoundingBox) {++ for (const page of processedPages) {++ page.boundingBoxes = buildBoundingBoxes(page.textItems);++ }+ }- }- // Build final text- const fullText = processedPages.map((p) => p.text).join("\n\n");- // Build final text- const fullText = processedPages.map((p) => p.text).join("\n\n");-- const result: ParseResult = {- pages: processedPages,- text: fullText,- };-- // Format based on output format- switch (this.config.outputFormat) {- case "json":- result.json = JSON.parse(formatJSON(result));- break;- case "text":- // Already in text format- break;- }++ // Build final text++ const fullText = processedPages.map((p) => p.text).join("\n\n");+- // Close PDF document- await this.pdfEngine.close(doc);++ const result: ParseResult = {++ pages: processedPages,++ text: fullText,++ };+- // Cleanup OCR engine if it's Tesseract (to free memory)- if (this.ocrEngine && "terminate" in this.ocrEngine) {- await (this.ocrEngine as TesseractEngine).terminate();- }++ // Format based on output format++ switch (this.config.outputFormat) {++ case "json":++ result.json = JSON.parse(formatJSON(result));++ break;++ case "text":++ // Already in text format++ break;++ }- // Cleanup temporary conversion files- if (needsCleanup && cleanupPath) {- await cleanupConversionFiles(cleanupPath);- }- return result;++ return result;++ }+ } finally {+ // Always release resources, even if processing throws+ await this.pdfEngine.close(doc);- const result: ParseResult = {- pages: processedPages,- text: fullText,- };+ if (this.ocrEngine && "terminate" in this.ocrEngine) {+ await (this.ocrEngine as TesseractEngine).terminate();+ }- // Format based on output format- switch (this.config.outputFormat) {- case "json":- result.json = JSON.parse(formatJSON(result));- break;- case "text":- // Already in text format- break;+ if (needsCleanup && cleanupPath) {+ await cleanupConversionFiles(cleanupPath);+ }}-- return result;}/**diff --cc src/core/types.tsindex d67569c,3ff1e5d..1abcc14--- a/src/core/types.ts+++ b/src/core/types.ts@@@ -137,14 -139,25 +139,34 @@@ export interface LiteParseConfig*/password?: string;+ /**+ * Use the experimental Rust-based PDF engine (`liteparse-rs`) instead of PDF.js.+ * Requires the `liteparse-rs` binary to be built. Set the `LITEPARSE_RS_BIN`+ * environment variable to override the default binary path.+ *+ * @defaultValue `false`+ */+ experimental?: boolean;+++ /**+ * Debug configuration for grid projection. When enabled, logs detailed+ * information about how text elements are snapped, anchored, and projected.+ * Can also generate visual PNG overlays of the projection.+ *+ * @example+ * ```typescript+ * const parser = new LiteParse({+ * debug: {+ * enabled: true,+ * textFilter: ["Total", "Revenue"],+ * pageFilter: 2,+ * visualize: true,+ * visualizePath: "./debug-output",+ * }+ * });+ * ```+ */+ debug?: GridDebugConfig;}/**