agentic-qe 2.5.9 → 2.6.0

package/dist/code-intelligence/search/BM25Search.js

@@ -0,0 +1,233 @@
+"use strict";
+/**
+ * BM25 Search Engine
+ *
+ * Implements Best Matching 25 algorithm for keyword-based
+ * code search with:
+ * - Term frequency saturation
+ * - Document length normalization
+ * - Inverse document frequency weighting
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BM25Search = void 0;
+const types_js_1 = require("./types.js");
+class BM25Search {
+    constructor(config = {}) {
+        this.config = { ...types_js_1.DEFAULT_BM25_CONFIG, ...config };
+        this.index = this.createEmptyIndex();
+    }
+    /**
+     * Add a document to the index.
+     */
+    addDocument(doc) {
+        const terms = this.tokenize(doc.content);
+        const document = { ...doc, terms };
+        // Store document
+        this.index.documents.set(doc.id, document);
+        this.index.documentLengths.set(doc.id, terms.length);
+        // Update term frequencies for this document
+        const termFreqs = new Map();
+        for (const term of terms) {
+            termFreqs.set(term, (termFreqs.get(term) || 0) + 1);
+        }
+        this.index.termFrequencies.set(doc.id, termFreqs);
+        // Update document frequencies
+        const uniqueTerms = new Set(terms);
+        for (const term of uniqueTerms) {
+            this.index.documentFrequency.set(term, (this.index.documentFrequency.get(term) || 0) + 1);
+        }
+        // Update stats
+        this.index.docCount++;
+        this.updateAvgDocLength();
+    }
+    /**
+     * Add multiple documents.
+     */
+    addDocuments(docs) {
+        for (const doc of docs) {
+            this.addDocument(doc);
+        }
+    }
+    /**
+     * Remove a document from the index.
+     */
+    removeDocument(docId) {
+        const doc = this.index.documents.get(docId);
+        if (!doc)
+            return false;
+        // Update document frequencies
+        const termFreqs = this.index.termFrequencies.get(docId);
+        if (termFreqs) {
+            for (const term of termFreqs.keys()) {
+                const df = this.index.documentFrequency.get(term) || 0;
+                if (df <= 1) {
+                    this.index.documentFrequency.delete(term);
+                }
+                else {
+                    this.index.documentFrequency.set(term, df - 1);
+                }
+            }
+        }
+        // Remove from index
+        this.index.documents.delete(docId);
+        this.index.documentLengths.delete(docId);
+        this.index.termFrequencies.delete(docId);
+        // Update stats
+        this.index.docCount--;
+        this.updateAvgDocLength();
+        return true;
+    }
+    /**
+     * Search for documents matching a query.
+     */
+    search(query, topK = 10) {
+        const queryTerms = this.tokenize(query);
+        // Filter query terms by document frequency
+        const filteredTerms = queryTerms.filter(term => {
+            const df = this.index.documentFrequency.get(term) || 0;
+            if (df < this.config.minDocFreq)
+                return false;
+            if (this.index.docCount > 0 && df / this.index.docCount > this.config.maxDocFreqRatio) {
+                return false;
+            }
+            return true;
+        });
+        if (filteredTerms.length === 0) {
+            return [];
+        }
+        // Calculate BM25 scores for all documents
+        const scores = [];
+        for (const [docId, termFreqs] of this.index.termFrequencies) {
+            const docLength = this.index.documentLengths.get(docId) || 0;
+            let score = 0;
+            for (const term of filteredTerms) {
+                const tf = termFreqs.get(term) || 0;
+                if (tf === 0)
+                    continue;
+                const df = this.index.documentFrequency.get(term) || 0;
+                const idf = this.calculateIDF(df);
+                const tfNorm = this.calculateTF(tf, docLength);
+                score += idf * tfNorm;
+            }
+            if (score > 0) {
+                scores.push({ docId, score });
+            }
+        }
+        // Sort by score
+        scores.sort((a, b) => b.score - a.score);
+        // Convert to results
+        return scores.slice(0, topK).map(({ docId, score }) => {
+            const doc = this.index.documents.get(docId);
+            return {
+                id: doc.id,
+                filePath: doc.filePath,
+                content: doc.content,
+                startLine: doc.startLine,
+                endLine: doc.endLine,
+                score,
+                bm25Score: score,
+                entityType: doc.entityType,
+                entityName: doc.entityName,
+                highlights: this.getHighlights(doc.content, filteredTerms),
+            };
+        });
+    }
+    /**
+     * Get term matches in content for highlighting.
+     */
+    getHighlights(content, queryTerms) {
+        const highlights = [];
+        const lines = content.split('\n');
+        for (const line of lines) {
+            const lineTokens = this.tokenize(line);
+            const hasMatch = queryTerms.some(term => lineTokens.includes(term));
+            if (hasMatch) {
+                highlights.push(line.trim());
+            }
+        }
+        return highlights.slice(0, 3); // Max 3 highlights
+    }
+    /**
+     * Get index statistics.
+     */
+    getStats() {
+        return {
+            docCount: this.index.docCount,
+            avgDocLength: this.index.avgDocLength,
+            uniqueTerms: this.index.documentFrequency.size,
+        };
+    }
+    /**
+     * Clear the index.
+     */
+    clear() {
+        this.index = this.createEmptyIndex();
+    }
+    /**
+     * Get configuration.
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Calculate Inverse Document Frequency.
+     * IDF = ln((N - df + 0.5) / (df + 0.5))
+     */
+    calculateIDF(df) {
+        const N = this.index.docCount;
+        return Math.log((N - df + 0.5) / (df + 0.5) + 1);
+    }
+    /**
+     * Calculate normalized term frequency.
+     * TF = (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * dl/avgdl))
+     */
+    calculateTF(tf, docLength) {
+        const { k1, b } = this.config;
+        const avgDl = this.index.avgDocLength || 1;
+        const numerator = tf * (k1 + 1);
+        const denominator = tf + k1 * (1 - b + b * (docLength / avgDl));
+        return numerator / denominator;
+    }
+    /**
+     * Tokenize text into terms.
+     */
+    tokenize(text) {
+        // Split on non-alphanumeric, handle camelCase and snake_case
+        const expanded = text
+            .replace(/([a-z])([A-Z])/g, '$1 $2') // camelCase
+            .replace(/_/g, ' ') // snake_case
+            .toLowerCase();
+        return expanded
+            .split(/[^a-z0-9]+/)
+            .filter(token => token.length >= 2); // Min 2 chars
+    }
+    /**
+     * Update average document length.
+     */
+    updateAvgDocLength() {
+        if (this.index.docCount === 0) {
+            this.index.avgDocLength = 0;
+            return;
+        }
+        let totalLength = 0;
+        for (const length of this.index.documentLengths.values()) {
+            totalLength += length;
+        }
+        this.index.avgDocLength = totalLength / this.index.docCount;
+    }
+    /**
+     * Create empty index structure.
+     */
+    createEmptyIndex() {
+        return {
+            docCount: 0,
+            avgDocLength: 0,
+            documentFrequency: new Map(),
+            termFrequencies: new Map(),
+            documentLengths: new Map(),
+            documents: new Map(),
+        };
+    }
+}
+exports.BM25Search = BM25Search;
+//# sourceMappingURL=BM25Search.js.map

