@heripo/document-processor 0.1.0

package/dist/index.js

@@ -0,0 +1,4262 @@
+// ../shared/dist/index.mjs
+import { Output, generateText } from "ai";
+var BatchProcessor = class {
+  /**
+   * Splits an array into batches of specified size.
+   *
+   * @param items - Array to split
+   * @param batchSize - Size of each batch
+   * @returns Array of batches
+   *
+   * @example
+   * ```typescript
+   * const items = [1, 2, 3, 4, 5];
+   * const batches = BatchProcessor.createBatches(items, 2);
+   * // [[1, 2], [3, 4], [5]]
+   * ```
+   */
+  static createBatches(items, batchSize) {
+    const batches = [];
+    for (let i = 0; i < items.length; i += batchSize) {
+      batches.push(items.slice(i, i + batchSize));
+    }
+    return batches;
+  }
+  /**
+   * Splits an array into batches and executes async function in parallel.
+   *
+   * @param items - Array to process
+   * @param batchSize - Size of each batch
+   * @param processFn - Async function to process each batch
+   * @returns Flattened array of processed results
+   *
+   * @example
+   * ```typescript
+   * const texts = ['a', 'b', 'c', 'd', 'e'];
+   * const results = await BatchProcessor.processBatch(
+   *   texts,
+   *   2,
+   *   async (batch) => {
+   *     return batch.map(t => t.toUpperCase());
+   *   }
+   * );
+   * // ['A', 'B', 'C', 'D', 'E']
+   * ```
+   */
+  static async processBatch(items, batchSize, processFn) {
+    const batches = this.createBatches(items, batchSize);
+    const results = await Promise.all(batches.map((batch) => processFn(batch)));
+    return results.flat();
+  }
+  /**
+   * Splits an array into batches and executes sync function in parallel.
+   *
+   * @param items - Array to process
+   * @param batchSize - Size of each batch
+   * @param processFn - Sync function to process each batch
+   * @returns Flattened array of processed results
+   *
+   * @example
+   * ```typescript
+   * const numbers = [1, 2, 3, 4, 5];
+   * const results = BatchProcessor.processBatchSync(
+   *   numbers,
+   *   2,
+   *   (batch) => batch.map(n => n * 2)
+   * );
+   * // [2, 4, 6, 8, 10]
+   * ```
+   */
+  static processBatchSync(items, batchSize, processFn) {
+    const batches = this.createBatches(items, batchSize);
+    const results = batches.map((batch) => processFn(batch));
+    return results.flat();
+  }
+};
+var LLMCaller = class {
+  /**
+   * Extract model name from LanguageModel object
+   *
+   * Attempts to get model ID from various possible fields in the LanguageModel object.
+   */
+  static extractModelName(model) {
+    const modelObj = model;
+    if (typeof modelObj.modelId === "string") return modelObj.modelId;
+    if (typeof modelObj.id === "string") return modelObj.id;
+    if (typeof modelObj.model === "string") return modelObj.model;
+    if (typeof modelObj.name === "string") return modelObj.name;
+    return String(model);
+  }
+  /**
+   * Build usage information from response
+   */
+  static buildUsage(config, modelName, response, usedFallback) {
+    return {
+      component: config.component,
+      phase: config.phase,
+      model: usedFallback ? "fallback" : "primary",
+      modelName,
+      inputTokens: response.usage?.inputTokens ?? 0,
+      outputTokens: response.usage?.outputTokens ?? 0,
+      totalTokens: response.usage?.totalTokens ?? 0
+    };
+  }
+  /**
+   * Execute LLM call with fallback support
+   *
+   * Common execution logic for both text and vision calls.
+   */
+  static async executeWithFallback(config, generateFn) {
+    const primaryModelName = this.extractModelName(config.primaryModel);
+    try {
+      const response = await generateFn(config.primaryModel);
+      return {
+        output: response.output,
+        usage: this.buildUsage(config, primaryModelName, response, false),
+        usedFallback: false
+      };
+    } catch (primaryError) {
+      if (config.abortSignal?.aborted) {
+        throw primaryError;
+      }
+      if (!config.fallbackModel) {
+        throw primaryError;
+      }
+      const fallbackModelName = this.extractModelName(config.fallbackModel);
+      const response = await generateFn(config.fallbackModel);
+      return {
+        output: response.output,
+        usage: this.buildUsage(config, fallbackModelName, response, true),
+        usedFallback: true
+      };
+    }
+  }
+  /**
+   * Call LLM with retry and fallback support
+   *
+   * Retry Strategy:
+   * 1. Try primary model up to maxRetries times
+   * 2. If all fail and fallbackModel provided, try fallback up to maxRetries times
+   * 3. Throw error if all attempts exhausted
+   *
+   * @template TOutput - Output type from schema validation
+   * @param config - LLM call configuration
+   * @returns Result with parsed object and usage information
+   * @throws Error if all retry attempts fail
+   */
+  static async call(config) {
+    return this.executeWithFallback(
+      config,
+      (model) => generateText({
+        model,
+        output: Output.object({
+          schema: config.schema
+        }),
+        system: config.systemPrompt,
+        prompt: config.userPrompt,
+        temperature: config.temperature,
+        maxRetries: config.maxRetries,
+        abortSignal: config.abortSignal
+      })
+    );
+  }
+  /**
+   * Call LLM for vision tasks with message format support
+   *
+   * Same retry and fallback logic as call(), but using message format instead of system/user prompts.
+   *
+   * @template TOutput - Output type from schema validation
+   * @param config - LLM vision call configuration
+   * @returns Result with parsed object and usage information
+   * @throws Error if all retry attempts fail
+   */
+  static async callVision(config) {
+    return this.executeWithFallback(
+      config,
+      (model) => generateText({
+        model,
+        output: Output.object({
+          schema: config.schema
+        }),
+        messages: config.messages,
+        temperature: config.temperature,
+        maxRetries: config.maxRetries,
+        abortSignal: config.abortSignal
+      })
+    );
+  }
+};
+function formatTokens(usage) {
+  return `${usage.inputTokens} input, ${usage.outputTokens} output, ${usage.totalTokens} total`;
+}
+var LLMTokenUsageAggregator = class {
+  usage = {};
+  /**
+   * Track token usage from an LLM call
+   *
+   * @param usage - Extended token usage with component/phase/model information
+   */
+  track(usage) {
+    if (!this.usage[usage.component]) {
+      this.usage[usage.component] = {
+        component: usage.component,
+        phases: {},
+        total: {
+          inputTokens: 0,
+          outputTokens: 0,
+          totalTokens: 0
+        }
+      };
+    }
+    const component = this.usage[usage.component];
+    if (!component.phases[usage.phase]) {
+      component.phases[usage.phase] = {
+        total: {
+          inputTokens: 0,
+          outputTokens: 0,
+          totalTokens: 0
+        }
+      };
+    }
+    const phase = component.phases[usage.phase];
+    if (usage.model === "primary") {
+      if (!phase.primary) {
+        phase.primary = {
+          modelName: usage.modelName,
+          inputTokens: 0,
+          outputTokens: 0,
+          totalTokens: 0
+        };
+      }
+      phase.primary.inputTokens += usage.inputTokens;
+      phase.primary.outputTokens += usage.outputTokens;
+      phase.primary.totalTokens += usage.totalTokens;
+    } else if (usage.model === "fallback") {
+      if (!phase.fallback) {
+        phase.fallback = {
+          modelName: usage.modelName,
+          inputTokens: 0,
+          outputTokens: 0,
+          totalTokens: 0
+        };
+      }
+      phase.fallback.inputTokens += usage.inputTokens;
+      phase.fallback.outputTokens += usage.outputTokens;
+      phase.fallback.totalTokens += usage.totalTokens;
+    }
+    phase.total.inputTokens += usage.inputTokens;
+    phase.total.outputTokens += usage.outputTokens;
+    phase.total.totalTokens += usage.totalTokens;
+    component.total.inputTokens += usage.inputTokens;
+    component.total.outputTokens += usage.outputTokens;
+    component.total.totalTokens += usage.totalTokens;
+  }
+  /**
+   * Get aggregated usage grouped by component
+   *
+   * @returns Array of component aggregates with phase breakdown
+   */
+  getByComponent() {
+    return Object.values(this.usage);
+  }
+  /**
+   * Get token usage report in structured JSON format
+   *
+   * Converts internal usage data to external TokenUsageReport format suitable
+   * for serialization and reporting. The report includes component breakdown,
+   * phase-level details, and both primary and fallback model usage.
+   *
+   * @returns Structured token usage report with components and total
+   */
+  getReport() {
+    const components = [];
+    for (const component of Object.values(this.usage)) {
+      const phases = [];
+      for (const [phaseName, phaseData] of Object.entries(component.phases)) {
+        const phaseReport = {
+          phase: phaseName,
+          total: {
+            inputTokens: phaseData.total.inputTokens,
+            outputTokens: phaseData.total.outputTokens,
+            totalTokens: phaseData.total.totalTokens
+          }
+        };
+        if (phaseData.primary) {
+          phaseReport.primary = {
+            modelName: phaseData.primary.modelName,
+            inputTokens: phaseData.primary.inputTokens,
+            outputTokens: phaseData.primary.outputTokens,
+            totalTokens: phaseData.primary.totalTokens
+          };
+        }
+        if (phaseData.fallback) {
+          phaseReport.fallback = {
+            modelName: phaseData.fallback.modelName,
+            inputTokens: phaseData.fallback.inputTokens,
+            outputTokens: phaseData.fallback.outputTokens,
+            totalTokens: phaseData.fallback.totalTokens
+          };
+        }
+        phases.push(phaseReport);
+      }
+      components.push({
+        component: component.component,
+        phases,
+        total: {
+          inputTokens: component.total.inputTokens,
+          outputTokens: component.total.outputTokens,
+          totalTokens: component.total.totalTokens
+        }
+      });
+    }
+    const totalUsage = this.getTotalUsage();
+    return {
+      components,
+      total: {
+        inputTokens: totalUsage.inputTokens,
+        outputTokens: totalUsage.outputTokens,
+        totalTokens: totalUsage.totalTokens
+      }
+    };
+  }
+  /**
+   * Get total usage across all components and phases
+   *
+   * @returns Aggregated token usage totals
+   */
+  getTotalUsage() {
+    let totalInput = 0;
+    let totalOutput = 0;
+    let totalTokens = 0;
+    for (const component of Object.values(this.usage)) {
+      totalInput += component.total.inputTokens;
+      totalOutput += component.total.outputTokens;
+      totalTokens += component.total.totalTokens;
+    }
+    return {
+      inputTokens: totalInput,
+      outputTokens: totalOutput,
+      totalTokens
+    };
+  }
+  /**
+   * Log comprehensive token usage summary
+   *
+   * Outputs usage grouped by component, with phase and model breakdown.
+   * Shows primary and fallback token usage separately for each phase.
+   * Call this once at the end of document processing.
+   *
+   * @param logger - Logger instance for output
+   */
+  logSummary(logger) {
+    const components = this.getByComponent();
+    if (components.length === 0) {
+      logger.info("[DocumentProcessor] No token usage to report");
+      return;
+    }
+    logger.info("[DocumentProcessor] Token usage summary:");
+    logger.info("");
+    let grandInputTokens = 0;
+    let grandOutputTokens = 0;
+    let grandTotalTokens = 0;
+    let grandPrimaryInputTokens = 0;
+    let grandPrimaryOutputTokens = 0;
+    let grandPrimaryTotalTokens = 0;
+    let grandFallbackInputTokens = 0;
+    let grandFallbackOutputTokens = 0;
+    let grandFallbackTotalTokens = 0;
+    for (const component of components) {
+      logger.info(`${component.component}:`);
+      for (const [phase, phaseData] of Object.entries(component.phases)) {
+        logger.info(`  - ${phase}:`);
+        if (phaseData.primary) {
+          logger.info(
+            `      primary (${phaseData.primary.modelName}): ${formatTokens(phaseData.primary)}`
+          );
+          grandPrimaryInputTokens += phaseData.primary.inputTokens;
+          grandPrimaryOutputTokens += phaseData.primary.outputTokens;
+          grandPrimaryTotalTokens += phaseData.primary.totalTokens;
+        }
+        if (phaseData.fallback) {
+          logger.info(
+            `      fallback (${phaseData.fallback.modelName}): ${formatTokens(phaseData.fallback)}`
+          );
+          grandFallbackInputTokens += phaseData.fallback.inputTokens;
+          grandFallbackOutputTokens += phaseData.fallback.outputTokens;
+          grandFallbackTotalTokens += phaseData.fallback.totalTokens;
+        }
+        logger.info(`      subtotal: ${formatTokens(phaseData.total)}`);
+      }
+      logger.info(
+        `  ${component.component} total: ${formatTokens(component.total)}`
+      );
+      logger.info("");
+      grandInputTokens += component.total.inputTokens;
+      grandOutputTokens += component.total.outputTokens;
+      grandTotalTokens += component.total.totalTokens;
+    }
+    logger.info("--- Summary ---");
+    if (grandPrimaryTotalTokens > 0) {
+      logger.info(
+        `Primary total: ${formatTokens({
+          inputTokens: grandPrimaryInputTokens,
+          outputTokens: grandPrimaryOutputTokens,
+          totalTokens: grandPrimaryTotalTokens
+        })}`
+      );
+    }
+    if (grandFallbackTotalTokens > 0) {
+      logger.info(
+        `Fallback total: ${formatTokens({
+          inputTokens: grandFallbackInputTokens,
+          outputTokens: grandFallbackOutputTokens,
+          totalTokens: grandFallbackTotalTokens
+        })}`
+      );
+    }
+    logger.info(
+      `Grand total: ${formatTokens({
+        inputTokens: grandInputTokens,
+        outputTokens: grandOutputTokens,
+        totalTokens: grandTotalTokens
+      })}`
+    );
+  }
+  /**
+   * Reset all tracked usage
+   *
+   * Call this at the start of a new document processing run.
+   */
+  reset() {
+    this.usage = {};
+  }
+};
+
+// src/utils/ref-resolver.ts
+var RefResolver = class {
+  logger;
+  textMap;
+  pictureMap;
+  tableMap;
+  groupMap;
+  constructor(logger, doc) {
+    this.logger = logger;
+    this.logger.info("[RefResolver] Initializing reference resolver...");
+    this.textMap = this.buildIndex(doc.texts, "texts");
+    this.pictureMap = this.buildIndex(doc.pictures, "pictures");
+    this.tableMap = this.buildIndex(doc.tables, "tables");
+    this.groupMap = this.buildIndex(doc.groups, "groups");
+    this.logger.info(
+      `[RefResolver] Indexed ${this.textMap.size} texts, ${this.pictureMap.size} pictures, ${this.tableMap.size} tables, ${this.groupMap.size} groups`
+    );
+  }
+  /**
+   * Build an index mapping self_ref to the actual item
+   */
+  buildIndex(items, _prefix) {
+    const map = /* @__PURE__ */ new Map();
+    for (const item of items) {
+      map.set(item.self_ref, item);
+    }
+    return map;
+  }
+  /**
+   * 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) {
+    const match = ref.match(/^#\/(\w+)\//);
+    if (!match) {
+      this.logger.warn(`[RefResolver] Invalid reference format: ${ref}`);
+      return null;
+    }
+    const collection = match[1];
+    if (collection === "texts") {
+      const result = this.textMap.get(ref) ?? null;
+      if (!result) {
+        this.logger.warn(`[RefResolver] Text reference not found: ${ref}`);
+      }
+      return result;
+    }
+    if (collection === "pictures") {
+      const result = this.pictureMap.get(ref) ?? null;
+      if (!result) {
+        this.logger.warn(`[RefResolver] Picture reference not found: ${ref}`);
+      }
+      return result;
+    }
+    if (collection === "tables") {
+      const result = this.tableMap.get(ref) ?? null;
+      if (!result) {
+        this.logger.warn(`[RefResolver] Table reference not found: ${ref}`);
+      }
+      return result;
+    }
+    if (collection === "groups") {
+      const result = this.groupMap.get(ref) ?? null;
+      if (!result) {
+        this.logger.warn(`[RefResolver] Group reference not found: ${ref}`);
+      }
+      return result;
+    }
+    this.logger.warn(`[RefResolver] Unknown collection type: ${collection}`);
+    return 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) {
+    return this.textMap.get(ref) ?? 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) {
+    return this.pictureMap.get(ref) ?? 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) {
+    return this.tableMap.get(ref) ?? 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) {
+    return this.groupMap.get(ref) ?? 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) {
+    return refs.map((ref) => this.resolve(ref.$ref));
+  }
+};
+
+// src/utils/id-generator.ts
+var IdGenerator = class {
+  chapterCounter = 0;
+  imageCounter = 0;
+  tableCounter = 0;
+  footnoteCounter = 0;
+  /**
+   * Generate a chapter ID
+   * @returns A chapter ID in the format "ch-001"
+   */
+  generateChapterId() {
+    this.chapterCounter++;
+    return `ch-${this.padNumber(this.chapterCounter)}`;
+  }
+  /**
+   * Generate an image ID
+   * @returns An image ID in the format "img-001"
+   */
+  generateImageId() {
+    this.imageCounter++;
+    return `img-${this.padNumber(this.imageCounter)}`;
+  }
+  /**
+   * Generate a table ID
+   * @returns A table ID in the format "tbl-001"
+   */
+  generateTableId() {
+    this.tableCounter++;
+    return `tbl-${this.padNumber(this.tableCounter)}`;
+  }
+  /**
+   * Generate a footnote ID
+   * @returns A footnote ID in the format "ftn-001"
+   */
+  generateFootnoteId() {
+    this.footnoteCounter++;
+    return `ftn-${this.padNumber(this.footnoteCounter)}`;
+  }
+  /**
+   * Reset all counters to zero
+   */
+  reset() {
+    this.chapterCounter = 0;
+    this.imageCounter = 0;
+    this.tableCounter = 0;
+    this.footnoteCounter = 0;
+  }
+  /**
+   * Get current counter values (for testing/debugging)
+   */
+  getCounters() {
+    return {
+      chapter: this.chapterCounter,
+      image: this.imageCounter,
+      table: this.tableCounter,
+      footnote: this.footnoteCounter
+    };
+  }
+  /**
+   * Pad a number to 3 digits with leading zeros
+   */
+  padNumber(num) {
+    return num.toString().padStart(3, "0");
+  }
+};
+
+// src/utils/text-cleaner.ts
+var TextCleaner = class {
+  /**
+   * Normalizes text
+   * - Converts consecutive spaces/line breaks to single space
+   * - Trims leading and trailing spaces
+   * - Normalizes special whitespace characters (tabs, non-breaking spaces, etc.)
+   */
+  static normalize(text) {
+    if (!text) return "";
+    let normalized = text.normalize("NFC");
+    normalized = normalized.replace(/[\t\u00A0\u2000-\u200B]/g, " ");
+    normalized = normalized.replace(/[\r\n]+/g, " ");
+    normalized = normalized.replace(/\s+/g, " ");
+    normalized = normalized.trim();
+    return normalized;
+  }
+  /**
+   * Clean text starting/ending with punctuation marks
+   * - Remove commas/periods at sentence start
+   * - Clean spaces and punctuation at sentence end
+   */
+  static cleanPunctuation(text) {
+    if (!text) return "";
+    let cleaned = text.replace(/^[,.:;!?]+\s*/, "");
+    cleaned = cleaned.replace(/\s+[,.:;!?]*$/, "");
+    return cleaned;
+  }
+  /**
+   * Filter text consisting only of numbers and spaces
+   */
+  static isValidText(text) {
+    if (!text) return false;
+    const cleaned = this.normalize(text);
+    return !/^\s*[\d\s]*$/.test(cleaned);
+  }
+  /**
+   * Batch normalization (for bulk processing)
+   */
+  static normalizeBatch(texts) {
+    return texts.map((text) => this.normalize(text));
+  }
+  /**
+   * Batch filtering (returns only valid text)
+   */
+  static filterValidTexts(texts) {
+    return texts.filter((text) => this.isValidText(text));
+  }
+  /**
+   * Batch normalization + filtering (stage 1 + stage 2 combined)
+   *
+   * Performs TextCleaner's basic normalization and filtering in batch processing at once.
+   * Splits large amounts of text into batches for efficient processing.
+   *
+   * If batchSize is 0, processes items sequentially without batch processing.
+   *
+   * @param texts - Original text array
+   * @param batchSize - Batch size (default: 10). Set to 0 for sequential processing without batching.
+   * @returns Normalized and filtered text array
+   *
+   * @example
+   * ```typescript
+   * const rawTexts = ['  text 1  ', '123', 'text 2\n'];
+   * const cleaned = TextCleaner.normalizeAndFilterBatch(rawTexts, 10);
+   * // ['text 1', 'text 2']
+   *
+   * // Sequential processing (no batching)
+   * const cleanedSequential = TextCleaner.normalizeAndFilterBatch(rawTexts, 0);
+   * // ['text 1', 'text 2']
+   * ```
+   */
+  static normalizeAndFilterBatch(texts, batchSize = 10) {
+    if (batchSize === 0) {
+      const results = [];
+      for (const text of texts) {
+        const normalized = this.normalize(text);
+        if (this.isValidText(normalized)) {
+          results.push(normalized);
+        }
+      }
+      return results;
+    }
+    return BatchProcessor.processBatchSync(texts, batchSize, (batch) => {
+      const normalized = this.normalizeBatch(batch);
+      return this.filterValidTexts(normalized);
+    });
+  }
+};
+
+// src/utils/markdown-converter.ts
+var MarkdownConverter = class _MarkdownConverter {
+  /**
+   * Convert TOC items (groups/tables) to Markdown string
+   *
+   * @param refs - Array of item references from TocAreaResult
+   * @param refResolver - RefResolver for resolving references
+   * @returns Markdown string representation of TOC
+   */
+  static convert(refs, refResolver) {
+    if (refs.length === 0) {
+      return "";
+    }
+    const lines = [];
+    for (const ref of refs) {
+      const item = refResolver.resolve(ref);
+      if (!item) {
+        continue;
+      }
+      if ("name" in item && (item.name === "list" || item.name === "group")) {
+        const groupMarkdown = _MarkdownConverter.groupToMarkdown(
+          item,
+          refResolver,
+          0
+        );
+        if (groupMarkdown) {
+          lines.push(groupMarkdown);
+        }
+      } else if ("data" in item && "grid" in item.data) {
+        const tableMarkdown = _MarkdownConverter.tableToMarkdown(
+          item
+        );
+        if (tableMarkdown) {
+          lines.push(tableMarkdown);
+        }
+      } else if ("text" in item && "orig" in item) {
+        const textMarkdown = _MarkdownConverter.textToMarkdown(
+          item,
+          0
+        );
+        if (textMarkdown) {
+          lines.push(textMarkdown);
+        }
+      }
+    }
+    return lines.join("\n\n");
+  }
+  /**
+   * Convert a group item to Markdown list format
+   *
+   * Handles nested lists and preserves hierarchy.
+   *
+   * @example
+   * Output:
+   * - Chapter 1 Introduction ..... 1
+   *   - 1.1 Background ..... 3
+   *   - 1.2 Objectives ..... 5
+   * - Chapter 2 Methodology ..... 10
+   */
+  static groupToMarkdown(group, refResolver, indentLevel = 0) {
+    const lines = [];
+    for (const childRef of group.children) {
+      const child = refResolver.resolve(childRef.$ref);
+      if (!child) {
+        continue;
+      }
+      if ("name" in child && (child.name === "list" || child.name === "group")) {
+        const nestedMarkdown = _MarkdownConverter.groupToMarkdown(
+          child,
+          refResolver,
+          indentLevel + 1
+        );
+        if (nestedMarkdown) {
+          lines.push(nestedMarkdown);
+        }
+      } else if ("text" in child && "orig" in child) {
+        const textMarkdown = _MarkdownConverter.textToMarkdown(
+          child,
+          indentLevel
+        );
+        if (textMarkdown) {
+          lines.push(textMarkdown);
+        }
+      }
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Convert a table item to Markdown table format
+   *
+   * @example
+   * Output:
+   * | Chapter | Page |
+   * |---------|------|
+   * | Chapter 1 Introduction | 1 |
+   * | Chapter 2 Methodology | 10 |
+   */
+  static tableToMarkdown(table) {
+    const { grid } = table.data;
+    if (!grid || grid.length === 0) {
+      return "";
+    }
+    const lines = [];
+    for (let rowIdx = 0; rowIdx < grid.length; rowIdx++) {
+      const row = grid[rowIdx];
+      if (!row || row.length === 0) {
+        continue;
+      }
+      const cells = row.map(
+        (cell) => _MarkdownConverter.escapeTableCell(cell.text)
+      );
+      lines.push(`| ${cells.join(" | ")} |`);
+      if (rowIdx === 0) {
+        const separator = row.map(() => "---").join(" | ");
+        lines.push(`| ${separator} |`);
+      }
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Convert a text item to Markdown line
+   */
+  static textToMarkdown(text, indentLevel = 0) {
+    const content = text.text.trim();
+    if (!content) {
+      return "";
+    }
+    const indent = _MarkdownConverter.getIndent(indentLevel);
+    const marker = _MarkdownConverter.getListMarker(
+      text.enumerated,
+      text.marker
+    );
+    return `${indent}${marker}${content}`;
+  }
+  /**
+   * Generate list marker based on enumeration and marker
+   */
+  static getListMarker(enumerated, marker) {
+    if (marker) {
+      return `${marker} `;
+    }
+    if (enumerated === true) {
+      return "1. ";
+    }
+    if (enumerated === false) {
+      return "- ";
+    }
+    return "- ";
+  }
+  /**
+   * Generate indent string (2 spaces per level)
+   */
+  static getIndent(level) {
+    return "  ".repeat(level);
+  }
+  /**
+   * Escape special characters in table cell content
+   */
+  static escapeTableCell(text) {
+    return text.replace(/\|/g, "\\|").replace(/\n/g, " ").trim();
+  }
+};
+
+// src/converters/chapter-converter.ts
+var ChapterConverter = class _ChapterConverter {
+  static FRONT_MATTER_ID = "ch-000";
+  static FRONT_MATTER_TITLE = "Front Matter";
+  logger;
+  idGenerator;
+  constructor(logger, idGenerator) {
+    this.logger = logger;
+    this.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, textItems, pageRangeMap, images, tables, footnotes) {
+    this.logger.info("[ChapterConverter] Starting chapter conversion...");
+    const frontMatter = this.createFrontMatterChapter();
+    const tocChapters = this.buildChapterTree(tocEntries);
+    this.logger.info(
+      `[ChapterConverter] Built ${tocChapters.length} TOC chapters + Front Matter`
+    );
+    const allChapters = [frontMatter, ...tocChapters];
+    const flatChapters = this.flattenChapters(allChapters);
+    const chapterRanges = this.calculatePageRanges(flatChapters, tocEntries);
+    this.logger.info(
+      `[ChapterConverter] Calculated ranges for ${chapterRanges.size} chapters`
+    );
+    const textBlocks = this.convertTextBlocks(textItems, pageRangeMap);
+    this.assignTextBlocks(allChapters, textBlocks, chapterRanges, pageRangeMap);
+    this.logger.info(
+      `[ChapterConverter] Assigned ${textBlocks.length} text blocks`
+    );
+    this.linkResources(
+      allChapters,
+      images,
+      tables,
+      footnotes,
+      chapterRanges,
+      pageRangeMap
+    );
+    this.logger.info(
+      `[ChapterConverter] Linked ${images.length} images, ${tables.length} tables, and ${footnotes.length} footnotes`
+    );
+    return allChapters;
+  }
+  /**
+   * Create Front Matter chapter for pre-TOC content
+   */
+  createFrontMatterChapter() {
+    return {
+      id: _ChapterConverter.FRONT_MATTER_ID,
+      originTitle: _ChapterConverter.FRONT_MATTER_TITLE,
+      title: _ChapterConverter.FRONT_MATTER_TITLE,
+      pageNo: 1,
+      level: 1,
+      textBlocks: [],
+      imageIds: [],
+      tableIds: [],
+      footnoteIds: []
+    };
+  }
+  /**
+   * Build chapter tree from TocEntry[]
+   * Recursively processes children
+   */
+  buildChapterTree(entries) {
+    return entries.map((entry) => {
+      const chapterId = this.idGenerator.generateChapterId();
+      const chapter = {
+        id: chapterId,
+        originTitle: entry.title,
+        title: TextCleaner.normalize(entry.title),
+        pageNo: entry.pageNo,
+        level: entry.level,
+        textBlocks: [],
+        imageIds: [],
+        tableIds: [],
+        footnoteIds: []
+      };
+      if (entry.children && entry.children.length > 0) {
+        chapter.children = this.buildChapterTree(entry.children);
+      }
+      return chapter;
+    });
+  }
+  /**
+   * Flatten chapter tree for page range calculation
+   * Preserves original TOC page numbers
+   */
+  flattenChapters(chapters) {
+    const result = [];
+    const flatten = (chapterList) => {
+      for (const chapter of chapterList) {
+        result.push({
+          chapter,
+          tocPageNo: chapter.pageNo
+        });
+        if (chapter.children && chapter.children.length > 0) {
+          flatten(chapter.children);
+        }
+      }
+    };
+    flatten(chapters);
+    return result;
+  }
+  /**
+   * 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)
+   */
+  calculatePageRanges(flatChapters, tocEntries) {
+    const ranges = /* @__PURE__ */ new Map();
+    if (flatChapters.length === 0) {
+      return ranges;
+    }
+    const firstTocPage = tocEntries.length > 0 ? Math.min(...tocEntries.map((e) => e.pageNo)) : Number.MAX_SAFE_INTEGER;
+    const tocChapters = flatChapters.filter(
+      (fc) => fc.chapter.id !== _ChapterConverter.FRONT_MATTER_ID
+    );
+    const sorted = [...tocChapters].sort((a, b) => a.tocPageNo - b.tocPageNo);
+    ranges.set(_ChapterConverter.FRONT_MATTER_ID, {
+      startPage: 1,
+      endPage: firstTocPage - 1
+    });
+    for (let i = 0; i < sorted.length; i++) {
+      const current = sorted[i];
+      const next = sorted[i + 1];
+      ranges.set(current.chapter.id, {
+        startPage: current.tocPageNo,
+        endPage: next ? next.tocPageNo - 1 : Number.MAX_SAFE_INTEGER
+      });
+    }
+    return ranges;
+  }
+  /**
+   * Valid labels for text blocks
+   * Only these labels are included in chapter text blocks
+   */
+  static VALID_TEXT_LABELS = /* @__PURE__ */ new Set([
+    "text",
+    "section_header",
+    "list_item"
+  ]);
+  /**
+   * Check if text item has a picture parent
+   * Items with parent.$ref starting with "#/pictures/" are excluded
+   */
+  static hasPictureParent(item) {
+    const parentRef = item.parent?.$ref;
+    return typeof parentRef === "string" && parentRef.startsWith("#/pictures/");
+  }
+  /**
+   * Convert text items to text blocks
+   * Filters by label (text, section_header, list_item), excludes picture children,
+   * and extracts page numbers from prov
+   */
+  convertTextBlocks(textItems, _pageRangeMap) {
+    return textItems.filter(
+      (item) => _ChapterConverter.VALID_TEXT_LABELS.has(item.label) && !_ChapterConverter.hasPictureParent(item) && TextCleaner.isValidText(item.text)
+    ).map((item) => {
+      const pdfPageNo = item.prov?.[0]?.page_no ?? 1;
+      return {
+        text: TextCleaner.normalize(item.text),
+        pdfPageNo
+      };
+    });
+  }
+  /**
+   * Convert PDF page number to actual document page number
+   * Falls back to pdfPageNo if mapping is missing
+   */
+  pdfPageToActualPage(pdfPageNo, pageRangeMap) {
+    const range = pageRangeMap[pdfPageNo];
+    if (!range) {
+      return pdfPageNo;
+    }
+    return range.startPageNo;
+  }
+  /**
+   * Find chapter ID for a given actual page number
+   * Uses "start page first" strategy
+   */
+  findChapterForPage(actualPageNo, chapterRanges) {
+    let bestMatch = null;
+    let bestStartPage = -1;
+    for (const [chapterId, range] of chapterRanges) {
+      if (actualPageNo >= range.startPage && actualPageNo <= range.endPage) {
+        if (range.startPage > bestStartPage) {
+          bestStartPage = range.startPage;
+          bestMatch = chapterId;
+        }
+      }
+    }
+    return bestMatch;
+  }
+  /**
+   * Assign text blocks to chapters based on page ranges
+   */
+  assignTextBlocks(chapters, textBlocks, chapterRanges, pageRangeMap) {
+    const chapterMap = this.buildChapterMap(chapters);
+    for (const textBlock of textBlocks) {
+      const actualPageNo = this.pdfPageToActualPage(
+        textBlock.pdfPageNo,
+        pageRangeMap
+      );
+      const chapterId = this.findChapterForPage(actualPageNo, chapterRanges);
+      if (chapterId && chapterMap.has(chapterId)) {
+        chapterMap.get(chapterId).textBlocks.push(textBlock);
+      }
+    }
+  }
+  /**
+   * Link images, tables, and footnotes to chapters based on page ranges
+   */
+  linkResources(chapters, images, tables, footnotes, chapterRanges, pageRangeMap) {
+    const chapterMap = this.buildChapterMap(chapters);
+    for (const image of images) {
+      const actualPageNo = this.pdfPageToActualPage(
+        image.pdfPageNo,
+        pageRangeMap
+      );
+      const chapterId = this.findChapterForPage(actualPageNo, chapterRanges);
+      if (chapterId && chapterMap.has(chapterId)) {
+        chapterMap.get(chapterId).imageIds.push(image.id);
+      }
+    }
+    for (const table of tables) {
+      const actualPageNo = this.pdfPageToActualPage(
+        table.pdfPageNo,
+        pageRangeMap
+      );
+      const chapterId = this.findChapterForPage(actualPageNo, chapterRanges);
+      if (chapterId && chapterMap.has(chapterId)) {
+        chapterMap.get(chapterId).tableIds.push(table.id);
+      }
+    }
+    for (const footnote of footnotes) {
+      const actualPageNo = this.pdfPageToActualPage(
+        footnote.pdfPageNo,
+        pageRangeMap
+      );
+      const chapterId = this.findChapterForPage(actualPageNo, chapterRanges);
+      if (chapterId && chapterMap.has(chapterId)) {
+        chapterMap.get(chapterId).footnoteIds.push(footnote.id);
+      }
+    }
+  }
+  /**
+   * Build flat chapter map for O(1) lookup
+   */
+  buildChapterMap(chapters) {
+    const map = /* @__PURE__ */ new Map();
+    const addToMap = (chapterList) => {
+      for (const chapter of chapterList) {
+        map.set(chapter.id, chapter);
+        if (chapter.children && chapter.children.length > 0) {
+          addToMap(chapter.children);
+        }
+      }
+    };
+    addToMap(chapters);
+    return map;
+  }
+};
+
+// src/extractors/toc-extract-error.ts
+var TocExtractError = class _TocExtractError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "TocExtractError";
+  }
+  /**
+   * Extract error message from unknown error type
+   */
+  static getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+  /**
+   * Create TocExtractError from unknown error with context
+   */
+  static fromError(context, error) {
+    return new _TocExtractError(
+      `${context}: ${_TocExtractError.getErrorMessage(error)}`,
+      { cause: error }
+    );
+  }
+};
+var TocNotFoundError = class extends TocExtractError {
+  constructor(message = "Table of contents not found in the document") {
+    super(message);
+    this.name = "TocNotFoundError";
+  }
+};
+var TocParseError = class extends TocExtractError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "TocParseError";
+  }
+};
+var TocValidationError = class extends TocExtractError {
+  /**
+   * Validation result with detailed issues
+   */
+  validationResult;
+  constructor(message, validationResult) {
+    super(message);
+    this.name = "TocValidationError";
+    this.validationResult = validationResult;
+  }
+  /**
+   * Get formatted error summary
+   */
+  getSummary() {
+    const { errorCount, issues } = this.validationResult;
+    const lines = [
+      `TOC validation failed: ${errorCount} error(s)`,
+      "",
+      "Issues:"
+    ];
+    for (const issue of issues) {
+      lines.push(`  [${issue.code}] ${issue.message}`);
+      lines.push(`    Path: ${issue.path}`);
+      lines.push(
+        `    Entry: "${issue.entry.title}" (page ${issue.entry.pageNo})`
+      );
+    }
+    return lines.join("\n");
+  }
+};
+
+// src/extractors/toc-validator.ts
+var DEFAULT_OPTIONS = {
+  totalPages: Infinity,
+  maxTitleLength: 200
+};
+var TocValidator = class {
+  options;
+  issues;
+  constructor(options) {
+    this.options = {
+      ...DEFAULT_OPTIONS,
+      ...options
+    };
+    this.issues = [];
+  }
+  /**
+   * Validate TocEntry array
+   *
+   * @param entries - TOC entries to validate
+   * @returns Validation result
+   */
+  validate(entries) {
+    this.issues = [];
+    this.validateEntries(entries, "", null, /* @__PURE__ */ new Set());
+    const errorCount = this.issues.length;
+    return {
+      valid: errorCount === 0,
+      issues: [...this.issues],
+      errorCount
+    };
+  }
+  /**
+   * Validate and throw if invalid
+   *
+   * @param entries - TOC entries to validate
+   * @throws {TocValidationError} When validation fails
+   */
+  validateOrThrow(entries) {
+    const result = this.validate(entries);
+    if (!result.valid) {
+      throw new TocValidationError(
+        `TOC validation failed with ${result.errorCount} error(s)`,
+        result
+      );
+    }
+  }
+  /**
+   * Recursively validate entries
+   */
+  validateEntries(entries, parentPath, parentEntry, seenKeys) {
+    let prevPageNo = parentEntry?.pageNo ?? 0;
+    for (let i = 0; i < entries.length; i++) {
+      const entry = entries[i];
+      const path4 = parentPath ? `${parentPath}.children[${i}]` : `[${i}]`;
+      this.validateTitle(entry, path4);
+      this.validateTitleLength(entry, path4);
+      this.validatePageRange(entry, path4);
+      this.validatePageOrder(entry, path4, prevPageNo);
+      prevPageNo = entry.pageNo;
+      if (parentEntry) {
+        this.validateParentChildPage(entry, path4, parentEntry);
+      }
+      const key = `${entry.title}:${entry.pageNo}`;
+      this.validateDuplicate(entry, path4, key, seenKeys);
+      seenKeys.add(key);
+      if (entry.children && entry.children.length > 0) {
+        this.validateEntries(entry.children, path4, entry, seenKeys);
+      }
+    }
+  }
+  /**
+   * V003: Validate title is not empty
+   */
+  validateTitle(entry, path4) {
+    if (!entry.title || entry.title.trim() === "") {
+      this.addIssue({
+        code: "V003",
+        message: "Title is empty or contains only whitespace",
+        path: path4,
+        entry
+      });
+    }
+  }
+  /**
+   * V004: Validate title length
+   */
+  validateTitleLength(entry, path4) {
+    if (entry.title.length > this.options.maxTitleLength) {
+      this.addIssue({
+        code: "V004",
+        message: `Title exceeds ${this.options.maxTitleLength} characters (${entry.title.length})`,
+        path: path4,
+        entry
+      });
+    }
+  }
+  /**
+   * V002: Validate page number range
+   */
+  validatePageRange(entry, path4) {
+    if (entry.pageNo < 1) {
+      this.addIssue({
+        code: "V002",
+        message: `Page number must be >= 1, got ${entry.pageNo}`,
+        path: path4,
+        entry
+      });
+    }
+    if (entry.pageNo > this.options.totalPages) {
+      this.addIssue({
+        code: "V002",
+        message: `Page number ${entry.pageNo} exceeds document total pages (${this.options.totalPages})`,
+        path: path4,
+        entry
+      });
+    }
+  }
+  /**
+   * V001: Validate page order within same level
+   */
+  validatePageOrder(entry, path4, prevPageNo) {
+    if (entry.pageNo < prevPageNo) {
+      this.addIssue({
+        code: "V001",
+        message: `Page number decreased from ${prevPageNo} to ${entry.pageNo}`,
+        path: path4,
+        entry
+      });
+    }
+  }
+  /**
+   * V005: Validate parent-child page relationship
+   */
+  validateParentChildPage(entry, path4, parent) {
+    if (entry.pageNo < parent.pageNo) {
+      this.addIssue({
+        code: "V005",
+        message: `Child page (${entry.pageNo}) is before parent page (${parent.pageNo})`,
+        path: path4,
+        entry
+      });
+    }
+  }
+  /**
+   * V006: Validate no duplicates
+   */
+  validateDuplicate(entry, path4, key, seenKeys) {
+    if (seenKeys.has(key)) {
+      this.addIssue({
+        code: "V006",
+        message: `Duplicate entry: "${entry.title}" at page ${entry.pageNo}`,
+        path: path4,
+        entry
+      });
+    }
+  }
+  /**
+   * Add issue to the list
+   */
+  addIssue(issue) {
+    this.issues.push(issue);
+  }
+};
+
+// src/extractors/toc-finder.ts
+var TOC_KEYWORDS = [
+  "\uBAA9\uCC28",
+  "\uCC28\uB840",
+  "\uBAA9 \uCC28",
+  "\u76EE\u5F55",
+  "\u76EE \u5F55",
+  "\u5185\u5BB9",
+  "\u5167\u5BB9",
+  "\u76EE\u6B21",
+  "\u76EE \u6B21",
+  "Contents",
+  "Table of Contents",
+  "TABLE OF CONTENTS",
+  "CONTENTS"
+];
+var CONTINUATION_MARKERS = [
+  "\uBAA9\uCC28(\uACC4\uC18D)",
+  "\uBAA9\uCC28 (\uACC4\uC18D)",
+  "(\uACC4\uC18D)",
+  "\u76EE\u5F55(\u7EED)",
+  "\u76EE\u5F55 (\u7EED)",
+  "(\u7EED)",
+  "\u7EED\u8868",
+  "\u76EE\u6B21(\u7D9A)",
+  "\u76EE\u6B21 (\u7D9A)",
+  "(\u7D9A)",
+  "(continued)",
+  "(Continued)",
+  "(CONTINUED)",
+  "continued"
+];
+var PAGE_NUMBER_PATTERN = /\.{2,}\s*\d+\s*$|…+\s*\d+\s*$|\s+\d+\s*$/;
+var TocFinder = class {
+  constructor(logger, refResolver, options) {
+    this.logger = logger;
+    this.refResolver = refResolver;
+    this.maxSearchPages = options?.maxSearchPages ?? 10;
+    this.keywords = [...TOC_KEYWORDS, ...options?.additionalKeywords ?? []];
+  }
+  maxSearchPages;
+  keywords;
+  /**
+   * Find TOC area in the document
+   *
+   * @throws {TocNotFoundError} When no TOC area is found
+   */
+  find(doc) {
+    this.logger.info("[TocFinder] Starting TOC search...");
+    const keywordResult = this.findByKeywords(doc);
+    if (keywordResult) {
+      this.logger.info(
+        `[TocFinder] Found TOC by keyword search: pages ${keywordResult.startPage}-${keywordResult.endPage}`
+      );
+      return keywordResult;
+    }
+    const structureResult = this.findByStructure(doc);
+    if (structureResult) {
+      this.logger.info(
+        `[TocFinder] Found TOC by structure analysis: pages ${structureResult.startPage}-${structureResult.endPage}`
+      );
+      return structureResult;
+    }
+    this.logger.warn("[TocFinder] No TOC found in document");
+    throw new TocNotFoundError();
+  }
+  /**
+   * Stage 1: Search by keywords in text items
+   */
+  findByKeywords(doc) {
+    for (const text of doc.texts) {
+      if (!this.containsTocKeyword(text.text)) {
+        continue;
+      }
+      const pageNo = text.prov[0]?.page_no;
+      if (pageNo === void 0 || pageNo > this.maxSearchPages) {
+        continue;
+      }
+      this.logger.info(
+        `[TocFinder] Found TOC keyword "${text.text}" on page ${pageNo}`
+      );
+      const parentRef = text.parent?.$ref;
+      if (!parentRef) {
+        return {
+          itemRefs: [text.self_ref],
+          startPage: pageNo,
+          endPage: pageNo
+        };
+      }
+      const result = this.findTocContainer(doc, parentRef, pageNo);
+      if (result) {
+        return this.expandToConsecutivePages(result, doc);
+      }
+    }
+    return null;
+  }
+  /**
+   * Stage 2: Search by structure (lists/tables with page numbers)
+   */
+  findByStructure(doc) {
+    const candidates = [];
+    for (const group of doc.groups) {
+      const pageNo = this.getGroupFirstPage(group);
+      if (pageNo === void 0 || pageNo > this.maxSearchPages) {
+        continue;
+      }
+      if (this.isGroupTocLike(group, doc)) {
+        const score = this.calculateScore(group, pageNo);
+        candidates.push({
+          result: {
+            itemRefs: [group.self_ref],
+            startPage: pageNo,
+            endPage: pageNo
+          },
+          score
+        });
+      }
+    }
+    for (const table of doc.tables) {
+      const pageNo = table.prov[0]?.page_no;
+      if (pageNo === void 0 || pageNo > this.maxSearchPages) {
+        continue;
+      }
+      if (this.isTableTocLike(table)) {
+        const score = this.calculateTableScore(table, pageNo);
+        candidates.push({
+          result: {
+            itemRefs: [table.self_ref],
+            startPage: pageNo,
+            endPage: pageNo
+          },
+          score
+        });
+      }
+    }
+    if (candidates.length === 0) {
+      return null;
+    }
+    candidates.sort((a, b) => b.score - a.score);
+    const best = candidates[0];
+    return this.expandToConsecutivePages(best.result, doc);
+  }
+  /**
+   * Find the TOC container (group or table) from a parent reference
+   */
+  findTocContainer(doc, parentRef, pageNo) {
+    const group = this.refResolver.resolveGroup(parentRef);
+    if (group) {
+      return {
+        itemRefs: [group.self_ref],
+        startPage: pageNo,
+        endPage: pageNo
+      };
+    }
+    const table = this.refResolver.resolveTable(parentRef);
+    if (table) {
+      return {
+        itemRefs: [table.self_ref],
+        startPage: pageNo,
+        endPage: pageNo
+      };
+    }
+    const item = this.refResolver.resolve(parentRef);
+    if (item && item.parent?.$ref) {
+      return this.findTocContainer(doc, item.parent.$ref, pageNo);
+    }
+    return null;
+  }
+  /**
+   * Check if a group contains TOC-like structure
+   */
+  isGroupTocLike(group, _doc) {
+    if (group.name !== "list" && group.name !== "group") {
+      return false;
+    }
+    let pageNumberCount = 0;
+    const children = this.refResolver.resolveMany(group.children);
+    for (const child of children) {
+      if (!child) continue;
+      if ("text" in child && "orig" in child) {
+        const textItem = child;
+        if (PAGE_NUMBER_PATTERN.test(textItem.text)) {
+          pageNumberCount++;
+        }
+      }
+    }
+    const total = children.filter((c) => c !== null).length;
+    return pageNumberCount >= 3 || total > 0 && pageNumberCount / total > 0.5;
+  }
+  /**
+   * Check if a table contains TOC-like structure
+   */
+  isTableTocLike(table) {
+    if (table.label === "document_index") {
+      return true;
+    }
+    const { grid, num_rows, num_cols } = table.data;
+    if (num_rows < 3 || num_cols < 2) {
+      return false;
+    }
+    let numberCount = 0;
+    for (let row = 1; row < grid.length; row++) {
+      const lastCell = grid[row]?.[num_cols - 1];
+      if (lastCell && /^\d+$/.test(lastCell.text.trim())) {
+        numberCount++;
+      }
+    }
+    return numberCount > 0 && numberCount / (num_rows - 1) > 0.5;
+  }
+  /**
+   * Expand TOC area to consecutive pages
+   */
+  expandToConsecutivePages(initial, doc) {
+    const itemRefs = [...initial.itemRefs];
+    let endPage = initial.endPage;
+    for (let pageNo = initial.endPage + 1; pageNo <= this.maxSearchPages; pageNo++) {
+      const continuationItems = this.findContinuationOnPage(doc, pageNo);
+      if (continuationItems.length === 0) {
+        break;
+      }
+      itemRefs.push(...continuationItems);
+      endPage = pageNo;
+    }
+    return {
+      itemRefs,
+      startPage: initial.startPage,
+      endPage
+    };
+  }
+  /**
+   * Find TOC continuation items on a specific page
+   */
+  findContinuationOnPage(doc, pageNo) {
+    const refs = [];
+    for (const text of doc.texts) {
+      if (text.prov[0]?.page_no !== pageNo) {
+        continue;
+      }
+      if (this.hasContinuationMarker(text.text)) {
+        const parentRef = text.parent?.$ref;
+        if (parentRef) {
+          const group = this.refResolver.resolveGroup(parentRef);
+          if (group) {
+            refs.push(group.self_ref);
+          }
+        }
+      }
+    }
+    for (const group of doc.groups) {
+      const groupPage = this.getGroupFirstPage(group);
+      if (groupPage !== pageNo) {
+        continue;
+      }
+      if (this.isGroupTocLike(group, doc) && !refs.includes(group.self_ref)) {
+        refs.push(group.self_ref);
+      }
+    }
+    for (const table of doc.tables) {
+      if (table.prov[0]?.page_no !== pageNo) {
+        continue;
+      }
+      if (this.isTableTocLike(table) && !refs.includes(table.self_ref)) {
+        refs.push(table.self_ref);
+      }
+    }
+    return refs;
+  }
+  /**
+   * Check if text contains TOC keyword
+   */
+  containsTocKeyword(text) {
+    const normalizedText = text.trim().toLowerCase();
+    return this.keywords.some(
+      (keyword) => normalizedText.includes(keyword.toLowerCase())
+    );
+  }
+  /**
+   * Check for continuation markers
+   */
+  hasContinuationMarker(text) {
+    const normalizedText = text.trim().toLowerCase();
+    return CONTINUATION_MARKERS.some(
+      (marker) => normalizedText.includes(marker.toLowerCase())
+    );
+  }
+  /**
+   * Get first page number of a group by checking its children
+   */
+  getGroupFirstPage(group) {
+    for (const childRef of group.children) {
+      const child = this.refResolver.resolve(childRef.$ref);
+      if (child && "prov" in child) {
+        const prov = child.prov;
+        if (prov && prov[0]?.page_no !== void 0) {
+          return prov[0].page_no;
+        }
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Calculate score for a group candidate
+   * Higher score = better match
+   */
+  calculateScore(group, pageNo) {
+    let score = 0;
+    score += (this.maxSearchPages - pageNo + 1) * 10;
+    score += group.children.length * 2;
+    const children = this.refResolver.resolveMany(group.children);
+    for (const child of children) {
+      if (child && "text" in child) {
+        const textItem = child;
+        if (PAGE_NUMBER_PATTERN.test(textItem.text)) {
+          score += 5;
+        }
+      }
+    }
+    return score;
+  }
+  /**
+   * Calculate score for a table candidate
+   */
+  calculateTableScore(table, pageNo) {
+    let score = 0;
+    score += (this.maxSearchPages - pageNo + 1) * 10;
+    score += table.data.num_rows * 2;
+    if (table.label === "document_index") {
+      score += 50;
+    }
+    return score;
+  }
+};
+
+// src/extractors/toc-extractor.ts
+import { z } from "zod";
+
+// src/core/base-llm-component.ts
+var BaseLLMComponent = class {
+  logger;
+  model;
+  fallbackModel;
+  maxRetries;
+  temperature;
+  componentName;
+  aggregator;
+  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, model, componentName, options, fallbackModel, aggregator) {
+    this.logger = logger;
+    this.model = model;
+    this.componentName = componentName;
+    this.maxRetries = options?.maxRetries ?? 3;
+    this.temperature = options?.temperature ?? 0;
+    this.fallbackModel = fallbackModel;
+    this.aggregator = aggregator;
+    this.abortSignal = options?.abortSignal;
+  }
+  /**
+   * 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
+   */
+  log(level, message, ...args) {
+    const formattedMessage = `[${this.componentName}] ${message}`;
+    this.logger[level](formattedMessage, ...args);
+  }
+  /**
+   * Track token usage to aggregator if available
+   *
+   * @param usage - Token usage information to track
+   */
+  trackUsage(usage) {
+    if (this.aggregator) {
+      this.aggregator.track(usage);
+    }
+  }
+  /**
+   * Create an empty usage record for edge cases (e.g., empty input)
+   *
+   * @param phase - Phase name for the usage record
+   * @returns Empty ExtendedTokenUsage object
+   */
+  createEmptyUsage(phase) {
+    return {
+      component: this.componentName,
+      phase,
+      model: "primary",
+      modelName: "none",
+      inputTokens: 0,
+      outputTokens: 0,
+      totalTokens: 0
+    };
+  }
+};
+
+// src/core/text-llm-component.ts
+var TextLLMComponent = class extends BaseLLMComponent {
+  constructor(logger, model, componentName, options, fallbackModel, aggregator) {
+    super(logger, model, componentName, options, fallbackModel, aggregator);
+  }
+  /**
+   * 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
+   */
+  async callTextLLM(schema, systemPrompt, userPrompt, phase) {
+    const result = await LLMCaller.call({
+      schema,
+      systemPrompt,
+      userPrompt,
+      primaryModel: this.model,
+      fallbackModel: this.fallbackModel,
+      maxRetries: this.maxRetries,
+      temperature: this.temperature,
+      abortSignal: this.abortSignal,
+      component: this.componentName,
+      phase
+    });
+    this.trackUsage(result.usage);
+    return {
+      output: result.output,
+      usage: result.usage
+    };
+  }
+};
+
+// src/extractors/toc-extractor.ts
+var TocEntrySchema = z.lazy(
+  () => z.object({
+    title: z.string().describe("Chapter or section title"),
+    level: z.number().int().min(1).describe("Hierarchy depth (1 = top level)"),
+    pageNo: z.number().int().min(1).describe("Starting page number"),
+    children: z.array(TocEntrySchema).optional().describe("Child sections")
+  })
+);
+var TocResponseSchema = z.object({
+  entries: z.array(TocEntrySchema).describe("Extracted TOC entries")
+});
+var TocExtractor = class extends TextLLMComponent {
+  validationOptions;
+  skipValidation;
+  constructor(logger, model, options, fallbackModel, abortSignal) {
+    super(
+      logger,
+      model,
+      "TocExtractor",
+      { ...options, abortSignal },
+      fallbackModel
+    );
+    this.validationOptions = options?.validation;
+    this.skipValidation = options?.skipValidation ?? false;
+  }
+  /**
+   * Extract TOC structure from Markdown
+   *
+   * @param markdown - Markdown representation of TOC area
+   * @returns Object with entries array and token usage information
+   * @throws {TocParseError} When LLM fails to parse structure
+   * @throws {TocValidationError} When validation fails
+   */
+  async extract(markdown) {
+    this.log("info", `Starting TOC extraction (${markdown.length} chars)`);
+    if (!markdown.trim()) {
+      this.log("info", "Empty markdown, returning empty array");
+      return {
+        entries: [],
+        usage: this.createEmptyUsage("extraction")
+      };
+    }
+    try {
+      const result = await this.callTextLLM(
+        TocResponseSchema,
+        this.buildSystemPrompt(),
+        this.buildUserPrompt(markdown),
+        "extraction"
+      );
+      const entries = this.normalizeEntries(result.output.entries);
+      if (!this.skipValidation) {
+        this.validateEntries(entries);
+      }
+      this.log(
+        "info",
+        `Extraction completed: ${entries.length} top-level entries`
+      );
+      return { entries, usage: result.usage };
+    } catch (error) {
+      if (error instanceof TocValidationError) {
+        this.log("error", `Validation failed: ${error.message}`);
+        throw error;
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      this.log("error", `Extraction failed: ${message}`);
+      throw new TocParseError(`Failed to extract TOC structure: ${message}`, {
+        cause: error
+      });
+    }
+  }
+  /**
+   * Validate extracted entries
+   *
+   * @throws {TocValidationError} When validation fails
+   */
+  validateEntries(entries) {
+    if (entries.length === 0) {
+      return;
+    }
+    const validator = new TocValidator(this.validationOptions);
+    validator.validateOrThrow(entries);
+  }
+  /**
+   * Build system prompt for TOC extraction
+   */
+  buildSystemPrompt() {
+    return `You are a document structure extraction assistant. Your task is to parse a table of contents (TOC) from markdown format and extract structured entries.
+
+## Instructions
+
+1. **Title**: Extract the exact chapter/section title from each line. Remove page number indicators like "..... 10" or "... 5" at the end.
+
+2. **Level**: Determine the hierarchy depth:
+   - Level 1: Top-level chapters (e.g., "\uC81C1\uC7A5", "Chapter 1", "I.", "Part 1")
+   - Level 2: Main sections within chapters (e.g., "1.", "1.1", "A.")
+   - Level 3: Subsections (e.g., "1.1.1", "a.", "(1)")
+   - Use indentation and numbering patterns to infer level
+
+3. **Page Number**: Extract the page number from each entry. Convert Roman numerals to Arabic numerals if present (e.g., "iv" \u2192 4).
+
+4. **Children**: Nest child entries under parent entries based on their hierarchy level.
+
+5. **IMPORTANT - Extract Main TOC Only**: Only extract the main document table of contents. EXCLUDE the following supplementary indices:
+   - Photo/image indices (\uC0AC\uC9C4 \uBAA9\uCC28, \uC0AC\uC9C4\uBAA9\uCC28, \uD654\uBCF4 \uBAA9\uCC28, Photo Index, List of Photos, List of Figures)
+   - Drawing/diagram indices (\uB3C4\uBA74 \uBAA9\uCC28, \uB3C4\uBA74\uBAA9\uCC28, \uC0BD\uB3C4 \uBAA9\uCC28, Drawing Index, List of Drawings)
+   - Table indices (\uD45C \uBAA9\uCC28, \uD45C\uBAA9\uCC28, Table Index, List of Tables)
+   - Appendix indices (\uBD80\uB85D \uBAA9\uCC28, Appendix Index)
+   - Any other supplementary material indices
+
+## Output Format
+
+Return a flat array of top-level entries. Each entry at level 1 should contain its children (level 2+) nested properly.
+
+## Example
+
+Input:
+- \uC81C1\uC7A5 \uC11C\uB860 ..... 1
+  - 1. \uC5F0\uAD6C \uBC30\uACBD ..... 3
+  - 2. \uC5F0\uAD6C \uBAA9\uC801 ..... 5
+- \uC81C2\uC7A5 \uBC29\uBC95\uB860 ..... 10
+
+Output:
+{
+  "entries": [
+    {
+      "title": "\uC81C1\uC7A5 \uC11C\uB860",
+      "level": 1,
+      "pageNo": 1,
+      "children": [
+        { "title": "1. \uC5F0\uAD6C \uBC30\uACBD", "level": 2, "pageNo": 3 },
+        { "title": "2. \uC5F0\uAD6C \uBAA9\uC801", "level": 2, "pageNo": 5 }
+      ]
+    },
+    { "title": "\uC81C2\uC7A5 \uBC29\uBC95\uB860", "level": 1, "pageNo": 10 }
+  ]
+}`;
+  }
+  /**
+   * Build user prompt with Markdown content
+   */
+  buildUserPrompt(markdown) {
+    return `Extract the table of contents structure from the following markdown:
+
+${markdown}`;
+  }
+  /**
+   * Normalize and validate extracted entries
+   */
+  normalizeEntries(entries) {
+    if (entries.length === 0) {
+      return [];
+    }
+    return this.normalizeLevel(entries, 1);
+  }
+  /**
+   * Recursively ensure level consistency
+   *
+   * Children must have level = parent.level + 1
+   */
+  normalizeLevel(entries, expectedLevel) {
+    return entries.map((entry) => {
+      const normalizedEntry = {
+        title: entry.title.trim(),
+        level: expectedLevel,
+        pageNo: entry.pageNo
+      };
+      if (entry.children && entry.children.length > 0) {
+        normalizedEntry.children = this.normalizeLevel(
+          entry.children,
+          expectedLevel + 1
+        );
+      }
+      return normalizedEntry;
+    });
+  }
+};
+
+// src/extractors/vision-toc-extractor.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+import { z as z2 } from "zod";
+
+// src/core/vision-llm-component.ts
+import * as fs from "fs";
+import * as path from "path";
+var VisionLLMComponent = class extends BaseLLMComponent {
+  outputPath;
+  constructor(logger, model, componentName, outputPath, options, fallbackModel, aggregator) {
+    super(logger, model, componentName, options, fallbackModel, aggregator);
+    this.outputPath = outputPath;
+  }
+  /**
+   * 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
+   */
+  async callVisionLLM(schema, messages, phase) {
+    const result = await LLMCaller.callVision({
+      schema,
+      messages,
+      primaryModel: this.model,
+      fallbackModel: this.fallbackModel,
+      maxRetries: this.maxRetries,
+      temperature: this.temperature,
+      abortSignal: this.abortSignal,
+      component: this.componentName,
+      phase
+    });
+    this.trackUsage(result.usage);
+    return {
+      output: result.output,
+      usage: result.usage
+    };
+  }
+  /**
+   * Load an image file and encode it as base64
+   *
+   * @param imagePath - Absolute path to the image file
+   * @returns Base64 encoded image string
+   */
+  loadImageAsBase64(imagePath) {
+    const imageBuffer = fs.readFileSync(imagePath);
+    return imageBuffer.toString("base64");
+  }
+  /**
+   * Build image content object for vision LLM messages
+   *
+   * @param imagePath - Path to the image file (relative to outputPath or absolute)
+   * @param mimeType - MIME type of the image (default: 'image/png')
+   * @returns ImageContent object for LLM message
+   */
+  buildImageContent(imagePath, mimeType = "image/png") {
+    const absolutePath = path.isAbsolute(imagePath) ? imagePath : path.resolve(this.outputPath, imagePath);
+    const base64Image = this.loadImageAsBase64(absolutePath);
+    return {
+      type: "image",
+      image: `data:${mimeType};base64,${base64Image}`
+    };
+  }
+};
+
+// src/extractors/vision-toc-extractor.ts
+var VisionTocExtractionSchema = z2.object({
+  hasToc: z2.boolean().describe("Whether a TOC is visible on these pages"),
+  tocMarkdown: z2.string().nullable().describe("Extracted TOC in markdown format, null if not found"),
+  continuesOnNextPage: z2.boolean().describe("Whether TOC continues beyond these pages")
+});
+var VisionTocExtractor = class extends VisionLLMComponent {
+  firstBatchSize;
+  secondBatchSize;
+  constructor(logger, model, outputPath, options, fallbackModel, aggregator) {
+    super(
+      logger,
+      model,
+      "VisionTocExtractor",
+      outputPath,
+      options,
+      fallbackModel,
+      aggregator ?? new LLMTokenUsageAggregator()
+    );
+    this.firstBatchSize = options?.firstBatchSize ?? 10;
+    this.secondBatchSize = options?.secondBatchSize ?? 10;
+  }
+  /**
+   * 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
+   */
+  async extract(totalPages) {
+    this.log("info", `Starting TOC extraction from ${totalPages} pages`);
+    if (totalPages === 0) {
+      this.log("info", "No pages to search");
+      return null;
+    }
+    const firstBatchEnd = Math.min(this.firstBatchSize, totalPages);
+    this.log("info", `Searching first batch: pages 1-${firstBatchEnd}`);
+    const firstResult = await this.extractFromBatch(1, firstBatchEnd);
+    if (firstResult.hasToc && firstResult.tocMarkdown) {
+      if (firstResult.continuesOnNextPage && firstBatchEnd < totalPages) {
+        this.log("info", "TOC continues on next pages, extracting more");
+        const continuationEnd = Math.min(
+          firstBatchEnd + this.secondBatchSize,
+          totalPages
+        );
+        const continuationResult = await this.extractFromBatch(
+          firstBatchEnd + 1,
+          continuationEnd
+        );
+        if (continuationResult.hasToc && continuationResult.tocMarkdown) {
+          const merged = this.mergeMarkdown(
+            firstResult.tocMarkdown,
+            continuationResult.tocMarkdown
+          );
+          this.aggregator.logSummary(this.logger);
+          this.log(
+            "info",
+            `TOC extracted with continuation (${merged.length} chars)`
+          );
+          return merged;
+        }
+      }
+      this.aggregator.logSummary(this.logger);
+      this.log(
+        "info",
+        `TOC found in first batch (${firstResult.tocMarkdown.length} chars)`
+      );
+      return firstResult.tocMarkdown;
+    }
+    if (firstBatchEnd < totalPages) {
+      const secondBatchStart = firstBatchEnd + 1;
+      const secondBatchEnd = Math.min(
+        firstBatchEnd + this.secondBatchSize,
+        totalPages
+      );
+      this.log(
+        "info",
+        `Searching second batch: pages ${secondBatchStart}-${secondBatchEnd}`
+      );
+      const secondResult = await this.extractFromBatch(
+        secondBatchStart,
+        secondBatchEnd
+      );
+      if (secondResult.hasToc && secondResult.tocMarkdown) {
+        this.aggregator.logSummary(this.logger);
+        this.log(
+          "info",
+          `TOC found in second batch (${secondResult.tocMarkdown.length} chars)`
+        );
+        return secondResult.tocMarkdown;
+      }
+    }
+    this.aggregator.logSummary(this.logger);
+    this.log("info", "TOC not found in any batch");
+    return null;
+  }
+  /**
+   * Extract TOC from a specific batch of pages
+   */
+  async extractFromBatch(startPage, endPage) {
+    this.log("info", `Extracting from pages ${startPage}-${endPage}`);
+    const imageContents = this.loadPageImages(startPage, endPage);
+    const result = await LLMCaller.callVision({
+      schema: VisionTocExtractionSchema,
+      messages: [
+        {
+          role: "user",
+          content: [
+            {
+              type: "text",
+              text: this.buildUserPrompt(startPage, endPage)
+            },
+            ...imageContents
+          ]
+        }
+      ],
+      primaryModel: this.model,
+      fallbackModel: this.fallbackModel,
+      maxRetries: this.maxRetries,
+      temperature: this.temperature,
+      abortSignal: this.abortSignal,
+      component: "VisionTocExtractor",
+      phase: "extraction"
+    });
+    this.trackUsage(result.usage);
+    return result.output;
+  }
+  /**
+   * Load page images and build message content
+   */
+  loadPageImages(startPage, endPage) {
+    const imageContents = [];
+    for (let pageNo = startPage; pageNo <= endPage; pageNo++) {
+      const imagePath = path2.resolve(
+        this.outputPath,
+        `pages/page_${pageNo - 1}.png`
+      );
+      const imageBuffer = fs2.readFileSync(imagePath);
+      const base64Image = imageBuffer.toString("base64");
+      imageContents.push({
+        type: "image",
+        image: `data:image/png;base64,${base64Image}`
+      });
+    }
+    return imageContents;
+  }
+  /**
+   * Merge markdown from multiple batches
+   */
+  mergeMarkdown(first, continuation) {
+    return `${first.trim()}
+${continuation.trim()}`;
+  }
+  /**
+   * Build system prompt for vision LLM (not used, but required by abstract class)
+   */
+  buildSystemPrompt() {
+    return "";
+  }
+  /**
+   * Build user prompt with page range information
+   */
+  buildUserPrompt(startPage, endPage) {
+    const pageCount = endPage - startPage + 1;
+    return `You are a document analysis specialist. Your task is to find and extract the Table of Contents (TOC) from document page images.
+
+I am providing ${pageCount} document page images (pages ${startPage}-${endPage}).
+
+## Where to Look for TOC:
+- TOC typically appears in the first 10-20 pages of a document
+- Look for pages with headings like "\uBAA9\uCC28", "\uCC28\uB840", "Contents", "Table of Contents"
+- Look for structured lists with chapter titles and page numbers
+
+## What to Extract:
+Extract the TOC content as markdown format that matches this exact structure:
+- Use "- " prefix for each list item
+- Use 2-space indentation for hierarchy levels
+- Include "..... " followed by page number at the end of each entry
+- Preserve original chapter/section numbering from the document
+
+## Output Format Example:
+\`\`\`
+- \uC81C1\uC7A5 \uC11C\uB860 ..... 1
+  - 1. \uC5F0\uAD6C \uBC30\uACBD ..... 3
+  - 2. \uC5F0\uAD6C \uBAA9\uC801 ..... 5
+- \uC81C2\uC7A5 \uC5F0\uAD6C \uBC29\uBC95 ..... 10
+  - 1. \uC870\uC0AC \uC9C0\uC5ED ..... 10
+  - 2. \uC870\uC0AC \uBC29\uBC95 ..... 15
+- \uC81C3\uC7A5 \uC5F0\uAD6C \uACB0\uACFC ..... 25
+\`\`\`
+
+## Important Rules:
+1. Extract ONLY the main document TOC
+2. DO NOT include supplementary indices:
+   - Photo indices (\uC0AC\uC9C4 \uBAA9\uCC28, \uC0AC\uC9C4\uBAA9\uCC28)
+   - Table indices (\uD45C \uBAA9\uCC28, \uD45C\uBAA9\uCC28)
+   - Figure indices (\uB3C4\uBA74 \uBAA9\uCC28, \uB3C4\uBA74\uBAA9\uCC28)
+3. If no TOC is found, set hasToc to false and tocMarkdown to null
+4. Set continuesOnNextPage to true if the TOC appears to continue beyond the visible pages
+
+Please examine these pages and:
+1. Determine if any page contains a Table of Contents (TOC)
+2. If found, extract the complete TOC in markdown format
+3. Indicate if the TOC continues beyond these pages
+
+Remember: Extract the main document TOC only. Ignore photo/table/figure indices.`;
+  }
+};
+
+// src/parsers/caption-parser.ts
+import { z as z3 } from "zod";
+var CaptionSingleSchema = z3.object({
+  num: z3.string().nullable().describe('Extracted caption prefix + number (e.g., "\uB3C4\uD310 1", "Figure 2")')
+});
+var CaptionExtractionSchema = z3.object({
+  index: z3.number().int().describe("Index of the caption in the input array"),
+  num: z3.string().nullable().describe('Extracted caption prefix + number (e.g., "\uB3C4\uD310 1", "Figure 2")')
+});
+var CaptionBatchSchema = z3.object({
+  results: z3.array(CaptionExtractionSchema)
+});
+var CaptionParser = class extends TextLLMComponent {
+  constructor(logger, model, options, fallbackModel, aggregator) {
+    super(
+      logger,
+      model,
+      options?.componentName ?? "CaptionParser",
+      options,
+      fallbackModel,
+      aggregator ?? new 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)
+   */
+  async parseBatch(captions, batchSize, overrideModel) {
+    const effectiveModel = overrideModel ?? this.model;
+    const isOverride = overrideModel !== void 0;
+    const modelName = effectiveModel.modelId ?? effectiveModel.id ?? "unknown";
+    this.log(
+      "info",
+      `Starting caption parsing for ${captions.length} captions with ${isOverride ? "override " : ""}model: ${modelName}`
+    );
+    if (captions.length === 0) {
+      this.log("info", "No captions to parse");
+      return [];
+    }
+    try {
+      if (batchSize === 0) {
+        this.log("info", "Using sequential processing (batchSize=0)");
+        const results2 = [];
+        for (let i = 0; i < captions.length; i++) {
+          const fullText = captions[i];
+          this.log("info", `Processing ${i + 1} / ${captions.length}...`);
+          const result = await LLMCaller.call({
+            schema: CaptionSingleSchema,
+            systemPrompt: this.buildSystemPrompt("single"),
+            userPrompt: this.buildUserPromptSingle(fullText),
+            primaryModel: effectiveModel,
+            fallbackModel: this.fallbackModel,
+            maxRetries: this.maxRetries,
+            temperature: this.temperature,
+            abortSignal: this.abortSignal,
+            component: this.componentName,
+            phase: "caption-extraction"
+          });
+          this.trackUsage(result.usage);
+          const finalNum = this.extractNumFromFullText(
+            fullText,
+            result.output.num
+          );
+          results2.push({ fullText, num: finalNum });
+        }
+        this.aggregator.logSummary(this.logger);
+        this.log(
+          "info",
+          `Completed: ${results2.length} captions parsed, ${results2.filter((r) => r.num).length} with extracted numbers`
+        );
+        return results2;
+      }
+      const indexedCaptions = captions.map((text, index) => ({ index, text }));
+      const batchResults = await BatchProcessor.processBatch(
+        indexedCaptions,
+        batchSize,
+        async (batch) => this.parseBatchInternal(batch, effectiveModel)
+      );
+      batchResults.sort((a, b) => a.index - b.index);
+      const results = batchResults.map((r) => r.caption);
+      this.aggregator.logSummary(this.logger);
+      this.log(
+        "info",
+        `Completed: ${results.length} captions parsed, ${results.filter((r) => r.num).length} with extracted numbers`
+      );
+      return results;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.log("error", `Parsing failed: ${message}`);
+      throw new CaptionParseError(`Failed to parse captions: ${message}`, {
+        cause: error
+      });
+    }
+  }
+  /**
+   * 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
+   */
+  async parseBatchInternal(captions, model) {
+    const result = await LLMCaller.call({
+      schema: CaptionBatchSchema,
+      systemPrompt: this.buildSystemPrompt(),
+      userPrompt: this.buildUserPrompt(captions),
+      primaryModel: model,
+      fallbackModel: this.fallbackModel,
+      maxRetries: this.maxRetries,
+      temperature: this.temperature,
+      abortSignal: this.abortSignal,
+      component: this.componentName,
+      phase: "caption-extraction"
+    });
+    this.trackUsage(result.usage);
+    if (result.output.results.length !== captions.length) {
+      this.log(
+        "warn",
+        `LLM returned ${result.output.results.length} results for ${captions.length} captions. This may cause index mismatch.`
+      );
+    }
+    const captionMap = new Map(captions.map((c) => [c.index, c.text]));
+    return result.output.results.map((resultItem) => {
+      const originalCaption = captions[resultItem.index];
+      const originalIndex = originalCaption?.index ?? resultItem.index;
+      const fullText = captionMap.get(originalIndex) || "";
+      const finalNum = this.extractNumFromFullText(fullText, resultItem.num);
+      return {
+        index: originalIndex,
+        caption: {
+          fullText,
+          num: finalNum
+        }
+      };
+    });
+  }
+  /**
+   * 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
+   */
+  extractNumFromFullText(fullText, extractedNum) {
+    if (!extractedNum) return void 0;
+    let matchIndex = fullText.indexOf(extractedNum);
+    if (matchIndex === -1) {
+      const lowerFullText = fullText.toLowerCase();
+      const lowerNum = extractedNum.toLowerCase();
+      matchIndex = lowerFullText.indexOf(lowerNum);
+      if (matchIndex !== -1) {
+        return fullText.substring(matchIndex, matchIndex + extractedNum.length);
+      }
+      return extractedNum;
+    }
+    return fullText.substring(matchIndex, matchIndex + extractedNum.length);
+  }
+  /**
+   * Build system prompt for caption parsing
+   *
+   * @param mode - 'batch' for multiple captions, 'single' for single caption
+   */
+  buildSystemPrompt(mode = "batch") {
+    const intro = mode === "batch" ? 'Extract the caption prefix and number (e.g., "\uB3C4\uD310 1", "Figure 2") from image/table captions.\nReturn the prefix + number part as a string, or null if no number exists.' : 'Extract the caption prefix and number (e.g., "\uB3C4\uD310 1", "Figure 2") from an image/table caption.\nReturn the prefix + number part as a string, or null if no number exists.';
+    return `You are a caption prefix extractor for archaeological excavation reports.
+
+${intro}
+
+Rules:
+1. Extract if the text follows a caption pattern: <prefix word(s)> <number>
+   - The prefix can be ANY Korean/English word(s) that label images/tables/figures
+   - Common examples: \uB3C4\uD310, \uC0AC\uC9C4, \uADF8\uB9BC, \uB3C4\uBA74, \uD45C, \uC6D0\uC0C9\uC0AC\uC9C4, \uD751\uBC31\uC0AC\uC9C4, Figure, Photo, Plate, etc.
+   - The key is the PATTERN (text followed by number), not a specific word list
+   - "\uC6D0\uC0C9\uC0AC\uC9C4 1. \uC870\uC0AC\uC9C0\uC5ED" \u2192 "\uC6D0\uC0C9\uC0AC\uC9C4 1" (valid: prefix + number pattern)
+   - "\uD751\uBC31\uC0AC\uC9C4 2 \uCD9C\uD1A0\uC720\uBB3C" \u2192 "\uD751\uBC31\uC0AC\uC9C4 2" (valid: prefix + number pattern)
+2. IGNORE leading punctuation/brackets when extracting:
+   - "(\uC0AC\uC9C4 16> \uB290\uD2F0\uB098\uBB34" \u2192 "\uC0AC\uC9C4 16" (ignore leading '(' and extract the pattern inside)
+   - "<\uB3C4\uD310 1> \uC720\uC801" \u2192 "\uB3C4\uD310 1" (ignore angle brackets)
+   - "[\uADF8\uB9BC 2] \uC804\uACBD" \u2192 "\uADF8\uB9BC 2" (ignore square brackets)
+3. Do NOT extract (return null) if:
+   - It's a numbered list item starting with just a number: "1. \uC720\uC801 \uC804\uACBD" \u2192 null
+   - It's a date/time reference: "39 3\uC6D4 28\uC77C..." \u2192 null
+   - It's a year reference: "2024\uB144 \uC870\uC0AC \uD604\uD669" \u2192 null
+   - It starts with a number without a prefix: "123 \uC124\uBA85" \u2192 null
+4. PRESERVE original spacing from the input text exactly (after ignoring leading punctuation)
+5. Include the full number (e.g., "1-2", "3a") not just the first digit
+6. Include period/dot after number if it directly follows (e.g., "3.6" \u2192 "\uB3C4\uD310 3.6")
+   - "\uADF8\uB9BC 3.6. \uD55C\uBC18\uB3C4 \uC911\uBD80" \u2192 "\uADF8\uB9BC 3.6" (period after decimal number included)
+   - "\uB3C4\uD310 2. \uC720\uC801" \u2192 "\uB3C4\uD310 2" (period after space NOT included)
+7. Stop at the first punctuation (except decimal point), whitespace, or underscore after the number
+   - "\uC0AC\uC9C4 1_\u3147\u3147\u3147" \u2192 "\uC0AC\uC9C4 1" (stop at underscore)
+   - "\uC0AC\uC9C4 1 \u3147\u3147\u3147" \u2192 "\uC0AC\uC9C4 1" (stop at space)
+   - "\uADF8\uB9BC 3.6. \uD55C\uBC18\uB3C4" \u2192 "\uADF8\uB9BC 3.6" (period included as decimal separator)
+
+Examples:
+- "\uB3C4\uD310 1 \uC720\uC801 \uC804\uACBD" \u2192 "\uB3C4\uD310 1"
+- "\uC6D0\uC0C9\uC0AC\uC9C4 1. \uC870\uC0AC\uC9C0\uC5ED \uC6D0\uACBD" \u2192 "\uC6D0\uC0C9\uC0AC\uC9C4 1"
+- "\uD751\uBC31\uC0AC\uC9C4 2 \uCD9C\uD1A0\uC720\uBB3C" \u2192 "\uD751\uBC31\uC0AC\uC9C4 2"
+- "(\uC0AC\uC9C4 16> \uB290\uD2F0\uB098\uBB34\uC758 \uC811\uC120\uB2E8\uBA74" \u2192 "\uC0AC\uC9C4 16" (ignore leading punctuation)
+- "<\uB3C4\uD310 3> \uC720\uBB3C \uC0AC\uC9C4" \u2192 "\uB3C4\uD310 3" (ignore angle brackets)
+- "\uB3C4\uD3101 \uC5B4\uCA4C\uAD6C" \u2192 "\uB3C4\uD3101" (no space preserved)
+- "\uC0AC\uC9C4 2. \uCD9C\uD1A0 \uC720\uBB3C" \u2192 "\uC0AC\uC9C4 2" (period after space, not included)
+- "\uADF8\uB9BC 3.6. \uD55C\uBC18\uB3C4 \uC911\uBD80 \uBC0F \uB0A8\uBD80\uC758 \u3147\u3147\u3147" \u2192 "\uADF8\uB9BC 3.6" (period as decimal included)
+- "Figure 3: Site plan" \u2192 "Figure 3"
+- "Table 4a. Artifact list" \u2192 "Table 4a"
+- "\uB3C4\uD310 5-2 \uCE35\uC704 \uB2E8\uBA74" \u2192 "\uB3C4\uD310 5-2"
+- "\uC124\uBA85 \uC5C6\uB294 \uC774\uBBF8\uC9C0" \u2192 null
+- "39 3\uC6D4 28\uC77C(\uBC31\uC81C \uB3C4\uB85C\uC720\uAD6C \uB0B4\uBD80 \uC870\uC0AC)" \u2192 null (starts with number, no prefix)
+- "1. \uC720\uAD6C \uD604\uD669" \u2192 null (numbered list, not caption)
+- "2024-05-01 \uCD2C\uC601" \u2192 null (date, not caption)`;
+  }
+  /**
+   * Build user prompt for caption parsing
+   */
+  buildUserPrompt(captions) {
+    const captionList = captions.map((c) => `[${c.index}] ${c.text}`).join("\n");
+    return `Extract caption prefix and number from the following captions:
+
+${captionList}
+
+Return the results as JSON array with "index" (original position) and "num" (extracted prefix + number or null).
+
+Example format:
+[
+  { "index": 0, "num": "\uB3C4\uD310 1" },
+  { "index": 1, "num": "Figure 2" },
+  { "index": 2, "num": null }
+]`;
+  }
+  /**
+   * Build user prompt for single caption parsing
+   */
+  buildUserPromptSingle(caption) {
+    return `Extract caption prefix and number from the following caption:
+
+"${caption}"
+
+CRITICAL: Return ONLY the JSON object directly with a "num" field.
+- DO NOT wrap the JSON in quotes or additional formatting
+- DO NOT output "final:", "result:", or any prefix labels
+- DO NOT wrap in backticks or code blocks
+- Return ONLY valid JSON: { "num": value }
+
+The value must be:
+- A string with the extracted caption prefix + number (e.g., "\uB3C4\uD310 1", "Figure 2")
+- null if no number exists
+
+Valid outputs:
+{ "num": "\uB3C4\uD310 1" }
+{ "num": null }
+
+Invalid outputs (NEVER do these):
+- { "final": "..." } \u274C
+- \`\`\`json { "num": "..." } \`\`\` \u274C
+- "{ "num": "..." }" \u274C
+- { "num": { "value": "..." } } \u274C`;
+  }
+};
+var CaptionParseError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "CaptionParseError";
+  }
+};
+
+// src/parsers/page-range-parse-error.ts
+var PageRangeParseError = class _PageRangeParseError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "PageRangeParseError";
+  }
+  /**
+   * Extract error message from unknown error type
+   */
+  static getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+  /**
+   * Create PageRangeParseError from unknown error with context
+   */
+  static fromError(context, error) {
+    return new _PageRangeParseError(
+      `${context}: ${_PageRangeParseError.getErrorMessage(error)}`,
+      { cause: error }
+    );
+  }
+};
+
+// src/parsers/page-range-parser.ts
+import * as fs3 from "fs";
+import * as path3 from "path";
+import { z as z4 } from "zod";
+var PagePattern = /* @__PURE__ */ ((PagePattern2) => {
+  PagePattern2["SIMPLE_INCREMENT"] = "simple_increment";
+  PagePattern2["DOUBLE_SIDED"] = "double_sided";
+  PagePattern2["OFFSET"] = "offset";
+  PagePattern2["UNKNOWN"] = "unknown";
+  return PagePattern2;
+})(PagePattern || {});
+var PageRangeParser = class extends VisionLLMComponent {
+  // Configuration constants
+  SAMPLE_SIZE = 3;
+  MAX_PATTERN_RETRIES = 6;
+  SIZE_TOLERANCE = 5;
+  constructor(logger, model, outputPath, maxRetries = 3, fallbackModel, aggregator, abortSignal) {
+    super(
+      logger,
+      model,
+      "PageRangeParser",
+      outputPath,
+      { maxRetries, abortSignal },
+      fallbackModel,
+      aggregator ?? new LLMTokenUsageAggregator()
+    );
+  }
+  /**
+   * 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
+   */
+  async parse(doclingDoc) {
+    this.log("info", "Starting page range parsing...");
+    const pages = this.extractPages(doclingDoc);
+    if (pages.length === 0) {
+      this.log("warn", "No pages found");
+      const emptyUsage = this.createEmptyUsage("sampling");
+      this.trackUsage(emptyUsage);
+      return {
+        pageRangeMap: {},
+        usage: [emptyUsage]
+      };
+    }
+    const sizeGroups = this.analyzeSizes(pages);
+    this.log(
+      "info",
+      `Found ${sizeGroups.length} size group(s), total ${pages.length} pages`
+    );
+    const pageRangeMap = {};
+    const usageList = [];
+    for (let i = 0; i < sizeGroups.length; i++) {
+      const group = sizeGroups[i];
+      this.log(
+        "info",
+        `Processing group ${i + 1}/${sizeGroups.length}: ${group.pageNos.length} pages`
+      );
+      const groupResult = await this.processGroup(pages, group, this.model);
+      Object.assign(pageRangeMap, groupResult.pageRangeMap);
+      usageList.push(...groupResult.usage);
+    }
+    for (const usage of usageList) {
+      this.trackUsage(usage);
+    }
+    this.postProcess(pageRangeMap);
+    this.log(
+      "info",
+      `Completed: ${Object.keys(pageRangeMap).length} pages mapped`
+    );
+    return { pageRangeMap, usage: usageList };
+  }
+  /**
+   * Extract pages array from DoclingDocument
+   */
+  extractPages(doclingDoc) {
+    const pageKeys = Object.keys(doclingDoc.pages).map(Number).filter((n) => !Number.isNaN(n)).sort((a, b) => a - b);
+    return pageKeys.map((key) => doclingDoc.pages[String(key)]);
+  }
+  /**
+   * Analyze page sizes and group consecutive pages with same dimensions
+   */
+  analyzeSizes(pages) {
+    const groups = [];
+    let currentGroup = null;
+    for (const page of pages) {
+      const sizeKey = this.createSizeKey(page.size.width, page.size.height);
+      if (!currentGroup || currentGroup.sizeKey !== sizeKey) {
+        currentGroup = { sizeKey, pageNos: [page.page_no] };
+        groups.push(currentGroup);
+      } else {
+        currentGroup.pageNos.push(page.page_no);
+      }
+    }
+    return groups;
+  }
+  /**
+   * Create size key with tolerance for floating point comparison
+   */
+  createSizeKey(width, height) {
+    const roundedWidth = Math.round(width / this.SIZE_TOLERANCE);
+    const roundedHeight = Math.round(height / this.SIZE_TOLERANCE);
+    return `${roundedWidth}x${roundedHeight}`;
+  }
+  /**
+   * Process a single size group
+   */
+  async processGroup(pages, group, model) {
+    const { pageNos } = group;
+    const usageList = [];
+    if (pageNos.length <= this.SAMPLE_SIZE) {
+      this.log(
+        "info",
+        `Small group (${pageNos.length} pages), extracting all at once`
+      );
+      const result = await this.extractMultiplePages(pages, pageNos, model);
+      usageList.push(result.usage);
+      return {
+        pageRangeMap: this.samplesToMap(result.samples),
+        usage: usageList
+      };
+    }
+    const sampledPages = /* @__PURE__ */ new Set();
+    for (let attempt = 0; attempt <= this.MAX_PATTERN_RETRIES; attempt++) {
+      const samplePageNos = this.selectRandomSamples(
+        pageNos,
+        this.SAMPLE_SIZE,
+        sampledPages
+      );
+      for (const p of samplePageNos) {
+        sampledPages.add(p);
+      }
+      this.log(
+        "info",
+        `Attempt ${attempt + 1}/${this.MAX_PATTERN_RETRIES + 1}: sampling pages ${samplePageNos.join(", ")}`
+      );
+      const result = await this.extractMultiplePages(
+        pages,
+        samplePageNos,
+        model
+      );
+      usageList.push(result.usage);
+      const samples = result.samples;
+      const pattern = this.detectPattern(samples);
+      if (pattern.pattern !== "unknown" /* UNKNOWN */) {
+        this.log(
+          "info",
+          `Pattern detected: ${pattern.pattern} (offset=${pattern.offset}, increment=${pattern.increment})`
+        );
+        return {
+          pageRangeMap: this.applyPattern(pageNos, pattern),
+          usage: usageList
+        };
+      }
+      this.log(
+        "warn",
+        `Pattern detection failed, attempt ${attempt + 1}/${this.MAX_PATTERN_RETRIES + 1}`
+      );
+    }
+    throw new PageRangeParseError(
+      `Failed to detect page pattern after ${this.MAX_PATTERN_RETRIES + 1} attempts for size group with ${pageNos.length} pages`
+    );
+  }
+  /**
+   * Select random samples from page numbers
+   */
+  selectRandomSamples(pageNos, count, exclude = /* @__PURE__ */ new Set()) {
+    const available = pageNos.filter((p) => !exclude.has(p));
+    const pool = available.length >= count ? available : pageNos;
+    const shuffled = [...pool];
+    for (let i = shuffled.length - 1; i > 0; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+    }
+    return shuffled.slice(0, count).sort((a, b) => a - b);
+  }
+  /**
+   * Extract page numbers from multiple pages in a single LLM call
+   */
+  async extractMultiplePages(pages, pageNos, model) {
+    this.log("info", `Extracting ${pageNos.length} pages in single LLM call`);
+    const imageContents = [];
+    for (const pageNo of pageNos) {
+      const page = pages[pageNo - 1];
+      const imagePath = path3.resolve(this.outputPath, page.image.uri);
+      const imageBuffer = fs3.readFileSync(imagePath);
+      const base64Image = imageBuffer.toString("base64");
+      const mimeType = page.image.mimetype || "image/png";
+      imageContents.push({
+        type: "image",
+        image: `data:${mimeType};base64,${base64Image}`
+      });
+    }
+    const schema = z4.object({
+      pages: z4.array(
+        z4.object({
+          imageIndex: z4.number().describe("0-based index of the image in the request"),
+          startPageNo: z4.number().nullable().describe("Start page number (null if not found)"),
+          endPageNo: z4.number().nullable().describe(
+            "End page number for double-sided scans (null for single page)"
+          )
+        })
+      ).describe("Extracted page numbers for each image")
+    });
+    try {
+      const result = await LLMCaller.callVision({
+        schema,
+        messages: [
+          {
+            role: "user",
+            content: [
+              { type: "text", text: this.buildUserPrompt(pageNos) },
+              ...imageContents
+            ]
+          }
+        ],
+        primaryModel: model,
+        fallbackModel: this.fallbackModel,
+        maxRetries: this.maxRetries,
+        temperature: 0,
+        abortSignal: this.abortSignal,
+        component: "PageRangeParser",
+        phase: "sampling"
+      });
+      const samples = result.output.pages.map((p) => ({
+        pdfPageNo: pageNos[p.imageIndex],
+        startPageNo: p.startPageNo,
+        endPageNo: p.endPageNo
+      }));
+      return { samples, usage: result.usage };
+    } catch (error) {
+      this.log("error", "Multi-image extraction failed:", error);
+      throw PageRangeParseError.fromError(
+        "Multi-image extraction failed",
+        error
+      );
+    }
+  }
+  /**
+   * Detect pattern from sample results
+   */
+  detectPattern(samples) {
+    const validSamples = samples.filter((s) => s.startPageNo !== null);
+    if (validSamples.length < 2) {
+      return { pattern: "unknown" /* UNKNOWN */, offset: 0, increment: 1 };
+    }
+    validSamples.sort((a, b) => a.pdfPageNo - b.pdfPageNo);
+    const isSimple = validSamples.every((s, i) => {
+      if (s.endPageNo !== null && s.startPageNo !== s.endPageNo) return false;
+      if (i === 0) return true;
+      const prev = validSamples[i - 1];
+      const expectedIncrease = s.pdfPageNo - prev.pdfPageNo;
+      return s.startPageNo === prev.startPageNo + expectedIncrease;
+    });
+    if (isSimple) {
+      const firstSample = validSamples[0];
+      const offset = firstSample.startPageNo - firstSample.pdfPageNo;
+      return { pattern: "simple_increment" /* SIMPLE_INCREMENT */, offset, increment: 1 };
+    }
+    const isDoubleSided = validSamples.every((s, i) => {
+      if (s.endPageNo === null) return false;
+      if (s.endPageNo !== s.startPageNo + 1) return false;
+      if (i === 0) return true;
+      const prev = validSamples[i - 1];
+      const pdfDiff = s.pdfPageNo - prev.pdfPageNo;
+      const expectedStartDiff = pdfDiff * 2;
+      const actualStartDiff = s.startPageNo - prev.startPageNo;
+      return actualStartDiff === expectedStartDiff;
+    });
+    if (isDoubleSided) {
+      const firstSample = validSamples[0];
+      const offset = firstSample.startPageNo - firstSample.pdfPageNo * 2;
+      return { pattern: "double_sided" /* DOUBLE_SIDED */, offset, increment: 2 };
+    }
+    const offsets = validSamples.map((s) => s.startPageNo - s.pdfPageNo);
+    const avgOffset = Math.round(
+      offsets.reduce((a, b) => a + b, 0) / offsets.length
+    );
+    const isConsistentOffset = offsets.every(
+      (o) => Math.abs(o - avgOffset) <= 1
+    );
+    if (isConsistentOffset) {
+      return { pattern: "offset" /* OFFSET */, offset: avgOffset, increment: 1 };
+    }
+    return { pattern: "unknown" /* UNKNOWN */, offset: 0, increment: 1 };
+  }
+  /**
+   * Apply detected pattern to generate page range map
+   */
+  applyPattern(pageNos, pattern) {
+    const result = {};
+    for (const pdfPageNo of pageNos) {
+      switch (pattern.pattern) {
+        case "simple_increment" /* SIMPLE_INCREMENT */:
+        case "offset" /* OFFSET */: {
+          const pageNo = pdfPageNo + pattern.offset;
+          result[pdfPageNo] = {
+            startPageNo: pageNo,
+            endPageNo: pageNo
+          };
+          break;
+        }
+        case "double_sided" /* DOUBLE_SIDED */: {
+          const start = pdfPageNo * 2 + pattern.offset;
+          result[pdfPageNo] = {
+            startPageNo: start,
+            endPageNo: start + 1
+          };
+          break;
+        }
+        default:
+          result[pdfPageNo] = { startPageNo: 0, endPageNo: 0 };
+      }
+    }
+    return result;
+  }
+  /**
+   * Convert sample results to page range map (for small groups)
+   */
+  samplesToMap(samples) {
+    const result = {};
+    for (const sample of samples) {
+      if (sample.startPageNo !== null) {
+        result[sample.pdfPageNo] = {
+          startPageNo: sample.startPageNo,
+          endPageNo: sample.endPageNo ?? sample.startPageNo
+        };
+      } else {
+        result[sample.pdfPageNo] = { startPageNo: 0, endPageNo: 0 };
+      }
+    }
+    return result;
+  }
+  /**
+   * Post-process the page range map
+   */
+  postProcess(pageRangeMap) {
+    this.detectAndHandleOutliers(pageRangeMap);
+    this.detectAndHandleDrops(pageRangeMap);
+    this.normalizeNegatives(pageRangeMap);
+    this.backfillFailedPages(pageRangeMap);
+  }
+  /**
+   * 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.
+   */
+  detectAndHandleOutliers(pageRangeMap) {
+    const pdfPages = Object.keys(pageRangeMap).map(Number).sort((a, b) => a - b);
+    if (pdfPages.length < 3) return;
+    const normalSequenceStart = this.findNormalSequenceStart(
+      pageRangeMap,
+      pdfPages
+    );
+    if (normalSequenceStart === null || normalSequenceStart <= 0) return;
+    const normalStartPdfPage = pdfPages[normalSequenceStart];
+    const normalStartPageNo = pageRangeMap[normalStartPdfPage].startPageNo;
+    let hasOutliers = false;
+    for (let i = 0; i < normalSequenceStart; i++) {
+      const pdfPage = pdfPages[i];
+      const pageNo = pageRangeMap[pdfPage].startPageNo;
+      if (pageNo === 0) continue;
+      const pdfDiff = normalStartPdfPage - pdfPage;
+      const isDoubleSided = this.isDoubleSidedRange(
+        pageRangeMap[normalStartPdfPage]
+      );
+      const expectedPageNo = isDoubleSided ? normalStartPageNo - pdfDiff * 2 : normalStartPageNo - pdfDiff;
+      if (pageNo > expectedPageNo + 10) {
+        this.log(
+          "info",
+          `Outlier detected: PDF ${pdfPage}=${pageNo} (expected ~${expectedPageNo})`
+        );
+        pageRangeMap[pdfPage] = { startPageNo: 0, endPageNo: 0 };
+        hasOutliers = true;
+      }
+    }
+    if (hasOutliers) {
+      this.log("info", `Outliers marked as failed, will be backfilled later`);
+    }
+  }
+  /**
+   * 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.
+   */
+  findNormalSequenceStart(pageRangeMap, pdfPages) {
+    const MIN_SEQUENCE_LENGTH = 3;
+    for (let startIdx = 0; startIdx <= pdfPages.length - MIN_SEQUENCE_LENGTH; startIdx++) {
+      let isValidSequence = true;
+      let expectedIncrement = null;
+      for (let i = 0; i < MIN_SEQUENCE_LENGTH - 1; i++) {
+        const currPdfPage = pdfPages[startIdx + i];
+        const nextPdfPage = pdfPages[startIdx + i + 1];
+        const currRange = pageRangeMap[currPdfPage];
+        const nextRange = pageRangeMap[nextPdfPage];
+        if (currRange.startPageNo === 0 || nextRange.startPageNo === 0) {
+          isValidSequence = false;
+          break;
+        }
+        const pageIncrement = nextRange.startPageNo - currRange.startPageNo;
+        const pdfIncrement = nextPdfPage - currPdfPage;
+        const isDoubleSided = this.isDoubleSidedRange(currRange);
+        const expectedIncrementPerPdf = isDoubleSided ? 2 : 1;
+        const expected = pdfIncrement * expectedIncrementPerPdf;
+        if (expectedIncrement === null) {
+          expectedIncrement = pageIncrement;
+        }
+        if (pageIncrement !== expected) {
+          isValidSequence = false;
+          break;
+        }
+      }
+      if (isValidSequence) {
+        return startIdx;
+      }
+    }
+    return null;
+  }
+  /**
+   * Check if a page range represents a double-sided scan
+   */
+  isDoubleSidedRange(range) {
+    return range.endPageNo !== null && range.endPageNo !== range.startPageNo && range.endPageNo === range.startPageNo + 1;
+  }
+  /**
+   * 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.
+   */
+  detectAndHandleDrops(pageRangeMap) {
+    const pdfPages = Object.keys(pageRangeMap).map(Number).sort((a, b) => a - b);
+    if (pdfPages.length < 2) return;
+    for (let i = 1; i < pdfPages.length; i++) {
+      const prevPdfPage = pdfPages[i - 1];
+      const currPdfPage = pdfPages[i];
+      const prevPageNo = pageRangeMap[prevPdfPage].startPageNo;
+      const currPageNo = pageRangeMap[currPdfPage].startPageNo;
+      if (prevPageNo === 0 || currPageNo === 0) continue;
+      if (currPageNo > 0 && prevPageNo > currPageNo && prevPageNo - currPageNo > 1) {
+        this.log(
+          "info",
+          `Page drop detected: PDF ${prevPdfPage}=${prevPageNo} -> PDF ${currPdfPage}=${currPageNo}`
+        );
+        const isDoubleSided = this.isDoubleSidedRange(
+          pageRangeMap[currPdfPage]
+        );
+        for (let j = i - 1; j >= 0; j--) {
+          const pdfPage = pdfPages[j];
+          const distance = currPdfPage - pdfPage;
+          if (isDoubleSided) {
+            const expectedStartPageNo = currPageNo - distance * 2;
+            if (expectedStartPageNo < 1) {
+              pageRangeMap[pdfPage] = { startPageNo: 0, endPageNo: 0 };
+            } else {
+              pageRangeMap[pdfPage] = {
+                startPageNo: expectedStartPageNo,
+                endPageNo: expectedStartPageNo + 1
+              };
+            }
+          } else {
+            const expectedPageNo = currPageNo - distance;
+            if (expectedPageNo < 1) {
+              pageRangeMap[pdfPage] = { startPageNo: 0, endPageNo: 0 };
+            } else {
+              pageRangeMap[pdfPage] = {
+                startPageNo: expectedPageNo,
+                endPageNo: expectedPageNo
+              };
+            }
+          }
+          this.log(
+            "info",
+            `Recalculated PDF ${pdfPage} -> ${pageRangeMap[pdfPage].startPageNo}`
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Normalize negative page numbers to 0
+   */
+  normalizeNegatives(pageRangeMap) {
+    for (const [pdfPageStr, range] of Object.entries(pageRangeMap)) {
+      if (range.startPageNo < 0 || range.endPageNo < 0) {
+        this.log("info", `Normalizing negative: PDF ${pdfPageStr} -> 0`);
+        pageRangeMap[Number(pdfPageStr)] = { startPageNo: 0, endPageNo: 0 };
+      }
+    }
+  }
+  /**
+   * Backfill pages marked with 0 using detected pattern
+   */
+  backfillFailedPages(pageRangeMap) {
+    const pdfPages = Object.keys(pageRangeMap).map(Number).sort((a, b) => a - b);
+    const failedPages = pdfPages.filter(
+      (p) => pageRangeMap[p].startPageNo === 0
+    );
+    if (failedPages.length === 0) return;
+    const successfulPages = pdfPages.filter((p) => pageRangeMap[p].startPageNo > 0).map((p) => ({
+      pdfPage: p,
+      pageNo: pageRangeMap[p].startPageNo,
+      isDoubleSided: this.isDoubleSidedRange(pageRangeMap[p])
+    }));
+    if (successfulPages.length < 2) {
+      this.log("warn", "Not enough successful pages for backfill");
+      return;
+    }
+    const doubleSidedCount = successfulPages.filter(
+      (s) => s.isDoubleSided
+    ).length;
+    const isDoubleSided = doubleSidedCount > successfulPages.length / 2;
+    if (isDoubleSided) {
+      const offsets = successfulPages.map((s) => s.pageNo - s.pdfPage * 2);
+      const avgOffset = Math.round(
+        offsets.reduce((a, b) => a + b, 0) / offsets.length
+      );
+      this.log(
+        "info",
+        `Backfilling ${failedPages.length} pages with double-sided pattern (offset=${avgOffset})`
+      );
+      for (const pdfPage of failedPages) {
+        const expectedStartPageNo = pdfPage * 2 + avgOffset;
+        if (expectedStartPageNo < 1) {
+          this.log(
+            "info",
+            `Backfill skipped for PDF ${pdfPage} (would be ${expectedStartPageNo})`
+          );
+          continue;
+        }
+        this.log(
+          "info",
+          `Backfill PDF ${pdfPage}: 0 -> ${expectedStartPageNo}-${expectedStartPageNo + 1}`
+        );
+        pageRangeMap[pdfPage] = {
+          startPageNo: expectedStartPageNo,
+          endPageNo: expectedStartPageNo + 1
+        };
+      }
+    } else {
+      const offsets = successfulPages.map((s) => s.pageNo - s.pdfPage);
+      const avgOffset = Math.round(
+        offsets.reduce((a, b) => a + b, 0) / offsets.length
+      );
+      this.log(
+        "info",
+        `Backfilling ${failedPages.length} pages with offset ${avgOffset}`
+      );
+      for (const pdfPage of failedPages) {
+        const expectedPageNo = pdfPage + avgOffset;
+        if (expectedPageNo < 1) {
+          this.log(
+            "info",
+            `Backfill skipped for PDF ${pdfPage} (would be ${expectedPageNo})`
+          );
+          continue;
+        }
+        this.log("info", `Backfill PDF ${pdfPage}: 0 -> ${expectedPageNo}`);
+        pageRangeMap[pdfPage] = {
+          startPageNo: expectedPageNo,
+          endPageNo: expectedPageNo
+        };
+      }
+    }
+  }
+  /**
+   * Build system prompt for Vision LLM
+   */
+  buildSystemPrompt() {
+    return `You are a page number extraction specialist for document images.
+You will receive multiple document page images. For EACH image, extract the visible page number(s).
+
+**SCAN TYPES:**
+1. SINGLE PAGE: One document page per image. Return startPageNo only, endPageNo should be null.
+2. DOUBLE-SIDED: Two document pages per image (spread). Return startPageNo (left) and endPageNo (right).
+
+**WHERE TO LOOK:**
+- Bottom center, bottom corners (most common)
+- Top corners (less common)
+- Page numbers are SMALL numbers in MARGINS, NOT in content area
+
+**WHAT TO IGNORE - These are NOT page numbers:**
+- Roman numerals (i, ii, iii, iv, v...) - return null
+- Figure numbers: "Figure 5", "Fig. 5", "\uB3C4 5", "\uADF8\uB9BC 5"
+- Table numbers: "Table 3", "\uD45C 3"
+- Photo numbers: "Photo 8", "\uC0AC\uC9C4 8", "Plate 4", "\uB3C4\uD310 4"
+- Years in content: "2015", "(1998)"
+- Any numbers with text prefix or inside content area
+
+**RESPONSE FORMAT:**
+For each image (in order), provide:
+- imageIndex: 0-based index of the image
+- startPageNo: The page number found (null if not visible/readable)
+- endPageNo: Right page number for double-sided scans (null for single pages)`;
+  }
+  /**
+   * Build user prompt for Vision LLM
+   */
+  buildUserPrompt(pageNos) {
+    return `I am providing ${pageNos.length} document page images.
+These are PDF pages: ${pageNos.join(", ")}.
+
+For each image (in order), extract the visible page number(s).
+Return null for pages where no page number is visible or readable.
+
+Remember: Look for SMALL numbers in MARGINS only. Ignore figure/table/photo numbers.`;
+  }
+};
+
+// src/validators/base-validator.ts
+var BaseValidator = class extends TextLLMComponent {
+  /**
+   * Validator name for logging (kept for backwards compatibility)
+   */
+  validatorName;
+  /**
+   * 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, model, validatorName, options, fallbackModel, aggregator) {
+    super(logger, model, validatorName, options, fallbackModel, aggregator);
+    this.validatorName = validatorName;
+  }
+  /**
+   * 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
+   */
+  async callLLM(schema, systemPrompt, userPrompt, phase, aggregator) {
+    const result = await LLMCaller.call({
+      schema,
+      systemPrompt,
+      userPrompt,
+      primaryModel: this.model,
+      fallbackModel: this.fallbackModel,
+      maxRetries: this.maxRetries,
+      temperature: this.temperature,
+      abortSignal: this.abortSignal,
+      component: this.validatorName,
+      phase
+    });
+    if (aggregator) {
+      aggregator.track(result.usage);
+    } else {
+      this.trackUsage(result.usage);
+    }
+    return {
+      output: result.output,
+      usage: result.usage
+    };
+  }
+};
+
+// src/validators/toc-content-validator.ts
+import { z as z5 } from "zod";
+var TocContentValidationSchema = z5.object({
+  isToc: z5.boolean().describe("Whether the content is a table of contents"),
+  confidence: z5.number().min(0).max(1).describe("Confidence score between 0 and 1"),
+  reason: z5.string().describe("Brief explanation for the decision")
+});
+var TocContentValidator = class extends BaseValidator {
+  confidenceThreshold;
+  constructor(logger, model, options, fallbackModel, aggregator) {
+    super(
+      logger,
+      model,
+      "TocContentValidator",
+      options,
+      fallbackModel,
+      aggregator
+    );
+    this.confidenceThreshold = options?.confidenceThreshold ?? 0.7;
+  }
+  /**
+   * Validate if the markdown content is a table of contents
+   *
+   * @param markdown - Markdown content to validate
+   * @returns Validation result with isToc, confidence, and reason
+   */
+  async validate(markdown) {
+    this.logger.info(
+      `[TocContentValidator] Validating content (${markdown.length} chars)`
+    );
+    if (!markdown.trim()) {
+      this.logger.info(
+        "[TocContentValidator] Empty markdown, returning invalid"
+      );
+      return {
+        isToc: false,
+        confidence: 1,
+        reason: "Empty content"
+      };
+    }
+    const { output: result } = await this.callLLM(
+      TocContentValidationSchema,
+      this.buildSystemPrompt(),
+      this.buildUserPrompt(markdown),
+      "validation",
+      this.aggregator
+    );
+    this.logger.info(
+      `[TocContentValidator] Result: isToc=${result.isToc}, confidence=${result.confidence}`
+    );
+    return result;
+  }
+  /**
+   * Check if validation result passes threshold
+   *
+   * @param result - Validation result from validate()
+   * @returns true if content is valid TOC with sufficient confidence
+   */
+  isValid(result) {
+    return result.isToc && result.confidence >= this.confidenceThreshold;
+  }
+  /**
+   * Build system prompt for TOC content validation
+   */
+  buildSystemPrompt() {
+    return `You are a document structure analyst. Your task is to determine if the provided content is a Table of Contents (TOC).
+
+## What IS a Table of Contents:
+- A structured list of chapters/sections with corresponding page numbers
+- Contains hierarchical section titles (e.g., "Chapter 1", "\uC81C1\uC7A5", "1.1 Introduction", etc.)
+- Has page number references for each entry (e.g., "..... 10", "... 5", or just a number at the end)
+- Multiple entries organized by document structure
+- Main document outline listing major chapters and sections
+
+## What is NOT a Table of Contents:
+- Photo/image indices (\uC0AC\uC9C4 \uBAA9\uCC28, \uC0AC\uC9C4\uBAA9\uCC28, Photo Index, List of Figures, List of Photos)
+- Table indices (\uD45C \uBAA9\uCC28, \uD45C\uBAA9\uCC28, Table Index, List of Tables)
+- Drawing/diagram indices (\uB3C4\uBA74 \uBAA9\uCC28, \uB3C4\uBA74\uBAA9\uCC28, Drawing Index, List of Drawings)
+- Appendix indices (\uBD80\uB85D \uBAA9\uCC28, Appendix Index)
+- Random body text from the document
+- Single entries or incomplete lists (fewer than 3 items)
+- Reference lists or bibliographies
+- Index pages (alphabetical keyword lists)
+
+## Response Guidelines:
+- Set isToc to true ONLY if content is clearly a main document TOC
+- Set confidence between 0.0 and 1.0 based on your certainty
+- Provide a brief reason explaining your decision (1-2 sentences)`;
+  }
+  /**
+   * Build user prompt with markdown content
+   */
+  buildUserPrompt(markdown) {
+    return `Determine if the following content is a Table of Contents:
+
+${markdown}`;
+  }
+};
+
+// src/validators/caption-validator.ts
+import { z as z6 } from "zod";
+var CaptionValidationItemSchema = z6.object({
+  index: z6.number().int().describe("Index of the caption in the input array"),
+  isValid: z6.boolean().describe("Whether the parsed caption is correct"),
+  reason: z6.string().nullable().describe("Brief explanation if invalid, null if valid")
+});
+var CaptionValidationBatchSchema = z6.object({
+  results: z6.array(CaptionValidationItemSchema)
+});
+var CaptionValidator = class extends BaseValidator {
+  constructor(logger, model, options, fallbackModel, aggregator) {
+    super(
+      logger,
+      model,
+      "CaptionValidator",
+      options,
+      fallbackModel,
+      aggregator
+    );
+  }
+  /**
+   * 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
+   */
+  async validateBatch(captions, originalTexts, batchSize) {
+    this.logger.info(
+      `[CaptionValidator] Validating ${captions.length} captions with batch size ${batchSize}...`
+    );
+    if (captions.length !== originalTexts.length) {
+      throw new Error(
+        `[CaptionValidator] Captions and originalTexts length mismatch: ${captions.length} vs ${originalTexts.length}`
+      );
+    }
+    if (captions.length === 0) {
+      this.logger.info("[CaptionValidator] No captions to validate");
+      return [];
+    }
+    if (batchSize === 0) {
+      this.logger.info(
+        "[CaptionValidator] Skipping validation (batchSize=0), assuming all captions are valid"
+      );
+      return new Array(captions.length).fill(true);
+    }
+    try {
+      const indexedItems = captions.map((caption, index) => ({
+        index,
+        caption,
+        originalText: originalTexts[index]
+      }));
+      const batchResults = await BatchProcessor.processBatch(
+        indexedItems,
+        batchSize,
+        async (batch) => this.validateBatchInternal(batch, this.model)
+      );
+      batchResults.sort((a, b) => a.index - b.index);
+      const results = batchResults.map((r) => r.isValid);
+      const validCount = results.filter((r) => r).length;
+      this.logger.info(
+        `[CaptionValidator] Completed: ${validCount}/${results.length} captions validated as correct`
+      );
+      if (this.aggregator) {
+        this.aggregator.logSummary(this.logger);
+      }
+      return results;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.logger.error(`[CaptionValidator] Validation failed: ${message}`);
+      throw new CaptionValidationError(
+        `Failed to validate captions: ${message}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * 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
+   */
+  async validateBatchInternal(items, model) {
+    const result = await LLMCaller.call({
+      schema: CaptionValidationBatchSchema,
+      systemPrompt: this.buildSystemPrompt(),
+      userPrompt: this.buildUserPrompt(items),
+      primaryModel: model,
+      fallbackModel: this.fallbackModel,
+      maxRetries: this.maxRetries,
+      temperature: this.temperature,
+      abortSignal: this.abortSignal,
+      component: "CaptionValidator",
+      phase: "validation"
+    });
+    if (this.aggregator) {
+      this.aggregator.track(result.usage);
+    }
+    return result.output.results.map((item) => ({
+      index: item.index,
+      isValid: item.isValid
+    }));
+  }
+  buildSystemPrompt() {
+    return `You are a caption validation expert for archaeological excavation reports.
+
+Your task is to validate whether parsed caption prefixes (num field) are correctly extracted from original caption texts.
+
+## Caption Pattern Recognition
+
+A valid caption follows the pattern: <prefix word(s)> <number>
+- The prefix can be ANY Korean/English word(s) that label images/tables/figures
+- Common examples: \uB3C4\uD310, \uC0AC\uC9C4, \uADF8\uB9BC, \uC6D0\uC0C9\uC0AC\uC9C4, \uD751\uBC31\uC0AC\uC9C4, Figure, Photo, Plate, etc.
+- The key is the PATTERN (text followed by number), not a specific word list
+- Leading punctuation/brackets should be IGNORED when extracting
+
+Valid caption patterns:
+- "\uC6D0\uC0C9\uC0AC\uC9C4 1. \uC870\uC0AC\uC9C0\uC5ED" \u2192 num="\uC6D0\uC0C9\uC0AC\uC9C4 1" \u2713
+- "\uD751\uBC31\uC0AC\uC9C4 2 \uCD9C\uD1A0\uC720\uBB3C" \u2192 num="\uD751\uBC31\uC0AC\uC9C4 2" \u2713
+- "\uB3C4\uD310 1 \uC720\uC801 \uC804\uACBD" \u2192 num="\uB3C4\uD310 1" \u2713
+- "(\uC0AC\uC9C4 16> \uB290\uD2F0\uB098\uBB34" \u2192 num="\uC0AC\uC9C4 16" \u2713 (ignore leading punctuation)
+- "<\uB3C4\uD310 3> \uC720\uBB3C \uC0AC\uC9C4" \u2192 num="\uB3C4\uD310 3" \u2713 (ignore angle brackets)
+
+Invalid patterns (num MUST be null):
+- "39 3\uC6D4 28\uC77C(\uBC31\uC81C \uB3C4\uB85C\uC720\uAD6C)" \u2192 null \u2713 (starts with number, no prefix)
+- "1. \uC720\uC801 \uC804\uACBD" \u2192 null \u2713 (numbered list item, not a caption)
+- "2024\uB144 \uC870\uC0AC \uD604\uD669" \u2192 null \u2713 (year reference, not a caption)
+
+## Extraction Algorithm:
+
+1. Extract prefix + number from the caption
+   - The prefix is the text portion before the number
+   - Full extraction: "\uC6D0\uC0C9\uC0AC\uC9C4 1", "\uB3C4\uD310 2-3", "\uADF8\uB9BC 3.6", "Figure 4a"
+
+2. **Decimal point handling**: Include period/dot after number if directly following
+   - "\uADF8\uB9BC 3.6. \uD55C\uBC18\uB3C4" \u2192 "\uADF8\uB9BC 3.6" (period as decimal separator included)
+   - "\uB3C4\uD310 2. \uC720\uC801" \u2192 "\uB3C4\uD310 2" (period after space, NOT included)
+
+3. **Stop rules** (extraction must stop at first occurrence of):
+   - Punctuation (except decimal point): , : ; ! ? ~ ( ) [ ] { }
+   - Whitespace: space, tab, newline
+   - Underscore: _
+   - Exception: Periods directly after digits are included as decimal separators
+   - Exception: Hyphens within numbers are included (e.g., "2-3")
+
+## Validation Rules:
+
+1. **Pattern requirement**: The original text MUST follow <prefix> <number> pattern
+   - "\uC6D0\uC0C9\uC0AC\uC9C4 1. \uC870\uC0AC\uC9C0\uC5ED" \u2192 num="\uC6D0\uC0C9\uC0AC\uC9C4 1" \u2713 (valid pattern)
+   - "39 3\uC6D4 28\uC77C(\uBC31\uC81C)" \u2192 num="39" \u2717 (starts with number, should be null)
+   - "1. \uC870\uC0AC \uAC1C\uC694" \u2192 num="1" \u2717 (numbered list, should be null)
+
+2. **Correctness**: The parsed "num" must contain the actual prefix+number
+   - "\uB3C4\uD310 1 \uC720\uC801 \uC804\uACBD" \u2192 num="\uB3C4\uD310 1" \u2713
+   - "\uB3C4\uD310 1 \uC720\uC801 \uC804\uACBD" \u2192 num="\uB3C4\uD310" \u2717 (incomplete)
+
+3. **Spacing**: The spacing in "num" must match the original text exactly
+   - "\uB3C4\uD310 1" \u2192 num="\uB3C4\uD310 1" \u2713
+   - "\uB3C4\uD3101" \u2192 num="\uB3C4\uD3101" \u2713
+   - "\uB3C4\uD310 1" \u2192 num="\uB3C4\uD3101" \u2717 (spacing mismatch)
+
+4. **Completeness**: The number part must be fully extracted
+   - "Figure 2-3" \u2192 num="Figure 2-3" \u2713
+   - "Figure 2-3" \u2192 num="Figure 2" \u2717 (incomplete number)
+
+5. **Null handling**: If "num" is null, verify:
+   - Either the original text has no number
+   - OR the text starts with a number (no prefix)
+   - "\uC720\uC801 \uC804\uACBD \uC0AC\uC9C4" \u2192 num=null \u2713 (no number in caption position)
+   - "\uC6D0\uC0C9\uC0AC\uC9C4 1 \uC870\uC0AC" \u2192 num=null \u2717 (should extract "\uC6D0\uC0C9\uC0AC\uC9C4 1")
+
+## Response:
+For each caption, return:
+- index: original position
+- isValid: true if parsing is correct, false otherwise
+- reason: null if valid, brief explanation if invalid`;
+  }
+  buildUserPrompt(items) {
+    const captionList = items.map(
+      (item) => `[${item.index}] Original: "${item.originalText}" | Parsed num: ${item.caption.num !== void 0 ? `"${item.caption.num}"` : "null"}`
+    ).join("\n");
+    return `Validate the following caption parsing results:
+
+${captionList}
+
+Return the results as JSON array with "index", "isValid", and "reason" (null if valid, explanation if invalid).
+
+Example format:
+{
+  "results": [
+    { "index": 0, "isValid": true, "reason": null },
+    { "index": 1, "isValid": false, "reason": "Number incomplete: expected '1-2' but got '1'" },
+    { "index": 2, "isValid": true, "reason": null }
+  ]
+}`;
+  }
+};
+var CaptionValidationError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "CaptionValidationError";
+  }
+};
+
+// src/document-processor.ts
+var DocumentProcessor = class {
+  logger;
+  fallbackModel;
+  pageRangeParserModel;
+  tocExtractorModel;
+  validatorModel;
+  visionTocExtractorModel;
+  captionParserModel;
+  textCleanerBatchSize;
+  captionParserBatchSize;
+  captionValidatorBatchSize;
+  maxRetries;
+  enableFallbackRetry;
+  abortSignal;
+  idGenerator = new IdGenerator();
+  refResolver;
+  pageRangeParser;
+  tocFinder;
+  tocExtractor;
+  tocContentValidator;
+  captionValidator;
+  visionTocExtractor;
+  captionParser;
+  chapterConverter;
+  textCleaner = TextCleaner;
+  usageAggregator = new LLMTokenUsageAggregator();
+  constructor(options) {
+    this.logger = options.logger;
+    this.fallbackModel = options.fallbackModel;
+    this.pageRangeParserModel = options.pageRangeParserModel ?? options.fallbackModel;
+    this.tocExtractorModel = options.tocExtractorModel ?? options.fallbackModel;
+    this.validatorModel = options.validatorModel ?? options.fallbackModel;
+    this.visionTocExtractorModel = options.visionTocExtractorModel ?? options.fallbackModel;
+    this.captionParserModel = options.captionParserModel ?? options.fallbackModel;
+    this.textCleanerBatchSize = options.textCleanerBatchSize;
+    this.captionParserBatchSize = options.captionParserBatchSize;
+    this.captionValidatorBatchSize = options.captionValidatorBatchSize;
+    this.maxRetries = options.maxRetries ?? 3;
+    this.enableFallbackRetry = options.enableFallbackRetry ?? false;
+    this.abortSignal = options.abortSignal;
+  }
+  /**
+   * Check if abort has been requested and throw error if so
+   *
+   * @throws {Error} with name 'AbortError' if aborted
+   */
+  checkAborted() {
+    if (this.abortSignal?.aborted) {
+      const error = new Error("Document processing was aborted");
+      error.name = "AbortError";
+      throw error;
+    }
+  }
+  /**
+   * Converts DoclingDocument to ProcessedDocument with token usage tracking.
+   *
+   * Conversion process:
+   * 1. Initialize processors and resolvers
+   * 2. Normalize and filter texts
+   * 3. Clean texts and parse page ranges (parallel)
+   * 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 outputPath - Path containing images and pages subdirectories (images/image_0.png, pages/page_0.png, etc.)
+   * @returns Document processing result with ProcessedDocument and token usage report
+   *
+   * @throws {TocExtractError} When TOC extraction fails
+   * @throws {PageRangeParseError} When page range parsing fails
+   * @throws {ConversionError} When error occurs during conversion
+   */
+  async process(doclingDoc, reportId, outputPath) {
+    this.logger.info("[DocumentProcessor] Starting document processing...");
+    this.logger.info("[DocumentProcessor] Report ID:", reportId);
+    this.usageAggregator.reset();
+    this.checkAborted();
+    this.initializeProcessors(doclingDoc, outputPath);
+    const startTimeFilter = Date.now();
+    const filtered = this.normalizeAndFilterTexts(doclingDoc);
+    const filteringTime = Date.now() - startTimeFilter;
+    this.logger.info(
+      `[DocumentProcessor] Text filtering took ${filteringTime}ms`
+    );
+    this.checkAborted();
+    const startTimePageRange = Date.now();
+    const pageRangeMap = await this.parsePageRanges(doclingDoc);
+    const pageRangeTime = Date.now() - startTimePageRange;
+    this.logger.info(
+      `[DocumentProcessor] Page range parsing took ${pageRangeTime}ms`
+    );
+    this.checkAborted();
+    const startTimeToc = Date.now();
+    const tocEntries = await this.extractTableOfContents(doclingDoc, filtered);
+    const tocTime = Date.now() - startTimeToc;
+    this.logger.info(`[DocumentProcessor] TOC extraction took ${tocTime}ms`);
+    this.checkAborted();
+    const startTimeResources = Date.now();
+    const { images, tables, footnotes } = await this.convertResources(
+      doclingDoc,
+      outputPath
+    );
+    const resourcesTime = Date.now() - startTimeResources;
+    this.logger.info(
+      `[DocumentProcessor] Resource conversion took ${resourcesTime}ms`
+    );
+    this.checkAborted();
+    const startTimeChapters = Date.now();
+    const chapters = await this.convertChapters(
+      doclingDoc,
+      tocEntries,
+      pageRangeMap,
+      images,
+      tables,
+      footnotes
+    );
+    const chaptersTime = Date.now() - startTimeChapters;
+    this.logger.info(
+      `[DocumentProcessor] Chapter conversion took ${chaptersTime}ms`
+    );
+    const startTimeAssemble = Date.now();
+    const processedDoc = this.assembleProcessedDocument(
+      reportId,
+      pageRangeMap,
+      chapters,
+      images,
+      tables,
+      footnotes
+    );
+    const assembleTime = Date.now() - startTimeAssemble;
+    this.logger.info(
+      `[DocumentProcessor] Document assembly took ${assembleTime}ms`
+    );
+    this.logger.info("[DocumentProcessor] Document processing completed");
+    return {
+      document: processedDoc,
+      usage: this.usageAggregator.getReport()
+    };
+  }
+  /**
+   * Initialize all processors and resolvers
+   *
+   * Sets up RefResolver, PageRangeParser, TocFinder, and TocExtractor
+   */
+  initializeProcessors(doclingDoc, outputPath) {
+    this.logger.info("[DocumentProcessor] Initializing processors...");
+    this.logger.info("[DocumentProcessor] - RefResolver");
+    this.refResolver = new RefResolver(this.logger, doclingDoc);
+    this.logger.info("[DocumentProcessor] - PageRangeParser");
+    this.pageRangeParser = new PageRangeParser(
+      this.logger,
+      this.pageRangeParserModel,
+      outputPath,
+      this.maxRetries,
+      this.enableFallbackRetry ? this.fallbackModel : void 0,
+      this.usageAggregator,
+      this.abortSignal
+    );
+    this.logger.info("[DocumentProcessor] - TocFinder");
+    this.tocFinder = new TocFinder(this.logger, this.refResolver);
+    this.logger.info("[DocumentProcessor] - TocExtractor");
+    this.tocExtractor = new TocExtractor(
+      this.logger,
+      this.tocExtractorModel,
+      {
+        maxRetries: this.maxRetries
+      },
+      this.enableFallbackRetry ? this.fallbackModel : void 0,
+      this.abortSignal
+    );
+    this.logger.info("[DocumentProcessor] - TocContentValidator");
+    this.tocContentValidator = new TocContentValidator(
+      this.logger,
+      this.validatorModel,
+      { maxRetries: this.maxRetries, abortSignal: this.abortSignal },
+      this.enableFallbackRetry ? this.fallbackModel : void 0,
+      this.usageAggregator
+    );
+    this.logger.info("[DocumentProcessor] - CaptionValidator");
+    this.captionValidator = new CaptionValidator(
+      this.logger,
+      this.validatorModel,
+      { maxRetries: this.maxRetries, abortSignal: this.abortSignal },
+      this.enableFallbackRetry ? this.fallbackModel : void 0,
+      this.usageAggregator
+    );
+    this.logger.info("[DocumentProcessor] - VisionTocExtractor");
+    this.visionTocExtractor = new VisionTocExtractor(
+      this.logger,
+      this.visionTocExtractorModel,
+      outputPath,
+      { maxRetries: this.maxRetries, abortSignal: this.abortSignal },
+      this.enableFallbackRetry ? this.fallbackModel : void 0,
+      this.usageAggregator
+    );
+    this.logger.info("[DocumentProcessor] - CaptionParser");
+    this.captionParser = new CaptionParser(
+      this.logger,
+      this.captionParserModel,
+      { maxRetries: this.maxRetries, abortSignal: this.abortSignal },
+      this.enableFallbackRetry ? this.fallbackModel : void 0,
+      this.usageAggregator
+    );
+    this.logger.info("[DocumentProcessor] - ChapterConverter");
+    this.chapterConverter = new ChapterConverter(this.logger, this.idGenerator);
+    this.logger.info("[DocumentProcessor] All processors initialized");
+  }
+  /**
+   * Normalize and filter texts using TextCleaner
+   *
+   * Performs basic text normalization (unicode, whitespace, punctuation)
+   * and filters out invalid texts (empty, numbers-only, etc.)
+   */
+  normalizeAndFilterTexts(doclingDoc) {
+    this.logger.info("[DocumentProcessor] Normalizing and filtering texts...");
+    const texts = doclingDoc.texts.map((text) => text.text);
+    const filtered = this.textCleaner.normalizeAndFilterBatch(
+      texts,
+      this.textCleanerBatchSize
+    );
+    this.logger.info(
+      `[DocumentProcessor] Filtered ${filtered.length} texts from ${texts.length} original texts`
+    );
+    return filtered;
+  }
+  /**
+   * 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.
+   */
+  async parsePageRanges(doclingDoc) {
+    this.logger.info("[DocumentProcessor] Starting page range parsing...");
+    const result = await this.pageRangeParser.parse(doclingDoc);
+    const pageRangeMap = result.pageRangeMap;
+    this.logger.info(
+      `[DocumentProcessor] Page range map entries: ${Object.keys(pageRangeMap).length}`
+    );
+    return pageRangeMap;
+  }
+  /**
+   * Convert images, tables, and footnotes
+   *
+   * Runs conversions:
+   * - Images conversion (with caption extraction)
+   * - Tables conversion (with caption extraction, excluding TOC tables)
+   * - Footnotes conversion (synchronous, from text items with label='footnote')
+   */
+  async convertResources(doclingDoc, outputPath) {
+    this.logger.info(
+      "[DocumentProcessor] Converting images, tables, and footnotes..."
+    );
+    const [images, tables] = await Promise.all([
+      this.convertImages(doclingDoc, outputPath),
+      this.convertTables(doclingDoc)
+    ]);
+    const footnotes = this.convertFootnotes(doclingDoc);
+    this.logger.info(
+      `[DocumentProcessor] Converted ${images.length} images, ${tables.length} tables, and ${footnotes.length} footnotes`
+    );
+    return { images, tables, footnotes };
+  }
+  /**
+   * Convert footnotes
+   *
+   * Extracts footnotes from DoclingDocument text items with label='footnote'
+   */
+  convertFootnotes(doclingDoc) {
+    const footnoteItems = doclingDoc.texts.filter(
+      (item) => item.label === "footnote"
+    );
+    this.logger.info(
+      `[DocumentProcessor] Converting ${footnoteItems.length} footnotes...`
+    );
+    const footnotes = [];
+    for (const item of footnoteItems) {
+      if (!this.textCleaner.isValidText(item.text)) {
+        continue;
+      }
+      const pdfPageNo = item.prov?.[0]?.page_no ?? 1;
+      const footnoteId = this.idGenerator.generateFootnoteId();
+      footnotes.push({
+        id: footnoteId,
+        text: this.textCleaner.normalize(item.text),
+        pdfPageNo
+      });
+    }
+    this.logger.info(
+      `[DocumentProcessor] Converted ${footnotes.length} valid footnotes`
+    );
+    return footnotes;
+  }
+  /**
+   * Assemble the final ProcessedDocument
+   *
+   * Creates the ProcessedDocument structure with all converted components
+   */
+  assembleProcessedDocument(reportId, pageRangeMap, chapters, images, tables, footnotes) {
+    this.logger.info("[DocumentProcessor] Assembling ProcessedDocument...");
+    const processedDoc = {
+      reportId,
+      pageRangeMap,
+      chapters,
+      images,
+      tables,
+      footnotes
+    };
+    this.logger.info(
+      `[DocumentProcessor] Assembled document with ${chapters.length} chapters, ${images.length} images, ${tables.length} tables, ${footnotes.length} footnotes`
+    );
+    return processedDoc;
+  }
+  /**
+   * Extract table of contents (TOC)
+   *
+   * Uses rule-based extraction with LLM validation and vision fallback:
+   * 1. TocFinder - find TOC area in document (rule-based)
+   * 2. MarkdownConverter - convert TOC items to Markdown
+   * 3. TocContentValidator - validate if content is actually a TOC (LLM)
+   * 4. If invalid: VisionTocExtractor - extract from page images (vision LLM fallback)
+   * 5. TocExtractor - LLM-based structured extraction
+   */
+  async extractTableOfContents(doclingDoc, _filteredTexts) {
+    this.logger.info("[DocumentProcessor] Extracting TOC...");
+    let markdown = null;
+    try {
+      const tocArea = this.tocFinder.find(doclingDoc);
+      this.logger.info(
+        `[DocumentProcessor] Found TOC area: pages ${tocArea.startPage}-${tocArea.endPage}`
+      );
+      markdown = MarkdownConverter.convert(tocArea.itemRefs, this.refResolver);
+      this.logger.info(
+        `[DocumentProcessor] Converted TOC to Markdown (${markdown.length} chars)`
+      );
+      const validation = await this.tocContentValidator.validate(markdown);
+      if (!this.tocContentValidator.isValid(validation)) {
+        this.logger.warn(
+          `[DocumentProcessor] TOC validation failed: ${validation.reason}`
+        );
+        markdown = null;
+      } else {
+        this.logger.info(
+          `[DocumentProcessor] TOC validation passed (confidence: ${validation.confidence})`
+        );
+      }
+    } catch (error) {
+      if (error instanceof TocNotFoundError) {
+        this.logger.info(
+          "[DocumentProcessor] Rule-based TOC not found, will try vision fallback"
+        );
+      } else {
+        throw error;
+      }
+    }
+    if (!markdown) {
+      this.logger.info("[DocumentProcessor] Using vision fallback for TOC");
+      const totalPages = Object.keys(doclingDoc.pages).length;
+      markdown = await this.visionTocExtractor.extract(totalPages);
+      if (!markdown) {
+        this.logger.warn(
+          "[DocumentProcessor] TOC not found in any method, returning empty"
+        );
+        return [];
+      }
+      this.logger.info(
+        `[DocumentProcessor] Vision extracted TOC markdown (${markdown.length} chars)`
+      );
+    }
+    const tocResult = await this.tocExtractor.extract(markdown);
+    this.usageAggregator.track(tocResult.usage);
+    this.logger.info(
+      `[DocumentProcessor] Extracted ${tocResult.entries.length} top-level TOC entries`
+    );
+    return tocResult.entries;
+  }
+  /**
+   * 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
+   */
+  async processResourceCaptions(captionTexts, resourceType) {
+    const captionsByIndex = /* @__PURE__ */ new Map();
+    const validCaptionData = [];
+    for (let i = 0; i < captionTexts.length; i++) {
+      const text = captionTexts[i];
+      if (text !== void 0) {
+        validCaptionData.push({
+          resourceIndex: i,
+          filteredIndex: validCaptionData.length,
+          text
+        });
+      }
+    }
+    const validCaptionTexts = validCaptionData.map((item) => item.text);
+    const parsedCaptions = validCaptionTexts.length > 0 ? await this.captionParser.parseBatch(
+      validCaptionTexts,
+      this.captionParserBatchSize
+    ) : [];
+    let finalValidCaptionData = validCaptionData;
+    let finalParsedCaptions = parsedCaptions;
+    if (parsedCaptions.length !== validCaptionData.length) {
+      this.logger.warn(
+        `[DocumentProcessor] Caption parsing length mismatch for ${resourceType}: expected ${validCaptionData.length}, got ${parsedCaptions.length}. Attempting recovery by matching fullText...`
+      );
+      const parsedMap = /* @__PURE__ */ new Map();
+      for (const parsed of parsedCaptions) {
+        parsedMap.set(parsed.fullText, parsed);
+      }
+      const recoveredData = [];
+      for (const item of validCaptionData) {
+        if (parsedMap.has(item.text)) {
+          recoveredData.push(item);
+        } else {
+          this.logger.warn(
+            `[DocumentProcessor] Skipping ${resourceType} caption at index ${item.resourceIndex}: "${item.text}" (not found in parsed results)`
+          );
+        }
+      }
+      const recoveredCaptions = [];
+      for (const item of recoveredData) {
+        const caption = parsedMap.get(item.text);
+        if (caption) {
+          recoveredCaptions.push(caption);
+        }
+      }
+      if (recoveredCaptions.length !== recoveredData.length) {
+        throw new Error(
+          `[DocumentProcessor] Failed to recover from length mismatch: recovered ${recoveredCaptions.length} captions for ${recoveredData.length} valid items`
+        );
+      }
+      finalValidCaptionData = recoveredData;
+      finalParsedCaptions = recoveredCaptions;
+      this.logger.info(
+        `[DocumentProcessor] Successfully recovered ${finalParsedCaptions.length} ${resourceType} captions after length mismatch`
+      );
+    }
+    for (let i = 0; i < finalParsedCaptions.length; i++) {
+      const resourceIndex = finalValidCaptionData[i].resourceIndex;
+      captionsByIndex.set(resourceIndex, finalParsedCaptions[i]);
+    }
+    if (finalParsedCaptions.length > 0) {
+      const finalValidCaptionTexts = finalValidCaptionData.map(
+        (item) => item.text
+      );
+      const validationResults = await this.captionValidator.validateBatch(
+        finalParsedCaptions,
+        finalValidCaptionTexts,
+        this.captionValidatorBatchSize
+      );
+      const failedIndices = validationResults.map((isValid, index) => isValid ? -1 : index).filter((index) => index !== -1);
+      if (failedIndices.length > 0) {
+        for (const filteredIndex of failedIndices) {
+          const captionData = finalValidCaptionData[filteredIndex];
+          const originalText = captionData.text;
+          const parsedNum = finalParsedCaptions[filteredIndex].num;
+          const resourceIndex = captionData.resourceIndex;
+          this.logger.warn(
+            `[DocumentProcessor] Invalid ${resourceType} caption [${resourceIndex}]: "${originalText}" | parsed num="${parsedNum}"`
+          );
+        }
+        if (this.enableFallbackRetry) {
+          this.logger.info(
+            `[DocumentProcessor] Reparsing ${failedIndices.length} failed ${resourceType} captions with fallback model...`
+          );
+          const failedCaptionTexts = failedIndices.map(
+            (filteredIndex) => finalValidCaptionData[filteredIndex].text
+          );
+          const fallbackCaptionParser = new CaptionParser(
+            this.logger,
+            this.fallbackModel,
+            {
+              maxRetries: this.maxRetries,
+              componentName: "CaptionParser-fallback",
+              abortSignal: this.abortSignal
+            },
+            void 0,
+            // no fallback for the fallback
+            this.usageAggregator
+          );
+          const reparsedCaptions = await fallbackCaptionParser.parseBatch(
+            failedCaptionTexts,
+            0
+            // sequential processing
+          );
+          for (let i = 0; i < failedIndices.length; i++) {
+            const filteredIndex = failedIndices[i];
+            const resourceIndex = finalValidCaptionData[filteredIndex].resourceIndex;
+            captionsByIndex.set(resourceIndex, reparsedCaptions[i]);
+          }
+          this.logger.info(
+            `[DocumentProcessor] Reparsed ${reparsedCaptions.length} ${resourceType} captions`
+          );
+        } else {
+          this.logger.warn(
+            `[DocumentProcessor] ${failedIndices.length} ${resourceType} captions failed validation (kept as-is, fallback retry disabled)`
+          );
+        }
+      }
+    }
+    return captionsByIndex;
+  }
+  /**
+   * Extract caption text from resource
+   *
+   * Handles both string references and $ref resolution
+   */
+  extractCaptionText(captions) {
+    if (!captions?.[0]) {
+      return void 0;
+    }
+    const captionRef = captions[0];
+    if (typeof captionRef === "string") {
+      return captionRef;
+    }
+    if (this.refResolver && "$ref" in captionRef) {
+      const resolved = this.refResolver.resolveText(captionRef.$ref);
+      return resolved?.text;
+    }
+    return void 0;
+  }
+  /**
+   * Convert images
+   *
+   * Converts pictures from DoclingDocument to ProcessedImage
+   */
+  async convertImages(doclingDoc, outputPath) {
+    this.logger.info(
+      `[DocumentProcessor] Converting ${doclingDoc.pictures.length} images...`
+    );
+    const images = [];
+    const captionTexts = [];
+    for (const picture of doclingDoc.pictures) {
+      const pdfPageNo = picture.prov?.[0]?.page_no ?? 0;
+      const imageId = this.idGenerator?.generateImageId() ?? `img-${images.length + 1}`;
+      const captionText = this.extractCaptionText(picture.captions);
+      captionTexts.push(captionText);
+      images.push({
+        id: imageId,
+        path: `${outputPath}/images/image_${images.length}.png`,
+        pdfPageNo
+        // caption will be assigned later
+      });
+    }
+    const captionsByIndex = await this.processResourceCaptions(
+      captionTexts,
+      "image"
+    );
+    for (let i = 0; i < images.length; i++) {
+      if (captionsByIndex.has(i)) {
+        images[i].caption = captionsByIndex.get(i);
+      }
+    }
+    return images;
+  }
+  /**
+   * Convert tables
+   *
+   * Converts tables from DoclingDocument to ProcessedTable
+   */
+  async convertTables(doclingDoc) {
+    this.logger.info(
+      `[DocumentProcessor] Converting ${doclingDoc.tables.length} tables...`
+    );
+    const tables = [];
+    const captionTexts = [];
+    for (const table of doclingDoc.tables) {
+      const pdfPageNo = table.prov?.[0]?.page_no ?? 0;
+      const tableId = this.idGenerator?.generateTableId() ?? `tbl-${tables.length + 1}`;
+      const grid = table.data.grid.map(
+        (row) => row.map((cell) => ({
+          text: cell.text,
+          rowSpan: cell.row_span ?? 1,
+          colSpan: cell.col_span ?? 1,
+          isHeader: cell.column_header || cell.row_header || false
+        }))
+      );
+      const captionText = this.extractCaptionText(table.captions);
+      captionTexts.push(captionText);
+      tables.push({
+        id: tableId,
+        pdfPageNo,
+        numRows: grid.length,
+        numCols: grid[0]?.length ?? 0,
+        grid
+        // caption will be assigned later
+      });
+    }
+    const captionsByIndex = await this.processResourceCaptions(
+      captionTexts,
+      "table"
+    );
+    for (let i = 0; i < tables.length; i++) {
+      if (captionsByIndex.has(i)) {
+        tables[i].caption = captionsByIndex.get(i);
+      }
+    }
+    return tables;
+  }
+  /**
+   * Convert chapters and link resources
+   *
+   * Generates chapters based on TOC and links images/tables/footnotes using ChapterConverter.
+   * Falls back to single "Document" chapter when TOC is empty.
+   */
+  async convertChapters(doclingDoc, tocEntries, pageRangeMap, images, tables, footnotes) {
+    this.logger.info("[DocumentProcessor] Converting chapters...");
+    if (tocEntries.length === 0) {
+      this.logger.info(
+        "[DocumentProcessor] No TOC entries, creating fallback chapter"
+      );
+      return this.createFallbackChapter(
+        doclingDoc,
+        pageRangeMap,
+        images,
+        tables,
+        footnotes
+      );
+    }
+    const chapters = this.chapterConverter.convert(
+      tocEntries,
+      doclingDoc.texts,
+      pageRangeMap,
+      images,
+      tables,
+      footnotes
+    );
+    this.logger.info(
+      `[DocumentProcessor] Converted ${chapters.length} top-level chapters`
+    );
+    return chapters;
+  }
+  /**
+   * Create a fallback chapter when TOC is not available
+   *
+   * Creates a single "Document" chapter containing all text blocks,
+   * images, tables, and footnotes from the document.
+   */
+  createFallbackChapter(doclingDoc, pageRangeMap, images, tables, footnotes) {
+    const textBlocks = doclingDoc.texts.filter(
+      (item) => item.label !== "footnote" && this.textCleaner.isValidText(item.text)
+    ).map((item) => ({
+      text: this.textCleaner.normalize(item.text),
+      pdfPageNo: item.prov?.[0]?.page_no ?? 1
+    }));
+    if (textBlocks.length === 0 && images.length === 0 && tables.length === 0 && footnotes.length === 0) {
+      this.logger.info(
+        "[DocumentProcessor] No content found for fallback chapter"
+      );
+      return [];
+    }
+    const firstPdfPage = Math.min(
+      ...Object.keys(pageRangeMap).map(Number).filter((n) => !isNaN(n)),
+      1
+    );
+    const firstPageRange = pageRangeMap[firstPdfPage];
+    const pageNo = firstPageRange?.startPageNo ?? 1;
+    const fallbackChapter = {
+      id: this.idGenerator.generateChapterId(),
+      originTitle: "Document",
+      title: "Document",
+      pageNo,
+      level: 1,
+      textBlocks,
+      imageIds: images.map((img) => img.id),
+      tableIds: tables.map((tbl) => tbl.id),
+      footnoteIds: footnotes.map((ftn) => ftn.id),
+      children: []
+    };
+    this.logger.info(
+      `[DocumentProcessor] Created fallback chapter with ${textBlocks.length} text blocks, ${images.length} images, ${tables.length} tables, ${footnotes.length} footnotes`
+    );
+    return [fallbackChapter];
+  }
+};
+export {
+  BaseLLMComponent,
+  BaseValidator,
+  CONTINUATION_MARKERS,
+  CaptionParseError,
+  CaptionParser,
+  CaptionValidationError,
+  CaptionValidator,
+  ChapterConverter,
+  DocumentProcessor,
+  PAGE_NUMBER_PATTERN,
+  PagePattern,
+  PageRangeParseError,
+  PageRangeParser,
+  TOC_KEYWORDS,
+  TextLLMComponent,
+  TocContentValidationSchema,
+  TocContentValidator,
+  TocEntrySchema,
+  TocExtractError,
+  TocExtractor,
+  TocFinder,
+  TocNotFoundError,
+  TocParseError,
+  TocResponseSchema,
+  VisionLLMComponent,
+  VisionTocExtractionSchema,
+  VisionTocExtractor
+};
+//# sourceMappingURL=index.js.map