@framers/agentos 0.1.247 → 0.1.249

package/dist/memory/retrieval/hybrid/HybridRetriever.d.ts

@@ -0,0 +1,151 @@
+/**
+ * @file HybridRetriever.ts
+ * @description Hybrid BM25 + dense retrieval for memory-domain traces.
+ * Dense side uses {@link MemoryStore} (preserves 6-signal cognitive
+ * scoring). Sparse side uses a per-instance {@link BM25Index}. RRF
+ * merges by rank. Optional {@link RerankerService} runs over the
+ * merged pool.
+ *
+ * ## What this does
+ *
+ * Given a query, runs dense retrieval through `MemoryStore.query`
+ * (cognitive-scored traces) and sparse retrieval through an owned
+ * `BM25Index` (keyword-matched trace content). Fuses the two ranked
+ * lists via Reciprocal Rank Fusion, optionally reranks the merged
+ * pool with a neural cross-encoder, and returns a standard
+ * `CognitiveRetrievalResult` so downstream consumers (prompt
+ * assembly, bench adapters) don't change shape.
+ *
+ * ## Why a separate class, not a `CognitiveMemoryManager` option
+ *
+ * Keeps the existing manager retrieval path untouched (same reason
+ * as SessionRetriever in Step 2). MVP ships as opt-in.
+ *
+ * ## Rerank integration is mandatory-wired from the bench
+ *
+ * Per the Step 2 post-mortem (rerank-skip was the root cause of
+ * that step's RED verdict), Step 3 threads rerank from day 1 when
+ * the bench is configured with `--rerank cohere`. Callers outside
+ * the bench can pass `undefined` for `rerankerService` to skip
+ * rerank explicitly.
+ *
+ * ## Sparse-only documents are skipped in MVP
+ *
+ * A document that appears in `bm25.search` results but NOT in the
+ * dense over-fetch pool is skipped. Rationale: at the default
+ * over-fetch=3 and K=10 (30 dense candidates), a doc ranked top-30
+ * on sparse is very likely in dense's top-30 on any coherent query.
+ * Measured impact is expected to be negligible. If Tier A surfaces
+ * a meaningful drop rate, the fix is to add a
+ * `memoryStore.getTrace(id)` hydration path.
+ *
+ * @module agentos/memory/retrieval/hybrid/HybridRetriever
+ */
+import { BM25Index, type BM25Config } from '../../../rag/search/BM25Index.js';
+import type { MemoryStore } from '../store/MemoryStore.js';
+import type { RerankerService } from '../../../rag/reranking/RerankerService.js';
+import type { HydeRetriever } from '../../../rag/HydeRetriever.js';
+import type { CognitiveRetrievalResult, MemoryScope } from '../../core/types.js';
+import type { PADState } from '../../core/config.js';
+/**
+ * Options for constructing a {@link HybridRetriever}.
+ */
+export interface HybridRetrieverOptions {
+    memoryStore: MemoryStore;
+    /** BM25 config (k1, b, optional tokenizer). Defaults match BM25Index. */
+    bm25Config?: BM25Config;
+    /**
+     * Optional neural reranker. When provided, the merged pool is
+     * reranked before truncation. Passing the same reranker the
+     * baseline uses is the matched-ablation path.
+     */
+    rerankerService?: RerankerService;
+    /**
+     * Optional HyDE retriever for query expansion (Step 4). When set,
+     * each `retrieve()` call generates a hypothesis and uses it as the
+     * query for BOTH dense (`memoryStore.query`) and sparse
+     * (`bm25.search`). The reranker continues to use the ORIGINAL user
+     * query so it scores documents against real user intent, not the
+     * hypothesis. HyDE generation is non-critical — errors fall back
+     * to the raw query without aborting retrieval.
+     */
+    hydeRetriever?: HydeRetriever;
+    /**
+     * Step-6: enable split-on-ambiguous rerank refinement. When set to a
+     * value in (0, 1], the bottom fraction of traces by first-pass
+     * rerank score are split at sentence boundaries, rescored with a
+     * second rerank call (same query), and replaced by their better
+     * half ONLY IF the better half outscores the original. Monotonic.
+     *
+     * Default: undefined (no split, Step 3 behavior preserved).
+     */
+    splitAmbiguousThreshold?: number;
+    /** Default dense weight in RRF. @default 0.7 */
+    defaultDenseWeight?: number;
+    /** Default sparse weight in RRF. @default 0.3 */
+    defaultSparseWeight?: number;
+    /** Default RRF constant. @default 60 */
+    defaultRrfK?: number;
+}
+/**
+ * Per-call options for {@link HybridRetriever.retrieve}.
+ */
+export interface HybridRetrieveOptions {
+    /** Final truncation after merge + rerank. @default 10 */
+    recallTopK?: number;
+    /** Over-fetch multiplier for each side before merge. @default 3 */
+    overFetchMultiplier?: number;
+    denseWeight?: number;
+    sparseWeight?: number;
+    rrfK?: number;
+}
+/**
+ * Hybrid BM25 + dense retriever.
+ *
+ * @example
+ * ```ts
+ * const hybrid = new HybridRetriever({ memoryStore, rerankerService });
+ * // At ingest:
+ * hybrid.bm25.addDocument(trace.id, trace.content, { tag: 'bench-session:s-1' });
+ * // At query time:
+ * const result = await hybrid.retrieve(
+ *   'What did the user say about their mortgage?',
+ *   { valence: 0, arousal: 0, dominance: 0 },
+ *   { scope: 'user', scopeId: 'u1' },
+ *   { recallTopK: 10 },
+ * );
+ * ```
+ */
+export declare class HybridRetriever {
+    readonly bm25: BM25Index;
+    private readonly memoryStore;
+    private readonly rerankerService?;
+    private readonly hydeRetriever?;
+    private readonly splitAmbiguousThreshold?;
+    private readonly defaultDenseWeight;
+    private readonly defaultSparseWeight;
+    private readonly defaultRrfK;
+    constructor(opts: HybridRetrieverOptions);
+    retrieve(query: string, mood: PADState, scope: {
+        scope: MemoryScope;
+        scopeId: string;
+    }, options?: HybridRetrieveOptions): Promise<CognitiveRetrievalResult>;
+    /** Assemble the CognitiveRetrievalResult shape. */
+    private buildResult;
+    /**
+     * Step-6: split bottom-fraction traces by neural score, rescore the
+     * halves, replace a trace's content with its better half IFF the
+     * better half's neural score outranks the original's. Monotonic.
+     *
+     * Modifies `hydrated` in place: `trace.content` and `trace.retrievalScore`
+     * are updated for replaced traces. Returns a diagnostic summary.
+     */
+    private refineAmbiguous;
+    /**
+     * Split a string at the sentence boundary nearest its midpoint.
+     * Returns [firstHalf, secondHalf] or null if the string is too short
+     * or no valid boundary is found.
+     */
+    private splitAtMidpointSentence;
+}
+//# sourceMappingURL=HybridRetriever.d.ts.map

