@hazeljs/rag 0.2.4 → 0.3.1

package/dist/__tests__/errors/rag.error.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rag.error.test.d.ts.map

package/dist/__tests__/errors/rag.error.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rag.error.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/errors/rag.error.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/errors/rag.error.test.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const rag_error_1 = require("../../errors/rag.error");
+describe('RAGError', () => {
+    describe('constructor', () => {
+        it('should create error with message and code', () => {
+            const error = new rag_error_1.RAGError('Test error', rag_error_1.RAGErrorCode.VECTOR_STORE_ERROR);
+            expect(error).toBeInstanceOf(Error);
+            expect(error).toBeInstanceOf(rag_error_1.RAGError);
+            expect(error.code).toBe(rag_error_1.RAGErrorCode.VECTOR_STORE_ERROR);
+            expect(error.message).toBe('Test error');
+            expect(error.name).toBe('RAGError');
+        });
+        it('should include cause if provided', () => {
+            const cause = new Error('Original error');
+            const error = new rag_error_1.RAGError('Wrapper error', rag_error_1.RAGErrorCode.EMBEDDING_ERROR, cause);
+            expect(error.cause).toBe(cause);
+        });
+    });
+    describe('static factory methods', () => {
+        it('should create vectorStoreError', () => {
+            const error = rag_error_1.RAGError.vectorStoreError('Connection failed');
+            expect(error.code).toBe(rag_error_1.RAGErrorCode.VECTOR_STORE_ERROR);
+            expect(error.message).toBe('Connection failed');
+        });
+        it('should create embeddingError', () => {
+            const error = rag_error_1.RAGError.embeddingError('API key invalid');
+            expect(error.code).toBe(rag_error_1.RAGErrorCode.EMBEDDING_ERROR);
+            expect(error.message).toBe('API key invalid');
+        });
+        it('should create loaderError', () => {
+            const error = rag_error_1.RAGError.loaderError('./test.pdf');
+            expect(error.code).toBe(rag_error_1.RAGErrorCode.LOADER_ERROR);
+            expect(error.message).toContain('./test.pdf');
+        });
+        it('should create splitterError', () => {
+            const error = rag_error_1.RAGError.splitterError('Invalid chunk size');
+            expect(error.code).toBe(rag_error_1.RAGErrorCode.SPLITTER_ERROR);
+            expect(error.message).toBe('Invalid chunk size');
+        });
+        it('should create generationError', () => {
+            const error = rag_error_1.RAGError.generationError('No LLM configured');
+            expect(error.code).toBe(rag_error_1.RAGErrorCode.LLM_GENERATION_ERROR);
+            expect(error.message).toContain('No LLM configured');
+        });
+        it('should create indexError', () => {
+            const error = rag_error_1.RAGError.indexError('Indexing failed');
+            expect(error.code).toBe(rag_error_1.RAGErrorCode.INDEX_ERROR);
+            expect(error.message).toBe('Indexing failed');
+        });
+        it('should create retrievalError', () => {
+            const error = rag_error_1.RAGError.retrievalError('Search failed');
+            expect(error.code).toBe(rag_error_1.RAGErrorCode.RETRIEVAL_ERROR);
+            expect(error.message).toBe('Search failed');
+        });
+        it('should create unsupportedFormat error', () => {
+            const error = rag_error_1.RAGError.unsupportedFormat('.xyz');
+            expect(error.code).toBe(rag_error_1.RAGErrorCode.UNSUPPORTED_FORMAT);
+            expect(error.message).toContain('.xyz');
+        });
+        it('should create missingDependency error', () => {
+            const error = rag_error_1.RAGError.missingDependency('pdf-parse', 'PDF loading');
+            expect(error.code).toBe(rag_error_1.RAGErrorCode.MISSING_DEPENDENCY);
+            expect(error.message).toContain('pdf-parse');
+            expect(error.message).toContain('PDF loading');
+        });
+        it('should create configurationError', () => {
+            const error = rag_error_1.RAGError.configurationError('Invalid config');
+            expect(error.code).toBe(rag_error_1.RAGErrorCode.CONFIGURATION_ERROR);
+            expect(error.message).toBe('Invalid config');
+        });
+    });
+    describe('error handling', () => {
+        it('should be catchable as Error', () => {
+            try {
+                throw rag_error_1.RAGError.vectorStoreError('Test');
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(Error);
+                expect(error).toBeInstanceOf(rag_error_1.RAGError);
+            }
+        });
+        it('should preserve stack trace', () => {
+            const error = rag_error_1.RAGError.embeddingError('Test');
+            expect(error.stack).toBeDefined();
+            expect(error.stack).toContain('RAGError');
+        });
+        it('should handle cause in factory methods', () => {
+            const cause = new Error('Root cause');
+            const error = rag_error_1.RAGError.vectorStoreError('Connection failed', cause);
+            expect(error.cause).toBe(cause);
+        });
+    });
+});
+//# sourceMappingURL=rag.error.test.js.map