package/dist/code-intelligence/search/BM25Search.js.map

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

package/dist/code-intelligence/search/HybridSearchEngine.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Hybrid Search Engine
+ *
+ * Combines BM25 keyword search with vector similarity search
+ * using Reciprocal Rank Fusion (RRF) for optimal results.
+ *
+ * Benefits:
+ * - BM25 excels at exact keyword matches and rare terms
+ * - Vector search excels at semantic similarity
+ * - RRF combines both without manual tuning
+ */
+import { HybridSearchConfig, SearchResult, SearchResponse } from './types.js';
+export interface VectorSearchProvider {
+    search(query: string, topK: number): Promise<SearchResult[]>;
+}
+export declare class HybridSearchEngine {
+    private config;
+    private bm25;
+    private rrfFusion;
+    private vectorProvider?;
+    constructor(config?: Partial<HybridSearchConfig>, vectorProvider?: VectorSearchProvider);
+    /**
+     * Add a document to the search index.
+     */
+    addDocument(doc: {
+        id: string;
+        filePath: string;
+        content: string;
+        startLine: number;
+        endLine: number;
+        entityType?: string;
+        entityName?: string;
+    }): void;
+    /**
+     * Add multiple documents.
+     */
+    addDocuments(docs: Array<{
+        id: string;
+        filePath: string;
+        content: string;
+        startLine: number;
+        endLine: number;
+        entityType?: string;
+        entityName?: string;
+    }>): void;
+    /**
+     * Remove a document.
+     */
+    removeDocument(docId: string): boolean;
+    /**
+     * Set the vector search provider.
+     */
+    setVectorProvider(provider: VectorSearchProvider): void;
+    /**
+     * Perform hybrid search.
+     */
+    search(query: string, configOverride?: Partial<HybridSearchConfig>): Promise<SearchResponse>;
+    /**
+     * BM25-only search (no vector).
+     */
+    searchKeyword(query: string, topK?: number): SearchResult[];
+    /**
+     * Vector-only search.
+     */
+    searchSemantic(query: string, topK?: number): Promise<SearchResult[]>;
+    /**
+     * Get index statistics.
+     */
+    getStats(): {
+        bm25: {
+            docCount: number;
+            avgDocLength: number;
+            uniqueTerms: number;
+        };
+        hasVectorProvider: boolean;
+    };
+    /**
+     * Clear all indexes.
+     */
+    clear(): void;
+    /**
+     * Get configuration.
+     */
+    getConfig(): HybridSearchConfig;
+    /**
+     * Update configuration.
+     */
+    updateConfig(config: Partial<HybridSearchConfig>): void;
+    /**
+     * Simple tokenization for highlighting.
+     */
+    private tokenize;
+}
+//# sourceMappingURL=HybridSearchEngine.d.ts.map

