ocr-provenance-mcp 1.0.0

package/dist/services/images/extractor.js

@@ -0,0 +1,340 @@
+/**
+ * Image Extractor Service
+ *
+ * TypeScript wrapper for Python image extraction scripts.
+ * Extracts images from PDF and DOCX documents for VLM analysis.
+ */
+import { spawn } from 'child_process';
+import * as path from 'path';
+import * as fs from 'fs';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/** Max stderr accumulation: 10KB (matches nomic.ts pattern) */
+const MAX_STDERR_LENGTH = 10_240;
+/** Supported file types for image extraction */
+const SUPPORTED_EXTRACTION_TYPES = new Set(['.pdf', '.docx']);
+const DEFAULT_CONFIG = {
+    pythonPath: process.platform === 'win32' ? 'python' : 'python3',
+    timeout: 120000,
+};
+/**
+ * Service for extracting images from PDF documents
+ */
+export class ImageExtractor {
+    config;
+    pdfScriptPath;
+    docxScriptPath;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.pdfScriptPath =
+            this.config.scriptPath || path.resolve(__dirname, '../../../python/image_extractor.py');
+        this.docxScriptPath = path.resolve(__dirname, '../../../python/docx_image_extractor.py');
+    }
+    /**
+     * Extract images from any supported document type.
+     * Routes to the correct extractor based on file extension.
+     *
+     * @param filePath - Path to the document file
+     * @param options - Extraction options
+     * @returns Promise<ExtractedImage[]> - Array of extracted images
+     * @throws Error if file type is unsupported or extraction fails
+     */
+    async extractImages(filePath, options) {
+        const ext = path.extname(filePath).toLowerCase();
+        switch (ext) {
+            case '.pdf':
+                return this.extractFromPDF(filePath, options);
+            case '.docx':
+                return this.extractFromDOCX(filePath, options);
+            default:
+                throw new Error(`Unsupported file type for image extraction: '${ext}'. ` +
+                    `Supported types: ${[...SUPPORTED_EXTRACTION_TYPES].join(', ')}`);
+        }
+    }
+    /**
+     * Check if a file type is supported for image extraction.
+     */
+    static isSupported(filePath) {
+        return SUPPORTED_EXTRACTION_TYPES.has(path.extname(filePath).toLowerCase());
+    }
+    /**
+     * Extract images from a PDF document
+     *
+     * @param pdfPath - Path to the PDF file
+     * @param options - Extraction options
+     * @returns Promise<ExtractedImage[]> - Array of extracted images
+     * @throws Error if extraction fails
+     */
+    async extractFromPDF(pdfPath, options) {
+        // Validate PDF exists
+        if (!fs.existsSync(pdfPath)) {
+            throw new Error(`PDF file not found: ${pdfPath}`);
+        }
+        // Validate script exists
+        if (!fs.existsSync(this.pdfScriptPath)) {
+            throw new Error(`Image extractor script not found: ${this.pdfScriptPath}. ` +
+                `Ensure python/image_extractor.py exists.`);
+        }
+        // Create output directory if it doesn't exist
+        if (!fs.existsSync(options.outputDir)) {
+            fs.mkdirSync(options.outputDir, { recursive: true });
+        }
+        const result = await this.runPythonExtractorScript(this.pdfScriptPath, pdfPath, options);
+        if (!result.success) {
+            throw new Error(`Image extraction failed: ${result.error}`);
+        }
+        if (result.warnings && result.warnings.length > 0) {
+            console.error(`[WARN] [ImageExtractor] Warnings during extraction: ${result.warnings.join('; ')}`);
+        }
+        return result.images;
+    }
+    /**
+     * Extract images from a DOCX document
+     *
+     * @param docxPath - Path to the DOCX file
+     * @param options - Extraction options
+     * @returns Promise<ExtractedImage[]> - Array of extracted images
+     * @throws Error if extraction fails
+     */
+    async extractFromDOCX(docxPath, options) {
+        if (!fs.existsSync(docxPath)) {
+            throw new Error(`DOCX file not found: ${docxPath}`);
+        }
+        if (!fs.existsSync(this.docxScriptPath)) {
+            throw new Error(`DOCX image extractor script not found: ${this.docxScriptPath}. ` +
+                `Ensure python/docx_image_extractor.py exists.`);
+        }
+        if (!fs.existsSync(options.outputDir)) {
+            fs.mkdirSync(options.outputDir, { recursive: true });
+        }
+        const result = await this.runPythonExtractorScript(this.docxScriptPath, docxPath, options);
+        if (!result.success) {
+            throw new Error(`DOCX image extraction failed: ${result.error}`);
+        }
+        if (result.warnings && result.warnings.length > 0) {
+            console.error(`[WARN] [ImageExtractor] DOCX extraction warnings: ${result.warnings.join('; ')}`);
+        }
+        return result.images;
+    }
+    /**
+     * Check if the Python environment is properly configured
+     *
+     * @returns Promise<boolean> - True if Python and dependencies are available
+     */
+    async checkEnvironment() {
+        const missingDeps = [];
+        // Check Python version
+        let pythonVersion;
+        try {
+            pythonVersion = await this.runCommand(this.config.pythonPath, ['--version']);
+        }
+        catch (error) {
+            console.error('[ImageExtractor] Python version check failed:', error instanceof Error ? error.message : String(error));
+            return {
+                available: false,
+                missingDependencies: ['python'],
+            };
+        }
+        // Check PyMuPDF
+        try {
+            await this.runCommand(this.config.pythonPath, ['-c', 'import fitz; print(fitz.version)']);
+        }
+        catch (error) {
+            console.error('[ImageExtractor] PyMuPDF import check failed:', error instanceof Error ? error.message : String(error));
+            missingDeps.push('PyMuPDF');
+        }
+        // Check Pillow
+        try {
+            await this.runCommand(this.config.pythonPath, ['-c', 'from PIL import Image; print("OK")']);
+        }
+        catch (error) {
+            console.error('[ImageExtractor] Pillow import check failed:', error instanceof Error ? error.message : String(error));
+            missingDeps.push('Pillow');
+        }
+        return {
+            available: missingDeps.length === 0,
+            pythonVersion: pythonVersion?.trim(),
+            missingDependencies: missingDeps,
+        };
+    }
+    /**
+     * Run a Python extraction script (works for both PDF and DOCX extractors)
+     */
+    runPythonExtractorScript(scriptPath, inputPath, options) {
+        return new Promise((resolve, reject) => {
+            const args = [
+                scriptPath,
+                '--input',
+                inputPath,
+                '--output',
+                options.outputDir,
+                '--min-size',
+                String(options.minSize ?? 50),
+                '--max-images',
+                String(options.maxImages ?? 100),
+            ];
+            const timeout = this.config.timeout ?? 120000;
+            const proc = spawn(this.config.pythonPath, args, {
+                timeout,
+            });
+            const stdoutChunks = [];
+            let stderr = '';
+            let settled = false;
+            let sigkillTimer = null;
+            const cleanup = () => {
+                if (sigkillTimer) {
+                    clearTimeout(sigkillTimer);
+                    sigkillTimer = null;
+                }
+            };
+            proc.stdout.on('data', (data) => {
+                stdoutChunks.push(data);
+            });
+            // Cap stderr accumulation to prevent unbounded memory growth
+            proc.stderr.on('data', (data) => {
+                if (stderr.length < MAX_STDERR_LENGTH) {
+                    stderr += data.toString();
+                }
+            });
+            proc.on('error', (err) => {
+                cleanup();
+                if (settled)
+                    return;
+                settled = true;
+                reject(new Error(`Failed to start Python process: ${err.message}`));
+            });
+            proc.on('close', (code, signal) => {
+                cleanup();
+                if (settled)
+                    return;
+                settled = true;
+                if (stderr) {
+                    console.error(`[WARN] [ImageExtractor] stderr: ${stderr.substring(0, 2000)}`);
+                }
+                if (signal === 'SIGTERM' || signal === 'SIGKILL') {
+                    reject(new Error(`Python process killed by ${signal} (timeout: ${timeout}ms)`));
+                    return;
+                }
+                const stdout = Buffer.concat(stdoutChunks).toString('utf-8');
+                try {
+                    // Python may output debug/warning lines before the JSON. Find the last
+                    // valid JSON line (starts with '{' or '[') to handle multi-line output.
+                    const lines = stdout.trim().split('\n');
+                    let parsed;
+                    for (let i = lines.length - 1; i >= 0; i--) {
+                        const line = lines[i].trim();
+                        if (line.startsWith('{') || line.startsWith('[')) {
+                            try {
+                                parsed = JSON.parse(line);
+                                break;
+                            }
+                            catch (error) {
+                                console.error('[ImageExtractor] JSON parse failed for output line, trying previous:', error instanceof Error ? error.message : String(error));
+                                /* not valid JSON, try previous line */
+                            }
+                        }
+                    }
+                    if (parsed === undefined) {
+                        // Fallback: try parsing the entire stdout as one JSON blob
+                        parsed = JSON.parse(stdout);
+                    }
+                    resolve(parsed);
+                }
+                catch (parseError) {
+                    if (code !== 0) {
+                        reject(new Error(`Python script exited with code ${code}: ${(stderr || stdout).substring(0, 2000)}`));
+                    }
+                    else {
+                        reject(new Error(`Failed to parse extraction result: ${parseError}`));
+                    }
+                }
+            });
+            // F-INTEG-12: SIGKILL escalation if SIGTERM doesn't exit within 5s.
+            // Also settles the promise to prevent zombie hangs if close event never fires.
+            if (timeout > 0) {
+                sigkillTimer = setTimeout(() => {
+                    if (!proc.killed) {
+                        console.error(`[ImageExtractor] Process did not exit after SIGTERM, sending SIGKILL (pid: ${proc.pid})`);
+                        try {
+                            proc.kill('SIGKILL');
+                        }
+                        catch (error) {
+                            console.error('[ImageExtractor] Failed to SIGKILL process (may already be gone):', error instanceof Error ? error.message : String(error));
+                            // Process may already be gone
+                        }
+                    }
+                    // Settle the promise if close event hasn't fired yet (zombie prevention)
+                    if (!settled) {
+                        settled = true;
+                        reject(new Error(`Python process killed by SIGKILL after timeout (${timeout}ms + 5s grace)`));
+                    }
+                }, timeout + 5000);
+            }
+        });
+    }
+    /**
+     * Run a simple command and return output
+     */
+    runCommand(cmd, args) {
+        const timeout = 10000;
+        return new Promise((resolve, reject) => {
+            const proc = spawn(cmd, args, { timeout });
+            let stdout = '';
+            let stderr = '';
+            let settled = false;
+            let sigkillTimer = null;
+            const cleanup = () => {
+                if (sigkillTimer) {
+                    clearTimeout(sigkillTimer);
+                    sigkillTimer = null;
+                }
+            };
+            proc.stdout.on('data', (d) => { if (stdout.length < 65536)
+                stdout += d; });
+            proc.stderr.on('data', (d) => { if (stderr.length < 10240)
+                stderr += d; });
+            proc.on('error', (err) => {
+                cleanup();
+                if (settled)
+                    return;
+                settled = true;
+                reject(err);
+            });
+            proc.on('close', (code, signal) => {
+                cleanup();
+                if (settled)
+                    return;
+                settled = true;
+                if (signal === 'SIGTERM' || signal === 'SIGKILL') {
+                    reject(new Error(`Process killed by ${signal} (timeout: ${timeout}ms)`));
+                    return;
+                }
+                if (code === 0) {
+                    resolve(stdout);
+                }
+                else {
+                    reject(new Error(stderr || `Exit code ${code}`));
+                }
+            });
+            // SIGKILL escalation if SIGTERM doesn't exit within 5s
+            if (timeout > 0) {
+                sigkillTimer = setTimeout(() => {
+                    if (!proc.killed) {
+                        console.error(`[ImageExtractor] runCommand process did not exit after SIGTERM, sending SIGKILL (pid: ${proc.pid})`);
+                        try {
+                            proc.kill('SIGKILL');
+                        }
+                        catch (error) {
+                            console.error('[ImageExtractor] Failed to SIGKILL runCommand process:', error instanceof Error ? error.message : String(error));
+                        }
+                    }
+                    if (!settled) {
+                        settled = true;
+                        reject(new Error(`Process killed by SIGKILL after timeout (${timeout}ms + 5s grace)`));
+                    }
+                }, timeout + 5000);
+            }
+        });
+    }
+}
+//# sourceMappingURL=extractor.js.map