package/dist/__tests__/errors/rag.error.test.js.map

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

package/dist/__tests__/reranking/cohere.reranker.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cohere.reranker.test.d.ts.map

package/dist/__tests__/reranking/cohere.reranker.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cohere.reranker.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/reranking/cohere.reranker.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/reranking/cohere.reranker.test.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const cohere_ai_1 = require("cohere-ai");
+const cohere_reranker_1 = require("../../reranking/cohere.reranker");
+// Mock cohere-ai module
+jest.mock('cohere-ai', () => ({
+    CohereClient: jest.fn().mockImplementation(() => ({
+        rerank: jest.fn(),
+    })),
+}), { virtual: true });
+describe('CohereReranker', () => {
+    let reranker;
+    let mockCohereClient;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockCohereClient = new cohere_ai_1.CohereClient();
+        reranker = new cohere_reranker_1.CohereReranker({ apiKey: 'test-key' });
+        // In actual implementation, this.client = new CohereClient
+        // We need to ensure reranker.client is the one we control
+        reranker.client = mockCohereClient;
+    });
+    it('reranks results using Cohere API', async () => {
+        const results = [
+            { id: '1', content: 'Apple is a fruit', score: 0.5, metadata: {} },
+            { id: '2', content: 'Banana is long', score: 0.4, metadata: {} },
+        ];
+        mockCohereClient.rerank.mockResolvedValue({
+            results: [
+                { index: 1, relevanceScore: 0.95 },
+                { index: 0, relevanceScore: 0.85 },
+            ],
+        });
+        const output = await reranker.rerank('Tell me about banana', results);
+        expect(output).toHaveLength(2);
+        expect(output[0].id).toBe('2'); // Banana index 1 moved to top
+        expect(output[0].score).toBe(0.95);
+        expect(output[1].id).toBe('1');
+        expect(output[1].score).toBe(0.85);
+        expect(mockCohereClient.rerank).toHaveBeenCalledWith(expect.objectContaining({
+            query: 'Tell me about banana',
+            documents: ['Apple is a fruit', 'Banana is long'],
+        }));
+    });
+    it('returns empty array if input results are empty', async () => {
+        const output = await reranker.rerank('query', []);
+        expect(output).toEqual([]);
+        expect(mockCohereClient.rerank).not.toHaveBeenCalled();
+    });
+    it('handles Cohere API errors gracefully', async () => {
+        mockCohereClient.rerank.mockRejectedValue(new Error('API Down'));
+        await expect(reranker.rerank('q', [{ id: '1', content: 'c', score: 1, metadata: {} }])).rejects.toThrow('Failed to rerank results using Cohere: Error: API Down');
+    });
+    it('uses default model and maxChunksPerDoc if not provided', () => {
+        const customReranker = new cohere_reranker_1.CohereReranker({ apiKey: 'k' });
+        expect(customReranker.model).toBe('rerank-english-v3.0');
+        expect(customReranker.maxChunksPerDoc).toBe(10);
+    });
+    it('uses custom model and maxChunksPerDoc if provided', () => {
+        const customReranker = new cohere_reranker_1.CohereReranker({
+            apiKey: 'k',
+            model: 'rerank-multilingual-v3.0',
+            maxChunksPerDoc: 5,
+        });
+        expect(customReranker.model).toBe('rerank-multilingual-v3.0');
+        expect(customReranker.maxChunksPerDoc).toBe(5);
+    });
+});
+//# sourceMappingURL=cohere.reranker.test.js.map

