@hazeljs/rag 0.2.4 → 0.3.0

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__/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

@@ -26,4 +26,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;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;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
@@ -55,4 +56,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,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;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;IAgB1B;;;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"}

package/dist/rag-pipeline.js

@@ -6,10 +6,73 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RAGPipeline = void 0;
 const types_1 = require("./types");
+const bm25_1 = require("./retrieval/bm25");
+const openai_embeddings_1 = require("./embeddings/openai-embeddings");
+const cohere_embeddings_1 = require("./embeddings/cohere-embeddings");
+const memory_vector_store_1 = require("./vector-stores/memory-vector-store");
+const recursive_text_splitter_1 = require("./text-splitters/recursive-text-splitter");
 class RAGPipeline {
     constructor(config, llmFunction) {
+        this.bm25Indexed = false;
         this.config = config;
         this.llmFunction = llmFunction;
+        this.bm25 = new bm25_1.BM25();
+    }
+    /**
+     * 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 = {}) {
+        const provider = quick.provider ?? 'openai';
+        // Resolve embedding provider
+        let embeddingProvider;
+        switch (provider) {
+            case 'cohere': {
+                const apiKey = quick.apiKey ?? process.env.COHERE_API_KEY;
+                if (!apiKey) {
+                    throw new Error('RAGPipeline.from(): Missing API key for Cohere. ' +
+                        'Pass `apiKey` or set the COHERE_API_KEY environment variable.');
+                }
+                embeddingProvider = new cohere_embeddings_1.CohereEmbeddings({
+                    apiKey,
+                    model: quick.embeddingModel,
+                });
+                break;
+            }
+            case 'openai':
+            default: {
+                const apiKey = quick.apiKey ?? process.env.OPENAI_API_KEY;
+                if (!apiKey) {
+                    throw new Error('RAGPipeline.from(): Missing API key for OpenAI. ' +
+                        'Pass `apiKey` or set the OPENAI_API_KEY environment variable.');
+                }
+                embeddingProvider = new openai_embeddings_1.OpenAIEmbeddings({
+                    apiKey,
+                    model: quick.embeddingModel,
+                });
+                break;
+            }
+        }
+        // Resolve vector store (currently only memory; extensible later)
+        const vectorStore = new memory_vector_store_1.MemoryVectorStore(embeddingProvider);
+        // Resolve text splitter
+        const textSplitter = new recursive_text_splitter_1.RecursiveTextSplitter({
+            chunkSize: quick.chunkSize ?? 1000,
+            chunkOverlap: quick.chunkOverlap ?? 200,
+        });
+        return new RAGPipeline({
+            vectorStore,
+            embeddingProvider,
+            textSplitter,
+            topK: quick.topK ?? 5,
+        }, quick.llm);
     }
     /**
      * Initialize the RAG pipeline
@@ -26,7 +89,20 @@ class RAGPipeline {
         if (this.config.textSplitter) {
             processedDocs = this.config.textSplitter.splitDocuments(documents);
         }
-        return this.config.vectorStore.addDocuments(processedDocs);
+        const ids = await this.config.vectorStore.addDocuments(processedDocs);
+        // Index in BM25 for hybrid search
+        const bm25Docs = processedDocs.map((doc, i) => ({
+            id: doc.id || ids[i],
+            content: doc.content,
+            tokens: doc.content
+                .toLowerCase()
+                .replace(/[^\w\s]/g, ' ')
+                .split(/\s+/)
+                .filter((t) => t.length > 0),
+        }));
+        this.bm25.addDocuments(bm25Docs);
+        this.bm25Indexed = true;
+        return ids;
     }
     /**
      * Query the RAG system
@@ -120,14 +196,56 @@ class RAGPipeline {
         return selected;
     }
     /**
-     * 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).
      */
     async retrieveHybrid(query, options = {}) {
-        // For now, fallback to similarity search
-        // In production, this would combine BM25 or other keyword search with vector search
-        return this.config.vectorStore.search(query, options);
+        const topK = options.topK || this.config.topK || 5;
+        // Always run vector search
+        const vectorResults = await this.config.vectorStore.search(query, {
+            ...options,
+            topK: topK * 2,
+        });
+        // If BM25 hasn't been indexed yet, fall back to vector-only
+        if (!this.bm25Indexed) {
+            return vectorResults.slice(0, topK);
+        }
+        // BM25 keyword search
+        const keywordResults = this.bm25.search(query, topK * 2);
+        // Normalize scores to [0, 1]
+        const normalize = (items) => {
+            if (items.length === 0)
+                return new Map();
+            const scores = items.map((r) => r.score);
+            const min = Math.min(...scores);
+            const max = Math.max(...scores);
+            const range = max - min || 1;
+            return new Map(items.map((r) => [r.id, (r.score - min) / range]));
+        };
+        const vectorScores = normalize(vectorResults.map((r) => ({ id: r.id, score: r.score })));
+        const keywordScores = normalize(keywordResults);
+        const vectorWeight = 0.7;
+        const keywordWeight = 0.3;
+        // Fuse scores
+        const allIds = new Set([...vectorScores.keys(), ...keywordScores.keys()]);
+        const fused = [];
+        for (const id of allIds) {
+            const vs = vectorScores.get(id) || 0;
+            const ks = keywordScores.get(id) || 0;
+            fused.push({ id, score: vectorWeight * vs + keywordWeight * ks });
+        }
+        fused.sort((a, b) => b.score - a.score);
+        // Map back to full SearchResult objects
+        const resultMap = new Map(vectorResults.map((r) => [r.id, r]));
+        return fused
+            .slice(0, topK)
+            .map((f) => {
+            const original = resultMap.get(f.id);
+            if (original)
+                return { ...original, score: f.score };
+            return null;
+        })
+            .filter((r) => r !== null);
     }
     /**
      * Build context string from search results
@@ -175,6 +293,8 @@ class RAGPipeline {
      */
     async clear() {
         await this.config.vectorStore.clear();
+        this.bm25.clear();
+        this.bm25Indexed = false;
     }
 }
 exports.RAGPipeline = RAGPipeline;