rag-lite-ts 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 RAG-lite TS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,240 @@
+# RAG-lite TS
+*A local-first, TypeScript-friendly retrieval engine*
+
+A local-first TypeScript retrieval engine for semantic search over static documents. Built to be lightweight, modular, and hackable with zero external run-time dependencies.
+
+![Pipeline](docs/assets/pipeline.jpg)
+
+## Features
+
+- 🏠 **Local-first**: All processing happens offline on your machine
+- 🚀 **Fast**: Sub-100ms queries for typical document collections
+- 📝 **Simple**: No ORMs, frameworks, or complex abstractions
+- 🔍 **Semantic**: Uses embeddings for meaning-based search, not just keywords
+- 🛠️ **Hackable**: Clear module boundaries and minimal dependencies
+- 📦 **Dual Interface**: CLI + MCP server entry points in one package
+- 🎯 **TypeScript**: Full type safety with ESM-only architecture
+- 🧠 **Multi-Model**: Support for multiple embedding models with automatic compatibility checking
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [How It Works](#how-it-works)
+- [Supported Models](#supported-models)
+- [MCP Server Integration](#mcp-server-integration)
+- [Documentation](#documentation)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install -g rag-lite-ts
+```
+
+### Basic Usage
+
+```bash
+# Ingest documents
+raglite ingest ./docs/
+
+# Search your documents
+raglite search "machine learning concepts"
+
+# Get more results with reranking
+raglite search "API documentation" --top-k 10 --rerank
+```
+
+### Using Different Models
+
+```bash
+# Use higher quality model (auto-rebuilds if needed)
+raglite ingest ./docs/ --model Xenova/all-mpnet-base-v2 --rebuild-if-needed
+
+# Search automatically uses the correct model
+raglite search "complex query"
+```
+
+### Programmatic Usage
+
+```typescript
+import { SearchEngine, IngestionPipeline, initializeEmbeddingEngine } from 'rag-lite-ts';
+
+// Initialize and ingest
+const embedder = await initializeEmbeddingEngine();
+const pipeline = new IngestionPipeline('./data/', embedder);
+await pipeline.ingestDirectory('./docs/');
+
+// Search
+const searchEngine = new SearchEngine('./vector-index.bin', './db.sqlite');
+const results = await searchEngine.search('machine learning', { top_k: 10 });
+```
+
+→ **[Complete CLI Reference](docs/cli-reference.md)** | **[API Documentation](docs/api-reference.md)**
+
+## How It Works
+
+RAG-lite TS follows a simple pipeline:
+
+1. **Document Ingestion**: Reads `.md`, `.txt`, `.mdx`, `.pdf`, and `.docx` files
+2. **Preprocessing**: Cleans content (JSX components, Mermaid diagrams, code blocks)
+3. **Semantic Chunking**: Splits documents at natural boundaries with token limits
+4. **Embedding Generation**: Uses transformers.js models for semantic vectors
+5. **Vector Storage**: Fast similarity search with hnswlib-wasm
+6. **Metadata Storage**: SQLite for document info and model compatibility
+7. **Search**: Embeds queries and finds similar chunks using cosine similarity
+8. **Reranking** (optional): Cross-encoder models for improved relevance
+
+### Architecture
+
+```
+Documents → Preprocessor → Chunker → Embedder → Vector Index
+                                        ↓
+Query → Embedder → Vector Search → SQLite Lookup → Results
+```
+
+→ **[Document Preprocessing Guide](docs/preprocessing.md)** | **[Model Management Details](models/README.md)**
+
+## Supported Models
+
+RAG-lite TS supports multiple embedding models with automatic optimization:
+
+| Model | Dimensions | Speed | Use Case |
+|-------|------------|-------|----------|
+| `sentence-transformers/all-MiniLM-L6-v2` | 384 | Fast | General purpose (default) |
+| `Xenova/all-mpnet-base-v2` | 768 | Slower | Higher quality, complex queries |
+
+**Model Features:**
+- **Automatic downloads**: Models cached locally on first use
+- **Smart compatibility**: Detects model changes and prompts rebuilds
+- **Offline support**: Pre-download for offline environments
+- **Reranking**: Optional cross-encoder models for better relevance
+
+→ **[Complete Model Guide](docs/model-guide.md)** | **[Performance Benchmarks](docs/EMBEDDING_MODELS_COMPARISON.md)**
+
+
+
+
+## MCP Server Integration
+
+RAG-lite TS includes a Model Context Protocol (MCP) server for integration with AI agents.
+
+```bash
+# Start MCP server
+raglite-mcp
+```
+
+**MCP Configuration:**
+```json
+{
+  "mcpServers": {
+    "rag-lite": {
+      "command": "raglite-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+**Available Tools:** `search_documents`, `ingest_documents`, `rebuild_index`, `get_stats`
+
+→ **[Complete MCP Integration Guide](docs/cli-reference.md#mcp-server)**
+
+## Documentation
+
+### 📚 Core Guides
+- **[CLI Reference](docs/cli-reference.md)** - Complete command-line documentation
+- **[API Reference](docs/api-reference.md)** - Programmatic usage and types
+- **[Configuration Guide](docs/configuration.md)** - Advanced configuration options
+
+### 🔧 Specialized Guides  
+- **[Model Selection Guide](docs/model-guide.md)** - Embedding models and performance
+- **[Path Storage Strategies](docs/path-strategies.md)** - Document path management
+- **[Document Preprocessing](docs/preprocessing.md)** - Content processing options
+- **[Troubleshooting Guide](docs/troubleshooting.md)** - Common issues and solutions
+
+### 📊 Technical References
+- **[Embedding Models Comparison](docs/EMBEDDING_MODELS_COMPARISON.md)** - Detailed benchmarks
+- **[Documentation Hub](docs/README.md)** - Complete documentation index
+
+### Quick Links by Use Case
+
+| Use Case | Primary Guide | Supporting Guides |
+|----------|---------------|-------------------|
+| **Getting Started** | [CLI Reference](docs/cli-reference.md) | [Configuration](docs/configuration.md) |
+| **Model Selection** | [Model Guide](docs/model-guide.md) | [Performance Benchmarks](docs/EMBEDDING_MODELS_COMPARISON.md) |
+| **Production Setup** | [Configuration Guide](docs/configuration.md) | [Path Strategies](docs/path-strategies.md) |
+| **File Processing** | [Preprocessing Guide](docs/preprocessing.md) | [Troubleshooting](docs/troubleshooting.md) |
+| **Integration** | [API Reference](docs/api-reference.md) | [Configuration](docs/configuration.md) |
+| **Issue Resolution** | [Troubleshooting Guide](docs/troubleshooting.md) | All guides |
+
+## Development
+
+### Building from Source
+
+```bash
+# Clone and setup
+git clone https://github.com/your-username/rag-lite-ts.git
+cd rag-lite-ts
+npm install
+
+# Build and link for development
+npm run build
+npm link  # Makes raglite/raglite-mcp available globally
+
+# Run tests
+npm test
+npm run test:integration
+```
+
+### Project Structure
+
+```
+src/
+├── index.ts              # Main exports
+├── config.ts             # Configuration system
+├── db.ts                 # SQLite operations
+├── embedder.ts           # Embedding generation
+├── search.ts             # Search engine
+├── ingestion.ts          # Document ingestion
+├── preprocess.ts         # Document preprocessing
+├── cli.ts                # CLI interface
+├── mcp-server.ts         # MCP server
+└── preprocessors/        # Content type processors
+
+dist/                     # Compiled output
+```
+
+### Design Philosophy
+
+**"Boringly Simple" Approach:**
+- ✅ Raw SQLite queries (no ORMs)
+- ✅ Direct function calls (no REST/GraphQL)
+- ✅ Simple configuration objects
+- ✅ Minimal abstractions
+- ❌ No complex frameworks or dependency injection
+
+This keeps the codebase hackable and maintainable while providing all functionality needed for local semantic search.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch  
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass
+6. Submit a pull request
+
+Please maintain the "boringly simple" philosophy - avoid unnecessary abstractions or dependencies.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Related Projects
+
+- **[transformers.js](https://github.com/xenova/transformers.js)** - Client-side ML models
+- **[hnswlib](https://github.com/nmslib/hnswlib)** - Fast approximate nearest neighbor search

package/dist/api-errors.d.ts

@@ -0,0 +1,90 @@
+/**
+ * User-friendly error classes with actionable suggestions
+ * Requirements: 5.3 - Create user-friendly error classes with actionable suggestions
+ */
+/**
+ * Base class for API errors with actionable suggestions
+ */
+export declare abstract class APIError extends Error {
+    code: string;
+    suggestions: string[];
+    context?: string | undefined;
+    constructor(message: string, code: string, suggestions: string[], context?: string | undefined);
+    /**
+     * Get formatted error message with suggestions
+     */
+    getFormattedMessage(): string;
+    /**
+     * Log the error with proper formatting
+     */
+    logError(): void;
+}
+/**
+ * Ingestion-related errors
+ */
+export declare class IngestionError extends APIError {
+    constructor(message: string, code: string, suggestions: string[], context?: string);
+}
+/**
+ * Search-related errors
+ */
+export declare class SearchError extends APIError {
+    constructor(message: string, code: string, suggestions: string[], context?: string);
+}
+/**
+ * Resource management errors
+ */
+export declare class ResourceError extends APIError {
+    constructor(message: string, code: string, suggestions: string[], context?: string);
+}
+/**
+ * Model compatibility errors
+ */
+export declare class ModelCompatibilityError extends APIError {
+    constructor(message: string, code: string, suggestions: string[], context?: string);
+}
+/**
+ * Error factory for creating user-friendly errors from internal errors
+ * Requirements: 5.3 - Map internal errors to clear guidance
+ */
+export declare class ErrorFactory {
+    /**
+     * Create user-friendly ingestion error from internal error
+     */
+    static createIngestionError(error: unknown, context: string): IngestionError;
+    /**
+     * Create user-friendly search error from internal error
+     */
+    static createSearchError(error: unknown, context: string): SearchError;
+    /**
+     * Create user-friendly resource error from internal error
+     */
+    static createResourceError(error: unknown, context: string): ResourceError;
+}
+/**
+ * Common error scenarios with predefined messages and suggestions
+ * Requirements: 5.3 - Add specific error handling for common scenarios
+ */
+export declare const CommonErrors: {
+    /**
+     * Error when trying to search without running ingestion first
+     */
+    NO_DOCUMENTS_INGESTED: SearchError;
+    /**
+     * Error when model versions don't match
+     */
+    MODEL_VERSION_MISMATCH: ModelCompatibilityError;
+    /**
+     * Error when required files are missing
+     */
+    MISSING_REQUIRED_FILES: SearchError;
+    /**
+     * Error when initialization fails
+     */
+    INITIALIZATION_FAILED: ResourceError;
+};
+/**
+ * Utility function to handle and log errors appropriately
+ */
+export declare function handleAPIError(error: unknown, context: string, operation: 'ingestion' | 'search' | 'resource'): never;
+//# sourceMappingURL=api-errors.d.ts.map

package/dist/api-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-errors.d.ts","sourceRoot":"","sources":["../src/api-errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,8BAAsB,QAAS,SAAQ,KAAK;IAGjC,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,MAAM,EAAE;IACrB,OAAO,CAAC,EAAE,MAAM;gBAHvB,OAAO,EAAE,MAAM,EACR,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EAAE,EACrB,OAAO,CAAC,EAAE,MAAM,YAAA;IAMzB;;OAEG;IACH,mBAAmB,IAAI,MAAM;IAa7B;;OAEG;IACH,QAAQ,IAAI,IAAI;CAejB;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,QAAQ;gBAC9B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM;CAGnF;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,QAAQ;gBAC3B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM;CAGnF;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM;CAGnF;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,QAAQ;gBACvC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM;CAGnF;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB;;OAEG;IACH,MAAM,CAAC,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc;IA+G5E;;OAEG;IACH,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW;IA4HtE;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa;CA4C3E;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY;IACvB;;OAEG;;IAYH;;OAEG;;IAYH;;OAEG;;IAYH;;OAEG;;CAYJ,CAAC;AAEF;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,KAAK,CA4BrH"}

package/dist/api-errors.js

@@ -0,0 +1,320 @@
+/**
+ * User-friendly error classes with actionable suggestions
+ * Requirements: 5.3 - Create user-friendly error classes with actionable suggestions
+ */
+/**
+ * Base class for API errors with actionable suggestions
+ */
+export class APIError extends Error {
+    code;
+    suggestions;
+    context;
+    constructor(message, code, suggestions, context) {
+        super(message);
+        this.code = code;
+        this.suggestions = suggestions;
+        this.context = context;
+        this.name = this.constructor.name;
+    }
+    /**
+     * Get formatted error message with suggestions
+     */
+    getFormattedMessage() {
+        let formatted = this.message;
+        if (this.suggestions.length > 0) {
+            formatted += '\n\nSuggestions:';
+            this.suggestions.forEach((suggestion, index) => {
+                formatted += `\n  ${index + 1}. ${suggestion}`;
+            });
+        }
+        return formatted;
+    }
+    /**
+     * Log the error with proper formatting
+     */
+    logError() {
+        console.error(`\n${this.name}: ${this.message}`);
+        if (this.context) {
+            console.error(`Context: ${this.context}`);
+        }
+        if (this.suggestions.length > 0) {
+            console.error('\nSuggestions:');
+            this.suggestions.forEach((suggestion, index) => {
+                console.error(`  ${index + 1}. ${suggestion}`);
+            });
+        }
+        console.error(''); // Empty line for better readability
+    }
+}
+/**
+ * Ingestion-related errors
+ */
+export class IngestionError extends APIError {
+    constructor(message, code, suggestions, context) {
+        super(message, code, suggestions, context);
+    }
+}
+/**
+ * Search-related errors
+ */
+export class SearchError extends APIError {
+    constructor(message, code, suggestions, context) {
+        super(message, code, suggestions, context);
+    }
+}
+/**
+ * Resource management errors
+ */
+export class ResourceError extends APIError {
+    constructor(message, code, suggestions, context) {
+        super(message, code, suggestions, context);
+    }
+}
+/**
+ * Model compatibility errors
+ */
+export class ModelCompatibilityError extends APIError {
+    constructor(message, code, suggestions, context) {
+        super(message, code, suggestions, context);
+    }
+}
+/**
+ * Error factory for creating user-friendly errors from internal errors
+ * Requirements: 5.3 - Map internal errors to clear guidance
+ */
+export class ErrorFactory {
+    /**
+     * Create user-friendly ingestion error from internal error
+     */
+    static createIngestionError(error, context) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        // Handle common error scenarios with specific guidance
+        if (errorMessage.includes('ENOENT') || errorMessage.includes('no such file')) {
+            if (context === 'path_validation') {
+                return new IngestionError(`Directory or file path does not exist: ${errorMessage}`, 'PATH_NOT_FOUND', [
+                    'Check that the path exists and is accessible',
+                    'Ensure you have read permissions for the directory',
+                    'Use an absolute path if the relative path is not working'
+                ], context);
+            }
+            else {
+                return new IngestionError(`Required files not found during ${context}`, 'FILES_NOT_FOUND', [
+                    'Ensure the base directory exists and is writable',
+                    'Check file permissions in the target directory',
+                    'Try using an absolute path instead of a relative path'
+                ], context);
+            }
+        }
+        if (errorMessage.includes('EACCES') || errorMessage.includes('permission denied')) {
+            return new IngestionError(`Permission denied during ${context}`, 'PERMISSION_DENIED', [
+                'Check that you have write permissions to the directory',
+                'Try running with appropriate permissions',
+                'Ensure the directory is not read-only'
+            ], context);
+        }
+        if (errorMessage.includes('ENOSPC') || errorMessage.includes('no space left')) {
+            return new IngestionError(`Insufficient disk space during ${context}`, 'DISK_SPACE_FULL', [
+                'Free up disk space in the target directory',
+                'Choose a different location with more available space',
+                'Check disk usage with your system tools'
+            ], context);
+        }
+        if (errorMessage.includes('model') && errorMessage.includes('version')) {
+            return new ModelCompatibilityError(`Embedding model compatibility issue: ${errorMessage}`, 'MODEL_COMPATIBILITY', [
+                'Run pipeline.rebuildIndex() to rebuild with the current model',
+                'Or specify the same model that was used during original ingestion',
+                'Check the model configuration in your setup'
+            ], context);
+        }
+        if (errorMessage.includes('embedding') || errorMessage.includes('model')) {
+            return new IngestionError(`Embedding model initialization failed: ${errorMessage}`, 'MODEL_INIT_FAILED', [
+                'Check your internet connection for model downloads',
+                'Ensure you have sufficient memory available',
+                'Try specifying a different embedding model',
+                'Check that the model name is correct and supported'
+            ], context);
+        }
+        if (errorMessage.includes('database') || errorMessage.includes('sqlite')) {
+            return new IngestionError(`Database initialization failed: ${errorMessage}`, 'DATABASE_ERROR', [
+                'Check that the database file is not corrupted',
+                'Ensure the directory is writable',
+                'Try deleting the database file to start fresh',
+                'Check for sufficient disk space'
+            ], context);
+        }
+        // Generic error with basic suggestions
+        return new IngestionError(`${context} failed: ${errorMessage}`, 'GENERAL_ERROR', [
+            'Check the error message above for specific details',
+            'Ensure all file paths are correct and accessible',
+            'Verify you have necessary permissions',
+            'Try the operation again or contact support if the issue persists'
+        ], context);
+    }
+    /**
+     * Create user-friendly search error from internal error
+     */
+    static createSearchError(error, context) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        // Handle common search error scenarios
+        if (context === 'missing_database') {
+            return new SearchError(`Database file not found`, 'DATABASE_NOT_FOUND', [
+                'Run ingestion first to create the database: pipeline.ingestDirectory("./docs/")',
+                'Check that the database path is correct',
+                'Ensure the ingestion process completed successfully'
+            ], context);
+        }
+        if (context === 'missing_index') {
+            return new SearchError(`Vector index file not found`, 'INDEX_NOT_FOUND', [
+                'Run ingestion first to create the index: pipeline.ingestDirectory("./docs/")',
+                'Check that the index path is correct',
+                'Ensure the ingestion process completed successfully'
+            ], context);
+        }
+        if (context === 'missing_model_info') {
+            return new SearchError('No embedding model information found in database. The database may be from an older version or corrupted.', 'MODEL_INFO_NOT_FOUND', [
+                'Run ingestion again to store model information: pipeline.ingestDirectory("./docs/")',
+                'If the problem persists, delete the database and index files and run ingestion from scratch',
+                'Check that the database was created with a compatible version of the library'
+            ], context);
+        }
+        if (context === 'model_loading') {
+            return new SearchError(`Failed to load embedding model: ${errorMessage}`, 'MODEL_LOADING_FAILED', [
+                'Check that the model name is correct and supported',
+                'Ensure you have internet connection for model download',
+                'Try running ingestion again with a supported model',
+                'Check the model configuration in your setup'
+            ], context);
+        }
+        if (context === 'model_compatibility' || (errorMessage.includes('model') && errorMessage.includes('mismatch'))) {
+            return new ModelCompatibilityError(`Model compatibility issue detected: ${errorMessage}`, 'MODEL_COMPATIBILITY', [
+                'The stored model information doesn\'t match the current configuration',
+                'Run pipeline.rebuildIndex() to rebuild with the current model',
+                'Or ensure you\'re using the same model that was used during ingestion',
+                'Check that the index and database files are from the same ingestion run'
+            ], context);
+        }
+        if (errorMessage.includes('ENOENT') || errorMessage.includes('no such file')) {
+            return new SearchError(`Required files not found: ${errorMessage}`, 'FILES_NOT_FOUND', [
+                'Run ingestion first to create the required files',
+                'Check that the file paths are correct',
+                'Ensure you have read permissions for the files'
+            ], context);
+        }
+        if (errorMessage.includes('EACCES') || errorMessage.includes('permission denied')) {
+            return new SearchError(`Permission denied: ${errorMessage}`, 'PERMISSION_DENIED', [
+                'Check that you have read permissions for the database and index files',
+                'Ensure the files are not locked by another process',
+                'Try running with appropriate permissions'
+            ], context);
+        }
+        if (errorMessage.includes('database') || errorMessage.includes('sqlite')) {
+            return new SearchError(`Database error: ${errorMessage}`, 'DATABASE_ERROR', [
+                'Check that the database file is not corrupted',
+                'Ensure no other processes are using the database',
+                'Try recreating the database by running ingestion again'
+            ], context);
+        }
+        // Generic error with basic suggestions
+        return new SearchError(`Search engine ${context} failed: ${errorMessage}`, 'GENERAL_ERROR', [
+            'Check the error message above for specific details',
+            'Ensure all required files exist and are accessible',
+            'Try running ingestion first if you haven\'t already',
+            'Contact support if the issue persists'
+        ], context);
+    }
+    /**
+     * Create user-friendly resource error from internal error
+     */
+    static createResourceError(error, context) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (errorMessage.includes('initialization')) {
+            return new ResourceError(`Resource initialization failed: ${errorMessage}`, 'INITIALIZATION_FAILED', [
+                'Check that all required files exist and are accessible',
+                'Ensure you have proper permissions for the resource files',
+                'Try cleaning up and reinitializing the resources',
+                'Check for sufficient disk space and memory'
+            ], context);
+        }
+        if (errorMessage.includes('cleanup')) {
+            return new ResourceError(`Resource cleanup failed: ${errorMessage}`, 'CLEANUP_FAILED', [
+                'Some resources may not have been properly released',
+                'Try restarting the application to ensure clean state',
+                'Check for any locked files or processes',
+                'This may not affect functionality but could cause resource leaks'
+            ], context);
+        }
+        // Generic resource error
+        return new ResourceError(`Resource management error: ${errorMessage}`, 'RESOURCE_ERROR', [
+            'Check the error message above for specific details',
+            'Try restarting the application',
+            'Ensure sufficient system resources are available',
+            'Contact support if the issue persists'
+        ], context);
+    }
+}
+/**
+ * Common error scenarios with predefined messages and suggestions
+ * Requirements: 5.3 - Add specific error handling for common scenarios
+ */
+export const CommonErrors = {
+    /**
+     * Error when trying to search without running ingestion first
+     */
+    NO_DOCUMENTS_INGESTED: new SearchError('No documents found to search. Run ingestion first.', 'NO_DOCUMENTS', [
+        'Call pipeline.ingestDirectory("./docs/") to add documents',
+        'Check that your document directory contains .md, .txt, or .mdx files',
+        'Ensure the ingestion process completed successfully'
+    ], 'search_initialization'),
+    /**
+     * Error when model versions don't match
+     */
+    MODEL_VERSION_MISMATCH: new ModelCompatibilityError('Embedding model version mismatch detected between stored index and current configuration.', 'MODEL_MISMATCH', [
+        'Run pipeline.rebuildIndex() to rebuild with current model',
+        'Or specify the same model used during ingestion',
+        'Check your model configuration settings'
+    ], 'model_validation'),
+    /**
+     * Error when required files are missing
+     */
+    MISSING_REQUIRED_FILES: new SearchError('Required database or index files are missing.', 'MISSING_FILES', [
+        'Run ingestion first: pipeline.ingestDirectory("./docs/")',
+        'Check that the file paths are correct',
+        'Ensure the ingestion process completed without errors'
+    ], 'file_validation'),
+    /**
+     * Error when initialization fails
+     */
+    INITIALIZATION_FAILED: new ResourceError('Failed to initialize required resources.', 'INIT_FAILED', [
+        'Check that all file paths are correct and accessible',
+        'Ensure you have proper read/write permissions',
+        'Try running ingestion first if this is a new setup',
+        'Check for sufficient disk space and memory'
+    ], 'resource_initialization')
+};
+/**
+ * Utility function to handle and log errors appropriately
+ */
+export function handleAPIError(error, context, operation) {
+    let apiError;
+    if (error instanceof APIError) {
+        apiError = error;
+    }
+    else {
+        switch (operation) {
+            case 'ingestion':
+                apiError = ErrorFactory.createIngestionError(error, context);
+                break;
+            case 'search':
+                apiError = ErrorFactory.createSearchError(error, context);
+                break;
+            case 'resource':
+                apiError = ErrorFactory.createResourceError(error, context);
+                break;
+            default:
+                apiError = new ResourceError(`Unexpected error in ${context}: ${error instanceof Error ? error.message : String(error)}`, 'UNEXPECTED_ERROR', ['Contact support with the error details above'], context);
+        }
+    }
+    apiError.logError();
+    throw apiError;
+}
+//# sourceMappingURL=api-errors.js.map