package/dist/__tests__/reranking/cohere.reranker.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cohere.reranker.test.js","sourceRoot":"","sources":["../../../src/__tests__/reranking/cohere.reranker.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/utils/debug.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=debug.test.d.ts.map

package/dist/__tests__/utils/debug.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/utils/debug.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/utils/debug.test.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const debug_1 = require("../../utils/debug");
+describe('debug utility', () => {
+    let originalEnv;
+    let consoleErrorSpy;
+    let log;
+    beforeEach(() => {
+        originalEnv = process.env.HAZELJS_DEBUG;
+        consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation();
+        log = (0, debug_1.debug)('rag');
+    });
+    afterEach(() => {
+        if (originalEnv !== undefined) {
+            process.env.HAZELJS_DEBUG = originalEnv;
+        }
+        else {
+            delete process.env.HAZELJS_DEBUG;
+        }
+        consoleErrorSpy.mockRestore();
+        (0, debug_1.setDebugEnabled)(false);
+    });
+    describe('environment variable detection', () => {
+        it('should enable debug when HAZELJS_DEBUG=true', () => {
+            (0, debug_1.setDebugEnabled)(true);
+            log('test message');
+            expect(consoleErrorSpy).toHaveBeenCalled();
+        });
+        it('should enable debug when HAZELJS_DEBUG=1', () => {
+            process.env.HAZELJS_DEBUG = '1';
+            (0, debug_1.setDebugEnabled)(true);
+            log('test message');
+            expect(consoleErrorSpy).toHaveBeenCalled();
+        });
+        it('should not log when debug is disabled', () => {
+            (0, debug_1.setDebugEnabled)(false);
+            log('test message');
+            expect(consoleErrorSpy).not.toHaveBeenCalled();
+        });
+    });
+    describe('setDebugEnabled', () => {
+        it('should enable debug logging', () => {
+            (0, debug_1.setDebugEnabled)(true);
+            log('test message');
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('[hazeljs:rag]'));
+        });
+        it('should disable debug logging', () => {
+            (0, debug_1.setDebugEnabled)(false);
+            log('test message');
+            expect(consoleErrorSpy).not.toHaveBeenCalled();
+        });
+    });
+    describe('debug function', () => {
+        beforeEach(() => {
+            (0, debug_1.setDebugEnabled)(true);
+        });
+        it('should log with timestamp and prefix', () => {
+            log('test message');
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringMatching(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z \[hazeljs:rag\] test message$/));
+        });
+        it('should handle string formatting with %s', () => {
+            log('user=%s action=%s', 'alice', 'login');
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('user=alice action=login'));
+        });
+        it('should handle number formatting with %d', () => {
+            log('count=%d total=%d', 5, 100);
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('count=5 total=100'));
+        });
+        it('should handle JSON formatting with %j', () => {
+            log('data=%j', { key: 'value' });
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('data={"key":"value"}'));
+        });
+        it('should handle remaining arguments', () => {
+            log('message', 'extra', 123);
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('message extra 123'));
+        });
+        it('should create scoped loggers', () => {
+            const aiLog = (0, debug_1.debug)('ai');
+            const ragLog = (0, debug_1.debug)('rag');
+            aiLog('ai message');
+            ragLog('rag message');
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('[hazeljs:ai]'));
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('[hazeljs:rag]'));
+        });
+        it('should not log when disabled', () => {
+            (0, debug_1.setDebugEnabled)(false);
+            log('should not appear');
+            expect(consoleErrorSpy).not.toHaveBeenCalled();
+        });
+    });
+    describe('performance', () => {
+        it('should skip logging when disabled', () => {
+            (0, debug_1.setDebugEnabled)(false);
+            log('message with %s', 'formatting');
+            expect(consoleErrorSpy).not.toHaveBeenCalled();
+        });
+    });
+});
+//# sourceMappingURL=debug.test.js.map

package/dist/__tests__/utils/debug.test.js.map

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

