@renseiai/agentfactory-code-intelligence 0.8.8 → 0.8.9

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

@@ -0,0 +1,503 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { CohereReranker } from '../cohere-reranker.js';
+import { VoyageReranker } from '../voyage-reranker.js';
+import { SearchEngine } from '../../search/search-engine.js';
+import { HybridSearchEngine } from '../../search/hybrid-search.js';
+// ── Helpers ──────────────────────────────────────────────────────────
+/** Create a mock fetch response. */
+function mockFetchResponse(status, body, headers) {
+    return {
+        ok: status >= 200 && status < 300,
+        status,
+        headers: new Headers(headers ?? {}),
+        json: async () => body,
+        text: async () => JSON.stringify(body),
+    };
+}
+function makeSymbol(name, kind, filePath, extra) {
+    return {
+        name,
+        kind: kind,
+        filePath,
+        line: extra?.line ?? 1,
+        exported: true,
+        ...extra,
+    };
+}
+function makeSearchResult(name, score, extra) {
+    return {
+        symbol: makeSymbol(name, 'function', `src/${name}.ts`, extra),
+        score,
+        matchType: 'bm25',
+    };
+}
+// ── CohereReranker ──────────────────────────────────────────────────
+describe('CohereReranker', () => {
+    let originalEnv;
+    beforeEach(() => {
+        originalEnv = process.env.COHERE_API_KEY;
+        process.env.COHERE_API_KEY = 'test-cohere-key';
+    });
+    afterEach(() => {
+        if (originalEnv !== undefined) {
+            process.env.COHERE_API_KEY = originalEnv;
+        }
+        else {
+            delete process.env.COHERE_API_KEY;
+        }
+        vi.restoreAllMocks();
+    });
+    it('throws on missing API key', () => {
+        delete process.env.COHERE_API_KEY;
+        expect(() => new CohereReranker()).toThrow('COHERE_API_KEY');
+    });
+    it('uses default model', () => {
+        const reranker = new CohereReranker();
+        expect(reranker.model).toBe('rerank-v3.5');
+    });
+    it('sends correct request format', async () => {
+        const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(mockFetchResponse(200, {
+            results: [
+                { index: 0, relevance_score: 0.95 },
+                { index: 1, relevance_score: 0.80 },
+            ],
+        }));
+        const reranker = new CohereReranker();
+        const documents = [
+            { id: 'doc-0', text: 'function handleRequest() {}' },
+            { id: 'doc-1', text: 'function processData() {}' },
+        ];
+        await reranker.rerank('handle request', documents);
+        expect(fetchSpy).toHaveBeenCalledTimes(1);
+        const callArgs = fetchSpy.mock.calls[0];
+        expect(callArgs[0]).toBe('https://api.cohere.com/v2/rerank');
+        const body = JSON.parse(callArgs[1].body);
+        expect(body.model).toBe('rerank-v3.5');
+        expect(body.query).toBe('handle request');
+        expect(body.documents).toEqual([
+            'function handleRequest() {}',
+            'function processData() {}',
+        ]);
+        expect(body.top_n).toBe(2);
+        const headers = callArgs[1].headers;
+        expect(headers['Authorization']).toBe('Bearer test-cohere-key');
+        expect(headers['Content-Type']).toBe('application/json');
+    });
+    it('parses response correctly and maps to RerankResult[]', async () => {
+        vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(mockFetchResponse(200, {
+            results: [
+                { index: 1, relevance_score: 0.95 },
+                { index: 0, relevance_score: 0.72 },
+            ],
+        }));
+        const reranker = new CohereReranker();
+        const documents = [
+            { id: 'doc-a', text: 'first document' },
+            { id: 'doc-b', text: 'second document' },
+        ];
+        const results = await reranker.rerank('query', documents);
+        expect(results).toHaveLength(2);
+        expect(results[0]).toEqual({ id: 'doc-b', score: 0.95, index: 1 });
+        expect(results[1]).toEqual({ id: 'doc-a', score: 0.72, index: 0 });
+    });
+    it('returns empty array for empty documents', async () => {
+        const fetchSpy = vi.spyOn(globalThis, 'fetch');
+        const reranker = new CohereReranker();
+        const results = await reranker.rerank('query', []);
+        expect(results).toHaveLength(0);
+        expect(fetchSpy).not.toHaveBeenCalled();
+    });
+    it('retries on 429', async () => {
+        const fetchSpy = vi.spyOn(globalThis, 'fetch')
+            .mockResolvedValueOnce(mockFetchResponse(429, { message: 'Rate limited' }))
+            .mockResolvedValueOnce(mockFetchResponse(200, {
+            results: [{ index: 0, relevance_score: 0.9 }],
+        }));
+        const reranker = new CohereReranker({ maxRetries: 3 });
+        vi.spyOn(reranker, 'sleep').mockResolvedValue(undefined);
+        const results = await reranker.rerank('query', [{ id: 'a', text: 'doc' }]);
+        expect(results).toHaveLength(1);
+        expect(fetchSpy).toHaveBeenCalledTimes(2);
+    });
+    it('retries on 5xx', async () => {
+        const fetchSpy = vi.spyOn(globalThis, 'fetch')
+            .mockResolvedValueOnce(mockFetchResponse(503, { message: 'Service unavailable' }))
+            .mockResolvedValueOnce(mockFetchResponse(500, { message: 'Internal error' }))
+            .mockResolvedValueOnce(mockFetchResponse(200, {
+            results: [{ index: 0, relevance_score: 0.85 }],
+        }));
+        const reranker = new CohereReranker({ maxRetries: 3 });
+        vi.spyOn(reranker, 'sleep').mockResolvedValue(undefined);
+        const results = await reranker.rerank('query', [{ id: 'a', text: 'doc' }]);
+        expect(results).toHaveLength(1);
+        expect(fetchSpy).toHaveBeenCalledTimes(3);
+    });
+    it('throws after exhausting retries', async () => {
+        vi.spyOn(globalThis, 'fetch').mockResolvedValue(mockFetchResponse(429, { message: 'Rate limited' }));
+        const reranker = new CohereReranker({ maxRetries: 2 });
+        vi.spyOn(reranker, 'sleep').mockResolvedValue(undefined);
+        await expect(reranker.rerank('query', [{ id: 'a', text: 'doc' }])).rejects.toThrow('429');
+    });
+    it('throws immediately on non-retryable errors', async () => {
+        vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(mockFetchResponse(401, { message: 'Invalid API key' }));
+        const reranker = new CohereReranker();
+        await expect(reranker.rerank('query', [{ id: 'a', text: 'doc' }])).rejects.toThrow('Invalid API key');
+    });
+});
+// ── VoyageReranker ──────────────────────────────────────────────────
+describe('VoyageReranker', () => {
+    let originalEnv;
+    beforeEach(() => {
+        originalEnv = process.env.VOYAGE_API_KEY;
+        process.env.VOYAGE_API_KEY = 'test-voyage-key';
+    });
+    afterEach(() => {
+        if (originalEnv !== undefined) {
+            process.env.VOYAGE_API_KEY = originalEnv;
+        }
+        else {
+            delete process.env.VOYAGE_API_KEY;
+        }
+        vi.restoreAllMocks();
+    });
+    it('throws on missing API key', () => {
+        delete process.env.VOYAGE_API_KEY;
+        expect(() => new VoyageReranker()).toThrow('VOYAGE_API_KEY');
+    });
+    it('uses VOYAGE_API_KEY', async () => {
+        const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(mockFetchResponse(200, {
+            data: [{ index: 0, relevance_score: 0.9 }],
+        }));
+        const reranker = new VoyageReranker();
+        await reranker.rerank('query', [{ id: 'a', text: 'doc' }]);
+        const callArgs = fetchSpy.mock.calls[0];
+        const headers = callArgs[1].headers;
+        expect(headers['Authorization']).toBe('Bearer test-voyage-key');
+    });
+    it('uses default model', () => {
+        const reranker = new VoyageReranker();
+        expect(reranker.model).toBe('rerank-2');
+    });
+    it('sends correct request format', async () => {
+        const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(mockFetchResponse(200, {
+            data: [
+                { index: 0, relevance_score: 0.95 },
+                { index: 1, relevance_score: 0.80 },
+            ],
+        }));
+        const reranker = new VoyageReranker();
+        const documents = [
+            { id: 'doc-0', text: 'function handleRequest() {}' },
+            { id: 'doc-1', text: 'function processData() {}' },
+        ];
+        await reranker.rerank('handle request', documents);
+        expect(fetchSpy).toHaveBeenCalledTimes(1);
+        const callArgs = fetchSpy.mock.calls[0];
+        expect(callArgs[0]).toBe('https://api.voyageai.com/v1/rerank');
+        const body = JSON.parse(callArgs[1].body);
+        expect(body.model).toBe('rerank-2');
+        expect(body.query).toBe('handle request');
+        expect(body.documents).toEqual([
+            'function handleRequest() {}',
+            'function processData() {}',
+        ]);
+        expect(body.top_k).toBe(2);
+    });
+    it('parses response correctly and maps to RerankResult[]', async () => {
+        vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(mockFetchResponse(200, {
+            data: [
+                { index: 1, relevance_score: 0.92 },
+                { index: 0, relevance_score: 0.68 },
+            ],
+        }));
+        const reranker = new VoyageReranker();
+        const documents = [
+            { id: 'doc-a', text: 'first document' },
+            { id: 'doc-b', text: 'second document' },
+        ];
+        const results = await reranker.rerank('query', documents);
+        expect(results).toHaveLength(2);
+        expect(results[0]).toEqual({ id: 'doc-b', score: 0.92, index: 1 });
+        expect(results[1]).toEqual({ id: 'doc-a', score: 0.68, index: 0 });
+    });
+    it('returns empty array for empty documents', async () => {
+        const fetchSpy = vi.spyOn(globalThis, 'fetch');
+        const reranker = new VoyageReranker();
+        const results = await reranker.rerank('query', []);
+        expect(results).toHaveLength(0);
+        expect(fetchSpy).not.toHaveBeenCalled();
+    });
+    it('retries on 429', async () => {
+        const fetchSpy = vi.spyOn(globalThis, 'fetch')
+            .mockResolvedValueOnce(mockFetchResponse(429, { detail: 'Rate limited' }))
+            .mockResolvedValueOnce(mockFetchResponse(200, {
+            data: [{ index: 0, relevance_score: 0.9 }],
+        }));
+        const reranker = new VoyageReranker({ maxRetries: 3 });
+        vi.spyOn(reranker, 'sleep').mockResolvedValue(undefined);
+        const results = await reranker.rerank('query', [{ id: 'a', text: 'doc' }]);
+        expect(results).toHaveLength(1);
+        expect(fetchSpy).toHaveBeenCalledTimes(2);
+    });
+    it('retries on 5xx', async () => {
+        const fetchSpy = vi.spyOn(globalThis, 'fetch')
+            .mockResolvedValueOnce(mockFetchResponse(503, { detail: 'Service unavailable' }))
+            .mockResolvedValueOnce(mockFetchResponse(200, {
+            data: [{ index: 0, relevance_score: 0.85 }],
+        }));
+        const reranker = new VoyageReranker({ maxRetries: 3 });
+        vi.spyOn(reranker, 'sleep').mockResolvedValue(undefined);
+        const results = await reranker.rerank('query', [{ id: 'a', text: 'doc' }]);
+        expect(results).toHaveLength(1);
+        expect(fetchSpy).toHaveBeenCalledTimes(2);
+    });
+    it('throws after exhausting retries', async () => {
+        vi.spyOn(globalThis, 'fetch').mockResolvedValue(mockFetchResponse(429, { detail: 'Rate limited' }));
+        const reranker = new VoyageReranker({ maxRetries: 2 });
+        vi.spyOn(reranker, 'sleep').mockResolvedValue(undefined);
+        await expect(reranker.rerank('query', [{ id: 'a', text: 'doc' }])).rejects.toThrow('429');
+    });
+    it('throws immediately on non-retryable errors', async () => {
+        vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(mockFetchResponse(401, { detail: 'Invalid API key' }));
+        const reranker = new VoyageReranker();
+        await expect(reranker.rerank('query', [{ id: 'a', text: 'doc' }])).rejects.toThrow('Invalid API key');
+    });
+});
+// ── HybridSearchEngine + Reranker Integration ──────────────────────
+describe('HybridSearchEngine with reranker', () => {
+    function createMockRerankerProvider(results) {
+        return {
+            model: 'mock-reranker',
+            rerank: vi.fn().mockResolvedValue((results ?? []).map(r => ({
+                id: `${r.index}`,
+                score: r.score,
+                index: r.index,
+            }))),
+        };
+    }
+    function createFailingRerankerProvider() {
+        return {
+            model: 'failing-reranker',
+            rerank: vi.fn().mockRejectedValue(new Error('Reranker failed')),
+        };
+    }
+    it('reranks top candidates and returns reranked scores', async () => {
+        const symbols = [
+            makeSymbol('handleRequest', 'function', 'src/api.ts', {
+                line: 1,
+                language: 'typescript',
+                signature: 'function handleRequest(req: Request): Response',
+                documentation: 'Handles incoming HTTP requests',
+            }),
+            makeSymbol('processData', 'function', 'src/data.ts', {
+                line: 1,
+                language: 'typescript',
+                signature: 'function processData(data: unknown): void',
+            }),
+            makeSymbol('handleError', 'function', 'src/error.ts', {
+                line: 1,
+                language: 'typescript',
+            }),
+        ];
+        const engine = new SearchEngine();
+        engine.buildIndex(symbols);
+        const mockProvider = createMockRerankerProvider([
+            { index: 2, score: 0.99 }, // handleError gets highest rerank score
+            { index: 0, score: 0.85 }, // handleRequest
+            { index: 1, score: 0.60 }, // processData
+        ]);
+        const rerankerConfig = {
+            enabled: true,
+            provider: mockProvider,
+            topN: 10,
+            candidatePool: 50,
+        };
+        const hybrid = new HybridSearchEngine(engine, null, null, {}, rerankerConfig);
+        const results = await hybrid.search({ query: 'handle', maxResults: 20 });
+        // Reranker should have been called
+        expect(mockProvider.rerank).toHaveBeenCalledTimes(1);
+        // Results should have rerankScore set
+        for (const r of results) {
+            expect(r.rerankScore).toBeDefined();
+        }
+        // Results should be sorted by rerank score descending
+        if (results.length >= 2) {
+            expect(results[0].score).toBeGreaterThanOrEqual(results[1].score);
+        }
+    });
+    it('passes through results when reranker is disabled', async () => {
+        const symbols = [
+            makeSymbol('handleRequest', 'function', 'src/api.ts', { line: 1, language: 'typescript' }),
+            makeSymbol('processData', 'function', 'src/data.ts', { line: 1, language: 'typescript' }),
+        ];
+        const engine = new SearchEngine();
+        engine.buildIndex(symbols);
+        const mockProvider = createMockRerankerProvider();
+        const rerankerConfig = {
+            enabled: false,
+            provider: mockProvider,
+            topN: 10,
+            candidatePool: 50,
+        };
+        const hybrid = new HybridSearchEngine(engine, null, null, {}, rerankerConfig);
+        const results = await hybrid.search({ query: 'handle', maxResults: 20 });
+        // Reranker should NOT have been called
+        expect(mockProvider.rerank).not.toHaveBeenCalled();
+        // Results should not have rerankScore
+        for (const r of results) {
+            expect(r.rerankScore).toBeUndefined();
+        }
+    });
+    it('gracefully falls back when reranker errors', async () => {
+        const symbols = [
+            makeSymbol('handleRequest', 'function', 'src/api.ts', { line: 1, language: 'typescript' }),
+        ];
+        const engine = new SearchEngine();
+        engine.buildIndex(symbols);
+        const failingProvider = createFailingRerankerProvider();
+        const rerankerConfig = {
+            enabled: true,
+            provider: failingProvider,
+            topN: 10,
+            candidatePool: 50,
+        };
+        const hybrid = new HybridSearchEngine(engine, null, null, {}, rerankerConfig);
+        const results = await hybrid.search({ query: 'handleRequest', maxResults: 20 });
+        // Should return results despite reranker failure
+        expect(results.length).toBeGreaterThan(0);
+        expect(results[0].symbol.name).toBe('handleRequest');
+        // Results should not have rerankScore (fallback path)
+        expect(results[0].rerankScore).toBeUndefined();
+    });
+    it('passes through results when rerankerConfig is null', async () => {
+        const symbols = [
+            makeSymbol('handleRequest', 'function', 'src/api.ts', { line: 1, language: 'typescript' }),
+        ];
+        const engine = new SearchEngine();
+        engine.buildIndex(symbols);
+        const hybrid = new HybridSearchEngine(engine, null, null, {}, null);
+        const results = await hybrid.search({ query: 'handleRequest', maxResults: 20 });
+        expect(results.length).toBeGreaterThan(0);
+        expect(results[0].rerankScore).toBeUndefined();
+    });
+    it('respects topN limit from reranker config', async () => {
+        const symbols = [
+            makeSymbol('a', 'function', 'a.ts', { line: 1, language: 'typescript' }),
+            makeSymbol('ab', 'function', 'ab.ts', { line: 1, language: 'typescript' }),
+            makeSymbol('abc', 'function', 'abc.ts', { line: 1, language: 'typescript' }),
+            makeSymbol('abcd', 'function', 'abcd.ts', { line: 1, language: 'typescript' }),
+            makeSymbol('abcde', 'function', 'abcde.ts', { line: 1, language: 'typescript' }),
+        ];
+        const engine = new SearchEngine();
+        engine.buildIndex(symbols);
+        const mockProvider = createMockRerankerProvider([
+            { index: 0, score: 0.9 },
+            { index: 1, score: 0.8 },
+            { index: 2, score: 0.7 },
+            { index: 3, score: 0.6 },
+            { index: 4, score: 0.5 },
+        ]);
+        const rerankerConfig = {
+            enabled: true,
+            provider: mockProvider,
+            topN: 2,
+            candidatePool: 50,
+        };
+        const hybrid = new HybridSearchEngine(engine, null, null, {}, rerankerConfig);
+        const results = await hybrid.search({ query: 'a', maxResults: 20 });
+        expect(results.length).toBeLessThanOrEqual(2);
+    });
+    it('respects candidatePool limit', async () => {
+        // Create many symbols that will all match the query "handle"
+        const symbols = Array.from({ length: 20 }, (_, i) => makeSymbol(`handleFunc${i}`, 'function', `src/f${i}.ts`, { line: 1, language: 'typescript' }));
+        const engine = new SearchEngine();
+        engine.buildIndex(symbols);
+        // Reranker returns results for all docs it receives
+        const mockProvider = {
+            model: 'mock-reranker',
+            rerank: vi.fn().mockImplementation((_query, docs) => {
+                return docs.map((d, i) => ({
+                    id: d.id,
+                    score: 0.9 - i * 0.01,
+                    index: i,
+                }));
+            }),
+        };
+        const rerankerConfig = {
+            enabled: true,
+            provider: mockProvider,
+            topN: 10,
+            candidatePool: 5,
+        };
+        const hybrid = new HybridSearchEngine(engine, null, null, {}, rerankerConfig);
+        await hybrid.search({ query: 'handle', maxResults: 20 });
+        // The reranker should have been called
+        expect(mockProvider.rerank).toHaveBeenCalledTimes(1);
+        // The reranker should have been called with at most candidatePool documents
+        const rerankCall = mockProvider.rerank.mock.calls[0];
+        const docsPassedToReranker = rerankCall[1];
+        expect(docsPassedToReranker.length).toBeLessThanOrEqual(5);
+    });
+});
+// ── Document preparation ────────────────────────────────────────────
+describe('Document preparation from SearchResult', () => {
+    it('includes signature and documentation in rerank text', async () => {
+        const symbols = [
+            makeSymbol('handleRequest', 'function', 'src/api.ts', {
+                line: 1,
+                language: 'typescript',
+                signature: 'function handleRequest(req: Request): Response',
+                documentation: 'Handles incoming HTTP requests and returns a Response object.',
+            }),
+        ];
+        const engine = new SearchEngine();
+        engine.buildIndex(symbols);
+        const mockProvider = {
+            model: 'mock',
+            rerank: vi.fn().mockImplementation((_query, docs) => {
+                // Verify the document text includes signature, docs, name, and kind
+                const text = docs[0].text;
+                expect(text).toContain('function handleRequest(req: Request): Response');
+                expect(text).toContain('Handles incoming HTTP requests');
+                expect(text).toContain('function handleRequest');
+                return [{ id: docs[0].id, score: 0.9, index: 0 }];
+            }),
+        };
+        const rerankerConfig = {
+            enabled: true,
+            provider: mockProvider,
+            topN: 10,
+            candidatePool: 50,
+        };
+        const hybrid = new HybridSearchEngine(engine, null, null, {}, rerankerConfig);
+        await hybrid.search({ query: 'handleRequest', maxResults: 10 });
+        expect(mockProvider.rerank).toHaveBeenCalledTimes(1);
+    });
+    it('includes name and kind when no signature or documentation', async () => {
+        const symbols = [
+            makeSymbol('processData', 'function', 'src/data.ts', {
+                line: 1,
+                language: 'typescript',
+            }),
+        ];
+        const engine = new SearchEngine();
+        engine.buildIndex(symbols);
+        const mockProvider = {
+            model: 'mock',
+            rerank: vi.fn().mockImplementation((_query, docs) => {
+                const text = docs[0].text;
+                expect(text).toContain('function processData');
+                return [{ id: docs[0].id, score: 0.8, index: 0 }];
+            }),
+        };
+        const rerankerConfig = {
+            enabled: true,
+            provider: mockProvider,
+            topN: 10,
+            candidatePool: 50,
+        };
+        const hybrid = new HybridSearchEngine(engine, null, null, {}, rerankerConfig);
+        await hybrid.search({ query: 'processData', maxResults: 10 });
+        expect(mockProvider.rerank).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/src/reranking/cohere-reranker.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Cross-encoder reranker using the Cohere Rerank API.
+ *
+ * Features:
+ * - Model: rerank-v3.5
+ * - Exponential backoff retry on 429 / 5xx errors
+ * - Uses Node.js built-in fetch
+ *
+ * Requires the COHERE_API_KEY environment variable.
+ */
+import type { RerankerProvider, RerankDocument, RerankResult } from './reranker-provider.js';
+export declare class CohereReranker implements RerankerProvider {
+    readonly model: string;
+    private maxRetries;
+    private apiKey;
+    constructor(config?: {
+        model?: string;
+        maxRetries?: number;
+    });
+    rerank(query: string, documents: RerankDocument[]): Promise<RerankResult[]>;
+    private callAPI;
+    /** Calculate retry delay with exponential backoff, respecting Retry-After header. */
+    private getRetryDelay;
+    private sleep;
+}
+//# sourceMappingURL=cohere-reranker.d.ts.map

package/dist/src/reranking/cohere-reranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cohere-reranker.d.ts","sourceRoot":"","sources":["../../../src/reranking/cohere-reranker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAc5F,qBAAa,cAAe,YAAW,gBAAgB;IACrD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,MAAM,CAAQ;gBAEV,MAAM,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO;IAa1D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;YAmBnE,OAAO;IAuDrB,qFAAqF;IACrF,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,KAAK;CAGd"}

package/dist/src/reranking/cohere-reranker.js

@@ -0,0 +1,110 @@
+/**
+ * Cross-encoder reranker using the Cohere Rerank API.
+ *
+ * Features:
+ * - Model: rerank-v3.5
+ * - Exponential backoff retry on 429 / 5xx errors
+ * - Uses Node.js built-in fetch
+ *
+ * Requires the COHERE_API_KEY environment variable.
+ */
+const COHERE_RERANK_URL = 'https://api.cohere.com/v2/rerank';
+const DEFAULT_MODEL = 'rerank-v3.5';
+const DEFAULT_MAX_RETRIES = 3;
+const BASE_RETRY_DELAY_MS = 1000;
+export class CohereReranker {
+    model;
+    maxRetries;
+    apiKey;
+    constructor(config = {}) {
+        const apiKey = process.env.COHERE_API_KEY;
+        if (!apiKey) {
+            throw new Error('COHERE_API_KEY environment variable is required. '
+                + 'Get your API key at https://dashboard.cohere.com/');
+        }
+        this.apiKey = apiKey;
+        this.model = config.model ?? DEFAULT_MODEL;
+        this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    }
+    async rerank(query, documents) {
+        if (documents.length === 0)
+            return [];
+        const body = JSON.stringify({
+            model: this.model,
+            query,
+            documents: documents.map(d => d.text),
+            top_n: documents.length,
+        });
+        const response = await this.callAPI(body);
+        return response.results.map(r => ({
+            id: documents[r.index].id,
+            score: r.relevance_score,
+            index: r.index,
+        }));
+    }
+    async callAPI(body) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                const response = await fetch(COHERE_RERANK_URL, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Authorization': `Bearer ${this.apiKey}`,
+                    },
+                    body,
+                });
+                if (response.ok) {
+                    return (await response.json());
+                }
+                // Retry on rate limit or server errors
+                if (response.status === 429 || response.status >= 500) {
+                    const errorBody = await response.text();
+                    lastError = new Error(`Cohere Rerank API returned ${response.status}: ${errorBody}`);
+                    if (attempt < this.maxRetries) {
+                        await this.sleep(this.getRetryDelay(attempt, response));
+                        continue;
+                    }
+                }
+                else {
+                    // Non-retryable error
+                    const errorBody = await response.text();
+                    let message;
+                    try {
+                        const parsed = JSON.parse(errorBody);
+                        message = parsed.message ?? errorBody;
+                    }
+                    catch {
+                        message = errorBody;
+                    }
+                    throw new Error(`Cohere Rerank API error (${response.status}): ${message}`);
+                }
+            }
+            catch (error) {
+                if (error instanceof Error && error.message.startsWith('Cohere Rerank API error')) {
+                    throw error;
+                }
+                lastError = error instanceof Error ? error : new Error(String(error));
+                if (attempt < this.maxRetries) {
+                    await this.sleep(BASE_RETRY_DELAY_MS * Math.pow(2, attempt));
+                    continue;
+                }
+            }
+        }
+        throw lastError ?? new Error('Cohere Rerank API request failed after retries');
+    }
+    /** Calculate retry delay with exponential backoff, respecting Retry-After header. */
+    getRetryDelay(attempt, response) {
+        const retryAfter = response.headers.get('retry-after');
+        if (retryAfter) {
+            const seconds = Number(retryAfter);
+            if (!Number.isNaN(seconds)) {
+                return seconds * 1000;
+            }
+        }
+        return BASE_RETRY_DELAY_MS * Math.pow(2, attempt);
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/dist/src/reranking/reranker-provider.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Abstract interfaces for cross-encoder reranking providers.
+ * Rerankers rescore search results using a cross-encoder model
+ * for higher-precision final rankings.
+ */
+/** A document to be reranked against a query. */
+export interface RerankDocument {
+    /** Unique identifier for the document. */
+    id: string;
+    /** Document content to score against the query. */
+    text: string;
+}
+/** A single reranking result with relevance score. */
+export interface RerankResult {
+    /** Unique identifier matching the input document. */
+    id: string;
+    /** Relevance score in [0, 1]. */
+    score: number;
+    /** Original position in the input documents array. */
+    index: number;
+}
+/** Abstract interface for cross-encoder reranking providers. */
+export interface RerankerProvider {
+    /** The model name used for reranking. */
+    readonly model: string;
+    /** Rerank documents against a query, returning results sorted by relevance. */
+    rerank(query: string, documents: RerankDocument[]): Promise<RerankResult[]>;
+}
+/** Configuration for the reranking stage in the hybrid search pipeline. */
+export interface RerankerConfig {
+    /** Feature flag — set to false to disable reranking. Default: true */
+    enabled: boolean;
+    /** The reranking provider to use. */
+    provider: RerankerProvider;
+    /** Return top N results after reranking. Default: 10 */
+    topN: number;
+    /** Feed top N candidates from hybrid search to the reranker. Default: 50 */
+    candidatePool: number;
+}
+//# sourceMappingURL=reranker-provider.d.ts.map