rag-lite-ts 2.1.0 → 2.2.0

package/dist/esm/core/path-manager.d.ts

@@ -0,0 +1,47 @@
+/**
+ * CORE MODULE — Shared between text-only (rag-lite-ts) and future multimodal (rag-lite-mm)
+ * Model-agnostic. No transformer or modality-specific logic.
+ */
+/**
+ * Manages document path storage and resolution strategies
+ * Model-agnostic - works with any content type (text, image, etc.)
+ */
+export declare class DocumentPathManager {
+    private strategy;
+    private basePath;
+    constructor(strategy: 'absolute' | 'relative', basePath: string);
+    /**
+     * Convert absolute file path to storage path based on strategy
+     * @param absolutePath - The absolute file path
+     * @returns Path to store in database
+     */
+    toStoragePath(absolutePath: string): string;
+    /**
+     * Convert storage path back to absolute path for file operations
+     * @param storagePath - Path stored in database
+     * @returns Absolute path for file operations
+     */
+    toAbsolutePath(storagePath: string): string;
+    /**
+     * Get the current strategy
+     */
+    getStrategy(): 'absolute' | 'relative';
+    /**
+     * Get the current base path
+     */
+    getBasePath(): string;
+    /**
+     * Create a new path manager with different base path (for search/retrieval)
+     * @param newBasePath - New base path to use
+     * @returns New DocumentPathManager instance
+     */
+    withBasePath(newBasePath: string): DocumentPathManager;
+    /**
+     * Create a new path manager with different strategy
+     * @param newStrategy - New strategy to use
+     * @param newBasePath - Optional new base path
+     * @returns New DocumentPathManager instance
+     */
+    withStrategy(newStrategy: 'absolute' | 'relative', newBasePath?: string): DocumentPathManager;
+}
+//# sourceMappingURL=path-manager.d.ts.map

package/dist/esm/core/path-manager.js

@@ -0,0 +1,71 @@
+/**
+ * CORE MODULE — Shared between text-only (rag-lite-ts) and future multimodal (rag-lite-mm)
+ * Model-agnostic. No transformer or modality-specific logic.
+ */
+import { relative, resolve, isAbsolute } from 'path';
+/**
+ * Manages document path storage and resolution strategies
+ * Model-agnostic - works with any content type (text, image, etc.)
+ */
+export class DocumentPathManager {
+    strategy;
+    basePath;
+    constructor(strategy, basePath) {
+        this.strategy = strategy;
+        this.basePath = basePath;
+    }
+    /**
+     * Convert absolute file path to storage path based on strategy
+     * @param absolutePath - The absolute file path
+     * @returns Path to store in database
+     */
+    toStoragePath(absolutePath) {
+        if (this.strategy === 'absolute') {
+            return absolutePath;
+        }
+        // For relative strategy, store path relative to base
+        return relative(this.basePath, absolutePath);
+    }
+    /**
+     * Convert storage path back to absolute path for file operations
+     * @param storagePath - Path stored in database
+     * @returns Absolute path for file operations
+     */
+    toAbsolutePath(storagePath) {
+        if (isAbsolute(storagePath)) {
+            return storagePath;
+        }
+        // Resolve relative path against base path
+        return resolve(this.basePath, storagePath);
+    }
+    /**
+     * Get the current strategy
+     */
+    getStrategy() {
+        return this.strategy;
+    }
+    /**
+     * Get the current base path
+     */
+    getBasePath() {
+        return this.basePath;
+    }
+    /**
+     * Create a new path manager with different base path (for search/retrieval)
+     * @param newBasePath - New base path to use
+     * @returns New DocumentPathManager instance
+     */
+    withBasePath(newBasePath) {
+        return new DocumentPathManager(this.strategy, newBasePath);
+    }
+    /**
+     * Create a new path manager with different strategy
+     * @param newStrategy - New strategy to use
+     * @param newBasePath - Optional new base path
+     * @returns New DocumentPathManager instance
+     */
+    withStrategy(newStrategy, newBasePath) {
+        return new DocumentPathManager(newStrategy, newBasePath || this.basePath);
+    }
+}
+//# sourceMappingURL=path-manager.js.map