package/dist/code-intelligence/search/HybridSearchEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HybridSearchEngine.d.ts","sourceRoot":"","sources":["../../../src/code-intelligence/search/HybridSearchEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,cAAc,EAGf,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CAC9D;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,cAAc,CAAC,CAAuB;gBAG5C,MAAM,GAAE,OAAO,CAAC,kBAAkB,CAAM,EACxC,cAAc,CAAC,EAAE,oBAAoB;IAQvC;;OAEG;IACH,WAAW,CAAC,GAAG,EAAE;QACf,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,IAAI;IAIR;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC;QACvB,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC,GAAG,IAAI;IAIT;;OAEG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAItC;;OAEG;IACH,iBAAiB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI;IAIvD;;OAEG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,cAAc,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAC3C,OAAO,CAAC,cAAc,CAAC;IA8E1B;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE;IAI3D;;OAEG;IACG,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAO3E;;OAEG;IACH,QAAQ,IAAI;QACV,IAAI,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,YAAY,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAC;QACtE,iBAAiB,EAAE,OAAO,CAAC;KAC5B;IAOD;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,SAAS,IAAI,kBAAkB;IAI/B;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,IAAI;IAKvD;;OAEG;IACH,OAAO,CAAC,QAAQ;CAQjB"}

package/dist/code-intelligence/search/HybridSearchEngine.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * Hybrid Search Engine
+ *
+ * Combines BM25 keyword search with vector similarity search
+ * using Reciprocal Rank Fusion (RRF) for optimal results.
+ *
+ * Benefits:
+ * - BM25 excels at exact keyword matches and rare terms
+ * - Vector search excels at semantic similarity
+ * - RRF combines both without manual tuning
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HybridSearchEngine = void 0;
+const BM25Search_js_1 = require("./BM25Search.js");
+const RRFFusion_js_1 = require("./RRFFusion.js");
+const types_js_1 = require("./types.js");
+class HybridSearchEngine {
+    constructor(config = {}, vectorProvider) {
+        this.config = { ...types_js_1.DEFAULT_HYBRID_SEARCH_CONFIG, ...config };
+        this.bm25 = new BM25Search_js_1.BM25Search();
+        this.rrfFusion = new RRFFusion_js_1.RRFFusion({ k: this.config.rrfK });
+        this.vectorProvider = vectorProvider;
+    }
+    /**
+     * Add a document to the search index.
+     */
+    addDocument(doc) {
+        this.bm25.addDocument(doc);
+    }
+    /**
+     * Add multiple documents.
+     */
+    addDocuments(docs) {
+        this.bm25.addDocuments(docs);
+    }
+    /**
+     * Remove a document.
+     */
+    removeDocument(docId) {
+        return this.bm25.removeDocument(docId);
+    }
+    /**
+     * Set the vector search provider.
+     */
+    setVectorProvider(provider) {
+        this.vectorProvider = provider;
+    }
+    /**
+     * Perform hybrid search.
+     */
+    async search(query, configOverride) {
+        const config = { ...this.config, ...configOverride };
+        const startTime = Date.now();
+        const candidateCount = config.topK * config.candidateMultiplier;
+        let bm25TimeMs = 0;
+        let vectorTimeMs = 0;
+        let fusionTimeMs = 0;
+        // BM25 search
+        const bm25Start = Date.now();
+        const bm25Results = this.bm25.search(query, candidateCount);
+        bm25TimeMs = Date.now() - bm25Start;
+        // Vector search (if provider available)
+        let vectorResults = [];
+        if (this.vectorProvider) {
+            const vectorStart = Date.now();
+            vectorResults = await this.vectorProvider.search(query, candidateCount);
+            vectorTimeMs = Date.now() - vectorStart;
+        }
+        // Fusion
+        const fusionStart = Date.now();
+        let results;
+        if (vectorResults.length === 0) {
+            // BM25 only
+            results = bm25Results.slice(0, config.topK);
+        }
+        else if (config.useRRF) {
+            // RRF fusion
+            results = this.rrfFusion.fuse([bm25Results, vectorResults], config.topK);
+        }
+        else {
+            // Weighted score fusion
+            results = this.rrfFusion.fuseScores([bm25Results, vectorResults], [config.bm25Weight, config.vectorWeight], config.topK);
+        }
+        fusionTimeMs = Date.now() - fusionStart;
+        // Filter by minimum score
+        results = results.filter(r => r.score >= config.minScore);
+        // Add highlights if enabled
+        if (config.includeHighlights) {
+            for (const result of results) {
+                if (!result.highlights || result.highlights.length === 0) {
+                    result.highlights = this.bm25.getHighlights(result.content, this.tokenize(query));
+                }
+            }
+        }
+        const stats = {
+            bm25Candidates: bm25Results.length,
+            vectorCandidates: vectorResults.length,
+            fusedResults: results.length,
+            bm25TimeMs,
+            vectorTimeMs,
+            fusionTimeMs,
+        };
+        return {
+            results,
+            query,
+            totalMatches: bm25Results.length + vectorResults.length,
+            searchTimeMs: Date.now() - startTime,
+            stats,
+        };
+    }
+    /**
+     * BM25-only search (no vector).
+     */
+    searchKeyword(query, topK) {
+        return this.bm25.search(query, topK || this.config.topK);
+    }
+    /**
+     * Vector-only search.
+     */
+    async searchSemantic(query, topK) {
+        if (!this.vectorProvider) {
+            throw new Error('Vector provider not configured');
+        }
+        return this.vectorProvider.search(query, topK || this.config.topK);
+    }
+    /**
+     * Get index statistics.
+     */
+    getStats() {
+        return {
+            bm25: this.bm25.getStats(),
+            hasVectorProvider: !!this.vectorProvider,
+        };
+    }
+    /**
+     * Clear all indexes.
+     */
+    clear() {
+        this.bm25.clear();
+    }
+    /**
+     * Get configuration.
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update configuration.
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+        this.rrfFusion.updateConfig({ k: this.config.rrfK });
+    }
+    /**
+     * Simple tokenization for highlighting.
+     */
+    tokenize(text) {
+        return text
+            .replace(/([a-z])([A-Z])/g, '$1 $2')
+            .replace(/_/g, ' ')
+            .toLowerCase()
+            .split(/[^a-z0-9]+/)
+            .filter(token => token.length >= 2);
+    }
+}
+exports.HybridSearchEngine = HybridSearchEngine;
+//# sourceMappingURL=HybridSearchEngine.js.map

