@heripo/document-processor 0.1.21 → 0.1.23

package/README.ko.md

@@ -75,7 +75,7 @@ const processor = new DocumentProcessor({
 const { document, usage } = await processor.process(
   doclingDocument, // PDF 파서 출력
   'report-001', // 리포트 ID
-  outputPath, // 이미지/페이지가 있는 디렉토리
+  artifactDir, // 이미지/페이지 등 parser 산출물이 있는 디렉토리
 );
 
 // 결과 사용
@@ -111,13 +111,81 @@ const processor = new DocumentProcessor({
 
   // 재시도 설정
   maxRetries: 3,
+  maxValidationRetries: 3,
   enableFallbackRetry: true, // fallback 모델로 자동 재시도 (기본값: false)
 });
 
 const { document, usage } = await processor.process(
   doclingDocument,
   'report-001',
-  outputPath,
+  artifactDir,
+);
+```
+
+### 수동 페이지 범위 매핑
+
+페이지 범위 매핑을 이미 검수했다면 `process()`의 네 번째 인자로 전달해
+PageRangeParser 자동 실행을 건너뛸 수 있습니다. 전달한 매핑은 추가 후처리 없이
+그대로 사용됩니다.
+
+```typescript
+import type { PageRange } from '@heripo/model';
+
+const pageRangeMap: Record<number, PageRange> = {
+  1: { startPageNo: 0, endPageNo: 0 },
+  2: { startPageNo: 1, endPageNo: 1 },
+  3: { startPageNo: 2, endPageNo: 3 },
+};
+
+const { document, usage } = await processor.process(
+  doclingDocument,
+  'report-001',
+  artifactDir,
+  { pageRangeMap },
+);
+```
+
+### 수동 TOC 항목
+
+목차를 이미 검수했다면 `process()`의 네 번째 인자로 `tocEntries`를 전달해
+자동 TOC 추출을 건너뛸 수 있습니다. 전달한 항목은 추가 추출이나 검증 없이
+그대로 사용됩니다.
+
+```typescript
+import type { TocEntry } from '@heripo/document-processor';
+
+const tocEntries: TocEntry[] = [
+  {
+    title: '제1장 조사 개요',
+    level: 1,
+    pageNo: 1,
+    children: [
+      {
+        title: '1. 조사 경위',
+        level: 2,
+        pageNo: 3,
+      },
+    ],
+  },
+];
+
+const { document, usage } = await processor.process(
+  doclingDocument,
+  'report-001',
+  artifactDir,
+  { tocEntries },
+);
+```
+
+수동 페이지 범위 매핑과 TOC 항목을 함께 전달하면 두 자동 단계를 모두
+건너뜁니다.
+
+```typescript
+const { document, usage } = await processor.process(
+  doclingDocument,
+  'report-001',
+  artifactDir,
+  { pageRangeMap, tocEntries },
 );
 ```
 
@@ -206,6 +274,7 @@ interface DocumentProcessorOptions {
 
   // 재시도 설정
   maxRetries?: number; // LLM API 재시도 횟수 (기본값: 3)
+  maxValidationRetries?: number; // TOC 검증 보정 재시도 횟수 (기본값: 3)
   enableFallbackRetry?: boolean; // Fallback 재시도 활성화 (기본값: false)
 
   // 고급 옵션
@@ -216,15 +285,23 @@ interface DocumentProcessorOptions {
 
 #### 메서드
 
-##### `process(doclingDoc, reportId, outputPath): Promise<DocumentProcessResult>`
+##### `process(doclingDoc, reportId, artifactDir, processOptions?): Promise<DocumentProcessResult>`
 
 DoclingDocument를 ProcessedDocument로 변환합니다.
 
+```typescript
+interface DocumentProcessorProcessOptions {
+  pageRangeMap?: Record<number, PageRange>;
+  tocEntries?: TocEntry[];
+}
+```
+
 **파라미터:**
 
 - `doclingDoc` (DoclingDocument): PDF 파서의 출력
 - `reportId` (string): 리포트 ID
-- `outputPath` (string): 이미지/페이지가 있는 출력 디렉토리
+- `artifactDir` (string): `images/`, `pages/`, `result.json` 같은 parser 산출물이 들어 있는 디렉토리
+- `processOptions` (DocumentProcessorProcessOptions, 선택): 문서별 처리 입력값. `pageRangeMap`이 제공되면 자동 페이지 범위 파싱을 건너뜁니다. `tocEntries`가 제공되면 자동 TOC 추출을 건너뜁니다.
 
 **반환값:**
 

package/README.md

@@ -75,7 +75,7 @@ const processor = new DocumentProcessor({
 const { document, usage } = await processor.process(
   doclingDocument, // PDF parser output
   'report-001', // Report ID
-  outputPath, // Directory containing images/pages
+  artifactDir, // Directory containing parser artifacts such as images/pages
 );
 
 // Use results
@@ -111,13 +111,81 @@ const processor = new DocumentProcessor({
 
   // Retry settings
   maxRetries: 3,
+  maxValidationRetries: 3,
   enableFallbackRetry: true, // Automatic retry with fallback model (default: false)
 });
 
 const { document, usage } = await processor.process(
   doclingDocument,
   'report-001',
-  outputPath,
+  artifactDir,
+);
+```
+
+### Manual Page Range Map
+
+If page range mapping has already been reviewed, pass it as the fourth
+`process()` argument to skip automatic PageRangeParser execution. The provided
+map is used as-is without additional post-processing.
+
+```typescript
+import type { PageRange } from '@heripo/model';
+
+const pageRangeMap: Record<number, PageRange> = {
+  1: { startPageNo: 0, endPageNo: 0 },
+  2: { startPageNo: 1, endPageNo: 1 },
+  3: { startPageNo: 2, endPageNo: 3 },
+};
+
+const { document, usage } = await processor.process(
+  doclingDocument,
+  'report-001',
+  artifactDir,
+  { pageRangeMap },
+);
+```
+
+### Manual TOC Entries
+
+If the table of contents has already been reviewed, pass `tocEntries` as the
+fourth `process()` argument to skip automatic TOC extraction. The provided
+entries are used as-is without additional extraction or validation.
+
+```typescript
+import type { TocEntry } from '@heripo/document-processor';
+
+const tocEntries: TocEntry[] = [
+  {
+    title: 'Chapter 1. Overview',
+    level: 1,
+    pageNo: 1,
+    children: [
+      {
+        title: '1. Background',
+        level: 2,
+        pageNo: 3,
+      },
+    ],
+  },
+];
+
+const { document, usage } = await processor.process(
+  doclingDocument,
+  'report-001',
+  artifactDir,
+  { tocEntries },
+);
+```
+
+Manual page range maps and TOC entries can be provided together to skip both
+automatic stages.
+
+```typescript
+const { document, usage } = await processor.process(
+  doclingDocument,
+  'report-001',
+  artifactDir,
+  { pageRangeMap, tocEntries },
 );
 ```
 
@@ -206,6 +274,7 @@ interface DocumentProcessorOptions {
 
   // Retry settings
   maxRetries?: number; // LLM API retry count (default: 3)
+  maxValidationRetries?: number; // TOC validation correction retry count (default: 3)
   enableFallbackRetry?: boolean; // Enable fallback retry (default: false)
 
   // Advanced options
@@ -216,15 +285,23 @@ interface DocumentProcessorOptions {
 
 #### Methods
 
-##### `process(doclingDoc, reportId, outputPath): Promise<DocumentProcessResult>`
+##### `process(doclingDoc, reportId, artifactDir, processOptions?): Promise<DocumentProcessResult>`
 
 Transforms DoclingDocument into ProcessedDocument.
 
+```typescript
+interface DocumentProcessorProcessOptions {
+  pageRangeMap?: Record<number, PageRange>;
+  tocEntries?: TocEntry[];
+}
+```
+
 **Parameters:**
 
 - `doclingDoc` (DoclingDocument): PDF parser output
 - `reportId` (string): Report ID
-- `outputPath` (string): Output directory containing images/pages
+- `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.
 
 **Returns:**
 

package/dist/index.cjs

@@ -1284,12 +1284,12 @@ var ResourceConverter = class {
    *
    * Runs image and table conversions in parallel, then footnotes synchronously.
    */
-  async convertAll(doclingDoc, outputPath) {
+  async convertAll(doclingDoc, artifactDir) {
     this.logger.info(
       "[ResourceConverter] Converting images, tables, and footnotes..."
     );
     const [images, tables] = await Promise.all([
-      this.convertImages(doclingDoc, outputPath),
+      this.convertImages(doclingDoc, artifactDir),
       this.convertTables(doclingDoc)
     ]);
     const footnotes = this.convertFootnotes(doclingDoc);
@@ -1301,7 +1301,7 @@ var ResourceConverter = class {
   /**
    * Convert images from DoclingDocument to ProcessedImage[]
    */
-  async convertImages(doclingDoc, outputPath) {
+  async convertImages(doclingDoc, artifactDir) {
     this.logger.info(
       `[ResourceConverter] Converting ${doclingDoc.pictures.length} images...`
     );
@@ -1311,7 +1311,7 @@ var ResourceConverter = class {
     const images = doclingDoc.pictures.map(
       (picture, index) => ({
         id: this.idGenerator.generateImageId(),
-        path: `${outputPath}/images/image_${index}.png`,
+        path: `${artifactDir}/images/image_${index}.png`,
         pdfPageNo: picture.prov?.[0]?.page_no ?? 0
       })
     );
@@ -2132,7 +2132,7 @@ var TextLLMComponent = class extends BaseLLMComponent {
 };
 
 // src/extractors/toc-extractor.ts
-var MAX_VALIDATION_RETRIES = 3;
+var DEFAULT_MAX_VALIDATION_RETRIES = 3;
 var VALIDATION_CODE_DESCRIPTIONS = {
   V001: "Page numbers must be in non-decreasing order within the same level. A decrease usually means a hierarchy or page number error.",
   V002: "Page number is out of valid range (must be >= 1 and <= total pages).",
@@ -2165,6 +2165,7 @@ var TocResponseSchema = import_zod.z.object({
 var TocExtractor = class extends TextLLMComponent {
   validationOptions;
   skipValidation;
+  maxValidationRetries;
   constructor(logger, model, options, fallbackModel, abortSignal) {
     super(
       logger,
@@ -2175,11 +2176,12 @@ var TocExtractor = class extends TextLLMComponent {
     );
     this.validationOptions = options?.validation;
     this.skipValidation = options?.skipValidation ?? false;
+    this.maxValidationRetries = options?.maxValidationRetries ?? DEFAULT_MAX_VALIDATION_RETRIES;
   }
   /**
    * Extract TOC structure from Markdown
    *
-   * When validation fails, retries with correction feedback up to MAX_VALIDATION_RETRIES times.
+   * When validation fails, retries with correction feedback up to maxValidationRetries times.
    *
    * @param markdown - Markdown representation of TOC area
    * @param validationOverrides - Optional overrides for validation options (merged with constructor options)
@@ -2209,10 +2211,10 @@ var TocExtractor = class extends TextLLMComponent {
           entries,
           validationOverrides
         );
-        for (let attempt = 1; attempt <= MAX_VALIDATION_RETRIES && validationError !== null; attempt++) {
+        for (let attempt = 1; attempt <= this.maxValidationRetries && validationError !== null; attempt++) {
           this.log(
             "warn",
-            `Validation failed (attempt ${attempt}/${MAX_VALIDATION_RETRIES}), retrying with correction feedback`
+            `Validation failed (attempt ${attempt}/${this.maxValidationRetries}), retrying with correction feedback`
           );
           const correctionPrompt = this.buildCorrectionPrompt(
             markdown,
@@ -2235,7 +2237,7 @@ var TocExtractor = class extends TextLLMComponent {
         if (validationError !== null) {
           this.log(
             "error",
-            `Validation failed after ${MAX_VALIDATION_RETRIES} retries:
+            `Validation failed after ${this.maxValidationRetries} retries:
 ${validationError.getSummary()}`
           );
           throw validationError;
@@ -2427,10 +2429,10 @@ var import_zod2 = require("zod");
 var fs = __toESM(require("fs"), 1);
 var path = __toESM(require("path"), 1);
 var VisionLLMComponent = class extends BaseLLMComponent {
-  outputPath;
-  constructor(logger, model, componentName, outputPath, options, fallbackModel, aggregator) {
+  artifactDir;
+  constructor(logger, model, componentName, artifactDir, options, fallbackModel, aggregator) {
     super(logger, model, componentName, options, fallbackModel, aggregator);
-    this.outputPath = outputPath;
+    this.artifactDir = artifactDir;
   }
   /**
    * Call LLM with vision capabilities using LLMCaller.callVision()
@@ -2462,12 +2464,12 @@ var VisionLLMComponent = class extends BaseLLMComponent {
   /**
    * Build image content object for vision LLM messages
    *
-   * @param imagePath - Path to the image file (relative to outputPath or absolute)
+   * @param imagePath - Path to the image file (relative to artifactDir or absolute)
    * @param mimeType - MIME type of the image (default: 'image/png')
    * @returns ImageContent object for LLM message
    */
   buildImageContent(imagePath, mimeType = "image/png") {
-    const absolutePath = path.isAbsolute(imagePath) ? imagePath : path.resolve(this.outputPath, imagePath);
+    const absolutePath = path.isAbsolute(imagePath) ? imagePath : path.resolve(this.artifactDir, imagePath);
     const imageData = new Uint8Array(fs.readFileSync(absolutePath));
     return {
       type: "image",
@@ -2486,12 +2488,12 @@ var VisionTocExtractionSchema = import_zod2.z.object({
 var VisionTocExtractor = class extends VisionLLMComponent {
   firstBatchSize;
   secondBatchSize;
-  constructor(logger, model, outputPath, options, fallbackModel, aggregator) {
+  constructor(logger, model, artifactDir, options, fallbackModel, aggregator) {
     super(
       logger,
       model,
       "VisionTocExtractor",
-      outputPath,
+      artifactDir,
       options,
       fallbackModel,
       aggregator ?? new LLMTokenUsageAggregator()
@@ -2624,7 +2626,7 @@ var VisionTocExtractor = class extends VisionLLMComponent {
     const imageContents = [];
     for (let pageNo = startPage; pageNo <= endPage; pageNo++) {
       const imagePath = path2.resolve(
-        this.outputPath,
+        this.artifactDir,
         `pages/page_${pageNo - 1}.png`
       );
       const imageData = new Uint8Array(fs2.readFileSync(imagePath));
@@ -3034,12 +3036,12 @@ var PageRangeParser = class extends VisionLLMComponent {
   SAMPLE_SIZE = 3;
   MAX_PATTERN_RETRIES = 19;
   SIZE_TOLERANCE = 5;
-  constructor(logger, model, outputPath, maxRetries = 3, fallbackModel, aggregator, abortSignal) {
+  constructor(logger, model, artifactDir, maxRetries = 3, fallbackModel, aggregator, abortSignal) {
     super(
       logger,
       model,
       "PageRangeParser",
-      outputPath,
+      artifactDir,
       { maxRetries, abortSignal },
       fallbackModel,
       aggregator ?? new LLMTokenUsageAggregator()
@@ -3238,7 +3240,7 @@ var PageRangeParser = class extends VisionLLMComponent {
     const imageContentsFromPages = pageNos.map((pageNo) => {
       const page = pages[pageNo - 1];
       const imagePath = path3.resolve(
-        this.outputPath,
+        this.artifactDir,
         `pages/page_${pageNo - 1}.png`
       );
       const imageData = new Uint8Array(fs3.readFileSync(imagePath));
@@ -4422,6 +4424,7 @@ var DocumentProcessor = class {
   captionParserBatchSize;
   captionValidatorBatchSize;
   maxRetries;
+  maxValidationRetries;
   enableFallbackRetry;
   abortSignal;
   onTokenUsage;
@@ -4451,6 +4454,7 @@ var DocumentProcessor = class {
     this.captionParserBatchSize = options.captionParserBatchSize;
     this.captionValidatorBatchSize = options.captionValidatorBatchSize;
     this.maxRetries = options.maxRetries ?? 3;
+    this.maxValidationRetries = options.maxValidationRetries ?? 3;
     this.enableFallbackRetry = options.enableFallbackRetry ?? false;
     this.abortSignal = options.abortSignal;
     this.onTokenUsage = options.onTokenUsage;
@@ -4482,7 +4486,7 @@ var DocumentProcessor = class {
    * Conversion process:
    * 1. Initialize processors and resolvers
    * 2. Normalize and filter texts
-   * 3. Clean texts and parse page ranges (parallel)
+   * 3. Clean texts and resolve page ranges
    * 4. Extract table of contents
    * 5. Convert images and tables (parallel)
    * 6. Convert chapters and link resources
@@ -4491,19 +4495,20 @@ var DocumentProcessor = class {
    *
    * @param doclingDoc - Original document extracted from Docling SDK
    * @param reportId - Report unique identifier
-   * @param outputPath - Path containing images and pages subdirectories (images/image_0.png, pages/page_0.png, etc.)
+   * @param artifactDir - Directory containing parser artifacts such as images/, pages/, and result.json
+   * @param processOptions - Per-document processing inputs such as manually verified page range mappings and TOC entries
    * @returns Document processing result with ProcessedDocument and token usage report
    *
    * @throws {TocExtractError} When TOC extraction fails
    * @throws {PageRangeParseError} When page range parsing fails
    * @throws {ConversionError} When error occurs during conversion
    */
-  async process(doclingDoc, reportId, outputPath) {
+  async process(doclingDoc, reportId, artifactDir, processOptions = {}) {
     this.logger.info("[DocumentProcessor] Starting document processing...");
     this.logger.info("[DocumentProcessor] Report ID:", reportId);
     this.usageAggregator.reset();
     this.checkAborted();
-    this.initializeProcessors(doclingDoc, outputPath);
+    this.initializeProcessors(doclingDoc, artifactDir);
     const startTimeFilter = Date.now();
     const filtered = this.normalizeAndFilterTexts(doclingDoc);
     const filteringTime = Date.now() - startTimeFilter;
@@ -4512,24 +4517,31 @@ var DocumentProcessor = class {
     );
     this.checkAborted();
     const startTimePageRange = Date.now();
-    const pageRangeMap = await this.parsePageRanges(doclingDoc);
+    const pageRangeMap = processOptions.pageRangeMap !== void 0 ? processOptions.pageRangeMap : await this.parsePageRanges(doclingDoc);
+    if (processOptions.pageRangeMap !== void 0) {
+      this.logger.info(
+        `[DocumentProcessor] Using injected page range map with ${Object.keys(pageRangeMap).length} entries`
+      );
+    }
     const pageRangeTime = Date.now() - startTimePageRange;
     this.logger.info(
-      `[DocumentProcessor] Page range parsing took ${pageRangeTime}ms`
+      `[DocumentProcessor] Page range resolution took ${pageRangeTime}ms`
     );
     this.emitTokenUsage();
     this.checkAborted();
     const startTimeToc = Date.now();
-    const tocEntries = await this.tocExtractionPipeline.extract(
-      doclingDoc,
-      filtered
-    );
+    const tocEntries = processOptions.tocEntries !== void 0 ? processOptions.tocEntries : await this.tocExtractionPipeline.extract(doclingDoc, filtered);
+    if (processOptions.tocEntries !== void 0) {
+      this.logger.info(
+        `[DocumentProcessor] Using injected TOC entries with ${tocEntries.length} top-level entries`
+      );
+    }
     const tocTime = Date.now() - startTimeToc;
     this.logger.info(`[DocumentProcessor] TOC extraction took ${tocTime}ms`);
     this.emitTokenUsage();
     this.checkAborted();
     const startTimeResources = Date.now();
-    const { images, tables, footnotes } = await this.resourceConverter.convertAll(doclingDoc, outputPath);
+    const { images, tables, footnotes } = await this.resourceConverter.convertAll(doclingDoc, artifactDir);
     const resourcesTime = Date.now() - startTimeResources;
     this.logger.info(
       `[DocumentProcessor] Resource conversion took ${resourcesTime}ms`
@@ -4573,7 +4585,7 @@ var DocumentProcessor = class {
    *
    * Sets up RefResolver, PageRangeParser, TocFinder, and TocExtractor
    */
-  initializeProcessors(doclingDoc, outputPath) {
+  initializeProcessors(doclingDoc, artifactDir) {
     this.logger.info("[DocumentProcessor] Initializing processors...");
     this.logger.info("[DocumentProcessor] - RefResolver");
     this.refResolver = new RefResolver(this.logger, doclingDoc);
@@ -4581,7 +4593,7 @@ var DocumentProcessor = class {
     this.pageRangeParser = new PageRangeParser(
       this.logger,
       this.pageRangeParserModel,
-      outputPath,
+      artifactDir,
       this.maxRetries,
       this.enableFallbackRetry ? this.fallbackModel : void 0,
       this.usageAggregator,
@@ -4594,7 +4606,8 @@ var DocumentProcessor = class {
       this.logger,
       this.tocExtractorModel,
       {
-        maxRetries: this.maxRetries
+        maxRetries: this.maxRetries,
+        maxValidationRetries: this.maxValidationRetries
       },
       this.enableFallbackRetry ? this.fallbackModel : void 0,
       this.abortSignal
@@ -4619,7 +4632,7 @@ var DocumentProcessor = class {
     this.visionTocExtractor = new VisionTocExtractor(
       this.logger,
       this.visionTocExtractorModel,
-      outputPath,
+      artifactDir,
       { maxRetries: this.maxRetries, abortSignal: this.abortSignal },
       this.enableFallbackRetry ? this.fallbackModel : void 0,
       this.usageAggregator