@heripo/pdf-parser 0.1.6 → 0.1.8

package/dist/index.d.cts

@@ -1,6 +1,8 @@
 import { LoggerMethods } from '@heripo/logger';
-import { ConversionOptions, VlmModelLocal } from 'docling-sdk';
-export { DEFAULT_VLM_MODEL, VLM_MODELS, VlmModelPreset, resolveVlmModel } from './vlm-models.cjs';
+import { OcrStrategy, TokenUsageReport } from '@heripo/model';
+import { LanguageModel } from 'ai';
+import { ConversionOptions } from 'docling-sdk';
+import { LLMTokenUsageAggregator } from '@heripo/shared';
 
 /**
  * Callback function invoked after PDF conversion completes
@@ -8,19 +10,37 @@ export { DEFAULT_VLM_MODEL, VLM_MODELS, VlmModelPreset, resolveVlmModel } from '
  */
 type ConversionCompleteCallback = (outputPath: string) => Promise<void> | void;
 /**
- * Pipeline type for PDF conversion
- * - 'standard': Use OCR-based pipeline (default, uses ocrmac)
- * - 'vlm': Use Vision Language Model pipeline for better KCJ/complex layout handling
+ * Extended options for PDF conversion.
  */
-type PipelineType = 'standard' | 'vlm';
-/**
- * Extended options for PDF conversion including pipeline selection
- */
-type PDFConvertOptions = Omit<ConversionOptions, 'to_formats' | 'image_export_mode' | 'ocr_engine' | 'accelerator_options' | 'ocr_options' | 'generate_picture_images' | 'images_scale' | 'force_ocr' | 'pipeline' | 'vlm_pipeline_model_local'> & {
+type PDFConvertOptions = Omit<ConversionOptions, 'to_formats' | 'image_export_mode' | 'ocr_engine' | 'accelerator_options' | 'ocr_options' | 'generate_picture_images' | 'images_scale' | 'force_ocr' | 'pipeline' | 'vlm_pipeline_model_local' | 'vlm_pipeline_model_api'> & {
     num_threads?: number;
-    pipeline?: PipelineType;
-    vlm_model?: string | VlmModelLocal;
+    /**
+     * Force pre-conversion to image-based PDF before processing.
+     * Requires ImageMagick and Ghostscript.
+     */
+    forceImagePdf?: boolean;
+    /** Vision model for OCR strategy sampling (enables new strategy-based flow) */
+    strategySamplerModel?: LanguageModel;
+    /** Vision model for VLM page processing (required when strategy selects VLM) */
+    vlmProcessorModel?: LanguageModel;
+    /** Concurrency for VLM page processing (default: 1) */
+    vlmConcurrency?: number;
+    /** Skip sampling and default to ocrmac */
+    skipSampling?: boolean;
+    /** Force a specific OCR method, bypassing sampling */
+    forcedMethod?: 'ocrmac' | 'vlm';
+    /** Token usage aggregator for tracking across sampling and VLM processing */
+    aggregator?: LLMTokenUsageAggregator;
+    /** Callback fired after each batch of VLM pages completes, with cumulative token usage */
+    onTokenUsage?: (report: TokenUsageReport) => void;
 };
+/** Result of strategy-based conversion */
+interface ConvertWithStrategyResult {
+    /** The OCR strategy that was determined */
+    strategy: OcrStrategy;
+    /** Token usage report from sampling and/or VLM processing (null when no LLM usage occurs) */
+    tokenUsageReport: TokenUsageReport | null;
+}
 
 type Options = {
     logger: LoggerMethods;
@@ -120,7 +140,15 @@ declare class PDFParser {
      */
     private restartServer;
     private waitForServerReady;
-    parse(url: string, reportId: string, onComplete: ConversionCompleteCallback, cleanupAfterCallback: boolean, options: PDFConvertOptions, abortSignal?: AbortSignal): Promise<void>;
+    parse(url: string, reportId: string, onComplete: ConversionCompleteCallback, cleanupAfterCallback: boolean, options: PDFConvertOptions, abortSignal?: AbortSignal): Promise<TokenUsageReport | null>;
+    /**
+     * Parse a PDF using OCR strategy sampling to decide between ocrmac and VLM.
+     * Delegates to PDFConverter.convertWithStrategy() and returns the token usage report.
+     *
+     * Server recovery (restart on ECONNREFUSED) is preserved because
+     * the ocrmac path still uses the Docling server.
+     */
+    private parseWithStrategy;
     /**
      * Dispose the parser instance.
      * - Sets the internal client to null
@@ -140,4 +168,112 @@ declare class ImagePdfFallbackError extends Error {
     constructor(originalError: Error, fallbackError: Error);
 }
 
-export { type ConversionCompleteCallback, ImagePdfFallbackError, type PDFConvertOptions, PDFParser, type PipelineType };
+/**
+ * Intermediate format produced by VLM page-by-page processing.
+ * Intentionally kept simple so VLM prompts stay short and accurate.
+ * The DoclingDocumentAssembler converts these into a full DoclingDocument.
+ */
+/** Allowed element types matching DoclingDocument text labels */
+type VlmElementType = 'text' | 'section_header' | 'caption' | 'footnote' | 'page_header' | 'page_footer' | 'list_item' | 'picture' | 'table';
+/**
+ * Normalized bounding box with coordinates in the range 0.0 to 1.0,
+ * using top-left origin (standard image coordinates).
+ */
+interface VlmBBox {
+    /** Left edge (0.0 = left boundary) */
+    l: number;
+    /** Top edge (0.0 = top boundary) */
+    t: number;
+    /** Right edge (1.0 = right boundary) */
+    r: number;
+    /** Bottom edge (1.0 = bottom boundary) */
+    b: number;
+}
+/** A single content element detected on a page by VLM */
+interface VlmPageElement {
+    /** Element type */
+    type: VlmElementType;
+    /** Text content (empty string for picture elements) */
+    content: string;
+    /** Heading depth for section_header (1 = top-level) */
+    level?: number;
+    /** List marker for list_item (e.g., "1)", "a.", "\u2022") */
+    marker?: string;
+    /** Reading order within the page (top-to-bottom, left-to-right) */
+    order: number;
+    /**
+     * Bounding box in normalized coordinates (0.0-1.0, top-left origin).
+     * - Text elements: optional (included in prov if present)
+     * - Picture elements: **required** (used for image cropping)
+     */
+    bbox?: VlmBBox;
+}
+/** Types of quality issues detected in VLM responses */
+type VlmQualityIssueType = 'placeholder_text' | 'script_anomaly' | 'meta_description' | 'repetitive_pattern';
+/** Quality metadata for a processed page */
+interface VlmPageQuality {
+    /** Whether the page passed quality validation (after possible retry) */
+    isValid: boolean;
+    /** Whether a quality retry was performed for this page */
+    retried: boolean;
+    /** Issue types detected (may persist even after retry) */
+    issueTypes: VlmQualityIssueType[];
+}
+
+/** A single quality issue found during validation */
+interface VlmQualityIssue {
+    /** Type of issue detected */
+    type: VlmQualityIssueType;
+    /** Human-readable description of the issue */
+    message: string;
+    /** Element reading-order indices that triggered the issue */
+    affectedElements: number[];
+}
+/** Result of VLM response quality validation */
+interface VlmValidationResult {
+    /** Whether the response passes quality validation */
+    isValid: boolean;
+    /** List of quality issues found (empty if valid) */
+    issues: VlmQualityIssue[];
+}
+/**
+ * Lightweight, stateless validator for VLM page extraction responses.
+ *
+ * Detects four categories of hallucination without any additional VLM calls:
+ * 1. Placeholder text (Lorem ipsum and variants)
+ * 2. Script anomaly (expected Korean but got Latin-only text)
+ * 3. Meta description (VLM described the image instead of transcribing text)
+ * 4. Repetitive pattern (repeated character patterns like `: : : : :`)
+ */
+declare class VlmResponseValidator {
+    /**
+     * Validate VLM page result quality.
+     *
+     * @param elements - Extracted page elements to validate
+     * @param documentLanguages - BCP 47 language tags (e.g., ['ko-KR', 'en-US'])
+     * @returns Validation result with issues list
+     */
+    static validate(elements: VlmPageElement[], documentLanguages?: string[]): VlmValidationResult;
+    /**
+     * Detect known placeholder / filler text in elements.
+     */
+    private static detectPlaceholderText;
+    /**
+     * Detect script anomaly: expected Korean content but found mostly Latin text.
+     * Counts Hangul + CJK characters and flags if the ratio is below threshold.
+     */
+    private static detectScriptAnomaly;
+    /**
+     * Detect meta description: VLM described the image/resolution instead
+     * of transcribing actual text content.
+     */
+    private static detectMetaDescription;
+    /**
+     * Detect repetitive character patterns (e.g., `: : : : :` or `= = = = =`).
+     * Flags when the same character repeats with spaces 5+ times and the
+     * repetitive portion exceeds 30% of total content.
+     */
+    private static detectRepetitivePattern;
+}
+
+export { type ConversionCompleteCallback, type ConvertWithStrategyResult, ImagePdfFallbackError, type PDFConvertOptions, PDFParser, type VlmPageQuality, type VlmQualityIssue, type VlmQualityIssueType, VlmResponseValidator, type VlmValidationResult };

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import { LoggerMethods } from '@heripo/logger';
-import { ConversionOptions, VlmModelLocal } from 'docling-sdk';
-export { DEFAULT_VLM_MODEL, VLM_MODELS, VlmModelPreset, resolveVlmModel } from './vlm-models.js';
+import { OcrStrategy, TokenUsageReport } from '@heripo/model';
+import { LanguageModel } from 'ai';
+import { ConversionOptions } from 'docling-sdk';
+import { LLMTokenUsageAggregator } from '@heripo/shared';
 
 /**
  * Callback function invoked after PDF conversion completes
@@ -8,19 +10,37 @@ export { DEFAULT_VLM_MODEL, VLM_MODELS, VlmModelPreset, resolveVlmModel } from '
  */
 type ConversionCompleteCallback = (outputPath: string) => Promise<void> | void;
 /**
- * Pipeline type for PDF conversion
- * - 'standard': Use OCR-based pipeline (default, uses ocrmac)
- * - 'vlm': Use Vision Language Model pipeline for better KCJ/complex layout handling
+ * Extended options for PDF conversion.
  */
-type PipelineType = 'standard' | 'vlm';
-/**
- * Extended options for PDF conversion including pipeline selection
- */
-type PDFConvertOptions = Omit<ConversionOptions, 'to_formats' | 'image_export_mode' | 'ocr_engine' | 'accelerator_options' | 'ocr_options' | 'generate_picture_images' | 'images_scale' | 'force_ocr' | 'pipeline' | 'vlm_pipeline_model_local'> & {
+type PDFConvertOptions = Omit<ConversionOptions, 'to_formats' | 'image_export_mode' | 'ocr_engine' | 'accelerator_options' | 'ocr_options' | 'generate_picture_images' | 'images_scale' | 'force_ocr' | 'pipeline' | 'vlm_pipeline_model_local' | 'vlm_pipeline_model_api'> & {
     num_threads?: number;
-    pipeline?: PipelineType;
-    vlm_model?: string | VlmModelLocal;
+    /**
+     * Force pre-conversion to image-based PDF before processing.
+     * Requires ImageMagick and Ghostscript.
+     */
+    forceImagePdf?: boolean;
+    /** Vision model for OCR strategy sampling (enables new strategy-based flow) */
+    strategySamplerModel?: LanguageModel;
+    /** Vision model for VLM page processing (required when strategy selects VLM) */
+    vlmProcessorModel?: LanguageModel;
+    /** Concurrency for VLM page processing (default: 1) */
+    vlmConcurrency?: number;
+    /** Skip sampling and default to ocrmac */
+    skipSampling?: boolean;
+    /** Force a specific OCR method, bypassing sampling */
+    forcedMethod?: 'ocrmac' | 'vlm';
+    /** Token usage aggregator for tracking across sampling and VLM processing */
+    aggregator?: LLMTokenUsageAggregator;
+    /** Callback fired after each batch of VLM pages completes, with cumulative token usage */
+    onTokenUsage?: (report: TokenUsageReport) => void;
 };
+/** Result of strategy-based conversion */
+interface ConvertWithStrategyResult {
+    /** The OCR strategy that was determined */
+    strategy: OcrStrategy;
+    /** Token usage report from sampling and/or VLM processing (null when no LLM usage occurs) */
+    tokenUsageReport: TokenUsageReport | null;
+}
 
 type Options = {
     logger: LoggerMethods;
@@ -120,7 +140,15 @@ declare class PDFParser {
      */
     private restartServer;
     private waitForServerReady;
-    parse(url: string, reportId: string, onComplete: ConversionCompleteCallback, cleanupAfterCallback: boolean, options: PDFConvertOptions, abortSignal?: AbortSignal): Promise<void>;
+    parse(url: string, reportId: string, onComplete: ConversionCompleteCallback, cleanupAfterCallback: boolean, options: PDFConvertOptions, abortSignal?: AbortSignal): Promise<TokenUsageReport | null>;
+    /**
+     * Parse a PDF using OCR strategy sampling to decide between ocrmac and VLM.
+     * Delegates to PDFConverter.convertWithStrategy() and returns the token usage report.
+     *
+     * Server recovery (restart on ECONNREFUSED) is preserved because
+     * the ocrmac path still uses the Docling server.
+     */
+    private parseWithStrategy;
     /**
      * Dispose the parser instance.
      * - Sets the internal client to null
@@ -140,4 +168,112 @@ declare class ImagePdfFallbackError extends Error {
     constructor(originalError: Error, fallbackError: Error);
 }
 
-export { type ConversionCompleteCallback, ImagePdfFallbackError, type PDFConvertOptions, PDFParser, type PipelineType };
+/**
+ * Intermediate format produced by VLM page-by-page processing.
+ * Intentionally kept simple so VLM prompts stay short and accurate.
+ * The DoclingDocumentAssembler converts these into a full DoclingDocument.
+ */
+/** Allowed element types matching DoclingDocument text labels */
+type VlmElementType = 'text' | 'section_header' | 'caption' | 'footnote' | 'page_header' | 'page_footer' | 'list_item' | 'picture' | 'table';
+/**
+ * Normalized bounding box with coordinates in the range 0.0 to 1.0,
+ * using top-left origin (standard image coordinates).
+ */
+interface VlmBBox {
+    /** Left edge (0.0 = left boundary) */
+    l: number;
+    /** Top edge (0.0 = top boundary) */
+    t: number;
+    /** Right edge (1.0 = right boundary) */
+    r: number;
+    /** Bottom edge (1.0 = bottom boundary) */
+    b: number;
+}
+/** A single content element detected on a page by VLM */
+interface VlmPageElement {
+    /** Element type */
+    type: VlmElementType;
+    /** Text content (empty string for picture elements) */
+    content: string;
+    /** Heading depth for section_header (1 = top-level) */
+    level?: number;
+    /** List marker for list_item (e.g., "1)", "a.", "\u2022") */
+    marker?: string;
+    /** Reading order within the page (top-to-bottom, left-to-right) */
+    order: number;
+    /**
+     * Bounding box in normalized coordinates (0.0-1.0, top-left origin).
+     * - Text elements: optional (included in prov if present)
+     * - Picture elements: **required** (used for image cropping)
+     */
+    bbox?: VlmBBox;
+}
+/** Types of quality issues detected in VLM responses */
+type VlmQualityIssueType = 'placeholder_text' | 'script_anomaly' | 'meta_description' | 'repetitive_pattern';
+/** Quality metadata for a processed page */
+interface VlmPageQuality {
+    /** Whether the page passed quality validation (after possible retry) */
+    isValid: boolean;
+    /** Whether a quality retry was performed for this page */
+    retried: boolean;
+    /** Issue types detected (may persist even after retry) */
+    issueTypes: VlmQualityIssueType[];
+}
+
+/** A single quality issue found during validation */
+interface VlmQualityIssue {
+    /** Type of issue detected */
+    type: VlmQualityIssueType;
+    /** Human-readable description of the issue */
+    message: string;
+    /** Element reading-order indices that triggered the issue */
+    affectedElements: number[];
+}
+/** Result of VLM response quality validation */
+interface VlmValidationResult {
+    /** Whether the response passes quality validation */
+    isValid: boolean;
+    /** List of quality issues found (empty if valid) */
+    issues: VlmQualityIssue[];
+}
+/**
+ * Lightweight, stateless validator for VLM page extraction responses.
+ *
+ * Detects four categories of hallucination without any additional VLM calls:
+ * 1. Placeholder text (Lorem ipsum and variants)
+ * 2. Script anomaly (expected Korean but got Latin-only text)
+ * 3. Meta description (VLM described the image instead of transcribing text)
+ * 4. Repetitive pattern (repeated character patterns like `: : : : :`)
+ */
+declare class VlmResponseValidator {
+    /**
+     * Validate VLM page result quality.
+     *
+     * @param elements - Extracted page elements to validate
+     * @param documentLanguages - BCP 47 language tags (e.g., ['ko-KR', 'en-US'])
+     * @returns Validation result with issues list
+     */
+    static validate(elements: VlmPageElement[], documentLanguages?: string[]): VlmValidationResult;
+    /**
+     * Detect known placeholder / filler text in elements.
+     */
+    private static detectPlaceholderText;
+    /**
+     * Detect script anomaly: expected Korean content but found mostly Latin text.
+     * Counts Hangul + CJK characters and flags if the ratio is below threshold.
+     */
+    private static detectScriptAnomaly;
+    /**
+     * Detect meta description: VLM described the image/resolution instead
+     * of transcribing actual text content.
+     */
+    private static detectMetaDescription;
+    /**
+     * Detect repetitive character patterns (e.g., `: : : : :` or `= = = = =`).
+     * Flags when the same character repeats with spaces 5+ times and the
+     * repetitive portion exceeds 30% of total content.
+     */
+    private static detectRepetitivePattern;
+}
+
+export { type ConversionCompleteCallback, type ConvertWithStrategyResult, ImagePdfFallbackError, type PDFConvertOptions, PDFParser, type VlmPageQuality, type VlmQualityIssue, type VlmQualityIssueType, VlmResponseValidator, type VlmValidationResult };