@heripo/pdf-parser 0.1.27 → 0.1.29

package/README.ko.md

@@ -21,6 +21,7 @@
 - [설치](#설치)
 - [사용법](#사용법)
 - [OCR 전략 시스템](#ocr-전략-시스템)
+- [Review Assistance](#review-assistance)
 - [문서 유형 검증](#문서-유형-검증)
 - [대용량 PDF 청크 변환](#대용량-pdf-청크-변환)
 - [이미지 PDF 폴백](#이미지-pdf-폴백)
@@ -30,18 +31,20 @@
 - [시스템 의존성 상세](#시스템-의존성-상세)
 - [API 문서](#api-문서)
 - [문제 해결](#문제-해결)
+- [후원](#후원)
 - [라이선스](#라이선스)
 
 ## 주요 기능
 
 - **고품질 OCR**: Docling SDK를 활용한 문서 인식 (ocrmac / Apple Vision Framework)
-- **혼합 문자 자동 감지 및 보정**: 한글·한자 혼용 페이지를 자동 감지하여 VLM으로 보정
+- **한국어 보고서 VLM 보정**: 한국어 보고서를 자동 감지하고 모든 페이지에 VLM 텍스트 보정을 적용
 - **Apple Silicon 최적화**: M1/M2/M3/M4/M5 칩에서 GPU 가속 지원
 - **자동 환경 설정**: Python 가상환경 및 docling-serve 자동 설치
 - **이미지 추출**: PDF 내 이미지 자동 추출 및 저장
 - **문서 유형 검증**: LLM 기반 고고학 보고서 여부 검증 (선택)
 - **청크 변환**: 대용량 PDF를 청크로 분할하여 안정적으로 처리
 - **이미지 PDF 폴백**: 변환 실패 시 이미지 기반 PDF로 자동 재시도
+- **Review Assistance**: 선택적 page-level VLM review로 audit proposal을 기록하고 고신뢰도 수정만 자동 적용
 - **AbortSignal 지원**: 진행 중인 파싱 작업 취소
 - **서버 크래시 복구**: ECONNREFUSED 발생 시 docling-serve 자동 재시작
 
@@ -49,7 +52,7 @@
 
 ### 시스템 요구사항
 
-- **macOS** with Apple Silicon (M1/M2/M3) - 최적 성능을 위해 권장
+- **macOS** with Apple Silicon (M1/M2/M3/M4/M5) - 최적 성능을 위해 권장
 - **macOS** with Intel - 지원되지만 속도가 느림
 - **Linux/Windows** - 현재 지원하지 않음
 
@@ -61,7 +64,7 @@
 brew install node
 ```
 
-#### 2. pnpm >= 9.0.0
+#### 2. pnpm >= 10.0.0
 
 ```bash
 npm install -g pnpm
@@ -123,13 +126,13 @@ brew install imagemagick ghostscript
 
 ```bash
 # npm으로 설치
-npm install @heripo/pdf-parser
+npm install @heripo/pdf-parser @heripo/logger
 
 # pnpm으로 설치
-pnpm add @heripo/pdf-parser
+pnpm add @heripo/pdf-parser @heripo/logger
 
 # yarn으로 설치
-yarn add @heripo/pdf-parser
+yarn add @heripo/pdf-parser @heripo/logger
 ```
 
 ## 사용법
@@ -140,7 +143,12 @@ yarn add @heripo/pdf-parser
 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),
+});
 
 // PDFParser 인스턴스 생성 (logger는 필수)
 const pdfParser = new PDFParser({
@@ -154,13 +162,13 @@ await pdfParser.init();
 // PDF 파싱
 const tokenUsageReport = await pdfParser.parse(
   'file:///path/to/report.pdf', // PDF URL (file:// 또는 http://)
-  'report-001',                 // 리포트 ID
+  'report-001', // 리포트 ID
   async (outputPath) => {
     // 변환 완료 콜백
     console.log('PDF 변환 완료:', outputPath);
   },
-  false,                        // cleanupAfterCallback
-  {},                           // PDFConvertOptions
+  false, // cleanupAfterCallback
+  {}, // PDFConvertOptions
 );
 
 // 토큰 사용량 리포트 (LLM 사용이 없으면 null)
@@ -201,6 +209,15 @@ const tokenUsageReport = await pdfParser.parse(
     // 문서 유형 검증
     documentValidationModel: openai('gpt-5.1'),
 
+    // 선택적 page-level review assistance
+    reviewAssistance: {
+      enabled: true,
+      autoApplyThreshold: 0.85,
+      proposalThreshold: 0.5,
+      outputLanguage: 'ko-KR',
+    },
+    onReviewAssistanceProgress: (event) => console.log(event),
+
     // 대용량 PDF 청크 변환
     chunkedConversion: true,
     chunkSize: 50,
@@ -233,16 +250,16 @@ await pdfParser.dispose();
 
 **ocrmac(Apple Vision Framework)은 매우 우수한 OCR 엔진입니다** -- 무료이고, GPU 가속을 지원하며, 고품질 결과를 제공합니다. 수천~수백만 권의 고고학 보고서를 처리할 때 이만한 솔루션이 없습니다.
 
-**그러나 ocrmac은 혼합 문자 체계를 처리하지 못합니다.** 한글·한자 혼용 문서(그리고 잠재적으로 다른 혼합 문자 조합)에서 보조 문자가 깨진 텍스트로 변환됩니다. 전체 파이프라인을 비용이 높은 VLM으로 전환하는 대신, **문제가 있는 페이지만 타겟팅**하여 VLM으로 보정합니다.
+**그러나 한국어 고고학 보고서는 문자 체계 인식 보정이 자주 필요합니다.** 한자 복원, CJK mojibake, 음독 치환, 기관명 등은 표준 OCR만으로 안정적으로 처리하기 어렵습니다. VLM을 기본 OCR 엔진으로 쓰는 대신, 빠른 ocrmac 파이프라인을 먼저 실행한 뒤 한국어 보고서에 VLM 텍스트 보정을 적용합니다.
 
-### 2단계 감지 (`OcrStrategySampler`)
+### 2단계 한국어 감지 (`OcrStrategySampler`)
 
-1. **텍스트 레이어 사전 검사** (비용 없음): `pdftotext`로 문서의 텍스트 레이어를 추출하여 한글과 CJK 문자가 모두 존재하는지 확인합니다. 둘 다 존재하면 즉시 혼합 문자 문서로 판별합니다.
-2. **VLM 샘플링** (필요 시에만): 최대 15페이지를 샘플링(앞뒤 10%는 표지·부록으로 제외)하여 Vision LLM으로 분석합니다. 최초 한글·한자 혼용 감지 시 즉시 종료하여 API 비용을 최소화합니다.
+1. **텍스트 레이어 사전 검사** (비용 없음): `pdftotext`로 문서의 텍스트 레이어를 추출하여 한글을 확인합니다. 한글이 있으면 즉시 한국어 문서로 판별합니다.
+2. **VLM 샘플링** (필요 시에만): 최대 15페이지를 샘플링(앞뒤 10%는 표지·부록으로 제외)하여 Vision LLM으로 언어를 판정합니다. `ko-KR` 감지 시 즉시 종료합니다.
 
-### 페이지별 보정 (`VlmTextCorrector`)
+### 전체 문서 보정 (`VlmTextCorrector`)
 
-혼합 문자 페이지가 감지되면, 해당 페이지만 VLM에 전송하여 보정합니다:
+한국어 보고서가 감지되면, 모든 페이지를 VLM에 전송하여 보정합니다:
 
 - 각 페이지의 OCR 텍스트 요소와 표 셀을 추출
 - `pdftotext` 참조 텍스트를 품질 기준으로 활용
@@ -261,7 +278,7 @@ const tokenUsageReport = await pdfParser.parse(
     // OCR 전략 샘플링 활성화 (Vision LLM 모델 제공)
     strategySamplerModel: openai('gpt-5.1'),
 
-    // VLM 텍스트 보정 모델 (혼합 문자 감지 시 필요)
+    // VLM 텍스트 보정 모델 (한국어 보고서 감지 시 필요)
     vlmProcessorModel: openai('gpt-5.1'),
 
     // VLM 페이지 처리 동시성 (기본값: 1)
@@ -273,6 +290,42 @@ const tokenUsageReport = await pdfParser.parse(
 );
 ```
 
+## Review Assistance
+
+`reviewAssistance`는 Docling 변환 후 선택적으로 실행되는 page-level VLM
+review입니다. 렌더링된 페이지 이미지, 텍스트, 테이블, 캡션, 그림, reading
+order, role, bounding box, 도메인 패턴을 점검하고, 고신뢰도 수정만
+`result.json`에 적용하면서 audit report를 남깁니다.
+
+```typescript
+const tokenUsageReport = await pdfParser.parse(
+  'file:///path/to/input.pdf',
+  'report-001',
+  async (outputPath) => console.log(outputPath),
+  false,
+  {
+    strategySamplerModel: openai('gpt-5.1'),
+    vlmProcessorModel: openai('gpt-5.1'),
+    reviewAssistance: {
+      enabled: true,
+      autoApplyThreshold: 0.85,
+      proposalThreshold: 0.5,
+      maxRetries: 3,
+      temperature: 0,
+      outputLanguage: 'ko-KR',
+    },
+    onReviewAssistanceProgress: (event) => {
+      console.log(event.substage, event.status, event.pageNo);
+    },
+  },
+);
+```
+
+Review Assistance는 로컬 `file://` PDF와 `vlmProcessorModel` 또는
+`strategySamplerModel`이 필요합니다. 고신뢰도 수정은 `result.json`에 적용하고,
+원본 snapshot은 `result_review_origin.json`, `result_ocr_origin.json`에 보존하며,
+페이지별 결정, 이슈, proposal, 요약 count는 `review_assistance.json`에 기록합니다.
+
 ## 문서 유형 검증
 
 LLM 기반으로 PDF가 고고학 발굴조사보고서인지 검증하는 선택적 기능입니다. `documentValidationModel`을 제공하면 파서가 PDF에서 텍스트를 추출하고 LLM을 사용하여 문서 유형을 확인한 후 처리합니다. 검증에 실패하면 `InvalidDocumentTypeError`가 발생합니다.
@@ -404,7 +457,7 @@ try {
 ### 핵심 장점
 
 - **비용**: 클라우드 OCR 대비 100배 이상 저렴 (무료)
-- **성능**: Apple Silicon M1/M2/M3에서 GPU 가속으로 빠른 처리
+- **성능**: Apple Silicon M1/M2/M3/M4/M5에서 GPU 가속으로 빠른 처리
 - **품질**: 복잡한 레이아웃의 문서도 정확히 인식
 - **프라이버시**: 문서가 외부 서버로 전송되지 않음
 
@@ -525,6 +578,10 @@ type PDFConvertOptions = {
   document_timeout?: number; // 문서 처리 타임아웃 (초)
   documentValidationModel?: LanguageModel; // 문서 유형 검증용 LLM
 
+  // Review Assistance
+  reviewAssistance?: boolean | ReviewAssistanceOptions; // 선택적 page-level review
+  onReviewAssistanceProgress?: (event: ReviewAssistanceProgressEvent) => void; // 진행 상황 callback
+
   // 청크 변환 (대용량 PDF)
   chunkedConversion?: boolean; // 청크 변환 활성화
   chunkSize?: number; // 청크당 페이지 수
@@ -537,6 +594,19 @@ type PDFConvertOptions = {
 };
 ```
 
+### ReviewAssistanceOptions
+
+```typescript
+interface ReviewAssistanceOptions {
+  enabled?: boolean; // page-level review assistance 활성화
+  autoApplyThreshold?: number; // 자동 적용 최소 confidence (기본값: 0.85)
+  proposalThreshold?: number; // sidecar proposal 최소 confidence (기본값: 0.5)
+  maxRetries?: number; // page-level VLM 호출별 최대 재시도 횟수 (기본값: 3)
+  temperature?: number; // VLM 생성 temperature (기본값: 0)
+  outputLanguage?: string; // 사람이 읽는 review reason 언어 (기본값: en-US)
+}
+```
+
 ### ConvertWithStrategyResult
 
 ```typescript
@@ -665,6 +735,13 @@ Docling SDK의 로컬 OCR은 macOS에서 Apple Metal GPU 가속을 활용해 성
 - [@heripo/document-processor](../document-processor) - 문서 구조 분석 및 LLM 처리
 - [@heripo/model](../model) - 데이터 모델 및 타입 정의
 
+## 후원
+
+heripo lab의 오픈소스 연구를 후원하려면 다음 경로를 이용할 수 있습니다:
+
+- [Open Collective](https://opencollective.com/heripo-project): 전반적인 프로젝트 후원
+- [fairy.hada.io/@heripo](https://fairy.hada.io/@heripo): 한국인 개인 후원자를 위한 원화 결제
+
 ## 라이선스
 
 이 패키지는 [Apache License 2.0](../../LICENSE) 라이선스 하에 배포됩니다.

package/README.md

@@ -21,6 +21,7 @@
 - [Installation](#installation)
 - [Usage](#usage)
 - [OCR Strategy System](#ocr-strategy-system)
+- [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,20 @@
 - [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)
-- **Mixed Script Auto-Detection & Correction**: Automatically detects Korean-Hanja mixed pages and corrects them via VLM
+- **Korean Report VLM Correction**: Automatically detects Korean reports and applies VLM text correction to all pages
 - **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**: Optional page-level VLM review that writes audit proposals and can auto-apply high-confidence fixes
 - **AbortSignal Support**: Cancel ongoing parsing operations
 - **Server Crash Recovery**: Automatic restart of docling-serve on ECONNREFUSED
 
@@ -49,7 +52,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 +64,7 @@
 brew install node
 ```
 
-#### 2. pnpm >= 9.0.0
+#### 2. pnpm >= 10.0.0
 
 ```bash
 npm install -g pnpm
@@ -123,13 +126,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
@@ -140,7 +143,12 @@ yarn add @heripo/pdf-parser
 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({
@@ -154,13 +162,13 @@ 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
+  {}, // PDFConvertOptions
 );
 
 // Token usage report (null when no LLM usage)
@@ -201,6 +209,15 @@ const tokenUsageReport = await pdfParser.parse(
     // Document validation
     documentValidationModel: openai('gpt-5.1'),
 
+    // Optional page-level review assistance
+    reviewAssistance: {
+      enabled: true,
+      autoApplyThreshold: 0.85,
+      proposalThreshold: 0.5,
+      outputLanguage: 'en-US',
+    },
+    onReviewAssistanceProgress: (event) => console.log(event),
+
     // Chunked conversion for large PDFs
     chunkedConversion: true,
     chunkSize: 50,
@@ -233,16 +250,16 @@ await pdfParser.dispose();
 
 **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, ocrmac cannot handle mixed character systems.** Documents containing Korean-Hanja combinations (and potentially other mixed scripts) produce garbled text for the non-primary script. Rather than switching the entire pipeline to a costly VLM, the system **targets only the affected pages** for VLM correction, minimizing cost and processing time.
+**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.
 
-### Two-Stage Detection (`OcrStrategySampler`)
+### Two-Stage Korean Detection (`OcrStrategySampler`)
 
-1. **Text Layer Pre-Check** (zero cost): Extracts the document's text layer using `pdftotext` and checks for both Hangul and CJK characters. If both are present, the document is immediately flagged as mixed-script.
-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 on first Korean-Hanja mix detection to minimize API costs.
+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.
 
-### Per-Page Correction (`VlmTextCorrector`)
+### Full-Document Correction (`VlmTextCorrector`)
 
-When mixed-script pages are detected, only those pages are sent to the VLM for correction:
+When a Korean report is detected, every page is sent to the VLM for correction:
 
 - Extracts OCR text elements and table cells from each page
 - Uses `pdftotext` reference text as a quality anchor
@@ -261,7 +278,7 @@ const tokenUsageReport = await pdfParser.parse(
     // Enable OCR strategy sampling (provide a Vision LLM model)
     strategySamplerModel: openai('gpt-5.1'),
 
-    // VLM model for text correction (required when mixed-script is detected)
+    // VLM model for text correction (required when Korean reports are detected)
     vlmProcessorModel: openai('gpt-5.1'),
 
     // Concurrency for VLM page processing (default: 1)
@@ -273,6 +290,43 @@ const tokenUsageReport = await pdfParser.parse(
 );
 ```
 
+## Review Assistance
+
+`reviewAssistance` enables an optional page-level VLM review after Docling
+conversion. It inspects rendered page images, text, tables, captions, pictures,
+reading order, roles, bounding boxes, and domain patterns, then writes an audit
+report while applying only high-confidence fixes.
+
+```typescript
+const tokenUsageReport = await pdfParser.parse(
+  'file:///path/to/input.pdf',
+  'report-001',
+  async (outputPath) => console.log(outputPath),
+  false,
+  {
+    strategySamplerModel: openai('gpt-5.1'),
+    vlmProcessorModel: openai('gpt-5.1'),
+    reviewAssistance: {
+      enabled: true,
+      autoApplyThreshold: 0.85,
+      proposalThreshold: 0.5,
+      maxRetries: 3,
+      temperature: 0,
+      outputLanguage: 'en-US',
+    },
+    onReviewAssistanceProgress: (event) => {
+      console.log(event.substage, event.status, event.pageNo);
+    },
+  },
+);
+```
+
+Review Assistance requires a local `file://` PDF and either
+`vlmProcessorModel` or `strategySamplerModel`. It updates `result.json` with
+auto-applied fixes, keeps snapshots in `result_review_origin.json` and
+`result_ocr_origin.json`, and writes `review_assistance.json` containing
+per-page decisions, issues, proposals, 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.
@@ -404,7 +458,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
 
@@ -525,6 +579,10 @@ type PDFConvertOptions = {
   document_timeout?: number; // Document processing timeout in seconds
   documentValidationModel?: LanguageModel; // LLM for document type validation
 
+  // Review Assistance
+  reviewAssistance?: boolean | ReviewAssistanceOptions; // Optional page-level review
+  onReviewAssistanceProgress?: (event: ReviewAssistanceProgressEvent) => void; // Progress callback
+
   // Chunked conversion (large PDFs)
   chunkedConversion?: boolean; // Enable chunked conversion
   chunkSize?: number; // Pages per chunk
@@ -537,6 +595,19 @@ type PDFConvertOptions = {
 };
 ```
 
+### ReviewAssistanceOptions
+
+```typescript
+interface ReviewAssistanceOptions {
+  enabled?: boolean; // Enable page-level review assistance
+  autoApplyThreshold?: number; // Minimum confidence for direct mutation (default: 0.85)
+  proposalThreshold?: number; // Minimum confidence for sidecar proposal (default: 0.5)
+  maxRetries?: number; // Max retries per page-level VLM call (default: 3)
+  temperature?: number; // VLM generation temperature (default: 0)
+  outputLanguage?: string; // Human-readable review reason language (default: en-US)
+}
+```
+
 ### ConvertWithStrategyResult
 
 ```typescript
@@ -665,6 +736,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).