package/dist/services/images/extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractor.js","sourceRoot":"","sources":["../../../src/services/images/extractor.ts"],"names":[],"mappings":"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"}

package/dist/services/images/optimizer.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Image Optimizer Service
+ *
+ * TypeScript wrapper for Python image optimizer providing:
+ * 1. Resize for OCR (max 4800px width for Datalab API)
+ * 2. Resize for VLM (optimize token usage, max 2048px)
+ * 3. Relevance analysis to filter logos, icons, and decorative elements
+ *
+ * The relevance analysis uses multi-layer heuristics:
+ * - Size filtering (tiny images are likely icons)
+ * - Aspect ratio analysis (extreme ratios = banners/logos)
+ * - Color diversity (low color count = likely logo/icon)
+ */
+/**
+ * Image category classification
+ */
+type ImageCategory = 'photo' | 'chart' | 'document' | 'logo' | 'icon' | 'decorative' | 'unknown';
+/**
+ * Result of image relevance analysis
+ */
+interface ImageAnalysisResult {
+    success: true;
+    path: string;
+    width: number;
+    height: number;
+    aspect_ratio: number;
+    unique_colors: number;
+    color_diversity_score: number;
+    size_score: number;
+    aspect_score: number;
+    overall_relevance: number;
+    predicted_category: ImageCategory;
+    should_vlm: boolean;
+    skip_reason?: string;
+}
+/**
+ * Result of resize operation
+ */
+interface ResizeResult {
+    success: true;
+    resized: boolean;
+    original_width: number;
+    original_height: number;
+    output_width: number;
+    output_height: number;
+    scale_factor?: number;
+    output_path: string;
+}
+/**
+ * Result when image is skipped (too small)
+ */
+interface SkipResult {
+    success: true;
+    skipped: true;
+    skip_reason: string;
+    original_width: number;
+    original_height: number;
+}
+/**
+ * Error result from Python script
+ */
+interface ErrorResult {
+    success: false;
+    error: string;
+}
+/**
+ * Configuration for the image optimizer
+ */
+interface ImageOptimizerConfig {
+    /** Path to Python executable */
+    pythonPath: string;
+    /** Timeout in milliseconds */
+    timeout: number;
+    /** Maximum dimension for VLM resize (default: 2048) */
+    vlmMaxDimension: number;
+    /** Minimum size to skip for VLM (default: 50) */
+    vlmSkipBelowSize: number;
+    /** Minimum relevance score for VLM (default: 0.3) */
+    minRelevanceScore: number;
+}
+/**
+ * Service for optimizing images for OCR and VLM processing
+ */
+export declare class ImageOptimizer {
+    private readonly config;
+    private readonly scriptPath;
+    constructor(config?: Partial<ImageOptimizerConfig>);
+    /**
+     * Analyze an image to determine if it should be processed by VLM.
+     *
+     * Uses multi-layer heuristics:
+     * 1. Size (tiny images = skip)
+     * 2. Aspect ratio (extreme ratios = skip)
+     * 3. Color diversity (low = likely logo/icon)
+     * 4. Category prediction
+     *
+     * @param imagePath - Path to the image file
+     * @returns Analysis result with should_vlm recommendation
+     */
+    analyzeImage(imagePath: string): Promise<ImageAnalysisResult | ErrorResult>;
+    /**
+     * Resize an image for VLM processing (Gemini).
+     *
+     * @param inputPath - Path to input image
+     * @param outputPath - Path for output (optional, creates temp file if not provided)
+     * @returns Resize result or skip result if too small
+     */
+    resizeForVLM(inputPath: string, outputPath?: string): Promise<ResizeResult | SkipResult | ErrorResult>;
+    /**
+     * Check if the Python optimizer script exists.
+     */
+    isAvailable(): boolean;
+    /**
+     * Create a temporary file path for resized output.
+     */
+    private createTempPath;
+    /**
+     * Run the Python optimizer script.
+     * M-14: Sends SIGKILL after 5s if SIGTERM from Node.js timeout didn't terminate the process.
+     */
+    private runPython;
+}
+/**
+ * Get an optimizer instance.
+ * When config is provided, always creates a new instance and updates the cache.
+ * When no config is provided, returns the cached instance (creating one if needed).
+ */
+export declare function getImageOptimizer(config?: Partial<ImageOptimizerConfig>): ImageOptimizer;
+export {};
+//# sourceMappingURL=optimizer.d.ts.map

package/dist/services/images/optimizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimizer.d.ts","sourceRoot":"","sources":["../../../src/services/images/optimizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAUH;;GAEG;AACH,KAAK,aAAa,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;AAEjG;;GAEG;AACH,UAAU,mBAAmB;IAC3B,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,aAAa,CAAC;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,UAAU,YAAY;IACpB,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,UAAU,UAAU;IAClB,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,IAAI,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,UAAU,WAAW;IACnB,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,UAAU,oBAAoB;IAC5B,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,eAAe,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,gBAAgB,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAaD;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,MAAM,GAAE,OAAO,CAAC,oBAAoB,CAAM;IAKtD;;;;;;;;;;;OAWG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,WAAW,CAAC;IAIjF;;;;;;OAMG;IACG,YAAY,CAChB,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,YAAY,GAAG,UAAU,GAAG,WAAW,CAAC;IAYnD;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,OAAO,CAAC,cAAc;IAOtB;;;OAGG;IACH,OAAO,CAAC,SAAS;CAoIlB;AAOD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,cAAc,CASxF"}