@heripo/pdf-parser 0.1.28 → 0.1.30

package/README.md

@@ -20,7 +20,8 @@
 - [Prerequisites](#prerequisites)
 - [Installation](#installation)
 - [Usage](#usage)
-- [OCR Strategy System](#ocr-strategy-system)
+- [Mandatory Correction Pipeline](#mandatory-correction-pipeline)
+- [Review Assistance](#review-assistance)
 - [Document Type Validation](#document-type-validation)
 - [Large PDF Chunked Conversion](#large-pdf-chunked-conversion)
 - [Image PDF Fallback](#image-pdf-fallback)
@@ -30,18 +31,21 @@
 - [System Dependencies Details](#system-dependencies-details)
 - [API Documentation](#api-documentation)
 - [Troubleshooting](#troubleshooting)
+- [Sponsor](#sponsor)
 - [License](#license)
 
 ## Key Features
 
-- **High-Quality OCR**: Document recognition using Docling SDK (ocrmac / Apple Vision Framework)
-- **Korean Report VLM Correction**: Automatically detects Korean reports and applies VLM text correction to all pages
+- **Fixed ocrmac OCR**: Docling conversion always uses ocrmac / Apple Vision Framework
+- **Mandatory VLM Correction**: Post-Docling correction always runs with text correction, page gating, and structural review models
 - **Apple Silicon Optimized**: GPU acceleration on M1/M2/M3/M4/M5 chips
 - **Automatic Environment Setup**: Automatic Python virtual environment and docling-serve installation
 - **Image Extraction**: Automatic extraction and saving of images from PDFs
 - **Document Type Validation**: Optional LLM-based validation that a PDF is an archaeological report
 - **Chunked Conversion**: Split large PDFs into chunks for reliable processing
 - **Image PDF Fallback**: Automatic fallback to image-based PDF when conversion fails
+- **Review Assistance**: Page-level VLM review writes audit proposals, skips low-value pages with observable reasons, and can auto-apply high-confidence fixes
+- **Table Correction**: Table-specific work items validate cells, spans, headers, units, footnotes, and adjacent-page continuations
 - **AbortSignal Support**: Cancel ongoing parsing operations
 - **Server Crash Recovery**: Automatic restart of docling-serve on ECONNREFUSED
 
@@ -49,7 +53,7 @@
 
 ### System Requirements
 
-- **macOS** with Apple Silicon (M1/M2/M3) - Recommended for optimal performance
+- **macOS** with Apple Silicon (M1/M2/M3/M4/M5) - Recommended for optimal performance
 - **macOS** with Intel - Supported but slower
 - **Linux/Windows** - Currently not supported
 
@@ -61,7 +65,7 @@
 brew install node
 ```
 
-#### 2. pnpm >= 9.0.0
+#### 2. pnpm >= 10.0.0
 
 ```bash
 npm install -g pnpm
@@ -81,7 +85,7 @@ python3.11 --version
 
 #### 4. poppler (PDF text extraction)
 
-Required for PDF page counting (`pdfinfo`) and text layer extraction (`pdftotext`), used by the OCR strategy system's text layer pre-check.
+Required for PDF page counting (`pdfinfo`) and text layer extraction (`pdftotext`), used as a post-Docling correction reference.
 
 ```bash
 brew install poppler
@@ -123,13 +127,13 @@ This setup runs only once and may take 5-10 minutes depending on internet connec
 
 ```bash
 # Install with npm
-npm install @heripo/pdf-parser
+npm install @heripo/pdf-parser @heripo/logger
 
 # Install with pnpm
-pnpm add @heripo/pdf-parser
+pnpm add @heripo/pdf-parser @heripo/logger
 
 # Install with yarn
-yarn add @heripo/pdf-parser
+yarn add @heripo/pdf-parser @heripo/logger
 ```
 
 ## Usage
@@ -137,10 +141,16 @@ yarn add @heripo/pdf-parser
 ### Basic Usage
 
 ```typescript
+import { openai } from '@ai-sdk/openai';
 import { Logger } from '@heripo/logger';
 import { PDFParser } from '@heripo/pdf-parser';
 
-const logger = Logger(...);
+const logger = new Logger({
+  debug: (...args) => console.debug('[heripo]', ...args),
+  info: (...args) => console.info('[heripo]', ...args),
+  warn: (...args) => console.warn('[heripo]', ...args),
+  error: (...args) => console.error('[heripo]', ...args),
+});
 
 // Create PDFParser instance (logger is required)
 const pdfParser = new PDFParser({
@@ -148,19 +158,29 @@ const pdfParser = new PDFParser({
   logger,
 });
 
+const correctionModel = openai('gpt-5.1');
+
 // Initialize (environment setup and start docling-serve)
 await pdfParser.init();
 
 // Parse PDF
 const tokenUsageReport = await pdfParser.parse(
   'file:///path/to/report.pdf', // PDF URL (file:// or http://)
-  'report-001',                 // Report ID
+  'report-001', // Report ID
   async (outputPath) => {
     // Conversion complete callback
     console.log('PDF conversion complete:', outputPath);
   },
-  false,                        // cleanupAfterCallback
-  {},                           // PDFConvertOptions
+  false, // cleanupAfterCallback
+  {
+    correction: {
+      models: {
+        textCorrection: correctionModel,
+        pageGate: correctionModel,
+        reviewAssistance: correctionModel,
+      },
+    },
+  }, // PDFConvertOptions
 );
 
 // Token usage report (null when no LLM usage)
@@ -193,10 +213,37 @@ const tokenUsageReport = await pdfParser.parse(
   async (outputPath) => console.log(outputPath),
   false,
   {
-    // OCR strategy options
-    strategySamplerModel: openai('gpt-5.1'),
-    vlmProcessorModel: openai('gpt-5.1'),
-    vlmConcurrency: 3,
+    // Mandatory post-Docling correction
+    correction: {
+      models: {
+        textCorrection: openai('gpt-5.1'),
+        pageGate: openai('gpt-5.1'),
+        reviewAssistance: openai('gpt-5.1'),
+        tableCorrection: openai('gpt-5.1'),
+        reviewAssistanceTasks: {
+          text_ocr_hanja: openai('gpt-5.1'),
+          tables: openai('gpt-5.1'),
+        },
+      },
+      concurrency: {
+        pages: 1,
+        reviewTasks: 4,
+        tables: 1,
+      },
+      localModelConcurrency: 1,
+      workItemTimeoutMs: 900000,
+      maxRetries: {
+        textCorrection: 3,
+        pageGate: 3,
+        reviewAssistance: 3,
+        tableCorrection: 3,
+      },
+      autoApplyThreshold: 0.85,
+      proposalThreshold: 0.5,
+      temperature: 0,
+      outputLanguage: 'en-US',
+    },
+    onReviewAssistanceProgress: (event) => console.log(event),
 
     // Document validation
     documentValidationModel: openai('gpt-5.1'),
@@ -227,29 +274,52 @@ Clean up resources after work is complete:
 await pdfParser.dispose();
 ```
 
-## OCR Strategy System
+## Mandatory Correction Pipeline
 
-### Why This Strategy?
+### Why ocrmac Is Fixed
 
 **ocrmac (Apple Vision Framework) is an excellent OCR engine** -- it's free, GPU-accelerated, and delivers high-quality results. For processing thousands to millions of archaeological reports, there's no better solution.
 
-**However, Korean archaeological reports often need script-aware correction.** Hanja restoration, CJK mojibake, phonetic substitutions, and institution names can be unreliable with standard OCR alone. Rather than using VLM as the primary OCR engine, the system runs the fast ocrmac pipeline first and then applies VLM text correction to Korean reports.
+`@heripo/pdf-parser` no longer samples OCR strategies or switches to a VLM OCR path. Docling conversion always uses ocrmac. VLMs are used only after Docling conversion as a mandatory correction stage.
+
+### Required Correction Contract
+
+Every `parse()` call must provide `correction.models.textCorrection`, `correction.models.pageGate`, and `correction.models.reviewAssistance`. If any required correction model is missing, parsing fails before conversion callback wrapping.
+
+The correction stage runs in this order:
 
-### Two-Stage Korean Detection (`OcrStrategySampler`)
+1. Save `result_ocr_origin.json` before mutations.
+2. Run page-level text and table-cell OCR correction with `textCorrection`.
+3. Run the Review Assistance page gate with `pageGate` and write `review_assistance_page_gate.json`.
+4. Run structural Review Assistance work items with task-specific models.
+5. Run table-specific correction work items for each detected table.
+6. Write `review_assistance_checkpoint.json` during execution and `review_assistance.json` at the end.
+
+Text correction applies to every page with text or table content. The page gate only controls structural Review Assistance noise; it does not disable OCR text correction.
+
+### Local Model Execution
+
+The correction pipeline is optimized for local VLMs: small contexts, many calls, deterministic validation, retry loops, bounded concurrency, and resumable checkpoints. For local models, start with `concurrency.pages: 1`, `concurrency.tables: 1`, `localModelConcurrency: 1`, `temperature: 0`, and a generous `workItemTimeoutMs`. Increase concurrency only after the model is stable.
+
+### Rollout Smoke Test
+
+Repository contributors can run the correction rollout smoke test against two local demo archaeological report artifacts:
+
+```bash
+pnpm --filter @heripo/pdf-parser smoke:correction
+```
 
-1. **Text Layer Pre-Check** (zero cost): Extracts the document's text layer using `pdftotext` and checks for Hangul. If Hangul is present, the document is immediately treated as Korean.
-2. **VLM Sampling** (only when needed): Samples up to 15 pages (trimming 10% from front/back to skip covers and appendices) and analyzes them with a Vision LLM. Uses early exit when `ko-KR` is detected.
+The smoke test copies existing demo artifacts into `/private/tmp/heripo-pdf-parser-correction-smoke`, runs correction with a deterministic local fake model, verifies `review_assistance.json`, table work-item traces, validation status, and checkpoint resume behavior. It exercises pipeline mechanics; semantic table quality still depends on the configured real local VLM.
 
-### Full-Document Correction (`VlmTextCorrector`)
+## Review Assistance
 
-When a Korean report is detected, every page is sent to the VLM for correction:
+Review Assistance always runs after text correction, but it does not process every page with the same intensity. The page gate marks covers, chapter covers, barcode/ISBN pages, and decorative pages as low-value for structural review. Skipped pages remain observable in `review_assistance.json` with an info issue and skip reason.
 
-- Extracts OCR text elements and table cells from each page
-- Uses `pdftotext` reference text as a quality anchor
-- VLM returns substitution-based corrections (find -> replace)
-- Failed page corrections are gracefully skipped, preserving original OCR text
+Eligible pages are split into small work items for text OCR/Hanja review, text integrity, text role/footnote review, tables, pictures/captions, layout/bbox/order, and table-specific correction. Each call records timing, model id, attempts, target refs, and deterministic validation status in `review_assistance.json`.
 
-### Strategy Options
+### Table Correction Strategy
+
+Tables are treated as first-class correction targets. The scheduler creates one table-specific work item per table so pages with multiple tables keep independent bbox, crop, context, and validation state. The table validator checks target identity, same-page table mixing, cells, spans, headers, units, footnotes, empty-cell expansion, and adjacent-page continuation refs before any command can become an auto-apply or proposal decision.
 
 ```typescript
 const tokenUsageReport = await pdfParser.parse(
@@ -258,21 +328,33 @@ const tokenUsageReport = await pdfParser.parse(
   async (outputPath) => console.log(outputPath),
   false,
   {
-    // Enable OCR strategy sampling (provide a Vision LLM model)
-    strategySamplerModel: openai('gpt-5.1'),
-
-    // VLM model for text correction (required when Korean reports are detected)
-    vlmProcessorModel: openai('gpt-5.1'),
-
-    // Concurrency for VLM page processing (default: 1)
-    vlmConcurrency: 3,
-
-    // Skip sampling and force a specific OCR method
-    forcedMethod: 'ocrmac', // or 'vlm'
+    correction: {
+      models: {
+        textCorrection: openai('gpt-5.1'),
+        pageGate: openai('gpt-5.1-mini'),
+        reviewAssistance: openai('gpt-5.1'),
+        tableCorrection: openai('gpt-5.1'),
+      },
+      autoApplyThreshold: 0.85,
+      proposalThreshold: 0.5,
+      maxRetries: {
+        textCorrection: 3,
+        pageGate: 3,
+        reviewAssistance: 3,
+        tableCorrection: 3,
+      },
+      temperature: 0,
+      outputLanguage: 'en-US',
+    },
+    onReviewAssistanceProgress: (event) => {
+      console.log(event.substage, event.status, event.pageNo);
+    },
   },
 );
 ```
 
+Review Assistance requires a local `file://` PDF for page image and text-layer references. It updates `result.json` with auto-applied fixes, keeps snapshots in `result_review_origin.json` and `result_ocr_origin.json`, writes `review_assistance_page_gate.json`, and writes `review_assistance.json` containing per-page decisions, issues, proposals, call traces, validation status, and summary counts.
+
 ## Document Type Validation
 
 Optional LLM-based validation that a PDF is an archaeological investigation report. When `documentValidationModel` is provided, the parser extracts text from the PDF and uses the LLM to verify the document type before processing. If validation fails, an `InvalidDocumentTypeError` is thrown.
@@ -287,6 +369,13 @@ try {
     async (outputPath) => console.log(outputPath),
     false,
     {
+      correction: {
+        models: {
+          textCorrection: openai('gpt-5.1'),
+          pageGate: openai('gpt-5.1'),
+          reviewAssistance: openai('gpt-5.1'),
+        },
+      },
       documentValidationModel: openai('gpt-5.1'),
     },
   );
@@ -308,6 +397,13 @@ const tokenUsageReport = await pdfParser.parse(
   async (outputPath) => console.log(outputPath),
   false,
   {
+    correction: {
+      models: {
+        textCorrection: openai('gpt-5.1'),
+        pageGate: openai('gpt-5.1'),
+        reviewAssistance: openai('gpt-5.1'),
+      },
+    },
     chunkedConversion: true,
     chunkSize: 50, // Pages per chunk (default: configured in constants)
     chunkMaxRetries: 3, // Max retry attempts per failed chunk (default: configured in constants)
@@ -342,6 +438,13 @@ const tokenUsageReport = await pdfParser.parse(
   async (outputPath) => console.log(outputPath),
   false,
   {
+    correction: {
+      models: {
+        textCorrection: openai('gpt-5.1'),
+        pageGate: openai('gpt-5.1'),
+        reviewAssistance: openai('gpt-5.1'),
+      },
+    },
     forceImagePdf: true, // Always convert to image PDF first
   },
 );
@@ -365,7 +468,15 @@ try {
     'report-001',
     async (outputPath) => console.log(outputPath),
     false,
-    {},
+    {
+      correction: {
+        models: {
+          textCorrection: openai('gpt-5.1'),
+          pageGate: openai('gpt-5.1'),
+          reviewAssistance: openai('gpt-5.1'),
+        },
+      },
+    },
     controller.signal, // AbortSignal
   );
 } catch (error) {
@@ -404,7 +515,7 @@ Archaeological excavation report PDFs have the following characteristics:
 ### Key Advantages
 
 - **Cost**: 100x+ cheaper than cloud OCR (free)
-- **Performance**: Fast processing with GPU acceleration on Apple Silicon M1/M2/M3
+- **Performance**: Fast processing with GPU acceleration on Apple Silicon M1/M2/M3/M4/M5
 - **Quality**: Accurate recognition even for complex documents
 - **Privacy**: Documents are not sent to external servers
 
@@ -507,12 +618,8 @@ await pdfParser.dispose();
 
 ```typescript
 type PDFConvertOptions = {
-  // OCR strategy options
-  strategySamplerModel?: LanguageModel; // Vision LLM for OCR strategy sampling
-  vlmProcessorModel?: LanguageModel; // Vision LLM for text correction
-  vlmConcurrency?: number; // Parallel page processing (default: 1)
-  skipSampling?: boolean; // Skip strategy sampling
-  forcedMethod?: 'ocrmac' | 'vlm'; // Force specific OCR method
+  // Mandatory post-Docling correction
+  correction: PDFCorrectionOptions;
 
   // Image PDF options
   forceImagePdf?: boolean; // Force pre-conversion to image-based PDF
@@ -525,6 +632,9 @@ type PDFConvertOptions = {
   document_timeout?: number; // Document processing timeout in seconds
   documentValidationModel?: LanguageModel; // LLM for document type validation
 
+  // Correction progress
+  onReviewAssistanceProgress?: (event: ReviewAssistanceProgressEvent) => void; // Progress callback
+
   // Chunked conversion (large PDFs)
   chunkedConversion?: boolean; // Enable chunked conversion
   chunkSize?: number; // Pages per chunk
@@ -537,14 +647,47 @@ type PDFConvertOptions = {
 };
 ```
 
-### ConvertWithStrategyResult
+### PDFCorrectionOptions
 
 ```typescript
-interface ConvertWithStrategyResult {
-  /** The OCR strategy that was determined */
-  strategy: OcrStrategy;
-  /** Token usage report from sampling and/or VLM processing (null when no LLM usage occurs) */
-  tokenUsageReport: TokenUsageReport | null;
+interface PDFCorrectionOptions {
+  models: {
+    textCorrection: LanguageModel; // Required: page text and table-cell OCR correction
+    pageGate: LanguageModel; // Required: structural Review Assistance page gate
+    reviewAssistance: LanguageModel; // Required: default structural review model
+    tableCorrection?: LanguageModel; // Optional: table-specific correction override
+    reviewAssistanceTasks?: Partial<
+      Record<
+        | 'text_ocr_hanja'
+        | 'text_integrity'
+        | 'text_role_footnote'
+        | 'tables'
+        | 'pictures_captions'
+        | 'layout_bbox_order',
+        LanguageModel
+      >
+    >;
+  };
+  concurrency?: {
+    pages?: number; // Page-level text correction and page gate concurrency
+    reviewTasks?: number; // Structural Review Assistance work-item concurrency
+    tables?: number; // Table-specific correction concurrency
+  };
+  maxRetries?: {
+    textCorrection?: number;
+    pageGate?: number;
+    reviewAssistance?: number;
+    tableCorrection?: number;
+  };
+  localModelConcurrency?: number; // Bounded local model request concurrency
+  workItemTimeoutMs?: number; // Per-work-item timeout
+  outputLanguage?: string; // Human-readable review reason language (default: en-US)
+  pageGate?: {
+    structuralNoiseThreshold?: number;
+  };
+  autoApplyThreshold?: number; // Minimum confidence for direct mutation (default: 0.85)
+  proposalThreshold?: number; // Minimum confidence for sidecar proposal (default: 0.5)
+  temperature?: number; // VLM generation temperature (default: 0)
 }
 ```
 
@@ -665,6 +808,13 @@ If you have ideas for supporting Linux while maintaining both performance and co
 - [@heripo/document-processor](../document-processor) - Document structure analysis and LLM processing
 - [@heripo/model](../model) - Data models and type definitions
 
+## Sponsor
+
+If you'd like to support heripo lab's open-source research, you can sponsor us through:
+
+- [Open Collective](https://opencollective.com/heripo-project) for general project sponsorship.
+- [fairy.hada.io/@heripo](https://fairy.hada.io/@heripo) for Korean individual supporters who prefer KRW payments.
+
 ## License
 
 This package is distributed under the [Apache License 2.0](../../LICENSE).