@heripo/document-processor 0.1.44 → 0.1.46

package/README.ko.md

@@ -56,6 +56,14 @@ npm install ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google
 
 ## 사용법
 
+### 실행 조건과 결과 저장
+
+이 패키지는 Node.js 24 이상에서 사용하는 ESM 라이브러리입니다. Python이나 macOS는 이 패키지 자체의 필수 조건이 아니며, PDF를 만드는 `@heripo/pdf-parser`에서 요구합니다. AI SDK/provider 버전은 저장소의 [catalog](../../pnpm-workspace.yaml)와 맞추세요.
+
+아래 예제의 `doclingDocument`는 파서의 보정된 `result.json`, `artifactDir`는 해당 이미지·페이지 산출물이 있는 디렉터리입니다. 기본 모델은 개별 모델이 생략된 모든 컴포넌트에도 사용되므로 이미지 입력과 구조화된 출력을 지원해야 합니다. 예제용 환경 변수 `HERIPO_ANTHROPIC_MODEL`과 `HERIPO_OPENAI_MODEL`에 사용할 모델 ID를 설정하고, 선택한 provider의 API 키도 설정하세요.
+
+`process()`는 파일을 저장하지 않습니다. 반환한 `document`를 직접 JSON으로 저장하고 참조 이미지도 보존하세요. 출력 `schemaVersion`은 내보낸 `PROCESSED_DOCUMENT_SCHEMA_VERSION` 값인 `processed-document.v2`입니다.
+
 ### 기본 사용법
 
 ```typescript
@@ -73,7 +81,7 @@ const logger = new Logger({
 // 기본 사용 - fallback 모델만 지정
 const processor = new DocumentProcessor({
   logger,
-  fallbackModel: anthropic('claude-opus-4-5'),
+  fallbackModel: anthropic(process.env.HERIPO_ANTHROPIC_MODEL!),
   textCleanerBatchSize: 10,
   captionParserBatchSize: 5,
   captionValidatorBatchSize: 5,
@@ -103,14 +111,14 @@ import { openai } from '@ai-sdk/openai';
 const processor = new DocumentProcessor({
   logger,
   // Fallback 모델 (실패 시 재시도용)
-  fallbackModel: anthropic('claude-opus-4-5'),
+  fallbackModel: anthropic(process.env.HERIPO_ANTHROPIC_MODEL!),
 
   // 컴포넌트별 모델 지정
-  pageRangeParserModel: openai('gpt-5.1'), // Vision 필요
-  tocExtractorModel: openai('gpt-5.1'), // 구조화 출력
-  validatorModel: openai('gpt-5.2'), // 간단한 검증
-  visionTocExtractorModel: openai('gpt-5.1'), // Vision 필요
-  captionParserModel: openai('gpt-5-mini'), // 캡션 파싱
+  pageRangeParserModel: openai(process.env.HERIPO_OPENAI_MODEL!), // Vision 필요
+  tocExtractorModel: openai(process.env.HERIPO_OPENAI_MODEL!), // 구조화 출력
+  validatorModel: openai(process.env.HERIPO_OPENAI_MODEL!), // 간단한 검증
+  visionTocExtractorModel: openai(process.env.HERIPO_OPENAI_MODEL!), // Vision 필요
+  captionParserModel: openai(process.env.HERIPO_OPENAI_MODEL!), // 캡션 파싱
 
   // 배치 크기 설정
   textCleanerBatchSize: 20, // 동기 처리 (크게 가능)
@@ -228,7 +236,7 @@ console.log(document.images[0].captionSourceRefs);
 
 `sourceRefValidationMode: 'error'`는 누락된 참조가 있으면 처리를 실패시킵니다. `validateSourceRefs: true`는 호환용 단축 옵션이며, 별도 mode를 지정하지 않으면 `'error'`와 같습니다.
 
-테이블 셀에는 cell-level `sourceRef`를 만들지 않습니다. 특정 셀의 원천 위치는 `table.sourceRef`와 `grid[row][col]`의 row/column index를 함께 사용해 추적합니다.
+테이블 셀에는 개별 `sourceRef`가 없습니다. `table.sourceRef`로 원천 표를 찾고 span과 원천 셀 좌표를 대조하세요. 압축된 `grid`의 배열 인덱스는 원천 표의 논리적 열 번호와 다를 수 있습니다.
 
 ### 테이블 그리드 처리
 
@@ -239,7 +247,7 @@ console.log(document.images[0].captionSourceRefs);
 - Docling이 병합 셀의 덮인 영역을 반복 제공하는 경우 shadow entry 제거
 - Docling의 `data.grid`가 비어 있으면 `table_cells`에서 그리드 구성
 
-`numRows`와 `numCols`는 논리적 테이블 크기를 유지합니다. 개별 셀에는 `sourceRef`를 저장하지 않으므로, 셀의 원천 위치를 추적할 때는 `table.sourceRef`와 `grid[row][col]` 위치를 함께 사용합니다.
+`numRows`와 `numCols`는 논리적 테이블 크기이며 각 배열의 길이와 같다고 가정하면 안 됩니다. 렌더링 시 `rowSpan`과 `colSpan`으로 이미 덮인 위치를 건너뛰세요.
 
 ## 처리 파이프라인
 
@@ -294,6 +302,8 @@ DocumentProcessor는 다음 5단계 파이프라인으로 문서를 처리합니
 
 ### 5. 챕터 변환 (ChapterConverter)
 
+`Front Matter` (`ch-000`) 챕터를 항상 첫 항목으로 생성하여 첫 목차 항목 이전의 내용을 보존합니다. 이후 계층은 제공·추출한 TOC로 구성됩니다.
+
 - TOC 기반 챕터 트리 구성
 - Chapter 계층 생성
 - 페이지 범위별로 텍스트 블록을 챕터에 연결
@@ -371,8 +381,8 @@ interface DocumentProcessorProcessOptions {
 ```typescript
 const processor = new DocumentProcessor({
   logger,
-  fallbackModel: anthropic('claude-opus-4-5'), // 재시도용
-  pageRangeParserModel: openai('gpt-5.2'), // 첫 시도
+  fallbackModel: anthropic(process.env.HERIPO_ANTHROPIC_MODEL!), // 재시도용
+  pageRangeParserModel: openai(process.env.HERIPO_OPENAI_MODEL!), // 첫 시도
   enableFallbackRetry: true, // 실패 시 fallback 사용 (기본값: false)
   textCleanerBatchSize: 10,
   captionParserBatchSize: 5,
@@ -386,8 +396,10 @@ const { document, usage } = await processor.process(doc, 'id', 'path');
 ### 배치 크기 파라미터
 
 - **textCleanerBatchSize**: 동기 텍스트 정규화 및 필터링 배치 크기. 로컬 처리이므로 큰 값 가능
-- **captionParserBatchSize**: LLM 기반 캡션 파싱 배치 크기. API 요청 동시성 및 비용 관리를 위해 작은 값 사용
-- **captionValidatorBatchSize**: LLM 기반 캡션 검증 배치 크기. 검증 요청 동시성 제한을 위해 작은 값 사용
+- **captionParserBatchSize**: LLM 기반 캡션 파싱 배치 크기. 요청 하나에 포함하는 캡션 수 조절
+- **captionValidatorBatchSize**: LLM 기반 캡션 검증 배치 크기. 검증할 캡션 묶음 크기 조절
+
+`textCleanerBatchSize`, `captionParserBatchSize`, `captionValidatorBatchSize`는 `0`이면 묶음 처리 없이 순차 처리합니다. 묶음 처리를 사용할 때는 양의 정수로 지정하세요. 양수 배치 크기는 항목 묶음 크기이며 전체 API 호출 동시성의 상한은 아닙니다.
 
 ## 에러 처리
 
@@ -397,9 +409,15 @@ TOC 추출 실패 시 발생하는 에러들:
 
 - `TocNotFoundError`: 문서에서 TOC를 찾을 수 없음
 - `TocParseError`: LLM 응답 파싱 실패
-- `TocValidationError`: TOC 검증 실패
+- `TocValidationError`: 내부 검증 오류로 발생할 수 있지만 패키지 루트에서 export하지 않습니다. 공개 API에서는 `TocExtractError`를 사용해 처리하세요.
 
 ```typescript
+import {
+  TocExtractError,
+  TocNotFoundError,
+  TocParseError,
+} from '@heripo/document-processor';
+
 try {
   const { document, usage } = await processor.process(doc, 'id', 'path');
 } catch (error) {
@@ -407,6 +425,10 @@ try {
     console.error('TOC를 찾을 수 없습니다. 수동 TOC 검수가 필요합니다.');
   } else if (error instanceof TocParseError) {
     console.error('TOC 파싱 실패:', error.message);
+  } else if (error instanceof TocExtractError) {
+    console.error(error.message);
+  } else {
+    throw error;
   }
 }
 ```
@@ -436,18 +458,18 @@ import {
 
 ```typescript
 // PageRangeParser
-const { pageRangeMap, tokenUsage } = await pageRangeParser.parse(doc);
-console.log('토큰 사용:', tokenUsage);
+const { pageRangeMap, usage } = await pageRangeParser.parse(doc);
+console.log('Token usage:', usage);
 
 // TocExtractor
-const { entries, tokenUsage } = await tocExtractor.extract(markdown);
-console.log('토큰 사용:', tokenUsage);
+const { entries, usages } = await tocExtractor.extract(markdown);
+console.log('Token usage:', usages);
 ```
 
 ## 관련 패키지
 
-- [@heripo/pdf-parser](../pdf-parser) - PDF 파싱 및 OCR
-- [@heripo/model](../model) - 데이터 모델 및 타입 정의
+- [@heripo/pdf-parser](../pdf-parser/README.ko.md) - PDF 파싱 및 OCR
+- [@heripo/model](../model/README.ko.md) - 데이터 모델 및 타입 정의
 
 ## 후원
 
@@ -462,7 +484,7 @@ heripo lab의 오픈소스 연구를 후원하려면 다음 경로를 이용할
 
 ## 기여하기
 
-기여는 언제나 환영합니다! [기여 가이드](../../CONTRIBUTING.ko.md)를 참고하세요.
+기여는 언제나 환영합니다! [기여 가이드](../../CONTRIBUTING.md)를 참고하세요.
 
 ## 이슈 및 지원
 

package/README.md

@@ -56,6 +56,14 @@ npm install ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google
 
 ## Usage
 
+### Runtime and Result Persistence
+
+This package is an ESM library for Node.js 24+. It does not itself require Python or macOS; those requirements belong to `@heripo/pdf-parser`. Align AI SDK/provider versions with the repository [catalog](../../pnpm-workspace.yaml).
+
+In the examples, `doclingDocument` is the parser's corrected `result.json`, and `artifactDir` contains its image/page artifacts. The fallback model also serves every component without an explicit model, so it must support image input and structured output. Set the example-specific `HERIPO_ANTHROPIC_MODEL` and `HERIPO_OPENAI_MODEL` environment variables to available model IDs, and configure credentials for the selected providers.
+
+`process()` does not save files. Save the returned `document` as JSON and preserve referenced images yourself. Its `schemaVersion` is the exported `PROCESSED_DOCUMENT_SCHEMA_VERSION`, currently `processed-document.v2`.
+
 ### Basic Usage
 
 ```typescript
@@ -73,7 +81,7 @@ const logger = new Logger({
 // Basic usage - specify fallback model only
 const processor = new DocumentProcessor({
   logger,
-  fallbackModel: anthropic('claude-opus-4-5'),
+  fallbackModel: anthropic(process.env.HERIPO_ANTHROPIC_MODEL!),
   textCleanerBatchSize: 10,
   captionParserBatchSize: 5,
   captionValidatorBatchSize: 5,
@@ -103,14 +111,14 @@ import { openai } from '@ai-sdk/openai';
 const processor = new DocumentProcessor({
   logger,
   // Fallback model (for retry on failure)
-  fallbackModel: anthropic('claude-opus-4-5'),
+  fallbackModel: anthropic(process.env.HERIPO_ANTHROPIC_MODEL!),
 
   // Per-component model specification
-  pageRangeParserModel: openai('gpt-5.1'), // Vision required
-  tocExtractorModel: openai('gpt-5.1'), // Structured output
-  validatorModel: openai('gpt-5.2'), // Simple validation
-  visionTocExtractorModel: openai('gpt-5.1'), // Vision required
-  captionParserModel: openai('gpt-5-mini'), // Caption parsing
+  pageRangeParserModel: openai(process.env.HERIPO_OPENAI_MODEL!), // Vision required
+  tocExtractorModel: openai(process.env.HERIPO_OPENAI_MODEL!), // Structured output
+  validatorModel: openai(process.env.HERIPO_OPENAI_MODEL!), // Simple validation
+  visionTocExtractorModel: openai(process.env.HERIPO_OPENAI_MODEL!), // Vision required
+  captionParserModel: openai(process.env.HERIPO_OPENAI_MODEL!), // Caption parsing
 
   // Batch size settings
   textCleanerBatchSize: 20, // Synchronous processing (can be large)
@@ -240,9 +248,9 @@ node reference.
 `validateSourceRefs: true` is a compatibility shortcut and behaves like
 `'error'` unless a mode is explicitly provided.
 
-Table cells do not receive cell-level `sourceRef` values. To locate a specific
-cell in the source artifact, combine `table.sourceRef` with the
-`grid[row][col]` row/column indexes.
+Table cells do not receive cell-level `sourceRef` values. Use `table.sourceRef`
+to find the source table, then compare spans and source cell coordinates.
+Compact `grid` array indexes may differ from logical source column indexes.
 
 ### Table Grid Handling
 
@@ -253,9 +261,8 @@ Processed tables expose a compact `grid` of visible cells. The processor:
 - Removes merged-cell shadow entries when Docling repeats covered cells
 - Falls back to `table_cells` when Docling's `data.grid` is empty
 
-`numRows` and `numCols` keep the logical table size. Individual cells do not
-store `sourceRef`; use `table.sourceRef` together with the `grid[row][col]`
-position when tracing a cell back to the source table.
+`numRows` and `numCols` keep the logical table size; do not assume they match
+array lengths. When rendering, skip positions covered by `rowSpan`/`colSpan`.
 
 ## Processing Pipeline
 
@@ -310,6 +317,8 @@ DocumentProcessor processes documents through a 5-stage pipeline:
 
 ### 5. Chapter Conversion (ChapterConverter)
 
+A `Front Matter` (`ch-000`) chapter is always prepended to retain content before the first TOC entry. The remaining hierarchy is built from the supplied or extracted TOC.
+
 - Build chapter tree based on TOC
 - Create Chapter hierarchy
 - Link text blocks to chapters by page range
@@ -387,8 +396,8 @@ When `enableFallbackRetry: true` is set (default is `false`), LLM components aut
 ```typescript
 const processor = new DocumentProcessor({
   logger,
-  fallbackModel: anthropic('claude-opus-4-5'), // For retry
-  pageRangeParserModel: openai('gpt-5.2'), // First attempt
+  fallbackModel: anthropic(process.env.HERIPO_ANTHROPIC_MODEL!), // For retry
+  pageRangeParserModel: openai(process.env.HERIPO_OPENAI_MODEL!), // First attempt
   enableFallbackRetry: true, // Use fallback on failure (default: false)
   textCleanerBatchSize: 10,
   captionParserBatchSize: 5,
@@ -402,8 +411,10 @@ const { document, usage } = await processor.process(doc, 'id', 'path');
 ### Batch Size Parameters
 
 - **textCleanerBatchSize**: Synchronous text normalization and filtering batch size. Large values possible due to local processing
-- **captionParserBatchSize**: LLM-based caption parsing batch size. Small values for API request concurrency and cost management
-- **captionValidatorBatchSize**: LLM-based caption validation batch size. Small values to limit validation request concurrency
+- **captionParserBatchSize**: LLM-based caption parsing batch size. Controls captions included per parsing request
+- **captionValidatorBatchSize**: LLM-based caption validation batch size. Controls captions grouped for validation
+
+`textCleanerBatchSize`, `captionParserBatchSize` and `captionValidatorBatchSize` accept `0` for sequential processing without batching. Use positive integers to enable batching. Positive batch sizes group items; they do not impose a global API concurrency limit.
 
 ## Error Handling
 
@@ -413,9 +424,15 @@ Errors thrown when TOC extraction fails:
 
 - `TocNotFoundError`: TOC not found in document
 - `TocParseError`: LLM response parsing failed
-- `TocValidationError`: TOC validation failed
+- `TocValidationError`: May be raised internally, but is not exported from the package root. Catch the exported `TocExtractError` base class.
 
 ```typescript
+import {
+  TocExtractError,
+  TocNotFoundError,
+  TocParseError,
+} from '@heripo/document-processor';
+
 try {
   const { document, usage } = await processor.process(doc, 'id', 'path');
 } catch (error) {
@@ -423,6 +440,10 @@ try {
     console.error('TOC not found. Manual TOC review is required.');
   } else if (error instanceof TocParseError) {
     console.error('TOC parsing failed:', error.message);
+  } else if (error instanceof TocExtractError) {
+    console.error(error.message);
+  } else {
+    throw error;
   }
 }
 ```
@@ -452,18 +473,18 @@ Major LLM components return token usage:
 
 ```typescript
 // PageRangeParser
-const { pageRangeMap, tokenUsage } = await pageRangeParser.parse(doc);
-console.log('Token usage:', tokenUsage);
+const { pageRangeMap, usage } = await pageRangeParser.parse(doc);
+console.log('Token usage:', usage);
 
 // TocExtractor
-const { entries, tokenUsage } = await tocExtractor.extract(markdown);
-console.log('Token usage:', tokenUsage);
+const { entries, usages } = await tocExtractor.extract(markdown);
+console.log('Token usage:', usages);
 ```
 
 ## Related Packages
 
-- [@heripo/pdf-parser](../pdf-parser) - PDF parsing and OCR
-- [@heripo/model](../model) - Data models and type definitions
+- [@heripo/pdf-parser](../pdf-parser/README.md) - PDF parsing and OCR
+- [@heripo/model](../model/README.md) - Data models and type definitions
 
 ## Sponsor
 

package/dist/index.js

@@ -90,6 +90,15 @@ function detectProvider(model) {
   if (providerId.includes("lmstudio")) return "lmstudio";
   return "unknown";
 }
+function cacheWrite1hTokens(steps) {
+  let total;
+  for (const step of steps ?? []) {
+    const raw = step.usage.raw;
+    const value = raw?.cache_creation?.ephemeral_1h_input_tokens;
+    if (value !== void 0) total = (total ?? 0) + value;
+  }
+  return total;
+}
 var LLMCaller = class {
   /**
    * Extract model name from LanguageModel object
@@ -108,6 +117,9 @@ var LLMCaller = class {
    * Build usage information from response
    */
   static buildUsage(config, modelName, response, usedFallback) {
+    const usage = response.usage;
+    const write1h = cacheWrite1hTokens(response.steps);
+    const allWrites = usage?.inputTokenDetails?.cacheWriteTokens;
     return {
       component: config.component,
       phase: config.phase,
@@ -116,6 +128,13 @@ var LLMCaller = class {
       inputTokens: response.usage?.inputTokens ?? 0,
       outputTokens: response.usage?.outputTokens ?? 0,
       totalTokens: response.usage?.totalTokens ?? 0,
+      ...usage?.inputTokenDetails?.cacheReadTokens != null && {
+        cachedInputTokens: usage.inputTokenDetails.cacheReadTokens
+      },
+      ...allWrites != null && {
+        cacheWriteTokens: allWrites - (write1h ?? 0)
+      },
+      ...write1h !== void 0 && { cacheWrite1hTokens: write1h },
       metadata: config.metadata
     };
   }
@@ -158,7 +177,8 @@ var LLMCaller = class {
       if (toolCall) {
         return {
           output: toolCall.input,
-          usage: lastResult.usage
+          usage: lastResult.usage,
+          steps: lastResult.steps
         };
       }
     }
@@ -295,16 +315,32 @@ function emptyUsage() {
   return { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
 }
 function addInto(target, src) {
+  const hadUsage = target.inputTokens !== 0 || target.outputTokens !== 0 || target.totalTokens !== 0;
   target.inputTokens += src.inputTokens;
   target.outputTokens += src.outputTokens;
   target.totalTokens += src.totalTokens;
+  for (const key of CACHE_KEYS) {
+    const next = src[key];
+    const current = target[key];
+    if (next === void 0) {
+      if (current !== void 0) target[key] = null;
+    } else if (current === void 0) {
+      target[key] = hadUsage ? null : next;
+    } else {
+      target[key] = current === null || next === null ? null : current + next;
+    }
+  }
 }
+var CACHE_KEYS = [
+  "cachedInputTokens",
+  "cacheWriteTokens",
+  "cacheWrite1hTokens"
+];
 function sumUsage(a, b) {
-  return {
-    inputTokens: (a?.inputTokens ?? 0) + (b?.inputTokens ?? 0),
-    outputTokens: (a?.outputTokens ?? 0) + (b?.outputTokens ?? 0),
-    totalTokens: (a?.totalTokens ?? 0) + (b?.totalTokens ?? 0)
-  };
+  const total = emptyUsage();
+  if (a) addInto(total, a);
+  if (b) addInto(total, b);
+  return total;
 }
 function accumulateModel(bucket, modelName, usage) {
   let entry = bucket.get(modelName);
@@ -419,21 +455,13 @@ var LLMTokenUsageAggregator = class {
       components.push({
         component: component.component,
         phases,
-        total: {
-          inputTokens: component.total.inputTokens,
-          outputTokens: component.total.outputTokens,
-          totalTokens: component.total.totalTokens
-        }
+        total: { ...component.total }
       });
     }
     const totalUsage = this.getTotalUsage();
     return {
       components,
-      total: {
-        inputTokens: totalUsage.inputTokens,
-        outputTokens: totalUsage.outputTokens,
-        totalTokens: totalUsage.totalTokens
-      }
+      total: totalUsage
     };
   }
   /**
@@ -442,19 +470,11 @@ var LLMTokenUsageAggregator = class {
    * @returns Aggregated token usage totals
    */
   getTotalUsage() {
-    let totalInput = 0;
-    let totalOutput = 0;
-    let totalTokens = 0;
+    const total = emptyUsage();
     for (const component of Object.values(this.usage)) {
-      totalInput += component.total.inputTokens;
-      totalOutput += component.total.outputTokens;
-      totalTokens += component.total.totalTokens;
+      addInto(total, component.total);
     }
-    return {
-      inputTokens: totalInput,
-      outputTokens: totalOutput,
-      totalTokens
-    };
+    return total;
   }
   /**
    * Log comprehensive token usage summary