@sprinterai/runtime 0.4.1 → 0.5.0

package/dist/realtime/realtime-manager.test.js

@@ -0,0 +1,273 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { createEventBus } from '../events/index.js';
+import { createRealtimeManager } from './realtime-manager.js';
+function createMockBroadcaster() {
+    const broadcasts = [];
+    const presenceTracked = [];
+    const presenceUntracked = [];
+    return {
+        broadcasts,
+        presenceTracked,
+        presenceUntracked,
+        async broadcast(message) {
+            broadcasts.push(message);
+        },
+        async trackPresence(channel, state) {
+            presenceTracked.push({ channel, state });
+        },
+        async untrackPresence(channel, userId) {
+            presenceUntracked.push({ channel, userId });
+        },
+    };
+}
+describe('createRealtimeManager', () => {
+    let broadcaster;
+    beforeEach(() => {
+        broadcaster = createMockBroadcaster();
+    });
+    describe('broadcastEvent', () => {
+        it('broadcasts entity events to entity channel', async () => {
+            const manager = createRealtimeManager({ broadcaster });
+            await manager.broadcastEvent('t1', 'entity.created', {
+                entityId: 'e1',
+                tenantId: 't1',
+                entityTypeSlug: 'person',
+            });
+            expect(broadcaster.broadcasts).toHaveLength(1);
+            expect(broadcaster.broadcasts[0]).toEqual({
+                channel: 'tenant:t1:entity:e1',
+                event: 'entity.created',
+                payload: { entityId: 'e1', tenantId: 't1', entityTypeSlug: 'person' },
+            });
+        });
+        it('broadcasts entity.updated to entity channel', async () => {
+            const manager = createRealtimeManager({ broadcaster });
+            await manager.broadcastEvent('t1', 'entity.updated', {
+                entityId: 'e2',
+                tenantId: 't1',
+                entityTypeSlug: 'company',
+                changedFields: ['name'],
+            });
+            expect(broadcaster.broadcasts).toHaveLength(1);
+            expect(broadcaster.broadcasts[0].channel).toBe('tenant:t1:entity:e2');
+            expect(broadcaster.broadcasts[0].event).toBe('entity.updated');
+        });
+        it('broadcasts workflow events to workflow channel', async () => {
+            const manager = createRealtimeManager({ broadcaster });
+            await manager.broadcastEvent('t1', 'workflow.started', {
+                workflowRunId: 'wr1',
+                entityId: 'e1',
+                tenantId: 't1',
+                status: 'running',
+            });
+            expect(broadcaster.broadcasts).toHaveLength(1);
+            expect(broadcaster.broadcasts[0]).toEqual({
+                channel: 'tenant:t1:workflow:e1',
+                event: 'workflow.started',
+                payload: {
+                    workflowRunId: 'wr1',
+                    entityId: 'e1',
+                    tenantId: 't1',
+                    status: 'running',
+                },
+            });
+        });
+        it('broadcasts workflow.node_completed to workflow channel', async () => {
+            const manager = createRealtimeManager({ broadcaster });
+            await manager.broadcastEvent('t1', 'workflow.node_completed', {
+                workflowRunId: 'wr1',
+                entityId: 'e1',
+                tenantId: 't1',
+                status: 'completed',
+                nodeKey: 'extract-name',
+            });
+            expect(broadcaster.broadcasts).toHaveLength(1);
+            expect(broadcaster.broadcasts[0].channel).toBe('tenant:t1:workflow:e1');
+        });
+        it('broadcasts extraction events to workflow channel', async () => {
+            const manager = createRealtimeManager({ broadcaster });
+            await manager.broadcastEvent('t1', 'extraction.completed', {
+                entityId: 'e1',
+                tenantId: 't1',
+            });
+            expect(broadcaster.broadcasts).toHaveLength(1);
+            expect(broadcaster.broadcasts[0].channel).toBe('tenant:t1:workflow:e1');
+            expect(broadcaster.broadcasts[0].event).toBe('extraction.completed');
+        });
+        it('broadcasts notification events to notifications channel', async () => {
+            const manager = createRealtimeManager({ broadcaster });
+            await manager.broadcastEvent('t1', 'notification.created', {
+                tenantId: 't1',
+                userId: 'u1',
+                type: 'info',
+                title: 'New item',
+            });
+            expect(broadcaster.broadcasts).toHaveLength(1);
+            expect(broadcaster.broadcasts[0]).toEqual({
+                channel: 'tenant:t1:notifications:u1',
+                event: 'notification.created',
+                payload: { tenantId: 't1', userId: 'u1', type: 'info', title: 'New item' },
+            });
+        });
+        it('broadcasts document events to entity channel', async () => {
+            const manager = createRealtimeManager({ broadcaster });
+            await manager.broadcastEvent('t1', 'document.processed', {
+                documentId: 'd1',
+                tenantId: 't1',
+                entityId: 'e1',
+            });
+            expect(broadcaster.broadcasts).toHaveLength(1);
+            expect(broadcaster.broadcasts[0].channel).toBe('tenant:t1:entity:e1');
+        });
+        it('does not broadcast unmapped event types', async () => {
+            const manager = createRealtimeManager({ broadcaster });
+            await manager.broadcastEvent('t1', 'agent.heartbeat', {
+                agentId: 'a1',
+                tenantId: 't1',
+            });
+            expect(broadcaster.broadcasts).toHaveLength(0);
+        });
+        it('is a no-op when no broadcaster is provided', async () => {
+            const manager = createRealtimeManager({});
+            // Should not throw
+            await manager.broadcastEvent('t1', 'entity.created', {
+                entityId: 'e1',
+                tenantId: 't1',
+            });
+        });
+    });
+    describe('connectToEventBus', () => {
+        it('auto-broadcasts events emitted on the bus', async () => {
+            const eventBus = createEventBus();
+            const manager = createRealtimeManager({ broadcaster, eventBus });
+            const disconnect = manager.connectToEventBus();
+            await eventBus.emit('entity.created', {
+                entityId: 'e1',
+                tenantId: 't1',
+                entityTypeSlug: 'person',
+            });
+            expect(broadcaster.broadcasts).toHaveLength(1);
+            expect(broadcaster.broadcasts[0].channel).toBe('tenant:t1:entity:e1');
+            expect(broadcaster.broadcasts[0].event).toBe('entity.created');
+            disconnect();
+        });
+        it('stops broadcasting after disconnect', async () => {
+            const eventBus = createEventBus();
+            const manager = createRealtimeManager({ broadcaster, eventBus });
+            const disconnect = manager.connectToEventBus();
+            disconnect();
+            await eventBus.emit('entity.created', {
+                entityId: 'e1',
+                tenantId: 't1',
+                entityTypeSlug: 'person',
+            });
+            expect(broadcaster.broadcasts).toHaveLength(0);
+        });
+        it('returns a no-op disconnect when no event bus is provided', () => {
+            const manager = createRealtimeManager({ broadcaster });
+            const disconnect = manager.connectToEventBus();
+            expect(disconnect).toBeTypeOf('function');
+            disconnect(); // should not throw
+        });
+        it('does not broadcast if no broadcaster is provided', async () => {
+            const eventBus = createEventBus();
+            const manager = createRealtimeManager({ eventBus });
+            const disconnect = manager.connectToEventBus();
+            // Should not throw even without broadcaster
+            await eventBus.emit('entity.created', {
+                entityId: 'e1',
+                tenantId: 't1',
+                entityTypeSlug: 'person',
+            });
+            disconnect();
+        });
+        it('broadcasts multiple events from bus', async () => {
+            const eventBus = createEventBus();
+            const manager = createRealtimeManager({ broadcaster, eventBus });
+            const disconnect = manager.connectToEventBus();
+            await eventBus.emit('entity.created', {
+                entityId: 'e1',
+                tenantId: 't1',
+                entityTypeSlug: 'person',
+            });
+            await eventBus.emit('workflow.started', {
+                workflowRunId: 'wr1',
+                entityId: 'e1',
+                tenantId: 't1',
+                status: 'running',
+            });
+            expect(broadcaster.broadcasts).toHaveLength(2);
+            expect(broadcaster.broadcasts[0].event).toBe('entity.created');
+            expect(broadcaster.broadcasts[1].event).toBe('workflow.started');
+            disconnect();
+        });
+    });
+    describe('trackEntityPresence', () => {
+        it('tracks presence on the correct channel', async () => {
+            const manager = createRealtimeManager({ broadcaster });
+            const user = {
+                userId: 'u1',
+                displayName: 'Alice',
+                lastSeen: '2026-01-01T00:00:00.000Z',
+            };
+            await manager.trackEntityPresence('t1', 'e1', user);
+            expect(broadcaster.presenceTracked).toHaveLength(1);
+            expect(broadcaster.presenceTracked[0]).toEqual({
+                channel: 'tenant:t1:presence:e1',
+                state: user,
+            });
+        });
+        it('is a no-op when no broadcaster is provided', async () => {
+            const manager = createRealtimeManager({});
+            const user = {
+                userId: 'u1',
+                lastSeen: '2026-01-01T00:00:00.000Z',
+            };
+            // Should not throw
+            await manager.trackEntityPresence('t1', 'e1', user);
+        });
+    });
+    describe('untrackEntityPresence', () => {
+        it('untracks presence on the correct channel', async () => {
+            const manager = createRealtimeManager({ broadcaster });
+            await manager.untrackEntityPresence('t1', 'e1', 'u1');
+            expect(broadcaster.presenceUntracked).toHaveLength(1);
+            expect(broadcaster.presenceUntracked[0]).toEqual({
+                channel: 'tenant:t1:presence:e1',
+                userId: 'u1',
+            });
+        });
+        it('is a no-op when no broadcaster is provided', async () => {
+            const manager = createRealtimeManager({});
+            // Should not throw
+            await manager.untrackEntityPresence('t1', 'e1', 'u1');
+        });
+    });
+    describe('event-to-channel mapping', () => {
+        it('maps entity.deleted to entity channel', async () => {
+            const manager = createRealtimeManager({ broadcaster });
+            await manager.broadcastEvent('t1', 'entity.deleted', {
+                entityId: 'e1',
+                tenantId: 't1',
+                entityTypeSlug: 'person',
+            });
+            expect(broadcaster.broadcasts[0].channel).toBe('tenant:t1:entity:e1');
+        });
+        it('maps notification.digest to notifications channel without resourceId', async () => {
+            const manager = createRealtimeManager({ broadcaster });
+            await manager.broadcastEvent('t1', 'notification.digest', {
+                tenantId: 't1',
+            });
+            expect(broadcaster.broadcasts[0].channel).toBe('tenant:t1:notifications');
+        });
+        it('maps document events without entityId to entity channel without resourceId', async () => {
+            const manager = createRealtimeManager({ broadcaster });
+            await manager.broadcastEvent('t1', 'document.uploaded', {
+                documentId: 'd1',
+                tenantId: 't1',
+            });
+            expect(broadcaster.broadcasts[0].channel).toBe('tenant:t1:entity');
+        });
+    });
+});
+//# sourceMappingURL=realtime-manager.test.js.map

