@framers/agentos 0.1.120 → 0.1.122

package/dist/rag/search/HybridSearcher.d.ts

@@ -0,0 +1,198 @@
+/**
+ * @fileoverview Hybrid dense+sparse searcher combining vector embeddings with BM25.
+ *
+ * Uses Reciprocal Rank Fusion (RRF) to merge results from both systems:
+ * - Dense: semantic understanding, handles paraphrasing and conceptual similarity
+ * - Sparse: keyword matching, handles exact terms, error codes, function names
+ *
+ * RRF formula (Cormack et al. 2009):
+ * ```
+ * score(d) = sum_{i} weight_i / (k + rank_i(d))
+ * ```
+ * where `k=60` (standard constant) and `rank_i(d)` is the rank of document `d`
+ * in result set `i`. Documents not present in a result set are assigned rank infinity.
+ *
+ * Alternative fusion methods:
+ * - **weighted-sum**: `score(d) = w_dense * norm_score_dense(d) + w_sparse * norm_score_sparse(d)`
+ * - **interleave**: Round-robin from each result set, deduplicating
+ *
+ * @module agentos/rag/search/HybridSearcher
+ * @see BM25Index for the sparse keyword index
+ * @see IVectorStore for the dense vector store interface
+ */
+import type { IVectorStore, QueryOptions } from '../IVectorStore.js';
+import type { IEmbeddingManager } from '../IEmbeddingManager.js';
+import { BM25Index } from './BM25Index.js';
+/**
+ * Configuration for the hybrid searcher.
+ *
+ * @interface HybridSearcherConfig
+ */
+export interface HybridSearcherConfig {
+    /** Weight for dense (vector) results. Range: 0-1. Default: 0.7. */
+    denseWeight?: number;
+    /** Weight for sparse (BM25) results. Range: 0-1. Default: 0.3. */
+    sparseWeight?: number;
+    /** RRF constant k. Higher values flatten score differences. Default: 60. */
+    rrfK?: number;
+    /** Fusion method for merging ranked lists. Default: 'rrf'. */
+    fusionMethod?: 'rrf' | 'weighted-sum' | 'interleave';
+}
+/**
+ * A hybrid search result combining dense and sparse signals.
+ *
+ * @interface HybridResult
+ * @property {string} id - Document identifier.
+ * @property {number} score - Fused relevance score.
+ * @property {number} [denseScore] - Score from vector search (if present).
+ * @property {number} [sparseScore] - Score from BM25 search (if present).
+ * @property {number} [denseRank] - Rank in vector search results (1-based).
+ * @property {number} [sparseRank] - Rank in BM25 search results (1-based).
+ * @property {string} [textContent] - Document text content if available.
+ * @property {Record<string, unknown>} [metadata] - Document metadata.
+ */
+export interface HybridResult {
+    /** Document identifier. */
+    id: string;
+    /** Fused relevance score (higher = more relevant). */
+    score: number;
+    /** Score from the dense (vector) search, if this document appeared in dense results. */
+    denseScore?: number;
+    /** Score from the sparse (BM25) search, if this document appeared in sparse results. */
+    sparseScore?: number;
+    /** 1-based rank in the dense search results. */
+    denseRank?: number;
+    /** 1-based rank in the sparse search results. */
+    sparseRank?: number;
+    /** Document text content if available from the vector store. */
+    textContent?: string;
+    /** Document metadata merged from both sources. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Hybrid dense+sparse searcher combining vector embeddings with BM25.
+ *
+ * Uses Reciprocal Rank Fusion (RRF) to merge results from both retrieval
+ * systems, capturing both semantic similarity and exact keyword matches.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const bm25 = new BM25Index();
+ * bm25.addDocuments(documents);
+ *
+ * const hybrid = new HybridSearcher(vectorStore, embeddingManager, bm25, {
+ *   denseWeight: 0.7,
+ *   sparseWeight: 0.3,
+ *   fusionMethod: 'rrf',
+ * });
+ *
+ * const results = await hybrid.search(
+ *   'error TS2304 type declarations',
+ *   'my-collection',
+ *   10,
+ * );
+ * ```
+ *
+ * @example Weighted sum fusion (when you have calibrated scores)
+ * ```typescript
+ * const hybrid = new HybridSearcher(vectorStore, embeddingManager, bm25, {
+ *   fusionMethod: 'weighted-sum',
+ *   denseWeight: 0.6,
+ *   sparseWeight: 0.4,
+ * });
+ * ```
+ */
+export declare class HybridSearcher {
+    /** Dense vector store for semantic retrieval. */
+    private vectorStore;
+    /** Embedding manager for generating query embeddings. */
+    private embeddingManager;
+    /** Sparse BM25 index for keyword retrieval. */
+    private bm25Index;
+    /** Resolved configuration with defaults applied. */
+    private config;
+    /**
+     * Creates a new HybridSearcher.
+     *
+     * @param {IVectorStore} vectorStore - Dense vector store for semantic search.
+     * @param {IEmbeddingManager} embeddingManager - Manager for generating query embeddings.
+     * @param {BM25Index} bm25Index - BM25 sparse keyword index.
+     * @param {HybridSearcherConfig} [config] - Optional configuration overrides.
+     *
+     * @example
+     * ```typescript
+     * const searcher = new HybridSearcher(store, embeddings, bm25, {
+     *   denseWeight: 0.7,
+     *   sparseWeight: 0.3,
+     * });
+     * ```
+     */
+    constructor(vectorStore: IVectorStore, embeddingManager: IEmbeddingManager, bm25Index: BM25Index, config?: HybridSearcherConfig);
+    /**
+     * Searches both dense and sparse indexes, then fuses results.
+     *
+     * Pipeline:
+     * 1. Generate query embedding via the embedding manager
+     * 2. Query the dense vector store for semantically similar documents
+     * 3. Query the BM25 sparse index for keyword-matching documents
+     * 4. Fuse both result sets using the configured fusion method (RRF by default)
+     * 5. Return the top K results sorted by fused score
+     *
+     * @param {string} query - The search query text.
+     * @param {string} collectionName - Vector store collection to search.
+     * @param {number} [topK=10] - Maximum number of results to return.
+     * @param {Partial<QueryOptions>} [queryOptions] - Additional options for the vector store query.
+     * @returns {Promise<HybridResult[]>} Fused results sorted by relevance.
+     * @throws {Error} If embedding generation fails.
+     *
+     * @example
+     * ```typescript
+     * const results = await hybrid.search('error TS2304', 'knowledge-base', 5);
+     * for (const r of results) {
+     *   console.log(`${r.id}: fused=${r.score.toFixed(4)} dense=${r.denseRank} sparse=${r.sparseRank}`);
+     * }
+     * ```
+     */
+    search(query: string, collectionName: string, topK?: number, queryOptions?: Partial<QueryOptions>): Promise<HybridResult[]>;
+    /**
+     * Fuses results using Reciprocal Rank Fusion (RRF).
+     *
+     * Formula: `score(d) = sum_i weight_i / (k + rank_i(d))`
+     *
+     * Documents appearing in both result sets get contributions from both,
+     * naturally boosting documents ranked highly by both systems.
+     *
+     * @param {RetrievedVectorDocument[]} denseResults - Dense vector search results.
+     * @param {BM25Result[]} sparseResults - BM25 sparse search results.
+     * @param {number} topK - Maximum results to return.
+     * @returns {HybridResult[]} Fused results sorted by RRF score.
+     */
+    private fuseRRF;
+    /**
+     * Fuses results using weighted score summation with min-max normalization.
+     *
+     * Both score distributions are normalized to [0, 1] before weighting
+     * to account for the different scoring scales of dense (cosine similarity)
+     * and sparse (BM25 score) systems.
+     *
+     * @param {RetrievedVectorDocument[]} denseResults - Dense vector search results.
+     * @param {BM25Result[]} sparseResults - BM25 sparse search results.
+     * @param {number} topK - Maximum results to return.
+     * @returns {HybridResult[]} Fused results sorted by weighted score.
+     */
+    private fuseWeightedSum;
+    /**
+     * Fuses results using round-robin interleaving with deduplication.
+     *
+     * Alternates between picking the next-best dense result and the
+     * next-best sparse result, skipping documents already included.
+     * This provides a simple diversity-preserving fusion.
+     *
+     * @param {RetrievedVectorDocument[]} denseResults - Dense vector search results.
+     * @param {BM25Result[]} sparseResults - BM25 sparse search results.
+     * @param {number} topK - Maximum results to return.
+     * @returns {HybridResult[]} Interleaved results.
+     */
+    private fuseInterleave;
+}
+//# sourceMappingURL=HybridSearcher.d.ts.map

package/dist/rag/search/HybridSearcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HybridSearcher.d.ts","sourceRoot":"","sources":["../../../src/rag/search/HybridSearcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAwC,MAAM,oBAAoB,CAAC;AAC3G,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,SAAS,EAAmB,MAAM,gBAAgB,CAAC;AAI5D;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,YAAY,CAAC,EAAE,KAAK,GAAG,cAAc,GAAG,YAAY,CAAC;CACtD;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,cAAc;IACzB,iDAAiD;IACjD,OAAO,CAAC,WAAW,CAAe;IAElC,yDAAyD;IACzD,OAAO,CAAC,gBAAgB,CAAoB;IAE5C,+CAA+C;IAC/C,OAAO,CAAC,SAAS,CAAY;IAE7B,oDAAoD;IACpD,OAAO,CAAC,MAAM,CAAiC;IAE/C;;;;;;;;;;;;;;;OAeG;gBAED,WAAW,EAAE,YAAY,EACzB,gBAAgB,EAAE,iBAAiB,EACnC,SAAS,EAAE,SAAS,EACpB,MAAM,CAAC,EAAE,oBAAoB;IAa/B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,EACtB,IAAI,GAAE,MAAW,EACjB,YAAY,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GACnC,OAAO,CAAC,YAAY,EAAE,CAAC;IA0C1B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,OAAO;IAyDf;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,eAAe;IAoDvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,cAAc;CA+CvB"}

package/dist/rag/search/HybridSearcher.js

@@ -0,0 +1,316 @@
+/**
+ * @fileoverview Hybrid dense+sparse searcher combining vector embeddings with BM25.
+ *
+ * Uses Reciprocal Rank Fusion (RRF) to merge results from both systems:
+ * - Dense: semantic understanding, handles paraphrasing and conceptual similarity
+ * - Sparse: keyword matching, handles exact terms, error codes, function names
+ *
+ * RRF formula (Cormack et al. 2009):
+ * ```
+ * score(d) = sum_{i} weight_i / (k + rank_i(d))
+ * ```
+ * where `k=60` (standard constant) and `rank_i(d)` is the rank of document `d`
+ * in result set `i`. Documents not present in a result set are assigned rank infinity.
+ *
+ * Alternative fusion methods:
+ * - **weighted-sum**: `score(d) = w_dense * norm_score_dense(d) + w_sparse * norm_score_sparse(d)`
+ * - **interleave**: Round-robin from each result set, deduplicating
+ *
+ * @module agentos/rag/search/HybridSearcher
+ * @see BM25Index for the sparse keyword index
+ * @see IVectorStore for the dense vector store interface
+ */
+// ── Hybrid Searcher ───────────────────────────────────────────────────────
+/**
+ * Hybrid dense+sparse searcher combining vector embeddings with BM25.
+ *
+ * Uses Reciprocal Rank Fusion (RRF) to merge results from both retrieval
+ * systems, capturing both semantic similarity and exact keyword matches.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const bm25 = new BM25Index();
+ * bm25.addDocuments(documents);
+ *
+ * const hybrid = new HybridSearcher(vectorStore, embeddingManager, bm25, {
+ *   denseWeight: 0.7,
+ *   sparseWeight: 0.3,
+ *   fusionMethod: 'rrf',
+ * });
+ *
+ * const results = await hybrid.search(
+ *   'error TS2304 type declarations',
+ *   'my-collection',
+ *   10,
+ * );
+ * ```
+ *
+ * @example Weighted sum fusion (when you have calibrated scores)
+ * ```typescript
+ * const hybrid = new HybridSearcher(vectorStore, embeddingManager, bm25, {
+ *   fusionMethod: 'weighted-sum',
+ *   denseWeight: 0.6,
+ *   sparseWeight: 0.4,
+ * });
+ * ```
+ */
+export class HybridSearcher {
+    /**
+     * Creates a new HybridSearcher.
+     *
+     * @param {IVectorStore} vectorStore - Dense vector store for semantic search.
+     * @param {IEmbeddingManager} embeddingManager - Manager for generating query embeddings.
+     * @param {BM25Index} bm25Index - BM25 sparse keyword index.
+     * @param {HybridSearcherConfig} [config] - Optional configuration overrides.
+     *
+     * @example
+     * ```typescript
+     * const searcher = new HybridSearcher(store, embeddings, bm25, {
+     *   denseWeight: 0.7,
+     *   sparseWeight: 0.3,
+     * });
+     * ```
+     */
+    constructor(vectorStore, embeddingManager, bm25Index, config) {
+        this.vectorStore = vectorStore;
+        this.embeddingManager = embeddingManager;
+        this.bm25Index = bm25Index;
+        this.config = {
+            denseWeight: config?.denseWeight ?? 0.7,
+            sparseWeight: config?.sparseWeight ?? 0.3,
+            rrfK: config?.rrfK ?? 60,
+            fusionMethod: config?.fusionMethod ?? 'rrf',
+        };
+    }
+    /**
+     * Searches both dense and sparse indexes, then fuses results.
+     *
+     * Pipeline:
+     * 1. Generate query embedding via the embedding manager
+     * 2. Query the dense vector store for semantically similar documents
+     * 3. Query the BM25 sparse index for keyword-matching documents
+     * 4. Fuse both result sets using the configured fusion method (RRF by default)
+     * 5. Return the top K results sorted by fused score
+     *
+     * @param {string} query - The search query text.
+     * @param {string} collectionName - Vector store collection to search.
+     * @param {number} [topK=10] - Maximum number of results to return.
+     * @param {Partial<QueryOptions>} [queryOptions] - Additional options for the vector store query.
+     * @returns {Promise<HybridResult[]>} Fused results sorted by relevance.
+     * @throws {Error} If embedding generation fails.
+     *
+     * @example
+     * ```typescript
+     * const results = await hybrid.search('error TS2304', 'knowledge-base', 5);
+     * for (const r of results) {
+     *   console.log(`${r.id}: fused=${r.score.toFixed(4)} dense=${r.denseRank} sparse=${r.sparseRank}`);
+     * }
+     * ```
+     */
+    async search(query, collectionName, topK = 10, queryOptions) {
+        // Fetch more candidates from each system to improve fusion quality
+        const candidateMultiplier = 3;
+        const candidateK = topK * candidateMultiplier;
+        // 1. Generate query embedding
+        const embeddingResponse = await this.embeddingManager.generateEmbeddings({
+            texts: [query],
+        });
+        if (!embeddingResponse.embeddings?.[0] ||
+            embeddingResponse.embeddings[0].length === 0) {
+            throw new Error('HybridSearcher: Failed to generate query embedding.');
+        }
+        const queryEmbedding = embeddingResponse.embeddings[0];
+        // 2. Execute both searches in parallel
+        const [denseResult, sparseResults] = await Promise.all([
+            this.vectorStore.query(collectionName, queryEmbedding, {
+                topK: candidateK,
+                includeTextContent: true,
+                includeMetadata: true,
+                ...queryOptions,
+            }),
+            Promise.resolve(this.bm25Index.search(query, candidateK)),
+        ]);
+        // 3. Fuse results
+        switch (this.config.fusionMethod) {
+            case 'weighted-sum':
+                return this.fuseWeightedSum(denseResult.documents, sparseResults, topK);
+            case 'interleave':
+                return this.fuseInterleave(denseResult.documents, sparseResults, topK);
+            case 'rrf':
+            default:
+                return this.fuseRRF(denseResult.documents, sparseResults, topK);
+        }
+    }
+    /**
+     * Fuses results using Reciprocal Rank Fusion (RRF).
+     *
+     * Formula: `score(d) = sum_i weight_i / (k + rank_i(d))`
+     *
+     * Documents appearing in both result sets get contributions from both,
+     * naturally boosting documents ranked highly by both systems.
+     *
+     * @param {RetrievedVectorDocument[]} denseResults - Dense vector search results.
+     * @param {BM25Result[]} sparseResults - BM25 sparse search results.
+     * @param {number} topK - Maximum results to return.
+     * @returns {HybridResult[]} Fused results sorted by RRF score.
+     */
+    fuseRRF(denseResults, sparseResults, topK) {
+        const resultMap = new Map();
+        const k = this.config.rrfK;
+        // Score from dense results
+        for (let rank = 0; rank < denseResults.length; rank++) {
+            const doc = denseResults[rank];
+            const rrfScore = this.config.denseWeight / (k + rank + 1); // rank is 1-based in formula
+            const existing = resultMap.get(doc.id);
+            if (existing) {
+                existing.score += rrfScore;
+                existing.denseScore = doc.similarityScore;
+                existing.denseRank = rank + 1;
+                existing.textContent = existing.textContent ?? doc.textContent;
+            }
+            else {
+                resultMap.set(doc.id, {
+                    id: doc.id,
+                    score: rrfScore,
+                    denseScore: doc.similarityScore,
+                    denseRank: rank + 1,
+                    textContent: doc.textContent,
+                    metadata: doc.metadata,
+                });
+            }
+        }
+        // Score from sparse results
+        for (let rank = 0; rank < sparseResults.length; rank++) {
+            const result = sparseResults[rank];
+            const rrfScore = this.config.sparseWeight / (k + rank + 1);
+            const existing = resultMap.get(result.id);
+            if (existing) {
+                existing.score += rrfScore;
+                existing.sparseScore = result.score;
+                existing.sparseRank = rank + 1;
+                existing.metadata = existing.metadata ?? result.metadata;
+            }
+            else {
+                resultMap.set(result.id, {
+                    id: result.id,
+                    score: rrfScore,
+                    sparseScore: result.score,
+                    sparseRank: rank + 1,
+                    metadata: result.metadata,
+                });
+            }
+        }
+        // Sort by fused score descending and return top K
+        return Array.from(resultMap.values())
+            .sort((a, b) => b.score - a.score)
+            .slice(0, topK);
+    }
+    /**
+     * Fuses results using weighted score summation with min-max normalization.
+     *
+     * Both score distributions are normalized to [0, 1] before weighting
+     * to account for the different scoring scales of dense (cosine similarity)
+     * and sparse (BM25 score) systems.
+     *
+     * @param {RetrievedVectorDocument[]} denseResults - Dense vector search results.
+     * @param {BM25Result[]} sparseResults - BM25 sparse search results.
+     * @param {number} topK - Maximum results to return.
+     * @returns {HybridResult[]} Fused results sorted by weighted score.
+     */
+    fuseWeightedSum(denseResults, sparseResults, topK) {
+        // Normalize dense scores to [0, 1]
+        const denseScores = denseResults.map((d) => d.similarityScore);
+        const denseMin = Math.min(...denseScores, 0);
+        const denseMax = Math.max(...denseScores, 1);
+        const denseRange = denseMax - denseMin || 1;
+        // Normalize sparse scores to [0, 1]
+        const sparseScores = sparseResults.map((r) => r.score);
+        const sparseMin = Math.min(...sparseScores, 0);
+        const sparseMax = Math.max(...sparseScores, 1);
+        const sparseRange = sparseMax - sparseMin || 1;
+        const resultMap = new Map();
+        for (const doc of denseResults) {
+            const normalizedScore = (doc.similarityScore - denseMin) / denseRange;
+            resultMap.set(doc.id, {
+                id: doc.id,
+                score: this.config.denseWeight * normalizedScore,
+                denseScore: doc.similarityScore,
+                textContent: doc.textContent,
+                metadata: doc.metadata,
+            });
+        }
+        for (const result of sparseResults) {
+            const normalizedScore = (result.score - sparseMin) / sparseRange;
+            const existing = resultMap.get(result.id);
+            if (existing) {
+                existing.score += this.config.sparseWeight * normalizedScore;
+                existing.sparseScore = result.score;
+                existing.metadata = existing.metadata ?? result.metadata;
+            }
+            else {
+                resultMap.set(result.id, {
+                    id: result.id,
+                    score: this.config.sparseWeight * normalizedScore,
+                    sparseScore: result.score,
+                    metadata: result.metadata,
+                });
+            }
+        }
+        return Array.from(resultMap.values())
+            .sort((a, b) => b.score - a.score)
+            .slice(0, topK);
+    }
+    /**
+     * Fuses results using round-robin interleaving with deduplication.
+     *
+     * Alternates between picking the next-best dense result and the
+     * next-best sparse result, skipping documents already included.
+     * This provides a simple diversity-preserving fusion.
+     *
+     * @param {RetrievedVectorDocument[]} denseResults - Dense vector search results.
+     * @param {BM25Result[]} sparseResults - BM25 sparse search results.
+     * @param {number} topK - Maximum results to return.
+     * @returns {HybridResult[]} Interleaved results.
+     */
+    fuseInterleave(denseResults, sparseResults, topK) {
+        const results = [];
+        const seen = new Set();
+        let di = 0;
+        let si = 0;
+        while (results.length < topK && (di < denseResults.length || si < sparseResults.length)) {
+            // Pick from dense
+            while (di < denseResults.length && results.length < topK) {
+                const doc = denseResults[di++];
+                if (!seen.has(doc.id)) {
+                    seen.add(doc.id);
+                    results.push({
+                        id: doc.id,
+                        score: doc.similarityScore,
+                        denseScore: doc.similarityScore,
+                        denseRank: di,
+                        textContent: doc.textContent,
+                        metadata: doc.metadata,
+                    });
+                    break;
+                }
+            }
+            // Pick from sparse
+            while (si < sparseResults.length && results.length < topK) {
+                const result = sparseResults[si++];
+                if (!seen.has(result.id)) {
+                    seen.add(result.id);
+                    results.push({
+                        id: result.id,
+                        score: result.score,
+                        sparseScore: result.score,
+                        sparseRank: si,
+                        metadata: result.metadata,
+                    });
+                    break;
+                }
+            }
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=HybridSearcher.js.map

package/dist/rag/search/HybridSearcher.js.map

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

package/dist/rag/search/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Hybrid search module combining dense vector search with BM25 sparse retrieval.
+ *
+ * Exports:
+ * - {@link BM25Index} — Sparse keyword index using BM25 ranking
+ * - {@link HybridSearcher} — Fuses dense + sparse results via RRF or other strategies
+ *
+ * @module agentos/rag/search
+ */
+export { BM25Index, type BM25Config, type BM25Document, type BM25Result, type BM25Stats } from './BM25Index.js';
+export { HybridSearcher, type HybridSearcherConfig, type HybridResult } from './HybridSearcher.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/rag/search/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/rag/search/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChH,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/rag/search/index.js

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Hybrid search module combining dense vector search with BM25 sparse retrieval.
+ *
+ * Exports:
+ * - {@link BM25Index} — Sparse keyword index using BM25 ranking
+ * - {@link HybridSearcher} — Fuses dense + sparse results via RRF or other strategies
+ *
+ * @module agentos/rag/search
+ */
+export { BM25Index } from './BM25Index.js';
+export { HybridSearcher } from './HybridSearcher.js';
+//# sourceMappingURL=index.js.map

package/dist/rag/search/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/rag/search/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAuE,MAAM,gBAAgB,CAAC;AAChH,OAAO,EAAE,cAAc,EAAgD,MAAM,qBAAqB,CAAC"}

package/dist/rag/setup/DockerDetector.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Docker environment detection and container management.
+ * @module rag/setup/DockerDetector
+ *
+ * Utility class for detecting whether Docker is available, checking
+ * container state, starting/stopping containers, and pulling images.
+ * Used by QdrantSetup and PostgresSetup for auto-provisioning.
+ */
+export declare class DockerDetector {
+    /**
+     * Check if Docker is installed and the daemon is running.
+     * Runs `docker info` with a 5-second timeout.
+     *
+     * @returns True if Docker is available and responsive.
+     */
+    static isDockerAvailable(): boolean;
+    /**
+     * Check the state of a named Docker container.
+     *
+     * @param name - Container name to inspect.
+     * @returns 'running' if active, 'stopped' if exists but not running,
+     *          'not_found' if the container doesn't exist.
+     */
+    static getContainerState(name: string): 'running' | 'stopped' | 'not_found';
+    /**
+     * Start a stopped container by name.
+     *
+     * @param name - Container name to start.
+     * @throws If the container cannot be started.
+     */
+    static startContainer(name: string): void;
+    /**
+     * Pull a Docker image and run a new container.
+     *
+     * @param opts.name    - Container name.
+     * @param opts.image   - Docker image (e.g. 'qdrant/qdrant:latest').
+     * @param opts.ports   - Port mappings (e.g. ['6333:6333', '6334:6334']).
+     * @param opts.volumes - Volume mounts (e.g. ['data-vol:/data']).
+     * @param opts.env     - Environment variables (e.g. { POSTGRES_PASSWORD: 'pw' }).
+     */
+    static pullAndRun(opts: {
+        name: string;
+        image: string;
+        ports: string[];
+        volumes: string[];
+        env?: Record<string, string>;
+    }): void;
+    /**
+     * Poll a health check URL until it returns 200 or timeout is reached.
+     * Checks every 500ms.
+     *
+     * @param url       - Health check endpoint (e.g. 'http://localhost:6333/healthz').
+     * @param timeoutMs - Maximum time to wait in milliseconds. @default 15000
+     * @returns True if the endpoint became healthy within the timeout.
+     */
+    static waitForHealthy(url: string, timeoutMs?: number): Promise<boolean>;
+    /**
+     * Get the mapped host port for a container's internal port.
+     * Useful when the host port was dynamically assigned.
+     *
+     * @param name         - Container name.
+     * @param internalPort - The container-internal port to look up.
+     * @returns The host port number, or null if not found.
+     */
+    static getHostPort(name: string, internalPort: number): number | null;
+}
+//# sourceMappingURL=DockerDetector.d.ts.map

package/dist/rag/setup/DockerDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DockerDetector.d.ts","sourceRoot":"","sources":["../../../src/rag/setup/DockerDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,qBAAa,cAAc;IACzB;;;;;OAKG;IACH,MAAM,CAAC,iBAAiB,IAAI,OAAO;IASnC;;;;;;OAMG;IACH,MAAM,CAAC,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW;IAc3E;;;;;OAKG;IACH,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIzC;;;;;;;;OAQG;IACH,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE;QACtB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAC9B,GAAG,IAAI;IAuBR;;;;;;;OAOG;WACU,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,SAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAc7E;;;;;;;OAOG;IACH,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CActE"}