package/dist/errors/rag.error.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Structured RAG errors for robust handling and observability.
+ *
+ * Mirrors the `AgentError` pattern from `@hazeljs/agent` for consistency.
+ */
+export declare enum RAGErrorCode {
+    VECTOR_STORE_ERROR = "RAG_VECTOR_STORE_ERROR",
+    EMBEDDING_ERROR = "RAG_EMBEDDING_ERROR",
+    LOADER_ERROR = "RAG_LOADER_ERROR",
+    SPLITTER_ERROR = "RAG_SPLITTER_ERROR",
+    LLM_GENERATION_ERROR = "RAG_LLM_GENERATION_ERROR",
+    INDEX_ERROR = "RAG_INDEX_ERROR",
+    RETRIEVAL_ERROR = "RAG_RETRIEVAL_ERROR",
+    UNSUPPORTED_FORMAT = "RAG_UNSUPPORTED_FORMAT",
+    MISSING_DEPENDENCY = "RAG_MISSING_DEPENDENCY",
+    CONFIGURATION_ERROR = "RAG_CONFIGURATION_ERROR"
+}
+export declare class RAGError extends Error {
+    readonly code: RAGErrorCode;
+    readonly cause?: Error;
+    constructor(message: string, code: RAGErrorCode, cause?: Error);
+    static vectorStoreError(message: string, cause?: Error): RAGError;
+    static embeddingError(message: string, cause?: Error): RAGError;
+    static loaderError(source: string, cause?: Error): RAGError;
+    static splitterError(message: string, cause?: Error): RAGError;
+    static generationError(message: string, cause?: Error): RAGError;
+    static indexError(message: string, cause?: Error): RAGError;
+    static retrievalError(message: string, cause?: Error): RAGError;
+    static unsupportedFormat(extension: string): RAGError;
+    static missingDependency(packageName: string, feature: string): RAGError;
+    static configurationError(message: string): RAGError;
+}
+//# sourceMappingURL=rag.error.d.ts.map

package/dist/errors/rag.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rag.error.d.ts","sourceRoot":"","sources":["../../src/errors/rag.error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,oBAAY,YAAY;IACtB,kBAAkB,2BAA2B;IAC7C,eAAe,wBAAwB;IACvC,YAAY,qBAAqB;IACjC,cAAc,uBAAuB;IACrC,oBAAoB,6BAA6B;IACjD,WAAW,oBAAoB;IAC/B,eAAe,wBAAwB;IACvC,kBAAkB,2BAA2B;IAC7C,kBAAkB,2BAA2B;IAC7C,mBAAmB,4BAA4B;CAChD;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;gBAEX,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,CAAC,EAAE,KAAK;IAQ9D,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,QAAQ;IAIjE,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,QAAQ;IAI/D,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,QAAQ;IAQ3D,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,QAAQ;IAI9D,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,QAAQ;IAQhE,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,QAAQ;IAI3D,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,QAAQ;IAI/D,MAAM,CAAC,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ;IAQrD,MAAM,CAAC,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ;IAQxE,MAAM,CAAC,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ;CAGrD"}

