@heripo/pdf-parser 0.1.28 → 0.1.29

package/README.ko.md

@@ -21,6 +21,7 @@
 - [설치](#설치)
 - [사용법](#사용법)
 - [OCR 전략 시스템](#ocr-전략-시스템)
+- [Review Assistance](#review-assistance)
 - [문서 유형 검증](#문서-유형-검증)
 - [대용량 PDF 청크 변환](#대용량-pdf-청크-변환)
 - [이미지 PDF 폴백](#이미지-pdf-폴백)
@@ -30,6 +31,7 @@
 - [시스템 의존성 상세](#시스템-의존성-상세)
 - [API 문서](#api-문서)
 - [문제 해결](#문제-해결)
+- [후원](#후원)
 - [라이선스](#라이선스)
 
 ## 주요 기능
@@ -42,6 +44,7 @@
 - **문서 유형 검증**: 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,
@@ -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,6 +31,7 @@
 - [System Dependencies Details](#system-dependencies-details)
 - [API Documentation](#api-documentation)
 - [Troubleshooting](#troubleshooting)
+- [Sponsor](#sponsor)
 - [License](#license)
 
 ## Key Features
@@ -42,6 +44,7 @@
 - **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,
@@ -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).

package/package.json

@@ -2,7 +2,7 @@
   "name": "@heripo/pdf-parser",
   "private": false,
   "type": "module",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "description": "PDF parsing library using Docling SDK with OCR support for macOS",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -62,8 +62,8 @@
     "es-toolkit": "^1.46.1",
     "yauzl": "^3.3.0",
     "zod": "^4.4.3",
-    "@heripo/logger": "0.1.28",
-    "@heripo/model": "0.1.28"
+    "@heripo/logger": "0.1.29",
+    "@heripo/model": "0.1.29"
   },
   "devDependencies": {
     "@types/yauzl": "^2.10.3",
@@ -72,9 +72,9 @@
     "tsup": "^8.5.1",
     "vitest": "^4.1.5",
     "@heripo/shared": "0.0.0",
+    "@heripo/tsconfig": "0.0.0",
     "@heripo/tsup-config": "0.0.0",
-    "@heripo/vitest-config": "0.0.0",
-    "@heripo/tsconfig": "0.0.0"
+    "@heripo/vitest-config": "0.0.0"
   },
   "scripts": {
     "clean": "rimraf dist",