package/dist/code-intelligence/search/HybridSearchEngine.js.map

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

package/dist/code-intelligence/search/RRFFusion.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Reciprocal Rank Fusion (RRF)
+ *
+ * Combines rankings from multiple search methods
+ * using the RRF formula:
+ *   score(d) = Σ 1 / (k + rank_i(d))
+ *
+ * Where k is a constant (typically 60) that determines
+ * how much weight is given to lower-ranked results.
+ */
+import { RRFConfig, SearchResult } from './types.js';
+export declare class RRFFusion {
+    private config;
+    constructor(config?: Partial<RRFConfig>);
+    /**
+     * Fuse multiple ranked lists using RRF.
+     *
+     * @param rankedLists - Array of search result lists, each ordered by relevance
+     * @param topK - Number of results to return
+     * @returns Fused results ordered by RRF score
+     */
+    fuse(rankedLists: SearchResult[][], topK?: number): SearchResult[];
+    /**
+     * Fuse with weighted RRF.
+     * Allows different weights for each source.
+     */
+    fuseWeighted(rankedLists: SearchResult[][], weights: number[], topK?: number): SearchResult[];
+    /**
+     * Simple weighted score fusion (alternative to RRF).
+     * Combines normalized scores directly.
+     */
+    fuseScores(rankedLists: SearchResult[][], weights: number[], topK?: number): SearchResult[];
+    /**
+     * Calculate RRF score from ranks.
+     */
+    private calculateRRFScore;
+    /**
+     * Get configuration.
+     */
+    getConfig(): RRFConfig;
+    /**
+     * Update configuration.
+     */
+    updateConfig(config: Partial<RRFConfig>): void;
+}
+//# sourceMappingURL=RRFFusion.d.ts.map

