@heripo/model 0.1.28 → 0.1.30

package/README.ko.md

@@ -18,6 +18,7 @@
 - [설치](#설치)
 - [데이터 모델](#데이터-모델)
 - [사용법](#사용법)
+- [후원](#후원)
 - [라이선스](#라이선스)
 
 ## 개요
@@ -59,9 +60,11 @@ import type { DoclingDocument } from '@heripo/model';
 
 **주요 필드:**
 
-- `type`: 문서 타입 (예: "pdf")
-- `item_index`: 아이템 인덱스
-- `json_content`: 문서 내용 (JSON 객체)
+- `schema_name`, `version`, `name`: Docling 문서 식별 필드
+- `origin`: 원천 파일 metadata
+- `body`, `furniture`, `groups`: 문서 트리 및 그룹 구조
+- `texts`, `pictures`, `tables`: 추출된 content node
+- `pages`: 페이지 metadata와 렌더링된 페이지 이미지 참조
 
 ### ProcessedDocument
 
@@ -72,6 +75,8 @@ import type { ProcessedDocument } from '@heripo/model';
 
 interface ProcessedDocument {
   reportId: string; // 리포트 ID
+  schemaVersion?: string; // 처리된 문서 schema version
+  source?: ProcessedDocumentSource; // 원천 Docling artifact metadata
   pageRangeMap: Record<number, PageRange>; // PDF 페이지 → 문서 페이지 매핑
   chapters: Chapter[]; // 계층적 챕터 구조
   images: ProcessedImage[]; // 추출된 이미지 메타데이터
@@ -80,6 +85,21 @@ interface ProcessedDocument {
 }
 ```
 
+### ProcessedDocumentSource
+
+처리된 문서를 만들 때 사용한 Docling JSON의 원천 artifact metadata입니다.
+
+```typescript
+import type { ProcessedDocumentSource } from '@heripo/model';
+
+interface ProcessedDocumentSource {
+  pipelineRunId?: string; // 처리 pipeline run ID
+  doclingObjectKey?: string; // result.json 또는 병합된 Docling JSON object key
+  doclingSha256?: string; // Docling JSON artifact의 SHA-256 hash
+  handoffManifestObjectKey?: string; // handoff manifest object key
+}
+```
+
 ### Chapter
 
 문서의 계층적 섹션 구조입니다.
@@ -93,6 +113,7 @@ interface Chapter {
   originTitle: string; // 원본 제목
   level: number; // 계층 레벨 (1, 2, 3, ...)
   pageNo: number; // 시작 페이지 번호
+  sourceRefs?: string[]; // 제목 추출에 사용된 원천 Docling ref
   textBlocks: TextBlock[]; // 텍스트 블록
   imageIds: string[]; // 이미지 ID 참조
   tableIds: string[]; // 테이블 ID 참조
@@ -109,6 +130,8 @@ interface Chapter {
 import type { TextBlock } from '@heripo/model';
 
 interface TextBlock {
+  id?: string; // 안정적인 텍스트 블록 ID
+  sourceRef?: string; // 원천 Docling text ref
   text: string; // 텍스트 내용
   pdfPageNo: number; // PDF 페이지 번호
 }
@@ -123,6 +146,8 @@ import type { ProcessedImage } from '@heripo/model';
 
 interface ProcessedImage {
   id: string; // 이미지 ID
+  sourceRef?: string; // 원천 Docling picture ref
+  captionSourceRefs?: string[]; // 캡션 텍스트 item의 원천 Docling ref
   caption?: Caption; // 캡션 (선택)
   pdfPageNo: number; // PDF 페이지 번호
   path: string; // 이미지 파일 경로
@@ -138,6 +163,8 @@ import type { ProcessedTable } from '@heripo/model';
 
 interface ProcessedTable {
   id: string; // 테이블 ID
+  sourceRef?: string; // 원천 Docling table ref
+  captionSourceRefs?: string[]; // 캡션 텍스트 item의 원천 Docling ref
   caption?: Caption; // 캡션 (선택)
   pdfPageNo: number; // PDF 페이지 번호
   grid: ProcessedTableCell[][]; // 2D 그리드 데이터
@@ -146,6 +173,12 @@ interface ProcessedTable {
 }
 ```
 
+`grid`는 화면에 보이는 셀만 담은 compact list입니다. 병합 셀은
+`rowSpan`, `colSpan`으로 표현하고, span으로 덮인 shadow cell은 포함하지
+않습니다. 테이블 셀에는 의도적으로 cell-level `sourceRef`가 없습니다. 셀을
+원천 테이블로 추적할 때는 `table.sourceRef`와 `grid[row][col]` 위치를 함께
+사용합니다.
+
 ### ProcessedTableCell
 
 테이블 셀 메타데이터입니다.
@@ -196,6 +229,7 @@ import type { ProcessedFootnote } from '@heripo/model';
 
 interface ProcessedFootnote {
   id: string; // 각주 ID
+  sourceRef?: string; // 원천 Docling text ref
   text: string; // 각주 텍스트
   pdfPageNo: number; // PDF 페이지 번호
 }
@@ -276,6 +310,58 @@ interface TokenUsageSummary {
 }
 ```
 
+### Review Assistance 타입
+
+`@heripo/pdf-parser`에서 `reviewAssistance`를 활성화했을 때 생성되는 선택적
+page-level review assistance 결과 타입입니다.
+
+```typescript
+import type {
+  ReviewAssistanceDecision,
+  ReviewAssistanceIssue,
+  ReviewAssistanceProgressEvent,
+  ReviewAssistanceReport,
+} from '@heripo/model';
+
+interface ReviewAssistanceReport {
+  schemaName: 'HeripoReviewAssistanceReport';
+  version: '1.0';
+  reportId: string;
+  source: {
+    doclingResult: 'result.json';
+    ocrOriginSnapshot?: 'result_ocr_origin.json';
+    originSnapshot?: 'result_review_origin.json';
+  };
+  summary: {
+    pageCount: number;
+    pagesSucceeded: number;
+    pagesFailed: number;
+    autoAppliedCount: number;
+    proposalCount: number;
+    skippedCount: number;
+    issueCount: number;
+  };
+  pages: Array<{
+    pageNo: number;
+    status: 'succeeded' | 'failed';
+    decisions: ReviewAssistanceDecision[];
+    issues: ReviewAssistanceIssue[];
+  }>;
+}
+
+interface ReviewAssistanceProgressEvent {
+  substage:
+    | 'review-assistance:prepare'
+    | 'review-assistance:page'
+    | 'review-assistance:patch'
+    | 'review-assistance:write-report';
+  status: 'started' | 'progress' | 'completed' | 'failed';
+  reportId: string;
+  pageNo?: number;
+  pageCount?: number;
+}
+```
+
 ### BCP-47 언어 태그 유틸리티
 
 BCP-47 언어 태그를 다루기 위한 유틸리티입니다.
@@ -289,10 +375,10 @@ import {
   normalizeToBcp47,
 } from '@heripo/model';
 
-// Bcp47LanguageTag - 지원되는 BCP-47 언어 태그의 유니온 타입
-type Bcp47LanguageTag = 'ko' | 'en' | 'ja' | 'zh' | /* ... */ string;
+// Bcp47LanguageTag - 지원되는 전체 BCP-47 언어 태그의 유니온 타입
+type Bcp47LanguageTag = (typeof BCP47_LANGUAGE_TAGS)[number];
 
-// BCP47_LANGUAGE_TAGS - 30개 지원 태그의 상수 배열
+// BCP47_LANGUAGE_TAGS - ocrmac에서 지원하는 언어 태그 상수 배열
 const BCP47_LANGUAGE_TAGS: readonly Bcp47LanguageTag[];
 
 // BCP47_LANGUAGE_TAG_SET - O(1) 조회를 위한 ReadonlySet
@@ -302,7 +388,7 @@ const BCP47_LANGUAGE_TAG_SET: ReadonlySet<string>;
 function isValidBcp47Tag(tag: string): tag is Bcp47LanguageTag;
 
 // normalizeToBcp47 - 언어 문자열을 BCP-47 형식으로 정규화
-function normalizeToBcp47(tag: string): Bcp47LanguageTag | undefined;
+function normalizeToBcp47(tag: string): Bcp47LanguageTag | null;
 ```
 
 ## 사용법
@@ -383,6 +469,13 @@ const resourcesWithCaptions = [...doc.images, ...doc.tables].filter(hasCaption);
 - [@heripo/pdf-parser](../pdf-parser) - PDF 파싱 및 OCR
 - [@heripo/document-processor](../document-processor) - 문서 구조 분석
 
+## 후원
+
+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

@@ -18,6 +18,7 @@
 - [Installation](#installation)
 - [Data Models](#data-models)
 - [Usage](#usage)
+- [Sponsor](#sponsor)
 - [License](#license)
 
 ## Overview
@@ -59,9 +60,11 @@ import type { DoclingDocument } from '@heripo/model';
 
 **Key Fields:**
 
-- `type`: Document type (e.g., "pdf")
-- `item_index`: Item index
-- `json_content`: Document content (JSON object)
+- `schema_name`, `version`, `name`: Docling document identity fields
+- `origin`: Source file metadata
+- `body`, `furniture`, `groups`: Document tree and grouping structures
+- `texts`, `pictures`, `tables`: Extracted content nodes
+- `pages`: Page metadata and rendered page image references
 
 ### ProcessedDocument
 
@@ -72,6 +75,8 @@ import type { ProcessedDocument } from '@heripo/model';
 
 interface ProcessedDocument {
   reportId: string; // Report ID
+  schemaVersion?: string; // Processed document schema version
+  source?: ProcessedDocumentSource; // Source Docling artifact metadata
   pageRangeMap: Record<number, PageRange>; // PDF page → document page mapping
   chapters: Chapter[]; // Hierarchical chapter structure
   images: ProcessedImage[]; // Extracted image metadata
@@ -80,6 +85,21 @@ interface ProcessedDocument {
 }
 ```
 
+### ProcessedDocumentSource
+
+Source artifact metadata for the Docling JSON used to create a processed document.
+
+```typescript
+import type { ProcessedDocumentSource } from '@heripo/model';
+
+interface ProcessedDocumentSource {
+  pipelineRunId?: string; // Processing pipeline run ID
+  doclingObjectKey?: string; // Object key for result.json or merged Docling JSON
+  doclingSha256?: string; // SHA-256 hash of the Docling JSON artifact
+  handoffManifestObjectKey?: string; // Object key for a handoff manifest
+}
+```
+
 ### Chapter
 
 Hierarchical section structure of the document.
@@ -93,6 +113,7 @@ interface Chapter {
   originTitle: string; // Original title from source
   level: number; // Hierarchy level (1, 2, 3, ...)
   pageNo: number; // Start page number
+  sourceRefs?: string[]; // Source Docling refs used for the title
   textBlocks: TextBlock[]; // Text blocks
   imageIds: string[]; // Image ID references
   tableIds: string[]; // Table ID references
@@ -109,6 +130,8 @@ Atomic text unit.
 import type { TextBlock } from '@heripo/model';
 
 interface TextBlock {
+  id?: string; // Stable text block ID
+  sourceRef?: string; // Source Docling text ref
   text: string; // Text content
   pdfPageNo: number; // PDF page number
 }
@@ -123,6 +146,8 @@ import type { ProcessedImage } from '@heripo/model';
 
 interface ProcessedImage {
   id: string; // Image ID
+  sourceRef?: string; // Source Docling picture ref
+  captionSourceRefs?: string[]; // Source Docling refs for caption text items
   caption?: Caption; // Caption (optional)
   pdfPageNo: number; // PDF page number
   path: string; // Image file path
@@ -138,6 +163,8 @@ import type { ProcessedTable } from '@heripo/model';
 
 interface ProcessedTable {
   id: string; // Table ID
+  sourceRef?: string; // Source Docling table ref
+  captionSourceRefs?: string[]; // Source Docling refs for caption text items
   caption?: Caption; // Caption (optional)
   pdfPageNo: number; // PDF page number
   grid: ProcessedTableCell[][]; // 2D grid data
@@ -146,6 +173,12 @@ interface ProcessedTable {
 }
 ```
 
+`grid` is a compact list of visible cells. Merged cells are represented with
+`rowSpan` and `colSpan`; shadow cells covered by a span are not included.
+Table cells intentionally do not have cell-level `sourceRef` values. Use
+`table.sourceRef` together with `grid[row][col]` when tracing a cell back to
+the source table.
+
 ### ProcessedTableCell
 
 Table cell metadata.
@@ -196,6 +229,7 @@ import type { ProcessedFootnote } from '@heripo/model';
 
 interface ProcessedFootnote {
   id: string; // Footnote ID
+  sourceRef?: string; // Source Docling text ref
   text: string; // Footnote text
   pdfPageNo: number; // PDF page number
 }
@@ -276,6 +310,58 @@ interface TokenUsageSummary {
 }
 ```
 
+### Review Assistance Types
+
+Types for optional page-level review assistance generated by
+`@heripo/pdf-parser` when `reviewAssistance` is enabled.
+
+```typescript
+import type {
+  ReviewAssistanceDecision,
+  ReviewAssistanceIssue,
+  ReviewAssistanceProgressEvent,
+  ReviewAssistanceReport,
+} from '@heripo/model';
+
+interface ReviewAssistanceReport {
+  schemaName: 'HeripoReviewAssistanceReport';
+  version: '1.0';
+  reportId: string;
+  source: {
+    doclingResult: 'result.json';
+    ocrOriginSnapshot?: 'result_ocr_origin.json';
+    originSnapshot?: 'result_review_origin.json';
+  };
+  summary: {
+    pageCount: number;
+    pagesSucceeded: number;
+    pagesFailed: number;
+    autoAppliedCount: number;
+    proposalCount: number;
+    skippedCount: number;
+    issueCount: number;
+  };
+  pages: Array<{
+    pageNo: number;
+    status: 'succeeded' | 'failed';
+    decisions: ReviewAssistanceDecision[];
+    issues: ReviewAssistanceIssue[];
+  }>;
+}
+
+interface ReviewAssistanceProgressEvent {
+  substage:
+    | 'review-assistance:prepare'
+    | 'review-assistance:page'
+    | 'review-assistance:patch'
+    | 'review-assistance:write-report';
+  status: 'started' | 'progress' | 'completed' | 'failed';
+  reportId: string;
+  pageNo?: number;
+  pageCount?: number;
+}
+```
+
 ### BCP-47 Language Tag Utilities
 
 Utilities for working with BCP-47 language tags.
@@ -289,10 +375,10 @@ import {
   normalizeToBcp47,
 } from '@heripo/model';
 
-// Bcp47LanguageTag - Union type of supported BCP-47 language tags
-type Bcp47LanguageTag = 'ko' | 'en' | 'ja' | 'zh' | /* ... */ string;
+// Bcp47LanguageTag - Union type of supported full BCP-47 language tags
+type Bcp47LanguageTag = (typeof BCP47_LANGUAGE_TAGS)[number];
 
-// BCP47_LANGUAGE_TAGS - Const array of 30 supported tags
+// BCP47_LANGUAGE_TAGS - Const array of supported ocrmac language tags
 const BCP47_LANGUAGE_TAGS: readonly Bcp47LanguageTag[];
 
 // BCP47_LANGUAGE_TAG_SET - ReadonlySet for O(1) lookup
@@ -302,7 +388,7 @@ const BCP47_LANGUAGE_TAG_SET: ReadonlySet<string>;
 function isValidBcp47Tag(tag: string): tag is Bcp47LanguageTag;
 
 // normalizeToBcp47 - Normalize a language string to BCP-47 format
-function normalizeToBcp47(tag: string): Bcp47LanguageTag | undefined;
+function normalizeToBcp47(tag: string): Bcp47LanguageTag | null;
 ```
 
 ## Usage
@@ -383,6 +469,13 @@ const resourcesWithCaptions = [...doc.images, ...doc.tables].filter(hasCaption);
 - [@heripo/pdf-parser](../pdf-parser) - PDF parsing and OCR
 - [@heripo/document-processor](../document-processor) - Document structure analysis
 
+## 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/dist/index.d.cts

@@ -191,6 +191,37 @@ interface PageRange {
      */
     endPageNo: number;
 }
+/**
+ * Source artifact metadata for a processed document
+ *
+ * Stores caller-supplied identifiers for the raw or merged Docling artifact used
+ * to create this processed document. Storage providers and URL formats are kept
+ * outside this model.
+ *
+ * @interface ProcessedDocumentSource
+ */
+interface ProcessedDocumentSource {
+    /**
+     * Identifier of the processing pipeline run that produced the source artifact
+     * @type {string}
+     */
+    pipelineRunId?: string;
+    /**
+     * Object key for the canonical or merged Docling JSON artifact
+     * @type {string}
+     */
+    doclingObjectKey?: string;
+    /**
+     * SHA-256 hash of the Docling JSON artifact
+     * @type {string}
+     */
+    doclingSha256?: string;
+    /**
+     * Object key for a handoff manifest that describes related processing outputs
+     * @type {string}
+     */
+    handoffManifestObjectKey?: string;
+}
 /**
  * Text block (paragraph, sentence, etc.)
  *
@@ -199,6 +230,16 @@ interface PageRange {
  * @interface TextBlock
  */
 interface TextBlock {
+    /**
+     * Stable identifier of the text block
+     * @type {string}
+     */
+    id?: string;
+    /**
+     * Docling self reference for the source text item
+     * @type {string}
+     */
+    sourceRef?: string;
     /**
      * Content of the text block
      * @type {string}
@@ -248,6 +289,11 @@ interface Chapter {
      * @type {number}
      */
     level: number;
+    /**
+     * Docling references for the source nodes used to derive the chapter title
+     * @type {string[]}
+     */
+    sourceRefs?: string[];
     /**
      * Text blocks inside the chapter
      *
@@ -303,6 +349,16 @@ interface ProcessedImage {
      * @type {string}
      */
     id: string;
+    /**
+     * Docling self reference for the source picture item
+     * @type {string}
+     */
+    sourceRef?: string;
+    /**
+     * Docling references for caption text items associated with this image
+     * @type {string[]}
+     */
+    captionSourceRefs?: string[];
     /**
      * Caption information for the image (if available)
      * @type {Caption}
@@ -325,6 +381,10 @@ interface ProcessedImage {
 /**
  * Cell information of a table
  *
+ * Table cells intentionally do not carry cell-level Docling source references.
+ * Use the parent table's `sourceRef` with the row/column index in `grid` as
+ * the locator for cell provenance.
+ *
  * @interface ProcessedTableCell
  */
 interface ProcessedTableCell {
@@ -366,6 +426,16 @@ interface ProcessedTable {
      * @type {string}
      */
     id: string;
+    /**
+     * Docling self reference for the source table item
+     * @type {string}
+     */
+    sourceRef?: string;
+    /**
+     * Docling references for caption text items associated with this table
+     * @type {string[]}
+     */
+    captionSourceRefs?: string[];
     /**
      * Caption information for the table (if available)
      * @type {Caption}
@@ -389,7 +459,9 @@ interface ProcessedTable {
     /**
      * Table data (2D array)
      *
-     * Access using grid[row][col].
+     * Access using grid[row][col]. For source lookup, combine `sourceRef` with
+     * the row and column indexes because processed cells do not store cell-level
+     * source references.
      *
      * @type {ProcessedTableCell[][]}
      */
@@ -412,6 +484,11 @@ interface ProcessedFootnote {
      * @type {string}
      */
     id: string;
+    /**
+     * Docling self reference for the source footnote text item
+     * @type {string}
+     */
+    sourceRef?: string;
     /**
      * Text content of the footnote
      *
@@ -438,6 +515,16 @@ interface ProcessedDocument {
      * @type {string}
      */
     reportId: string;
+    /**
+     * Processed document schema version
+     * @type {string}
+     */
+    schemaVersion?: string;
+    /**
+     * Source artifact metadata for the Docling artifact used to produce this document
+     * @type {ProcessedDocumentSource}
+     */
+    source?: ProcessedDocumentSource;
     /**
      * Mapping of page ranges for actual document pages per PDF page
      *
@@ -763,6 +850,8 @@ type ReviewAssistanceReportVersion = '1.0';
 type ReviewAssistanceDisposition = 'auto_applied' | 'proposal' | 'skipped';
 type ReviewAssistanceFailurePolicy = 'partial_page';
 type ReviewAssistancePageStatus = 'succeeded' | 'failed';
+type ReviewAssistanceWorkItemKind = 'text_ocr_hanja' | 'text_integrity' | 'text_role_footnote' | 'table' | 'picture_caption' | 'picture_split' | 'layout_bbox_order';
+type ReviewAssistanceCallTraceValidation = 'passed' | 'reasked' | 'failed';
 type ReviewAssistanceIssueCategory = 'text' | 'table' | 'caption' | 'picture' | 'reading_order' | 'role' | 'text_integrity' | 'paragraph' | 'footnote' | 'bbox' | 'multi_page_table' | 'domain_pattern' | 'review_execution';
 type ReviewAssistanceIssueSeverity = 'info' | 'warning' | 'error';
 type ReviewAssistanceProgressSubstage = 'review-assistance:prepare' | 'review-assistance:page' | 'review-assistance:patch' | 'review-assistance:write-report';
@@ -902,6 +991,18 @@ interface ReviewAssistancePageResult {
         code?: string;
     };
 }
+interface ReviewAssistanceCallTrace {
+    workItemId: string;
+    kind: ReviewAssistanceWorkItemKind;
+    pageNo: number;
+    targetRefs: string[];
+    modelId?: string;
+    attempts: number;
+    startedAt: string;
+    durationMs: number;
+    validation: ReviewAssistanceCallTraceValidation;
+    failureReasons?: string[];
+}
 interface ReviewAssistanceReport {
     schemaName: ReviewAssistanceReportSchemaName;
     version: ReviewAssistanceReportVersion;
@@ -917,6 +1018,9 @@ interface ReviewAssistanceReport {
         autoApplyThreshold: number;
         proposalThreshold: number;
         maxRetries: number;
+        tableMaxRetries?: number;
+        localModelConcurrency?: number;
+        workItemTimeoutMs?: number;
         temperature: number;
         outputLanguage: string;
         failurePolicy: ReviewAssistanceFailurePolicy;
@@ -933,6 +1037,7 @@ interface ReviewAssistanceReport {
         textIntegrityIssueCount?: number;
     };
     pages: ReviewAssistancePageResult[];
+    callTraces: ReviewAssistanceCallTrace[];
 }
 interface ReviewAssistanceProgressEvent {
     substage: ReviewAssistanceProgressSubstage;
@@ -948,4 +1053,4 @@ interface ReviewAssistanceProgressEvent {
     message?: string;
 }
 
-export { BCP47_LANGUAGE_TAGS, BCP47_LANGUAGE_TAG_SET, type Bcp47LanguageTag, type Caption, type Chapter, type ComponentUsageReport, type DoclingBBox, type DoclingBaseNode, type DoclingBody, type DoclingDocument, type DoclingGroupItem, type DoclingOrigin, type DoclingPage, type DoclingPageImage, type DoclingPictureItem, type DoclingProv, type DoclingReference, type DoclingTableCell, type DoclingTableData, type DoclingTableItem, type DoclingTextItem, type DocumentProcessResult, LANGUAGE_DISPLAY_NAMES, type ModelUsageDetail, type OcrStrategy, type PageRange, type PhaseUsageReport, type ProcessedDocument, type ProcessedFootnote, type ProcessedImage, type ProcessedTable, type ProcessedTableCell, type ReviewAssistanceCommand, type ReviewAssistanceDecision, type ReviewAssistanceDecisionEvidence, type ReviewAssistanceDisposition, type ReviewAssistanceFailurePolicy, type ReviewAssistanceImageRegion, type ReviewAssistanceIssue, type ReviewAssistanceIssueCategory, type ReviewAssistanceIssueSeverity, type ReviewAssistancePageResult, type ReviewAssistancePageStatus, type ReviewAssistanceProgressEvent, type ReviewAssistanceProgressStatus, type ReviewAssistanceProgressSubstage, type ReviewAssistanceReport, type ReviewAssistanceReportSchemaName, type ReviewAssistanceReportVersion, type ReviewAssistanceTableCell, type TextBlock, type TokenUsageMetadata, type TokenUsageMetadataValue, type TokenUsageReport, type TokenUsageSummary, buildLanguageDescription, getLanguageDisplayName, isValidBcp47Tag, normalizeToBcp47 };
+export { BCP47_LANGUAGE_TAGS, BCP47_LANGUAGE_TAG_SET, type Bcp47LanguageTag, type Caption, type Chapter, type ComponentUsageReport, type DoclingBBox, type DoclingBaseNode, type DoclingBody, type DoclingDocument, type DoclingGroupItem, type DoclingOrigin, type DoclingPage, type DoclingPageImage, type DoclingPictureItem, type DoclingProv, type DoclingReference, type DoclingTableCell, type DoclingTableData, type DoclingTableItem, type DoclingTextItem, type DocumentProcessResult, LANGUAGE_DISPLAY_NAMES, type ModelUsageDetail, type OcrStrategy, type PageRange, type PhaseUsageReport, type ProcessedDocument, type ProcessedDocumentSource, type ProcessedFootnote, type ProcessedImage, type ProcessedTable, type ProcessedTableCell, type ReviewAssistanceCallTrace, type ReviewAssistanceCallTraceValidation, type ReviewAssistanceCommand, type ReviewAssistanceDecision, type ReviewAssistanceDecisionEvidence, type ReviewAssistanceDisposition, type ReviewAssistanceFailurePolicy, type ReviewAssistanceImageRegion, type ReviewAssistanceIssue, type ReviewAssistanceIssueCategory, type ReviewAssistanceIssueSeverity, type ReviewAssistancePageResult, type ReviewAssistancePageStatus, type ReviewAssistanceProgressEvent, type ReviewAssistanceProgressStatus, type ReviewAssistanceProgressSubstage, type ReviewAssistanceReport, type ReviewAssistanceReportSchemaName, type ReviewAssistanceReportVersion, type ReviewAssistanceTableCell, type ReviewAssistanceWorkItemKind, type TextBlock, type TokenUsageMetadata, type TokenUsageMetadataValue, type TokenUsageReport, type TokenUsageSummary, buildLanguageDescription, getLanguageDisplayName, isValidBcp47Tag, normalizeToBcp47 };

package/dist/index.d.ts

@@ -191,6 +191,37 @@ interface PageRange {
      */
     endPageNo: number;
 }
+/**
+ * Source artifact metadata for a processed document
+ *
+ * Stores caller-supplied identifiers for the raw or merged Docling artifact used
+ * to create this processed document. Storage providers and URL formats are kept
+ * outside this model.
+ *
+ * @interface ProcessedDocumentSource
+ */
+interface ProcessedDocumentSource {
+    /**
+     * Identifier of the processing pipeline run that produced the source artifact
+     * @type {string}
+     */
+    pipelineRunId?: string;
+    /**
+     * Object key for the canonical or merged Docling JSON artifact
+     * @type {string}
+     */
+    doclingObjectKey?: string;
+    /**
+     * SHA-256 hash of the Docling JSON artifact
+     * @type {string}
+     */
+    doclingSha256?: string;
+    /**
+     * Object key for a handoff manifest that describes related processing outputs
+     * @type {string}
+     */
+    handoffManifestObjectKey?: string;
+}
 /**
  * Text block (paragraph, sentence, etc.)
  *
@@ -199,6 +230,16 @@ interface PageRange {
  * @interface TextBlock
  */
 interface TextBlock {
+    /**
+     * Stable identifier of the text block
+     * @type {string}
+     */
+    id?: string;
+    /**
+     * Docling self reference for the source text item
+     * @type {string}
+     */
+    sourceRef?: string;
     /**
      * Content of the text block
      * @type {string}
@@ -248,6 +289,11 @@ interface Chapter {
      * @type {number}
      */
     level: number;
+    /**
+     * Docling references for the source nodes used to derive the chapter title
+     * @type {string[]}
+     */
+    sourceRefs?: string[];
     /**
      * Text blocks inside the chapter
      *
@@ -303,6 +349,16 @@ interface ProcessedImage {
      * @type {string}
      */
     id: string;
+    /**
+     * Docling self reference for the source picture item
+     * @type {string}
+     */
+    sourceRef?: string;
+    /**
+     * Docling references for caption text items associated with this image
+     * @type {string[]}
+     */
+    captionSourceRefs?: string[];
     /**
      * Caption information for the image (if available)
      * @type {Caption}
@@ -325,6 +381,10 @@ interface ProcessedImage {
 /**
  * Cell information of a table
  *
+ * Table cells intentionally do not carry cell-level Docling source references.
+ * Use the parent table's `sourceRef` with the row/column index in `grid` as
+ * the locator for cell provenance.
+ *
  * @interface ProcessedTableCell
  */
 interface ProcessedTableCell {
@@ -366,6 +426,16 @@ interface ProcessedTable {
      * @type {string}
      */
     id: string;
+    /**
+     * Docling self reference for the source table item
+     * @type {string}
+     */
+    sourceRef?: string;
+    /**
+     * Docling references for caption text items associated with this table
+     * @type {string[]}
+     */
+    captionSourceRefs?: string[];
     /**
      * Caption information for the table (if available)
      * @type {Caption}
@@ -389,7 +459,9 @@ interface ProcessedTable {
     /**
      * Table data (2D array)
      *
-     * Access using grid[row][col].
+     * Access using grid[row][col]. For source lookup, combine `sourceRef` with
+     * the row and column indexes because processed cells do not store cell-level
+     * source references.
      *
      * @type {ProcessedTableCell[][]}
      */
@@ -412,6 +484,11 @@ interface ProcessedFootnote {
      * @type {string}
      */
     id: string;
+    /**
+     * Docling self reference for the source footnote text item
+     * @type {string}
+     */
+    sourceRef?: string;
     /**
      * Text content of the footnote
      *
@@ -438,6 +515,16 @@ interface ProcessedDocument {
      * @type {string}
      */
     reportId: string;
+    /**
+     * Processed document schema version
+     * @type {string}
+     */
+    schemaVersion?: string;
+    /**
+     * Source artifact metadata for the Docling artifact used to produce this document
+     * @type {ProcessedDocumentSource}
+     */
+    source?: ProcessedDocumentSource;
     /**
      * Mapping of page ranges for actual document pages per PDF page
      *
@@ -763,6 +850,8 @@ type ReviewAssistanceReportVersion = '1.0';
 type ReviewAssistanceDisposition = 'auto_applied' | 'proposal' | 'skipped';
 type ReviewAssistanceFailurePolicy = 'partial_page';
 type ReviewAssistancePageStatus = 'succeeded' | 'failed';
+type ReviewAssistanceWorkItemKind = 'text_ocr_hanja' | 'text_integrity' | 'text_role_footnote' | 'table' | 'picture_caption' | 'picture_split' | 'layout_bbox_order';
+type ReviewAssistanceCallTraceValidation = 'passed' | 'reasked' | 'failed';
 type ReviewAssistanceIssueCategory = 'text' | 'table' | 'caption' | 'picture' | 'reading_order' | 'role' | 'text_integrity' | 'paragraph' | 'footnote' | 'bbox' | 'multi_page_table' | 'domain_pattern' | 'review_execution';
 type ReviewAssistanceIssueSeverity = 'info' | 'warning' | 'error';
 type ReviewAssistanceProgressSubstage = 'review-assistance:prepare' | 'review-assistance:page' | 'review-assistance:patch' | 'review-assistance:write-report';
@@ -902,6 +991,18 @@ interface ReviewAssistancePageResult {
         code?: string;
     };
 }
+interface ReviewAssistanceCallTrace {
+    workItemId: string;
+    kind: ReviewAssistanceWorkItemKind;
+    pageNo: number;
+    targetRefs: string[];
+    modelId?: string;
+    attempts: number;
+    startedAt: string;
+    durationMs: number;
+    validation: ReviewAssistanceCallTraceValidation;
+    failureReasons?: string[];
+}
 interface ReviewAssistanceReport {
     schemaName: ReviewAssistanceReportSchemaName;
     version: ReviewAssistanceReportVersion;
@@ -917,6 +1018,9 @@ interface ReviewAssistanceReport {
         autoApplyThreshold: number;
         proposalThreshold: number;
         maxRetries: number;
+        tableMaxRetries?: number;
+        localModelConcurrency?: number;
+        workItemTimeoutMs?: number;
         temperature: number;
         outputLanguage: string;
         failurePolicy: ReviewAssistanceFailurePolicy;
@@ -933,6 +1037,7 @@ interface ReviewAssistanceReport {
         textIntegrityIssueCount?: number;
     };
     pages: ReviewAssistancePageResult[];
+    callTraces: ReviewAssistanceCallTrace[];
 }
 interface ReviewAssistanceProgressEvent {
     substage: ReviewAssistanceProgressSubstage;
@@ -948,4 +1053,4 @@ interface ReviewAssistanceProgressEvent {
     message?: string;
 }
 
-export { BCP47_LANGUAGE_TAGS, BCP47_LANGUAGE_TAG_SET, type Bcp47LanguageTag, type Caption, type Chapter, type ComponentUsageReport, type DoclingBBox, type DoclingBaseNode, type DoclingBody, type DoclingDocument, type DoclingGroupItem, type DoclingOrigin, type DoclingPage, type DoclingPageImage, type DoclingPictureItem, type DoclingProv, type DoclingReference, type DoclingTableCell, type DoclingTableData, type DoclingTableItem, type DoclingTextItem, type DocumentProcessResult, LANGUAGE_DISPLAY_NAMES, type ModelUsageDetail, type OcrStrategy, type PageRange, type PhaseUsageReport, type ProcessedDocument, type ProcessedFootnote, type ProcessedImage, type ProcessedTable, type ProcessedTableCell, type ReviewAssistanceCommand, type ReviewAssistanceDecision, type ReviewAssistanceDecisionEvidence, type ReviewAssistanceDisposition, type ReviewAssistanceFailurePolicy, type ReviewAssistanceImageRegion, type ReviewAssistanceIssue, type ReviewAssistanceIssueCategory, type ReviewAssistanceIssueSeverity, type ReviewAssistancePageResult, type ReviewAssistancePageStatus, type ReviewAssistanceProgressEvent, type ReviewAssistanceProgressStatus, type ReviewAssistanceProgressSubstage, type ReviewAssistanceReport, type ReviewAssistanceReportSchemaName, type ReviewAssistanceReportVersion, type ReviewAssistanceTableCell, type TextBlock, type TokenUsageMetadata, type TokenUsageMetadataValue, type TokenUsageReport, type TokenUsageSummary, buildLanguageDescription, getLanguageDisplayName, isValidBcp47Tag, normalizeToBcp47 };
+export { BCP47_LANGUAGE_TAGS, BCP47_LANGUAGE_TAG_SET, type Bcp47LanguageTag, type Caption, type Chapter, type ComponentUsageReport, type DoclingBBox, type DoclingBaseNode, type DoclingBody, type DoclingDocument, type DoclingGroupItem, type DoclingOrigin, type DoclingPage, type DoclingPageImage, type DoclingPictureItem, type DoclingProv, type DoclingReference, type DoclingTableCell, type DoclingTableData, type DoclingTableItem, type DoclingTextItem, type DocumentProcessResult, LANGUAGE_DISPLAY_NAMES, type ModelUsageDetail, type OcrStrategy, type PageRange, type PhaseUsageReport, type ProcessedDocument, type ProcessedDocumentSource, type ProcessedFootnote, type ProcessedImage, type ProcessedTable, type ProcessedTableCell, type ReviewAssistanceCallTrace, type ReviewAssistanceCallTraceValidation, type ReviewAssistanceCommand, type ReviewAssistanceDecision, type ReviewAssistanceDecisionEvidence, type ReviewAssistanceDisposition, type ReviewAssistanceFailurePolicy, type ReviewAssistanceImageRegion, type ReviewAssistanceIssue, type ReviewAssistanceIssueCategory, type ReviewAssistanceIssueSeverity, type ReviewAssistancePageResult, type ReviewAssistancePageStatus, type ReviewAssistanceProgressEvent, type ReviewAssistanceProgressStatus, type ReviewAssistanceProgressSubstage, type ReviewAssistanceReport, type ReviewAssistanceReportSchemaName, type ReviewAssistanceReportVersion, type ReviewAssistanceTableCell, type ReviewAssistanceWorkItemKind, type TextBlock, type TokenUsageMetadata, type TokenUsageMetadataValue, type TokenUsageReport, type TokenUsageSummary, buildLanguageDescription, getLanguageDisplayName, isValidBcp47Tag, normalizeToBcp47 };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@heripo/model",
   "private": false,
   "type": "module",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "Document models and type definitions for heripo engine",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -52,11 +52,11 @@
     "access": "public"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^4.1.5",
+    "@vitest/coverage-v8": "^4.1.6",
     "tsup": "^8.5.1",
-    "vitest": "^4.1.5",
-    "@heripo/tsconfig": "0.0.0",
+    "vitest": "^4.1.6",
     "@heripo/tsup-config": "0.0.0",
+    "@heripo/tsconfig": "0.0.0",
     "@heripo/vitest-config": "0.0.0"
   },
   "scripts": {