@heripo/pdf-parser 0.1.7 → 0.1.9

package/dist/index.js

@@ -1,15 +1,8 @@
-import {
-  DEFAULT_VLM_MODEL,
-  VLM_MODELS,
-  resolveVlmModel
-} from "./chunk-WWNI354M.js";
-import "./chunk-VUNV25KB.js";
-
 // src/core/pdf-parser.ts
 import { Docling } from "docling-sdk";
 import { execSync } from "child_process";
-import { platform as platform2 } from "os";
-import { join as join5 } from "path";
+import { platform } from "os";
+import { join as join7 } from "path";
 
 // src/config/constants.ts
 var PDF_PARSER = {
@@ -60,22 +53,48 @@ var IMAGE_PDF_CONVERTER = {
    */
   QUALITY: 100
 };
-var VLM_ENVIRONMENT = {
-  /**
-   * Timeout for VLM dependency installation (pip install) in milliseconds (3 hours).
-   * VLM packages can be very large and may require extended download times
-   * depending on network conditions.
-   */
-  SETUP_TIMEOUT_MS: 108e5,
-  /**
-   * Timeout for VLM model download in milliseconds (3 hours).
-   * Large VLM models (e.g., multi-GB weights) need sufficient time to download.
-   */
-  MODEL_DOWNLOAD_TIMEOUT_MS: 108e5
-};
 
 // ../shared/dist/index.mjs
 import { spawn } from "child_process";
+import {
+  NoObjectGeneratedError,
+  Output,
+  generateText,
+  hasToolCall,
+  tool
+} from "ai";
+var ConcurrentPool = class {
+  /**
+   * Process items concurrently using a worker pool pattern.
+   *
+   * Spawns up to `concurrency` workers that pull items from a shared queue.
+   * Each worker processes one item at a time; when it finishes, it immediately
+   * takes the next available item. Results maintain the original item order.
+   *
+   * @param items - Array of items to process
+   * @param concurrency - Maximum number of concurrent workers
+   * @param processFn - Async function to process each item
+   * @param onItemComplete - Optional callback fired after each item completes
+   * @returns Array of results in the same order as the input items
+   */
+  static async run(items, concurrency, processFn, onItemComplete) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    async function worker() {
+      while (nextIndex < items.length) {
+        const index = nextIndex++;
+        results[index] = await processFn(items[index], index);
+        onItemComplete?.(results[index], index);
+      }
+    }
+    const workers = Array.from(
+      { length: Math.min(concurrency, items.length) },
+      () => worker()
+    );
+    await Promise.all(workers);
+    return results;
+  }
+};
 function spawnAsync(command, args, options = {}) {
   const {
     captureStdout = true,
@@ -102,10 +121,456 @@ function spawnAsync(command, args, options = {}) {
     proc.on("error", reject);
   });
 }