package/dist/realtime/realtime-manager.test.js.map

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

package/dist/scoring/compute-score.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { mean, median, min, max, aggregateScores, computeResponseScore } from './compute-score';
+import { mean, median, min, max, aggregateScores, computeResponseScore } from './compute-score.js';
 describe('aggregation helpers', () => {
     describe('mean', () => {
         it('returns null for empty array', () => {

package/dist/scoring/index.d.ts

@@ -1,3 +1,3 @@
-export { computeResponseScore, mean, median, min, max, aggregateScores, } from "./compute-score";
-export type { ScoreAggregation } from "./compute-score";
+export { computeResponseScore, mean, median, min, max, aggregateScores, } from "./compute-score.js";
+export type { ScoreAggregation } from "./compute-score.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/scoring/index.js

@@ -1,2 +1,2 @@
-export { computeResponseScore, mean, median, min, max, aggregateScores, } from "./compute-score";
+export { computeResponseScore, mean, median, min, max, aggregateScores, } from "./compute-score.js";
 //# sourceMappingURL=index.js.map

package/dist/search/cosine-similarity.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Compute cosine similarity between two vectors.
+ * Returns a value in [-1, 1] where 1 means identical direction,
+ * 0 means orthogonal, and -1 means opposite direction.
+ * Returns 0 if either vector has zero magnitude.
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+//# sourceMappingURL=cosine-similarity.d.ts.map

package/dist/search/cosine-similarity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cosine-similarity.d.ts","sourceRoot":"","sources":["../../src/search/cosine-similarity.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CA0BjE"}

package/dist/search/cosine-similarity.js

@@ -0,0 +1,28 @@
+/**
+ * Compute cosine similarity between two vectors.
+ * Returns a value in [-1, 1] where 1 means identical direction,
+ * 0 means orthogonal, and -1 means opposite direction.
+ * Returns 0 if either vector has zero magnitude.
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector dimension mismatch: ${String(a.length)} vs ${String(b.length)}`);
+    }
+    if (a.length === 0) {
+        return 0;
+    }
+    let dotProduct = 0;
+    let magnitudeA = 0;
+    let magnitudeB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dotProduct += a[i] * b[i];
+        magnitudeA += a[i] * a[i];
+        magnitudeB += b[i] * b[i];
+    }
+    const magnitude = Math.sqrt(magnitudeA) * Math.sqrt(magnitudeB);
+    if (magnitude === 0) {
+        return 0;
+    }
+    return dotProduct / magnitude;
+}
+//# sourceMappingURL=cosine-similarity.js.map

package/dist/search/cosine-similarity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cosine-similarity.js","sourceRoot":"","sources":["../../src/search/cosine-similarity.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAW,EAAE,CAAW;IACvD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,8BAA8B,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC3F,CAAC;IAED,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnB,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1B,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1B,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5B,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAEhE,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;QACpB,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,UAAU,GAAG,SAAS,CAAC;AAChC,CAAC"}

package/dist/search/cosine-similarity.test.d.ts

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

package/dist/search/cosine-similarity.test.d.ts.map

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

package/dist/search/cosine-similarity.test.js

@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest';
+import { cosineSimilarity } from './cosine-similarity.js';
+describe('cosineSimilarity', () => {
+    it('returns 1 for identical vectors', () => {
+        expect(cosineSimilarity([1, 0, 0], [1, 0, 0])).toBeCloseTo(1, 10);
+        expect(cosineSimilarity([0.5, 0.5], [0.5, 0.5])).toBeCloseTo(1, 10);
+        expect(cosineSimilarity([3, 4], [3, 4])).toBeCloseTo(1, 10);
+    });
+    it('returns 1 for parallel vectors (same direction, different magnitude)', () => {
+        expect(cosineSimilarity([1, 0], [2, 0])).toBeCloseTo(1, 10);
+        expect(cosineSimilarity([1, 2, 3], [2, 4, 6])).toBeCloseTo(1, 10);
+    });
+    it('returns 0 for orthogonal vectors', () => {
+        expect(cosineSimilarity([1, 0], [0, 1])).toBeCloseTo(0, 10);
+        expect(cosineSimilarity([1, 0, 0], [0, 1, 0])).toBeCloseTo(0, 10);
+    });
+    it('returns -1 for opposite vectors', () => {
+        expect(cosineSimilarity([1, 0], [-1, 0])).toBeCloseTo(-1, 10);
+        expect(cosineSimilarity([1, 2, 3], [-1, -2, -3])).toBeCloseTo(-1, 10);
+    });
+    it('returns 0 for zero vectors', () => {
+        expect(cosineSimilarity([0, 0, 0], [1, 2, 3])).toBe(0);
+        expect(cosineSimilarity([1, 2, 3], [0, 0, 0])).toBe(0);
+        expect(cosineSimilarity([0, 0], [0, 0])).toBe(0);
+    });
+    it('returns 0 for empty vectors', () => {
+        expect(cosineSimilarity([], [])).toBe(0);
+    });
+    it('throws on dimension mismatch', () => {
+        expect(() => cosineSimilarity([1, 2], [1, 2, 3])).toThrow('Vector dimension mismatch');
+    });
+    it('computes correct similarity for non-trivial vectors', () => {
+        // Known: cos([1,2,3], [4,5,6]) = 32 / (sqrt(14) * sqrt(77)) ≈ 0.9746
+        const a = [1, 2, 3];
+        const b = [4, 5, 6];
+        const expected = 32 / (Math.sqrt(14) * Math.sqrt(77));
+        expect(cosineSimilarity(a, b)).toBeCloseTo(expected, 10);
+    });
+    it('handles high-dimensional vectors', () => {
+        const dim = 1536;
+        const a = Array.from({ length: dim }, (_, i) => Math.sin(i));
+        const b = Array.from({ length: dim }, (_, i) => Math.cos(i));
+        const result = cosineSimilarity(a, b);
+        // Just verify it produces a valid number in range
+        expect(result).toBeGreaterThanOrEqual(-1);
+        expect(result).toBeLessThanOrEqual(1);
+    });
+});
+//# sourceMappingURL=cosine-similarity.test.js.map

package/dist/search/cosine-similarity.test.js.map

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

package/dist/search/hybrid-search.d.ts

@@ -0,0 +1,47 @@
+import type { SearchResult, HybridSearchOptions, SearchProvider, EmbeddingProvider } from '@sprinterai/core';
+/** A hit from full-text search. */
+export interface TextSearchHit {
+    id: string;
+    documentId: string;
+    content: string;
+    chunkIndex: number;
+    pageNumber: number | null;
+    metadata: Record<string, unknown> | null;
+    /** FTS rank score. */
+    rank: number;
+}
+/** A hit from vector similarity search. */
+export interface VectorSearchHit {
+    id: string;
+    documentId: string;
+    content: string;
+    chunkIndex: number;
+    pageNumber: number | null;
+    metadata: Record<string, unknown> | null;
+    /** Cosine similarity (0-1). */
+    similarity: number;
+}
+/** Configuration for hybrid search. */
+export interface HybridSearchConfig {
+    /** Generate query embedding. */
+    embeddingProvider?: EmbeddingProvider;
+    /** Full-text search function (injected -- backend-specific). */
+    textSearch: (query: string, options: HybridSearchOptions) => Promise<TextSearchHit[]>;
+    /** Vector search function (injected -- backend-specific). */
+    vectorSearch?: (embedding: number[], options: HybridSearchOptions) => Promise<VectorSearchHit[]>;
+}
+/**
+ * Reciprocal Rank Fusion: combines two ranked lists into one.
+ * score = vectorWeight / (RRF_K + vectorRank) + textWeight / (RRF_K + textRank)
+ *
+ * Hits appearing in only one list receive the RRF contribution from that list only.
+ */
+export declare function reciprocalRankFusion(vectorHits: VectorSearchHit[], textHits: TextSearchHit[], options: {
+    vectorWeight?: number;
+    textWeight?: number;
+    minSimilarity?: number;
+    limit?: number;
+}): SearchResult[];
+/** Create a hybrid search provider. */
+export declare function createHybridSearch(config: HybridSearchConfig): SearchProvider;
+//# sourceMappingURL=hybrid-search.d.ts.map

package/dist/search/hybrid-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid-search.d.ts","sourceRoot":"","sources":["../../src/search/hybrid-search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAE1B,mCAAmC;AACnC,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzC,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzC,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,gCAAgC;IAChC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,gEAAgE;IAChE,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACtF,6DAA6D;IAC7D,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;CAClG;AAaD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,eAAe,EAAE,EAC7B,QAAQ,EAAE,aAAa,EAAE,EACzB,OAAO,EAAE;IACP,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACA,YAAY,EAAE,CAiEhB;AAED,uCAAuC;AACvC,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,cAAc,CA4C7E"}

package/dist/search/hybrid-search.js

@@ -0,0 +1,111 @@
+/** RRF constant (standard value from literature). */
+const RRF_K = 60;
+/** Default search configuration values. */
+const DEFAULTS = {
+    vectorWeight: 0.7,
+    textWeight: 0.3,
+    minSimilarity: 0.3,
+    limit: 10,
+};
+/**
+ * Reciprocal Rank Fusion: combines two ranked lists into one.
+ * score = vectorWeight / (RRF_K + vectorRank) + textWeight / (RRF_K + textRank)
+ *
+ * Hits appearing in only one list receive the RRF contribution from that list only.
+ */
+export function reciprocalRankFusion(vectorHits, textHits, options) {
+    const vectorWeight = options.vectorWeight ?? DEFAULTS.vectorWeight;
+    const textWeight = options.textWeight ?? DEFAULTS.textWeight;
+    const minSimilarity = options.minSimilarity ?? DEFAULTS.minSimilarity;
+    const limit = options.limit ?? DEFAULTS.limit;
+    // Filter vector hits by minimum similarity
+    const filteredVectorHits = vectorHits.filter((hit) => hit.similarity >= minSimilarity);
+    // Rank vector hits by similarity (highest first -- already assumed sorted, but be safe)
+    const rankedVector = [...filteredVectorHits].sort((a, b) => b.similarity - a.similarity);
+    // Rank text hits by rank score (highest first)
+    const rankedText = [...textHits].sort((a, b) => b.rank - a.rank);
+    // Build vector rank map: id -> { rank (1-based), hit }
+    const vectorRankMap = new Map();
+    for (let i = 0; i < rankedVector.length; i++) {
+        vectorRankMap.set(rankedVector[i].id, {
+            rank: i + 1,
+            hit: rankedVector[i],
+        });
+    }
+    // Build text rank map: id -> { rank (1-based), hit }
+    const textRankMap = new Map();
+    for (let i = 0; i < rankedText.length; i++) {
+        textRankMap.set(rankedText[i].id, { rank: i + 1, hit: rankedText[i] });
+    }
+    // Collect all unique IDs
+    const allIds = new Set([...vectorRankMap.keys(), ...textRankMap.keys()]);
+    // Compute RRF score for each item
+    const results = [];
+    for (const id of allIds) {
+        const vectorEntry = vectorRankMap.get(id);
+        const textEntry = textRankMap.get(id);
+        const vectorRRF = vectorEntry ? vectorWeight / (RRF_K + vectorEntry.rank) : 0;
+        const textRRF = textEntry ? textWeight / (RRF_K + textEntry.rank) : 0;
+        // Use whichever hit we have for the base data
+        const hit = vectorEntry?.hit ?? textEntry?.hit;
+        if (!hit)
+            continue;
+        results.push({
+            id: hit.id,
+            documentId: hit.documentId,
+            content: hit.content,
+            chunkIndex: hit.chunkIndex,
+            pageNumber: hit.pageNumber,
+            metadata: hit.metadata,
+            vectorScore: vectorEntry?.hit.similarity ?? null,
+            textScore: textEntry?.hit.rank ?? null,
+            score: vectorRRF + textRRF,
+        });
+    }
+    // Sort by combined score descending
+    results.sort((a, b) => b.score - a.score);
+    // Apply limit
+    return results.slice(0, limit);
+}
+/** Create a hybrid search provider. */
+export function createHybridSearch(config) {
+    return {
+        async search(query, options) {
+            const canVector = config.embeddingProvider !== undefined && config.vectorSearch !== undefined;
+            if (canVector) {
+                // Generate query embedding and run both searches in parallel
+                const embedding = await config.embeddingProvider.generateEmbeddings([query]);
+                if (embedding !== null && embedding.length > 0) {
+                    const [vectorHits, textHits] = await Promise.all([
+                        config.vectorSearch(embedding[0], options),
+                        config.textSearch(query, options),
+                    ]);
+                    return reciprocalRankFusion(vectorHits, textHits, {
+                        vectorWeight: options.vectorWeight,
+                        textWeight: options.textWeight,
+                        minSimilarity: options.minSimilarity,
+                        limit: options.limit,
+                    });
+                }
+            }
+            // Fallback: text search only
+            const textHits = await config.textSearch(query, options);
+            // Convert text hits to SearchResult with text-only scoring
+            return textHits
+                .sort((a, b) => b.rank - a.rank)
+                .slice(0, options.limit ?? DEFAULTS.limit)
+                .map((hit, index) => ({
+                id: hit.id,
+                documentId: hit.documentId,
+                content: hit.content,
+                chunkIndex: hit.chunkIndex,
+                pageNumber: hit.pageNumber,
+                metadata: hit.metadata,
+                vectorScore: null,
+                textScore: hit.rank,
+                score: (options.textWeight ?? DEFAULTS.textWeight) / (RRF_K + index + 1),
+            }));
+        },
+    };
+}
+//# sourceMappingURL=hybrid-search.js.map

package/dist/search/hybrid-search.js.map

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

package/dist/search/hybrid-search.test.d.ts

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

package/dist/search/hybrid-search.test.d.ts.map

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