@heripo/document-processor 0.1.39 → 0.1.41

package/dist/index.d.cts

@@ -1,1702 +0,0 @@
-import { LoggerMethods } from '@heripo/logger';
-import { TokenUsageReport, DoclingDocument, PageRange, ProcessedDocumentSource, DocumentProcessResult, Caption, DoclingTextItem, DoclingPictureItem, DoclingTableItem, DoclingGroupItem, ProcessedImage, ProcessedTable, ProcessedFootnote, Chapter, DoclingReference } from '@heripo/model';
-import { LanguageModel } from 'ai';
-import { LLMTokenUsageAggregator, ExtendedTokenUsage } from '@heripo/shared';
-import { z } from 'zod';
-
-/**
- * Table of Contents Entry
- *
- * Tree node representing the table of contents structure of a document.
- */
-interface TocEntry {
-    /**
-     * Chapter title
-     */
-    title: string;
-    /**
-     * Hierarchy depth (1, 2, 3...)
-     */
-    level: number;
-    /**
-     * Starting page number
-     */
-    pageNo: number;
-    /**
-     * Docling references for source nodes used to derive this TOC entry
-     */
-    sourceRefs?: string[];
-    /**
-     * Child TOC entries
-     */
-    children?: TocEntry[];
-}
-/**
- * TOC Area Search Result
- */
-interface TocAreaResult {
-    /**
-     * Group or table item references corresponding to the table of contents
-     */
-    itemRefs: string[];
-    /**
-     * TOC start page
-     */
-    startPage: number;
-    /**
-     * TOC end page
-     */
-    endPage: number;
-}
-/**
- * Page Size Information
- */
-interface PageSizeGroup {
-    /**
-     * Size identifier (width x height)
-     */
-    sizeKey: string;
-    /**
-     * PDF page numbers with this size specification
-     */
-    pageNos: number[];
-}
-
-declare const PROCESSED_DOCUMENT_SCHEMA_VERSION = "processed-document.v2";
-type SourceRefValidationMode = 'off' | 'warn' | 'error';
-/**
- * DocumentProcessor Options
- */
-interface DocumentProcessorOptions {
-    /**
-     * Logger instance
-     */
-    logger: LoggerMethods;
-    /**
-     * Fallback model - used as fallback when component-specific models are not provided or fail.
-     * This is the only required model. Should be set to a frontier model (e.g., Claude Opus 4.6, GPT-5.2)
-     * to ensure reliable fallback performance across all components.
-     */
-    fallbackModel: LanguageModel;
-    /**
-     * Model for PageRangeParser - extracts page numbers from page images.
-     * Requires vision capabilities. Falls back to 'fallbackModel' if not provided.
-     */
-    pageRangeParserModel?: LanguageModel;
-    /**
-     * Model for TocExtractor - extracts structured TOC from Markdown representation.
-     * Falls back to 'fallbackModel' if not provided.
-     */
-    tocExtractorModel?: LanguageModel;
-    /**
-     * Model for validators (TOC content validation, caption validation).
-     * Falls back to 'fallbackModel' if not provided.
-     */
-    validatorModel?: LanguageModel;
-    /**
-     * Model for VisionTocExtractor - extracts TOC directly from page images.
-     * Requires vision capabilities. Falls back to 'fallbackModel' if not provided.
-     */
-    visionTocExtractorModel?: LanguageModel;
-    /**
-     * Model for CaptionParser - extracts caption prefix and number from image/table captions.
-     * Falls back to 'fallbackModel' if not provided.
-     */
-    captionParserModel?: LanguageModel;
-    /**
-     * Batch size for TextCleaner text normalization (synchronous processing)
-     */
-    textCleanerBatchSize: number;
-    /**
-     * Batch size for CaptionParser LLM parsing (async parallel processing)
-     */
-    captionParserBatchSize: number;
-    /**
-     * Batch size for CaptionValidator LLM validation (async parallel processing)
-     */
-    captionValidatorBatchSize: number;
-    /**
-     * Maximum retry count (default: 3)
-     */
-    maxRetries?: number;
-    /**
-     * Maximum retry count for TOC validation correction feedback (default: 3)
-     */
-    maxValidationRetries?: number;
-    /**
-     * Enable fallback retry mechanism - automatically retries with fallback model on failure (default: false)
-     * Set to true to enable automatic fallback retry with fallback model on component-specific model errors
-     */
-    enableFallbackRetry?: boolean;
-    /**
-     * Abort signal for cancellation support.
-     * When aborted, processing stops at the next checkpoint between stages.
-     */
-    abortSignal?: AbortSignal;
-    /**
-     * Callback fired after each major processing phase completes.
-     * Receives the current cumulative token usage report.
-     * Useful for real-time token usage monitoring during processing.
-     */
-    onTokenUsage?: (report: TokenUsageReport) => void;
-}
-/**
- * Per-document processing inputs.
- */
-interface DocumentProcessorProcessOptions {
-    /**
-     * Precomputed PDF page number to actual document page range mapping.
-     * When provided, automatic PageRangeParser execution is skipped.
-     */
-    pageRangeMap?: Record<number, PageRange>;
-    /**
-     * Precomputed table of contents entries.
-     * When provided, automatic TOC extraction pipeline execution is skipped.
-     */
-    tocEntries?: TocEntry[];
-    /**
-     * Caller-supplied source artifact metadata for the Docling input.
-     */
-    source?: ProcessedDocumentSource;
-    /**
-     * Validate generated source references against the input Docling document.
-     *
-     * When true, missing references are treated as errors unless
-     * `sourceRefValidationMode` is provided.
-     *
-     * @experimental
-     */
-    validateSourceRefs?: boolean;
-    /**
-     * Controls how missing generated source references are handled.
-     *
-     * Explicit mode takes precedence over `validateSourceRefs`. Use `warn` for
-     * rollout visibility without failing processing, and `error` for strict
-     * provenance checks.
-     *
-     * @default 'off'
-     * @experimental
-     */
-    sourceRefValidationMode?: SourceRefValidationMode;
-}
-/**
- * DocumentProcessor
- *
- * Main class that converts DoclingDocument to ProcessedDocument.
- *
- * ## Conversion Process
- *
- * 1. Initialize RefResolver - indexing for $ref resolution
- * 2. Initialize IdGenerator - unique ID generator
- * 3. Text filtering and PageRangeMap generation (visionModel)
- * 4. TOC extraction (model) - core step
- * 5. Parallel processing block:
- *    - Images conversion (caption extraction)
- *    - Tables conversion (excluding TOC tables)
- * 6. Chapters conversion (based on TOC)
- * 7. Assemble ProcessedDocument
- *
- * @example
- * ```typescript
- * import { openai } from '@ai-sdk/openai';
- * import { anthropic } from '@ai-sdk/anthropic';
- * import { DocumentProcessor } from '@heripo/document-processor';
- * import { getLogger } from '@heripo/logger';
- *
- * const logger = getLogger();
- *
- * // Basic usage - all components use the fallback model
- * const processor = new DocumentProcessor({
- *   logger,
- *   fallbackModel: anthropic('claude-opus-4-5-20251101'), // Frontier model for reliable fallback
- * });
- *
- * // Advanced usage - component-specific models with frontier fallback
- * const advancedProcessor = new DocumentProcessor({
- *   logger,
- *   fallbackModel: anthropic('claude-opus-4-5-20251101'), // Frontier model for fallback
- *   pageRangeParserModel: openai('gpt-5.2'), // Vision-capable
- *   tocExtractorModel: openai('gpt-5-mini'), // Structured output
- *   validatorModel: openai('gpt-5.2'), // Validation (TOC + caption)
- *   visionTocExtractorModel: openai('gpt-5.1'), // Vision-capable
- *   captionParserModel: openai('gpt-5-mini'),
- *   textCleanerBatchSize: 20,      // Sync text processing
- *   captionParserBatchSize: 10,    // LLM caption parsing
- *   captionValidatorBatchSize: 10, // LLM caption validation
- *   maxRetries: 3,
- *   maxValidationRetries: 3,
- * });
- *
- * const result = await processor.process(
- *   doclingDoc,
- *   'report-001',
- *   artifactDir
- * );
- * ```
- */
-declare class DocumentProcessor {
-    private readonly logger;
-    private readonly fallbackModel;
-    private readonly pageRangeParserModel;
-    private readonly tocExtractorModel;
-    private readonly validatorModel;
-    private readonly visionTocExtractorModel;
-    private readonly captionParserModel;
-    private readonly textCleanerBatchSize;
-    private readonly captionParserBatchSize;
-    private readonly captionValidatorBatchSize;
-    private readonly maxRetries;
-    private readonly maxValidationRetries;
-    private readonly enableFallbackRetry;
-    private readonly abortSignal?;
-    private readonly onTokenUsage?;
-    private idGenerator;
-    private refResolver?;
-    private pageRangeParser?;
-    private tocFinder?;
-    private tocExtractor?;
-    private tocContentValidator?;
-    private captionValidator?;
-    private visionTocExtractor?;
-    private captionParser?;
-    private chapterConverter?;
-    private resourceConverter?;
-    private tocExtractionPipeline?;
-    private captionProcessingPipeline?;
-    private readonly usageAggregator;
-    constructor(options: DocumentProcessorOptions);
-    /**
-     * Emit current token usage report via callback
-     *
-     * Calls the onTokenUsage callback with the current cumulative report
-     * from the usage aggregator. Safe to call even if no callback is set.
-     */
-    private emitTokenUsage;
-    /**
-     * Check if abort has been requested and throw error if so
-     *
-     * @throws {Error} with name 'AbortError' if aborted
-     */
-    private checkAborted;
-    /**
-     * Converts DoclingDocument to ProcessedDocument with token usage tracking.
-     *
-     * Conversion process:
-     * 1. Initialize processors and resolvers
-     * 2. Normalize and filter texts
-     * 3. Clean texts and resolve page ranges
-     * 4. Extract table of contents
-     * 5. Convert images and tables (parallel)
-     * 6. Convert chapters and link resources
-     * 7. Assemble final ProcessedDocument
-     * 8. Collect and report token usage
-     *
-     * @param doclingDoc - Original document extracted from Docling SDK
-     * @param reportId - Report unique identifier
-     * @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
-     */
-    process(doclingDoc: DoclingDocument, reportId: string, artifactDir: string, processOptions?: DocumentProcessorProcessOptions): Promise<DocumentProcessResult>;
-    /**
-     * Initialize all processors and resolvers
-     *
-     * Sets up RefResolver, PageRangeParser, TocFinder, and TocExtractor
-     */
-    private initializeProcessors;
-    /**
-     * Normalize and filter texts using TextCleaner
-     *
-     * Performs basic text normalization (unicode, whitespace, punctuation)
-     * and filters out invalid texts (empty, numbers-only, etc.)
-     */
-    private normalizeAndFilterTexts;
-    /**
-     * Parse page ranges using Vision LLM
-     *
-     * Extracts actual page numbers from page images and creates mapping.
-     * Token usage is automatically tracked by PageRangeParser into the shared aggregator.
-     */
-    private parsePageRanges;
-    private resolveSourceRefValidationMode;
-    private validateProcessedDocumentSourceRefs;
-    private collectMissingSourceRefs;
-    /**
-     * Assemble the final ProcessedDocument
-     *
-     * Creates the ProcessedDocument structure with all converted components
-     */
-    private assembleProcessedDocument;
-    /**
-     * Convert chapters and link resources
-     *
-     * Generates chapters based on TOC and links images/tables/footnotes using ChapterConverter.
-     * Throws TocNotFoundError if TOC entries are empty (defensive assertion).
-     */
-    private convertChapters;
-}
-
-/**
- * Base options for all LLM-based components
- */
-interface BaseLLMComponentOptions {
-    /**
-     * Maximum retry count for LLM API (default: 3)
-     */
-    maxRetries?: number;
-    /**
-     * Temperature for LLM generation (default: 0)
-     */
-    temperature?: number;
-    /**
-     * Abort signal for cancellation support
-     */
-    abortSignal?: AbortSignal;
-}
-/**
- * Abstract base class for all LLM-based components
- *
- * Provides common functionality:
- * - Consistent logging with component name prefix
- * - Token usage tracking via optional aggregator
- * - Standard configuration (model, fallback, retries, temperature)
- *
- * Subclasses must implement buildSystemPrompt() and buildUserPrompt().
- */
-declare abstract class BaseLLMComponent {
-    protected readonly logger: LoggerMethods;
-    protected readonly model: LanguageModel;
-    protected readonly fallbackModel?: LanguageModel;
-    protected readonly maxRetries: number;
-    protected readonly temperature: number;
-    protected readonly componentName: string;
-    protected readonly aggregator?: LLMTokenUsageAggregator;
-    protected readonly abortSignal?: AbortSignal;
-    /**
-     * Constructor for BaseLLMComponent
-     *
-     * @param logger - Logger instance for logging
-     * @param model - Primary language model for LLM calls
-     * @param componentName - Name of the component for logging (e.g., "TocExtractor")
-     * @param options - Optional configuration (maxRetries, temperature)
-     * @param fallbackModel - Optional fallback model for retry on failure
-     * @param aggregator - Optional token usage aggregator for tracking LLM calls
-     */
-    constructor(logger: LoggerMethods, model: LanguageModel, componentName: string, options?: BaseLLMComponentOptions, fallbackModel?: LanguageModel, aggregator?: LLMTokenUsageAggregator);
-    /**
-     * Log a message with consistent component name prefix
-     *
-     * @param level - Log level ('info', 'warn', 'error')
-     * @param message - Message to log (without prefix)
-     * @param args - Additional arguments to pass to logger
-     */
-    protected log(level: 'info' | 'warn' | 'error', message: string, ...args: unknown[]): void;
-    /**
-     * Track token usage to aggregator if available
-     *
-     * @param usage - Token usage information to track
-     */
-    protected trackUsage(usage: ExtendedTokenUsage): void;
-    /**
-     * Create an empty usage record for edge cases (e.g., empty input)
-     *
-     * @param phase - Phase name for the usage record
-     * @returns Empty ExtendedTokenUsage object
-     */
-    protected createEmptyUsage(phase: string): ExtendedTokenUsage;
-    /**
-     * Build system prompt for LLM call
-     *
-     * Subclasses must implement this to provide component-specific system prompts.
-     */
-    protected abstract buildSystemPrompt(...args: unknown[]): string;
-    /**
-     * Build user prompt for LLM call
-     *
-     * Subclasses must implement this to construct prompts from input data.
-     */
-    protected abstract buildUserPrompt(...args: unknown[]): string;
-}
-
-/**
- * Abstract base class for text-based LLM components
- *
- * Extends BaseLLMComponent with helper method for text-based LLM calls
- * using LLMCaller.call() (non-vision).
- *
- * Subclasses: TocExtractor, CaptionParser, BaseValidator
- */
-declare abstract class TextLLMComponent extends BaseLLMComponent {
-    constructor(logger: LoggerMethods, model: LanguageModel, componentName: string, options?: BaseLLMComponentOptions, fallbackModel?: LanguageModel, aggregator?: LLMTokenUsageAggregator);
-    /**
-     * Call LLM with text-based prompts using LLMCaller.call()
-     *
-     * @template TSchema - Zod schema type for response validation
-     * @param schema - Zod schema for response validation
-     * @param systemPrompt - System prompt for LLM
-     * @param userPrompt - User prompt for LLM
-     * @param phase - Phase name for tracking (e.g., 'extraction', 'validation')
-     * @returns Promise with parsed object and usage information
-     */
-    protected callTextLLM<TSchema extends z.ZodType>(schema: TSchema, systemPrompt: string, userPrompt: string, phase: string): Promise<{
-        output: z.infer<TSchema>;
-        usage: ExtendedTokenUsage;
-    }>;
-}
-
-/**
- * Options for VisionLLMComponent
- */
-interface VisionLLMComponentOptions extends BaseLLMComponentOptions {
-}
-/**
- * Image content structure for vision LLM messages
- */
-interface ImageContent {
-    type: 'image';
-    image: Uint8Array;
-    mediaType: string;
-}
-/**
- * Abstract base class for vision-based LLM components
- *
- * Extends BaseLLMComponent with helper methods for vision-based LLM calls
- * using LLMCaller.callVision().
- *
- * Subclasses: PageRangeParser, VisionTocExtractor
- */
-declare abstract class VisionLLMComponent extends BaseLLMComponent {
-    protected readonly artifactDir: string;
-    constructor(logger: LoggerMethods, model: LanguageModel, componentName: string, artifactDir: string, options?: VisionLLMComponentOptions, fallbackModel?: LanguageModel, aggregator?: LLMTokenUsageAggregator);
-    /**
-     * Call LLM with vision capabilities using LLMCaller.callVision()
-     *
-     * @template TSchema - Zod schema type for response validation
-     * @param schema - Zod schema for response validation
-     * @param messages - Messages array including image content
-     * @param phase - Phase name for tracking (e.g., 'extraction', 'sampling')
-     * @returns Promise with parsed object and usage information
-     */
-    protected callVisionLLM<TSchema extends z.ZodType>(schema: TSchema, messages: Array<{
-        role: 'user' | 'assistant';
-        content: unknown[] | string;
-    }>, phase: string): Promise<{
-        output: z.infer<TSchema>;
-        usage: ExtendedTokenUsage;
-    }>;
-    /**
-     * Build image content object for vision LLM messages
-     *
-     * @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
-     */
-    protected buildImageContent(imagePath: string, mimeType?: string): ImageContent;
-}
-
-/**
- * CaptionParser options
- */
-interface CaptionParserOptions extends BaseLLMComponentOptions {
-    /**
-     * Custom component name for token usage tracking.
-     * Defaults to 'CaptionParser'.
-     */
-    componentName?: string;
-}
-/**
- * CaptionParser
- *
- * Extracts caption prefix and number from image/table captions using LLM.
- * Preserves original spacing from input text.
- * Extends TextLLMComponent for standardized LLM call handling.
- *
- * ## Algorithm
- *
- * 1. Collect caption texts
- * 2. Split into batches based on batchSize
- * 3. For each batch: call LLM to extract caption prefix + number
- * 4. Flatten results and return
- */
-declare class CaptionParser extends TextLLMComponent {
-    constructor(logger: LoggerMethods, model: LanguageModel, options?: CaptionParserOptions, fallbackModel?: LanguageModel, aggregator?: LLMTokenUsageAggregator);
-    /**
-     * Parse batch of captions
-     *
-     * @param captions - Array of caption full texts
-     * @param batchSize - Batch size for processing. Set to 0 for sequential processing without batching.
-     * @param overrideModel - Optional model to use instead of the default model
-     * @returns Array of Caption objects with num extracted (maintains original order)
-     */
-    parseBatch(captions: string[], batchSize: number, overrideModel?: LanguageModel): Promise<Caption[]>;
-    /**
-     * Internal: Parse batch of captions using LLM
-     *
-     * @param captions - Batch of caption texts with original indices
-     * @param model - Effective model to use
-     * @returns Array of Caption objects indexed correctly
-     */
-    private parseBatchInternal;
-    /**
-     * Extract and normalize caption number from full text
-     *
-     * Finds the extracted num pattern in the full text and extracts it
-     * with original casing. Handles case-insensitive matching.
-     *
-     * @param fullText - The full caption text
-     * @param extractedNum - The num extracted by LLM (may have different casing)
-     * @returns Normalized num or undefined if no match
-     */
-    private extractNumFromFullText;
-    /**
-     * Build system prompt for caption parsing
-     *
-     * @param mode - 'batch' for multiple captions, 'single' for single caption
-     */
-    protected buildSystemPrompt(mode?: 'batch' | 'single'): string;
-    /**
-     * Build user prompt for caption parsing
-     */
-    protected buildUserPrompt(captions: Array<{
-        index: number;
-        text: string;
-    }>): string;
-    /**
-     * Build user prompt for single caption parsing
-     */
-    private buildUserPromptSingle;
-}
-/**
- * Error thrown when caption parsing fails
- */
-declare class CaptionParseError extends Error {
-    constructor(message: string, options?: ErrorOptions);
-}
-
-/**
- * PageRangeParseError
- *
- * Custom error thrown when page range parsing fails.
- */
-declare class PageRangeParseError extends Error {
-    constructor(message: string, options?: ErrorOptions);
-    /**
-     * Extract error message from unknown error type
-     */
-    static getErrorMessage(error: unknown): string;
-    /**
-     * Create PageRangeParseError from unknown error with context
-     */
-    static fromError(context: string, error: unknown): PageRangeParseError;
-}
-
-/**
- * Pattern types for page number sequences
- */
-declare enum PagePattern {
-    /** Simple increment: [1, 2, 3, 4, ...] */
-    SIMPLE_INCREMENT = "simple_increment",
-    /** Double-sided scan: [1-2, 3-4, 5-6, ...] */
-    DOUBLE_SIDED = "double_sided",
-    /** Offset pattern: PDF page != actual page (consistent offset) */
-    OFFSET = "offset",
-    /** No clear pattern detected */
-    UNKNOWN = "unknown"
-}
-/**
- * PageRangeParser
- *
- * Extracts actual document page numbers from PDF page images using Vision LLM.
- * Uses random sampling + pattern detection to minimize LLM calls.
- * Extends VisionLLMComponent for standardized vision LLM call handling.
- *
- * ## Algorithm
- *
- * 1. Group pages by size (consecutive pages with same dimensions)
- * 2. For each group:
- *    - If ≤3 pages: send all to LLM at once
- *    - If >3 pages: random sample 3 pages, detect pattern, apply to all
- * 3. Post-process: handle drops, normalize negatives, backfill failed pages
- */
-declare class PageRangeParser extends VisionLLMComponent {
-    private readonly SAMPLE_SIZE;
-    private readonly MAX_PATTERN_RETRIES;
-    private readonly SIZE_TOLERANCE;
-    constructor(logger: LoggerMethods, model: LanguageModel, artifactDir: string, maxRetries?: number, fallbackModel?: LanguageModel, aggregator?: LLMTokenUsageAggregator, abortSignal?: AbortSignal);
-    /**
-     * Main parse method
-     *
-     * Extracts page range mapping from DoclingDocument using Vision LLM.
-     * Automatically tracks token usage in the aggregator if one was provided.
-     *
-     * @param doclingDoc - DoclingDocument to extract page ranges from
-     * @returns Object with page range mapping and token usage information
-     */
-    parse(doclingDoc: DoclingDocument): Promise<{
-        pageRangeMap: Record<number, PageRange>;
-        usage: ExtendedTokenUsage[];
-    }>;
-    /**
-     * Extract pages array from DoclingDocument
-     */
-    private extractPages;
-    /**
-     * Analyze page sizes and group consecutive pages with same dimensions
-     */
-    private analyzeSizes;
-    /**
-     * Create size key with tolerance for floating point comparison
-     */
-    private createSizeKey;
-    /**
-     * Process a single size group
-     */
-    private processGroup;
-    /**
-     * Select random samples from page numbers
-     */
-    private selectRandomSamples;
-    /**
-     * Extract page numbers from multiple pages in a single LLM call
-     */
-    private extractMultiplePages;
-    /**
-     * Detect pattern from sample results
-     */
-    private detectPattern;
-    /**
-     * Apply detected pattern to generate page range map
-     */
-    private applyPattern;
-    /**
-     * Convert sample results to page range map (for small groups)
-     */
-    private samplesToMap;
-    /**
-     * Post-process the page range map
-     */
-    private postProcess;
-    /**
-     * Detect and handle outlier page numbers at the beginning of document
-     *
-     * When early PDF pages have abnormally high page numbers compared to
-     * subsequent pages (e.g., PDF 1-9 = 75-83, but PDF 10+ = 2,3,4...),
-     * the LLM likely misread figure/photo numbers as page numbers.
-     *
-     * Detection: If page numbers at the beginning are significantly higher
-     * than subsequent pages (which follow a normal pattern), mark them as failed.
-     */
-    private detectAndHandleOutliers;
-    /**
-     * Find the start index of a "normal" sequence in the page range map
-     *
-     * A normal sequence is defined as at least 3 consecutive PDF pages where:
-     * - Page numbers are increasing (for single-page) or increasing by 2 (for double-sided)
-     * - The pattern is consistent
-     *
-     * Returns the index in pdfPages array, or null if not found.
-     */
-    private findNormalSequenceStart;
-    /**
-     * Check if a page range represents a double-sided scan
-     */
-    private isDoubleSidedRange;
-    /**
-     * Detect and handle page number drops
-     *
-     * When page numbers suddenly decrease (e.g., 8,9 -> 3,4),
-     * recalculate previous pages based on the drop point.
-     */
-    private detectAndHandleDrops;
-    /**
-     * Normalize negative page numbers to 0
-     */
-    private normalizeNegatives;
-    /**
-     * Backfill pages marked with 0 using detected pattern
-     */
-    private backfillFailedPages;
-    /**
-     * Build system prompt for Vision LLM
-     */
-    protected buildSystemPrompt(): string;
-    /**
-     * Build user prompt for Vision LLM
-     */
-    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
- *
- * Base error class for TOC extraction failures.
- */
-declare class TocExtractError extends Error {
-    constructor(message: string, options?: ErrorOptions);
-    /**
-     * Extract error message from unknown error type
-     */
-    static getErrorMessage(error: unknown): string;
-    /**
-     * Create TocExtractError from unknown error with context
-     */
-    static fromError(context: string, error: unknown): TocExtractError;
-}
-/**
- * TocNotFoundError
- *
- * Error thrown when TOC area cannot be found in the document.
- */
-declare class TocNotFoundError extends TocExtractError {
-    constructor(message?: string);
-}
-/**
- * TocParseError
- *
- * Error thrown when LLM fails to parse TOC structure.
- */
-declare class TocParseError extends TocExtractError {
-    constructor(message: string, options?: ErrorOptions);
-}
-
-/**
- * Validation options for TocValidator
- */
-interface TocValidationOptions {
-    /**
-     * Total page count of the document (for range validation)
-     * If not provided, page range upper bound validation is skipped
-     */
-    totalPages?: number;
-    /**
-     * 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;
-}
-
-/**
- * Resolves $ref references in DoclingDocument to actual objects.
- *
- * DoclingDocument uses JSON references (e.g., "#/texts/0") to link nodes.
- * This class builds an index for quick lookups of texts, pictures, tables, and groups.
- */
-declare class RefResolver {
-    private readonly logger;
-    private readonly textMap;
-    private readonly pictureMap;
-    private readonly tableMap;
-    private readonly groupMap;
-    constructor(logger: LoggerMethods, doc: DoclingDocument);
-    /**
-     * Build an index mapping self_ref to the actual item
-     */
-    private buildIndex;
-    /**
-     * Check whether a Docling self reference exists in the indexed document.
-     */
-    hasRef(ref: string): boolean;
-    /**
-     * Assert that a Docling self reference exists in the indexed document.
-     */
-    assertRef(ref: string, context: string): void;
-    /**
-     * Assert that every Docling self reference exists in the indexed document.
-     */
-    assertRefs(refs: string[], context: string): void;
-    /**
-     * Resolve a $ref string to the actual item
-     * @param ref - Reference string (e.g., "#/texts/0")
-     * @returns The resolved item, or null if not found
-     */
-    resolve(ref: string): DoclingTextItem | DoclingPictureItem | DoclingTableItem | DoclingGroupItem | null;
-    /**
-     * Resolve a text reference
-     * @param ref - Reference string (e.g., "#/texts/0")
-     * @returns The resolved text item, or null if not found
-     */
-    resolveText(ref: string): DoclingTextItem | null;
-    /**
-     * Resolve a picture reference
-     * @param ref - Reference string (e.g., "#/pictures/0")
-     * @returns The resolved picture item, or null if not found
-     */
-    resolvePicture(ref: string): DoclingPictureItem | null;
-    /**
-     * Resolve a table reference
-     * @param ref - Reference string (e.g., "#/tables/0")
-     * @returns The resolved table item, or null if not found
-     */
-    resolveTable(ref: string): DoclingTableItem | null;
-    /**
-     * Resolve a group reference
-     * @param ref - Reference string (e.g., "#/groups/0")
-     * @returns The resolved group item, or null if not found
-     */
-    resolveGroup(ref: string): DoclingGroupItem | null;
-    /**
-     * Resolve multiple references at once
-     * @param refs - Array of reference objects with $ref property
-     * @returns Array of resolved items (null for unresolved references)
-     */
-    resolveMany(refs: Array<{
-        $ref: string;
-    }>): Array<DoclingTextItem | DoclingPictureItem | DoclingTableItem | DoclingGroupItem | null>;
-}
-
-/**
- * Generates sequential IDs for different types of items.
- *
- * IDs are formatted as: `{prefix}-{number}` where number is zero-padded to 3 digits.
- * - Chapters: ch-001, ch-002, ...
- * - Images: img-001, img-002, ...
- * - Tables: tbl-001, tbl-002, ...
- * - Text blocks: txt-001, txt-002, ...
- *
- * Each type maintains its own independent counter.
- */
-declare class IdGenerator {
-    private chapterCounter;
-    private imageCounter;
-    private tableCounter;
-    private footnoteCounter;
-    private textBlockCounter;
-    /**
-     * Generate a chapter ID
-     * @returns A chapter ID in the format "ch-001"
-     */
-    generateChapterId(): string;
-    /**
-     * Generate an image ID
-     * @returns An image ID in the format "img-001"
-     */
-    generateImageId(): string;
-    /**
-     * Generate a table ID
-     * @returns A table ID in the format "tbl-001"
-     */
-    generateTableId(): string;
-    /**
-     * Generate a footnote ID
-     * @returns A footnote ID in the format "ftn-001"
-     */
-    generateFootnoteId(): string;
-    /**
-     * Generate a text block ID
-     * @returns A text block ID in the format "txt-001"
-     */
-    generateTextBlockId(): string;
-    /**
-     * Reset all counters to zero
-     */
-    reset(): void;
-    /**
-     * Get current counter values (for testing/debugging)
-     */
-    getCounters(): {
-        chapter: number;
-        image: number;
-        table: number;
-        footnote: number;
-        textBlock: number;
-    };
-    /**
-     * Pad a number to 3 digits with leading zeros
-     */
-    private padNumber;
-}
-
-/**
- * Extract the maximum page number from TOC markdown
- *
- * Parses page numbers from dot-leader patterns (e.g., "..... 175")
- * and table cell patterns (e.g., "| title | 175 |") to detect compiled
- * volume scenarios where TOC page numbers exceed the sub-document's page count.
- *
- * @param markdown - TOC markdown content
- * @returns Maximum page number found, or 0 if none found
- */
-declare function extractMaxPageNumber(markdown: string): number;
-
-/**
- * TOC keyword patterns for different languages
- * Korean: 목차, 차례, 목 차
- * Chinese: 目录, 目 录, 内容, 內容
- * Japanese: 目次, 目 次
- * English: Contents, Table of Contents, etc.
- */
-declare const TOC_KEYWORDS: readonly ["목차", "차례", "목 차", "目录", "目 录", "内容", "內容", "目次", "目 次", "Contents", "Table of Contents", "TABLE OF CONTENTS", "CONTENTS"];
-/**
- * Continuation marker patterns for multi-page TOC
- * Korean: 목차(계속), 목차 (계속), (계속)
- * Chinese: 目录(续), 目录 (续), (续), 续表
- * Japanese: 目次(続), 目次 (続), (続)
- * English: (continued), (Continued), etc.
- */
-declare const CONTINUATION_MARKERS: readonly ["목차(계속)", "목차 (계속)", "(계속)", "目录(续)", "目录 (续)", "(续)", "续表", "目次(続)", "目次 (続)", "(続)", "(continued)", "(Continued)", "(CONTINUED)", "continued"];
-/**
- * Page number pattern regex for detecting TOC-like structures
- * Matches patterns like "... 123", ".... 45", ending with numbers
- */
-declare const PAGE_NUMBER_PATTERN: RegExp;
-/**
- * TocFinder options
- */
-interface TocFinderOptions {
-    /**
-     * Maximum pages to search for TOC (default: 10)
-     */
-    maxSearchPages?: number;
-    /**
-     * Custom TOC keywords to add (optional)
-     */
-    additionalKeywords?: string[];
-}
-/**
- * TocFinder
- *
- * Finds TOC area in DoclingDocument using multi-stage search strategy:
- * 1. Keyword search in texts (section_header, list_item labels)
- * 2. Structure analysis for lists/tables with page number patterns
- * 3. Position heuristic (prioritize early pages)
- */
-declare class TocFinder {
-    private readonly logger;
-    private readonly refResolver;
-    private readonly maxSearchPages;
-    private readonly keywords;
-    constructor(logger: LoggerMethods, refResolver: RefResolver, options?: TocFinderOptions);
-    /**
-     * Find TOC area in the document
-     *
-     * @throws {TocNotFoundError} When no TOC area is found
-     */
-    find(doc: DoclingDocument): TocAreaResult;
-    /**
-     * Stage 1: Search by keywords in text items
-     */
-    private findByKeywords;
-    /**
-     * Stage 2: Search by structure (lists/tables with page numbers)
-     */
-    private findByStructure;
-    /**
-     * Find the TOC container (group or table) from a parent reference
-     */
-    private findTocContainer;
-    /**
-     * Find adjacent TOC item among body siblings following the keyword text.
-     * Used when findTocContainer returns null (e.g., parent is #/body).
-     */
-    private findSiblingTocItem;
-    /**
-     * Check if a group contains TOC-like structure
-     */
-    private isGroupTocLike;
-    /**
-     * Check if a table contains TOC-like structure
-     */
-    private isTableTocLike;
-    /**
-     * Check if a table is a resource index (drawing/photo/figure list)
-     * rather than a main TOC table
-     */
-    private isResourceIndexTable;
-    /**
-     * Expand TOC area to consecutive pages (both backward and forward)
-     */
-    private expandToConsecutivePages;
-    /**
-     * Find TOC continuation items on a specific page
-     */
-    private findContinuationOnPage;
-    /**
-     * Check if text contains TOC keyword
-     */
-    private containsTocKeyword;
-    /**
-     * Check for continuation markers
-     */
-    private hasContinuationMarker;
-    /**
-     * Get first page number of a group by checking its children
-     */
-    private getGroupFirstPage;
-    /**
-     * Calculate score for a group candidate
-     * Higher score = better match
-     */
-    private calculateScore;
-    /**
-     * Calculate score for a table candidate
-     */
-    private calculateTableScore;
-}
-
-/**
- * Zod schema for TocEntry structure with fixed 4-level depth
- */
-declare const TocEntrySchema: z.ZodType<TocEntry>;
-/**
- * Schema for LLM response
- */
-declare const TocResponseSchema: z.ZodObject<{
-    entries: z.ZodArray<z.ZodType<TocEntry, unknown, z.core.$ZodTypeInternals<TocEntry, unknown>>>;
-}, z.core.$strip>;
-type TocResponse = z.infer<typeof TocResponseSchema>;
-/**
- * TocExtractor options
- */
-interface TocExtractorOptions extends BaseLLMComponentOptions {
-    /**
-     * Validation options (optional)
-     * If not provided, validation is performed with default settings
-     */
-    validation?: TocValidationOptions;
-    /**
-     * Whether to skip validation entirely (default: false)
-     */
-    skipValidation?: boolean;
-    /**
-     * Maximum retry count for TOC validation correction feedback (default: 3)
-     */
-    maxValidationRetries?: number;
-}
-/**
- * TocExtractor
- *
- * 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 maxValidationRetries times before throwing.
- */
-declare class TocExtractor extends TextLLMComponent {
-    private readonly validationOptions?;
-    private readonly skipValidation;
-    private readonly maxValidationRetries;
-    constructor(logger: LoggerMethods, model: LanguageModel, options?: TocExtractorOptions, fallbackModel?: LanguageModel, abortSignal?: AbortSignal);
-    /**
-     * Extract TOC structure from Markdown
-     *
-     * 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)
-     * @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 after all retries
-     */
-    extract(markdown: string, validationOverrides?: Partial<TocValidationOptions>): Promise<{
-        entries: TocEntry[];
-        usages: ExtendedTokenUsage[];
-    }>;
-    /**
-     * 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
-     *
-     * Includes the original markdown, previous extraction result,
-     * validation errors, and guidance for fixing common mistakes.
-     */
-    protected buildCorrectionPrompt(markdown: string, previousEntries: TocEntry[], issues: TocValidationIssue[]): string;
-    /**
-     * Build system prompt for TOC extraction
-     */
-    protected buildSystemPrompt(): string;
-    /**
-     * Build user prompt with Markdown content
-     */
-    protected buildUserPrompt(markdown: string): string;
-    /**
-     * Normalize and validate extracted entries
-     */
-    private normalizeEntries;
-    /**
-     * Recursively ensure level consistency
-     *
-     * Children must have level = parent.level + 1
-     */
-    private normalizeLevel;
-}
-
-/**
- * Schema for vision-based TOC extraction response
- */
-declare const VisionTocExtractionSchema: z.ZodObject<{
-    hasToc: z.ZodBoolean;
-    tocMarkdown: z.ZodNullable<z.ZodString>;
-    continuesOnNextPage: z.ZodBoolean;
-}, z.core.$strip>;
-type VisionTocExtractionResult = z.infer<typeof VisionTocExtractionSchema>;
-/**
- * Options for VisionTocExtractor
- */
-interface VisionTocExtractorOptions extends VisionLLMComponentOptions {
-    /**
-     * Number of pages for first batch (default: 10)
-     */
-    firstBatchSize?: number;
-    /**
-     * Number of pages for second batch (default: 10)
-     */
-    secondBatchSize?: number;
-}
-/**
- * VisionTocExtractor
- *
- * Uses vision LLM to find and extract TOC directly from page images.
- * Fallback strategy when rule-based extraction fails or produces invalid content.
- * Extends VisionLLMComponent for standardized vision LLM call handling.
- *
- * Output format matches MarkdownConverter.convert() for consistency.
- */
-declare class VisionTocExtractor extends VisionLLMComponent {
-    private readonly firstBatchSize;
-    private readonly secondBatchSize;
-    constructor(logger: LoggerMethods, model: LanguageModel, artifactDir: string, options?: VisionTocExtractorOptions, fallbackModel?: LanguageModel, aggregator?: LLMTokenUsageAggregator);
-    /**
-     * Extract TOC from page images
-     *
-     * Searches pages 1-10 first, then 11-20 if not found.
-     *
-     * @param totalPages - Total number of pages in the document
-     * @returns Extracted TOC markdown or null if not found
-     */
-    extract(totalPages: number): Promise<string | null>;
-    /**
-     * Extract TOC from a specific batch of pages
-     */
-    private extractFromBatch;
-    /**
-     * Load page images and build message content
-     */
-    private loadPageImages;
-    /**
-     * Merge markdown from multiple batches
-     */
-    private mergeMarkdown;
-    /**
-     * Build system prompt for vision LLM (not used, but required by abstract class)
-     */
-    protected buildSystemPrompt(): string;
-    /**
-     * Build user prompt with page range information
-     */
-    protected buildUserPrompt(startPage: number, endPage: number): string;
-}
-
-/**
- * Base options for all validators
- *
- * Re-exported from BaseLLMComponentOptions for backwards compatibility.
- */
-type BaseValidatorOptions = BaseLLMComponentOptions;
-/**
- * Abstract base class for LLM-based validators
- *
- * Extends TextLLMComponent to provide common functionality for validators
- * that use LLM to validate/analyze content:
- * - LLM API call wrapper with LLMCaller (via callLLM method)
- * - Standard logging patterns (via log method from base class)
- * - Retry and fallback configuration
- *
- * Token usage is tracked by LLMCaller and should be aggregated by DocumentProcessor.
- *
- * @template TSchema - Zod schema type for validation
- * @template TResult - Result type after parsing with schema
- */
-declare abstract class BaseValidator<TSchema extends z.ZodType, TResult = z.infer<TSchema>> extends TextLLMComponent {
-    /**
-     * Validator name for logging (kept for backwards compatibility)
-     */
-    protected readonly validatorName: string;
-    /**
-     * Constructor for BaseValidator
-     *
-     * @param logger - Logger instance
-     * @param model - Language model to use for validation
-     * @param validatorName - Name of the validator for logging (e.g., "TocContentValidator")
-     * @param options - Optional configuration (maxRetries, temperature)
-     * @param fallbackModel - Optional fallback model for retry on failure
-     * @param aggregator - Optional token usage aggregator for tracking LLM calls
-     */
-    constructor(logger: LoggerMethods, model: LanguageModel, validatorName: string, options?: BaseValidatorOptions, fallbackModel?: LanguageModel, aggregator?: LLMTokenUsageAggregator);
-    /**
-     * Call LLM with LLMCaller
-     *
-     * This method provides backwards compatibility with existing validators.
-     * It wraps the parent callTextLLM method but allows passing a custom aggregator.
-     *
-     * @param schema - Zod schema for response validation
-     * @param systemPrompt - System prompt
-     * @param userPrompt - User prompt
-     * @param phase - Phase name for tracking (e.g., 'validation', 'batch-validation')
-     * @param aggregator - Optional token usage aggregator for tracking this call
-     * @returns Parsed and validated LLM response with usage information
-     */
-    protected callLLM(schema: TSchema, systemPrompt: string, userPrompt: string, phase: string, aggregator?: LLMTokenUsageAggregator): Promise<{
-        output: TResult;
-        usage: ExtendedTokenUsage;
-    }>;
-}
-
-/**
- * Content type for TOC validation
- */
-type TocContentType = 'pure_toc' | 'mixed' | 'resource_only' | 'invalid';
-/**
- * Schema for TOC content validation response
- */
-declare const TocContentValidationSchema: z.ZodObject<{
-    isValid: z.ZodBoolean;
-    confidence: z.ZodNumber;
-    contentType: z.ZodEnum<{
-        pure_toc: "pure_toc";
-        mixed: "mixed";
-        resource_only: "resource_only";
-        invalid: "invalid";
-    }>;
-    extractedTocMarkdown: z.ZodNullable<z.ZodString>;
-    reason: z.ZodString;
-}, z.core.$strip>;
-type TocContentValidationResult = z.infer<typeof TocContentValidationSchema>;
-/**
- * Output type for TOC validation with resolved markdown
- */
-interface TocValidationOutput {
-    isValid: boolean;
-    confidence: number;
-    contentType: TocContentType;
-    validTocMarkdown: string | null;
-    reason: string;
-}
-/**
- * Options for TocContentValidator
- */
-interface TocContentValidatorOptions extends BaseValidatorOptions {
-    /**
-     * Minimum confidence to consider valid (default: 0.7)
-     */
-    confidenceThreshold?: number;
-}
-/**
- * TocContentValidator
- *
- * Uses LLM to validate whether extracted markdown content is actually a TOC.
- * This is a semantic validation, not structural validation.
- * Supports mixed content extraction where main TOC is combined with resource indices.
- */
-declare class TocContentValidator extends BaseValidator<typeof TocContentValidationSchema, TocContentValidationResult> {
-    private readonly confidenceThreshold;
-    constructor(logger: LoggerMethods, model: LanguageModel, options?: TocContentValidatorOptions, fallbackModel?: LanguageModel, aggregator?: LLMTokenUsageAggregator);
-    /**
-     * Validate if the markdown content is a table of contents
-     *
-     * @param markdown - Markdown content to validate
-     * @returns Validation output with resolved markdown for valid TOC
-     */
-    validate(markdown: string): Promise<TocValidationOutput>;
-    /**
-     * Check if validation result passes threshold
-     *
-     * @param result - Validation output from validate()
-     * @returns true if content is valid TOC with sufficient confidence
-     */
-    isValid(result: TocValidationOutput): boolean;
-    /**
-     * Get the valid TOC markdown from validation result
-     *
-     * @param result - Validation output from validate()
-     * @returns Valid TOC markdown or null if invalid
-     */
-    getValidMarkdown(result: TocValidationOutput): string | null;
-    /**
-     * Build system prompt for TOC content validation
-     */
-    protected buildSystemPrompt(): string;
-    /**
-     * Build user prompt with markdown content
-     */
-    protected buildUserPrompt(markdown: string): string;
-}
-
-/**
- * Schema for batch caption validation response
- */
-declare const CaptionValidationBatchSchema: z.ZodObject<{
-    results: z.ZodArray<z.ZodObject<{
-        index: z.ZodNumber;
-        isValid: z.ZodBoolean;
-        reason: z.ZodNullable<z.ZodString>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-type CaptionValidationBatch = z.infer<typeof CaptionValidationBatchSchema>;
-/**
- * Options for CaptionValidator
- */
-interface CaptionValidatorOptions extends BaseValidatorOptions {
-}
-/**
- * CaptionValidator
- *
- * Validates parsed captions against original text using LLM.
- * Processes captions in batches to optimize LLM API calls.
- *
- * ## Validation Rules
- *
- * Checks if the parsed "num" field correctly extracts the prefix + number from original text:
- * 1. **Correctness**: The "num" must contain the actual prefix+number from the original text
- *    - Example: "도판 1 유적 전경" → num="도판 1" ✓
- *    - Example: "도판 1 유적 전경" → num="도판" ✗ (incomplete)
- *
- * 2. **Spacing**: The spacing in "num" must match the original text exactly
- *    - Example: "도판 1" → num="도판 1" ✓
- *    - Example: "도판1" → num="도판1" ✓
- *    - Example: "도판 1" → num="도판1" ✗ (spacing mismatch)
- *
- * 3. **Completeness**: The number part must be fully extracted
- *    - Example: "Figure 2-3" → num="Figure 2-3" ✓
- *    - Example: "Figure 2-3" → num="Figure 2" ✗ (incomplete number)
- *
- * 4. **Null handling**: If "num" is null, verify that the original text has no number prefix
- *    - Example: "유적 전경 사진" → num=null ✓
- *    - Example: "도판 1 전경" → num=null ✗ (should extract "도판 1")
- */
-declare class CaptionValidator extends BaseValidator<typeof CaptionValidationBatchSchema, CaptionValidationBatch> {
-    constructor(logger: LoggerMethods, model: LanguageModel, options?: CaptionValidatorOptions, fallbackModel?: LanguageModel, aggregator?: LLMTokenUsageAggregator);
-    /**
-     * Validate batch of parsed captions against original texts
-     *
-     * @param captions - Array of parsed Caption objects
-     * @param originalTexts - Array of original caption texts (same order as captions)
-     * @param batchSize - Batch size for processing. Set to 0 to skip validation (assume all valid).
-     * @returns Array of validation results (boolean) maintaining original order
-     */
-    validateBatch(captions: Caption[], originalTexts: string[], batchSize: number): Promise<boolean[]>;
-    /**
-     * Internal: Validate batch of captions using LLM
-     *
-     * @param items - Batch of caption items with original indices
-     * @param model - Effective model to use
-     * @returns Array of validation results indexed correctly
-     */
-    private validateBatchInternal;
-    protected buildSystemPrompt(): string;
-    protected buildUserPrompt(items: Array<{
-        index: number;
-        caption: Caption;
-        originalText: string;
-    }>): string;
-}
-/**
- * Error thrown when caption validation fails
- */
-declare class CaptionValidationError extends Error {
-    constructor(message: string, options?: ErrorOptions);
-}
-
-/**
- * ChapterConverter
- *
- * Converts TocEntry[] to Chapter[] with text blocks, images, and tables.
- *
- * ## Conversion Process
- *
- * 1. Create Front Matter chapter (ch-000) for pre-TOC content
- * 2. Build chapter tree from TocEntry[] (recursive)
- * 3. Calculate page ranges for each chapter
- * 4. Assign text blocks to chapters based on page ranges
- * 5. Link images/tables to chapters based on page ranges
- *
- * ## Page Assignment Strategy
- *
- * Uses "start page first" strategy: resources are assigned to the chapter
- * whose startPage is the largest value that is still <= the resource's page.
- *
- * ## Front Matter
- *
- * A special chapter (ch-000) is always created to hold content that appears
- * before the first TOC entry (e.g., cover, preface, table of contents itself).
- */
-declare class ChapterConverter {
-    private static readonly FRONT_MATTER_ID;
-    private static readonly FRONT_MATTER_TITLE;
-    private readonly logger;
-    private readonly idGenerator;
-    constructor(logger: LoggerMethods, idGenerator: IdGenerator);
-    /**
-     * Convert TocEntry[] to Chapter[]
-     *
-     * @param tocEntries - Table of contents entries
-     * @param textItems - DoclingDocument.texts (with prov for page numbers)
-     * @param pageRangeMap - PDF page to actual page mapping
-     * @param images - Converted images
-     * @param tables - Converted tables
-     * @param footnotes - Converted footnotes
-     * @returns Converted chapters with text blocks and resource references
-     */
-    convert(tocEntries: TocEntry[], textItems: DoclingTextItem[], pageRangeMap: Record<number, PageRange>, images: ProcessedImage[], tables: ProcessedTable[], footnotes: ProcessedFootnote[]): Chapter[];
-    /**
-     * Create Front Matter chapter for pre-TOC content
-     */
-    private createFrontMatterChapter;
-    /**
-     * Build chapter tree from TocEntry[]
-     * Recursively processes children
-     */
-    private buildChapterTree;
-    /**
-     * Flatten chapter tree for page range calculation
-     * Preserves original TOC page numbers
-     */
-    private flattenChapters;
-    /**
-     * Calculate page range for each chapter
-     * Uses next chapter's start page as end boundary
-     *
-     * Front Matter (ch-000) gets special handling:
-     * - startPage: 1
-     * - endPage: first TOC entry's page - 1 (or 0 if TOC starts at page 1)
-     */
-    private calculatePageRanges;
-    /**
-     * Valid labels for text blocks
-     * Only these labels are included in chapter text blocks
-     */
-    private static readonly VALID_TEXT_LABELS;
-    /**
-     * Check if text item has a picture parent
-     * Items with parent.$ref starting with "#/pictures/" are excluded
-     */
-    private static hasPictureParent;
-    /**
-     * Convert text items to text blocks
-     * Filters by label (text, section_header, list_item), excludes picture children,
-     * and extracts page numbers from prov
-     */
-    private convertTextBlocks;
-    /**
-     * Convert PDF page number to actual document page number
-     * Falls back to pdfPageNo if mapping is missing
-     */
-    private pdfPageToActualPage;
-    /**
-     * Find chapter ID for a given actual page number
-     * Uses "start page first" strategy
-     */
-    private findChapterForPage;
-    /**
-     * Assign text blocks to chapters based on page ranges
-     */
-    private assignTextBlocks;
-    /**
-     * Link images, tables, and footnotes to chapters based on page ranges
-     */
-    private linkResources;
-    /**
-     * Build flat chapter map for O(1) lookup
-     */
-    private buildChapterMap;
-}
-
-/**
- * Dependencies required by CaptionProcessingPipeline
- */
-interface CaptionProcessingPipelineDeps {
-    logger: LoggerMethods;
-    captionParser: CaptionParser;
-    captionValidator: CaptionValidator;
-    refResolver?: RefResolver;
-    fallbackModel: LanguageModel;
-    enableFallbackRetry: boolean;
-    maxRetries: number;
-    captionParserBatchSize: number;
-    captionValidatorBatchSize: number;
-    usageAggregator: LLMTokenUsageAggregator;
-    abortSignal?: AbortSignal;
-}
-/**
- * Caption text and source references extracted from Docling caption links.
- *
- * `text` is omitted when none of the captions resolved to non-empty text;
- * `sourceRefs` is always present and contains every `$ref` caption in order
- * (string captions contribute to `text` only).
- */
-interface CaptionSourceExtraction {
-    text?: string;
-    sourceRefs: string[];
-}
-/**
- * CaptionProcessingPipeline
- *
- * Processes resource captions through a multi-step pipeline:
- * 1. Parse captions in batch (CaptionParser)
- * 2. Handle length mismatch recovery
- * 3. Validate parsed captions (CaptionValidator)
- * 4. Reparse failed captions with fallback model
- */
-declare class CaptionProcessingPipeline {
-    private static readonly CAPTION_JOIN_SEPARATOR;
-    private readonly logger;
-    private readonly captionParser;
-    private readonly captionValidator;
-    private readonly refResolver?;
-    private readonly fallbackModel;
-    private readonly enableFallbackRetry;
-    private readonly maxRetries;
-    private readonly captionParserBatchSize;
-    private readonly captionValidatorBatchSize;
-    private readonly usageAggregator;
-    private readonly abortSignal?;
-    constructor(deps: CaptionProcessingPipelineDeps);
-    /**
-     * Process resource captions (for images and tables)
-     *
-     * Common caption processing pipeline:
-     * 1. Parse captions in batch
-     * 2. Validate parsed captions
-     * 3. Reparse failed captions with fallback model
-     *
-     * @param captionTexts - Array of caption texts to process
-     * @param resourceType - Type of resource for logging (e.g., 'image', 'table')
-     * @returns Parsed captions with index mapping
-     */
-    processResourceCaptions(captionTexts: Array<string | undefined>, resourceType: string): Promise<Map<number, Caption>>;
-    /**
-     * Extract combined caption text from resource captions.
-     *
-     * Returns every caption joined with a single space; empty/whitespace-only
-     * entries are skipped. Returns `undefined` when nothing resolves to text.
-     *
-     * @deprecated Use {@link extractCaptionSource} to also receive the
-     * caption `$ref` list. This helper is retained as a thin wrapper for
-     * legacy callers.
-     */
-    extractCaptionText(captions: Array<string | DoclingReference> | undefined): string | undefined;
-    /**
-     * Extract caption text and source references from resource captions.
-     *
-     * Iterates captions in order. String captions contribute to text only;
-     * `$ref` captions also push the ref onto `sourceRefs` regardless of whether
-     * the resolver finds text. Resolved/raw text is trimmed, and empty parts
-     * are skipped before joining.
-     */
-    extractCaptionSource(captions: Array<string | DoclingReference> | undefined): CaptionSourceExtraction;
-}
-
-/**
- * Dependencies required by TocExtractionPipeline
- */
-interface TocExtractionPipelineDeps {
-    logger: LoggerMethods;
-    tocFinder: TocFinder;
-    tocExtractor: TocExtractor;
-    tocContentValidator: TocContentValidator;
-    visionTocExtractor: VisionTocExtractor;
-    refResolver: RefResolver;
-    usageAggregator: LLMTokenUsageAggregator;
-}
-/**
- * TocExtractionPipeline
- *
- * Orchestrates the multi-stage TOC extraction process:
- * 1. Rule-based extraction (TocFinder + MarkdownConverter)
- * 2. Content validation (TocContentValidator)
- * 3. Vision fallback (VisionTocExtractor)
- * 4. Structured extraction with validation retry (TocExtractor)
- * 5. Vision fallback retry when text-based extraction yields 0 entries
- */
-declare class TocExtractionPipeline {
-    private readonly logger;
-    private readonly tocFinder;
-    private readonly tocExtractor;
-    private readonly tocContentValidator;
-    private readonly visionTocExtractor;
-    private readonly refResolver;
-    private readonly usageAggregator;
-    constructor(deps: TocExtractionPipelineDeps);
-    /**
-     * Execute the TOC extraction pipeline
-     *
-     * @param doclingDoc - Document containing texts, pages, etc.
-     * @param _filteredTexts - Pre-filtered texts (reserved for future use)
-     * @returns Extracted TOC entries
-     * @throws {TocNotFoundError} When TOC cannot be found or extracted
-     */
-    extract(doclingDoc: DoclingDocument, _filteredTexts: string[]): Promise<TocEntry[]>;
-}
-
-/**
- * ResourceConverter
- *
- * Converts DoclingDocument resources (images, tables, footnotes) to processed format.
- * Uses CaptionProcessingPipeline for caption extraction and validation.
- */
-declare class ResourceConverter {
-    private readonly logger;
-    private readonly idGenerator;
-    private readonly captionProcessingPipeline;
-    constructor(logger: LoggerMethods, idGenerator: IdGenerator, captionProcessingPipeline: CaptionProcessingPipeline);
-    /**
-     * Convert all resources (images, tables, footnotes)
-     *
-     * Runs image and table conversions in parallel, then footnotes synchronously.
-     */
-    convertAll(doclingDoc: DoclingDocument, artifactDir: string): Promise<{
-        images: ProcessedImage[];
-        tables: ProcessedTable[];
-        footnotes: ProcessedFootnote[];
-    }>;
-    /**
-     * Convert images from DoclingDocument to ProcessedImage[]
-     */
-    convertImages(doclingDoc: DoclingDocument, artifactDir: string): Promise<ProcessedImage[]>;
-    /**
-     * Convert tables from DoclingDocument to ProcessedTable[]
-     */
-    convertTables(doclingDoc: DoclingDocument): Promise<ProcessedTable[]>;
-    /**
-     * Convert footnotes from DoclingDocument text items
-     */
-    convertFootnotes(doclingDoc: DoclingDocument): ProcessedFootnote[];
-}
-
-export { BaseLLMComponent, type BaseLLMComponentOptions, BaseValidator, type BaseValidatorOptions, CONTINUATION_MARKERS, CaptionParseError, CaptionParser, type CaptionParserOptions, CaptionProcessingPipeline, type CaptionProcessingPipelineDeps, type CaptionSourceExtraction, CaptionValidationError, CaptionValidator, type CaptionValidatorOptions, ChapterConverter, DocumentProcessor, type DocumentProcessorOptions, type DocumentProcessorProcessOptions, type ImageContent, PAGE_NUMBER_PATTERN, PROCESSED_DOCUMENT_SCHEMA_VERSION, PagePattern, PageRangeParseError, PageRangeParser, type PageSizeGroup, ResourceConverter, type SourceRefValidationMode, TOC_KEYWORDS, TextLLMComponent, type TocAreaResult, type TocContentValidationResult, TocContentValidationSchema, TocContentValidator, type TocContentValidatorOptions, type TocEntry, TocEntrySchema, TocExtractError, TocExtractionPipeline, type TocExtractionPipelineDeps, TocExtractor, type TocExtractorOptions, TocFinder, type TocFinderOptions, TocNotFoundError, TocParseError, type TocResponse, TocResponseSchema, VisionLLMComponent, type VisionLLMComponentOptions, type VisionTocExtractionResult, VisionTocExtractionSchema, VisionTocExtractor, type VisionTocExtractorOptions, extractMaxPageNumber };