ocr-provenance-mcp 1.0.0

package/dist/services/vlm/pipeline.d.ts

@@ -0,0 +1,194 @@
+/**
+ * VLM Pipeline - Batch Image Processing with Embedding Integration
+ *
+ * Orchestrates the full VLM processing pipeline:
+ * 1. Fetch pending images from database
+ * 2. Analyze with Gemini VLM
+ * 3. Generate embeddings for descriptions
+ * 4. Track provenance
+ * 5. Update database records
+ *
+ * @module services/vlm/pipeline
+ */
+import Database from 'better-sqlite3';
+import { VLMService } from './service.js';
+import { NomicEmbeddingClient } from '../embedding/nomic.js';
+import { DatabaseService } from '../storage/database/index.js';
+import { VectorService } from '../storage/vector.js';
+import { ImageOptimizer } from '../images/optimizer.js';
+import type { ImageOptimizationConfig } from '../../server/types.js';
+/**
+ * Pipeline configuration options
+ */
+export interface PipelineConfig {
+    /** Number of images per processing batch */
+    batchSize: number;
+    /** Max concurrent VLM requests */
+    concurrency: number;
+    /** Minimum confidence threshold */
+    minConfidence: number;
+    /** Use universal blind-person-detail prompt for all images (default: true) */
+    useUniversalPrompt: boolean;
+    /** Skip embedding generation */
+    skipEmbeddings: boolean;
+    /** Skip provenance tracking */
+    skipProvenance: boolean;
+    /** Image optimization settings */
+    imageOptimization: ImageOptimizationConfig;
+}
+/**
+ * Result of processing a single image
+ */
+export interface ProcessingResult {
+    imageId: string;
+    success: boolean;
+    description?: string;
+    embeddingId?: string;
+    tokensUsed?: number;
+    confidence?: number;
+    error?: string;
+    processingTimeMs: number;
+}
+/**
+ * Summary of batch processing
+ */
+export interface BatchResult {
+    total: number;
+    successful: number;
+    failed: number;
+    /** Images skipped due to relevance filtering (logos, icons, decorative) */
+    skipped: number;
+    totalTokens: number;
+    totalTimeMs: number;
+    results: ProcessingResult[];
+}
+/**
+ * VLMPipeline - Orchestrates image processing workflow
+ *
+ * Integrates VLM analysis with:
+ * - Database operations (image records)
+ * - Embedding generation (Nomic)
+ * - Vector storage (sqlite-vec)
+ * - Provenance tracking
+ * - Image relevance filtering (logos, icons, decorative elements)
+ */
+export declare class VLMPipeline {
+    private readonly vlm;
+    private readonly embeddingClient;
+    private readonly config;
+    private readonly db;
+    private readonly dbService;
+    private readonly vectorService;
+    private readonly optimizer;
+    constructor(db: Database.Database, options: {
+        config?: Partial<PipelineConfig>;
+        vlmService?: VLMService;
+        embeddingClient?: NomicEmbeddingClient;
+        dbService?: DatabaseService;
+        vectorService: VectorService;
+        optimizer?: ImageOptimizer;
+    });
+    /**
+     * Process all images in a document.
+     *
+     * @param documentId - Document UUID
+     * @returns BatchResult with processing summary
+     */
+    processDocument(documentId: string): Promise<BatchResult>;
+    /**
+     * Process all pending images in the database.
+     *
+     * @param limit - Maximum images to process
+     * @returns BatchResult with processing summary
+     */
+    processPending(limit?: number): Promise<BatchResult>;
+    /**
+     * Process a single image by ID.
+     *
+     * @param imageId - Image UUID
+     * @returns ProcessingResult
+     */
+    processOne(imageId: string): Promise<ProcessingResult>;
+    /**
+     * Process array of images in batches.
+     */
+    private processImages;
+    /**
+     * Process a batch of images with rate limiting and exponential backoff.
+     *
+     * F-INTEG-9: Uses exponential backoff on 429/5xx errors (1s -> 2s -> 4s -> ... -> 32s max).
+     * Aborts batch after 5 consecutive failures to avoid wasting resources.
+     */
+    private processBatch;
+    /**
+     * Process a single image through the full pipeline.
+     * Includes relevance filtering to skip logos, icons, and decorative elements.
+     */
+    private processImage;
+    /**
+     * Check if an image should be processed by VLM based on relevance analysis.
+     *
+     * Uses multi-layer heuristics to filter out:
+     * - Tiny images (likely icons)
+     * - Extreme aspect ratios (likely banners/decorative)
+     * - Low color diversity (likely logos)
+     *
+     * @param image - Image reference with dimensions
+     * @returns Object with process flag and reason
+     */
+    private checkImageRelevance;
+    /**
+     * Resize an image for VLM if it exceeds the max dimension.
+     *
+     * @param image - Image reference
+     * @returns Path to resized image, or null if no resize needed
+     */
+    private maybeResizeForVLM;
+    /**
+     * Generate embedding and store in vector database.
+     * Creates EMBEDDING provenance at depth 4 (from VLM_DESCRIPTION).
+     *
+     * @param description - VLM description text to embed
+     * @param image - Source image reference
+     * @param vlmDescriptionProvId - VLM_DESCRIPTION provenance ID for chain tracking
+     */
+    private generateAndStoreEmbedding;
+    /**
+     * Convert ImageAnalysis to VLMStructuredData format.
+     */
+    private convertToStructuredData;
+    /**
+     * Track VLM_DESCRIPTION provenance for VLM processing output.
+     * Chain: DOCUMENT (0) -> OCR_RESULT (1) -> IMAGE (2) -> VLM_DESCRIPTION (3)
+     *
+     * @param image - Source image reference with provenance_id
+     * @param vlmResult - VLM analysis result
+     * @returns Provenance ID for the VLM_DESCRIPTION record (used for embedding chain)
+     */
+    private trackProvenance;
+    /**
+     * Track VLM_DESCRIPTION provenance for a deduplicated image.
+     * Creates provenance record documenting that VLM results were copied from a source image
+     * with identical content hash, preserving full chain: DOCUMENT(0) -> OCR_RESULT(1) -> IMAGE(2) -> VLM_DESCRIPTION(3).
+     *
+     * @param image - The dedup copy image that received copied VLM results
+     * @param source - The source image whose VLM results were copied
+     */
+    private trackDedupProvenance;
+    /**
+     * Get processing statistics.
+     */
+    getStats(): {
+        images: import("../../models/image.js").ImageStats;
+        vlm: {
+            model: string;
+            rateLimiter: import("../gemini/rate-limiter.js").RateLimiterStatus;
+            circuitBreaker: import("../gemini/circuit-breaker.js").CircuitBreakerStatus;
+        };
+    };
+}
+/**
+ * Create a VLMPipeline with full service integration.
+ */
+export declare function createVLMPipeline(dbService: DatabaseService, vectorService: VectorService, config?: Partial<PipelineConfig>): VLMPipeline;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/services/vlm/pipeline.d.ts.map

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