package/dist/memory/retrieval/hybrid/HybridRetriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HybridRetriever.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/hybrid/HybridRetriever.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAE9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EACV,wBAAwB,EACxB,WAAW,EAEZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,WAAW,CAAC;IACzB,yEAAyE;IACzE,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;;OAIG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;;;;;OAQG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,gDAAgD;IAChD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iDAAiD;IACjD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,eAAe;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAEzB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAkB;IACnD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAgB;IAC/C,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAC,CAAS;IAClD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,IAAI,EAAE,sBAAsB;IAWlC,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAC9C,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,wBAAwB,CAAC;IAkIpC,mDAAmD;IACnD,OAAO,CAAC,WAAW;IA2BnB;;;;;;;OAOG;YACW,eAAe;IAiE7B;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;CAwBhC"}

package/dist/memory/retrieval/hybrid/HybridRetriever.js

@@ -0,0 +1,287 @@
+/**
+ * @file HybridRetriever.ts
+ * @description Hybrid BM25 + dense retrieval for memory-domain traces.
+ * Dense side uses {@link MemoryStore} (preserves 6-signal cognitive
+ * scoring). Sparse side uses a per-instance {@link BM25Index}. RRF
+ * merges by rank. Optional {@link RerankerService} runs over the
+ * merged pool.
+ *
+ * ## What this does
+ *
+ * Given a query, runs dense retrieval through `MemoryStore.query`
+ * (cognitive-scored traces) and sparse retrieval through an owned
+ * `BM25Index` (keyword-matched trace content). Fuses the two ranked
+ * lists via Reciprocal Rank Fusion, optionally reranks the merged
+ * pool with a neural cross-encoder, and returns a standard
+ * `CognitiveRetrievalResult` so downstream consumers (prompt
+ * assembly, bench adapters) don't change shape.
+ *
+ * ## Why a separate class, not a `CognitiveMemoryManager` option
+ *
+ * Keeps the existing manager retrieval path untouched (same reason
+ * as SessionRetriever in Step 2). MVP ships as opt-in.
+ *
+ * ## Rerank integration is mandatory-wired from the bench
+ *
+ * Per the Step 2 post-mortem (rerank-skip was the root cause of
+ * that step's RED verdict), Step 3 threads rerank from day 1 when
+ * the bench is configured with `--rerank cohere`. Callers outside
+ * the bench can pass `undefined` for `rerankerService` to skip
+ * rerank explicitly.
+ *
+ * ## Sparse-only documents are skipped in MVP
+ *
+ * A document that appears in `bm25.search` results but NOT in the
+ * dense over-fetch pool is skipped. Rationale: at the default
+ * over-fetch=3 and K=10 (30 dense candidates), a doc ranked top-30
+ * on sparse is very likely in dense's top-30 on any coherent query.
+ * Measured impact is expected to be negligible. If Tier A surfaces
+ * a meaningful drop rate, the fix is to add a
+ * `memoryStore.getTrace(id)` hydration path.
+ *
+ * @module agentos/memory/retrieval/hybrid/HybridRetriever
+ */
+import { BM25Index } from '../../../rag/search/BM25Index.js';
+import { reciprocalRankFusion } from './reciprocalRankFusion.js';
+/**
+ * Hybrid BM25 + dense retriever.
+ *
+ * @example
+ * ```ts
+ * const hybrid = new HybridRetriever({ memoryStore, rerankerService });
+ * // At ingest:
+ * hybrid.bm25.addDocument(trace.id, trace.content, { tag: 'bench-session:s-1' });
+ * // At query time:
+ * const result = await hybrid.retrieve(
+ *   'What did the user say about their mortgage?',
+ *   { valence: 0, arousal: 0, dominance: 0 },
+ *   { scope: 'user', scopeId: 'u1' },
+ *   { recallTopK: 10 },
+ * );
+ * ```
+ */
+export class HybridRetriever {
+    constructor(opts) {
+        this.memoryStore = opts.memoryStore;
+        this.bm25 = new BM25Index(opts.bm25Config);
+        this.rerankerService = opts.rerankerService;
+        this.hydeRetriever = opts.hydeRetriever;
+        this.splitAmbiguousThreshold = opts.splitAmbiguousThreshold;
+        this.defaultDenseWeight = opts.defaultDenseWeight ?? 0.7;
+        this.defaultSparseWeight = opts.defaultSparseWeight ?? 0.3;
+        this.defaultRrfK = opts.defaultRrfK ?? 60;
+    }
+    async retrieve(query, mood, scope, options = {}) {
+        const startTime = Date.now();
+        const recallTopK = options.recallTopK ?? 10;
+        const overFetchMultiplier = options.overFetchMultiplier ?? 3;
+        const overFetchTopK = recallTopK * overFetchMultiplier;
+        const wDense = options.denseWeight ?? this.defaultDenseWeight;
+        const wSparse = options.sparseWeight ?? this.defaultSparseWeight;
+        const rrfK = options.rrfK ?? this.defaultRrfK;
+        // HyDE expansion (Step 4): when a hydeRetriever is attached,
+        // generate a hypothetical answer and use it as the query for BOTH
+        // dense and sparse sides. The reranker (below) keeps the ORIGINAL
+        // query so it scores documents against the user's real intent,
+        // not the hypothesis. Errors are non-critical — fall back to raw.
+        let effectiveQuery = query;
+        let hypothesisDiagnostic;
+        if (this.hydeRetriever) {
+            try {
+                const hypo = await this.hydeRetriever.generateHypothesis(query);
+                if (hypo.hypothesis && hypo.hypothesis.trim().length > 0) {
+                    effectiveQuery = hypo.hypothesis;
+                    hypothesisDiagnostic = hypo.hypothesis.slice(0, 120);
+                }
+            }
+            catch {
+                // HyDE generation failed — raw query fallback.
+            }
+        }
+        // Dense side: use MemoryStore.query so we keep the 6-signal
+        // cognitive scoring (strength, recency, etc.) — matches baseline.
+        const { scored: denseScored, timings: denseTimings } = await this.memoryStore.query(effectiveQuery, mood, { topK: overFetchTopK, scopes: [scope] });
+        // Sparse side: BM25 over the per-instance index.
+        const sparseResults = this.bm25.search(effectiveQuery, overFetchTopK);
+        // Fallback: empty BM25 index or zero sparse hits => dense-only
+        // with explicit escalation diagnostic.
+        if (sparseResults.length === 0) {
+            return this.buildResult(denseScored.slice(0, recallTopK), {
+                escalations: ['hybrid-retriever:sparse-empty'],
+                candidatesScanned: denseScored.length,
+                vectorSearchMs: denseTimings.vectorSearchMs,
+                scoringMs: denseTimings.scoringMs,
+                totalMs: Date.now() - startTime,
+                hypothesis: hypothesisDiagnostic,
+            });
+        }
+        // Build 1-based ranked lists for RRF.
+        const denseRanked = denseScored.map((t, i) => ({ id: t.id, rank: i + 1 }));
+        const sparseRanked = sparseResults.map((r, i) => ({ id: r.id, rank: i + 1 }));
+        const merged = reciprocalRankFusion(denseRanked, sparseRanked, {
+            denseWeight: wDense,
+            sparseWeight: wSparse,
+            k: rrfK,
+        });
+        // Hydrate: resolve each RRFResult.id to the ScoredMemoryTrace from
+        // the dense side. Skip sparse-only docs (see file docstring).
+        const denseById = new Map(denseScored.map((t) => [t.id, t]));
+        const hydrated = [];
+        for (const m of merged) {
+            const trace = denseById.get(m.id);
+            if (trace) {
+                hydrated.push(trace);
+            }
+            // MVP: sparse-only docs (not in denseById) are skipped.
+        }
+        // Optional rerank: same 0.7 cognitive + 0.3 neural blend as baseline.
+        let splitDiagnostic;
+        if (this.rerankerService && hydrated.length > 0) {
+            try {
+                const rerankerOutput = await this.rerankerService.rerank({
+                    query,
+                    documents: hydrated.map((t) => ({
+                        id: t.id,
+                        content: t.content,
+                        originalScore: t.retrievalScore,
+                    })),
+                }, { topN: hydrated.length });
+                const neuralScores = new Map(rerankerOutput.results.map((r) => [r.id, r.relevanceScore]));
+                for (const trace of hydrated) {
+                    const neural = neuralScores.get(trace.id);
+                    if (neural !== undefined) {
+                        trace.retrievalScore = 0.7 * trace.retrievalScore + 0.3 * neural;
+                    }
+                }
+                // Step-6: split-on-ambiguous refinement.
+                if (this.splitAmbiguousThreshold !== undefined &&
+                    this.splitAmbiguousThreshold > 0 &&
+                    hydrated.length > 0) {
+                    splitDiagnostic = await this.refineAmbiguous(hydrated, neuralScores, query, this.splitAmbiguousThreshold);
+                }
+                hydrated.sort((a, b) => b.retrievalScore - a.retrievalScore);
+            }
+            catch {
+                // Reranker errors are non-critical: keep RRF ordering.
+            }
+        }
+        // Truncate to recallTopK.
+        const truncated = hydrated.slice(0, recallTopK);
+        return this.buildResult(truncated, {
+            candidatesScanned: denseScored.length + sparseResults.length,
+            vectorSearchMs: denseTimings.vectorSearchMs,
+            scoringMs: denseTimings.scoringMs,
+            totalMs: Date.now() - startTime,
+            hypothesis: hypothesisDiagnostic,
+            splitOnAmbiguous: splitDiagnostic,
+        });
+    }
+    /** Assemble the CognitiveRetrievalResult shape. */
+    buildResult(retrieved, d) {
+        return {
+            retrieved,
+            partiallyRetrieved: [],
+            diagnostics: {
+                candidatesScanned: d.candidatesScanned,
+                vectorSearchTimeMs: d.vectorSearchMs,
+                scoringTimeMs: d.scoringMs,
+                totalTimeMs: d.totalMs,
+                ...(d.escalations ? { escalations: d.escalations } : {}),
+                ...(d.hypothesis ? { hyde: { hypothesis: d.hypothesis } } : {}),
+                ...(d.splitOnAmbiguous ? { splitOnAmbiguous: d.splitOnAmbiguous } : {}),
+            },
+        };
+    }
+    /**
+     * Step-6: split bottom-fraction traces by neural score, rescore the
+     * halves, replace a trace's content with its better half IFF the
+     * better half's neural score outranks the original's. Monotonic.
+     *
+     * Modifies `hydrated` in place: `trace.content` and `trace.retrievalScore`
+     * are updated for replaced traces. Returns a diagnostic summary.
+     */
+    async refineAmbiguous(hydrated, neuralScores, query, threshold) {
+        const replacedIds = [];
+        const sortedByNeural = hydrated
+            .map((t) => ({ trace: t, neural: neuralScores.get(t.id) ?? 0 }))
+            .sort((a, b) => a.neural - b.neural);
+        const candidateCount = Math.ceil(hydrated.length * threshold);
+        const candidates = sortedByNeural.slice(0, candidateCount);
+        const splits = [];
+        for (const { trace, neural } of candidates) {
+            const halves = this.splitAtMidpointSentence(trace.content);
+            if (!halves)
+                continue;
+            splits.push({
+                traceId: trace.id,
+                halfAId: `${trace.id}::a`,
+                halfBId: `${trace.id}::b`,
+                halfA: halves[0],
+                halfB: halves[1],
+                originalNeural: neural,
+            });
+        }
+        if (splits.length === 0) {
+            return { threshold, candidateCount, replacedIds };
+        }
+        const halfDocs = splits.flatMap((s) => [
+            { id: s.halfAId, content: s.halfA },
+            { id: s.halfBId, content: s.halfB },
+        ]);
+        let halfScores;
+        try {
+            const halfOut = await this.rerankerService.rerank({ query, documents: halfDocs }, { topN: halfDocs.length });
+            halfScores = new Map(halfOut.results.map((r) => [r.id, r.relevanceScore]));
+        }
+        catch {
+            return { threshold, candidateCount, replacedIds };
+        }
+        const traceById = new Map(hydrated.map((t) => [t.id, t]));
+        for (const s of splits) {
+            const a = halfScores.get(s.halfAId) ?? -Infinity;
+            const b = halfScores.get(s.halfBId) ?? -Infinity;
+            const winningScore = Math.max(a, b);
+            if (winningScore <= s.originalNeural)
+                continue;
+            const winningText = a >= b ? s.halfA : s.halfB;
+            const trace = traceById.get(s.traceId);
+            if (!trace)
+                continue;
+            trace.content = winningText;
+            trace.retrievalScore += 0.3 * (winningScore - s.originalNeural);
+            replacedIds.push(s.traceId);
+        }
+        return { threshold, candidateCount, replacedIds };
+    }
+    /**
+     * Split a string at the sentence boundary nearest its midpoint.
+     * Returns [firstHalf, secondHalf] or null if the string is too short
+     * or no valid boundary is found.
+     */
+    splitAtMidpointSentence(text) {
+        if (text.length < 50)
+            return null;
+        const mid = Math.floor(text.length / 2);
+        const window = Math.floor(text.length * 0.4);
+        const lo = Math.max(0, mid - window);
+        const hi = Math.min(text.length, mid + window);
+        for (let offset = 0; offset <= window; offset++) {
+            for (const sign of [-1, 1]) {
+                const i = mid + sign * offset;
+                if (i < lo || i > hi)
+                    continue;
+                if (i > 0 &&
+                    i < text.length - 1 &&
+                    /[.!?]/.test(text[i]) &&
+                    /\s/.test(text[i + 1])) {
+                    return [text.slice(0, i + 1).trim(), text.slice(i + 1).trim()];
+                }
+            }
+        }
+        const spaceIdx = text.indexOf(' ', mid);
+        if (spaceIdx === -1 || spaceIdx >= text.length - 1)
+            return null;
+        return [text.slice(0, spaceIdx).trim(), text.slice(spaceIdx + 1).trim()];
+    }
+}
+//# sourceMappingURL=HybridRetriever.js.map

