@heripo/pdf-parser 0.1.5 → 0.1.7

package/dist/index.d.cts

@@ -1,11 +1,26 @@
 import { LoggerMethods } from '@heripo/logger';
-import { ConversionOptions } from 'docling-sdk';
+import { ConversionOptions, VlmModelLocal } from 'docling-sdk';
+export { DEFAULT_VLM_MODEL, VLM_MODELS, VlmModelPreset, resolveVlmModel } from './vlm-models.cjs';
 
 /**
  * Callback function invoked after PDF conversion completes
  * @param outputPath Absolute path to the output directory containing result files
  */
 type ConversionCompleteCallback = (outputPath: string) => Promise<void> | void;
+/**
+ * Pipeline type for PDF conversion
+ * - 'standard': Use OCR-based pipeline (default, uses ocrmac)
+ * - 'vlm': Use Vision Language Model pipeline for better KCJ/complex layout handling
+ */
+type PipelineType = 'standard' | 'vlm';
+/**
+ * Extended options for PDF conversion including pipeline selection
+ */
+type PDFConvertOptions = Omit<ConversionOptions, 'to_formats' | 'image_export_mode' | 'ocr_engine' | 'accelerator_options' | 'ocr_options' | 'generate_picture_images' | 'images_scale' | 'force_ocr' | 'pipeline' | 'vlm_pipeline_model_local'> & {
+    num_threads?: number;
+    pipeline?: PipelineType;
+    vlm_model?: string | VlmModelLocal;
+};
 
 type Options = {
     logger: LoggerMethods;
@@ -82,6 +97,7 @@ declare class PDFParser {
     private readonly killExistingProcess;
     private readonly enableImagePdfFallback;
     private client;
+    private environment?;
     constructor(options: Options);
     init(): Promise<void>;
     private checkOperatingSystem;
@@ -104,9 +120,7 @@ declare class PDFParser {
      */
     private restartServer;
     private waitForServerReady;
-    parse(url: string, reportId: string, onComplete: ConversionCompleteCallback, cleanupAfterCallback: boolean, options: Omit<ConversionOptions, 'to_formats' | 'image_export_mode' | 'ocr_engine' | 'accelerator_options' | 'ocr_options' | 'generate_picture_images' | 'images_scale' | 'force_ocr'> & {
-        num_threads?: number;
-    }, abortSignal?: AbortSignal): Promise<void>;
+    parse(url: string, reportId: string, onComplete: ConversionCompleteCallback, cleanupAfterCallback: boolean, options: PDFConvertOptions, abortSignal?: AbortSignal): Promise<void>;
     /**
      * Dispose the parser instance.
      * - Sets the internal client to null
@@ -126,4 +140,4 @@ declare class ImagePdfFallbackError extends Error {
     constructor(originalError: Error, fallbackError: Error);
 }
 
-export { type ConversionCompleteCallback, ImagePdfFallbackError, PDFParser };
+export { type ConversionCompleteCallback, ImagePdfFallbackError, type PDFConvertOptions, PDFParser, type PipelineType };

package/dist/index.d.ts

@@ -1,11 +1,26 @@
 import { LoggerMethods } from '@heripo/logger';
-import { ConversionOptions } from 'docling-sdk';
+import { ConversionOptions, VlmModelLocal } from 'docling-sdk';
+export { DEFAULT_VLM_MODEL, VLM_MODELS, VlmModelPreset, resolveVlmModel } from './vlm-models.js';
 
 /**
  * Callback function invoked after PDF conversion completes
  * @param outputPath Absolute path to the output directory containing result files
  */
 type ConversionCompleteCallback = (outputPath: string) => Promise<void> | void;
+/**
+ * Pipeline type for PDF conversion
+ * - 'standard': Use OCR-based pipeline (default, uses ocrmac)
+ * - 'vlm': Use Vision Language Model pipeline for better KCJ/complex layout handling
+ */
+type PipelineType = 'standard' | 'vlm';
+/**
+ * Extended options for PDF conversion including pipeline selection
+ */
+type PDFConvertOptions = Omit<ConversionOptions, 'to_formats' | 'image_export_mode' | 'ocr_engine' | 'accelerator_options' | 'ocr_options' | 'generate_picture_images' | 'images_scale' | 'force_ocr' | 'pipeline' | 'vlm_pipeline_model_local'> & {
+    num_threads?: number;
+    pipeline?: PipelineType;
+    vlm_model?: string | VlmModelLocal;
+};
 
 type Options = {
     logger: LoggerMethods;
@@ -82,6 +97,7 @@ declare class PDFParser {
     private readonly killExistingProcess;
     private readonly enableImagePdfFallback;
     private client;
+    private environment?;
     constructor(options: Options);
     init(): Promise<void>;
     private checkOperatingSystem;
@@ -104,9 +120,7 @@ declare class PDFParser {
      */
     private restartServer;
     private waitForServerReady;
-    parse(url: string, reportId: string, onComplete: ConversionCompleteCallback, cleanupAfterCallback: boolean, options: Omit<ConversionOptions, 'to_formats' | 'image_export_mode' | 'ocr_engine' | 'accelerator_options' | 'ocr_options' | 'generate_picture_images' | 'images_scale' | 'force_ocr'> & {
-        num_threads?: number;
-    }, abortSignal?: AbortSignal): Promise<void>;
+    parse(url: string, reportId: string, onComplete: ConversionCompleteCallback, cleanupAfterCallback: boolean, options: PDFConvertOptions, abortSignal?: AbortSignal): Promise<void>;
     /**
      * Dispose the parser instance.
      * - Sets the internal client to null
@@ -126,4 +140,4 @@ declare class ImagePdfFallbackError extends Error {
     constructor(originalError: Error, fallbackError: Error);
 }
 
-export { type ConversionCompleteCallback, ImagePdfFallbackError, PDFParser };
+export { type ConversionCompleteCallback, ImagePdfFallbackError, type PDFConvertOptions, PDFParser, type PipelineType };

package/dist/index.js

@@ -1,9 +1,14 @@
+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 } from "os";
+import { platform as platform2 } from "os";
 import { join as join5 } from "path";
 
 // src/config/constants.ts
@@ -33,7 +38,11 @@ var PDF_CONVERTER = {
   /**
    * Interval for progress polling in milliseconds
    */
-  POLL_INTERVAL_MS: 1e3
+  POLL_INTERVAL_MS: 1e3,
+  /**
+   * Default timeout for task completion in milliseconds (30 minutes)
+   */
+  DEFAULT_TIMEOUT_MS: 18e5
 };
 var DOCLING_ENVIRONMENT = {
   /**
@@ -51,6 +60,19 @@ 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";
@@ -83,6 +105,7 @@ function spawnAsync(command, args, options = {}) {
 
 // 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
@@ -124,6 +147,7 @@ var DoclingEnvironment = class _DoclingEnvironment {
   venvPath;
   port;
   killExistingProcess;
+  vlmDependenciesInstalled = false;
   constructor(options) {
     this.logger = options.logger;
     this.venvPath = options.venvPath;
@@ -253,6 +277,81 @@ 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}`]);
@@ -339,6 +438,7 @@ 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";
@@ -789,11 +889,17 @@ 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) {
+  constructor(logger, client, enableImagePdfFallback = false, timeout = PDF_CONVERTER.DEFAULT_TIMEOUT_MS) {
     this.logger = logger;
     this.client = client;
     this.enableImagePdfFallback = enableImagePdfFallback;
+    this.timeout = timeout;
   }
   async convert(url, reportId, onComplete, cleanupAfterCallback, options, abortSignal) {
     this.logger.info("[PDFConverter] Converting:", url);
@@ -848,10 +954,15 @@ var PDFConverter = class {
   }
   async performConversion(url, reportId, onComplete, cleanupAfterCallback, options, abortSignal) {
     const startTime = Date.now();
-    const conversionOptions = this.buildConversionOptions(options);
-    this.logger.info(
-      `[PDFConverter] OCR languages: ${JSON.stringify(conversionOptions.ocr_options?.lang)}`
-    );
+    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)}`
+      );
+    }
     this.logger.info(
       "[PDFConverter] Converting document with Async Source API..."
     );
@@ -918,7 +1029,7 @@ var PDFConverter = class {
   }
   buildConversionOptions(options) {
     return {
-      ...omit(options, ["num_threads"]),
+      ...omit(options, ["num_threads", "pipeline", "vlm_model"]),
       to_formats: ["json", "html"],
       image_export_mode: "embedded",
       ocr_engine: "ocrmac",
@@ -944,6 +1055,31 @@ 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: [
@@ -979,38 +1115,42 @@ var PDFConverter = class {
   }
   async trackTaskProgress(task) {
     const conversionStartTime = Date.now();
-    let lastStatus = "";
-    let isCompleted = false;
-    const pollInterval = setInterval(() => {
-      if (isCompleted) return;
-      const elapsed = Math.floor((Date.now() - conversionStartTime) / 1e3);
-      process.stdout.write(
-        `\r[PDFConverter] Status: ${lastStatus || "processing"} (${elapsed}s elapsed)`
-      );
-    }, PDF_CONVERTER.POLL_INTERVAL_MS);
-    task.on("progress", (status) => {
-      lastStatus = status.task_status;
+    let lastProgressLine = "";
+    const logProgress = (status) => {
+      const parts = [`Status: ${status.task_status}`];
       if (status.task_position !== void 0) {
-        process.stdout.write(
-          `\r[PDFConverter] Status: ${status.task_status} (position: ${status.task_position})`
-        );
+        parts.push(`position: ${status.task_position}`);
       }
-    });
-    task.on("complete", () => {
-      isCompleted = true;
-      clearInterval(pollInterval);
-      this.logger.info("\n[PDFConverter] Conversion completed!");
-    });
-    task.on("error", (error) => {
-      isCompleted = true;
-      clearInterval(pollInterval);
-      this.logger.error("\n[PDFConverter] Conversion error:", error.message);
-    });
-    try {
-      await task.waitForCompletion();
-    } finally {
-      isCompleted = true;
-      clearInterval(pollInterval);
+      const meta = status.task_meta;
+      if (meta) {
+        if (meta.processed_documents !== void 0 && meta.total_documents !== void 0) {
+          parts.push(
+            `progress: ${meta.processed_documents}/${meta.total_documents}`
+          );
+        }
+      }
+      const progressLine = `\r[PDFConverter] ${parts.join(" | ")}`;
+      if (progressLine !== lastProgressLine) {
+        lastProgressLine = progressLine;
+        process.stdout.write(progressLine);
+      }
+    };
+    while (true) {
+      if (Date.now() - conversionStartTime > this.timeout) {
+        throw new Error("Task timeout");
+      }
+      const status = await task.poll();
+      logProgress(status);
+      if (status.task_status === "success") {
+        this.logger.info("\n[PDFConverter] Conversion completed!");
+        return;
+      }
+      if (status.task_status === "failure") {
+        throw new Error("Task failed with status: failure");
+      }
+      await new Promise(
+        (resolve) => setTimeout(resolve, PDF_CONVERTER.POLL_INTERVAL_MS)
+      );
     }
   }
   async downloadResult(taskId) {
@@ -1046,6 +1186,7 @@ var PDFParser = class {
   killExistingProcess;
   enableImagePdfFallback;
   client = null;
+  environment;
   constructor(options) {
     const {
       logger,
@@ -1090,13 +1231,13 @@ var PDFParser = class {
     }
     this.logger.info("[PDFParser] Setting up local server...");
     try {
-      const environment = new DoclingEnvironment({
+      this.environment = new DoclingEnvironment({
         logger: this.logger,
         venvPath: this.venvPath,
         port: this.port,
         killExistingProcess: this.killExistingProcess
       });
-      await environment.setup();
+      await this.environment.setup();
       const clientUrl = `http://localhost:${this.port}`;
       this.client = new Docling({
         api: {
@@ -1112,9 +1253,9 @@ var PDFParser = class {
     }
   }
   checkOperatingSystem() {
-    if (platform() !== "darwin") {
+    if (platform2() !== "darwin") {
       throw new Error(
-        "PDFParser is only supported on macOS. Current platform: " + platform()
+        "PDFParser is only supported on macOS. Current platform: " + platform2()
       );
     }
   }
@@ -1242,6 +1383,12 @@ 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..."
+      );
+      await this.environment.setupVlmDependencies();
+    }
     const canRecover = !this.baseUrl && this.port !== void 0;
     const maxAttempts = PDF_PARSER.MAX_SERVER_RECOVERY_ATTEMPTS;
     let attempt = 0;
@@ -1251,7 +1398,8 @@ var PDFParser = class {
         const converter = new PDFConverter(
           this.logger,
           this.client,
-          effectiveFallbackEnabled
+          effectiveFallbackEnabled,
+          this.timeout
         );
         return await converter.convert(
           url,
@@ -1298,7 +1446,10 @@ var PDFParser = class {
   }
 };
 export {
+  DEFAULT_VLM_MODEL,
   ImagePdfFallbackError,
-  PDFParser
+  PDFParser,
+  VLM_MODELS,
+  resolveVlmModel
 };
 //# sourceMappingURL=index.js.map