package/dist/errors/rag.error.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Structured RAG errors for robust handling and observability.
+ *
+ * Mirrors the `AgentError` pattern from `@hazeljs/agent` for consistency.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RAGError = exports.RAGErrorCode = void 0;
+var RAGErrorCode;
+(function (RAGErrorCode) {
+    RAGErrorCode["VECTOR_STORE_ERROR"] = "RAG_VECTOR_STORE_ERROR";
+    RAGErrorCode["EMBEDDING_ERROR"] = "RAG_EMBEDDING_ERROR";
+    RAGErrorCode["LOADER_ERROR"] = "RAG_LOADER_ERROR";
+    RAGErrorCode["SPLITTER_ERROR"] = "RAG_SPLITTER_ERROR";
+    RAGErrorCode["LLM_GENERATION_ERROR"] = "RAG_LLM_GENERATION_ERROR";
+    RAGErrorCode["INDEX_ERROR"] = "RAG_INDEX_ERROR";
+    RAGErrorCode["RETRIEVAL_ERROR"] = "RAG_RETRIEVAL_ERROR";
+    RAGErrorCode["UNSUPPORTED_FORMAT"] = "RAG_UNSUPPORTED_FORMAT";
+    RAGErrorCode["MISSING_DEPENDENCY"] = "RAG_MISSING_DEPENDENCY";
+    RAGErrorCode["CONFIGURATION_ERROR"] = "RAG_CONFIGURATION_ERROR";
+})(RAGErrorCode || (exports.RAGErrorCode = RAGErrorCode = {}));
+class RAGError extends Error {
+    constructor(message, code, cause) {
+        super(message);
+        this.name = 'RAGError';
+        this.code = code;
+        this.cause = cause;
+        Object.setPrototypeOf(this, RAGError.prototype);
+    }
+    static vectorStoreError(message, cause) {
+        return new RAGError(message, RAGErrorCode.VECTOR_STORE_ERROR, cause);
+    }
+    static embeddingError(message, cause) {
+        return new RAGError(message, RAGErrorCode.EMBEDDING_ERROR, cause);
+    }
+    static loaderError(source, cause) {
+        return new RAGError(`Failed to load documents from "${source}". Check that the file exists and is readable.`, RAGErrorCode.LOADER_ERROR, cause);
+    }
+    static splitterError(message, cause) {
+        return new RAGError(message, RAGErrorCode.SPLITTER_ERROR, cause);
+    }
+    static generationError(message, cause) {
+        return new RAGError(`LLM generation failed: ${message}. Ensure an llmFunction is configured.`, RAGErrorCode.LLM_GENERATION_ERROR, cause);
+    }
+    static indexError(message, cause) {
+        return new RAGError(message, RAGErrorCode.INDEX_ERROR, cause);
+    }
+    static retrievalError(message, cause) {
+        return new RAGError(message, RAGErrorCode.RETRIEVAL_ERROR, cause);
+    }
+    static unsupportedFormat(extension) {
+        return new RAGError(`Unsupported file format "${extension}". ` +
+            `Supported: .txt, .log, .json, .csv, .md, .mdx, .html, .htm, .pdf, .docx`, RAGErrorCode.UNSUPPORTED_FORMAT);
+    }
+    static missingDependency(packageName, feature) {
+        return new RAGError(`The "${feature}" feature requires the "${packageName}" package. ` +
+            `Install it with: npm install ${packageName}`, RAGErrorCode.MISSING_DEPENDENCY);
+    }
+    static configurationError(message) {
+        return new RAGError(message, RAGErrorCode.CONFIGURATION_ERROR);
+    }
+}
+exports.RAGError = RAGError;
+//# sourceMappingURL=rag.error.js.map

package/dist/errors/rag.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rag.error.js","sourceRoot":"","sources":["../../src/errors/rag.error.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,IAAY,YAWX;AAXD,WAAY,YAAY;IACtB,6DAA6C,CAAA;IAC7C,uDAAuC,CAAA;IACvC,iDAAiC,CAAA;IACjC,qDAAqC,CAAA;IACrC,iEAAiD,CAAA;IACjD,+CAA+B,CAAA;IAC/B,uDAAuC,CAAA;IACvC,6DAA6C,CAAA;IAC7C,6DAA6C,CAAA;IAC7C,+DAA+C,CAAA;AACjD,CAAC,EAXW,YAAY,4BAAZ,YAAY,QAWvB;AAED,MAAa,QAAS,SAAQ,KAAK;IAIjC,YAAY,OAAe,EAAE,IAAkB,EAAE,KAAa;QAC5D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAClD,CAAC;IAED,MAAM,CAAC,gBAAgB,CAAC,OAAe,EAAE,KAAa;QACpD,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC;IACvE,CAAC;IAED,MAAM,CAAC,cAAc,CAAC,OAAe,EAAE,KAAa;QAClD,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,CAAC,WAAW,CAAC,MAAc,EAAE,KAAa;QAC9C,OAAO,IAAI,QAAQ,CACjB,kCAAkC,MAAM,gDAAgD,EACxF,YAAY,CAAC,YAAY,EACzB,KAAK,CACN,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,aAAa,CAAC,OAAe,EAAE,KAAa;QACjD,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACnE,CAAC;IAED,MAAM,CAAC,eAAe,CAAC,OAAe,EAAE,KAAa;QACnD,OAAO,IAAI,QAAQ,CACjB,0BAA0B,OAAO,wCAAwC,EACzE,YAAY,CAAC,oBAAoB,EACjC,KAAK,CACN,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,UAAU,CAAC,OAAe,EAAE,KAAa;QAC9C,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IAChE,CAAC;IAED,MAAM,CAAC,cAAc,CAAC,OAAe,EAAE,KAAa;QAClD,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,CAAC,iBAAiB,CAAC,SAAiB;QACxC,OAAO,IAAI,QAAQ,CACjB,4BAA4B,SAAS,KAAK;YACxC,yEAAyE,EAC3E,YAAY,CAAC,kBAAkB,CAChC,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,iBAAiB,CAAC,WAAmB,EAAE,OAAe;QAC3D,OAAO,IAAI,QAAQ,CACjB,QAAQ,OAAO,2BAA2B,WAAW,aAAa;YAChE,gCAAgC,WAAW,EAAE,EAC/C,YAAY,CAAC,kBAAkB,CAChC,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,kBAAkB,CAAC,OAAe;QACvC,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,mBAAmB,CAAC,CAAC;IACjE,CAAC;CACF;AAnED,4BAmEC"}

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export * from './decorators/embeddable.decorator';
 export * from './decorators/semantic-search.decorator';
 export * from './embeddings/openai-embeddings';
 export * from './embeddings/cohere-embeddings';
