@heripo/pdf-parser 0.1.44 → 0.1.45

package/README.ko.md

@@ -37,8 +37,8 @@
 ## 주요 기능
 
 - **ocrmac 고정 OCR**: Docling 변환은 항상 ocrmac / Apple Vision Framework를 사용
-- **필수 VLM 보정**: Docling 이후 텍스트 보정, page gate, 구조 review 모델을 항상 실행
-- **Apple Silicon 최적화**: M1/M2/M3/M4/M5 칩에서 GPU 가속 지원
+- **필수 VLM 보정**: Docling 이후 텍스트 보정은 필수이며 page gate와 구조 검토는 비활성화 가능
+- **Apple Silicon 백엔드**: Docling 변환에서 `mps` accelerator 요청
 - **자동 환경 설정**: Python 가상환경 및 docling-serve 자동 설치
 - **이미지 추출**: PDF 내 이미지 자동 추출 및 저장
 - **문서 유형 검증**: LLM 기반 고고학 보고서 여부 검증 (선택)
@@ -65,22 +65,23 @@
 brew install node
 ```
 
-#### 2. pnpm >= 11
+#### 2. pnpm >= 12
 
 ```bash
-npm install -g pnpm
+npm install -g pnpm@12
 ```
 
 #### 3. Python 3.9 - 3.12
 
-> **중요**: Python 3.13+는 지원하지 않습니다. Docling SDK의 일부 의존성이 Python 3.13과 호환되지 않습니다.
+> **중요**: 현재 설치 코드는 Python 3.9–3.12만 허용하고 3.13 이상은 거부합니다. 저장소의 버전 검사 기준이며 모든 upstream Docling 버전의 호환성을 뜻하지는 않습니다.
 
 ```bash
 # Python 3.11 설치 (권장)
 brew install python@3.11
 
 # 버전 확인
-python3.11 --version
+export PATH="$(brew --prefix python@3.11)/libexec/bin:$PATH"
+python3 --version
 ```
 
 #### 4. poppler (PDF 텍스트 추출)
@@ -105,9 +106,9 @@ macOS에 기본적으로 설치되어 있습니다. 확인:
 which lsof
 ```
 
-#### 7. ImageMagick + Ghostscript (선택)
+#### 7. ImageMagick + Ghostscript
 
-이미지 PDF 폴백 기능(`enableImagePdfFallback` 또는 `forceImagePdf`)을 사용할 때만 필요합니다.
+필수 VLM 보정에 사용하는 로컬 PDF 페이지 렌더링과 이미지 PDF 폴백에 필요합니다. `enableImagePdfFallback`과 `forceImagePdf`가 꺼져 있어도 설치하세요.
 
 ```bash
 brew install imagemagick ghostscript
@@ -121,25 +122,27 @@ brew install imagemagick ghostscript
 2. `docling-serve` 및 의존성 설치
 3. 로컬 포트에서 docling-serve 프로세스 시작
 
-이 설정은 한 번만 수행되며 인터넷 연결 상태에 따라 5-10분 정도 소요될 수 있습니다.
+가상환경은 재사용하지만 로컬 초기화에서 의존성 설치 단계를 다시 실행합니다. 설치 코드는 docling-serve 1.16.1과 명시적인 Docling 런타임 버전을 사용합니다. [python-environment.ts](./src/environment/python-environment.ts)를 참고하세요. 별도 `python3.11` 설치 여부보다 PATH의 `python3` 버전이 중요합니다.
 
 ## 설치
 
 ```bash
 # npm으로 설치
-npm install @heripo/pdf-parser @heripo/logger
+npm install @heripo/pdf-parser @heripo/logger @ai-sdk/openai
 
 # pnpm으로 설치
-pnpm add @heripo/pdf-parser @heripo/logger
+pnpm add @heripo/pdf-parser @heripo/logger @ai-sdk/openai
 
 # yarn으로 설치
-yarn add @heripo/pdf-parser @heripo/logger
+yarn add @heripo/pdf-parser @heripo/logger @ai-sdk/openai
 ```
 
 ## 사용법
 
 ### 기본 사용법
 
+ESM 프로젝트에서 실행하세요. 예제의 `HERIPO_MODEL`은 사용자가 설정하는 환경 변수로, 이미지 입력과 구조화된 출력을 지원하는 모델 ID를 지정합니다. `OPENAI_API_KEY`도 설정하세요. 다른 provider는 해당 AI SDK adapter로 대체할 수 있습니다.
+
 ```typescript
 import { openai } from '@ai-sdk/openai';
 import { Logger } from '@heripo/logger';
@@ -158,33 +161,37 @@ const pdfParser = new PDFParser({
   logger,
 });
 
-const correctionModel = openai('gpt-5.1');
+const correctionModel = openai(process.env.HERIPO_MODEL!);
 
 // 초기화 (환경 설정 및 docling-serve 시작)
