rag-lite-ts 1.0.1 → 1.0.2

package/dist/{error-handler.js → core/error-handler.js}

@@ -1,6 +1,6 @@
 /**
- * Centralized error handling utilities for RAG-lite TS
- * Provides consistent error handling patterns across the application
+ * CORE MODULE — Shared between text-only (rag-lite-ts) and future multimodal (rag-lite-mm)
+ * Model-agnostic. No transformer or modality-specific logic.
  */
 import { EXIT_CODES } from './config.js';
 /**
@@ -45,15 +45,48 @@ export class CategorizedError extends Error {
         this.name = 'CategorizedError';
     }
 }
+/**
+ * Default error context implementation - provides generic guidance
+ */
+class DefaultErrorContext {
+    getErrorMessage(error, context) {
+        return error.message;
+    }
+    getSuggestions(error, context) {
+        return [
+            'Check the error message above for specific details',
+            'Try running the command again',
+            'If the problem persists, please report it as a bug'
+        ];
+    }
+}
+// Global error context - can be injected by implementations
+let globalErrorContext = new DefaultErrorContext();
+/**
+ * Set the global error context for dependency injection
+ * @param errorContext - Implementation-specific error context
+ */
+export function setErrorContext(errorContext) {
+    globalErrorContext = errorContext;
+}
+/**
+ * Get the current error context
+ * @returns Current error context
+ */
+export function getErrorContext() {
+    return globalErrorContext;
+}
 /**
  * Handle errors with appropriate logging and exit behavior
+ * Supports dependency injection of implementation-specific error contexts
  * @param error - Error to handle
  * @param context - Context where error occurred
  * @param options - Handling options
  */
 export function handleError(error, context, options = {}) {
-    const { category = ErrorCategory.GENERAL, severity = ErrorSeverity.ERROR, exitCode = EXIT_CODES.GENERAL_ERROR, skipError = false, showStack = false } = options;
-    const errorMessage = error instanceof Error ? error.message : String(error);
+    const { category = ErrorCategory.GENERAL, severity = ErrorSeverity.ERROR, exitCode = EXIT_CODES.GENERAL_ERROR, skipError = false, showStack = false, errorContext = globalErrorContext } = options;
+    const errorObj = error instanceof Error ? error : new Error(String(error));
+    const errorMessage = errorContext.getErrorMessage(errorObj, context);
     const timestamp = new Date().toISOString();
     // Format error message based on severity
     const severityPrefix = severity === ErrorSeverity.FATAL ? '🚨' :
@@ -67,13 +100,13 @@ export function handleError(error, context, options = {}) {
         console.log(logMessage);
     }
     // Show stack trace for debugging if requested
-    if (showStack && error instanceof Error && error.stack) {
-        console.error('Stack trace:', error.stack);
+    if (showStack && errorObj.stack) {
+        console.error('Stack trace:', errorObj.stack);
     }
     // Handle based on severity
     if (severity === ErrorSeverity.FATAL) {
         console.error('\nThe system cannot continue and will exit immediately.');
-        provideContextualGuidance(category, exitCode);
+        provideContextualGuidance(category, exitCode, errorObj, context, errorContext);
         process.exit(exitCode);
     }
     else if (severity === ErrorSeverity.ERROR && !skipError) {
@@ -82,9 +115,19 @@ export function handleError(error, context, options = {}) {
 }
 /**
  * Provide contextual guidance based on error category and exit code
+ * Uses dependency injection to get implementation-specific suggestions
  */
-function provideContextualGuidance(category, exitCode) {
+function provideContextualGuidance(category, exitCode, error, context, errorContext) {
     console.error('\nTroubleshooting guidance:');
+    // Get implementation-specific suggestions first
+    const customSuggestions = errorContext.getSuggestions(error, context);
+    if (customSuggestions.length > 0) {
+        customSuggestions.forEach(suggestion => {
+            console.error(`- ${suggestion}`);
+        });
+        return;
+    }
+    // Fallback to generic category-based guidance
     switch (category) {
         case ErrorCategory.CONFIGURATION:
             console.error('- Check your configuration file for syntax errors');

package/dist/core/error-handler.js.map

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

package/dist/core/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * CORE MODULE — Shared between text-only (rag-lite-ts) and future multimodal (rag-lite-mm)
+ * Model-agnostic. No transformer or modality-specific logic.
+ *
+ * This module provides the clean re-export surface for the core layer, enabling
+ * dependency injection patterns for different implementations (text-only, multimodal, etc.).
+ *
+ * DEPENDENCY INJECTION ARCHITECTURE:
+ *
+ * The core layer uses explicit dependency injection to maintain clean separation between
+ * model-agnostic logic and implementation-specific components:
+ *
+ * 1. Core Classes (SearchEngine, IngestionPipeline):
+ *    - Accept injected functions (EmbedFunction, RerankFunction) in constructors
+ *    - Coordinate model-agnostic operations (database, vector index, search pipeline)
+ *    - No knowledge of specific embedding models or transformers
+ *
+ * 2. Dependency Injection Interfaces:
+ *    - EmbedFunction: (query: string, contentType?: string) => Promise<EmbeddingResult>
+ *    - RerankFunction: (query: string, results: SearchResult[], contentType?: string) => Promise<SearchResult[]>
+ *    - Support different content types (text, image, etc.) and embedding dimensions
+ *
+ * 3. Usage Patterns:
+ *
+ *    // Direct dependency injection (advanced users)
+ *    const embedFn = await createTextEmbedder();
+ *    const rerankFn = await createTextReranker();
+ *    const indexManager = new IndexManager('./index.bin');
+ *    const db = await openDatabase('./db.sqlite');
+ *    const search = new SearchEngine(embedFn, indexManager, db, rerankFn);
+ *
+ *    // Factory pattern (recommended for common use cases)
+ *    const search = await TextSearchFactory.create('./index.bin', './db.sqlite');
+ *
+ * 4. Extension Points:
+ *    - New implementations (multimodal, custom models) implement the same interfaces
+ *    - Core classes remain unchanged when adding new modalities
+ *    - Plugin architecture enabled through interface-based design
+ *
+ * 5. Benefits:
+ *    - Clean separation of concerns
+ *    - Testability through mock injection
+ *    - Future extensibility without core changes
+ *    - Support for different embedding dimensions and content types
+ */
+export { type ContentDocument, type ContentChunk, type Document, type Chunk, type EmbeddingResult, type SearchResult, type SearchOptions, } from './types.js';
+export { type EmbedFunction, type RerankFunction, type EmbeddingQueryInterface, type RerankingInterface, type SearchEngineConfig, type ContentTypeStrategy, type ModelAgnosticInterface, type ExtendedEmbeddingInterface, type ExtendedRerankingInterface, type SearchPipelineInterface, type SearchDependencyFactory, InterfaceValidator } from './interfaces.js';
+export * from './adapters.js';
+export * from './config.js';
+export { type DatabaseConnection, openDatabase, initializeSchema, insertDocument, insertChunk, upsertDocument, getChunksByEmbeddingIds, getModelVersion, setModelVersion, getStoredModelInfo, setStoredModelInfo } from './db.js';
+export { type VectorIndexOptions, VectorIndex } from './vector-index.js';
+export { type ChunkConfig, type GenericDocument, type GenericChunk, type ChunkingStrategy, ChunkingStrategyRegistry, DEFAULT_CHUNK_CONFIG, chunkingRegistry, chunkGenericDocument, registerTextChunkingStrategy } from './chunker.js';
+export * from './search.js';
+export * from './ingestion.js';
+export * from './path-manager.js';
+export * from './error-handler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAGH,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,KAAK,EACV,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,aAAa,GAEnB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAC/B,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,kBAAkB,EACnB,MAAM,iBAAiB,CAAC;AAGzB,cAAc,eAAe,CAAC;AAG9B,cAAc,aAAa,CAAC;AAG5B,OAAO,EACL,KAAK,kBAAkB,EACvB,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,cAAc,EACd,uBAAuB,EACvB,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,KAAK,kBAAkB,EACvB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,4BAA4B,EAC7B,MAAM,cAAc,CAAC;AAGtB,cAAc,aAAa,CAAC;AAG5B,cAAc,gBAAgB,CAAC;AAG/B,cAAc,mBAAmB,CAAC;AAGlC,cAAc,oBAAoB,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,66 @@
+/**
+ * CORE MODULE — Shared between text-only (rag-lite-ts) and future multimodal (rag-lite-mm)
+ * Model-agnostic. No transformer or modality-specific logic.
+ *
+ * This module provides the clean re-export surface for the core layer, enabling
+ * dependency injection patterns for different implementations (text-only, multimodal, etc.).
+ *
+ * DEPENDENCY INJECTION ARCHITECTURE:
+ *
+ * The core layer uses explicit dependency injection to maintain clean separation between
+ * model-agnostic logic and implementation-specific components:
+ *
+ * 1. Core Classes (SearchEngine, IngestionPipeline):
+ *    - Accept injected functions (EmbedFunction, RerankFunction) in constructors
+ *    - Coordinate model-agnostic operations (database, vector index, search pipeline)
+ *    - No knowledge of specific embedding models or transformers
+ *
+ * 2. Dependency Injection Interfaces:
+ *    - EmbedFunction: (query: string, contentType?: string) => Promise<EmbeddingResult>
+ *    - RerankFunction: (query: string, results: SearchResult[], contentType?: string) => Promise<SearchResult[]>
+ *    - Support different content types (text, image, etc.) and embedding dimensions
+ *
+ * 3. Usage Patterns:
+ *
+ *    // Direct dependency injection (advanced users)
+ *    const embedFn = await createTextEmbedder();
+ *    const rerankFn = await createTextReranker();
+ *    const indexManager = new IndexManager('./index.bin');
+ *    const db = await openDatabase('./db.sqlite');
+ *    const search = new SearchEngine(embedFn, indexManager, db, rerankFn);
+ *
+ *    // Factory pattern (recommended for common use cases)
+ *    const search = await TextSearchFactory.create('./index.bin', './db.sqlite');
+ *
+ * 4. Extension Points:
+ *    - New implementations (multimodal, custom models) implement the same interfaces
+ *    - Core classes remain unchanged when adding new modalities
+ *    - Plugin architecture enabled through interface-based design
+ *
+ * 5. Benefits:
+ *    - Clean separation of concerns
+ *    - Testability through mock injection
+ *    - Future extensibility without core changes
+ *    - Support for different embedding dimensions and content types
+ */
+// Dependency injection interfaces and utilities
+export { InterfaceValidator } from './interfaces.js';
+// Adapter utilities for converting implementations to dependency injection
+export * from './adapters.js';
+// Core configuration management - model-agnostic settings
+export * from './config.js';
+// Database operations - supports different content types through metadata
+export { openDatabase, initializeSchema, insertDocument, insertChunk, upsertDocument, getChunksByEmbeddingIds, getModelVersion, setModelVersion, getStoredModelInfo, setStoredModelInfo } from './db.js';
+// Vector index operations - works with any embedding dimensions
+export { VectorIndex } from './vector-index.js';
+// Generic chunking interfaces and strategies - supports text, image metadata, etc.
+export { ChunkingStrategyRegistry, DEFAULT_CHUNK_CONFIG, chunkingRegistry, chunkGenericDocument, registerTextChunkingStrategy } from './chunker.js';
+// Core search engine - uses dependency injection for embedding and reranking
+export * from './search.js';
+// Core ingestion pipeline - uses dependency injection for embedding
+export * from './ingestion.js';
+// Path management utilities - content-type agnostic
+export * from './path-manager.js';
+// Error handling framework - supports implementation-specific error contexts
+export * from './error-handler.js';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAcH,gDAAgD;AAChD,OAAO,EAYL,kBAAkB,EACnB,MAAM,iBAAiB,CAAC;AAEzB,2EAA2E;AAC3E,cAAc,eAAe,CAAC;AAE9B,0DAA0D;AAC1D,cAAc,aAAa,CAAC;AAE5B,0EAA0E;AAC1E,OAAO,EAEL,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,cAAc,EACd,uBAAuB,EACvB,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAEjB,gEAAgE;AAChE,OAAO,EAEL,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B,mFAAmF;AACnF,OAAO,EAKL,wBAAwB,EACxB,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,4BAA4B,EAC7B,MAAM,cAAc,CAAC;AAEtB,6EAA6E;AAC7E,cAAc,aAAa,CAAC;AAE5B,oEAAoE;AACpE,cAAc,gBAAgB,CAAC;AAE/B,oDAAoD;AACpD,cAAc,mBAAmB,CAAC;AAElC,6EAA6E;AAC7E,cAAc,oBAAoB,CAAC"}

package/dist/core/ingestion.d.ts

@@ -0,0 +1,143 @@
+/**
+ * CORE MODULE — Shared between text-only (rag-lite-ts) and future multimodal (rag-lite-mm)
+ * Model-agnostic. No transformer or modality-specific logic.
+ */
+import { type FileProcessorOptions } from '../file-processor.js';
+import { type ChunkConfig } from './chunker.js';
+import { IndexManager } from '../index-manager.js';
+import { type DatabaseConnection } from './db.js';
+import type { EmbedFunction } from './interfaces.js';
+/**
+ * Options for the ingestion pipeline
+ */
+export interface IngestionOptions {
+    /** File processing options */
+    fileOptions?: FileProcessorOptions;
+    /** Chunking configuration */
+    chunkConfig?: ChunkConfig;
+    /** Whether to force rebuild the index */
+    forceRebuild?: boolean;
+}
+/**
+ * Result of the ingestion process
+ */
+export interface IngestionResult {
+    /** Total documents processed */
+    documentsProcessed: number;
+    /** Total chunks created */
+    chunksCreated: number;
+    /** Total embeddings generated */
+    embeddingsGenerated: number;
+    /** Number of documents that failed processing */
+    documentErrors: number;
+    /** Number of chunks that failed embedding */
+    embeddingErrors: number;
+    /** Processing time in milliseconds */
+    processingTimeMs: number;
+}
+/**
+ * Main ingestion pipeline class
+ * Coordinates the entire process from file discovery to vector storage
+ * Uses explicit dependency injection for clean architecture
+ */
+export declare class IngestionPipeline {
+    private embedFn;
+    private indexManager;
+    private db;
+    private defaultChunkConfig?;
+    private pathManager;
+    /**
+     * Creates a new IngestionPipeline with explicit dependency injection
+     *
+     * DEPENDENCY INJECTION PATTERN:
+     * This constructor requires all dependencies to be explicitly provided, enabling:
+     * - Clean separation between core ingestion logic and implementation-specific components
+     * - Support for different embedding models and content types
+     * - Testability through mock injection
+     * - Future extensibility for multimodal content processing
+     *
+     * @param embedFn - Function to embed document chunks into vectors
+     *   - Signature: (query: string, contentType?: string) => Promise<EmbeddingResult>
+     *   - Must handle chunk text and return consistent embedding format
+     *   - Examples:
+     *     - Text: const embedFn = (text) => textEmbedder.embedSingle(text)
+     *     - Multimodal: const embedFn = (content, type) => type === 'image' ? clipEmbedder.embedImage(content) : clipEmbedder.embedText(content)
+     *     - Custom: const embedFn = (text) => customModel.embed(text)
+     *
+     * @param indexManager - Vector index manager for storing embeddings
+     *   - Handles vector storage and indexing operations
+     *   - Must support the embedding dimensions produced by embedFn
+     *   - Example: new IndexManager('./index.bin')
+     *
+     * @param db - Database connection for metadata storage
+     *   - Stores document and chunk metadata with content type support
+     *   - Supports different content types through metadata fields
+     *   - Example: await openDatabase('./db.sqlite')
+     *
+     * USAGE EXAMPLES:
+     * ```typescript
+     * // Text-only ingestion pipeline
+     * const textEmbedFn = await createTextEmbedder();
+     * const indexManager = new IndexManager('./index.bin');
+     * const db = await openDatabase('./db.sqlite');
+     * const ingestion = new IngestionPipeline(textEmbedFn, indexManager, db);
+     *
+     * // Custom embedding implementation
+     * const customEmbedFn = async (text) => ({
+     *   embedding_id: generateId(),
+     *   vector: await myCustomModel.embed(text)
+     * });
+     * const ingestion = new IngestionPipeline(customEmbedFn, indexManager, db);
+     *
+     * // Multimodal ingestion (future)
+     * const multimodalEmbedFn = async (content, contentType) => {
+     *   if (contentType === 'image') {
+     *     return { embedding_id: generateId(), vector: await clipModel.embedImage(content) };
+     *   }
+     *   return { embedding_id: generateId(), vector: await clipModel.embedText(content) };
+     * };
+     * const ingestion = new IngestionPipeline(multimodalEmbedFn, indexManager, db);
+     * ```
+     */
+    constructor(embedFn: EmbedFunction, indexManager: IndexManager, db: DatabaseConnection, defaultChunkConfig?: ChunkConfig | undefined);
+    /**
+     * Ingest documents from a directory
+     * @param directoryPath - Path to directory containing documents
+     * @param options - Optional ingestion configuration
+     * @returns Promise resolving to ingestion results
+     */
+    ingestDirectory(directoryPath: string, options?: IngestionOptions): Promise<IngestionResult>;
+    /**
+     * Ingest a single file
+     * @param filePath - Path to the file to ingest
+     * @param options - Optional ingestion configuration
+     * @returns Promise resolving to ingestion results
+     */
+    ingestFile(filePath: string, options?: IngestionOptions): Promise<IngestionResult>;
+    /**
+     * Ingest documents from a path (file or directory)
+     * Implements the complete pipeline: file processing → chunking → embedding → storage
+     */
+    ingestPath(path: string, options?: IngestionOptions): Promise<IngestionResult>;
+    /**
+     * Chunk all documents and organize results
+     */
+    private chunkDocuments;
+    /**
+     * Generate embeddings for all chunks with error handling
+     */
+    private generateEmbeddings;
+    /**
+     * Store documents and chunks in database
+     */
+    private storeDocumentsAndChunks;
+    /**
+     * Update vector index with new embeddings
+     */
+    private updateVectorIndex;
+    /**
+     * Clean up resources - explicit cleanup method
+     */
+    cleanup(): Promise<void>;
+}
+//# sourceMappingURL=ingestion.d.ts.map

package/dist/core/ingestion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingestion.d.ts","sourceRoot":"","sources":["../../src/core/ingestion.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAA2B,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC1F,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAA+B,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAI/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8BAA8B;IAC9B,WAAW,CAAC,EAAE,oBAAoB,CAAC;IACnC,6BAA6B;IAC7B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,yCAAyC;IACzC,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,gCAAgC;IAChC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,2BAA2B;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,iCAAiC;IACjC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iDAAiD;IACjD,cAAc,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,eAAe,EAAE,MAAM,CAAC;IACxB,sCAAsC;IACtC,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,qBAAa,iBAAiB;IAyD1B,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,kBAAkB,CAAC;IA3D7B,OAAO,CAAC,WAAW,CAAsB;IAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoDG;gBAEO,OAAO,EAAE,aAAa,EACtB,YAAY,EAAE,YAAY,EAC1B,EAAE,EAAE,kBAAkB,EACtB,kBAAkB,CAAC,EAAE,WAAW,YAAA;IAoB1C;;;;;OAKG;IACG,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IAQtG;;;;;OAKG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IAQ5F;;;OAGG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IAqFxF;;OAEG;YACW,cAAc;IA2C5B;;OAEG;YACW,kBAAkB;IA0ChC;;OAEG;YACW,uBAAuB;IAwErC;;OAEG;YACW,iBAAiB;IAiB/B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ/B"}