package/dist/esm/core/raglite-paths.d.ts

@@ -0,0 +1,121 @@
+/**
+ * RAG-lite Path Management
+ *
+ * Manages the standardized .raglite directory structure as specified in the design:
+ * .raglite/
+ * ├── db.sqlite                    # Database
+ * ├── index.bin                    # Vector index
+ * └── content/                     # Content directory
+ */
+/**
+ * RAG-lite directory structure configuration
+ */
+export interface RagLiteConfig {
+    /** Base directory for RAG-lite files (default: current working directory) */
+    baseDir?: string;
+    /** Custom database filename (default: 'db.sqlite') */
+    dbFilename?: string;
+    /** Custom index filename (default: 'index.bin') */
+    indexFilename?: string;
+    /** Custom content directory name (default: 'content') */
+    contentDirname?: string;
+}
+/**
+ * Resolved RAG-lite paths
+ */
+export interface RagLitePaths {
+    /** Base .raglite directory */
+    ragliteDir: string;
+    /** Database file path */
+    dbPath: string;
+    /** Vector index file path */
+    indexPath: string;
+    /** Content directory path */
+    contentDir: string;
+}
+/**
+ * Resolves and creates the standardized .raglite directory structure
+ *
+ * @param config - Configuration for RAG-lite paths
+ * @returns Resolved paths for all RAG-lite components
+ *
+ * @example
+ * ```typescript
+ * // Use default structure in current directory
+ * const paths = resolveRagLitePaths();
+ * // Results in:
+ * // .raglite/db.sqlite
+ * // .raglite/index.bin
+ * // .raglite/content/
+ *
+ * // Use custom base directory
+ * const paths = resolveRagLitePaths({ baseDir: './my-project' });
+ * // Results in:
+ * // my-project/.raglite/db.sqlite
+ * // my-project/.raglite/index.bin
+ * // my-project/.raglite/content/
+ * ```
+ */
+export declare function resolveRagLitePaths(config?: RagLiteConfig): RagLitePaths;
+/**
+ * Ensures the .raglite directory structure exists
+ *
+ * @param paths - RAG-lite paths to create
+ * @throws {Error} If directory creation fails
+ */
+export declare function ensureRagLiteStructure(paths: RagLitePaths): void;
+/**
+ * Migrates from user-specified paths to standardized .raglite structure
+ *
+ * This function helps transition from the current approach where users specify
+ * arbitrary paths to the standardized .raglite structure.
+ *
+ * @param userDbPath - User-specified database path
+ * @param userIndexPath - User-specified index path
+ * @param config - Configuration for the target .raglite structure
+ * @returns Resolved .raglite paths and migration info
+ *
+ * @example
+ * ```typescript
+ * // Migrate from user paths to .raglite structure
+ * const migration = migrateToRagLiteStructure('./my-db.sqlite', './my-index.bin');
+ *
+ * console.log('Target paths:', migration.paths);
+ * console.log('Migration needed:', migration.needsMigration);
+ *
+ * if (migration.needsMigration) {
+ *   console.log('Files will be moved from:');
+ *   console.log('  DB:', migration.sourceDbPath, '->', migration.paths.dbPath);
+ *   console.log('  Index:', migration.sourceIndexPath, '->', migration.paths.indexPath);
+ * }
+ * ```
+ */
+export declare function migrateToRagLiteStructure(userDbPath: string, userIndexPath: string, config?: RagLiteConfig): {
+    paths: RagLitePaths;
+    needsMigration: boolean;
+    sourceDbPath: string;
+    sourceIndexPath: string;
+};
+/**
+ * Gets the standardized .raglite paths for a given project directory
+ *
+ * This is the recommended way to get RAG-lite paths for new projects.
+ *
+ * @param projectDir - Project directory (default: current working directory)
+ * @returns Standardized RAG-lite paths
+ *
+ * @example
+ * ```typescript
+ * // For current directory
+ * const paths = getStandardRagLitePaths();
+ *
+ * // For specific project
+ * const paths = getStandardRagLitePaths('./my-project');
+ *
+ * // Use with factories
+ * const search = await SearchFactory.create(paths.indexPath, paths.dbPath);
+ * const ingestion = await IngestionFactory.create(paths.dbPath, paths.indexPath);
+ * ```
+ */
+export declare function getStandardRagLitePaths(projectDir?: string): RagLitePaths;
+//# sourceMappingURL=raglite-paths.d.ts.map

