@seanhogg/builderforce-memory 2026.9.29 → 2026.9.31

package/dist/retrieval/decay.js

@@ -0,0 +1,29 @@
+/**
+ * Recency decay — exponential half-life down-weighting of an older result's score.
+ *
+ * `score · e^(−λ·age)` with `λ = ln2 / halfLife`, so a result `halfLife` days old
+ * keeps half its score. The maths is here; deciding how old a result IS (a dated
+ * file name, an mtime, a `created_at` column) and which results never decay stays
+ * with the caller, because that is a property of its corpus.
+ *
+ * Pure and zero-dependency.
+ */
+/** The decay rate for a half-life in days; 0 (no decay) for a non-positive or non-finite half-life. */
+export function toDecayLambda(halfLifeDays) {
+    if (!Number.isFinite(halfLifeDays) || halfLifeDays <= 0)
+        return 0;
+    return Math.LN2 / halfLifeDays;
+}
+/** The factor in (0,1] a score is multiplied by at `ageInDays` (negative ages count as 0). */
+export function calculateTemporalDecayMultiplier(params) {
+    const lambda = toDecayLambda(params.halfLifeDays);
+    const clampedAge = Math.max(0, params.ageInDays);
+    if (lambda <= 0 || !Number.isFinite(clampedAge))
+        return 1;
+    return Math.exp(-lambda * clampedAge);
+}
+/** `score` decayed for its age. */
+export function applyTemporalDecayToScore(params) {
+    return params.score * calculateTemporalDecayMultiplier(params);
+}
+//# sourceMappingURL=decay.js.map

package/dist/retrieval/decay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decay.js","sourceRoot":"","sources":["../../src/retrieval/decay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,uGAAuG;AACvG,MAAM,UAAU,aAAa,CAAC,YAAoB;IAC9C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,YAAY,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAClE,OAAO,IAAI,CAAC,GAAG,GAAG,YAAY,CAAC;AACnC,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,gCAAgC,CAAC,MAAmD;IAChG,MAAM,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAClD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;IACjD,IAAI,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC;QAAE,OAAO,CAAC,CAAC;IAC1D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC;AAC1C,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,yBAAyB,CAAC,MAAkE;IACxG,OAAO,MAAM,CAAC,KAAK,GAAG,gCAAgC,CAAC,MAAM,CAAC,CAAC;AACnE,CAAC"}

package/dist/retrieval/fusion.d.ts

@@ -1,12 +1,9 @@
 /**
- * Rank fusion + diversity reranking.
- *
- *   • Reciprocal Rank Fusion (RRF) merges the dense (vector) and sparse (BM25)
- *     rankings into one list without needing the two score scales to be
- *     commensurable — it fuses on RANK, not raw score. This is the standard,
- *     parameter-light way to combine hybrid retrieval signals.
- *   • Maximal Marginal Relevance (MMR) reranks the fused list to trade off
- *     relevance against novelty, so the top-k isn't five near-duplicate chunks.
+ * Reciprocal Rank Fusion (RRF) — merges rankings (dense vector, sparse BM25, …) into
+ * one list without needing their score scales to be commensurable: it fuses on
+ * RANK, not raw score. The standard, parameter-light way to combine hybrid signals.
+ * Score-based fusion lives in {@link ./weightedFusion}; diversity reranking in
+ * {@link ./mmr}.
  *
  * Pure and zero-dependency.
  */
@@ -20,21 +17,18 @@ export interface FusedHit {
     id: string;
     score: number;
 }
+/** The canonical TREC damping constant for {@link rrfTerm}. */
+export declare const RRF_DEFAULT_K = 60;
+/**
+ * One list's RRF contribution for the item at zero-based `rank`: `1 / (k + rank + 1)`.
+ * Exported for a ranker that blends the rank signal into a score of its own rather
+ * than fusing whole lists.
+ */
+export declare function rrfTerm(rank: number, k?: number): number;
 /**
  * Reciprocal Rank Fusion over any number of ranked lists.
  * score(d) = Σ_lists weight / (k + rank(d)).  `k` (default 60) damps the
  * contribution of low-ranked items; the canonical TREC value.
  */
 export declare function reciprocalRankFusion(lists: RankedList[], k?: number): FusedHit[];
-export interface MmrCandidate {
-    id: string;
-    vector: Float32Array;
-}
-/**
- * Maximal Marginal Relevance rerank. Greedily selects up to `topK` candidates,
- * each step maximising `λ·sim(query, d) − (1−λ)·max sim(d, already-selected)`.
- * λ=1 is pure relevance; lower λ injects diversity. Candidates without vectors
- * should be filtered out by the caller (they cannot be MMR-scored).
- */
-export declare function maximalMarginalRelevance(queryVec: Float32Array, candidates: MmrCandidate[], topK: number, lambda?: number): string[];
 //# sourceMappingURL=fusion.d.ts.map