package/dist/code-intelligence/search/RRFFusion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RRFFusion.d.ts","sourceRoot":"","sources":["../../../src/code-intelligence/search/RRFFusion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,SAAS,EAET,YAAY,EAEb,MAAM,YAAY,CAAC;AAEpB,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAY;gBAEd,MAAM,GAAE,OAAO,CAAC,SAAS,CAAM;IAI3C;;;;;;OAMG;IACH,IAAI,CAAC,WAAW,EAAE,YAAY,EAAE,EAAE,EAAE,IAAI,GAAE,MAAW,GAAG,YAAY,EAAE;IAoEtE;;;OAGG;IACH,YAAY,CACV,WAAW,EAAE,YAAY,EAAE,EAAE,EAC7B,OAAO,EAAE,MAAM,EAAE,EACjB,IAAI,GAAE,MAAW,GAChB,YAAY,EAAE;IAsEjB;;;OAGG;IACH,UAAU,CACR,WAAW,EAAE,YAAY,EAAE,EAAE,EAC7B,OAAO,EAAE,MAAM,EAAE,EACjB,IAAI,GAAE,MAAW,GAChB,YAAY,EAAE;IA2DjB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAUzB;;OAEG;IACH,SAAS,IAAI,SAAS;IAItB;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,IAAI;CAG/C"}