rag-lite-ts 2.1.1 → 2.3.0

package/dist/esm/core/cross-modal-search.js

@@ -0,0 +1,342 @@
+/**
+ * Cross-Modal Search Implementation
+ *
+ * This module extends the core SearchEngine to provide cross-modal search capabilities
+ * that enable text queries to find images and image queries to find text content.
+ *
+ * Task 4.2: Implement cross-modal search functionality
+ * - Update search logic to handle mixed content type results
+ * - Ensure ranking works properly across text and image content
+ * - Test text queries finding relevant images and vice versa
+ *
+ * Requirements addressed:
+ * - 6.1: Enable text queries to find relevant image content
+ * - 6.2: Enable image queries to find relevant text content
+ * - 6.3: Rank mixed content types by semantic similarity
+ */
+import { SearchEngine } from './search.js';
+import { cosineSimilarity } from '../utils/vector-math.js';
+/**
+ * Cross-Modal Search Engine
+ *
+ * Extends the core SearchEngine to provide cross-modal search capabilities.
+ * This implementation enables:
+ * - Text queries finding semantically similar images
+ * - Image queries finding semantically similar text
+ * - Mixed content type results ranked by semantic similarity
+ * - Unified embedding space leveraging CLIP models
+ */
+export class CrossModalSearchEngine extends SearchEngine {
+    embedder; // Reference to the embedder for cross-modal operations
+    constructor(embedFn, indexManager, db, rerankFn, contentResolver, embedder) {
+        super(embedFn, indexManager, db, rerankFn, contentResolver);
+        this.embedder = embedder;
+    }
+    /**
+     * Perform cross-modal search that can find content across different modalities
+     *
+     * This method extends the base search functionality to:
+     * 1. Detect query content type (text or image path)
+     * 2. Generate appropriate embeddings for the query
+     * 3. Search across all content types in the unified embedding space
+     * 4. Rank results by semantic similarity regardless of content type
+     * 5. Apply cross-modal ranking adjustments
+     *
+     * @param query - Search query (text string or image path)
+     * @param options - Cross-modal search options
+     * @returns Promise resolving to cross-modal search results
+     */
+    async crossModalSearch(query, options = {}) {
+        console.log(`🔍 Cross-modal search: "${query.substring(0, 50)}${query.length > 50 ? '...' : ''}"`);
+        // Step 1: Detect query content type
+        const queryContentType = this.detectQueryContentType(query);
+        console.log(`📝 Query content type: ${queryContentType}`);
+        // Step 2: Perform base search with detected content type
+        const baseResults = await this.search(query, {
+            ...options,
+            contentType: queryContentType
+        });
+        // Step 3: Convert to cross-modal results with enhanced metadata
+        const crossModalResults = await this.enhanceResultsWithCrossModalInfo(baseResults, query, queryContentType, options);
+        // Step 4: Apply cross-modal ranking if enabled
+        if (options.enableCrossModalRanking !== false) {
+            return this.applyCrossModalRanking(crossModalResults, query, queryContentType, options);
+        }
+        return crossModalResults;
+    }
+    /**
+     * Search for images using text queries
+     *
+     * @param textQuery - Text description to search for
+     * @param options - Search options
+     * @returns Promise resolving to image search results
+     */
+    async searchImagesWithText(textQuery, options = {}) {
+        console.log(`🖼️ Text-to-image search: "${textQuery}"`);
+        const searchOptions = {
+            ...options,
+            includeContentTypes: ['image'],
+            enableCrossModalRanking: true
+        };
+        return this.crossModalSearch(textQuery, searchOptions);
+    }
+    /**
+     * Search for text using image queries
+     *
+     * @param imagePath - Path to image file to search with
+     * @param options - Search options
+     * @returns Promise resolving to text search results
+     */
+    async searchTextWithImage(imagePath, options = {}) {
+        console.log(`📝 Image-to-text search: "${imagePath}"`);
+        const searchOptions = {
+            ...options,
+            includeContentTypes: ['text'],
+            enableCrossModalRanking: true
+        };
+        return this.crossModalSearch(imagePath, searchOptions);
+    }
+    /**
+     * Search across all content types with unified ranking
+     *
+     * @param query - Search query (text or image path)
+     * @param options - Search options
+     * @returns Promise resolving to mixed content type results
+     */
+    async searchUnified(query, options = {}) {
+        console.log(`🌐 Unified cross-modal search: "${query.substring(0, 50)}${query.length > 50 ? '...' : ''}"`);
+        const searchOptions = {
+            ...options,
+            includeContentTypes: ['text', 'image'],
+            enableCrossModalRanking: true
+        };
+        return this.crossModalSearch(query, searchOptions);
+    }
+    /**
+     * Detect the content type of a query
+     * @private
+     */
+    detectQueryContentType(query) {
+        // Simple heuristic: if query looks like a file path with image extension, treat as image
+        const imageExtensions = ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp'];
+        const lowerQuery = query.toLowerCase();
+        if (imageExtensions.some(ext => lowerQuery.endsWith(ext))) {
+            return 'image';
+        }
+        // Default to text for all other queries
+        return 'text';
+    }
+    /**
+     * Enhance search results with cross-modal information
+     * @private
+     */
+    async enhanceResultsWithCrossModalInfo(results, query, queryContentType, options) {
+        const enhancedResults = [];
+        for (const result of results) {
+            const resultContentType = result.contentType || 'text';
+            const isCrossModal = queryContentType !== resultContentType;
+            // Filter by content type if specified
+            if (options.includeContentTypes &&
+                !options.includeContentTypes.includes(resultContentType)) {
+                continue;
+            }
+            // Calculate semantic similarity for cross-modal results
+            let semanticSimilarity;
+            if (isCrossModal && this.embedder) {
+                try {
+                    semanticSimilarity = await this.calculateSemanticSimilarity(query, result.content, queryContentType, resultContentType);
+                }
+                catch (error) {
+                    console.warn(`Failed to calculate semantic similarity: ${error instanceof Error ? error.message : 'Unknown error'}`);
+                }
+            }
+            // Apply cross-modal threshold if specified
+            if (options.crossModalThreshold &&
+                isCrossModal &&
+                semanticSimilarity !== undefined &&
+                semanticSimilarity < options.crossModalThreshold) {
+                continue;
+            }
+            enhancedResults.push({
+                ...result,
+                isCrossModal,
+                semanticSimilarity,
+                originalScore: result.score
+            });
+        }
+        return enhancedResults;
+    }
+    /**
+     * Apply cross-modal ranking to results
+     * @private
+     */
+    applyCrossModalRanking(results, query, queryContentType, options) {
+        console.log(`🎯 Applying cross-modal ranking to ${results.length} results`);
+        // Sort results by a combination of original score and semantic similarity
+        const rankedResults = results.sort((a, b) => {
+            // For cross-modal results, use semantic similarity if available
+            if (a.isCrossModal && a.semanticSimilarity !== undefined) {
+                const aScore = a.semanticSimilarity;
+                const bScore = b.isCrossModal && b.semanticSimilarity !== undefined
+                    ? b.semanticSimilarity
+                    : b.score;
+                return bScore - aScore;
+            }
+            if (b.isCrossModal && b.semanticSimilarity !== undefined) {
+                const aScore = a.isCrossModal && a.semanticSimilarity !== undefined
+                    ? a.semanticSimilarity
+                    : a.score;
+                const bScore = b.semanticSimilarity;
+                return bScore - aScore;
+            }
+            // For same-modal results, use original score
+            return b.score - a.score;
+        });
+        // Update scores based on ranking
+        rankedResults.forEach((result, index) => {
+            if (result.isCrossModal && result.semanticSimilarity !== undefined) {
+                // Use semantic similarity as the primary score for cross-modal results
+                result.score = result.semanticSimilarity;
+            }
+        });
+        console.log(`✅ Cross-modal ranking applied: ${rankedResults.length} results ranked`);
+        return rankedResults;
+    }
+    /**
+     * Calculate semantic similarity between query and result content
+     * @private
+     */
+    async calculateSemanticSimilarity(query, resultContent, queryContentType, resultContentType) {
+        if (!this.embedder) {
+            throw new Error('Embedder not available for semantic similarity calculation');
+        }
+        try {
+            // Generate embeddings for both query and result
+            let queryEmbedding;
+            let resultEmbedding;
+            if (queryContentType === 'image') {
+                queryEmbedding = await this.embedder.embedImage(query);
+            }
+            else {
+                queryEmbedding = await this.embedder.embedText(query);
+            }
+            if (resultContentType === 'image') {
+                // For image results, we need the image path from metadata
+                // This is a simplified approach - in practice, you'd need proper image path resolution
+                resultEmbedding = await this.embedder.embedText(resultContent); // Fallback to text
+            }
+            else {
+                resultEmbedding = await this.embedder.embedText(resultContent);
+            }
+            // Calculate cosine similarity
+            const similarity = cosineSimilarity(queryEmbedding.vector, resultEmbedding.vector);
+            return Math.max(0, similarity); // Ensure non-negative similarity
+        }
+        catch (error) {
+            console.warn(`Semantic similarity calculation failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            return 0;
+        }
+    }
+    /**
+     * Get cross-modal search statistics
+     */
+    async getCrossModalStats() {
+        const baseStats = await this.getStats();
+        // This would need to be implemented with actual database queries
+        // For now, return basic stats with cross-modal indicators
+        return {
+            totalChunks: baseStats.totalChunks,
+            textChunks: baseStats.totalChunks, // Placeholder
+            imageChunks: 0, // Placeholder
+            crossModalCapable: this.embedder !== undefined,
+            supportedContentTypes: this.embedder?.supportedContentTypes || ['text']
+        };
+    }
+}
+/**
+ * Factory function to create a cross-modal search engine
+ *
+ * @param embedFn - Embedding function that supports multiple content types
+ * @param indexManager - Vector index manager
+ * @param db - Database connection
+ * @param rerankFn - Optional reranking function
+ * @param contentResolver - Content resolver for unified content system
+ * @param embedder - Reference to the embedder for cross-modal operations
+ * @returns CrossModalSearchEngine instance
+ */
+export function createCrossModalSearchEngine(embedFn, indexManager, db, rerankFn, contentResolver, embedder) {
+    return new CrossModalSearchEngine(embedFn, indexManager, db, rerankFn, contentResolver, embedder);
+}
+/**
+ * Utility function to check if a search engine supports cross-modal search
+ *
+ * @param searchEngine - Search engine to check
+ * @returns True if the engine supports cross-modal search
+ */
+export function supportsCrossModalSearch(searchEngine) {
+    return searchEngine instanceof CrossModalSearchEngine;
+}
+/**
+ * Cross-modal search result analyzer
+ * Provides utilities for analyzing cross-modal search results
+ */
+export class CrossModalResultAnalyzer {
+    /**
+     * Analyze cross-modal search results
+     */
+    static analyzeResults(results) {
+        const analysis = {
+            totalResults: results.length,
+            crossModalResults: 0,
+            sameModalResults: 0,
+            averageSemanticSimilarity: 0,
+            contentTypeDistribution: {}
+        };
+        let totalSimilarity = 0;
+        let similarityCount = 0;
+        for (const result of results) {
+            // Count cross-modal vs same-modal results
+            if (result.isCrossModal) {
+                analysis.crossModalResults++;
+            }
+            else {
+                analysis.sameModalResults++;
+            }
+            // Track semantic similarity
+            if (result.semanticSimilarity !== undefined) {
+                totalSimilarity += result.semanticSimilarity;
+                similarityCount++;
+            }
+            // Track content type distribution
+            const contentType = result.contentType || 'unknown';
+            analysis.contentTypeDistribution[contentType] =
+                (analysis.contentTypeDistribution[contentType] || 0) + 1;
+        }
+        // Calculate average semantic similarity
+        if (similarityCount > 0) {
+            analysis.averageSemanticSimilarity = totalSimilarity / similarityCount;
+        }
+        return analysis;
+    }
+    /**
+     * Generate a summary report of cross-modal search results
+     */
+    static generateReport(results, query) {
+        const analysis = this.analyzeResults(results);
+        let report = `Cross-Modal Search Report\n`;
+        report += `========================\n`;
+        report += `Query: "${query.substring(0, 50)}${query.length > 50 ? '...' : ''}"\n`;
+        report += `Total Results: ${analysis.totalResults}\n`;
+        report += `Cross-Modal Results: ${analysis.crossModalResults}\n`;
+        report += `Same-Modal Results: ${analysis.sameModalResults}\n`;
+        if (analysis.averageSemanticSimilarity > 0) {
+            report += `Average Semantic Similarity: ${analysis.averageSemanticSimilarity.toFixed(4)}\n`;
+        }
+        report += `\nContent Type Distribution:\n`;
+        for (const [type, count] of Object.entries(analysis.contentTypeDistribution)) {
+            report += `  ${type}: ${count}\n`;
+        }
+        return report;
+    }
+}
+//# sourceMappingURL=cross-modal-search.js.map

package/dist/esm/core/database-connection-manager.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Database Connection Manager - Centralized connection handling
+ * Prevents database locking issues by managing shared connections
+ * Addresses production issues with MCP server + CLI concurrent usage
+ */
+import { type DatabaseConnection } from './db.js';
+/**
+ * Database Connection Manager
+ * Manages shared database connections to prevent locking issues
+ */
+export declare class DatabaseConnectionManager {
+    private static connections;
+    private static cleanupInterval;
+    private static readonly CLEANUP_INTERVAL;
+    private static readonly MAX_IDLE_TIME;
+    /**
+     * Get a shared database connection
+     * Creates new connection if none exists, otherwise returns existing
+     */
+    static getConnection(dbPath: string): Promise<DatabaseConnection>;
+    /**
+     * Release a database connection reference
+     * Connection is kept alive for potential reuse
+     */
+    static releaseConnection(dbPath: string): Promise<void>;
+    /**
+     * Force close a specific database connection
+     * Use with caution - only for cleanup or error recovery
+     */
+    static forceCloseConnection(dbPath: string): Promise<void>;
+    /**
+     * Close all database connections
+     * Used during application shutdown
+     */
+    static closeAllConnections(): Promise<void>;
+    /**
+     * Get connection statistics for monitoring
+     */
+    static getConnectionStats(): {
+        totalConnections: number;
+        connections: Array<{
+            path: string;
+            refCount: number;
+            lastAccessed: Date;
+            idleTime: number;
+        }>;
+    };
+    /**
+     * Check if a connection exists for a given path
+     */
+    static hasConnection(dbPath: string): boolean;
+    /**
+     * Wait for database to become available
+     * Useful for handling temporary locking issues
+     */
+    static waitForDatabaseAccess(dbPath: string, maxWaitMs?: number): Promise<void>;
+    /**
+     * Normalize database path for consistent key usage
+     */
+    private static normalizePath;
+    /**
+     * Start the cleanup timer for idle connections
+     * Only start if not in CLI mode to prevent hanging
+     */
+    private static startCleanupTimer;
+    /**
+     * Clean up idle connections that haven't been used recently
+     */
+    private static cleanupIdleConnections;
+}
+/**
+ * Convenience function to get a managed database connection
+ * Use this instead of openDatabase() directly
+ */
+export declare function getManagedConnection(dbPath: string): Promise<DatabaseConnection>;
+/**
+ * Convenience function to release a managed database connection
+ * Use this instead of connection.close() directly
+ */
+export declare function releaseManagedConnection(dbPath: string): Promise<void>;
+/**
+ * Enhanced database connection wrapper
+ * Automatically manages connection lifecycle
+ */
+export declare class ManagedDatabaseConnection {
+    private dbPath;
+    private connection;
+    constructor(dbPath: string);
+    /**
+     * Get the underlying database connection
+     * Automatically acquires managed connection on first use
+     */
+    getConnection(): Promise<DatabaseConnection>;
+    /**
+     * Execute a database operation with automatic connection management
+     */
+    execute<T>(operation: (db: DatabaseConnection) => Promise<T>): Promise<T>;
+    /**
+     * Release the managed connection
+     * Connection may be kept alive for reuse by other components
+     */
+    release(): Promise<void>;
+    /**
+     * Force close the connection
+     * Use only during cleanup or error recovery
+     */
+    forceClose(): Promise<void>;
+}
+//# sourceMappingURL=database-connection-manager.d.ts.map