package/dist/esm/core/raglite-paths.js

@@ -0,0 +1,145 @@
+/**
+ * RAG-lite Path Management
+ *
+ * Manages the standardized .raglite directory structure as specified in the design:
+ * .raglite/
+ * ├── db.sqlite                    # Database
+ * ├── index.bin                    # Vector index
+ * └── content/                     # Content directory
+ */
+import { join, resolve, dirname } from 'path';
+import { existsSync, mkdirSync } from 'fs';
+/**
+ * Resolves and creates the standardized .raglite directory structure
+ *
+ * @param config - Configuration for RAG-lite paths
+ * @returns Resolved paths for all RAG-lite components
+ *
+ * @example
+ * ```typescript
+ * // Use default structure in current directory
+ * const paths = resolveRagLitePaths();
+ * // Results in:
+ * // .raglite/db.sqlite
+ * // .raglite/index.bin
+ * // .raglite/content/
+ *
+ * // Use custom base directory
+ * const paths = resolveRagLitePaths({ baseDir: './my-project' });
+ * // Results in:
+ * // my-project/.raglite/db.sqlite
+ * // my-project/.raglite/index.bin
+ * // my-project/.raglite/content/
+ * ```
+ */
+export function resolveRagLitePaths(config = {}) {
+    const { baseDir = process.cwd(), dbFilename = 'db.sqlite', indexFilename = 'index.bin', contentDirname = 'content' } = config;
+    // Resolve base directory to absolute path
+    const absoluteBaseDir = resolve(baseDir);
+    // Create .raglite directory structure
+    const ragliteDir = join(absoluteBaseDir, '.raglite');
+    const dbPath = join(ragliteDir, dbFilename);
+    const indexPath = join(ragliteDir, indexFilename);
+    const contentDir = join(ragliteDir, contentDirname);
+    return {
+        ragliteDir,
+        dbPath,
+        indexPath,
+        contentDir
+    };
+}
+/**
+ * Ensures the .raglite directory structure exists
+ *
+ * @param paths - RAG-lite paths to create
+ * @throws {Error} If directory creation fails
+ */
+export function ensureRagLiteStructure(paths) {
+    try {
+        // Create .raglite directory
+        if (!existsSync(paths.ragliteDir)) {
+            mkdirSync(paths.ragliteDir, { recursive: true });
+        }
+        // Create content directory
+        if (!existsSync(paths.contentDir)) {
+            mkdirSync(paths.contentDir, { recursive: true });
+        }
+    }
+    catch (error) {
+        throw new Error(`Failed to create .raglite directory structure: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Migrates from user-specified paths to standardized .raglite structure
+ *
+ * This function helps transition from the current approach where users specify
+ * arbitrary paths to the standardized .raglite structure.
+ *
+ * @param userDbPath - User-specified database path
+ * @param userIndexPath - User-specified index path
+ * @param config - Configuration for the target .raglite structure
+ * @returns Resolved .raglite paths and migration info
+ *
+ * @example
+ * ```typescript
+ * // Migrate from user paths to .raglite structure
+ * const migration = migrateToRagLiteStructure('./my-db.sqlite', './my-index.bin');
+ *
+ * console.log('Target paths:', migration.paths);
+ * console.log('Migration needed:', migration.needsMigration);
+ *
+ * if (migration.needsMigration) {
+ *   console.log('Files will be moved from:');
+ *   console.log('  DB:', migration.sourceDbPath, '->', migration.paths.dbPath);
+ *   console.log('  Index:', migration.sourceIndexPath, '->', migration.paths.indexPath);
+ * }
+ * ```
+ */
+export function migrateToRagLiteStructure(userDbPath, userIndexPath, config = {}) {
+    // Determine base directory from user paths
+    const dbDir = dirname(resolve(userDbPath));
+    const indexDir = dirname(resolve(userIndexPath));
+    // Use the directory containing the database as the base directory
+    // This preserves the user's intended project location
+    const baseDir = config.baseDir || dbDir;
+    // Resolve target .raglite paths
+    const paths = resolveRagLitePaths({ ...config, baseDir });
+    // Check if migration is needed
+    const resolvedUserDbPath = resolve(userDbPath);
+    const resolvedUserIndexPath = resolve(userIndexPath);
+    const needsMigration = (resolvedUserDbPath !== paths.dbPath ||
+        resolvedUserIndexPath !== paths.indexPath);
+    return {
+        paths,
+        needsMigration,
+        sourceDbPath: resolvedUserDbPath,
+        sourceIndexPath: resolvedUserIndexPath
+    };
+}
+/**
+ * Gets the standardized .raglite paths for a given project directory
+ *
+ * This is the recommended way to get RAG-lite paths for new projects.
+ *
+ * @param projectDir - Project directory (default: current working directory)
+ * @returns Standardized RAG-lite paths
+ *
+ * @example
+ * ```typescript
+ * // For current directory
+ * const paths = getStandardRagLitePaths();
+ *
+ * // For specific project
+ * const paths = getStandardRagLitePaths('./my-project');
+ *
+ * // Use with factories
+ * const search = await SearchFactory.create(paths.indexPath, paths.dbPath);
+ * const ingestion = await IngestionFactory.create(paths.dbPath, paths.indexPath);
+ * ```
+ */
+export function getStandardRagLitePaths(projectDir = process.cwd()) {
+    const paths = resolveRagLitePaths({ baseDir: projectDir });
+    ensureRagLiteStructure(paths);
+    return paths;
+}
+//# sourceMappingURL=raglite-paths.js.map

package/dist/esm/core/reranking-config.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Simple Reranking Configuration System
+ *
+ * Provides straightforward configuration types and validation for different
+ * reranking strategies without complex interface patterns.
+ */
+export type RerankingStrategyType = 'cross-encoder' | 'text-derived' | 'disabled';
+export interface RerankingConfig {
+    strategy: RerankingStrategyType;
+    model?: string;
+    enabled: boolean;
+    weights?: {
+        semantic?: number;
+        metadata?: number;
+        visual?: number;
+    };
+    fallback?: RerankingStrategyType;
+}
+export declare const DEFAULT_TEXT_RERANKING_CONFIG: RerankingConfig;
+export declare const DEFAULT_MULTIMODAL_RERANKING_CONFIG: RerankingConfig;
+export declare function validateRerankingStrategy(strategy: string): strategy is RerankingStrategyType;
+export declare function validateRerankingConfig(config: Partial<RerankingConfig>): RerankingConfig;
+export declare function getDefaultRerankingConfig(mode: 'text' | 'multimodal'): RerankingConfig;
+export declare function isStrategySupported(strategy: RerankingStrategyType, mode: 'text' | 'multimodal'): boolean;
+export declare function getSupportedStrategies(mode: 'text' | 'multimodal'): RerankingStrategyType[];
+export declare class RerankingConfigBuilder {
+    private config;
+    strategy(strategy: RerankingStrategyType): this;
+    model(model: string): this;
+    enabled(enabled: boolean): this;
+    weights(weights: {
+        semantic?: number;
+        metadata?: number;
+        visual?: number;
+    }): this;
+    fallback(fallback: RerankingStrategyType): this;
+    build(): RerankingConfig;
+    static textMode(): RerankingConfigBuilder;
+    static multimodalMode(): RerankingConfigBuilder;
+    static disabled(): RerankingConfigBuilder;
+}
+//# sourceMappingURL=reranking-config.d.ts.map

package/dist/esm/core/reranking-config.js

@@ -0,0 +1,147 @@
+/**
+ * Simple Reranking Configuration System
+ *
+ * Provides straightforward configuration types and validation for different
+ * reranking strategies without complex interface patterns.
+ */
+// Default configurations for different modes
+export const DEFAULT_TEXT_RERANKING_CONFIG = {
+    strategy: 'cross-encoder',
+    enabled: true,
+    fallback: 'disabled'
+};
+export const DEFAULT_MULTIMODAL_RERANKING_CONFIG = {
+    strategy: 'text-derived',
+    enabled: true,
+    weights: {
+        semantic: 0.7,
+        metadata: 0.3
+    },
+    fallback: 'disabled'
+};
+// Strategy validation without complex interface patterns
+export function validateRerankingStrategy(strategy) {
+    const validStrategies = [
+        'cross-encoder',
+        'text-derived',
+        'disabled'
+    ];
+    return validStrategies.includes(strategy);
+}
+// Simple strategy validation with clear error messages
+export function validateRerankingConfig(config) {
+    if (!config.strategy) {
+        throw new Error('Reranking strategy is required');
+    }
+    if (!validateRerankingStrategy(config.strategy)) {
+        const validStrategies = ['cross-encoder', 'text-derived', 'disabled'];
+        throw new Error(`Invalid reranking strategy '${config.strategy}'. ` +
+            `Valid strategies: ${validStrategies.join(', ')}`);
+    }
+    // Validate weights if provided
+    if (config.weights) {
+        const { semantic, metadata, visual } = config.weights;
+        if (semantic !== undefined && (semantic < 0 || semantic > 1)) {
+            throw new Error('Semantic weight must be between 0 and 1');
+        }
+        if (metadata !== undefined && (metadata < 0 || metadata > 1)) {
+            throw new Error('Metadata weight must be between 0 and 1');
+        }
+        if (visual !== undefined && (visual < 0 || visual > 1)) {
+            throw new Error('Visual weight must be between 0 and 1');
+        }
+    }
+    // Validate fallback strategy if provided
+    if (config.fallback && !validateRerankingStrategy(config.fallback)) {
+        const validStrategies = ['cross-encoder', 'text-derived', 'disabled'];
+        throw new Error(`Invalid fallback strategy '${config.fallback}'. ` +
+            `Valid strategies: ${validStrategies.join(', ')}`);
+    }
+    return {
+        strategy: config.strategy,
+        enabled: config.strategy === 'disabled' ? false : (config.enabled ?? true),
+        model: config.model,
+        weights: config.weights,
+        fallback: config.fallback || 'disabled'
+    };
+}
+// Get appropriate default configuration based on mode
+export function getDefaultRerankingConfig(mode) {
+    switch (mode) {
+        case 'text':
+            return { ...DEFAULT_TEXT_RERANKING_CONFIG };
+        case 'multimodal':
+            return { ...DEFAULT_MULTIMODAL_RERANKING_CONFIG };
+        default:
+            throw new Error(`Unknown mode: ${mode}`);
+    }
+}
+// Check if a strategy is supported for a given mode
+export function isStrategySupported(strategy, mode) {
+    switch (mode) {
+        case 'text':
+            return strategy === 'cross-encoder' || strategy === 'disabled';
+        case 'multimodal':
+            return ['text-derived', 'disabled'].includes(strategy);
+        default:
+            return false;
+    }
+}
+// Get supported strategies for a mode
+export function getSupportedStrategies(mode) {
+    switch (mode) {
+        case 'text':
+            return ['cross-encoder', 'disabled'];
+        case 'multimodal':
+            return ['text-derived', 'disabled'];
+        default:
+            return ['disabled'];
+    }
+}
+// Simple configuration builder for common scenarios
+export class RerankingConfigBuilder {
+    config = {};
+    strategy(strategy) {
+        this.config.strategy = strategy;
+        return this;
+    }
+    model(model) {
+        this.config.model = model;
+        return this;
+    }
+    enabled(enabled) {
+        this.config.enabled = enabled;
+        return this;
+    }
+    weights(weights) {
+        this.config.weights = weights;
+        return this;
+    }
+    fallback(fallback) {
+        this.config.fallback = fallback;
+        return this;
+    }
+    build() {
+        return validateRerankingConfig(this.config);
+    }
+    // Convenience methods for common configurations
+    static textMode() {
+        return new RerankingConfigBuilder()
+            .strategy('cross-encoder')
+            .enabled(true)
+            .fallback('disabled');
+    }
+    static multimodalMode() {
+        return new RerankingConfigBuilder()
+            .strategy('text-derived')
+            .enabled(true)
+            .weights({ semantic: 0.7, metadata: 0.3 })
+            .fallback('disabled');
+    }
+    static disabled() {
+        return new RerankingConfigBuilder()
+            .strategy('disabled')
+            .enabled(false);
+    }
+}
+//# sourceMappingURL=reranking-config.js.map

package/dist/esm/core/reranking-factory.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Simple Reranking Creation Function
+ *
+ * Implements createReranker function with simple conditional logic and automatic
+ * fallback mechanism for failed strategy initialization. Follows the design
+ * principle of using simple functions over complex factory patterns.
+ */
+import type { RerankFunction } from './types.js';
+import type { RerankingStrategyType, RerankingConfig } from './reranking-config.js';
+/**
+ * Simple reranking creation function with conditional logic
+ *
+ * Creates appropriate reranking function based on mode and strategy with
+ * automatic fallback mechanism for failed strategy initialization.
+ *
+ * @param mode - Operating mode ('text' or 'multimodal')
+ * @param strategy - Desired reranking strategy
+ * @param config - Optional configuration for the strategy
+ * @returns RerankFunction or undefined if reranking is disabled
+ */
+export declare function createReranker(mode: 'text' | 'multimodal', strategy?: RerankingStrategyType, config?: Partial<RerankingConfig>): RerankFunction | undefined;
+/**
+ * Create reranker with automatic mode detection
+ *
+ * This is a convenience function that automatically detects the appropriate
+ * default strategy based on mode and creates the reranker.
+ *
+ * @param mode - Operating mode ('text' or 'multimodal')
+ * @param config - Optional configuration override
+ * @returns RerankFunction or undefined if reranking is disabled
+ */
+export declare function createDefaultReranker(mode: 'text' | 'multimodal', config?: Partial<RerankingConfig>): RerankFunction | undefined;
+/**
+ * Check if reranking is available for a given mode and strategy
+ *
+ * This function can be used to test if a reranking strategy can be created
+ * without actually creating it.
+ *
+ * @param mode - Operating mode ('text' or 'multimodal')
+ * @param strategy - Reranking strategy to test
+ * @returns Promise<boolean> indicating if the strategy is available
+ */
+export declare function isRerankingAvailable(mode: 'text' | 'multimodal', strategy?: RerankingStrategyType): Promise<boolean>;
+/**
+ * Get comprehensive information about available reranking strategies for a mode
+ *
+ * @param mode - Operating mode ('text' or 'multimodal')
+ * @returns Object with strategy information and availability
+ */
+export declare function getRerankingInfo(mode: 'text' | 'multimodal'): Promise<{
+    mode: "text" | "multimodal";
+    defaultStrategy: RerankingStrategyType;
+    strategies: {
+        strategy: RerankingStrategyType;
+        supported: boolean;
+        available: boolean;
+        isDefault: boolean;
+        checkDuration: number;
+        error: string | undefined;
+    }[];
+    hasAvailableStrategies: boolean;
+}>;
+/**
+ * Test reranking system health and error recovery
+ *
+ * @param mode - Operating mode to test
+ * @returns Comprehensive health report
+ */
+export declare function testRerankingHealth(mode: 'text' | 'multimodal'): Promise<{
+    mode: 'text' | 'multimodal';
+    overallHealth: 'healthy' | 'degraded' | 'failed';
+    defaultStrategyWorking: boolean;
+    fallbackSystemWorking: boolean;
+    strategyTests: Array<{
+        strategy: RerankingStrategyType;
+        success: boolean;
+        duration: number;
+        error?: string;
+    }>;
+    recommendations: string[];
+}>;
+/**
+ * Get reranking system statistics and performance metrics
+ */
+export declare function getRerankingStats(): {
+    totalCreationAttempts: number;
+    successfulCreations: number;
+    failedCreations: number;
+    fallbacksTriggered: number;
+    strategiesUsed: Record<RerankingStrategyType, number>;
+};
+//# sourceMappingURL=reranking-factory.d.ts.map