+export * from './reranking/cohere.reranker';
 export * from './vector-stores/memory-vector-store';
 export * from './vector-stores/pinecone.store';
 export * from './vector-stores/qdrant.store';
@@ -26,4 +27,6 @@ export * from './memory';
 export * from './rag-pipeline-with-memory';
 export * from './agentic';
 export * from './graph';
+export { RAGError, RAGErrorCode } from './errors/rag.error';
+export { debug, setDebugEnabled } from './utils/debug';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,cAAc,SAAS,CAAC;AAGxB,cAAc,gBAAgB,CAAC;AAG/B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAG7B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mCAAmC,CAAC;AAClD,cAAc,wCAAwC,CAAC;AAGvD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAG/C,cAAc,qCAAqC,CAAC;AACpD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAG7C,cAAc,0CAA0C,CAAC;AAGzD,cAAc,WAAW,CAAC;AAG1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AAGxC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,UAAU,CAAC;AACzB,cAAc,4BAA4B,CAAC;AAG3C,cAAc,WAAW,CAAC;AAG1B,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,cAAc,SAAS,CAAC;AAGxB,cAAc,gBAAgB,CAAC;AAG/B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAG7B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mCAAmC,CAAC;AAClD,cAAc,wCAAwC,CAAC;AAGvD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAG5C,cAAc,qCAAqC,CAAC;AACpD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAG7C,cAAc,0CAA0C,CAAC;AAGzD,cAAc,WAAW,CAAC;AAG1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AAGxC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,UAAU,CAAC;AACzB,cAAc,4BAA4B,CAAC;AAG3C,cAAc,WAAW,CAAC;AAG1B,cAAc,SAAS,CAAC;AAGxB,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAG5D,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -18,6 +18,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.setDebugEnabled = exports.debug = exports.RAGErrorCode = exports.RAGError = void 0;
 // Core types
 __exportStar(require("./types"), exports);
 // RAG Pipeline
@@ -29,9 +30,10 @@ __exportStar(require("./rag.module"), exports);
 __exportStar(require("./decorators/rag.decorator"), exports);
 __exportStar(require("./decorators/embeddable.decorator"), exports);
 __exportStar(require("./decorators/semantic-search.decorator"), exports);
-// Embeddings
+// Embeddings & Reranking
 __exportStar(require("./embeddings/openai-embeddings"), exports);
 __exportStar(require("./embeddings/cohere-embeddings"), exports);
+__exportStar(require("./reranking/cohere.reranker"), exports);
 // Vector Stores
 __exportStar(require("./vector-stores/memory-vector-store"), exports);
 __exportStar(require("./vector-stores/pinecone.store"), exports);