+function detectProvider(model) {
+  const providerId = model.provider;
+  if (!providerId || typeof providerId !== "string") return "unknown";
+  if (providerId.includes("openai")) return "openai";
+  if (providerId.includes("google")) return "google";
+  if (providerId.includes("anthropic")) return "anthropic";
+  if (providerId.includes("together")) return "togetherai";
+  return "unknown";
+}
+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
+    };
+  }
+  /**
+   * Maximum number of retries when structured output generation fails.
+   * Total attempts = MAX_STRUCTURED_OUTPUT_RETRIES + 1.
+   *
+   * Applied to both:
+   * - `Output.object()` path: retries on NoObjectGeneratedError (schema mismatch)
+   * - Tool call path: retries when model does not produce a tool call
+   */
+  static MAX_STRUCTURED_OUTPUT_RETRIES = 10;
+  /**
+   * Generate structured output via forced tool call.
+   *
+   * Used for providers (Together AI, unknown) that do not reliably support
+   * `Output.object()`. Forces the model to call a tool whose inputSchema
+   * is the target Zod schema, then extracts the parsed input.
+   *
+   * Retries up to MAX_STRUCTURED_OUTPUT_RETRIES times when the model does not
+   * produce a tool call, for a total of MAX_STRUCTURED_OUTPUT_RETRIES + 1 attempts.
+   *
+   * @throws NoObjectGeneratedError when all attempts fail to produce a tool call
+   */
+  static async generateViaToolCall(model, schema, promptParams) {
+    const submitTool = tool({
+      description: "Submit the structured result",
+      inputSchema: schema
+    });
+    let lastResult;
+    for (let attempt = 0; attempt <= this.MAX_STRUCTURED_OUTPUT_RETRIES; attempt++) {
+      lastResult = await generateText({
+        ...promptParams,
+        model,
+        tools: { submitResult: submitTool },
+        toolChoice: { type: "tool", toolName: "submitResult" },
+        stopWhen: hasToolCall("submitResult")
+      });
+      const toolCall = lastResult.toolCalls?.[0];
+      if (toolCall) {
+        return {
+          output: toolCall.input,
+          usage: lastResult.usage
+        };
+      }
+    }
+    throw new NoObjectGeneratedError({
+      message: "Model did not produce a tool call for structured output",
+      text: lastResult.text ?? "",
+      response: lastResult.response,
+      usage: lastResult.usage,
+      finishReason: lastResult.finishReason
+    });
+  }
+  /**
+   * Generate structured output with provider-aware strategy.
+   *
+   * Strategy per provider:
+   * - OpenAI / Anthropic / Google Gemini: `Output.object()` with schema retry
+   * - Together AI / unknown: forced tool call pattern
+   *
+   * Retries up to MAX_STRUCTURED_OUTPUT_RETRIES times on NoObjectGeneratedError
+   * (schema mismatch), re-throwing the last error if all attempts fail.
+   */
+  static async generateStructuredOutput(model, schema, promptParams) {
+    const providerType = detectProvider(model);
+    if (providerType === "togetherai" || providerType === "unknown") {
+      return this.generateViaToolCall(model, schema, promptParams);
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= this.MAX_STRUCTURED_OUTPUT_RETRIES; attempt++) {
+      try {
+        return await generateText({
+          model,
+          output: Output.object({ schema }),
+          ...promptParams
+        });
+      } catch (error) {
+        if (NoObjectGeneratedError.isInstance(error)) {
+          lastError = error;
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw lastError;
+  }
+  /**
+   * Execute LLM call with fallback support
+   *
+   * Common execution logic for both text and vision calls.
+   * Logs additional details when NoObjectGeneratedError occurs.
+   */
+  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
+   *
+   * Provider-aware strategy is automatically applied based on the model's provider field.
+   *
+   * @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) => this.generateStructuredOutput(model, 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.
+   * Provider-aware strategy is automatically applied based on the model's provider field.
+   *
+   * @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) => this.generateStructuredOutput(model, 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/environment/docling-environment.ts
 import { spawn as spawn2 } from "child_process";
-import { arch, platform } from "os";
 import { join } from "path";
 
 // src/utils/python-version.ts
@@ -147,7 +612,6 @@ var DoclingEnvironment = class _DoclingEnvironment {
   venvPath;
   port;
   killExistingProcess;
-  vlmDependenciesInstalled = false;
   constructor(options) {
     this.logger = options.logger;
     this.venvPath = options.venvPath;
@@ -266,7 +730,11 @@ var DoclingEnvironment = class _DoclingEnvironment {
   }
   async installDoclingServe() {
     const pipPath = join(this.venvPath, "bin", "pip");
-    const result = await spawnAsync(pipPath, ["install", "docling-serve"]);
+    const result = await spawnAsync(pipPath, [
+      "install",
+      "--upgrade",
+      "docling-serve"
+    ]);
     if (result.code !== 0) {
       this.logger.error(
         "[DoclingEnvironment] Failed to install docling-serve:",
@@ -277,81 +745,6 @@ var DoclingEnvironment = class _DoclingEnvironment {
       );
     }
   }
-  /**
-   * Install VLM-specific dependencies for the Docling VLM pipeline.
-   *
-   * Installs:
-   * 1. docling-serve[vlm] - VLM model support for docling-serve
-   * 2. mlx + mlx-lm (macOS ARM64 only) - Apple Silicon optimized inference
-   *
-   * This is idempotent - subsequent calls skip if already installed.
-   */
-  async setupVlmDependencies() {
-    if (this.vlmDependenciesInstalled) {
-      this.logger.info(
-        "[DoclingEnvironment] VLM dependencies already installed, skipping"
-      );
-      return;
-    }
-    if (await this.isVlmReady()) {
-      this.vlmDependenciesInstalled = true;
-      this.logger.info(
-        "[DoclingEnvironment] VLM dependencies already installed, skipping"
-      );
-      return;
-    }
-    this.logger.info("[DoclingEnvironment] Installing VLM dependencies...");
-    const pipPath = join(this.venvPath, "bin", "pip");
-    this.logger.info("[DoclingEnvironment] Installing docling[vlm]...");
-    const vlmResult = await spawnAsync(
-      pipPath,
-      ["install", "docling-serve[vlm]"],
-      { timeout: VLM_ENVIRONMENT.SETUP_TIMEOUT_MS }
-    );
-    if (vlmResult.code !== 0) {
-      this.logger.error(
-        "[DoclingEnvironment] Failed to install docling-serve[vlm]:",
-        vlmResult.stderr
-      );
-      throw new Error(
-        `Failed to install docling-serve[vlm]. Exit code: ${vlmResult.code}`
-      );
-    }
-    if (platform() === "darwin" && arch() === "arm64") {
-      this.logger.info(
-        "[DoclingEnvironment] Installing mlx + mlx-lm for Apple Silicon..."
-      );
-      const mlxResult = await spawnAsync(
-        pipPath,
-        ["install", "mlx", "mlx-lm"],
-        { timeout: VLM_ENVIRONMENT.SETUP_TIMEOUT_MS }
-      );
-      if (mlxResult.code !== 0) {
-        this.logger.error(
-          "[DoclingEnvironment] Failed to install mlx/mlx-lm:",
-          mlxResult.stderr
-        );
-        throw new Error(
-          `Failed to install mlx/mlx-lm. Exit code: ${mlxResult.code}`
-        );
-      }
-    }
-    this.vlmDependenciesInstalled = true;
-    this.logger.info(
-      "[DoclingEnvironment] VLM dependencies installed successfully"
-    );
-  }
-  /**
-   * Check if VLM dependencies are ready by verifying Python module imports
-   */
-  async isVlmReady() {
-    const pythonPath = join(this.venvPath, "bin", "python");
-    const result = await spawnAsync(pythonPath, [
-      "-c",
-      "import docling_core; import docling"
-    ]);
-    return result.code === 0;
-  }
   async isPortInUse(port) {
     try {
       const result = await spawnAsync("lsof", ["-ti", `:${port}`]);
@@ -422,8 +815,13 @@ var DoclingEnvironment = class _DoclingEnvironment {
       const doclingProcess = spawn2(doclingServePath, args, {
         detached: true,
         // Detached from parent process
-        stdio: "ignore"
+        stdio: "ignore",
         // Remove stdio pipes to prevent event loop from hanging
+        env: {
+          ...process.env,
+          // Enable remote API calls for API VLM models
+          DOCLING_SERVE_ENABLE_REMOTE_SERVICES: "true"
+        }
       });
       doclingProcess.unref();
       doclingProcess.on("error", (error) => {
@@ -438,10 +836,16 @@ var DoclingEnvironment = class _DoclingEnvironment {
 };
 
 // src/core/pdf-converter.ts
-import { ValidationUtils } from "docling-sdk";
 import { omit } from "es-toolkit";
-import { createWriteStream as createWriteStream2, existsSync as existsSync3, rmSync as rmSync3 } from "fs";
-import { join as join4 } from "path";
+import {
+  copyFileSync,
+  createWriteStream as createWriteStream2,
+  existsSync as existsSync4,
+  readFileSync as readFileSync4,
+  rmSync as rmSync3
+} from "fs";
+import { writeFile } from "fs/promises";
+import { join as join6 } from "path";
 import { pipeline } from "stream/promises";
 
 // src/errors/image-pdf-fallback-error.ts
@@ -638,28 +1042,28 @@ var ImageExtractor = class _ImageExtractor {
     const baseName = filename.replace(extname(filename), "");
     const jsonPath = join2(outputDir, `${baseName}.json`);
     try {
-      const pagesDir = join2(outputDir, "pages");
-      if (!existsSync(pagesDir)) {
-        mkdirSync(pagesDir, { recursive: true });
+      const imagesDir = join2(outputDir, "images");
+      if (!existsSync(imagesDir)) {
+        mkdirSync(imagesDir, { recursive: true });
       }
       const base64Images = await _ImageExtractor.extractBase64ImagesFromJsonWithJq(jsonSourcePath);
       base64Images.forEach((base64Data, index) => {
         _ImageExtractor.extractBase64ImageToFile(
           base64Data,
-          pagesDir,
+          imagesDir,
           index,
-          "page",
-          "pages"
+          "pic",
+          "images"
         );
       });
       logger.info(
-        `[PDFConverter] Extracted ${base64Images.length} images from JSON to ${pagesDir}`
+        `[PDFConverter] Extracted ${base64Images.length} picture images from JSON to ${imagesDir}`
       );
       const replacedCount = await _ImageExtractor.replaceBase64ImagesInJsonWithJq(
         jsonSourcePath,
         jsonPath,
-        "pages",
-        "page"
+        "images",
+        "pic"
       );
       logger.info(
         `[PDFConverter] Replaced ${replacedCount} base64 images with file paths`
@@ -742,52 +1146,968 @@ var ImageExtractor = class _ImageExtractor {
   }
 };
 
-// src/utils/local-file-server.ts
-import { createReadStream, statSync } from "fs";
-import { createServer } from "http";
-import { basename } from "path";
-var LocalFileServer = class {
-  server = null;
-  port = 0;
+// src/processors/page-renderer.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync as readdirSync2 } from "fs";
+import { join as join3 } from "path";
+var DEFAULT_DPI = 300;
+var PageRenderer = class {
+  constructor(logger) {
+    this.logger = logger;
+  }
   /**
-   * Start serving a file and return the URL
+   * Render all pages of a PDF to individual PNG files.
    *
-   * @param filePath Absolute path to the file to serve
-   * @returns URL to access the file
+   * @param pdfPath - Absolute path to the source PDF file
+   * @param outputDir - Directory where pages/ subdirectory will be created
+   * @param options - Rendering options
+   * @returns Render result with page count and file paths
    */
-  async start(filePath) {
-    const filename = basename(filePath);
-    const stat = statSync(filePath);
-    return new Promise((resolve, reject) => {
-      this.server = createServer((req, res) => {
-        if (req.url === `/${filename}`) {
-          res.writeHead(200, {
-            "Content-Type": "application/pdf",
-            "Content-Length": stat.size
-          });
-          createReadStream(filePath).pipe(res);
-        } else {
-          res.writeHead(404);
-          res.end("Not Found");
-        }
-      });
-      this.server.on("error", reject);
-      this.server.listen(0, "127.0.0.1", () => {
-        const address = this.server.address();
-        if (typeof address === "object" && address !== null) {
-          this.port = address.port;
-          resolve(`http://127.0.0.1:${this.port}/${filename}`);
-        } else {
-          reject(new Error("Failed to get server address"));
-        }
-      });
-    });
+  async renderPages(pdfPath, outputDir, options) {
+    const dpi = options?.dpi ?? DEFAULT_DPI;
+    const pagesDir = join3(outputDir, "pages");
+    if (!existsSync2(pagesDir)) {
+      mkdirSync2(pagesDir, { recursive: true });
+    }
+    this.logger.info(`[PageRenderer] Rendering PDF at ${dpi} DPI...`);
+    const outputPattern = join3(pagesDir, "page_%d.png");
+    const result = await spawnAsync("magick", [
+      "-density",
+      dpi.toString(),
+      pdfPath,
+      "-background",
+      "white",
+      "-alpha",
+      "remove",
+      "-alpha",
+      "off",
+      outputPattern
+    ]);
+    if (result.code !== 0) {
+      throw new Error(
+        `[PageRenderer] Failed to render PDF pages: ${result.stderr || "Unknown error"}`
+      );
+    }
+    const pageFiles = readdirSync2(pagesDir).filter((f) => f.startsWith("page_") && f.endsWith(".png")).sort((a, b) => {
+      const numA = parseInt(a.replace("page_", "").replace(".png", ""), 10);
+      const numB = parseInt(b.replace("page_", "").replace(".png", ""), 10);
+      return numA - numB;
+    }).map((f) => join3(pagesDir, f));
+    this.logger.info(
+      `[PageRenderer] Rendered ${pageFiles.length} pages to ${pagesDir}`
+    );
+    return {
+      pageCount: pageFiles.length,
+      pagesDir,
+      pageFiles
+    };
+  }
+};
+
+// src/processors/pdf-text-extractor.ts
+var PdfTextExtractor = class {
+  constructor(logger) {
+    this.logger = logger;
   }
   /**
-   * Stop the server
+   * Extract text from all pages of a PDF.
+   *
+   * @param pdfPath - Absolute path to the source PDF file
+   * @param totalPages - Total number of pages in the PDF
+   * @returns Map of 1-based page numbers to extracted text strings
    */
-  stop() {
-    return new Promise((resolve) => {
+  async extractText(pdfPath, totalPages) {
+    this.logger.info(
+      `[PdfTextExtractor] Extracting text from ${totalPages} pages...`
+    );
+    const pageTexts = /* @__PURE__ */ new Map();
+    for (let page = 1; page <= totalPages; page++) {
+      const text = await this.extractPageText(pdfPath, page);
+      pageTexts.set(page, text);
+    }
+    const nonEmptyCount = [...pageTexts.values()].filter(
+      (t) => t.trim().length > 0
+    ).length;
+    this.logger.info(
+      `[PdfTextExtractor] Extracted text from ${nonEmptyCount}/${totalPages} pages`
+    );
+    return pageTexts;
+  }
+  /**
+   * Get total page count of a PDF using pdfinfo.
+   * Returns 0 on failure.
+   */
+  async getPageCount(pdfPath) {
+    const result = await spawnAsync("pdfinfo", [pdfPath]);
+    if (result.code !== 0) {
+      this.logger.warn(
+        `[PdfTextExtractor] pdfinfo failed: ${result.stderr || "Unknown error"}`
+      );
+      return 0;
+    }
+    const match = result.stdout.match(/^Pages:\s+(\d+)/m);
+    return match ? parseInt(match[1], 10) : 0;
+  }
+  /**
+   * Extract text from the entire PDF in a single pdftotext invocation.
+   * Returns empty string on failure (logged as warning).
+   */
+  async extractFullText(pdfPath) {
+    const result = await spawnAsync("pdftotext", ["-layout", pdfPath, "-"]);
+    if (result.code !== 0) {
+      this.logger.warn(
+        `[PdfTextExtractor] pdftotext (full) failed: ${result.stderr || "Unknown error"}`
+      );
+      return "";
+    }
+    return result.stdout;
+  }
+  /**
+   * Extract text from a single PDF page using pdftotext.
+   * Returns empty string on failure (logged as warning).
+   */
+  async extractPageText(pdfPath, page) {
+    const result = await spawnAsync("pdftotext", [
+      "-f",
+      page.toString(),
+      "-l",
+      page.toString(),
+      "-layout",
+      pdfPath,
+      "-"
+    ]);
+    if (result.code !== 0) {
+      this.logger.warn(
+        `[PdfTextExtractor] pdftotext failed for page ${page}: ${result.stderr || "Unknown error"}`
+      );
+      return "";
+    }
+    return result.stdout;
+  }
+};
+
+// src/processors/vlm-text-corrector.ts
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { join as join4 } from "path";
+
+// src/types/vlm-text-correction-schema.ts
+import { z } from "zod/v4";
+var vlmTextCorrectionSchema = z.object({
+  /** Text element corrections (substitution-based) */
+  tc: z.array(
+    z.object({
+      /** Text element index (from prompt) */
+      i: z.number().int().nonnegative(),
+      /** Substitutions: find/replace pairs applied left-to-right */
+      s: z.array(
+        z.object({
+          /** Exact garbled substring to find */
+          f: z.string(),
+          /** Corrected replacement text */
+          r: z.string()
+        })
+      )
+    })
+  ),
+  /** Table cell corrections */
+  cc: z.array(
+    z.object({
+      /** Table index (within the page) */
+      ti: z.number().int().nonnegative(),
+      /** Row index */
+      r: z.number().int().nonnegative(),
+      /** Column index */
+      c: z.number().int().nonnegative(),
+      /** Corrected cell text */
+      t: z.string()
+    })
+  )
+});
+
+// src/processors/vlm-text-corrector.ts
+var LANGUAGE_DISPLAY_NAMES = {
+  ko: "Korean (\uD55C\uAD6D\uC5B4)",
+  ja: "Japanese (\u65E5\u672C\u8A9E)",
+  zh: "Chinese (\u4E2D\u6587)",
+  en: "English",
+  fr: "French (Fran\xE7ais)",
+  de: "German (Deutsch)",
+  es: "Spanish (Espa\xF1ol)",
+  pt: "Portuguese (Portugu\xEAs)",
+  ru: "Russian (\u0420\u0443\u0441\u0441\u043A\u0438\u0439)",
+  uk: "Ukrainian (\u0423\u043A\u0440\u0430\u0457\u043D\u0441\u044C\u043A\u0430)",
+  it: "Italian (Italiano)"
+};
+var REFERENCE_MATCH_THRESHOLD = 0.4;
+var DEFAULT_CONCURRENCY = 1;
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_TEMPERATURE = 0;
+var LABEL_TO_TYPE_CODE = {
+  section_header: "sh",
+  text: "tx",
+  caption: "ca",
+  footnote: "fn",
+  list_item: "li",
+  page_header: "ph",
+  page_footer: "pf"
+};
+var TEXT_LABELS = new Set(Object.keys(LABEL_TO_TYPE_CODE));
+var TEXT_CORRECTION_SYSTEM_PROMPT = `You are a text correction engine for OCR output from Korean archaeological (\u8003\u53E4\u5B78) report PDFs. Compare OCR text against the page image and reference text to fix errors.
+
+The OCR engine cannot read Chinese characters (\u6F22\u5B57/Hanja) correctly. These errors appear as:
+- Random ASCII letters/symbols: \u718A\u6D25 \u2192 "M", \u5C0F\u4EAC\u5236 \u2192 "5\u2606", \u6545\u5740 \u2192 "Bbt"
+- Meaningless Korean syllables: \u6771\u660E \u2192 "\uD587\uBC30", \u91D1\u61B2\u660C \u2192 "\uC232", \u7E3D\u7BA1 \u2192 "3\uC501"
+- Number/symbol noise: \u718A\u5DDD\u5DDE \u2192 "IEJIM", \u6E6F\u4E95\u90E1 \u2192 "3#"
+- Hanja dropped entirely: (\u682A)\u97D3\u570B\u7E96\u7DAD \u2192 (\uC8FC), (\u8CA1)\u5FE0\u6DF8\u6587\u5316\u8CA1\u784F\u7A76\u9662 \u2192 (\uC7AC)\uCDA9\uB0A8\uBB38\uD654\uC7AC\uC5F0\uAD6C\uC6D0
+- Phonetic reading substitution (\u97F3\u8B80): \u6F22\u5B57 replaced by Korean pronunciation, e.g. \u5FE0\u6DF8\u6587\u5316\u8CA1\u784F\u7A76\u9662 \u2192 \uCDA9\uB0A8\uBB38\uD654\uC7AC\uC5F0\uAD6C\uC6D0, \u5BE6\u7389\u6D1E\u907A\u8E5F \u2192 \uC2E4\uC625\uB3D9\uC720\uC801
+
+FIX: garbled/wrong Chinese characters, mojibake, encoding artifacts, random ASCII/Korean replacing Hanja, dropped Hanja, phonetic reading substitutions
+KEEP: correct text, structure, punctuation, whitespace
+
+Input format:
+T: (text elements) index|type|text
+   Optional: index|ref|reference_text (PDF text layer for the above element)
+C: (table cells) tableIndex|row,col|text
+   Optional: C_REF: (unused pdftotext blocks as table reference)
+
+FOOTNOTE (fn) SPECIAL INSTRUCTIONS:
+- Footnotes in archaeological reports contain institution names with Hanja that are severely garbled
+- Common pattern: (\u8CA1)\u6A5F\u95DC\u540D\u784F\u7A76\u9662 \u2192 (W)#X1CR003T or (W): 103 or similar ASCII noise
+- When OCR shows patterns like (W), (M), or random ASCII where an institution name should be, READ THE IMAGE directly
+- Institution names follow patterns like: (\u8CA1)OO\u6587\u5316\u8CA1\u784F\u7A76\u9662, (\u682A)OO, (\u793E)OO\u5B78\u6703
+
+TABLE CELL (C:) SPECIAL INSTRUCTIONS:
+- Table headers often contain Hanja that OCR cannot read: \u767C\u520A\u65E5, \u6642\u4EE3, \u8ABF\u67FB\u7DE3\u7531, \u8ABF\u67FB\u6A5F\u95DC, \u907A\u8E5F\u540D, \u985E\u578B \uBC0F \u57FA\u6578
+- When OCR shows garbled characters like "\u20A9 A", "#\uCA6F\uBC0F\uD45C\uBF70" in table cells, READ THE IMAGE directly
+- If C_REF is present, use it as additional context for correcting table cells
+
+When a |ref| line is present:
+- It shows text extracted directly from the PDF text layer for that element
+- If OCR text contains garbled characters but ref text looks correct, USE the ref text
+- For long paragraphs, align OCR and ref text segment by segment to identify and fix each garbled portion
+- IMPORTANT: If BOTH OCR and ref text are garbled (e.g. CJK font encoding issues), IGNORE the ref text and READ THE IMAGE directly
+
+When NO |ref| line is present:
+- The PDF text layer could not be matched to this element
+- READ THE IMAGE directly to determine the correct text
+
+Output JSON with corrections:
+tc=[{i:index, s:[{f:"garbled_substring",r:"corrected_text"}, ...]}] for text
+cc=[{ti:tableIndex, r:row, c:col, t:corrected}] for table cells
+
+Substitution rules for tc:
+- 'f': exact garbled/wrong substring from the input text (must match exactly)
+- 'r': the corrected replacement
+- Include ALL garbled portions for each element as separate s entries
+- Order substitutions left-to-right as they appear in the text
+- Do NOT include unchanged text \u2014 only the specific substrings that need fixing
+
+If all correct: {"tc":[],"cc":[]}`;
+var VlmTextCorrector = class {
+  constructor(logger) {
+    this.logger = logger;
+  }
+  /**
+   * Read DoclingDocument from output directory, correct text via VLM,
+   * and save the corrected document back.
+   *
+   * @param outputDir - Directory containing result.json and pages/
+   * @param model - Vision language model for text correction
+   * @param options - Processing options
+   * @returns Correction statistics
+   */
+  async correctAndSave(outputDir, model, options) {
+    this.logger.info("[VlmTextCorrector] Starting text correction...");
+    const resultPath = join4(outputDir, "result.json");
+    const doc = JSON.parse(readFileSync2(resultPath, "utf-8"));
+    let pageNumbers = this.getPageNumbers(doc);
+    if (pageNumbers.length === 0) {
+      this.logger.info("[VlmTextCorrector] No pages to process");
+      return {
+        textCorrections: 0,
+        cellCorrections: 0,
+        pagesProcessed: 0,
+        pagesFailed: 0
+      };
+    }
+    if (options?.koreanHanjaMixPages && options.koreanHanjaMixPages.length > 0) {
+      const totalPageCount = pageNumbers.length;
+      const hanjaSet = new Set(options.koreanHanjaMixPages);
+      pageNumbers = pageNumbers.filter((p) => hanjaSet.has(p));
+      this.logger.info(
+        `[VlmTextCorrector] Filtering to ${pageNumbers.length} Korean-Hanja mix pages out of ${totalPageCount} total`
+      );
+    }
+    const concurrency = options?.concurrency ?? DEFAULT_CONCURRENCY;
+    this.logger.info(
+      `[VlmTextCorrector] Processing ${pageNumbers.length} pages (concurrency: ${concurrency})...`
+    );
+    const results = await ConcurrentPool.run(
+      pageNumbers,
+      concurrency,
+      (pageNo) => this.correctPage(outputDir, doc, pageNo, model, options),
+      () => {
+        if (options?.onTokenUsage && options?.aggregator) {
+          options.onTokenUsage(
+            options.aggregator.getReport()
+          );
+        }
+      }
+    );
+    let totalTextCorrections = 0;
+    let totalCellCorrections = 0;
+    let pagesFailed = 0;
+    for (const result of results) {
+      if (result === null) {
+        pagesFailed++;
+      } else {
+        totalTextCorrections += result.tc.length;
+        totalCellCorrections += result.cc.length;
+      }
+    }
+    for (let i = 0; i < pageNumbers.length; i++) {
+      const corrections = results[i];
+      if (corrections === null) continue;
+      this.applyCorrections(doc, pageNumbers[i], corrections);
+    }
+    writeFileSync2(resultPath, JSON.stringify(doc, null, 2));
+    this.logger.info(
+      `[VlmTextCorrector] Correction complete: ${totalTextCorrections} text, ${totalCellCorrections} cell corrections across ${pageNumbers.length} pages (${pagesFailed} failed)`
+    );
+    return {
+      textCorrections: totalTextCorrections,
+      cellCorrections: totalCellCorrections,
+      pagesProcessed: pageNumbers.length,
+      pagesFailed
+    };
+  }
+  /**
+   * Get sorted page numbers from the document.
+   */
+  getPageNumbers(doc) {
+    return Object.values(doc.pages).map((p) => p.page_no).sort((a, b) => a - b);
+  }
+  /**
+   * Correct text on a single page via VLM.
+   * Returns null if VLM call fails (graceful degradation).
+   */
+  async correctPage(outputDir, doc, pageNo, model, options) {
+    try {
+      const pageTexts = this.getPageTexts(doc, pageNo);
+      const pageTables = this.getPageTables(doc, pageNo);
+      if (pageTexts.length === 0 && pageTables.length === 0) {
+        this.logger.debug(
+          `[VlmTextCorrector] Page ${pageNo}: no text content, skipping`
+        );
+        return { tc: [], cc: [] };
+      }
+      const imageBase64 = this.readPageImage(outputDir, pageNo);
+      const pageText = options?.pageTexts?.get(pageNo);
+      let references;
+      let tableContext;
+      if (pageText) {
+        const { references: refs, unusedBlocks } = this.matchTextToReferenceWithUnused(pageTexts, pageText);
+        references = refs;
+        if (pageTables.length > 0 && unusedBlocks.length > 0) {
+          tableContext = unusedBlocks.join("\n");
+        }
+      }
+      const userPrompt = this.buildUserPrompt(
+        pageTexts,
+        pageTables,
+        references,
+        tableContext
+      );
+      const systemPrompt = this.buildLanguageAwareSystemPrompt(
+        options?.documentLanguages
+      );
+      const fullPrompt = systemPrompt + "\n\n" + userPrompt;
+      const result = await LLMCaller.callVision({
+        schema: vlmTextCorrectionSchema,
+        messages: [
+          {
+            role: "user",
+            content: [
+              {
+                type: "text",
+                text: fullPrompt
+              },
+              {
+                type: "image",
+                image: `data:image/png;base64,${imageBase64}`
+              }
+            ]
+          }
+        ],
+        primaryModel: model,
+        maxRetries: options?.maxRetries ?? DEFAULT_MAX_RETRIES,
+        temperature: options?.temperature ?? DEFAULT_TEMPERATURE,
+        abortSignal: options?.abortSignal,
+        component: "VlmTextCorrector",
+        phase: "text-correction"
+      });
+      if (options?.aggregator) {
+        options.aggregator.track(result.usage);
+      }
+      const output = result.output;
+      if (output.tc.length > 0 || output.cc.length > 0) {
+        this.logger.debug(
+          `[VlmTextCorrector] Page ${pageNo}: ${output.tc.length} text, ${output.cc.length} cell corrections`
+        );
+      }
+      return output;
+    } catch (error) {
+      if (options?.abortSignal?.aborted) {
+        throw error;
+      }
+      this.logger.warn(
+        `[VlmTextCorrector] Page ${pageNo}: VLM correction failed, keeping OCR text`,
+        error
+      );
+      return null;
+    }
+  }
+  /**
+   * Get text items on a specific page, with their indices for prompt building.
+   */
+  getPageTexts(doc, pageNo) {
+    const results = [];
+    for (let i = 0; i < doc.texts.length; i++) {
+      const item = doc.texts[i];
+      if (!TEXT_LABELS.has(item.label)) continue;
+      if (item.prov.some((p) => p.page_no === pageNo)) {
+        results.push({ index: i, item });
+      }
+    }
+    return results;
+  }
+  /**
+   * Get table items on a specific page, with their indices.
+   */
+  getPageTables(doc, pageNo) {
+    const results = [];
+    for (let i = 0; i < doc.tables.length; i++) {
+      const item = doc.tables[i];
+      if (item.prov.some((p) => p.page_no === pageNo)) {
+        results.push({ index: i, item });
+      }
+    }
+    return results;
+  }
+  /**
+   * Build compact user prompt for a page.
+   *
+   * Format:
+   * T:
+   * 0|sh|제1장 조사개요
+   * 1|tx|본 보고서는 ...
+   * C:
+   * 0|0,0|유구명
+   * 0|1,0|1호 住居址
+   */
+  buildUserPrompt(pageTexts, pageTables, references, tableContext) {
+    const parts = [];
+    if (pageTexts.length > 0) {
+      const textLines = [];
+      pageTexts.forEach((entry, promptIndex) => {
+        const typeCode = LABEL_TO_TYPE_CODE[entry.item.label] ?? "tx";
+        textLines.push(`${promptIndex}|${typeCode}|${entry.item.text}`);
+        const ref = references?.get(promptIndex);
+        if (ref) {
+          textLines.push(`${promptIndex}|ref|${ref}`);
+        }
+      });
+      parts.push("T:\n" + textLines.join("\n"));
+    }
+    if (pageTables.length > 0) {
+      const cellLines = [];
+      for (let tablePromptIndex = 0; tablePromptIndex < pageTables.length; tablePromptIndex++) {
+        const table = pageTables[tablePromptIndex].item;
+        for (const cell of table.data.table_cells) {
+          if (!cell.text || cell.text.trim().length === 0) continue;
+          cellLines.push(
+            `${tablePromptIndex}|${cell.start_row_offset_idx},${cell.start_col_offset_idx}|${cell.text}`
+          );
+        }
+      }
+      if (cellLines.length > 0) {
+        const cellSection = "C:\n" + cellLines.join("\n");
+        if (tableContext) {
+          parts.push(cellSection + "\nC_REF:\n" + tableContext);
+        } else {
+          parts.push(cellSection);
+        }
+      }
+    }
+    return parts.join("\n");
+  }
+  /**
+   * Build a language-aware system prompt by prepending language context.
+   */
+  buildLanguageAwareSystemPrompt(documentLanguages) {
+    if (!documentLanguages?.length) {
+      return TEXT_CORRECTION_SYSTEM_PROMPT;
+    }
+    const primaryBase = documentLanguages[0].split("-")[0];
+    const primaryName = LANGUAGE_DISPLAY_NAMES[primaryBase] ?? documentLanguages[0];
+    const otherNames = documentLanguages.slice(1).map((code) => LANGUAGE_DISPLAY_NAMES[code.split("-")[0]] ?? code);
+    const languageDesc = otherNames.length > 0 ? `primarily written in ${primaryName}, with ${otherNames.join(", ")} also present` : `written in ${primaryName}`;
+    const prefix = `LANGUAGE CONTEXT: This document is ${languageDesc}. Focus on correcting characters that do not match this language.
+
+`;
+    return prefix + TEXT_CORRECTION_SYSTEM_PROMPT;
+  }
+  /**
+   * Match pdftotext paragraph blocks to OCR elements using character multiset overlap.
+   * Returns a map from prompt index to the best-matching reference block.
+   */
+  matchTextToReference(pageTexts, pageText) {
+    return this.matchTextToReferenceWithUnused(pageTexts, pageText).references;
+  }
+  /**
+   * Match pdftotext paragraph blocks to OCR elements and also return unused blocks.
+   * Unused blocks are those that were not consumed by any text element match.
+   */
+  matchTextToReferenceWithUnused(pageTexts, pageText) {
+    const references = /* @__PURE__ */ new Map();
+    const refBlocks = this.mergeIntoBlocks(pageText);
+    if (refBlocks.length === 0) {
+      return { references, unusedBlocks: [] };
+    }
+    const available = new Set(refBlocks.map((_, i) => i));
+    for (let promptIndex = 0; promptIndex < pageTexts.length; promptIndex++) {
+      const ocrText = pageTexts[promptIndex].item.text;
+      let bestScore = 0;
+      let bestBlockIndex = -1;
+      for (const blockIndex of available) {
+        const score = this.computeCharOverlap(ocrText, refBlocks[blockIndex]);
+        if (score > bestScore) {
+          bestScore = score;
+          bestBlockIndex = blockIndex;
+        }
+      }
+      if (bestBlockIndex >= 0 && bestScore >= REFERENCE_MATCH_THRESHOLD) {
+        if (refBlocks[bestBlockIndex] !== ocrText) {
+          references.set(promptIndex, refBlocks[bestBlockIndex]);
+        }
+        available.delete(bestBlockIndex);
+      }
+    }
+    const unusedBlocks = [...available].sort((a, b) => a - b).map((i) => refBlocks[i]);
+    return { references, unusedBlocks };
+  }
+  /**
+   * Merge pdftotext output into paragraph blocks separated by blank lines.
+   * Consecutive non-empty lines are joined with a space.
+   */
+  mergeIntoBlocks(pageText) {
+    const blocks = [];
+    let currentLines = [];
+    for (const rawLine of pageText.split("\n")) {
+      const trimmed = rawLine.trim();
+      if (trimmed.length === 0) {
+        if (currentLines.length > 0) {
+          blocks.push(currentLines.join(" "));
+          currentLines = [];
+        }
+      } else {
+        currentLines.push(trimmed);
+      }
+    }
+    if (currentLines.length > 0) {
+      blocks.push(currentLines.join(" "));
+    }
+    return blocks;
+  }
+  /**
+   * Compute character multiset overlap ratio between two strings.
+   * Returns a value between 0.0 and 1.0.
+   */
+  computeCharOverlap(a, b) {
+    if (a.length === 0 || b.length === 0) return 0;
+    const freqA = /* @__PURE__ */ new Map();
+    for (const ch of a) {
+      freqA.set(ch, (freqA.get(ch) ?? 0) + 1);
+    }
+    const freqB = /* @__PURE__ */ new Map();
+    for (const ch of b) {
+      freqB.set(ch, (freqB.get(ch) ?? 0) + 1);
+    }
+    let overlap = 0;
+    for (const [ch, countA] of freqA) {
+      const countB = freqB.get(ch) ?? 0;
+      overlap += Math.min(countA, countB);
+    }
+    return overlap / Math.max(a.length, b.length);
+  }
+  /**
+   * Read page image as base64.
+   * Page images are 0-indexed: page_no N → pages/page_{N-1}.png
+   */
+  readPageImage(outputDir, pageNo) {
+    const imagePath = join4(outputDir, "pages", `page_${pageNo - 1}.png`);
+    return readFileSync2(imagePath).toString("base64");
+  }
+  /**
+   * Apply VLM corrections to the DoclingDocument.
+   */
+  applyCorrections(doc, pageNo, corrections) {
+    if (corrections.tc.length > 0) {
+      const pageTexts = this.getPageTexts(doc, pageNo);
+      for (const correction of corrections.tc) {
+        if (correction.i >= 0 && correction.i < pageTexts.length) {
+          const docIndex = pageTexts[correction.i].index;
+          let text = doc.texts[docIndex].text;
+          for (const sub of correction.s) {
+            const idx = text.indexOf(sub.f);
+            if (idx >= 0) {
+              text = text.substring(0, idx) + sub.r + text.substring(idx + sub.f.length);
+            } else {
+              this.logger.warn(
+                `[VlmTextCorrector] Page ${pageNo}, text ${correction.i}: find string not found, skipping substitution`
+              );
+            }
+          }
+          if (text !== doc.texts[docIndex].text) {
+            doc.texts[docIndex].text = text;
+            doc.texts[docIndex].orig = text;
+          }
+        }
+      }
+    }
+    if (corrections.cc.length > 0) {
+      const pageTables = this.getPageTables(doc, pageNo);
+      for (const correction of corrections.cc) {
+        if (correction.ti >= 0 && correction.ti < pageTables.length) {
+          const table = pageTables[correction.ti].item;
+          for (const cell of table.data.table_cells) {
+            if (cell.start_row_offset_idx === correction.r && cell.start_col_offset_idx === correction.c) {
+              cell.text = correction.t;
+              break;
+            }
+          }
+          const gridRow = table.data.grid[correction.r];
+          if (gridRow) {
+            const gridCell = gridRow[correction.c];
+            if (gridCell) {
+              gridCell.text = correction.t;
+            }
+          }
+        }
+      }
+    }
+  }
+};
+
+// src/samplers/ocr-strategy-sampler.ts
+import { normalizeToBcp47 } from "@heripo/model";
+import { readFileSync as readFileSync3 } from "fs";
+import { z as z2 } from "zod/v4";
+var SAMPLE_DPI = 150;
+var EDGE_TRIM_RATIO = 0.1;
+var DEFAULT_MAX_SAMPLE_PAGES = 15;
+var DEFAULT_MAX_RETRIES2 = 3;
+var CJK_REGEX = /[\u4E00-\u9FFF]/;
+var HANGUL_REGEX = /[\uAC00-\uD7AF]/;
+var koreanHanjaMixSchema = z2.object({
+  hasKoreanHanjaMix: z2.boolean().describe(
+    "Whether the page contains any Hanja (\u6F22\u5B57/Chinese characters) mixed with Korean text"
+  ),
+  detectedLanguages: z2.array(z2.string()).describe(
+    'BCP 47 language tags of languages found on this page, ordered by prevalence (e.g., ["ko-KR", "en-US"])'
+  )
+});
+var KOREAN_HANJA_MIX_PROMPT = `Look at this page image carefully. Does it contain any Hanja (\u6F22\u5B57/Chinese characters) mixed with Korean text?
+
+Hanja examples: \u907A\u8E5F, \u767C\u6398, \u8ABF\u67FB, \u5831\u544A\u66F8, \u6587\u5316\u8CA1
+Note: Hanja are Chinese characters used in Korean documents, different from modern Korean (\uD55C\uAE00).
+
+Answer whether any Hanja characters are present on this page.
+
+Also identify all languages present on this page. Return an array of BCP 47 language tags ordered by prevalence (primary language first).
+Examples: ["ko-KR", "en-US"], ["ja-JP"], ["zh-TW", "en-US"]`;
+var OcrStrategySampler = class {
+  logger;
+  pageRenderer;
+  textExtractor;
+  constructor(logger, pageRenderer, textExtractor) {
+    this.logger = logger;
+    this.pageRenderer = pageRenderer;
+    this.textExtractor = textExtractor ?? new PdfTextExtractor(logger);
+  }
+  /**
+   * Sample pages from a PDF and determine the OCR strategy.
+   *
+   * @param pdfPath - Path to the PDF file
+   * @param outputDir - Directory for temporary rendered pages
+   * @param model - Vision language model for Korean-Hanja mix detection
+   * @param options - Sampling options
+   * @returns OcrStrategy with method ('ocrmac' or 'vlm') and metadata
+   */
+  async sample(pdfPath, outputDir, model, options) {
+    const maxSamplePages = options?.maxSamplePages ?? DEFAULT_MAX_SAMPLE_PAGES;
+    this.logger.info("[OcrStrategySampler] Starting OCR strategy sampling...");
+    const preCheckResult = await this.preCheckHanjaFromTextLayer(pdfPath);
+    if (preCheckResult) {
+      return preCheckResult;
+    }
+    const renderResult = await this.pageRenderer.renderPages(
+      pdfPath,
+      outputDir,
+      { dpi: SAMPLE_DPI }
+    );
+    if (renderResult.pageCount === 0) {
+      this.logger.info("[OcrStrategySampler] No pages found in PDF");
+      return {
+        method: "ocrmac",
+        reason: "No pages found in PDF",
+        sampledPages: 0,
+        totalPages: 0
+      };
+    }
+    const sampleIndices = this.selectSamplePages(
+      renderResult.pageCount,
+      maxSamplePages
+    );
+    this.logger.info(
+      `[OcrStrategySampler] Sampling ${sampleIndices.length} of ${renderResult.pageCount} pages: [${sampleIndices.map((i) => i + 1).join(", ")}]`
+    );
+    let sampledCount = 0;
+    const languageFrequency = /* @__PURE__ */ new Map();
+    for (const idx of sampleIndices) {
+      sampledCount++;
+      const pageFile = renderResult.pageFiles[idx];
+      const pageAnalysis = await this.analyzeSamplePage(
+        pageFile,
+        idx + 1,
+        model,
+        options
+      );
+      for (const lang of pageAnalysis.detectedLanguages) {
+        languageFrequency.set(lang, (languageFrequency.get(lang) ?? 0) + 1);
+      }
+      if (pageAnalysis.hasKoreanHanjaMix) {
+        this.logger.info(
+          `[OcrStrategySampler] Korean-Hanja mix detected on page ${idx + 1} \u2192 VLM strategy`
+        );
+        const detectedLanguages2 = this.aggregateLanguages(languageFrequency);
+        return {
+          method: "vlm",
+          detectedLanguages: detectedLanguages2,
+          reason: `Korean-Hanja mix detected on page ${idx + 1}`,
+          sampledPages: sampledCount,
+          totalPages: renderResult.pageCount
+        };
+      }
+    }
+    this.logger.info(
+      "[OcrStrategySampler] No Korean-Hanja mix detected \u2192 ocrmac strategy"
+    );
+    const detectedLanguages = this.aggregateLanguages(languageFrequency);
+    return {
+      method: "ocrmac",
+      detectedLanguages,
+      reason: `No Korean-Hanja mix detected in ${sampledCount} sampled pages`,
+      sampledPages: sampledCount,
+      totalPages: renderResult.pageCount
+    };
+  }
+  /**
+   * Pre-check for Hangul-Hanja mix in PDF text layer using pdftotext.
+   * Extracts full document text in a single process and checks at document level.
+   * Only makes a definitive decision for Korean (Hangul) documents:
+   * - Hangul + Hanja (anywhere in document) → VLM (confirmed Korean-Hanja mix)
+   * - Hangul only → ocrmac with ko-KR (confirmed Korean)
+   * - No Hangul (English, Japanese, etc.) → null (delegates to VLM for language detection)
+   */
+  async preCheckHanjaFromTextLayer(pdfPath) {
+    try {
+      const totalPages = await this.textExtractor.getPageCount(pdfPath);
+      if (totalPages === 0) return null;
+      const fullText = await this.textExtractor.extractFullText(pdfPath);
+      if (fullText.trim().length === 0) {
+        this.logger.debug(
+          "[OcrStrategySampler] No Hangul in text layer, falling back to VLM sampling"
+        );
+        return null;
+      }
+      const hasHangul = HANGUL_REGEX.test(fullText);
+      const hasHanja = CJK_REGEX.test(fullText);
+      if (!hasHangul) {
+        this.logger.debug(
+          "[OcrStrategySampler] No Hangul in text layer, falling back to VLM sampling"
+        );
+        return null;
+      }
+      if (hasHanja) {
+        const pageTextArray = fullText.split("\f");
+        const koreanHanjaMixPages = [];
+        for (let i = 0; i < pageTextArray.length; i++) {
+          if (CJK_REGEX.test(pageTextArray[i])) {
+            koreanHanjaMixPages.push(i + 1);
+          }
+        }
+        this.logger.info(
+          `[OcrStrategySampler] Hangul-Hanja mix detected in text layer \u2192 VLM strategy (${koreanHanjaMixPages.length} pages with Hanja)`
+        );
+        return {
+          method: "vlm",
+          detectedLanguages: ["ko-KR"],
+          reason: "Hangul-Hanja mix found in PDF text layer",
+          koreanHanjaMixPages,
+          sampledPages: totalPages,
+          totalPages
+        };
+      }
+      this.logger.info(
+        "[OcrStrategySampler] No Hangul-Hanja mix in text layer \u2192 ocrmac strategy"
+      );
+      return {
+        method: "ocrmac",
+        detectedLanguages: ["ko-KR"],
+        reason: `No Hangul-Hanja mix in PDF text layer (${totalPages} pages checked)`,
+        sampledPages: totalPages,
+        totalPages
+      };
+    } catch {
+      this.logger.debug(
+        "[OcrStrategySampler] Text layer pre-check failed, falling back to VLM sampling"
+      );
+      return null;
+    }
+  }
+  /**
+   * Select page indices for sampling.
+   * Trims front/back edges and distributes samples evenly.
+   *
+   * @param totalPages - Total number of pages
+   * @param maxSamples - Maximum number of samples
+   * @returns Array of 0-based page indices
+   */
+  selectSamplePages(totalPages, maxSamples) {
+    if (totalPages === 0) return [];
+    if (totalPages <= maxSamples) {
+      return Array.from({ length: totalPages }, (_, i) => i);
+    }
+    const trimCount = Math.max(1, Math.ceil(totalPages * EDGE_TRIM_RATIO));
+    const start = trimCount;
+    const end = totalPages - trimCount;
+    const eligibleCount = end - start;
+    if (eligibleCount <= 0) {
+      return [Math.floor(totalPages / 2)];
+    }
+    if (eligibleCount <= maxSamples) {
+      return Array.from({ length: eligibleCount }, (_, i) => start + i);
+    }
+    const indices = [];
+    const step = eligibleCount / maxSamples;
+    for (let i = 0; i < maxSamples; i++) {
+      indices.push(start + Math.floor(i * step));
+    }
+    return indices;
+  }
+  /**
+   * Analyze a single sample page for Korean-Hanja mixed script and primary language.
+   * Normalizes raw VLM language responses to valid BCP 47 tags, filtering out invalid ones.
+   *
+   * @returns Object with Korean-Hanja detection result and normalized detected languages
+   */
+  async analyzeSamplePage(pageFile, pageNo, model, options) {
+    this.logger.debug(
+      `[OcrStrategySampler] Analyzing page ${pageNo} for Korean-Hanja mix and language...`
+    );
+    const base64Image = readFileSync3(pageFile).toString("base64");
+    const messages = [
+      {
+        role: "user",
+        content: [
+          { type: "text", text: KOREAN_HANJA_MIX_PROMPT },
+          {
+            type: "image",
+            image: `data:image/png;base64,${base64Image}`
+          }
+        ]
+      }
+    ];
+    const result = await LLMCaller.callVision({
+      schema: koreanHanjaMixSchema,
+      messages,
+      primaryModel: model,
+      fallbackModel: options?.fallbackModel,
+      maxRetries: options?.maxRetries ?? DEFAULT_MAX_RETRIES2,
+      temperature: options?.temperature ?? 0,
+      abortSignal: options?.abortSignal,
+      component: "OcrStrategySampler",
+      phase: "korean-hanja-mix-detection"
+    });
+    if (options?.aggregator) {
+      options.aggregator.track(result.usage);
+    }
+    const output = result.output;
+    const normalizedLanguages = output.detectedLanguages.map(normalizeToBcp47).filter((tag) => tag !== null);
+    this.logger.debug(
+      `[OcrStrategySampler] Page ${pageNo}: hasKoreanHanjaMix=${output.hasKoreanHanjaMix}, detectedLanguages=${normalizedLanguages.join(",")}`
+    );
+    return {
+      hasKoreanHanjaMix: output.hasKoreanHanjaMix,
+      detectedLanguages: normalizedLanguages
+    };
+  }
+  /**
+   * Aggregate language frequency map into a sorted array.
+   * Returns languages sorted by frequency (descending), or undefined if empty.
+   */
+  aggregateLanguages(frequencyMap) {
+    if (frequencyMap.size === 0) return void 0;
+    return [...frequencyMap.entries()].sort((a, b) => b[1] - a[1]).map(([lang]) => lang);
+  }
+};
+
+// src/utils/local-file-server.ts
+import { createReadStream, statSync } from "fs";
+import { createServer } from "http";
+import { basename } from "path";
+var LocalFileServer = class {
+  server = null;
+  port = 0;
+  /**
+   * Start serving a file and return the URL
+   *
+   * @param filePath Absolute path to the file to serve
+   * @returns URL to access the file
+   */
+  async start(filePath) {
+    const filename = basename(filePath);
+    const stat = statSync(filePath);
+    return new Promise((resolve, reject) => {
+      this.server = createServer((req, res) => {
+        if (req.url === `/${filename}`) {
+          res.writeHead(200, {
+            "Content-Type": "application/pdf",
+            "Content-Length": stat.size
+          });
+          createReadStream(filePath).pipe(res);
+        } else {
+          res.writeHead(404);
+          res.end("Not Found");
+        }
+      });
+      this.server.on("error", reject);
+      this.server.listen(0, "127.0.0.1", () => {
+        const address = this.server.address();
+        if (typeof address === "object" && address !== null) {
+          this.port = address.port;
+          resolve(`http://127.0.0.1:${this.port}/${filename}`);
+        } else {
+          reject(new Error("Failed to get server address"));
+        }
+      });
+    });
+  }
+  /**
+   * Stop the server
+   */
+  stop() {
+    return new Promise((resolve) => {
       if (this.server) {
         this.server.close(() => {
           this.server = null;
@@ -802,9 +2122,9 @@ var LocalFileServer = class {
 };
 
 // src/core/image-pdf-converter.ts
-import { existsSync as existsSync2, rmSync as rmSync2 } from "fs";
+import { existsSync as existsSync3, rmSync as rmSync2 } from "fs";
 import { tmpdir } from "os";
-import { join as join3 } from "path";
+import { join as join5 } from "path";
 var ImagePdfConverter = class {
   constructor(logger) {
     this.logger = logger;
@@ -820,8 +2140,8 @@ var ImagePdfConverter = class {
   async convert(pdfUrl, reportId) {
     const timestamp = Date.now();
     const tempDir = tmpdir();
-    const inputPath = join3(tempDir, `${reportId}-${timestamp}-input.pdf`);
-    const outputPath = join3(tempDir, `${reportId}-${timestamp}-image.pdf`);
+    const inputPath = join5(tempDir, `${reportId}-${timestamp}-input.pdf`);
+    const outputPath = join5(tempDir, `${reportId}-${timestamp}-image.pdf`);
     try {
       this.logger.info("[ImagePdfConverter] Downloading PDF from URL...");
       await this.downloadPdf(pdfUrl, inputPath);
@@ -830,7 +2150,7 @@ var ImagePdfConverter = class {
       this.logger.info("[ImagePdfConverter] Image PDF created:", outputPath);
       return outputPath;
     } finally {
-      if (existsSync2(inputPath)) {
+      if (existsSync3(inputPath)) {
         rmSync2(inputPath, { force: true });
       }
     }
@@ -878,7 +2198,7 @@ var ImagePdfConverter = class {
    * Cleanup the temporary image PDF file
    */
   cleanup(imagePdfPath) {
-    if (existsSync2(imagePdfPath)) {
+    if (existsSync3(imagePdfPath)) {
       this.logger.info(
         "[ImagePdfConverter] Cleaning up temp file:",
         imagePdfPath
@@ -889,11 +2209,6 @@ var ImagePdfConverter = class {
 };
 
 // src/core/pdf-converter.ts
-var _origAssertValidConversionOptions = ValidationUtils.assertValidConversionOptions.bind(ValidationUtils);
-ValidationUtils.assertValidConversionOptions = (options) => {
-  const { pipeline: _pipeline, ...rest } = options;
-  _origAssertValidConversionOptions(rest);
-};
 var PDFConverter = class {
   constructor(logger, client, enableImagePdfFallback = false, timeout = PDF_CONVERTER.DEFAULT_TIMEOUT_MS) {
     this.logger = logger;
@@ -903,9 +2218,232 @@ var PDFConverter = class {
   }
   async convert(url, reportId, onComplete, cleanupAfterCallback, options, abortSignal) {
     this.logger.info("[PDFConverter] Converting:", url);
+    if (options.forceImagePdf) {
+      return this.convertViaImagePdf(
+        url,
+        reportId,
+        onComplete,
+        cleanupAfterCallback,
+        options,
+        abortSignal
+      );
+    }
+    return this.convertWithFallback(
+      url,
+      reportId,
+      onComplete,
+      cleanupAfterCallback,
+      options,
+      abortSignal
+    );
+  }
+  /**
+   * Convert a PDF using OCR strategy sampling to decide between ocrmac and VLM.
+   *
+   * Flow:
+   * 1. Determine strategy (forced, skipped, or sampled via VLM)
+   * 2. If VLM → OCR pipeline + VlmTextCorrector (text correction)
+   * 3. If ocrmac → existing Docling conversion
+   *
+   * @returns ConvertWithStrategyResult with the chosen strategy and token report
+   */
+  async convertWithStrategy(url, reportId, onComplete, cleanupAfterCallback, options, abortSignal) {
+    this.logger.info("[PDFConverter] Starting strategy-based conversion:", url);
+    const aggregator = options.aggregator ?? new LLMTokenUsageAggregator();
+    const trackedOptions = { ...options, aggregator };
+    const pdfPath = url.startsWith("file://") ? url.slice(7) : null;
+    const strategy = await this.determineStrategy(
+      pdfPath,
+      reportId,
+      trackedOptions,
+      abortSignal
+    );
+    this.logger.info(
+      `[PDFConverter] OCR strategy: ${strategy.method} (${strategy.reason})`
+    );
+    if (trackedOptions.onTokenUsage) {
+      const samplingReport = this.buildTokenReport(aggregator);
+      if (samplingReport) {
+        trackedOptions.onTokenUsage(samplingReport);
+      }
+    }
+    if (strategy.method === "vlm") {
+      await this.convertWithVlm(
+        pdfPath,
+        reportId,
+        onComplete,
+        cleanupAfterCallback,
+        trackedOptions,
+        abortSignal,
+        strategy.detectedLanguages,
+        strategy.koreanHanjaMixPages
+      );
+      return {
+        strategy,
+        tokenUsageReport: this.buildTokenReport(aggregator)
+      };
+    }
+    const ocrmacOptions = strategy.detectedLanguages ? { ...trackedOptions, ocr_lang: strategy.detectedLanguages } : trackedOptions;
+    await this.convert(
+      url,
+      reportId,
+      onComplete,
+      cleanupAfterCallback,
+      ocrmacOptions,
+      abortSignal
+    );
+    return {
+      strategy,
+      tokenUsageReport: this.buildTokenReport(aggregator)
+    };
+  }
+  /**
+   * Build a token usage report from the aggregator.
+   * Returns null when no LLM calls were tracked (e.g. forced ocrmac without sampling).
+   */
+  buildTokenReport(aggregator) {
+    const report = aggregator.getReport();
+    if (report.components.length === 0) {
+      return null;
+    }
+    return report;
+  }
+  /**
+   * Determine the OCR strategy based on options and page sampling.
+   *
+   * When sampling is possible (strategySamplerModel + local file), it always
+   * runs — even with forcedMethod — so that detectedLanguages are available
+   * for OCR engine configuration. The forced method simply overrides the
+   * sampled method choice.
+   */
+  async determineStrategy(pdfPath, reportId, options, abortSignal) {
+    if (options.skipSampling || !options.strategySamplerModel || !pdfPath) {
+      const method = options.forcedMethod ?? "ocrmac";
+      const reason = options.forcedMethod ? `Forced: ${options.forcedMethod}` : !pdfPath ? "Non-local URL, sampling skipped" : "Sampling skipped";
+      return { method, reason, sampledPages: 0, totalPages: 0 };
+    }
+    const samplingDir = join6(process.cwd(), "output", reportId, "_sampling");
+    const sampler = new OcrStrategySampler(
+      this.logger,
+      new PageRenderer(this.logger),
+      new PdfTextExtractor(this.logger)
+    );
+    try {
+      const strategy = await sampler.sample(
+        pdfPath,
+        samplingDir,
+        options.strategySamplerModel,
+        {
+          aggregator: options.aggregator,
+          abortSignal
+        }
+      );
+      if (options.forcedMethod) {
+        return {
+          ...strategy,
+          method: options.forcedMethod,
+          reason: `Forced: ${options.forcedMethod} (${strategy.reason})`
+        };
+      }
+      return strategy;
+    } finally {
+      if (existsSync4(samplingDir)) {
+        rmSync3(samplingDir, { recursive: true, force: true });
+      }
+    }
+  }
+  /**
+   * Execute VLM-enhanced PDF conversion.
+   *
+   * Runs the standard OCR pipeline (Docling) first, then applies VLM text
+   * correction to fix garbled Chinese characters (漢字/Hanja) in OCR output.
+   */
+  async convertWithVlm(pdfPath, reportId, onComplete, cleanupAfterCallback, options, abortSignal, detectedLanguages, koreanHanjaMixPages) {
+    if (!options.vlmProcessorModel) {
+      throw new Error("vlmProcessorModel is required when OCR strategy is VLM");
+    }
+    if (!pdfPath) {
+      throw new Error("VLM conversion requires a local file (file:// URL)");
+    }
+    const url = `file://${pdfPath}`;
+    const wrappedCallback = async (outputDir) => {
+      let pageTexts;
+      try {
+        const resultPath2 = join6(outputDir, "result.json");
+        const doc = JSON.parse(readFileSync4(resultPath2, "utf-8"));
+        const totalPages = Object.keys(doc.pages).length;
+        const textExtractor = new PdfTextExtractor(this.logger);
+        pageTexts = await textExtractor.extractText(pdfPath, totalPages);
+      } catch {
+        this.logger.warn(
+          "[PDFConverter] pdftotext extraction failed, proceeding without text reference"
+        );
+      }
+      const resultPath = join6(outputDir, "result.json");
+      const ocrOriginPath = join6(outputDir, "result_ocr_origin.json");
+      copyFileSync(resultPath, ocrOriginPath);
+      const corrector = new VlmTextCorrector(this.logger);
+      await corrector.correctAndSave(outputDir, options.vlmProcessorModel, {
+        concurrency: options.vlmConcurrency,
+        aggregator: options.aggregator,
+        abortSignal,
+        onTokenUsage: options.onTokenUsage,
+        documentLanguages: detectedLanguages,
+        pageTexts,
+        koreanHanjaMixPages
+      });
+      await onComplete(outputDir);
+    };
+    const vlmOptions = detectedLanguages ? { ...options, ocr_lang: detectedLanguages } : options;
+    await this.convert(
+      url,
+      reportId,
+      wrappedCallback,
+      cleanupAfterCallback,
+      vlmOptions,
+      abortSignal
+    );
+    this.logger.info("[PDFConverter] VLM conversion completed successfully");
+  }
+  /**
+   * Convert by first creating an image PDF, then running the conversion.
+   * Used when forceImagePdf option is enabled.
+   */
+  async convertViaImagePdf(url, reportId, onComplete, cleanupAfterCallback, options, abortSignal) {
+    this.logger.info(
+      "[PDFConverter] Force image PDF mode: converting to image PDF first..."
+    );
+    const imagePdfConverter = new ImagePdfConverter(this.logger);
+    let imagePdfPath = null;
+    try {
+      imagePdfPath = await imagePdfConverter.convert(url, reportId);
+      const localUrl = `file://${imagePdfPath}`;
+      this.logger.info(
+        "[PDFConverter] Image PDF ready, starting conversion:",
+        localUrl
+      );
+      return await this.performConversion(
+        localUrl,
+        reportId,
+        onComplete,
+        cleanupAfterCallback,
+        options,
+        abortSignal
+      );
+    } finally {
+      if (imagePdfPath) {
+        imagePdfConverter.cleanup(imagePdfPath);
+      }
+    }
+  }
+  /**
+   * Convert directly with optional image PDF fallback on failure.
+   * Used by standard (OCR) pipeline.
+   */
+  async convertWithFallback(url, reportId, onComplete, cleanupAfterCallback, options, abortSignal) {
     let originalError = null;
     try {
-      await this.performConversion(
+      return await this.performConversion(
         url,
         reportId,
         onComplete,
@@ -913,7 +2451,6 @@ var PDFConverter = class {
         options,
         abortSignal
       );
-      return;
     } catch (error) {
       if (abortSignal?.aborted) {
         throw error;
@@ -931,7 +2468,7 @@ var PDFConverter = class {
       imagePdfPath = await imagePdfConverter.convert(url, reportId);
       const localUrl = `file://${imagePdfPath}`;
       this.logger.info("[PDFConverter] Retrying with image PDF:", localUrl);
-      await this.performConversion(
+      const report = await this.performConversion(
         localUrl,
         reportId,
         onComplete,
@@ -940,6 +2477,7 @@ var PDFConverter = class {
         abortSignal
       );
       this.logger.info("[PDFConverter] Fallback conversion succeeded");
+      return report;
     } catch (fallbackError) {
       this.logger.error(
         "[PDFConverter] Fallback conversion also failed:",
@@ -954,15 +2492,10 @@ var PDFConverter = class {
   }
   async performConversion(url, reportId, onComplete, cleanupAfterCallback, options, abortSignal) {
     const startTime = Date.now();
-    const pipelineType = options.pipeline ?? "standard";
-    const conversionOptions = pipelineType === "vlm" ? this.buildVlmConversionOptions(options) : this.buildConversionOptions(options);
-    if (pipelineType === "vlm") {
-      this.logger.info("[PDFConverter] Using VLM pipeline");
-    } else {
-      this.logger.info(
-        `[PDFConverter] OCR languages: ${JSON.stringify(conversionOptions.ocr_options?.lang)}`
-      );
-    }
+    const conversionOptions = this.buildConversionOptions(options);
+    this.logger.info(
+      `[PDFConverter] OCR languages: ${JSON.stringify(conversionOptions.ocr_options?.lang)}`
+    );
     this.logger.info(
       "[PDFConverter] Converting document with Async Source API..."
     );
@@ -990,11 +2523,12 @@ var PDFConverter = class {
       }
     }
     const cwd = process.cwd();
-    const zipPath = join4(cwd, "result.zip");
-    const extractDir = join4(cwd, "result_extracted");
-    const outputDir = join4(cwd, "output", reportId);
+    const zipPath = join6(cwd, "result.zip");
+    const extractDir = join6(cwd, "result_extracted");
+    const outputDir = join6(cwd, "output", reportId);
     try {
       await this.processConvertedFiles(zipPath, extractDir, outputDir);
+      await this.renderPageImages(url, outputDir);
       if (abortSignal?.aborted) {
         this.logger.info("[PDFConverter] Conversion aborted before callback");
         const error = new Error("PDF conversion was aborted");
@@ -1008,10 +2542,10 @@ var PDFConverter = class {
       this.logger.info("[PDFConverter] Total time:", duration, "ms");
     } finally {
       this.logger.info("[PDFConverter] Cleaning up temporary files...");
-      if (existsSync3(zipPath)) {
+      if (existsSync4(zipPath)) {
         rmSync3(zipPath, { force: true });
       }
-      if (existsSync3(extractDir)) {
+      if (existsSync4(extractDir)) {
         rmSync3(extractDir, { recursive: true, force: true });
       }
       if (cleanupAfterCallback) {
@@ -1019,17 +2553,27 @@ var PDFConverter = class {
           "[PDFConverter] Cleaning up output directory:",
           outputDir
         );
-        if (existsSync3(outputDir)) {
+        if (existsSync4(outputDir)) {
           rmSync3(outputDir, { recursive: true, force: true });
         }
       } else {
         this.logger.info("[PDFConverter] Output preserved at:", outputDir);
       }
     }
+    return null;
   }
   buildConversionOptions(options) {
     return {
-      ...omit(options, ["num_threads", "pipeline", "vlm_model"]),
+      ...omit(options, [
+        "num_threads",
+        "forceImagePdf",
+        "strategySamplerModel",
+        "vlmProcessorModel",
+        "skipSampling",
+        "forcedMethod",
+        "aggregator",
+        "onTokenUsage"
+      ]),
       to_formats: ["json", "html"],
       image_export_mode: "embedded",
       ocr_engine: "ocrmac",
@@ -1040,6 +2584,8 @@ var PDFConverter = class {
         framework: "livetext"
       },
       generate_picture_images: true,
+      generate_page_images: false,
+      // Page images are rendered by PageRenderer (ImageMagick) after conversion
       images_scale: 2,
       /**
        * While disabling this option yields the most accurate text extraction for readable PDFs,
@@ -1055,31 +2601,6 @@ var PDFConverter = class {
       }
     };
   }
-  /**
-   * Build conversion options for VLM pipeline.
-   *
-   * VLM pipeline uses a Vision Language Model instead of traditional OCR,
-   * providing better accuracy for KCJ characters and complex layouts.
-   */
-  buildVlmConversionOptions(options) {
-    const vlmModel = resolveVlmModel(options.vlm_model ?? DEFAULT_VLM_MODEL);
-    this.logger.info(
-      `[PDFConverter] VLM model: ${vlmModel.repo_id} (framework: ${vlmModel.inference_framework}, format: ${vlmModel.response_format})`
-    );
-    return {
-      ...omit(options, ["num_threads", "pipeline", "vlm_model", "ocr_lang"]),
-      to_formats: ["json", "html"],
-      image_export_mode: "embedded",
-      pipeline: "vlm",
-      vlm_pipeline_model_local: vlmModel,
-      generate_picture_images: true,
-      images_scale: 2,
-      accelerator_options: {
-        device: "mps",
-        num_threads: options.num_threads
-      }
-    };
-  }
   async startConversionTask(url, conversionOptions) {
     const task = await this.client.convertSourceAsync({
       sources: [
@@ -1146,25 +2667,64 @@ var PDFConverter = class {
         return;
       }
       if (status.task_status === "failure") {
-        throw new Error("Task failed with status: failure");
+        const errorDetails = await this.getTaskFailureDetails(task);
+        const elapsed = Math.round((Date.now() - conversionStartTime) / 1e3);
+        this.logger.error(
+          `
+[PDFConverter] Task failed after ${elapsed}s: ${errorDetails}`
+        );
+        throw new Error(`Task failed: ${errorDetails}`);
       }
       await new Promise(
         (resolve) => setTimeout(resolve, PDF_CONVERTER.POLL_INTERVAL_MS)
       );
     }
   }
+  /**
+   * Fetch detailed error information from a failed task result.
+   */
+  async getTaskFailureDetails(task) {
+    try {
+      const result = await task.getResult();
+      if (result.errors?.length) {
+        return result.errors.map((e) => e.message).join("; ");
+      }
+      return `status: ${result.status ?? "unknown"}`;
+    } catch (err) {
+      this.logger.error("[PDFConverter] Failed to retrieve task result:", err);
+      return "unable to retrieve error details";
+    }
+  }
   async downloadResult(taskId) {
     this.logger.info(
       "\n[PDFConverter] Task completed, downloading ZIP file..."
     );
     const zipResult = await this.client.getTaskResultFile(taskId);
-    if (!zipResult.success || !zipResult.fileStream) {
-      throw new Error("Failed to get ZIP file result");
-    }
-    const zipPath = join4(process.cwd(), "result.zip");
+    const zipPath = join6(process.cwd(), "result.zip");
     this.logger.info("[PDFConverter] Saving ZIP file to:", zipPath);
-    const writeStream = createWriteStream2(zipPath);
-    await pipeline(zipResult.fileStream, writeStream);
+    if (zipResult.fileStream) {
+      const writeStream = createWriteStream2(zipPath);
+      await pipeline(zipResult.fileStream, writeStream);
+      return;
+    }
+    if (zipResult.data) {
+      await writeFile(zipPath, zipResult.data);
+      return;
+    }
+    this.logger.warn(
+      "[PDFConverter] SDK file result unavailable, falling back to direct download..."
+    );
+    const baseUrl = this.client.getConfig().baseUrl;
+    const response = await fetch(`${baseUrl}/v1/result/${taskId}`, {
+      headers: { Accept: "application/zip" }
+    });
+    if (!response.ok) {
+      throw new Error(
+        `Failed to download ZIP file: ${response.status} ${response.statusText}`
+      );
+    }
+    const buffer = new Uint8Array(await response.arrayBuffer());
+    await writeFile(zipPath, buffer);
   }
   async processConvertedFiles(zipPath, extractDir, outputDir) {
     await ImageExtractor.extractAndSaveDocumentsFromZip(
@@ -1174,6 +2734,40 @@ var PDFConverter = class {
       outputDir
     );
   }
+  /**
+   * Render page images from the source PDF using ImageMagick and update result.json.
+   * Replaces Docling's generate_page_images which fails on large PDFs
+   * due to memory limits when embedding all page images as base64.
+   */
+  async renderPageImages(url, outputDir) {
+    if (!url.startsWith("file://")) {
+      this.logger.warn(
+        "[PDFConverter] Page image rendering skipped: only supported for local files (file:// URLs)"
+      );
+      return;
+    }
+    const pdfPath = url.slice(7);
+    this.logger.info(
+      "[PDFConverter] Rendering page images with ImageMagick..."
+    );
+    const renderer = new PageRenderer(this.logger);
+    const renderResult = await renderer.renderPages(pdfPath, outputDir);
+    const resultPath = join6(outputDir, "result.json");
+    const doc = JSON.parse(readFileSync4(resultPath, "utf-8"));
+    for (const page of Object.values(doc.pages)) {
+      const pageNo = page.page_no;
+      const fileIndex = pageNo - 1;
+      if (fileIndex >= 0 && fileIndex < renderResult.pageCount) {
+        page.image.uri = `pages/page_${fileIndex}.png`;
+        page.image.mimetype = "image/png";
+        page.image.dpi = 300;
+      }
+    }
+    await writeFile(resultPath, JSON.stringify(doc, null, 2));
+    this.logger.info(
+      `[PDFConverter] Rendered ${renderResult.pageCount} page images`
+    );
+  }
 };
 
 // src/core/pdf-parser.ts
@@ -1204,7 +2798,7 @@ var PDFParser = class {
       this.baseUrl = void 0;
     }
     this.timeout = timeout;
-    this.venvPath = venvPath || join5(process.cwd(), ".venv");
+    this.venvPath = venvPath || join7(process.cwd(), ".venv");
     this.killExistingProcess = killExistingProcess;
     this.enableImagePdfFallback = enableImagePdfFallback;
   }
@@ -1212,6 +2806,7 @@ var PDFParser = class {
     this.logger.info("[PDFParser] Initializing...");
     this.checkOperatingSystem();
     this.checkJqInstalled();
+    this.checkPopplerInstalled();
     this.checkMacOSVersion();
     if (this.enableImagePdfFallback && !this.baseUrl) {
       this.checkImageMagickInstalled();
@@ -1253,9 +2848,9 @@ var PDFParser = class {
     }
   }
   checkOperatingSystem() {
-    if (platform2() !== "darwin") {
+    if (platform() !== "darwin") {
       throw new Error(
-        "PDFParser is only supported on macOS. Current platform: " + platform2()
+        "PDFParser is only supported on macOS. Current platform: " + platform()
       );
     }
   }
@@ -1268,6 +2863,15 @@ var PDFParser = class {
       );
     }
   }
+  checkPopplerInstalled() {
+    try {
+      execSync("which pdftotext", { stdio: "ignore" });
+    } catch {
+      throw new Error(
+        "poppler is not installed. Please install poppler using: brew install poppler"
+      );
+    }
+  }
   checkMacOSVersion() {
     try {
       const versionOutput = execSync("sw_vers -productVersion", {
@@ -1314,8 +2918,12 @@ var PDFParser = class {
    */
   isConnectionRefusedError(error) {
     if (error instanceof Error) {
-      const errorStr = JSON.stringify(error);
-      return errorStr.includes("ECONNREFUSED");
+      if (error.message.includes("ECONNREFUSED")) {
+        return true;
+      }
+      if (error.cause instanceof Error && error.cause.message.includes("ECONNREFUSED")) {
+        return true;
+      }
     }
     return false;
   }
@@ -1383,11 +2991,20 @@ var PDFParser = class {
         "PDFParser is not initialized. Call init() before using parse()"
       );
     }
-    if (options.pipeline === "vlm" && this.environment && !this.baseUrl) {
-      this.logger.info(
-        "[PDFParser] VLM pipeline requested, ensuring VLM dependencies..."
+    if (options.forceImagePdf && !this.baseUrl) {
+      this.checkImageMagickInstalled();
+      this.checkGhostscriptInstalled();
+    }
+    const useStrategyFlow = options.strategySamplerModel !== void 0 || options.forcedMethod !== void 0;
+    if (useStrategyFlow) {
+      return this.parseWithStrategy(
+        url,
+        reportId,
+        onComplete,
+        cleanupAfterCallback,
+        options,
+        abortSignal
       );
-      await this.environment.setupVlmDependencies();
     }
     const canRecover = !this.baseUrl && this.port !== void 0;
     const maxAttempts = PDF_PARSER.MAX_SERVER_RECOVERY_ATTEMPTS;
@@ -1424,6 +3041,53 @@ var PDFParser = class {
         throw error;
       }
     }
+    return null;
+  }
+  /**
+   * Parse a PDF using OCR strategy sampling to decide between ocrmac and VLM.
+   * Delegates to PDFConverter.convertWithStrategy() and returns the token usage report.
+   *
+   * Server recovery (restart on ECONNREFUSED) is preserved because
+   * the ocrmac path still uses the Docling server.
+   */
+  async parseWithStrategy(url, reportId, onComplete, cleanupAfterCallback, options, abortSignal) {
+    const canRecover = !this.baseUrl && this.port !== void 0;
+    const maxAttempts = PDF_PARSER.MAX_SERVER_RECOVERY_ATTEMPTS;
+    let attempt = 0;
+    while (attempt <= maxAttempts) {
+      try {
+        const effectiveFallbackEnabled = this.enableImagePdfFallback && !this.baseUrl;
+        const converter = new PDFConverter(
+          this.logger,
+          this.client,
+          effectiveFallbackEnabled,
+          this.timeout
+        );
+        const result = await converter.convertWithStrategy(
+          url,
+          reportId,
+          onComplete,
+          cleanupAfterCallback,
+          options,
+          abortSignal
+        );
+        return result.tokenUsageReport;
+      } catch (error) {
+        if (abortSignal?.aborted) {
+          throw error;
+        }
+        if (canRecover && this.isConnectionRefusedError(error) && attempt < maxAttempts) {
+          this.logger.warn(
+            "[PDFParser] Connection refused, attempting server recovery..."
+          );
+          await this.restartServer();
+          attempt++;
+          continue;
+        }
+        throw error;
+      }
+    }
+    return null;
   }
   /**
    * Dispose the parser instance.
@@ -1445,11 +3109,173 @@ var PDFParser = class {
     }
   }
 };
+
+// src/validators/vlm-response-validator.ts
+var MIN_CONTENT_LENGTH = 20;
+var KOREAN_SCRIPT_RATIO_THRESHOLD = 0.1;
+var PLACEHOLDER_PATTERNS = [
+  /lorem\s+ipsum/i,
+  /dolor\s+sit\s+amet/i,
+  /consectetur\s+adipiscing/i,
+  /sed\s+do\s+eiusmod/i,
+  /ut\s+labore\s+et\s+dolore/i
+];
+var META_DESCRIPTION_PATTERNS_KO = [
+  /이미지\s*해상도/,
+  /판독하기?\s*어렵/,
+  /해상도가?\s*(매우\s*)?(낮|부족)/,
+  /텍스트를?\s*판독/,
+  /글자를?\s*읽기?\s*어렵/,
+  /정확한?\s*판독이?\s*(불가|어렵)/
+];
+var META_DESCRIPTION_PATTERNS_EN = [
+  /the image contains/i,
+  /unable to (read|transcribe)/i,
+  /resolution.*(too low|insufficient)/i,
+  /cannot (read|make out|decipher)/i,
+  /text is (not |un)?(legible|readable)/i,
+  /exact transcription is not possible/i
+];
+var REPETITIVE_PATTERN_RATIO_THRESHOLD = 0.3;
+var REPETITIVE_PATTERN_MIN_REPEATS = 5;
+var HANGUL_REGEX2 = /[\uAC00-\uD7AF\u1100-\u11FF]/g;
+var CJK_REGEX2 = /[\u4E00-\u9FFF]/g;
+var VlmResponseValidator = class {
+  /**
+   * Validate VLM page result quality.
+   *
+   * @param elements - Extracted page elements to validate
+   * @param documentLanguages - BCP 47 language tags (e.g., ['ko-KR', 'en-US'])
+   * @returns Validation result with issues list
+   */
+  static validate(elements, documentLanguages) {
+    const issues = [];
+    const textElements = elements.filter(
+      (el) => el.type !== "picture" && el.content.length > 0
+    );
+    if (textElements.length === 0) {
+      return { isValid: true, issues: [] };
+    }
+    const placeholderIssue = this.detectPlaceholderText(textElements);
+    if (placeholderIssue) {
+      issues.push(placeholderIssue);
+    }
+    if (documentLanguages?.[0]?.startsWith("ko")) {
+      const scriptIssue = this.detectScriptAnomaly(textElements);
+      if (scriptIssue) {
+        issues.push(scriptIssue);
+      }
+    }
+    const metaIssue = this.detectMetaDescription(textElements);
+    if (metaIssue) {
+      issues.push(metaIssue);
+    }
+    const repetitiveIssue = this.detectRepetitivePattern(textElements);
+    if (repetitiveIssue) {
+      issues.push(repetitiveIssue);
+    }
+    return { isValid: issues.length === 0, issues };
+  }
+  /**
+   * Detect known placeholder / filler text in elements.
+   */
+  static detectPlaceholderText(elements) {
+    const affectedElements = [];
+    for (const el of elements) {
+      for (const pattern of PLACEHOLDER_PATTERNS) {
+        if (pattern.test(el.content)) {
+          affectedElements.push(el.order);
+          break;
+        }
+      }
+    }
+    if (affectedElements.length === 0) return null;
+    return {
+      type: "placeholder_text",
+      message: `Detected placeholder text (e.g., Lorem ipsum) in ${affectedElements.length} element(s)`,
+      affectedElements
+    };
+  }
+  /**
+   * Detect script anomaly: expected Korean content but found mostly Latin text.
+   * Counts Hangul + CJK characters and flags if the ratio is below threshold.
+   */
+  static detectScriptAnomaly(elements) {
+    const allContent = elements.map((el) => el.content).join("");
+    const nonWhitespace = allContent.replace(/\s/g, "");
+    if (nonWhitespace.length < MIN_CONTENT_LENGTH) {
+      return null;
+    }
+    const hangulCount = allContent.match(HANGUL_REGEX2)?.length ?? 0;
+    const cjkCount = allContent.match(CJK_REGEX2)?.length ?? 0;
+    const koreanCjkCount = hangulCount + cjkCount;
+    const ratio = koreanCjkCount / nonWhitespace.length;
+    if (ratio < KOREAN_SCRIPT_RATIO_THRESHOLD) {
+      return {
+        type: "script_anomaly",
+        message: `Expected Korean text but found ${(ratio * 100).toFixed(1)}% Korean/CJK characters (threshold: ${KOREAN_SCRIPT_RATIO_THRESHOLD * 100}%)`,
+        affectedElements: elements.map((el) => el.order)
+      };
+    }
+    return null;
+  }
+  /**
+   * Detect meta description: VLM described the image/resolution instead
+   * of transcribing actual text content.
+   */
+  static detectMetaDescription(elements) {
+    const affectedElements = [];
+    const allPatterns = [
+      ...META_DESCRIPTION_PATTERNS_KO,
+      ...META_DESCRIPTION_PATTERNS_EN
+    ];
+    for (const el of elements) {
+      for (const pattern of allPatterns) {
+        if (pattern.test(el.content)) {
+          affectedElements.push(el.order);
+          break;
+        }
+      }
+    }
+    if (affectedElements.length === 0) return null;
+    return {
+      type: "meta_description",
+      message: `Detected meta-description of image instead of text transcription in ${affectedElements.length} element(s)`,
+      affectedElements
+    };
+  }
+  /**
+   * Detect repetitive character patterns (e.g., `: : : : :` or `= = = = =`).
+   * Flags when the same character repeats with spaces 5+ times and the
+   * repetitive portion exceeds 30% of total content.
+   */
+  static detectRepetitivePattern(elements) {
+    const allContent = elements.map((el) => el.content).join("\n");
+    if (allContent.trim().length === 0) return null;
+    const repetitiveRegex = /(\S)(\s+\1){4,}/g;
+    let totalRepetitiveLength = 0;
+    let match;
+    while ((match = repetitiveRegex.exec(allContent)) !== null) {
+      const repeatedChar = match[1];
+      const segment = match[0];
+      const parts = segment.split(/\s+/).filter((p) => p === repeatedChar);
+      if (parts.length >= REPETITIVE_PATTERN_MIN_REPEATS) {
+        totalRepetitiveLength += segment.length;
+      }
+    }
+    if (totalRepetitiveLength === 0) return null;
+    const ratio = totalRepetitiveLength / allContent.length;
+    if (ratio < REPETITIVE_PATTERN_RATIO_THRESHOLD) return null;
+    return {
+      type: "repetitive_pattern",
+      message: `Detected repetitive character patterns (${(ratio * 100).toFixed(0)}% of content)`,
+      affectedElements: elements.map((el) => el.order)
+    };
+  }
+};
 export {
-  DEFAULT_VLM_MODEL,
   ImagePdfFallbackError,
   PDFParser,
-  VLM_MODELS,
-  resolveVlmModel
+  VlmResponseValidator
 };
 //# sourceMappingURL=index.js.map