-await pdfParser.init();
-
-// PDF 파싱
-const tokenUsageReport = await pdfParser.parse(
-  'file:///path/to/report.pdf', // PDF URL (file:// 또는 http://)
-  'report-001', // 리포트 ID
-  async (outputPath) => {
-    // 변환 완료 콜백
-    console.log('PDF 변환 완료:', outputPath);
-  },
-  false, // cleanupAfterCallback
-  {
-    correction: {
-      models: {
-        textCorrection: correctionModel,
-        pageGate: correctionModel,
-        reviewAssistance: correctionModel,
-      },
+try {
+  await pdfParser.init();
+
+  // PDF 파싱
+  const tokenUsageReport = await pdfParser.parse(
+    'file:///path/to/report.pdf', // PDF URL (file:// 또는 http://)
+    'report-001', // 리포트 ID
+    async (outputPath) => {
+      // 변환 완료 콜백
+      console.log('PDF 변환 완료:', outputPath);
     },
-  }, // PDFConvertOptions
-);
+    false, // cleanupAfterCallback
+    {
+      correction: {
+        models: {
+          textCorrection: correctionModel,
+          pageGate: correctionModel,
+          reviewAssistance: correctionModel,
+        },
+      },
+    }, // PDFConvertOptions
+  );
 
-// 토큰 사용량 리포트 (LLM 사용이 없으면 null)
-console.log('토큰 사용량:', tokenUsageReport);
+  // 토큰 사용량 리포트 (LLM 사용이 없으면 null)
+  console.log('토큰 사용량:', tokenUsageReport);
+} finally {
+  await pdfParser.dispose();
+}
 ```
 
 ### 고급 옵션
@@ -193,7 +200,7 @@ console.log('토큰 사용량:', tokenUsageReport);
 // 옵션 A: 로컬 서버 (포트 모드)
 const pdfParser = new PDFParser({
   logger,
-  port: 5001,                      // 사용할 포트 (기본값: 5001)
+  port: 5001, // Local port must be specified explicitly
   timeout: 10000000,                // 타임아웃 (밀리초)
   venvPath: '/custom/path/.venv',   // 커스텀 venv 경로 (기본값: CWD/.venv)
   killExistingProcess: true,        // 포트의 기존 프로세스 종료 (기본값: false)
@@ -216,13 +223,13 @@ const tokenUsageReport = await pdfParser.parse(
     // Docling 이후 필수 보정
     correction: {
       models: {
-        textCorrection: openai('gpt-5.1'),
-        pageGate: openai('gpt-5.1'),
-        reviewAssistance: openai('gpt-5.1'),
-        tableCorrection: openai('gpt-5.1'),
+        textCorrection: openai(process.env.HERIPO_MODEL!),
+        pageGate: openai(process.env.HERIPO_MODEL!),
+        reviewAssistance: openai(process.env.HERIPO_MODEL!),
+        tableCorrection: openai(process.env.HERIPO_MODEL!),
         reviewAssistanceTasks: {
-          text_ocr_hanja: openai('gpt-5.1'),
-          tables: openai('gpt-5.1'),
+          text_ocr_hanja: openai(process.env.HERIPO_MODEL!),
+          tables: openai(process.env.HERIPO_MODEL!),
         },
       },
       concurrency: {
@@ -246,7 +253,7 @@ const tokenUsageReport = await pdfParser.parse(
     onReviewAssistanceProgress: (event) => console.log(event),
 
     // 문서 유형 검증
-    documentValidationModel: openai('gpt-5.1'),
+    documentValidationModel: openai(process.env.HERIPO_MODEL!),
 
     // 대용량 PDF 청크 변환
     chunkedConversion: true,
@@ -265,6 +272,12 @@ const tokenUsageReport = await pdfParser.parse(
 );
 ```
 
+### 산출물
+
+콜백은 `output/<reportId>/`의 절대 경로를 받습니다. `result.json`은 보정 결과이고 `result_ocr_origin.json`은 초기 OCR 스냅샷입니다. `images/`와 `pages/`는 추출 이미지와 페이지 이미지입니다. 구조 검토 활성화 시 `result_review_origin.json`, `review_assistance_page_gate.json`, `review_assistance_checkpoint.json`, `review_assistance.json`도 생성됩니다. 실패한 검토 작업은 리포트의 페이지 상태·이슈·call trace를 확인하세요.
+
+`cleanupAfterCallback: true`이면 콜백 이후 산출물 디렉터리가 삭제됩니다. 필요한 파일을 콜백 안에서 다른 위치로 복사하거나 `false`로 보존하세요. 파서는 `result-processed.json`이나 handoff manifest를 만들지 않으며 데모 worker가 별도로 저장합니다.
+
 ### 리소스 정리
 
 작업 완료 후 리소스를 정리합니다:
@@ -278,15 +291,15 @@ await pdfParser.dispose();
 
 ### ocrmac을 고정하는 이유
 
-**ocrmac(Apple Vision Framework)은 매우 우수한 OCR 엔진입니다** -- 무료이고, GPU 가속을 지원하며, 고품질 결과를 제공합니다. 수천~수백만 권의 고고학 보고서를 처리할 때 이만한 솔루션이 없습니다.
+ocrmac은 macOS의 Apple Vision을 사용하는 고정 OCR 백엔드입니다.
 
-`@heripo/pdf-parser`는 더 이상 OCR strategy를 sampling하거나 VLM OCR 경로로 전환하지 않습니다. Docling 변환은 항상 ocrmac으로 실행하고, VLM은 Docling 이후 필수 보정 단계에서만 사용합니다.
+`@heripo/pdf-parser`는 더 이상 OCR strategy를 sampling하거나 VLM OCR 경로로 전환하지 않습니다. Docling 변환은 항상 ocrmac으로 실행하고, VLM 보정은 Docling 이후 실행합니다. 선택적인 언어 감지와 문서 유형 검증에서도 변환 전에 모델을 호출할 수 있습니다.
 
 ### 필수 correction 계약
 
 모든 `parse()` 호출은 `correction.models.textCorrection`, `correction.models.pageGate`, `correction.models.reviewAssistance`를 제공해야 합니다. 필수 모델이 누락되면 변환 callback을 감싸기 전에 명확히 실패합니다.
 
-보정 단계는 다음 순서로 실행됩니다.
+구조 검토가 기본 설정대로 활성화된 경우 보정 단계는 다음과 같습니다.
 
 1. 변경 전 `result_ocr_origin.json`을 저장합니다.
 2. `textCorrection` 모델로 페이지 텍스트와 표 셀 OCR을 보정합니다.
@@ -299,21 +312,39 @@ await pdfParser.dispose();
 
 ### 로컬 모델 권장 실행 방식
 
-보정 파이프라인은 로컬 VLM 기준으로 설계되었습니다. 큰 context 하나보다 작은 context를 자주 호출하고, deterministic validator와 retry, timeout, checkpoint/resume으로 안정성을 확보합니다. 처음에는 `concurrency.pages: 1`, `concurrency.tables: 1`, `modelConcurrency: 1`, `temperature: 0`, 충분한 `workItemTimeoutMs`로 시작하고, 모델이 안정화된 뒤 동시성을 높이는 것을 권장합니다.
+보정 파이프라인은 로컬 VLM 기준으로 설계되었습니다. 큰 context 하나보다 작은 context를 자주 호출하고, deterministic validator와 retry, timeout, checkpoint/resume으로 안정성을 확보합니다. 처음에는 `concurrency.pages: 1`, `concurrency.reviewTasks: 1`, `modelConcurrency: 1`, `temperature: 0`, 충분한 `workItemTimeoutMs`로 시작하고, 모델이 안정화된 뒤 동시성을 높이는 것을 권장합니다.
 
-### 롤아웃 smoke test
+### 검증
 
-레포 contributor는 로컬 demo 고고학 보고서 산출물 2종으로 correction rollout smoke test를 실행할 수 있습니다.
+저장소에 정의된 테스트 명령은 `pnpm --filter @heripo/pdf-parser test:coverage`입니다. 테스트는 외부 모델 호출을 모킹하므로 실제 문서의 보정 품질은 별도 확인해야 합니다.
 
-```bash
-pnpm --filter @heripo/pdf-parser smoke:correction
-```
+### 보정 옵션과 기본값
 
-이 smoke test는 기존 demo artifact를 `/private/tmp/heripo-pdf-parser-correction-smoke`로 복사하고, deterministic local fake model로 correction을 실행한 뒤 `review_assistance.json`, 표 work-item trace, validation status, checkpoint resume 동작을 검증합니다. 파이프라인 기계적 경로를 검증하는 용도이며, 의미론적 표 보정 품질은 실제로 설정한 로컬 VLM 품질에 의존합니다.
+세 필수 모델은 구조 검토를 꺼도 모두 제공해야 합니다. `reviewAssistanceEnabled: false`이면 텍스트·표 셀 OCR 보정만 수행하고 page gate와 구조 검토를 생략합니다. `tableCorrectionEnabled: false`는 구조 검토의 표 작업만 생략하며 초기 표 셀 OCR 보정에는 영향을 주지 않습니다.
+
+`forceAutoApply` 기본값은 `false`입니다. `true`이면 검증을 통과한 명령을 신뢰도 임계값과 구조적 제약에 따른 수동 검토 분기 없이 적용합니다. 명령 검증 자체를 생략하는 옵션은 아닙니다.
+
+| Option                                               | Default                |
+| ---------------------------------------------------- | ---------------------- |
+| `concurrency.pages`                                  | `1`                    |
+| `concurrency.reviewTasks`                            | `6`                    |
+| `modelConcurrency`                                   | `1`                    |
+| `maxRetries.*`                                       | `3`                    |
+| `workItemTimeoutMs`                                  | `1800000` (30 minutes) |
+| `outputLanguage`                                     | `en-US`                |
+| `autoApplyThreshold` / `proposalThreshold`           | `0.85` / `0.5`         |
+| `reviewAssistanceEnabled` / `tableCorrectionEnabled` | `true` / `true`        |
+| `forceAutoApply` / `temperature`                     | `false` / `0`          |
+
+기본값은 내보낸 `PDF_CORRECTION_DEFAULTS`에서도 확인할 수 있습니다. `concurrency.tables`와 `pageGate.structuralNoiseThreshold`는 타입에 있지만 현재 최상위 파이프라인에서 runner 제어값으로 전달되지 않습니다. 표 작업 동시성은 `reviewTasks`와 `modelConcurrency`로 제어하세요.
+
+### 언어 감지
+
+`ocr_lang`이 있으면 그대로 사용합니다. 없으면 로컬 PDF 텍스트 레이어를 분석하고, 부족한 경우 `languageDetectionModel`로 페이지를 감지합니다. `languageDetectionFallbackModel`도 지정할 수 있습니다. 원격 입력이나 감지할 수 없는 입력은 기본 언어 `ko-KR`, `en-US`를 사용합니다. OCR 엔진 선택 기능은 아니며 OCR은 항상 ocrmac입니다.
 
 ## Review Assistance
 
-Review Assistance는 텍스트 보정 이후 항상 실행되지만 모든 페이지를 같은 강도로 처리하지 않습니다. page gate가 표지, 챕터 표지, 바코드/ISBN 페이지, 장식 중심 페이지를 구조 review 저가치 페이지로 분류합니다. skip된 페이지도 `review_assistance.json`에 info issue와 skip reason으로 남습니다.
+Review Assistance는 `correction.reviewAssistanceEnabled: true`일 때(라이브러리 기본값) 텍스트 보정 이후 실행되지만 모든 페이지를 같은 강도로 처리하지 않습니다. page gate가 표지, 챕터 표지, 바코드/ISBN 페이지, 장식 중심 페이지를 구조 review 저가치 페이지로 분류합니다. skip된 페이지도 `review_assistance.json`에 info issue와 skip reason으로 남습니다.
 
 eligible page는 text OCR/Hanja, text integrity, text role/footnote, tables, pictures/captions, layout/bbox/order, table-specific correction 같은 작은 work item으로 쪼개집니다. 각 호출의 timing, model id, attempts, target refs, deterministic validation status는 `review_assistance.json`에 기록됩니다.
 
@@ -330,10 +361,10 @@ const tokenUsageReport = await pdfParser.parse(
   {
     correction: {
       models: {
-        textCorrection: openai('gpt-5.1'),
-        pageGate: openai('gpt-5.1-mini'),
-        reviewAssistance: openai('gpt-5.1'),
-        tableCorrection: openai('gpt-5.1'),
+        textCorrection: openai(process.env.HERIPO_MODEL!),
+        pageGate: openai(process.env.HERIPO_MODEL!),
+        reviewAssistance: openai(process.env.HERIPO_MODEL!),
+        tableCorrection: openai(process.env.HERIPO_MODEL!),
       },
       autoApplyThreshold: 0.85,
       proposalThreshold: 0.5,
@@ -353,7 +384,7 @@ const tokenUsageReport = await pdfParser.parse(
 );
 ```
 
-Review Assistance는 page image와 text-layer reference를 위해 로컬 `file://` PDF를 필요로 합니다. 고신뢰도 수정은 `result.json`에 적용하고, 원본 snapshot은 `result_review_origin.json`, `result_ocr_origin.json`에 보존하며, `review_assistance_page_gate.json`과 페이지별 결정, 이슈, proposal, call trace, validation status, 요약 count를 담은 `review_assistance.json`을 기록합니다.
+전체 파이프라인에는 로컬 `file://` PDF를 사용하세요. HTTP 입력은 Docling에서 받지만 로컬 페이지 렌더링·언어 감지·문서 검증은 건너뜁니다. `pages/page_<index>.png`가 없으면 텍스트 보정을 생략하므로 콜백 성공이 모든 페이지의 보정 성공을 뜻하지는 않습니다. 보정 호출이 실패한 페이지는 OCR 원문을 유지하고 경고를 기록합니다. 고신뢰도 수정은 `result.json`에 적용하고, 원본 snapshot은 `result_review_origin.json`, `result_ocr_origin.json`에 보존하며, `review_assistance_page_gate.json`과 페이지별 결정, 이슈, proposal, call trace, validation status, 요약 count를 담은 `review_assistance.json`을 기록합니다.
 
 ## 문서 유형 검증
 
@@ -371,12 +402,12 @@ try {
     {
       correction: {
         models: {
-          textCorrection: openai('gpt-5.1'),
-          pageGate: openai('gpt-5.1'),
-          reviewAssistance: openai('gpt-5.1'),
+          textCorrection: openai(process.env.HERIPO_MODEL!),
+          pageGate: openai(process.env.HERIPO_MODEL!),
+          reviewAssistance: openai(process.env.HERIPO_MODEL!),
         },
       },
-      documentValidationModel: openai('gpt-5.1'),
+      documentValidationModel: openai(process.env.HERIPO_MODEL!),
     },
   );
 } catch (error) {
@@ -399,18 +430,20 @@ const tokenUsageReport = await pdfParser.parse(
   {
     correction: {
       models: {
-        textCorrection: openai('gpt-5.1'),
-        pageGate: openai('gpt-5.1'),
-        reviewAssistance: openai('gpt-5.1'),
+        textCorrection: openai(process.env.HERIPO_MODEL!),
+        pageGate: openai(process.env.HERIPO_MODEL!),
+        reviewAssistance: openai(process.env.HERIPO_MODEL!),
       },
     },
     chunkedConversion: true,
-    chunkSize: 50, // 청크당 페이지 수 (기본값: 상수에서 설정)
-    chunkMaxRetries: 3, // 실패한 청크의 최대 재시도 횟수 (기본값: 상수에서 설정)
+    chunkSize: 50, // Pages per chunk (default: 10)
+    chunkMaxRetries: 3, // Retries per failed chunk (default: 2)
   },
 );
 ```
 
+청크 변환 결과를 합친 뒤 보정을 수행합니다. 현재 구현은 청크 변환 실패 시 `enableImagePdfFallback`과 별개로 이미지 PDF 재시도를 수행하므로 이 경로에도 ImageMagick/Ghostscript가 필요합니다. `chunkedConversion`과 `forceImagePdf`를 함께 지정한 로컬 입력은 청크 분기가 우선합니다.
+
 ## 이미지 PDF 폴백
 
 변환이 실패하면 파서가 PDF를 이미지 기반 PDF로 변환한 후 재시도할 수 있습니다. 복잡하거나 손상된 구조의 PDF에 유용합니다. ImageMagick과 Ghostscript가 필요합니다.
@@ -440,9 +473,9 @@ const tokenUsageReport = await pdfParser.parse(
   {
     correction: {
       models: {
-        textCorrection: openai('gpt-5.1'),
-        pageGate: openai('gpt-5.1'),
-        reviewAssistance: openai('gpt-5.1'),
+        textCorrection: openai(process.env.HERIPO_MODEL!),
+        pageGate: openai(process.env.HERIPO_MODEL!),
+        reviewAssistance: openai(process.env.HERIPO_MODEL!),
       },
     },
     forceImagePdf: true, // 항상 이미지 PDF로 먼저 변환
@@ -471,16 +504,16 @@ try {
     {
       correction: {
         models: {
-          textCorrection: openai('gpt-5.1'),
-          pageGate: openai('gpt-5.1'),
-          reviewAssistance: openai('gpt-5.1'),
+          textCorrection: openai(process.env.HERIPO_MODEL!),
+          pageGate: openai(process.env.HERIPO_MODEL!),
+          reviewAssistance: openai(process.env.HERIPO_MODEL!),
         },
       },
     },
     controller.signal, // AbortSignal
   );
 } catch (error) {
-  if (error.name === 'AbortError') {
+  if (error instanceof Error && error.name === 'AbortError') {
     console.log('파싱이 취소되었습니다');
   }
 }
@@ -494,35 +527,9 @@ try {
 
 ## 왜 macOS 전용인가?
 
-`@heripo/pdf-parser`는 **의도적으로 macOS에 강하게 의존**합니다. 이 결정의 핵심 이유는 **Docling SDK의 로컬 OCR 성능**입니다.
-
-### OCR 선택 배경
-
-고고학 발굴조사보고서 PDF는 다음과 같은 특성이 있습니다:
-
-- 수백 페이지 분량의 스캔 문서
-- 복잡한 표, 도면, 사진이 포함된 레이아웃
-- 정밀한 텍스트 추출이 필수적
-
-### OCR 옵션 비교
-
-| 방식                    | 성능  | 비용 | 설명                                    |
-| ----------------------- | ----- | ---- | --------------------------------------- |
-| **Docling (로컬)**      | ★★★★★ | 무료 | Apple Silicon에서 압도적 성능, GPU 활용 |
-| Cloud OCR (Google, AWS) | ★★★★  | $$$  | 수백 페이지당 수십 달러                 |
-| Tesseract (로컬)        | ★★    | 무료 | 한국어 인식률 낮음, 레이아웃 분석 부족  |
-
-### 핵심 장점
+패키지는 `os: ["darwin"]`을 선언하고 `init()`에서 macOS와 로컬 도구를 확인합니다. `baseUrl`로 외부 Docling 서버를 연결해도 이 클라이언트 제한은 유지됩니다. ocrmac OCR은 macOS의 Apple Vision을 사용합니다.
 
-- **비용**: 클라우드 OCR 대비 100배 이상 저렴 (무료)
-- **성능**: Apple Silicon M1/M2/M3/M4/M5에서 GPU 가속으로 빠른 처리
-- **품질**: 복잡한 레이아웃의 문서도 정확히 인식
-- **프라이버시**: 문서가 외부 서버로 전송되지 않음
-
-### Trade-off
-
-- macOS + Apple Silicon 환경에서만 최적 성능
-- Linux/Windows 지원은 현재 계획 없음 (아래 "Linux 지원 현황" 참고)
+Docling OCR은 로컬에서 실행할 수 있지만 VLM 보정에는 설정한 모델을 호출합니다. 클라우드 모델을 선택하면 문서 텍스트와 페이지 이미지가 해당 provider로 전송될 수 있고 API 비용이 발생합니다. 전체 처리를 로컬에 유지하려면 언어 감지·문서 검증·보정·fallback·후속 문서 처리 모델까지 로컬로 설정해야 합니다.
 
 ## 시스템 의존성 상세
 
@@ -534,17 +541,18 @@ try {
 | poppler     | Any        | `brew install poppler`     | PDF 페이지 수 확인 (pdfinfo) 및 텍스트 레이어 추출 (pdftotext) |
 | jq          | Any        | `brew install jq`          | JSON 처리 (변환 결과 파싱)                                     |
 | lsof        | Any        | macOS 기본 설치됨          | docling-serve 포트 관리                                        |
-| ImageMagick | Any (선택) | `brew install imagemagick` | 이미지 PDF 폴백 및 페이지 렌더링                               |
-| Ghostscript | Any (선택) | `brew install ghostscript` | 이미지 PDF 폴백 (PDF를 이미지로 변환)                          |
+| ImageMagick | Any        | `brew install imagemagick` | 이미지 PDF 폴백 및 페이지 렌더링                               |
+| Ghostscript | Any        | `brew install ghostscript` | 이미지 PDF 폴백 (PDF를 이미지로 변환)                          |
 
-> **Python 3.13+는 지원하지 않습니다.** Docling SDK의 일부 의존성이 Python 3.13과 호환되지 않습니다.
+> **현재 설치 코드는 Python 3.13 이상을 거부합니다.** [python-version.ts](./src/utils/python-version.ts)의 검사를 참고하세요.
 
 ### Python 버전 확인
 
 ```bash
 # 설치된 Python 버전 확인
 python3 --version
-python3.11 --version
+export PATH="$(brew --prefix python@3.11)/libexec/bin:$PATH"
+python3 --version
 
 # 여러 버전이 설치된 경우
 ls -la /usr/local/bin/python*
@@ -569,12 +577,12 @@ which jq
 ```typescript
 type Options = {
   logger: LoggerMethods; // 로거 인스턴스 (필수)
-  timeout?: number; // 타임아웃 (밀리초, 기본값: 10000000)
+  timeout?: number; // 타임아웃 (밀리초, 기본값: 100000)
   venvPath?: string; // Python venv 경로 (기본값: CWD/.venv)
   killExistingProcess?: boolean; // 포트의 기존 프로세스 종료 (기본값: false)
   enableImagePdfFallback?: boolean; // 이미지 PDF 폴백 활성화 (기본값: false, ImageMagick + Ghostscript 필요)
 } & (
-  | { port?: number } // 로컬 서버 모드 (기본 포트: 5001)
+  | { port?: number } // 로컬 모드; port를 명시해야 함 (런타임 기본값 없음)
   | { baseUrl: string } // 외부 서버 모드
 );
 ```
@@ -614,6 +622,10 @@ PDF 파일을 파싱합니다.
 await pdfParser.dispose();
 ```
 
+##### `isReady(): Promise<boolean>` / `ensureReady(): Promise<void>`
+
+`isReady()`는 복구 없이 상태만 확인합니다. 초기화 후 사용하는 `ensureReady()`는 로컬 서버 복구를 시도하며 외부 서버 오류는 그대로 전달합니다. `dispose()`는 재사용한 서버를 포함해 설정된 로컬 포트의 프로세스를 종료하므로 외부에서 수명을 관리하는 서버는 `baseUrl`로 연결하세요.
+
 ### PDFConvertOptions
 
 ```typescript
@@ -630,6 +642,8 @@ type PDFConvertOptions = {
 
   // 문서 처리
   document_timeout?: number; // 문서 처리 타임아웃 (초)
+  languageDetectionModel?: LanguageModel;
+  languageDetectionFallbackModel?: LanguageModel;
   documentValidationModel?: LanguageModel; // 문서 유형 검증용 LLM
 
   // 보정 진행 상황
@@ -686,7 +700,7 @@ interface PDFCorrectionOptions {
   concurrency?: {
     pages?: number; // 페이지 단위 text correction/page gate 동시성
     reviewTasks?: number; // 구조 Review Assistance work-item 동시성
-    tables?: number; // 표 전용 보정 동시성
+    tables?: number; // Accepted but not forwarded by the top-level pipeline
   };
   maxRetries?: {
     textCorrection?: number;
@@ -800,31 +814,12 @@ brew install imagemagick ghostscript
 
 ## Linux 지원 현황
 
-현재 **macOS 전용**입니다. Linux 지원은 **완전히 배제한 것은 아니지만**, OCR 성능과 비용 효율성 문제로 **현재는 구체적인 계획이 없습니다**.
-
-| 플랫폼                | 상태 | 비고                            |
-| --------------------- | ---- | ------------------------------- |
-| macOS + Apple Silicon | 지원 | 최적 성능, GPU 가속             |
-| macOS + Intel         | 지원 | GPU 가속 없음                   |
-| Linux                 | 미정 | 성능/비용 문제로 현재 계획 없음 |
-| Windows               | 미정 | WSL2 통한 Linux 방식 고려 가능  |
-
-### Linux 미지원 사유
-
-Docling SDK의 로컬 OCR은 macOS에서 Apple Metal GPU 가속을 활용해 성능과 비용 효율성을 모두 달성합니다. Linux에서 동등한 성능과 비용 효율성을 제공하는 OCR 솔루션을 아직 찾지 못했습니다.
-
-### 아이디어 제안 환영
-
-성능과 비용을 모두 잡으면서 Linux를 지원할 수 있는 아이디어가 있다면, [GitHub Discussions](https://github.com/heripo-lab/heripo-engine/discussions) 또는 Issue로 제안해 주세요. 특히 다음과 같은 정보가 도움이 됩니다:
-
-- Linux에서 한국어 문서 OCR 경험
-- 복잡한 레이아웃(표, 도면) 처리 가능한 OCR 솔루션
-- 수백 페이지 처리 시 비용 추산
+현재 `@heripo/pdf-parser`는 macOS 전용이며 Linux/Windows 실행 경로를 제공하지 않습니다. 플랫폼 관련 제안은 [GitHub Discussions](https://github.com/heripo-lab/heripo-engine/discussions)에 남겨주세요.
 
 ## 관련 패키지
 
-- [@heripo/document-processor](../document-processor) - 문서 구조 분석 및 LLM 처리
-- [@heripo/model](../model) - 데이터 모델 및 타입 정의
+- [@heripo/document-processor](../document-processor/README.ko.md) - 문서 구조 분석 및 LLM 처리
+- [@heripo/model](../model/README.ko.md) - 데이터 모델 및 타입 정의
 
 ## 후원
 
@@ -839,13 +834,13 @@ heripo lab의 오픈소스 연구를 후원하려면 다음 경로를 이용할
 
 ## 기여하기
 
-기여는 언제나 환영합니다! [기여 가이드](../../CONTRIBUTING.ko.md)를 참고하세요.
+기여는 언제나 환영합니다! [기여 가이드](../../CONTRIBUTING.md)를 참고하세요.
 
 ## 이슈 및 지원
 
 - **버그 리포트**: [GitHub Issues](https://github.com/heripo-lab/heripo-engine/issues)
 - **토론**: [GitHub Discussions](https://github.com/heripo-lab/heripo-engine/discussions)
-- **보안 취약점**: [보안 정책](../../SECURITY.ko.md) 참고
+- **보안 취약점**: [보안 정책](../../SECURITY.md) 참고
 
 ## 프로젝트 전체 정보
 

package/README.md

@@ -37,8 +37,8 @@
 ## Key Features
 
 - **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
+- **Mandatory VLM Correction**: Post-Docling text correction always runs; page gating and structural review can be disabled
+- **Apple Silicon Backend**: Docling conversion requests the `mps` accelerator
 - **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
@@ -65,22 +65,23 @@
 brew install node
 ```
 
-#### 2. pnpm >= 11
+#### 2. pnpm >= 12
 
 ```bash
-npm install -g pnpm
+npm install -g pnpm@12
 ```
 
 #### 3. Python 3.9 - 3.12
 
-> **Important**: Python 3.13+ is not supported. Some Docling SDK dependencies are not compatible with Python 3.13.
+> **Important**: The current installer accepts Python 3.9–3.12 and rejects 3.13+. This is the repository's version check, not a compatibility statement for every upstream Docling release.
 
 ```bash
 # Install Python 3.11 (recommended)
 brew install python@3.11
 
 # Verify version
-python3.11 --version
+export PATH="$(brew --prefix python@3.11)/libexec/bin:$PATH"
+python3 --version
 ```
 
 #### 4. poppler (PDF text extraction)
@@ -105,9 +106,9 @@ Installed by default on macOS. Verify:
 which lsof
 ```
 
-#### 7. ImageMagick + Ghostscript (optional)
+#### 7. ImageMagick + Ghostscript
 
-Required only when using the image PDF fallback feature (`enableImagePdfFallback` or `forceImagePdf`).
+Required for rendering local PDF pages used by mandatory VLM correction, as well as image-PDF fallback. Install these even when `enableImagePdfFallback` and `forceImagePdf` are disabled.
 
 ```bash
 brew install imagemagick ghostscript
@@ -121,25 +122,27 @@ When using `@heripo/pdf-parser` for the first time, it automatically:
 2. Installs `docling-serve` and dependencies
 3. Starts docling-serve process on local port
 
-This setup runs only once and may take 5-10 minutes depending on internet connection.
+The virtual environment is reused, but local initialization runs dependency setup again. The installer pins docling-serve 1.16.1 and an explicit Docling runtime set; see [python-environment.ts](./src/environment/python-environment.ts). Ensure the `python3` command on PATH is a supported version, not just a separately installed `python3.11`.
 
 ## Installation
 
 ```bash
 # Install with npm
-npm install @heripo/pdf-parser @heripo/logger
+npm install @heripo/pdf-parser @heripo/logger @ai-sdk/openai
 
 # Install with pnpm
-pnpm add @heripo/pdf-parser @heripo/logger
+pnpm add @heripo/pdf-parser @heripo/logger @ai-sdk/openai
 
 # Install with yarn
-yarn add @heripo/pdf-parser @heripo/logger
+yarn add @heripo/pdf-parser @heripo/logger @ai-sdk/openai
 ```
 
 ## Usage
 
 ### Basic Usage
 
+Use an ESM project. `HERIPO_MODEL` is an example-specific environment variable for a model ID supporting image input and structured output; also set `OPENAI_API_KEY`. Other providers can be supplied through their AI SDK adapters.
+
 ```typescript
 import { openai } from '@ai-sdk/openai';
 import { Logger } from '@heripo/logger';
@@ -158,33 +161,37 @@ const pdfParser = new PDFParser({
   logger,
 });
 
-const correctionModel = openai('gpt-5.1');
+const correctionModel = openai(process.env.HERIPO_MODEL!);
 
 // 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
-  async (outputPath) => {
-    // Conversion complete callback
-    console.log('PDF conversion complete:', outputPath);
-  },
-  false, // cleanupAfterCallback
-  {
-    correction: {
-      models: {
-        textCorrection: correctionModel,
-        pageGate: correctionModel,
-        reviewAssistance: correctionModel,
-      },
+try {
+  await pdfParser.init();
+
+  // Parse PDF
+  const tokenUsageReport = await pdfParser.parse(
+    'file:///path/to/report.pdf', // PDF URL (file:// or http://)
+    'report-001', // Report ID
+    async (outputPath) => {
+      // Conversion complete callback
+      console.log('PDF conversion complete:', outputPath);
     },
-  }, // PDFConvertOptions
-);
+    false, // cleanupAfterCallback
+    {
+      correction: {
+        models: {
+          textCorrection: correctionModel,
+          pageGate: correctionModel,
+          reviewAssistance: correctionModel,
+        },
+      },
+    }, // PDFConvertOptions
+  );
 
-// Token usage report (null when no LLM usage)
-console.log('Token usage:', tokenUsageReport);
+  // Token usage report (null when no LLM usage)
+  console.log('Token usage:', tokenUsageReport);
+} finally {
+  await pdfParser.dispose();
+}
 ```
 
 ### Advanced Options
@@ -193,7 +200,7 @@ console.log('Token usage:', tokenUsageReport);
 // Option A: Use local server with port
 const pdfParser = new PDFParser({
   logger,
-  port: 5001,                      // Port to use (default: 5001)
+  port: 5001,                      // Set the local port explicitly
   timeout: 10000000,                // Timeout (milliseconds)
   venvPath: '/custom/path/.venv',   // Custom venv path (default: CWD/.venv)
   killExistingProcess: true,        // Kill existing process on port (default: false)
@@ -216,13 +223,13 @@ const tokenUsageReport = await pdfParser.parse(
     // 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'),
+        textCorrection: openai(process.env.HERIPO_MODEL!),
+        pageGate: openai(process.env.HERIPO_MODEL!),
+        reviewAssistance: openai(process.env.HERIPO_MODEL!),
+        tableCorrection: openai(process.env.HERIPO_MODEL!),
         reviewAssistanceTasks: {
-          text_ocr_hanja: openai('gpt-5.1'),
-          tables: openai('gpt-5.1'),
+          text_ocr_hanja: openai(process.env.HERIPO_MODEL!),
+          tables: openai(process.env.HERIPO_MODEL!),
         },
       },
       concurrency: {
@@ -246,7 +253,7 @@ const tokenUsageReport = await pdfParser.parse(
     onReviewAssistanceProgress: (event) => console.log(event),
 
     // Document validation
-    documentValidationModel: openai('gpt-5.1'),
+    documentValidationModel: openai(process.env.HERIPO_MODEL!),
 
     // Chunked conversion for large PDFs
     chunkedConversion: true,
@@ -265,6 +272,12 @@ const tokenUsageReport = await pdfParser.parse(
 );
 ```
 
+### Artifacts
+
+The callback receives the absolute `output/<reportId>/` path. `result.json` is the corrected document and `result_ocr_origin.json` is the initial OCR snapshot. `images/` and `pages/` hold extracted and page images. Structural review also produces `result_review_origin.json`, `review_assistance_page_gate.json`, `review_assistance_checkpoint.json` and `review_assistance.json`. Check page status, issues and call traces for failed review work.
+
+With `cleanupAfterCallback: true`, the artifact directory is removed after the callback. Copy required files elsewhere inside it or use `false` to preserve them. The parser does not create `result-processed.json` or a handoff manifest; the demo worker saves those separately.
+
 ### Resource Cleanup
 
 Clean up resources after work is complete:
@@ -278,15 +291,15 @@ await pdfParser.dispose();
 
 ### 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.
+ocrmac is the fixed OCR backend, using Apple Vision on macOS.
 
-`@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.
+`@heripo/pdf-parser` no longer samples OCR strategies or switches to a VLM OCR path. Docling conversion always uses ocrmac. VLM correction runs after Docling conversion. Optional language detection and document validation can also call a model before conversion.
 
 ### 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:
+With the default review controls enabled, the correction stage runs as follows:
 
 1. Save `result_ocr_origin.json` before mutations.
 2. Run page-level text and table-cell OCR correction with `textCorrection`.
@@ -299,21 +312,39 @@ Text correction applies to every page with text or table content. The page gate
 
 ### 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`, `modelConcurrency: 1`, `temperature: 0`, and a generous `workItemTimeoutMs`. Increase concurrency only after the model is stable.
+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.reviewTasks: 1`, `modelConcurrency: 1`, `temperature: 0`, and a generous `workItemTimeoutMs`. Increase concurrency only after the model is stable.
 
-### Rollout Smoke Test
+### Validation
 
-Repository contributors can run the correction rollout smoke test against two local demo archaeological report artifacts:
+Run the defined package check with `pnpm --filter @heripo/pdf-parser test:coverage`. Tests mock external model calls; correction quality on real documents requires separate evaluation.
 
-```bash
-pnpm --filter @heripo/pdf-parser smoke:correction
-```
+### Correction Controls and Defaults
 
-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.
+All three required models must still be supplied when structural review is disabled. `reviewAssistanceEnabled: false` runs only text/table-cell OCR correction, skipping the page gate and structural review. `tableCorrectionEnabled: false` skips structural table work items, but does not disable initial table-cell OCR correction.
+
+`forceAutoApply` defaults to `false`. When true, validated commands are applied without routing to manual review based on confidence thresholds or structural block reasons. Command validation still runs.
+
+| Option                                               | Default                |
+| ---------------------------------------------------- | ---------------------- |
+| `concurrency.pages`                                  | `1`                    |
+| `concurrency.reviewTasks`                            | `6`                    |
+| `modelConcurrency`                                   | `1`                    |
+| `maxRetries.*`                                       | `3`                    |
+| `workItemTimeoutMs`                                  | `1800000` (30 minutes) |
+| `outputLanguage`                                     | `en-US`                |
+| `autoApplyThreshold` / `proposalThreshold`           | `0.85` / `0.5`         |
+| `reviewAssistanceEnabled` / `tableCorrectionEnabled` | `true` / `true`        |
+| `forceAutoApply` / `temperature`                     | `false` / `0`          |
+
+Defaults are also exported as `PDF_CORRECTION_DEFAULTS`. `concurrency.tables` and `pageGate.structuralNoiseThreshold` exist in the type but are not forwarded as runner controls by the current top-level pipeline. Use `reviewTasks` and `modelConcurrency` to bound table work.
+
+### Language Detection
+
+Explicit `ocr_lang` values take precedence. Otherwise local PDF text is inspected, with optional vision-based detection through `languageDetectionModel` and `languageDetectionFallbackModel` when needed. Remote inputs and undetected inputs use `ko-KR`, `en-US` as defaults. This does not select an OCR engine: OCR remains ocrmac.
 
 ## Review Assistance
 
-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.
+Review Assistance runs after text correction when `correction.reviewAssistanceEnabled` is true (library default), 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.
 
 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`.
 
@@ -330,10 +361,10 @@ const tokenUsageReport = await pdfParser.parse(
   {
     correction: {
       models: {
-        textCorrection: openai('gpt-5.1'),
-        pageGate: openai('gpt-5.1-mini'),
-        reviewAssistance: openai('gpt-5.1'),
-        tableCorrection: openai('gpt-5.1'),
+        textCorrection: openai(process.env.HERIPO_MODEL!),
+        pageGate: openai(process.env.HERIPO_MODEL!),
+        reviewAssistance: openai(process.env.HERIPO_MODEL!),
+        tableCorrection: openai(process.env.HERIPO_MODEL!),
       },
       autoApplyThreshold: 0.85,
       proposalThreshold: 0.5,
@@ -353,7 +384,7 @@ const tokenUsageReport = await pdfParser.parse(
 );
 ```
 
-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.
+Use a local `file://` PDF for the complete pipeline. HTTP inputs are accepted by Docling, but local page rendering, language detection and document validation are skipped. Missing `pages/page_<index>.png` files cause text correction to be skipped; a successful callback does not prove every page was corrected. Failed correction calls retain the original OCR text and emit warnings. 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
 
@@ -371,12 +402,12 @@ try {
     {
       correction: {
         models: {
-          textCorrection: openai('gpt-5.1'),
-          pageGate: openai('gpt-5.1'),
-          reviewAssistance: openai('gpt-5.1'),
+          textCorrection: openai(process.env.HERIPO_MODEL!),
+          pageGate: openai(process.env.HERIPO_MODEL!),
+          reviewAssistance: openai(process.env.HERIPO_MODEL!),
         },
       },
-      documentValidationModel: openai('gpt-5.1'),
+      documentValidationModel: openai(process.env.HERIPO_MODEL!),
     },
   );
 } catch (error) {
@@ -399,18 +430,20 @@ const tokenUsageReport = await pdfParser.parse(
   {
     correction: {
       models: {
-        textCorrection: openai('gpt-5.1'),
-        pageGate: openai('gpt-5.1'),
-        reviewAssistance: openai('gpt-5.1'),
+        textCorrection: openai(process.env.HERIPO_MODEL!),
+        pageGate: openai(process.env.HERIPO_MODEL!),
+        reviewAssistance: openai(process.env.HERIPO_MODEL!),
       },
     },
     chunkedConversion: true,
-    chunkSize: 50, // Pages per chunk (default: configured in constants)
-    chunkMaxRetries: 3, // Max retry attempts per failed chunk (default: configured in constants)
+    chunkSize: 50, // Pages per chunk (default: 10)
+    chunkMaxRetries: 3, // Retries per failed chunk (default: 2)
   },
 );
 ```
 
+Correction runs after chunk results are merged. The current chunked failure path attempts image-PDF conversion independently of `enableImagePdfFallback`, so ImageMagick/Ghostscript are needed for that recovery path too. For local inputs, the chunked branch takes precedence when `chunkedConversion` and `forceImagePdf` are both set.
+
 ## Image PDF Fallback
 
 When conversion fails, the parser can automatically fall back to converting the PDF to an image-based PDF first, then retrying conversion. This is useful for PDFs with complex or corrupt structures. Requires ImageMagick and Ghostscript.
@@ -440,9 +473,9 @@ const tokenUsageReport = await pdfParser.parse(
   {
     correction: {
       models: {
-        textCorrection: openai('gpt-5.1'),
-        pageGate: openai('gpt-5.1'),
-        reviewAssistance: openai('gpt-5.1'),
+        textCorrection: openai(process.env.HERIPO_MODEL!),
+        pageGate: openai(process.env.HERIPO_MODEL!),
+        reviewAssistance: openai(process.env.HERIPO_MODEL!),
       },
     },
     forceImagePdf: true, // Always convert to image PDF first
@@ -471,16 +504,16 @@ try {
     {
       correction: {
         models: {
-          textCorrection: openai('gpt-5.1'),
-          pageGate: openai('gpt-5.1'),
-          reviewAssistance: openai('gpt-5.1'),
+          textCorrection: openai(process.env.HERIPO_MODEL!),
+          pageGate: openai(process.env.HERIPO_MODEL!),
+          reviewAssistance: openai(process.env.HERIPO_MODEL!),
         },
       },
     },
     controller.signal, // AbortSignal
   );
 } catch (error) {
-  if (error.name === 'AbortError') {
+  if (error instanceof Error && error.name === 'AbortError') {
     console.log('Parsing was cancelled');
   }
 }
@@ -494,35 +527,9 @@ When using a local docling-serve instance (port mode), the parser automatically
 
 ## Why macOS Only?
 
-`@heripo/pdf-parser` **intentionally relies heavily on macOS**. The key reason for this decision is **Docling SDK's local OCR performance**.
-
-### OCR Selection Background
-
-Archaeological excavation report PDFs have the following characteristics:
-
-- Scanned documents spanning hundreds of pages
-- Layouts containing complex tables, diagrams, photographs
-- Precise text extraction is essential
-
-### OCR Option Comparison
-
-| Method                  | Performance | Cost | Description                                                |
-| ----------------------- | ----------- | ---- | ---------------------------------------------------------- |
-| **Docling (Local)**     | ★★★★★       | Free | Overwhelming performance on Apple Silicon, GPU utilization |
-| Cloud OCR (Google, AWS) | ★★★★        | $$$  | Tens of dollars per hundreds of pages                      |
-| Tesseract (Local)       | ★★          | Free | Low Korean recognition rate, lacking layout analysis       |
-
-### Key Advantages
+The package declares `os: ["darwin"]` and checks macOS and local tools in `init()`. Connecting to an external Docling server through `baseUrl` does not remove this client-side restriction. ocrmac uses Apple Vision on macOS.
 
-- **Cost**: 100x+ cheaper than cloud OCR (free)
-- **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
-
-### Trade-off
-
-- Optimal performance only in macOS + Apple Silicon environment
-- No current plans for Linux/Windows support (see "Linux Support Status" below)
+Docling OCR can run locally, but VLM correction calls the configured models. Cloud models can receive document text and page images and incur API charges. To keep the full pipeline local, configure local models for language detection, document validation, correction, fallbacks and downstream document processing.
 
 ## System Dependencies Details
 
@@ -534,17 +541,18 @@ Archaeological excavation report PDFs have the following characteristics:
 | poppler     | Any              | `brew install poppler`     | PDF page counting (pdfinfo) and text layer extraction (pdftotext) |
 | jq          | Any              | `brew install jq`          | JSON processing (conversion result parsing)                       |
 | lsof        | Any              | Included with macOS        | docling-serve port management                                     |
-| ImageMagick | Any (optional)   | `brew install imagemagick` | Image PDF fallback and page rendering                             |
-| Ghostscript | Any (optional)   | `brew install ghostscript` | Image PDF fallback (PDF to image conversion)                      |
+| ImageMagick | Any              | `brew install imagemagick` | Image PDF fallback and page rendering                             |
+| Ghostscript | Any              | `brew install ghostscript` | Image PDF fallback (PDF to image conversion)                      |
 
-> **Python 3.13+ is not supported.** Some Docling SDK dependencies are not compatible with Python 3.13.
+> **Python 3.13+ is rejected by the current installer.** See the version check in [python-version.ts](./src/utils/python-version.ts).
 
 ### Checking Python Version
 
 ```bash
 # Check installed Python version
 python3 --version
-python3.11 --version
+export PATH="$(brew --prefix python@3.11)/libexec/bin:$PATH"
+python3 --version
 
 # When multiple versions are installed
 ls -la /usr/local/bin/python*
@@ -569,12 +577,12 @@ which jq
 ```typescript
 type Options = {
   logger: LoggerMethods; // Logger instance (REQUIRED)
-  timeout?: number; // Timeout in milliseconds (default: 10000000)
+  timeout?: number; // Timeout in milliseconds (default: 100000)
   venvPath?: string; // Python venv path (default: CWD/.venv)
   killExistingProcess?: boolean; // Kill existing process on port (default: false)
   enableImagePdfFallback?: boolean; // Enable image PDF fallback (default: false, requires ImageMagick + Ghostscript)
 } & (
-  | { port?: number } // Local server mode (default port: 5001)
+  | { port?: number } // Local mode; explicitly provide port (no runtime default)
   | { baseUrl: string } // External server mode
 );
 ```
@@ -614,6 +622,10 @@ Disposes the parser instance, kills the local docling-serve process (if started)
 await pdfParser.dispose();
 ```
 
+##### `isReady(): Promise<boolean>` / `ensureReady(): Promise<void>`
+
+`isReady()` checks health without recovery. `ensureReady()` requires initialization and attempts recovery for a local server. External server failures are propagated. `dispose()` also terminates a process on the configured local port, including a reused server; use `baseUrl` for an externally managed lifecycle.
+
 ### PDFConvertOptions
 
 ```typescript
@@ -630,6 +642,8 @@ type PDFConvertOptions = {
 
   // Document processing
   document_timeout?: number; // Document processing timeout in seconds
+  languageDetectionModel?: LanguageModel;
+  languageDetectionFallbackModel?: LanguageModel;
   documentValidationModel?: LanguageModel; // LLM for document type validation
 
   // Correction progress
@@ -686,7 +700,7 @@ interface PDFCorrectionOptions {
   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
+    tables?: number; // Accepted but not forwarded by the top-level pipeline
   };
   maxRetries?: {
     textCorrection?: number;
@@ -800,31 +814,12 @@ brew install imagemagick ghostscript
 
 ## Linux Support Status
 
-Currently **macOS only**. Linux support is **not entirely ruled out**, but due to OCR performance and cost efficiency issues, **there are no specific plans at this time**.
-
-| Platform              | Status    | Notes                                           |
-| --------------------- | --------- | ----------------------------------------------- |
-| macOS + Apple Silicon | Supported | Optimal performance, GPU acceleration           |
-| macOS + Intel         | Supported | No GPU acceleration                             |
-| Linux                 | TBD       | No current plans due to performance/cost issues |
-| Windows               | TBD       | WSL2 Linux approach possible                    |
-
-### Reason for No Linux Support
-
-Docling SDK's local OCR achieves both performance and cost efficiency by utilizing Apple Metal GPU acceleration on macOS. We have not yet found an OCR solution on Linux that provides equivalent performance and cost efficiency.
-
-### Ideas Welcome
-
-If you have ideas for supporting Linux while maintaining both performance and cost efficiency, please suggest them via [GitHub Discussions](https://github.com/heripo-lab/heripo-engine/discussions) or Issues. The following information is particularly helpful:
-
-- Experience with Korean document OCR on Linux
-- OCR solutions capable of handling complex layouts (tables, diagrams)
-- Cost estimates for processing hundreds of pages
+The current `@heripo/pdf-parser` package supports macOS and does not provide a Linux/Windows runtime path. Platform proposals are welcome in [GitHub Discussions](https://github.com/heripo-lab/heripo-engine/discussions).
 
 ## Related Packages
 
-- [@heripo/document-processor](../document-processor) - Document structure analysis and LLM processing
-- [@heripo/model](../model) - Data models and type definitions
+- [@heripo/document-processor](../document-processor/README.md) - Document structure analysis and LLM processing
+- [@heripo/model](../model/README.md) - Data models and type definitions
 
 ## Sponsor
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@heripo/pdf-parser",
   "private": false,
   "type": "module",
-  "version": "0.1.44",
+  "version": "0.1.45",
   "description": "PDF parsing library using Docling SDK with OCR support for macOS",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -55,13 +55,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@heripo/logger": "0.1.44",
-    "@heripo/model": "0.1.44",
-    "ai": "^7.0.91",
+    "@heripo/logger": "0.1.45",
+    "@heripo/model": "0.1.45",
+    "ai": "^7.0.107",
     "docling-sdk": "^2.0.6",
     "es-toolkit": "^1.52.0",
     "yauzl": "3.4.0",
-    "zod": "^4.5.4"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
     "@heripo/shared": "0.0.0",
@@ -69,10 +69,10 @@
     "@heripo/tsup-config": "0.0.0",
     "@heripo/vitest-config": "0.0.0",
     "@types/yauzl": "^3.4.0",
-    "@vitest/coverage-v8": "^5.0.0",
-    "@vitest/expect": "^5.0.0",
+    "@vitest/coverage-v8": "^5.0.1",
+    "@vitest/expect": "^5.0.1",
     "tsup": "^8.5.1",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.1"
   },
   "scripts": {
     "clean": "rimraf dist",