@heripo/document-processor 0.1.4 → 0.1.6

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { LoggerMethods } from '@heripo/logger';
-import { DoclingDocument, DocumentProcessResult, Caption, PageRange, DoclingTextItem, DoclingPictureItem, DoclingTableItem, DoclingGroupItem, ProcessedImage, ProcessedTable, ProcessedFootnote, Chapter } from '@heripo/model';
+import { DoclingDocument, HanjaAssessment, DocumentProcessResult, Caption, PageRange, DoclingTextItem, DoclingPictureItem, DoclingTableItem, DoclingGroupItem, ProcessedImage, ProcessedTable, ProcessedFootnote, Chapter } from '@heripo/model';
 import { LanguageModel } from 'ai';
 import { LLMTokenUsageAggregator, ExtendedTokenUsage } from '@heripo/shared';
 import { z } from 'zod';
@@ -43,6 +43,11 @@ interface DocumentProcessorOptions {
      * Falls back to 'fallbackModel' if not provided.
      */
     captionParserModel?: LanguageModel;
+    /**
+     * Model for HanjaQualitySampler - evaluates KCJ character quality in OCR output.
+     * Requires vision capabilities. Falls back to 'fallbackModel' if not provided.
+     */
+    hanjaQualitySamplerModel?: LanguageModel;
     /**
      * Batch size for TextCleaner text normalization (synchronous processing)
      */
@@ -132,6 +137,7 @@ declare class DocumentProcessor {
     private readonly validatorModel;
     private readonly visionTocExtractorModel;
     private readonly captionParserModel;
+    private readonly hanjaQualitySamplerModel;
     private readonly textCleanerBatchSize;
     private readonly captionParserBatchSize;
     private readonly captionValidatorBatchSize;
@@ -157,6 +163,18 @@ declare class DocumentProcessor {
      * @throws {Error} with name 'AbortError' if aborted
      */
     private checkAborted;
+    /**
+     * Assess the quality of KCJ (Hanja) character recognition in the OCR output.
+     *
+     * Samples pages containing KCJ characters and uses Vision LLM to compare
+     * the OCR text against the original page images. Returns an assessment
+     * indicating whether the document should be re-parsed with VLM pipeline.
+     *
+     * @param doclingDoc - Original document extracted from Docling SDK
+     * @param outputPath - Path containing pages subdirectory (pages/page_0.png, etc.)
+     * @returns Assessment result with severity and recommendation
+     */
+    assessHanjaQuality(doclingDoc: DoclingDocument, outputPath: string): Promise<HanjaAssessment>;
     /**
      * Converts DoclingDocument to ProcessedDocument with token usage tracking.
      *
@@ -722,6 +740,27 @@ declare class PageRangeParser extends VisionLLMComponent {
     protected buildUserPrompt(pageNos: number[]): string;
 }
 
+/**
+ * Single validation issue detected during TOC validation
+ */
+interface TocValidationIssue {
+    /**
+     * Issue code (V001, V002, etc.)
+     */
+    code: string;
+    /**
+     * Human-readable error message
+     */
+    message: string;
+    /**
+     * Path to the problematic entry (e.g., "[0].children[2]")
+     */
+    path: string;
+    /**
+     * The problematic entry
+     */
+    entry: TocEntry;
+}
 /**
  * TocExtractError
  *
@@ -768,6 +807,12 @@ interface TocValidationOptions {
      * Maximum allowed title length (default: 200)
      */
     maxTitleLength?: number;
+    /**
+     * Maximum ratio of the first entry's page to total pages (default: 0.3)
+     * Used for V007 completeness check - if the first level-1 entry
+     * starts beyond max(50, totalPages * ratio), the TOC may be incomplete.
+     */
+    maxFirstEntryPageRatio?: number;
 }
 
 /**
@@ -956,7 +1001,7 @@ declare class TocFinder {
      */
     private isTableTocLike;
     /**
-     * Expand TOC area to consecutive pages
+     * Expand TOC area to consecutive pages (both backward and forward)
      */
     private expandToConsecutivePages;
     /**
@@ -1016,6 +1061,9 @@ interface TocExtractorOptions extends BaseLLMComponentOptions {
  *
  * Uses high-performance LLM to extract structured TOC from Markdown representation.
  * Extends TextLLMComponent for standardized LLM call handling.
+ *
+ * When validation fails, automatically retries with correction feedback
+ * up to MAX_VALIDATION_RETRIES times before throwing.
  */
 declare class TocExtractor extends TextLLMComponent {
     private readonly validationOptions?;
@@ -1024,21 +1072,34 @@ declare class TocExtractor extends TextLLMComponent {
     /**
      * Extract TOC structure from Markdown
      *
+     * When validation fails, retries with correction feedback up to MAX_VALIDATION_RETRIES times.
+     *
      * @param markdown - Markdown representation of TOC area
-     * @returns Object with entries array and token usage information
+     * @param validationOverrides - Optional overrides for validation options (merged with constructor options)
+     * @returns Object with entries array and token usage array (initial extraction + any corrections)
      * @throws {TocParseError} When LLM fails to parse structure
-     * @throws {TocValidationError} When validation fails
+     * @throws {TocValidationError} When validation fails after all retries
      */
-    extract(markdown: string): Promise<{
+    extract(markdown: string, validationOverrides?: Partial<TocValidationOptions>): Promise<{
         entries: TocEntry[];
-        usage: ExtendedTokenUsage;
+        usages: ExtendedTokenUsage[];
     }>;
     /**
-     * Validate extracted entries
+     * Validate extracted entries and return error or null
+     *
+     * Unlike validateOrThrow, this returns the error instead of throwing,
+     * allowing the retry loop to handle it.
+     *
+     * @returns TocValidationError if validation fails, null if valid
+     */
+    private tryValidateEntries;
+    /**
+     * Build correction prompt with validation error feedback
      *
-     * @throws {TocValidationError} When validation fails
+     * Includes the original markdown, previous extraction result,
+     * validation errors, and guidance for fixing common mistakes.
      */
-    private validateEntries;
+    protected buildCorrectionPrompt(markdown: string, previousEntries: TocEntry[], issues: TocValidationIssue[]): string;
     /**
      * Build system prompt for TOC extraction
      */
@@ -1439,4 +1500,64 @@ declare class ChapterConverter {
     private buildChapterMap;
 }
 
-export { BaseLLMComponent, type BaseLLMComponentOptions, BaseValidator, type BaseValidatorOptions, CONTINUATION_MARKERS, CaptionParseError, CaptionParser, type CaptionParserOptions, CaptionValidationError, CaptionValidator, type CaptionValidatorOptions, ChapterConverter, DocumentProcessor, type DocumentProcessorOptions, type ImageContent, PAGE_NUMBER_PATTERN, PagePattern, PageRangeParseError, PageRangeParser, type PageSizeGroup, TOC_KEYWORDS, TextLLMComponent, type TocAreaResult, type TocContentValidationResult, TocContentValidationSchema, TocContentValidator, type TocContentValidatorOptions, type TocEntry, TocEntrySchema, TocExtractError, TocExtractor, type TocExtractorOptions, TocFinder, type TocFinderOptions, TocNotFoundError, TocParseError, type TocResponse, TocResponseSchema, VisionLLMComponent, type VisionLLMComponentOptions, type VisionTocExtractionResult, VisionTocExtractionSchema, VisionTocExtractor, type VisionTocExtractorOptions };
+/**
+ * HanjaQualitySampler
+ *
+ * Evaluates the quality of KCJ (Chinese/Japanese/Korean) character recognition
+ * in OCR-processed documents. Samples a subset of pages containing KCJ text and
+ * uses Vision LLM to compare the OCR output against the original page images.
+ *
+ * This is used to determine whether a document should be re-parsed using the
+ * VLM pipeline for better KCJ character accuracy.
+ */
+declare class HanjaQualitySampler extends VisionLLMComponent {
+    constructor(logger: LoggerMethods, model: LanguageModel, outputPath: string, maxRetries?: number, fallbackModel?: LanguageModel, aggregator?: LLMTokenUsageAggregator, abortSignal?: AbortSignal);
+    /**
+     * Assess the quality of KCJ character recognition in the document
+     *
+     * @param doclingDoc - DoclingDocument to assess
+     * @returns Assessment result indicating whether VLM re-parse is needed
+     */
+    assess(doclingDoc: DoclingDocument): Promise<HanjaAssessment>;
+    /**
+     * Get the eligible page range after trimming front/back edges.
+     * Returns cutoff values where eligible pages satisfy: pageNo > frontCutoff && pageNo <= backCutoff
+     */
+    private getEligiblePageRange;
+    /**
+     * Get page numbers that are "image-only" (contain pictures but minimal text).
+     * These pages (e.g., photo plates/도판) are unsuitable for KCJ quality assessment.
+     */
+    private getImageOnlyPages;
+    /**
+     * Get all pages with substantial text content.
+     * Pages with fewer characters than MIN_TEXT_LENGTH (e.g., page numbers, headers only) are excluded.
+     */
+    private getTextPages;
+    /**
+     * Select sample pages with highest text density.
+     * Prefers pages in the eligible range (not edge-trimmed) and not image-only.
+     * Falls back to all text pages if filtering leaves too few candidates.
+     */
+    private selectSamplePages;
+    /**
+     * Evaluate sampled pages using Vision LLM
+     */
+    private evaluatePages;
+    /**
+     * Evaluate a single page by comparing OCR text against the page image
+     */
+    private evaluateSinglePage;
+    /**
+     * Aggregate individual page results into final assessment
+     */
+    private aggregateResults;
+    /**
+     * Get page number from a text item
+     */
+    private getPageNo;
+    protected buildSystemPrompt(): string;
+    protected buildUserPrompt(ocrText: string): string;
+}
+
+export { BaseLLMComponent, type BaseLLMComponentOptions, BaseValidator, type BaseValidatorOptions, CONTINUATION_MARKERS, CaptionParseError, CaptionParser, type CaptionParserOptions, CaptionValidationError, CaptionValidator, type CaptionValidatorOptions, ChapterConverter, DocumentProcessor, type DocumentProcessorOptions, HanjaQualitySampler, type ImageContent, PAGE_NUMBER_PATTERN, PagePattern, PageRangeParseError, PageRangeParser, type PageSizeGroup, TOC_KEYWORDS, TextLLMComponent, type TocAreaResult, type TocContentValidationResult, TocContentValidationSchema, TocContentValidator, type TocContentValidatorOptions, type TocEntry, TocEntrySchema, TocExtractError, TocExtractor, type TocExtractorOptions, TocFinder, type TocFinderOptions, TocNotFoundError, TocParseError, type TocResponse, TocResponseSchema, VisionLLMComponent, type VisionLLMComponentOptions, type VisionTocExtractionResult, VisionTocExtractionSchema, VisionTocExtractor, type VisionTocExtractorOptions };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { LoggerMethods } from '@heripo/logger';
-import { DoclingDocument, DocumentProcessResult, Caption, PageRange, DoclingTextItem, DoclingPictureItem, DoclingTableItem, DoclingGroupItem, ProcessedImage, ProcessedTable, ProcessedFootnote, Chapter } from '@heripo/model';
+import { DoclingDocument, HanjaAssessment, DocumentProcessResult, Caption, PageRange, DoclingTextItem, DoclingPictureItem, DoclingTableItem, DoclingGroupItem, ProcessedImage, ProcessedTable, ProcessedFootnote, Chapter } from '@heripo/model';
 import { LanguageModel } from 'ai';
 import { LLMTokenUsageAggregator, ExtendedTokenUsage } from '@heripo/shared';
 import { z } from 'zod';
@@ -43,6 +43,11 @@ interface DocumentProcessorOptions {
      * Falls back to 'fallbackModel' if not provided.
      */
     captionParserModel?: LanguageModel;
+    /**
+     * Model for HanjaQualitySampler - evaluates KCJ character quality in OCR output.
+     * Requires vision capabilities. Falls back to 'fallbackModel' if not provided.
+     */
+    hanjaQualitySamplerModel?: LanguageModel;
     /**
      * Batch size for TextCleaner text normalization (synchronous processing)
      */
@@ -132,6 +137,7 @@ declare class DocumentProcessor {
     private readonly validatorModel;
     private readonly visionTocExtractorModel;
     private readonly captionParserModel;
+    private readonly hanjaQualitySamplerModel;
     private readonly textCleanerBatchSize;
     private readonly captionParserBatchSize;
     private readonly captionValidatorBatchSize;
@@ -157,6 +163,18 @@ declare class DocumentProcessor {
      * @throws {Error} with name 'AbortError' if aborted
      */
     private checkAborted;
+    /**
+     * Assess the quality of KCJ (Hanja) character recognition in the OCR output.
+     *
+     * Samples pages containing KCJ characters and uses Vision LLM to compare
+     * the OCR text against the original page images. Returns an assessment
+     * indicating whether the document should be re-parsed with VLM pipeline.
+     *
+     * @param doclingDoc - Original document extracted from Docling SDK
+     * @param outputPath - Path containing pages subdirectory (pages/page_0.png, etc.)
+     * @returns Assessment result with severity and recommendation
+     */
+    assessHanjaQuality(doclingDoc: DoclingDocument, outputPath: string): Promise<HanjaAssessment>;
     /**
      * Converts DoclingDocument to ProcessedDocument with token usage tracking.
      *
@@ -722,6 +740,27 @@ declare class PageRangeParser extends VisionLLMComponent {
     protected buildUserPrompt(pageNos: number[]): string;
 }
 
+/**
+ * Single validation issue detected during TOC validation
+ */
+interface TocValidationIssue {
+    /**
+     * Issue code (V001, V002, etc.)
+     */
+    code: string;
+    /**
+     * Human-readable error message
+     */
+    message: string;
+    /**
+     * Path to the problematic entry (e.g., "[0].children[2]")
+     */
+    path: string;
+    /**
+     * The problematic entry
+     */
+    entry: TocEntry;
+}
 /**
  * TocExtractError
  *
@@ -768,6 +807,12 @@ interface TocValidationOptions {
      * Maximum allowed title length (default: 200)
      */
     maxTitleLength?: number;
+    /**
+     * Maximum ratio of the first entry's page to total pages (default: 0.3)
+     * Used for V007 completeness check - if the first level-1 entry
+     * starts beyond max(50, totalPages * ratio), the TOC may be incomplete.
+     */
+    maxFirstEntryPageRatio?: number;
 }
 
 /**
@@ -956,7 +1001,7 @@ declare class TocFinder {
      */
     private isTableTocLike;
     /**
-     * Expand TOC area to consecutive pages
+     * Expand TOC area to consecutive pages (both backward and forward)
      */
     private expandToConsecutivePages;
     /**
@@ -1016,6 +1061,9 @@ interface TocExtractorOptions extends BaseLLMComponentOptions {
  *
  * Uses high-performance LLM to extract structured TOC from Markdown representation.
  * Extends TextLLMComponent for standardized LLM call handling.
+ *
+ * When validation fails, automatically retries with correction feedback
+ * up to MAX_VALIDATION_RETRIES times before throwing.
  */
 declare class TocExtractor extends TextLLMComponent {
     private readonly validationOptions?;
@@ -1024,21 +1072,34 @@ declare class TocExtractor extends TextLLMComponent {
     /**
      * Extract TOC structure from Markdown
      *
+     * When validation fails, retries with correction feedback up to MAX_VALIDATION_RETRIES times.
+     *
      * @param markdown - Markdown representation of TOC area
-     * @returns Object with entries array and token usage information
+     * @param validationOverrides - Optional overrides for validation options (merged with constructor options)
+     * @returns Object with entries array and token usage array (initial extraction + any corrections)
      * @throws {TocParseError} When LLM fails to parse structure
-     * @throws {TocValidationError} When validation fails
+     * @throws {TocValidationError} When validation fails after all retries
      */
-    extract(markdown: string): Promise<{
+    extract(markdown: string, validationOverrides?: Partial<TocValidationOptions>): Promise<{
         entries: TocEntry[];
-        usage: ExtendedTokenUsage;
+        usages: ExtendedTokenUsage[];
     }>;
     /**
-     * Validate extracted entries
+     * Validate extracted entries and return error or null
+     *
+     * Unlike validateOrThrow, this returns the error instead of throwing,
+     * allowing the retry loop to handle it.
+     *
+     * @returns TocValidationError if validation fails, null if valid
+     */
+    private tryValidateEntries;
+    /**
+     * Build correction prompt with validation error feedback
      *
-     * @throws {TocValidationError} When validation fails
+     * Includes the original markdown, previous extraction result,
+     * validation errors, and guidance for fixing common mistakes.
      */
-    private validateEntries;
+    protected buildCorrectionPrompt(markdown: string, previousEntries: TocEntry[], issues: TocValidationIssue[]): string;
     /**
      * Build system prompt for TOC extraction
      */
@@ -1439,4 +1500,64 @@ declare class ChapterConverter {
     private buildChapterMap;
 }
 
-export { BaseLLMComponent, type BaseLLMComponentOptions, BaseValidator, type BaseValidatorOptions, CONTINUATION_MARKERS, CaptionParseError, CaptionParser, type CaptionParserOptions, CaptionValidationError, CaptionValidator, type CaptionValidatorOptions, ChapterConverter, DocumentProcessor, type DocumentProcessorOptions, type ImageContent, PAGE_NUMBER_PATTERN, PagePattern, PageRangeParseError, PageRangeParser, type PageSizeGroup, TOC_KEYWORDS, TextLLMComponent, type TocAreaResult, type TocContentValidationResult, TocContentValidationSchema, TocContentValidator, type TocContentValidatorOptions, type TocEntry, TocEntrySchema, TocExtractError, TocExtractor, type TocExtractorOptions, TocFinder, type TocFinderOptions, TocNotFoundError, TocParseError, type TocResponse, TocResponseSchema, VisionLLMComponent, type VisionLLMComponentOptions, type VisionTocExtractionResult, VisionTocExtractionSchema, VisionTocExtractor, type VisionTocExtractorOptions };
+/**
+ * HanjaQualitySampler
+ *
+ * Evaluates the quality of KCJ (Chinese/Japanese/Korean) character recognition
+ * in OCR-processed documents. Samples a subset of pages containing KCJ text and
+ * uses Vision LLM to compare the OCR output against the original page images.
+ *
+ * This is used to determine whether a document should be re-parsed using the
+ * VLM pipeline for better KCJ character accuracy.
+ */
+declare class HanjaQualitySampler extends VisionLLMComponent {
+    constructor(logger: LoggerMethods, model: LanguageModel, outputPath: string, maxRetries?: number, fallbackModel?: LanguageModel, aggregator?: LLMTokenUsageAggregator, abortSignal?: AbortSignal);
+    /**
+     * Assess the quality of KCJ character recognition in the document
+     *
+     * @param doclingDoc - DoclingDocument to assess
+     * @returns Assessment result indicating whether VLM re-parse is needed
+     */
+    assess(doclingDoc: DoclingDocument): Promise<HanjaAssessment>;
+    /**
+     * Get the eligible page range after trimming front/back edges.
+     * Returns cutoff values where eligible pages satisfy: pageNo > frontCutoff && pageNo <= backCutoff
+     */
+    private getEligiblePageRange;
+    /**
+     * Get page numbers that are "image-only" (contain pictures but minimal text).
+     * These pages (e.g., photo plates/도판) are unsuitable for KCJ quality assessment.
+     */
+    private getImageOnlyPages;
+    /**
+     * Get all pages with substantial text content.
+     * Pages with fewer characters than MIN_TEXT_LENGTH (e.g., page numbers, headers only) are excluded.
+     */
+    private getTextPages;
+    /**
+     * Select sample pages with highest text density.
+     * Prefers pages in the eligible range (not edge-trimmed) and not image-only.
+     * Falls back to all text pages if filtering leaves too few candidates.
+     */
+    private selectSamplePages;
+    /**
+     * Evaluate sampled pages using Vision LLM
+     */
+    private evaluatePages;
+    /**
+     * Evaluate a single page by comparing OCR text against the page image
+     */
+    private evaluateSinglePage;
+    /**
+     * Aggregate individual page results into final assessment
+     */
+    private aggregateResults;
+    /**
+     * Get page number from a text item
+     */
+    private getPageNo;
+    protected buildSystemPrompt(): string;
+    protected buildUserPrompt(ocrText: string): string;
+}
+
+export { BaseLLMComponent, type BaseLLMComponentOptions, BaseValidator, type BaseValidatorOptions, CONTINUATION_MARKERS, CaptionParseError, CaptionParser, type CaptionParserOptions, CaptionValidationError, CaptionValidator, type CaptionValidatorOptions, ChapterConverter, DocumentProcessor, type DocumentProcessorOptions, HanjaQualitySampler, type ImageContent, PAGE_NUMBER_PATTERN, PagePattern, PageRangeParseError, PageRangeParser, type PageSizeGroup, TOC_KEYWORDS, TextLLMComponent, type TocAreaResult, type TocContentValidationResult, TocContentValidationSchema, TocContentValidator, type TocContentValidatorOptions, type TocEntry, TocEntrySchema, TocExtractError, TocExtractor, type TocExtractorOptions, TocFinder, type TocFinderOptions, TocNotFoundError, TocParseError, type TocResponse, TocResponseSchema, VisionLLMComponent, type VisionLLMComponentOptions, type VisionTocExtractionResult, VisionTocExtractionSchema, VisionTocExtractor, type VisionTocExtractorOptions };