@heripo/document-processor 0.1.28 → 0.1.30

package/README.ko.md

@@ -20,6 +20,7 @@
 - [사용법](#사용법)
 - [처리 파이프라인](#처리-파이프라인)
 - [API 문서](#api-문서)
+- [후원](#후원)
 - [라이선스](#라이선스)
 
 ## 주요 기능
@@ -28,6 +29,8 @@
 - **계층 구조**: 장/절/소절 계층 구조 자동 생성
 - **페이지 매핑**: Vision LLM을 활용한 실제 페이지 번호 매핑
 - **캡션 파싱**: 이미지 및 테이블 캡션 자동 파싱
+- **원천 추적성**: Docling 원천 metadata와 node-level reference 보존
+- **테이블 그리드 정규화**: row/column span을 보존하고 병합 셀 shadow entry 제거
 - **LLM 유연성**: OpenAI, Anthropic, Google 등 다양한 LLM 지원
 - **Fallback 재시도**: 실패 시 자동으로 fallback 모델로 재시도
 
@@ -35,13 +38,13 @@
 
 ```bash
 # npm으로 설치
-npm install @heripo/document-processor @heripo/model
+npm install @heripo/document-processor @heripo/model @heripo/logger
 
 # pnpm으로 설치
-pnpm add @heripo/document-processor @heripo/model
+pnpm add @heripo/document-processor @heripo/model @heripo/logger
 
 # yarn으로 설치
-yarn add @heripo/document-processor @heripo/model
+yarn add @heripo/document-processor @heripo/model @heripo/logger
 ```
 
 추가로 LLM 프로파이더의 SDK가 필요합니다:
@@ -60,7 +63,12 @@ import { anthropic } from '@ai-sdk/anthropic';
 import { DocumentProcessor } from '@heripo/document-processor';
 import { Logger } from '@heripo/logger';
 
-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),
+});
 
 // 기본 사용 - fallback 모델만 지정
 const processor = new DocumentProcessor({
@@ -189,6 +197,50 @@ const { document, usage } = await processor.process(
 );
 ```
 
+### 원천 Docling 참조 보존
+
+호출자가 원천 Docling JSON의 저장 위치나 해시를 알고 있다면 `source`로 전달할 수 있습니다. 이 값은 `ProcessedDocument.source`에 그대로 보존됩니다. `validateSourceRefs` 또는 `sourceRefValidationMode`를 사용하면 processor가 생성한 `sourceRef`, `captionSourceRefs`가 입력 `DoclingDocument`에 실제로 존재하는지 검증합니다.
+
+```typescript
+const { document } = await processor.process(
+  doclingDocument,
+  'report-001',
+  artifactDir,
+  {
+    pageRangeMap,
+    tocEntries,
+    source: {
+      pipelineRunId: 'run-001',
+      doclingObjectKey: 'docling/report-001.json',
+      doclingSha256: '...',
+      handoffManifestObjectKey: 'manifests/run-001.json',
+    },
+    sourceRefValidationMode: 'warn', // 'off' | 'warn' | 'error'
+  },
+);
+
+console.log(document.source);
+console.log(document.chapters[0].textBlocks[0].sourceRef);
+console.log(document.images[0].captionSourceRefs);
+```
+
+`ProcessedDocument.source`는 처리에 사용된 Docling artifact 자체를 가리키는 문서 단위 metadata입니다. `TextBlock.sourceRef`, `Chapter.sourceRefs`, `ProcessedImage.sourceRef`, `ProcessedTable.sourceRef`, `ProcessedFootnote.sourceRef`는 해당 processed node가 어떤 Docling node에서 왔는지 가리키는 node-level 참조입니다. 이미지와 테이블의 `captionSourceRefs`는 resource node가 아니라 caption text node의 참조만 담습니다.
+
+`sourceRefValidationMode: 'error'`는 누락된 참조가 있으면 처리를 실패시킵니다. `validateSourceRefs: true`는 호환용 단축 옵션이며, 별도 mode를 지정하지 않으면 `'error'`와 같습니다.
+
+테이블 셀에는 cell-level `sourceRef`를 만들지 않습니다. 특정 셀의 원천 위치는 `table.sourceRef`와 `grid[row][col]`의 row/column index를 함께 사용해 추적합니다.
+
+### 테이블 그리드 처리
+
+처리된 테이블은 화면에 보이는 셀만 담은 compact `grid`를 제공합니다. processor는 다음을 수행합니다:
+
+- Docling의 row/column span을 `rowSpan`, `colSpan`으로 보존
+- 행/열 헤더를 `isHeader`로 표시
+- Docling이 병합 셀의 덮인 영역을 반복 제공하는 경우 shadow entry 제거
+- Docling의 `data.grid`가 비어 있으면 `table_cells`에서 그리드 구성
+
+`numRows`와 `numCols`는 논리적 테이블 크기를 유지합니다. 개별 셀에는 `sourceRef`를 저장하지 않으므로, 셀의 원천 위치를 추적할 때는 `table.sourceRef`와 `grid[row][col]` 위치를 함께 사용합니다.
+
 ## 처리 파이프라인
 
 DocumentProcessor는 다음 5단계 파이프라인으로 문서를 처리합니다:
@@ -237,7 +289,7 @@ DocumentProcessor는 다음 5단계 파이프라인으로 문서를 처리합니
 ### 4. 리소스 변환
 
 - **이미지**: CaptionParser로 캡션 추출 및 파싱
-- **테이블**: 그리드 데이터 변환 및 캡션 파싱
+- **테이블**: 그리드 데이터 변환, 병합 셀 shadow filtering, span 보존 및 캡션 파싱
 - **캡션 검증**: CaptionValidator로 파싱 결과 검증
 
 ### 5. 챕터 변환 (ChapterConverter)
@@ -247,7 +299,7 @@ DocumentProcessor는 다음 5단계 파이프라인으로 문서를 처리합니
 - 페이지 범위별로 텍스트 블록을 챕터에 연결
 - 이미지/테이블 ID를 적절한 챕터에 연결
 - 각주 ID를 적절한 챕터에 연결
-- Fallback: TOC가 비어있을 때 단일 "Document" 챕터 생성
+- TOC 항목이 비어 있으면 TOC 기반 챕터 변환을 진행할 수 없으므로 `TocNotFoundError` 발생
 
 ## API 문서
 
@@ -257,7 +309,7 @@ DocumentProcessor는 다음 5단계 파이프라인으로 문서를 처리합니
 
 ```typescript
 interface DocumentProcessorOptions {
-  logger: Logger; // 로거 인스턴스 (필수)
+  logger: LoggerMethods; // 로거 인스턴스 (필수)
 
   // LLM 모델 설정
   fallbackModel: LanguageModel; // Fallback 모델 (필수)
@@ -293,6 +345,9 @@ DoclingDocument를 ProcessedDocument로 변환합니다.
 interface DocumentProcessorProcessOptions {
   pageRangeMap?: Record<number, PageRange>;
   tocEntries?: TocEntry[];
+  source?: ProcessedDocumentSource;
+  validateSourceRefs?: boolean;
+  sourceRefValidationMode?: 'off' | 'warn' | 'error';
 }
 ```
 
@@ -301,7 +356,7 @@ interface DocumentProcessorProcessOptions {
 - `doclingDoc` (DoclingDocument): PDF 파서의 출력
 - `reportId` (string): 리포트 ID
 - `artifactDir` (string): `images/`, `pages/`, `result.json` 같은 parser 산출물이 들어 있는 디렉토리
-- `processOptions` (DocumentProcessorProcessOptions, 선택): 문서별 처리 입력값. `pageRangeMap`이 제공되면 자동 페이지 범위 파싱을 건너뜁니다. `tocEntries`가 제공되면 자동 TOC 추출을 건너뜁니다.
+- `processOptions` (DocumentProcessorProcessOptions, 선택): 문서별 처리 입력값. `pageRangeMap`이 제공되면 자동 페이지 범위 파싱을 건너뜁니다. `tocEntries`가 제공되면 자동 TOC 추출을 건너뜁니다. `source`는 원천 Docling artifact metadata를 결과에 보존하고, `sourceRefValidationMode`는 생성된 원천 참조의 검증 방식을 제어합니다.
 
 **반환값:**
 
@@ -349,7 +404,7 @@ try {
   const { document, usage } = await processor.process(doc, 'id', 'path');
 } catch (error) {
   if (error instanceof TocNotFoundError) {
-    console.log('TOC를 찾을 수 없습니다. 단일 챕터로 처리됩니다.');
+    console.error('TOC를 찾을 수 없습니다. 수동 TOC 검수가 필요합니다.');
   } else if (error instanceof TocParseError) {
     console.error('TOC 파싱 실패:', error.message);
   }
@@ -394,6 +449,13 @@ console.log('토큰 사용:', tokenUsage);
 - [@heripo/pdf-parser](../pdf-parser) - PDF 파싱 및 OCR
 - [@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

@@ -20,6 +20,7 @@
 - [Usage](#usage)
 - [Processing Pipeline](#processing-pipeline)
 - [API Documentation](#api-documentation)
+- [Sponsor](#sponsor)
 - [License](#license)
 
 ## Key Features
@@ -28,6 +29,8 @@
 - **Hierarchical Structure**: Automatic generation of chapter/section/subsection hierarchy
 - **Page Mapping**: Actual page number mapping using Vision LLM
 - **Caption Parsing**: Automatic parsing of image and table captions
+- **Source Provenance**: Preserves Docling source metadata and node-level references
+- **Table Grid Normalization**: Preserves row/column spans and removes merged-cell shadow entries
 - **LLM Flexibility**: Support for various LLMs including OpenAI, Anthropic, Google
 - **Fallback Retry**: Automatic retry with fallback model on failure
 
@@ -35,13 +38,13 @@
 
 ```bash
 # Install with npm
-npm install @heripo/document-processor @heripo/model
+npm install @heripo/document-processor @heripo/model @heripo/logger
 
 # Install with pnpm
-pnpm add @heripo/document-processor @heripo/model
+pnpm add @heripo/document-processor @heripo/model @heripo/logger
 
 # Install with yarn
-yarn add @heripo/document-processor @heripo/model
+yarn add @heripo/document-processor @heripo/model @heripo/logger
 ```
 
 Additionally, LLM provider SDKs are required:
@@ -60,7 +63,12 @@ import { anthropic } from '@ai-sdk/anthropic';
 import { DocumentProcessor } from '@heripo/document-processor';
 import { Logger } from '@heripo/logger';
 
-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),
+});
 
 // Basic usage - specify fallback model only
 const processor = new DocumentProcessor({
@@ -189,6 +197,66 @@ const { document, usage } = await processor.process(
 );
 ```
 
+### Preserving Source Docling References
+
+If the caller knows where the source Docling JSON is stored or has its hash,
+pass that metadata through `source`. The value is preserved as
+`ProcessedDocument.source`. Use `validateSourceRefs` or
+`sourceRefValidationMode` to verify that generated `sourceRef` and
+`captionSourceRefs` values exist in the input `DoclingDocument`.
+
+```typescript
+const { document } = await processor.process(
+  doclingDocument,
+  'report-001',
+  artifactDir,
+  {
+    pageRangeMap,
+    tocEntries,
+    source: {
+      pipelineRunId: 'run-001',
+      doclingObjectKey: 'docling/report-001.json',
+      doclingSha256: '...',
+      handoffManifestObjectKey: 'manifests/run-001.json',
+    },
+    sourceRefValidationMode: 'warn', // 'off' | 'warn' | 'error'
+  },
+);
+
+console.log(document.source);
+console.log(document.chapters[0].textBlocks[0].sourceRef);
+console.log(document.images[0].captionSourceRefs);
+```
+
+`ProcessedDocument.source` is document-level metadata that identifies the
+Docling artifact used for processing. `TextBlock.sourceRef`,
+`Chapter.sourceRefs`, `ProcessedImage.sourceRef`, `ProcessedTable.sourceRef`,
+and `ProcessedFootnote.sourceRef` are node-level references that point back to
+the Docling nodes each processed node came from. For images and tables,
+`captionSourceRefs` contains only caption text node references, not the resource
+node reference.
+
+`sourceRefValidationMode: 'error'` fails processing when references are missing.
+`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 Grid Handling
+
+Processed tables expose a compact `grid` of visible cells. The processor:
+
+- Preserves Docling row/column spans as `rowSpan` and `colSpan`
+- Marks row and column headers through `isHeader`
+- 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.
+
 ## Processing Pipeline
 
 DocumentProcessor processes documents through a 5-stage pipeline:
@@ -237,7 +305,7 @@ DocumentProcessor processes documents through a 5-stage pipeline:
 ### 4. Resource Transformation
 
 - **Images**: Caption extraction and parsing with CaptionParser
-- **Tables**: Grid data transformation and caption parsing
+- **Tables**: Grid data transformation, merged-cell shadow filtering, span preservation, and caption parsing
 - **Caption Validation**: Parsing result validation with CaptionValidator
 
 ### 5. Chapter Conversion (ChapterConverter)
@@ -247,7 +315,7 @@ DocumentProcessor processes documents through a 5-stage pipeline:
 - Link text blocks to chapters by page range
 - Connect image/table IDs to appropriate chapters
 - Link footnote IDs to appropriate chapters
-- Fallback: Create single "Document" chapter when TOC is empty
+- Throws `TocNotFoundError` when TOC entries are empty because TOC-based chapter conversion is required
 
 ## API Documentation
 
@@ -257,7 +325,7 @@ DocumentProcessor processes documents through a 5-stage pipeline:
 
 ```typescript
 interface DocumentProcessorOptions {
-  logger: Logger; // Logger instance (required)
+  logger: LoggerMethods; // Logger instance (required)
 
   // LLM model settings
   fallbackModel: LanguageModel; // Fallback model (required)
@@ -293,6 +361,9 @@ Transforms DoclingDocument into ProcessedDocument.
 interface DocumentProcessorProcessOptions {
   pageRangeMap?: Record<number, PageRange>;
   tocEntries?: TocEntry[];
+  source?: ProcessedDocumentSource;
+  validateSourceRefs?: boolean;
+  sourceRefValidationMode?: 'off' | 'warn' | 'error';
 }
 ```
 
@@ -301,7 +372,7 @@ interface DocumentProcessorProcessOptions {
 - `doclingDoc` (DoclingDocument): PDF parser output
 - `reportId` (string): Report ID
 - `artifactDir` (string): Artifact directory containing parser outputs such as `images/`, `pages/`, and `result.json`
-- `processOptions` (DocumentProcessorProcessOptions, optional): Per-document processing inputs. When `pageRangeMap` is provided, automatic page range parsing is skipped. When `tocEntries` is provided, automatic TOC extraction is skipped.
+- `processOptions` (DocumentProcessorProcessOptions, optional): Per-document processing inputs. When `pageRangeMap` is provided, automatic page range parsing is skipped. When `tocEntries` is provided, automatic TOC extraction is skipped. `source` preserves source Docling artifact metadata, and `sourceRefValidationMode` controls generated source reference validation.
 
 **Returns:**
 
@@ -349,7 +420,7 @@ try {
   const { document, usage } = await processor.process(doc, 'id', 'path');
 } catch (error) {
   if (error instanceof TocNotFoundError) {
-    console.log('TOC not found. Processing as single chapter.');
+    console.error('TOC not found. Manual TOC review is required.');
   } else if (error instanceof TocParseError) {
     console.error('TOC parsing failed:', error.message);
   }
@@ -394,6 +465,13 @@ console.log('Token usage:', tokenUsage);
 - [@heripo/pdf-parser](../pdf-parser) - PDF parsing and OCR
 - [@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).