@@ -55,4 +57,12 @@ __exportStar(require("./rag-pipeline-with-memory"), exports);
 __exportStar(require("./agentic"), exports);
 // GraphRAG - Knowledge graph-based retrieval (entity + community search)
 __exportStar(require("./graph"), exports);
+// Errors
+var rag_error_1 = require("./errors/rag.error");
+Object.defineProperty(exports, "RAGError", { enumerable: true, get: function () { return rag_error_1.RAGError; } });
+Object.defineProperty(exports, "RAGErrorCode", { enumerable: true, get: function () { return rag_error_1.RAGErrorCode; } });
+// Debug utility
+var debug_1 = require("./utils/debug");
+Object.defineProperty(exports, "debug", { enumerable: true, get: function () { return debug_1.debug; } });
+Object.defineProperty(exports, "setDebugEnabled", { enumerable: true, get: function () { return debug_1.setDebugEnabled; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;AAEH,aAAa;AACb,0CAAwB;AAExB,eAAe;AACf,iDAA+B;AAE/B,uBAAuB;AACvB,gDAA8B;AAC9B,+CAA6B;AAE7B,aAAa;AACb,6DAA2C;AAC3C,oEAAkD;AAClD,yEAAuD;AAEvD,aAAa;AACb,iEAA+C;AAC/C,iEAA+C;AAE/C,gBAAgB;AAChB,sEAAoD;AACpD,iEAA+C;AAC/C,+DAA6C;AAC7C,iEAA+C;AAC/C,+DAA6C;AAE7C,iBAAiB;AACjB,2EAAyD;AAEzD,mBAAmB;AACnB,4CAA0B;AAE1B,uBAAuB;AACvB,mDAAiC;AACjC,4DAA0C;AAC1C,0DAAwC;AAExC,QAAQ;AACR,qDAAmC;AAEnC,SAAS;AACT,2CAAyB;AACzB,6DAA2C;AAE3C,2DAA2D;AAC3D,4CAA0B;AAE1B,yEAAyE;AACzE,0CAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;;AAEH,aAAa;AACb,0CAAwB;AAExB,eAAe;AACf,iDAA+B;AAE/B,uBAAuB;AACvB,gDAA8B;AAC9B,+CAA6B;AAE7B,aAAa;AACb,6DAA2C;AAC3C,oEAAkD;AAClD,yEAAuD;AAEvD,yBAAyB;AACzB,iEAA+C;AAC/C,iEAA+C;AAC/C,8DAA4C;AAE5C,gBAAgB;AAChB,sEAAoD;AACpD,iEAA+C;AAC/C,+DAA6C;AAC7C,iEAA+C;AAC/C,+DAA6C;AAE7C,iBAAiB;AACjB,2EAAyD;AAEzD,mBAAmB;AACnB,4CAA0B;AAE1B,uBAAuB;AACvB,mDAAiC;AACjC,4DAA0C;AAC1C,0DAAwC;AAExC,QAAQ;AACR,qDAAmC;AAEnC,SAAS;AACT,2CAAyB;AACzB,6DAA2C;AAE3C,2DAA2D;AAC3D,4CAA0B;AAE1B,yEAAyE;AACzE,0CAAwB;AAExB,SAAS;AACT,gDAA4D;AAAnD,qGAAA,QAAQ,OAAA;AAAE,yGAAA,YAAY,OAAA;AAE/B,gBAAgB;AAChB,uCAAuD;AAA9C,8FAAA,KAAK,OAAA;AAAE,wGAAA,eAAe,OAAA"}

package/dist/rag-pipeline.d.ts

@@ -4,10 +4,47 @@
  */
 import { RAGConfig, RAGQueryOptions, RAGResponse, Document, SearchResult, RetrievalStrategy } from './types';
 export type LLMFunction = (prompt: string) => Promise<string>;
+/**
+ * Shorthand configuration for `RAGPipeline.from()`.
+ *
+ * Only `provider` (or `apiKey`) is required — everything else has sensible defaults.
+ */
+export interface RAGPipelineQuickConfig {
+    /** Embedding provider name. Defaults to `'openai'`. */
+    provider?: 'openai' | 'cohere';
+    /** API key for the embedding provider. Falls back to `OPENAI_API_KEY` / `COHERE_API_KEY` env vars. */
+    apiKey?: string;
+    /** Embedding model name (provider-specific). */
+    embeddingModel?: string;
+    /** Vector store to use. Defaults to in-memory. */
+    vectorStore?: 'memory';
+    /** Number of results to return. Default: 5. */
+    topK?: number;
+    /** Chunk size for text splitting. Default: 1000. */
+    chunkSize?: number;
+    /** Chunk overlap for text splitting. Default: 200. */
+    chunkOverlap?: number;
+    /** LLM function for answer generation. */
+    llm?: LLMFunction;
+}
 export declare class RAGPipeline {
     private config;
     private llmFunction?;
+    private bm25;
+    private bm25Indexed;
     constructor(config: RAGConfig, llmFunction?: LLMFunction);
+    /**
+     * Create a RAGPipeline with sensible defaults from minimal configuration.
+     *
+     * @example
+     * ```ts
+     * const pipeline = RAGPipeline.from({ provider: 'openai', topK: 5, llm: myLLM });
+     * await pipeline.initialize();
+     * await pipeline.addDocuments(docs);
+     * const result = await pipeline.query('What is X?');
+     * ```
+     */
+    static from(quick?: RAGPipelineQuickConfig): RAGPipeline;
     /**
      * Initialize the RAG pipeline
      */
@@ -30,9 +67,8 @@ export declare class RAGPipeline {
      */
     private retrieveWithMMR;
     /**
-     * Hybrid retrieval (combines keyword and semantic search)
-     * For now, just returns semantic search results
-     * TODO: Implement keyword search integration
+     * Hybrid retrieval — combines BM25 keyword search with vector similarity.
+     * Uses weighted score fusion (default 0.7 vector, 0.3 keyword).
      */
     private retrieveHybrid;
     /**

package/dist/rag-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rag-pipeline.d.ts","sourceRoot":"","sources":["../src/rag-pipeline.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,SAAS,EACT,eAAe,EACf,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9D,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,WAAW,CAAC,CAAc;gBAEtB,MAAM,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,WAAW;IAKxD;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC;;OAEG;IACG,YAAY,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAW5D;;OAEG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,WAAW,CAAC;IA8B/E;;OAEG;IACG,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,eAAoB,EAC7B,QAAQ,GAAE,iBAAgD,GACzD,OAAO,CAAC,YAAY,EAAE,CAAC;IAgB1B;;;OAGG;YACW,eAAe;IA6D7B;;;;OAIG;YACW,cAAc;IAS5B;;OAEG;IACH,OAAO,CAAC,YAAY;IASpB;;OAEG;YACW,cAAc;IAU5B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAcxB;;OAEG;IACG,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}
+{"version":3,"file":"rag-pipeline.d.ts","sourceRoot":"","sources":["../src/rag-pipeline.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,SAAS,EACT,eAAe,EACf,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAOjB,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,uDAAuD;IACvD,QAAQ,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC/B,sGAAsG;IACtG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,GAAG,CAAC,EAAE,WAAW,CAAC;CACnB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,WAAW,CAAC,CAAc;IAClC,OAAO,CAAC,IAAI,CAAO;IACnB,OAAO,CAAC,WAAW,CAAkB;gBAEzB,MAAM,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,WAAW;IAMxD;;;;;;;;;;OAUG;IACH,MAAM,CAAC,IAAI,CAAC,KAAK,GAAE,sBAA2B,GAAG,WAAW;IAyD5D;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC;;OAEG;IACG,YAAY,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA0B5D;;OAEG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,WAAW,CAAC;IA8B/E;;OAEG;IACG,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,eAAoB,EAC7B,QAAQ,GAAE,iBAAgD,GACzD,OAAO,CAAC,YAAY,EAAE,CAAC;IA8B1B;;;OAGG;YACW,eAAe;IA6D7B;;;OAGG;YACW,cAAc;IA4D5B;;OAEG;IACH,OAAO,CAAC,YAAY;IASpB;;OAEG;YACW,cAAc;IAU5B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAcxB;;OAEG;IACG,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7B"}