/**
 * VLM Pipeline - Batch Image Processing with Embedding Integration
 *
 * Orchestrates the full VLM processing pipeline:
 * 1. Fetch pending images from database
 * 2. Analyze with Chandra VLM (local GPU)
 * 3. Generate embeddings for descriptions
 * 4. Track provenance
 * 5. Update database records
 *
 * @module services/vlm/pipeline
 */
import Database from 'better-sqlite3';
import { ChandraClient } from './chandra.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?: ChandraClient;
        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 in parallel with concurrency control.
     *
     * Uses a semaphore pattern: N worker loops pull from a shared index.
     * Local GPU processing — no rate limiting needed.
     * Aborts batch after 5 consecutive failures to avoid wasting resources.
     *
     * Thread safety: nextIndex++ is safe because JS is single-threaded for
     * synchronous code — the increment happens before the async yield.
     * failuresSinceLastSuccess is intentionally shared across workers: any
     * success from any worker resets it. This makes the abort threshold mean
     * "5 failures without any intervening success across all workers".
     */
    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;
            method: string;
            batchSize: number;
        };
    };
}
/**
 * Create a VLMPipeline with full service integration.
 */
export declare function createVLMPipeline(dbService: DatabaseService, vectorService: VectorService, config?: Partial<PipelineConfig>): VLMPipeline;
//# sourceMappingURL=pipeline.d.ts.map