package/dist/retrieval/fusion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fusion.d.ts","sourceRoot":"","sources":["../../src/retrieval/fusion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,WAAW,UAAU;IACvB,wCAAwC;IACxC,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC,SAAK,GAAG,QAAQ,EAAE,CAW5E;AAED,MAAM,WAAW,YAAY;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,YAAY,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACpC,QAAQ,EAAE,YAAY,EACtB,UAAU,EAAE,YAAY,EAAE,EAC1B,IAAI,EAAE,MAAM,EACZ,MAAM,SAAM,GACb,MAAM,EAAE,CAsBV"}
+{"version":3,"file":"fusion.d.ts","sourceRoot":"","sources":["../../src/retrieval/fusion.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,UAAU;IACvB,wCAAwC;IACxC,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,+DAA+D;AAC/D,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,GAAE,MAAsB,GAAG,MAAM,CAEvE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC,SAAgB,GAAG,QAAQ,EAAE,CAWvF"}

package/dist/retrieval/fusion.js

@@ -1,64 +1,37 @@
 /**
- * Rank fusion + diversity reranking.
- *
- *   • Reciprocal Rank Fusion (RRF) merges the dense (vector) and sparse (BM25)
- *     rankings into one list without needing the two score scales to be
- *     commensurable — it fuses on RANK, not raw score. This is the standard,
- *     parameter-light way to combine hybrid retrieval signals.
- *   • Maximal Marginal Relevance (MMR) reranks the fused list to trade off
- *     relevance against novelty, so the top-k isn't five near-duplicate chunks.
+ * Reciprocal Rank Fusion (RRF) — merges rankings (dense vector, sparse BM25, …) into
+ * one list without needing their score scales to be commensurable: it fuses on
+ * RANK, not raw score. The standard, parameter-light way to combine hybrid signals.
+ * Score-based fusion lives in {@link ./weightedFusion}; diversity reranking in
+ * {@link ./mmr}.
  *
  * Pure and zero-dependency.
  */
-import { cosineSimilarity } from '../similarity/index.js';
+/** The canonical TREC damping constant for {@link rrfTerm}. */
+export const RRF_DEFAULT_K = 60;
+/**
+ * One list's RRF contribution for the item at zero-based `rank`: `1 / (k + rank + 1)`.
+ * Exported for a ranker that blends the rank signal into a score of its own rather
+ * than fusing whole lists.
+ */
+export function rrfTerm(rank, k = RRF_DEFAULT_K) {
+    return 1 / (k + rank + 1);
+}
 /**
  * Reciprocal Rank Fusion over any number of ranked lists.
  * score(d) = Σ_lists weight / (k + rank(d)).  `k` (default 60) damps the
  * contribution of low-ranked items; the canonical TREC value.
  */
-export function reciprocalRankFusion(lists, k = 60) {
+export function reciprocalRankFusion(lists, k = RRF_DEFAULT_K) {
     const acc = new Map();
     for (const list of lists) {
         const weight = list.weight ?? 1;
         list.ids.forEach((id, rank) => {
-            acc.set(id, (acc.get(id) ?? 0) + weight / (k + rank + 1));
+            acc.set(id, (acc.get(id) ?? 0) + weight * rrfTerm(rank, k));
         });
     }
     return [...acc.entries()]
         .map(([id, score]) => ({ id, score }))
         .sort((a, b) => b.score - a.score);
 }
-/**
- * Maximal Marginal Relevance rerank. Greedily selects up to `topK` candidates,
- * each step maximising `λ·sim(query, d) − (1−λ)·max sim(d, already-selected)`.
- * λ=1 is pure relevance; lower λ injects diversity. Candidates without vectors
- * should be filtered out by the caller (they cannot be MMR-scored).
- */
-export function maximalMarginalRelevance(queryVec, candidates, topK, lambda = 0.7) {
-    const remaining = [...candidates];
-    const selected = [];
-    const relevance = new Map();
-    for (const c of remaining)
-        relevance.set(c.id, cosineSimilarity(queryVec, c.vector));
-    while (selected.length < topK && remaining.length > 0) {
-        let bestIdx = 0;
-        let bestScore = -Infinity;
-        for (let i = 0; i < remaining.length; i++) {
-            const c = remaining[i];
-            let maxSimToSelected = 0;
-            for (const s of selected) {
-                const sim = cosineSimilarity(c.vector, s.vector);
-                if (sim > maxSimToSelected)
-                    maxSimToSelected = sim;
-            }
-            const mmr = lambda * relevance.get(c.id) - (1 - lambda) * maxSimToSelected;
-            if (mmr > bestScore) {
-                bestScore = mmr;
-                bestIdx = i;
-            }
-        }
-        selected.push(remaining.splice(bestIdx, 1)[0]);
-    }
-    return selected.map(s => s.id);
-}
 //# sourceMappingURL=fusion.js.map

package/dist/retrieval/fusion.js.map

@@ -1 +1 @@
-{"version":3,"file":"fusion.js","sourceRoot":"","sources":["../../src/retrieval/fusion.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fusion.js","sourceRoot":"","sources":["../../src/retrieval/fusion.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAcH,+DAA+D;AAC/D,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAC;AAEhC;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,IAAY,aAAa;IAC3D,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAmB,EAAE,CAAC,GAAG,aAAa;IACvE,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE;YAC1B,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAChE,CAAC,CAAC,CAAC;IACP,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC;SACpB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;SACrC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;AAC3C,CAAC"}

package/dist/retrieval/index.d.ts

@@ -1,16 +1,23 @@
 /**
- * Retrieval layer — chunking, BM25, rank fusion, and the HybridRetriever.
+ * Retrieval layer — chunking, BM25, rank and score fusion, MMR, recency decay, the
+ * similarity primitives they rest on, and the HybridRetriever.
  *
- * The classic RAG pieces the memory stack previously lacked (chunking, hybrid
- * dense+sparse search, reranking), implemented zero-dependency so they run in the
- * browser, Node, and the SSM runtime alike.
+ * Zero-dependency and engine-free: this is the `@seanhogg/builderforce-memory/retrieval`
+ * subpath, which a Cloudflare Worker, Node and the browser can all import without
+ * pulling the WebGPU engine. Every host ranks with THESE functions rather than a copy.
  */
+export { cosineSimilarity, jaccardSimilarity, tokenize } from '../similarity/index.js';
 export { chunkText } from './chunk.js';
 export type { Chunk, ChunkOptions } from './chunk.js';
 export { bm25Search, bm25Idf, bm25LengthNorm, bm25TermScore, BM25_DEFAULT_K1, BM25_DEFAULT_B } from './bm25.js';
 export type { Bm25Doc, Bm25Hit, Bm25Options, Bm25Tokenizer } from './bm25.js';
-export { reciprocalRankFusion, maximalMarginalRelevance } from './fusion.js';
-export type { RankedList, FusedHit, MmrCandidate } from './fusion.js';
+export { reciprocalRankFusion, rrfTerm, RRF_DEFAULT_K } from './fusion.js';
+export type { RankedList, FusedHit } from './fusion.js';
+export { mmrSelect, maximalMarginalRelevance, textMaximalMarginalRelevance } from './mmr.js';
+export type { MmrSelectOptions, MmrCandidate, TextMmrItem } from './mmr.js';
+export { DEFAULT_HYBRID_VECTOR_WEIGHT, DEFAULT_HYBRID_TEXT_WEIGHT, normalizeHybridWeights, hybridScore, bm25RankToScore, fuseHybridArms, } from './weightedFusion.js';
+export type { HybridWeights, HybridArmScores } from './weightedFusion.js';
+export { toDecayLambda, calculateTemporalDecayMultiplier, applyTemporalDecayToScore } from './decay.js';
 export { hybridRetrieve } from './HybridRetriever.js';
 export type { RetrievalCandidate, HybridQuery, HybridRetrieveOptions, HybridHit, } from './HybridRetriever.js';
 export { HnswIndex, denseSearch } from './hnsw.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChH,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE9E,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACR,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,SAAS,GACZ,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEvF,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChH,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE9E,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC3E,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,EAAE,SAAS,EAAE,wBAAwB,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAC;AAC7F,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5E,OAAO,EACH,4BAA4B,EAC5B,0BAA0B,EAC1B,sBAAsB,EACtB,WAAW,EACX,eAAe,EACf,cAAc,GACjB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE1E,OAAO,EAAE,aAAa,EAAE,gCAAgC,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAExG,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACR,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,SAAS,GACZ,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}

package/dist/retrieval/index.js

@@ -1,13 +1,18 @@
 /**
- * Retrieval layer — chunking, BM25, rank fusion, and the HybridRetriever.
+ * Retrieval layer — chunking, BM25, rank and score fusion, MMR, recency decay, the
+ * similarity primitives they rest on, and the HybridRetriever.
  *
- * The classic RAG pieces the memory stack previously lacked (chunking, hybrid
- * dense+sparse search, reranking), implemented zero-dependency so they run in the
- * browser, Node, and the SSM runtime alike.
+ * Zero-dependency and engine-free: this is the `@seanhogg/builderforce-memory/retrieval`
+ * subpath, which a Cloudflare Worker, Node and the browser can all import without
+ * pulling the WebGPU engine. Every host ranks with THESE functions rather than a copy.
  */
+export { cosineSimilarity, jaccardSimilarity, tokenize } from '../similarity/index.js';
 export { chunkText } from './chunk.js';
 export { bm25Search, bm25Idf, bm25LengthNorm, bm25TermScore, BM25_DEFAULT_K1, BM25_DEFAULT_B } from './bm25.js';
-export { reciprocalRankFusion, maximalMarginalRelevance } from './fusion.js';
+export { reciprocalRankFusion, rrfTerm, RRF_DEFAULT_K } from './fusion.js';
+export { mmrSelect, maximalMarginalRelevance, textMaximalMarginalRelevance } from './mmr.js';
+export { DEFAULT_HYBRID_VECTOR_WEIGHT, DEFAULT_HYBRID_TEXT_WEIGHT, normalizeHybridWeights, hybridScore, bm25RankToScore, fuseHybridArms, } from './weightedFusion.js';
+export { toDecayLambda, calculateTemporalDecayMultiplier, applyTemporalDecayToScore } from './decay.js';
 export { hybridRetrieve } from './HybridRetriever.js';
 export { HnswIndex, denseSearch } from './hnsw.js';
 //# sourceMappingURL=index.js.map

package/dist/retrieval/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGhH,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAG7E,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAQtD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEvF,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGhH,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG3E,OAAO,EAAE,SAAS,EAAE,wBAAwB,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAC;AAG7F,OAAO,EACH,4BAA4B,EAC5B,0BAA0B,EAC1B,sBAAsB,EACtB,WAAW,EACX,eAAe,EACf,cAAc,GACjB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,aAAa,EAAE,gCAAgC,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAExG,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAQtD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC"}

package/dist/retrieval/mmr.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Maximal Marginal Relevance — ONE greedy selection loop, two similarity bases.
+ *
+ * MMR reranks a relevance-ordered list so the top of it is not five near-duplicates:
+ * each step picks the candidate maximising `λ·relevance − (1−λ)·max sim(candidate,
+ * already-selected)`. λ=1 is pure relevance; lower λ buys diversity.
+ *
+ * What differs between callers is only what "similar" means:
+ *   • {@link maximalMarginalRelevance} — cosine over embedding vectors, relevance =
+ *     cosine to the query vector. For retrievers that hold vectors;
+ *   • {@link textMaximalMarginalRelevance} — Jaccard over word tokens, relevance =
+ *     the candidate's own score min-max normalised onto [0,1]. For retrievers that
+ *     only have text and a fused score (an FTS5 + sqlite-vec hybrid, say).
+ *
+ * Both run {@link mmrSelect}, so the selection rule itself exists once.
+ *
+ * Pure and zero-dependency.
+ */
+export interface MmrSelectOptions<T> {
+    /** Relevance of one candidate, on the same scale as {@link similarity}. */
+    relevance: (item: T) => number;
+    /** Similarity of two candidates. */
+    similarity: (a: T, b: T) => number;
+    /** 0 = maximum diversity, 1 = maximum relevance. Default 0.7. */
+    lambda?: number;
+    /** Stop after this many picks. Default: every candidate. */
+    topK?: number;
+    /**
+     * Breaks an exact MMR tie in favour of the higher value. Without it the earlier
+     * candidate wins, so input order decides.
+     */
+    tieScore?: (item: T) => number;
+}
+/** Greedy MMR selection. Returns the picked candidates in pick order. */
+export declare function mmrSelect<T>(items: readonly T[], opts: MmrSelectOptions<T>): T[];
+export interface MmrCandidate {
+    id: string;
+    vector: Float32Array;
+}
+/**
+ * Vector MMR. Selects up to `topK` candidates by cosine relevance to `queryVec`,
+ * penalising cosine similarity to what is already selected. Candidates without
+ * vectors should be filtered out by the caller (they cannot be MMR-scored).
+ */
+export declare function maximalMarginalRelevance(queryVec: Float32Array, candidates: MmrCandidate[], topK: number, lambda?: number): string[];
+export interface TextMmrItem {
+    id: string;
+    /** The candidate's fused relevance score (any scale — it is normalised here). */
+    score: number;
+    /** The text diversity is judged on. */
+    content: string;
+}
+/**
+ * Text MMR. Reorders every item, judging diversity by Jaccard similarity of word
+ * tokens, and relevance by the item's `score` min-max normalised onto [0,1] (all
+ * equal → 1). An exact tie goes to the higher raw score. `lambda` is clamped to
+ * [0,1]; at 1 this is a plain score sort.
+ */
+export declare function textMaximalMarginalRelevance<T extends TextMmrItem>(items: readonly T[], lambda?: number): T[];
+//# sourceMappingURL=mmr.d.ts.map

package/dist/retrieval/mmr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mmr.d.ts","sourceRoot":"","sources":["../../src/retrieval/mmr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IAC/B,2EAA2E;IAC3E,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;IAC/B,oCAAoC;IACpC,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC;IACnC,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;CAClC;AAED,yEAAyE;AACzE,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CA4BhF;AAED,MAAM,WAAW,YAAY;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,YAAY,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACpC,QAAQ,EAAE,YAAY,EACtB,UAAU,EAAE,YAAY,EAAE,EAC1B,IAAI,EAAE,MAAM,EACZ,MAAM,SAAM,GACb,MAAM,EAAE,CAOV;AAED,MAAM,WAAW,WAAW;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,SAAS,WAAW,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,MAAM,SAAM,GAAG,CAAC,EAAE,CAmB1G"}

package/dist/retrieval/mmr.js

@@ -0,0 +1,94 @@
+/**
+ * Maximal Marginal Relevance — ONE greedy selection loop, two similarity bases.
+ *
+ * MMR reranks a relevance-ordered list so the top of it is not five near-duplicates:
+ * each step picks the candidate maximising `λ·relevance − (1−λ)·max sim(candidate,
+ * already-selected)`. λ=1 is pure relevance; lower λ buys diversity.
+ *
+ * What differs between callers is only what "similar" means:
+ *   • {@link maximalMarginalRelevance} — cosine over embedding vectors, relevance =
+ *     cosine to the query vector. For retrievers that hold vectors;
+ *   • {@link textMaximalMarginalRelevance} — Jaccard over word tokens, relevance =
+ *     the candidate's own score min-max normalised onto [0,1]. For retrievers that
+ *     only have text and a fused score (an FTS5 + sqlite-vec hybrid, say).
+ *
+ * Both run {@link mmrSelect}, so the selection rule itself exists once.
+ *
+ * Pure and zero-dependency.
+ */
+import { cosineSimilarity, jaccardSimilarity, tokenize } from '../similarity/index.js';
+/** Greedy MMR selection. Returns the picked candidates in pick order. */
+export function mmrSelect(items, opts) {
+    const lambda = opts.lambda ?? 0.7;
+    const limit = Math.min(opts.topK ?? items.length, items.length);
+    const remaining = [...items];
+    const relevance = new Map();
+    for (const item of remaining)
+        relevance.set(item, opts.relevance(item));
+    const selected = [];
+    while (selected.length < limit && remaining.length > 0) {
+        let bestIdx = -1;
+        let bestScore = -Infinity;
+        for (let i = 0; i < remaining.length; i++) {
+            const candidate = remaining[i];
+            let maxSimToSelected = 0;
+            for (const s of selected) {
+                const sim = opts.similarity(candidate, s);
+                if (sim > maxSimToSelected)
+                    maxSimToSelected = sim;
+            }
+            const score = lambda * relevance.get(candidate) - (1 - lambda) * maxSimToSelected;
+            const wins = score > bestScore
+                || (score === bestScore && bestIdx >= 0 && opts.tieScore !== undefined
+                    && opts.tieScore(candidate) > opts.tieScore(remaining[bestIdx]));
+            if (wins) {
+                bestScore = score;
+                bestIdx = i;
+            }
+        }
+        if (bestIdx < 0)
+            break;
+        selected.push(remaining.splice(bestIdx, 1)[0]);
+    }
+    return selected;
+}
+/**
+ * Vector MMR. Selects up to `topK` candidates by cosine relevance to `queryVec`,
+ * penalising cosine similarity to what is already selected. Candidates without
+ * vectors should be filtered out by the caller (they cannot be MMR-scored).
+ */
+export function maximalMarginalRelevance(queryVec, candidates, topK, lambda = 0.7) {
+    return mmrSelect(candidates, {
+        relevance: (c) => cosineSimilarity(queryVec, c.vector),
+        similarity: (a, b) => cosineSimilarity(a.vector, b.vector),
+        lambda,
+        topK,
+    }).map((c) => c.id);
+}
+/**
+ * Text MMR. Reorders every item, judging diversity by Jaccard similarity of word
+ * tokens, and relevance by the item's `score` min-max normalised onto [0,1] (all
+ * equal → 1). An exact tie goes to the higher raw score. `lambda` is clamped to
+ * [0,1]; at 1 this is a plain score sort.
+ */
+export function textMaximalMarginalRelevance(items, lambda = 0.7) {
+    if (items.length <= 1)
+        return [...items];
+    const l = Math.max(0, Math.min(1, lambda));
+    if (l === 1)
+        return [...items].sort((a, b) => b.score - a.score);
+    const tokens = new Map();
+    for (const item of items)
+        tokens.set(item.id, new Set(tokenize(item.content)));
+    const tokensOf = (item) => tokens.get(item.id) ?? new Set(tokenize(item.content));
+    const scores = items.map((i) => i.score);
+    const min = Math.min(...scores);
+    const range = Math.max(...scores) - min;
+    return mmrSelect(items, {
+        relevance: (item) => (range === 0 ? 1 : (item.score - min) / range),
+        similarity: (a, b) => jaccardSimilarity(tokensOf(a), tokensOf(b)),
+        lambda: l,
+        tieScore: (item) => item.score,
+    });
+}
+//# sourceMappingURL=mmr.js.map

package/dist/retrieval/mmr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mmr.js","sourceRoot":"","sources":["../../src/retrieval/mmr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAkBvF,yEAAyE;AACzE,MAAM,UAAU,SAAS,CAAI,KAAmB,EAAE,IAAyB;IACvE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC;IAClC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAChE,MAAM,SAAS,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IAC7B,MAAM,SAAS,GAAG,IAAI,GAAG,EAAa,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,SAAS;QAAE,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;IAExE,MAAM,QAAQ,GAAQ,EAAE,CAAC;IACzB,OAAO,QAAQ,CAAC,MAAM,GAAG,KAAK,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrD,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC;QACjB,IAAI,SAAS,GAAG,CAAC,QAAQ,CAAC;QAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,MAAM,SAAS,GAAG,SAAS,CAAC,CAAC,CAAE,CAAC;YAChC,IAAI,gBAAgB,GAAG,CAAC,CAAC;YACzB,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;gBACvB,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;gBAC1C,IAAI,GAAG,GAAG,gBAAgB;oBAAE,gBAAgB,GAAG,GAAG,CAAC;YACvD,CAAC;YACD,MAAM,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,SAAS,CAAE,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,gBAAgB,CAAC;YACnF,MAAM,IAAI,GAAG,KAAK,GAAG,SAAS;mBACvB,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;uBAC/D,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAE,CAAC,CAAC,CAAC;YAC1E,IAAI,IAAI,EAAE,CAAC;gBAAC,SAAS,GAAG,KAAK,CAAC;gBAAC,OAAO,GAAG,CAAC,CAAC;YAAC,CAAC;QACjD,CAAC;QACD,IAAI,OAAO,GAAG,CAAC;YAAE,MAAM;QACvB,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,QAAQ,CAAC;AACpB,CAAC;AAOD;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CACpC,QAAsB,EACtB,UAA0B,EAC1B,IAAY,EACZ,MAAM,GAAG,GAAG;IAEZ,OAAO,SAAS,CAAC,UAAU,EAAE;QACzB,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC;QACtD,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QAC1D,MAAM;QACN,IAAI;KACP,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AACxB,CAAC;AAUD;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAAwB,KAAmB,EAAE,MAAM,GAAG,GAAG;IACjG,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;IACzC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3C,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAEjE,MAAM,MAAM,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC9C,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/E,MAAM,QAAQ,GAAG,CAAC,IAAO,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAErF,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,GAAG,CAAC;IAExC,OAAO,SAAS,CAAC,KAAK,EAAE;QACpB,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,KAAK,CAAC;QACnE,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;QACjE,MAAM,EAAE,CAAC;QACT,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK;KACjC,CAAC,CAAC;AACP,CAAC"}

package/dist/retrieval/weightedFusion.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Weighted-score fusion — the ONE formula for fusing a semantic arm with a lexical
+ * arm by SCORE, where {@link ./fusion reciprocalRankFusion} fuses by RANK.
+ *
+ * Score fusion is the choice when two different engines must rank the same way: an
+ * on-prem `sqlite-vec` cosine + FTS5/BM25 pair and a cloud pgvector cosine + ILIKE
+ * pair answer the same question, and a weighted sum of scores already on roughly
+ * [0,1] makes "recall ranks the same everywhere" a property of one function.
+ *
+ * Union semantics: a candidate found by only one arm scores 0 on the other rather
+ * than being dropped, because "the lexical arm did not match" is evidence about the
+ * query's wording, not about the candidate's relevance.
+ *
+ * Pure and zero-dependency.
+ */
+/** Weight on the semantic arm when a caller states none. */
+export declare const DEFAULT_HYBRID_VECTOR_WEIGHT = 0.7;
+/** Weight on the lexical arm when a caller states none. */
+export declare const DEFAULT_HYBRID_TEXT_WEIGHT = 0.3;
+export interface HybridWeights {
+    vectorWeight: number;
+    textWeight: number;
+}
+/**
+ * Renormalise a pair of weights so it sums to 1 — a fused score is only comparable
+ * across queries if the weights always sum the same. A degenerate pair (both zero
+ * or non-finite) falls back to the defaults.
+ *
+ * The pair is a RATIO, so only the lower bound is clamped: `(3, 1)` means "three
+ * parts semantic to one part lexical" and must come back as 0.75/0.25, not be
+ * capped into an even split. Normalisation is what bounds the result.
+ */
+export declare function normalizeHybridWeights(vectorWeight?: number, textWeight?: number): HybridWeights;
+/** One candidate's per-arm scores, both already normalised to roughly [0,1]. */
+export interface HybridArmScores {
+    vectorScore?: number;
+    textScore?: number;
+}
+/** The fused score for one candidate under the given (already normalised) weights. */
+export declare function hybridScore(scores: HybridArmScores, weights: HybridWeights): number;
+/**
+ * Map a BM25 rank (lower is better, unbounded — FTS5's `bm25()`) onto a (0,1]
+ * score so it can be summed with a cosine similarity. A non-finite rank is treated
+ * as very poor rather than as an error.
+ */
+export declare function bm25RankToScore(rank: number): number;
+/**
+ * Fuse two arms keyed by a caller-supplied id and return the candidates ordered
+ * best-first. `merge` builds the output row from the winning payload of each id;
+ * later duplicates of the same id keep the first payload seen (arm order decides).
+ */
+export declare function fuseHybridArms<TVector extends {
+    id: string;
+}, TText extends {
+    id: string;
+}, TOut>(params: {
+    vector: readonly TVector[];
+    text: readonly TText[];
+    vectorScoreOf: (row: TVector) => number;
+    textScoreOf: (row: TText) => number;
+    merge: (row: TVector | TText, score: number) => TOut;
+    weights?: Partial<HybridWeights>;
+}): TOut[];
+//# sourceMappingURL=weightedFusion.d.ts.map

package/dist/retrieval/weightedFusion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"weightedFusion.d.ts","sourceRoot":"","sources":["../../src/retrieval/weightedFusion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAChD,2DAA2D;AAC3D,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,aAAa,CAUhG;AAED,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAInF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EAAE,MAAM,EAAE;IACvG,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;IAC3B,IAAI,EAAE,SAAS,KAAK,EAAE,CAAC;IACvB,aAAa,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;IACxC,WAAW,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,MAAM,CAAC;IACpC,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrD,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;CACpC,GAAG,IAAI,EAAE,CAkBT"}

package/dist/retrieval/weightedFusion.js

@@ -0,0 +1,80 @@
+/**
+ * Weighted-score fusion — the ONE formula for fusing a semantic arm with a lexical
+ * arm by SCORE, where {@link ./fusion reciprocalRankFusion} fuses by RANK.
+ *
+ * Score fusion is the choice when two different engines must rank the same way: an
+ * on-prem `sqlite-vec` cosine + FTS5/BM25 pair and a cloud pgvector cosine + ILIKE
+ * pair answer the same question, and a weighted sum of scores already on roughly
+ * [0,1] makes "recall ranks the same everywhere" a property of one function.
+ *
+ * Union semantics: a candidate found by only one arm scores 0 on the other rather
+ * than being dropped, because "the lexical arm did not match" is evidence about the
+ * query's wording, not about the candidate's relevance.
+ *
+ * Pure and zero-dependency.
+ */
+/** Weight on the semantic arm when a caller states none. */
+export const DEFAULT_HYBRID_VECTOR_WEIGHT = 0.7;
+/** Weight on the lexical arm when a caller states none. */
+export const DEFAULT_HYBRID_TEXT_WEIGHT = 0.3;
+/**
+ * Renormalise a pair of weights so it sums to 1 — a fused score is only comparable
+ * across queries if the weights always sum the same. A degenerate pair (both zero
+ * or non-finite) falls back to the defaults.
+ *
+ * The pair is a RATIO, so only the lower bound is clamped: `(3, 1)` means "three
+ * parts semantic to one part lexical" and must come back as 0.75/0.25, not be
+ * capped into an even split. Normalisation is what bounds the result.
+ */
+export function normalizeHybridWeights(vectorWeight, textWeight) {
+    const clamp = (n, fallback) => typeof n === 'number' && Number.isFinite(n) ? Math.max(0, n) : fallback;
+    const v = clamp(vectorWeight, DEFAULT_HYBRID_VECTOR_WEIGHT);
+    const t = clamp(textWeight, DEFAULT_HYBRID_TEXT_WEIGHT);
+    const sum = v + t;
+    if (sum <= 0) {
+        return { vectorWeight: DEFAULT_HYBRID_VECTOR_WEIGHT, textWeight: DEFAULT_HYBRID_TEXT_WEIGHT };
+    }
+    return { vectorWeight: v / sum, textWeight: t / sum };
+}
+/** The fused score for one candidate under the given (already normalised) weights. */
+export function hybridScore(scores, weights) {
+    const v = Number.isFinite(scores.vectorScore) ? scores.vectorScore : 0;
+    const t = Number.isFinite(scores.textScore) ? scores.textScore : 0;
+    return weights.vectorWeight * v + weights.textWeight * t;
+}
+/**
+ * Map a BM25 rank (lower is better, unbounded — FTS5's `bm25()`) onto a (0,1]
+ * score so it can be summed with a cosine similarity. A non-finite rank is treated
+ * as very poor rather than as an error.
+ */
+export function bm25RankToScore(rank) {
+    const normalized = Number.isFinite(rank) ? Math.max(0, rank) : 999;
+    return 1 / (1 + normalized);
+}
+/**
+ * Fuse two arms keyed by a caller-supplied id and return the candidates ordered
+ * best-first. `merge` builds the output row from the winning payload of each id;
+ * later duplicates of the same id keep the first payload seen (arm order decides).
+ */
+export function fuseHybridArms(params) {
+    const weights = normalizeHybridWeights(params.weights?.vectorWeight, params.weights?.textWeight);
+    const byId = new Map();
+    for (const row of params.vector) {
+        byId.set(row.id, { row, scores: { vectorScore: params.vectorScoreOf(row), textScore: 0 } });
+    }
+    for (const row of params.text) {
+        const existing = byId.get(row.id);
+        if (existing)
+            existing.scores.textScore = params.textScoreOf(row);
+        else
+            byId.set(row.id, { row, scores: { vectorScore: 0, textScore: params.textScoreOf(row) } });
+    }
+    return [...byId.values()]
+        .map((entry) => {
+        const score = hybridScore(entry.scores, weights);
+        return { out: params.merge(entry.row, score), score };
+    })
+        .sort((a, b) => b.score - a.score)
+        .map((entry) => entry.out);
+}
+//# sourceMappingURL=weightedFusion.js.map

package/dist/retrieval/weightedFusion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"weightedFusion.js","sourceRoot":"","sources":["../../src/retrieval/weightedFusion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,4DAA4D;AAC5D,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAChD,2DAA2D;AAC3D,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAO9C;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,YAAqB,EAAE,UAAmB;IAC7E,MAAM,KAAK,GAAG,CAAC,CAAqB,EAAE,QAAgB,EAAU,EAAE,CAC9D,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC5E,MAAM,CAAC,GAAG,KAAK,CAAC,YAAY,EAAE,4BAA4B,CAAC,CAAC;IAC5D,MAAM,CAAC,GAAG,KAAK,CAAC,UAAU,EAAE,0BAA0B,CAAC,CAAC;IACxD,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IAClB,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,YAAY,EAAE,4BAA4B,EAAE,UAAU,EAAE,0BAA0B,EAAE,CAAC;IAClG,CAAC;IACD,OAAO,EAAE,YAAY,EAAE,CAAC,GAAG,GAAG,EAAE,UAAU,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC;AAC1D,CAAC;AAQD,sFAAsF;AACtF,MAAM,UAAU,WAAW,CAAC,MAAuB,EAAE,OAAsB;IACvE,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAE,MAAM,CAAC,WAAsB,CAAC,CAAC,CAAC,CAAC,CAAC;IACnF,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAE,MAAM,CAAC,SAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/E,OAAO,OAAO,CAAC,YAAY,GAAG,CAAC,GAAG,OAAO,CAAC,UAAU,GAAG,CAAC,CAAC;AAC7D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IACxC,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACnE,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAqE,MAOlG;IACG,MAAM,OAAO,GAAG,sBAAsB,CAAC,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACjG,MAAM,IAAI,GAAG,IAAI,GAAG,EAA6D,CAAC;IAClF,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAC9B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IAChG,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,QAAQ;YAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;;YAC7D,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;IACnG,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;SACpB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACX,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjD,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC;IAC1D,CAAC,CAAC;SACD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;SACjC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AACnC,CAAC"}

package/dist/similarity/index.d.ts

@@ -10,10 +10,12 @@ export declare function tokenize(text: string): string[];
 /** Jaccard similarity between two token sets: |A ∩ B| / |A ∪ B|. */
 export declare function jaccardSimilarity(a: Set<string>, b: Set<string>): number;
 /**
- * Cosine similarity between two vectors in the range [-1, 1] (0 when either is a
- * zero vector). Compares over the shorter length when lengths differ. Vectors
+ * Cosine similarity between two vectors in the range [-1, 1] (0 when either is empty
+ * or a zero vector). Compares over the shorter length when lengths differ. Vectors
  * from MambaSession.embed() are already L2-normalised — this reduces to a dot
- * product — but we normalise defensively for vectors from other sources.
+ * product — but we normalise defensively for vectors from other sources. Takes any
+ * numeric array, so a `Float32Array` embedding and a JSON-decoded `number[]` (a
+ * pgvector row, a KV entry) go through the same function.
  */
-export declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+export declare function cosineSimilarity(a: ArrayLike<number>, b: ArrayLike<number>): number;
 //# sourceMappingURL=index.d.ts.map

package/dist/similarity/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/similarity/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,oEAAoE;AACpE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAE/C;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CASxE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CAUzE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/similarity/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,oEAAoE;AACpE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAE/C;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CASxE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAUnF"}

package/dist/similarity/index.js

@@ -23,10 +23,12 @@ export function jaccardSimilarity(a, b) {
     return intersection / union;
 }
 /**
- * Cosine similarity between two vectors in the range [-1, 1] (0 when either is a
- * zero vector). Compares over the shorter length when lengths differ. Vectors
+ * Cosine similarity between two vectors in the range [-1, 1] (0 when either is empty
+ * or a zero vector). Compares over the shorter length when lengths differ. Vectors
  * from MambaSession.embed() are already L2-normalised — this reduces to a dot
- * product — but we normalise defensively for vectors from other sources.
+ * product — but we normalise defensively for vectors from other sources. Takes any
+ * numeric array, so a `Float32Array` embedding and a JSON-decoded `number[]` (a
+ * pgvector row, a KV entry) go through the same function.
  */
 export function cosineSimilarity(a, b) {
     const n = Math.min(a.length, b.length);