package/dist/memory/retrieval/hybrid/HybridRetriever.js.map

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

package/dist/memory/retrieval/hybrid/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @file index.ts
+ * @description Barrel exports for hybrid BM25 + dense retrieval
+ * (Step 3 of the RAG stack sequenced rollout).
+ *
+ * @module agentos/memory/retrieval/hybrid
+ */
+export { HybridRetriever } from './HybridRetriever.js';
+export type { HybridRetrieverOptions, HybridRetrieveOptions, } from './HybridRetriever.js';
+export { reciprocalRankFusion } from './reciprocalRankFusion.js';
+export type { RankedDoc, RRFOptions, RRFResult, } from './reciprocalRankFusion.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/memory/retrieval/hybrid/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/hybrid/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EACV,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,YAAY,EACV,SAAS,EACT,UAAU,EACV,SAAS,GACV,MAAM,2BAA2B,CAAC"}

package/dist/memory/retrieval/hybrid/index.js

@@ -0,0 +1,10 @@
+/**
+ * @file index.ts
+ * @description Barrel exports for hybrid BM25 + dense retrieval
+ * (Step 3 of the RAG stack sequenced rollout).
+ *
+ * @module agentos/memory/retrieval/hybrid
+ */
+export { HybridRetriever } from './HybridRetriever.js';
+export { reciprocalRankFusion } from './reciprocalRankFusion.js';
+//# sourceMappingURL=index.js.map

package/dist/memory/retrieval/hybrid/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/hybrid/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAMvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/memory/retrieval/hybrid/reciprocalRankFusion.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @file reciprocalRankFusion.ts
+ * @description Rank-based fusion of two ranked document lists using
+ * the Reciprocal Rank Fusion (RRF) algorithm (Cormack et al. 2009).
+ *
+ * ## What this does
+ *
+ * Takes two 1-based ranked lists of document ids (one from dense
+ * retrieval, one from sparse retrieval) and merges them into a single
+ * ranked list via:
+ *
+ * ```
+ * score(d) = w_dense / (k + rank_dense(d)) + w_sparse / (k + rank_sparse(d))
+ * ```
+ *
+ * Missing ranks (a doc appearing on only one side) contribute zero
+ * from the other side.
+ *
+ * ## Why rank-based (not score-based)
+ *
+ * Dense scorers (cosine similarity, cognitive composites) and sparse
+ * scorers (BM25) produce values on different scales with different
+ * distributions. Score-weighted fusion requires calibration; rank
+ * fusion sidesteps this entirely. Published RAG literature
+ * consistently prefers RRF over weighted-sum for heterogeneous
+ * retrievers.
+ *
+ * ## Stable ordering
+ *
+ * When two documents have identical RRF scores, they are ordered by
+ * id ascending. Deterministic across process restarts.
+ *
+ * @module agentos/memory/retrieval/hybrid/reciprocalRankFusion
+ */
+/**
+ * One document's position in a ranked retrieval result.
+ */
+export interface RankedDoc {
+    id: string;
+    /** 1-based rank. First result has rank 1. */
+    rank: number;
+}
+/**
+ * Options for {@link reciprocalRankFusion}.
+ */
+export interface RRFOptions {
+    /** Weight on the dense-side rank contribution. Default 0.7. */
+    denseWeight?: number;
+    /** Weight on the sparse-side rank contribution. Default 0.3. */
+    sparseWeight?: number;
+    /**
+     * RRF smoothing constant. Larger k flattens rank differences.
+     * Default 60 per Cormack et al. 2009.
+     */
+    k?: number;
+}
+/**
+ * One merged result from {@link reciprocalRankFusion}.
+ */
+export interface RRFResult {
+    id: string;
+    /** Fused score; higher = more relevant. */
+    score: number;
+    /** Rank in the dense list (undefined if doc was sparse-only). */
+    denseRank?: number;
+    /** Rank in the sparse list (undefined if doc was dense-only). */
+    sparseRank?: number;
+}
+/**
+ * Merge two ranked retrieval results via Reciprocal Rank Fusion.
+ *
+ * @param denseRanked - 1-based ranked list from dense retrieval.
+ * @param sparseRanked - 1-based ranked list from sparse retrieval.
+ * @param options - {@link RRFOptions}; defaults to w_dense=0.7, w_sparse=0.3, k=60.
+ * @returns Merged results sorted by fused score descending, stable
+ *          tiebreak by id ascending.
+ *
+ * @example
+ * ```ts
+ * const dense = [{ id: 'a', rank: 1 }, { id: 'b', rank: 2 }];
+ * const sparse = [{ id: 'b', rank: 1 }, { id: 'c', rank: 2 }];
+ * const merged = reciprocalRankFusion(dense, sparse);
+ * // => [{ id: 'b', score: 0.0162, denseRank: 2, sparseRank: 1 }, ...]
+ * ```
+ */
+export declare function reciprocalRankFusion(denseRanked: RankedDoc[], sparseRanked: RankedDoc[], options?: RRFOptions): RRFResult[];
+//# sourceMappingURL=reciprocalRankFusion.d.ts.map

package/dist/memory/retrieval/hybrid/reciprocalRankFusion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reciprocalRankFusion.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/hybrid/reciprocalRankFusion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,SAAS,EAAE,EACxB,YAAY,EAAE,SAAS,EAAE,EACzB,OAAO,GAAE,UAAe,GACvB,SAAS,EAAE,CAoCb"}