feat(rag): add MMR (Maximal Marginal Relevance) diversity strategy (#163)

* feat(rag): add MMR (Maximal Marginal Relevance) diversity strategy

- new MmrStrategy (post-retrieval), greedily selects chunks balancing
  relevance (context.scores) against similarity to already-selected
  chunks, so near-duplicates (e.g. overlapping parent/child chunks)
  don't crowd out distinct context
- lambda (relevance/diversity balance, default 0.5) and topK configurable
- extract cosineSimilarity as a shared utils/cosine-similarity.ts,
  used by both MmrStrategy and HybridVectorStore (previously inline)

Closes #133

* fix(rag): address review feedback on PR #163

- MmrStrategy: validate topK (non-negative integer) and lambda (finite,
  in [0, 1]) at construction instead of accepting arbitrary values
- MmrStrategy: initialize maxSimToSelected to -Infinity instead of 0, so
  a genuinely negative cosine similarity (anti-correlated embeddings)
  is not clamped away, matching the documented MMR formula
- cosineSimilarity: add @PARAM a/@PARAM b JSDoc
- docs: clarify that chunks without an embedding still participate in
  MMR selection via their relevance score, they only skip the diversity
  comparison; only an entirely embedding-free set passes through unranked

Not changed: Njent's suggestion to prune context.scores to only the
selected chunk IDs. RerankerStrategy already returns the full scores map
after slicing chunks to topK; changing MmrStrategy alone would be an
inconsistent, one-off deviation from that existing convention.

Author: irzix

.changeset/mmr-diversity-strategy.md

@@ -0,0 +1,5 @@
+---
+"@nestjs-agentic/rag": minor
+---
+
+Add `MmrStrategy`, a post-retrieval Maximal Marginal Relevance diversity strategy that reduces near-duplicate chunks in retrieved context. Extract `cosineSimilarity` as a shared utility, used by both `MmrStrategy` and `HybridVectorStore`. Closes #133.

apps/landing/content/docs/rag/retrieval-strategies.mdx

@@ -16,6 +16,20 @@ Blends a document-level global embedding into each chunk vector to preserve full
 ### 3. `ParentChildHydrationStrategy`
 Works with chunks produced by `ParentChildSplitter`: indexes small sub-chunks (methods, paragraphs) for high vector search precision, but hydrates the full parent text (carried in `chunk.metadata.parentText`) when constructing the final context prompt.
 
+### 4. `MmrStrategy`
+A post-retrieval diversity strategy implementing Maximal Marginal Relevance: greedily selects chunks that are relevant to the query but dissimilar to chunks already selected, so near-duplicate results (e.g. overlapping parent/child chunks) don't crowd out distinct context.
+
+```typescript
+import { MmrStrategy } from '@nestjs-agentic/rag';
+
+const mmr = new MmrStrategy({
+  topK: 5,
+  lambda: 0.5, // 1 = pure relevance, 0 = pure diversity
+});
+```
+
+Relevance comes from `context.scores` (populated by `RAGPipeline` during retrieval). Chunks without an `embedding` still participate in MMR selection using their relevance score, they just skip the diversity comparison against other chunks. If no chunk in the set has an embedding at all, MMR has no diversity signal to work with and passes the incoming order through, capped at `topK`.
+
 Strategies aren't passed to `KnowledgeBase` directly — they're registered on a `RAGPipeline`, which runs pre-retrieval strategies, retrieves via the `KnowledgeBase`, then runs post-retrieval strategies:
 
 ```typescript

docs/ARCHITECTURE.md

@@ -177,6 +177,7 @@ All stores implement the shared `AgentMemoryStore` interface (`save(record)` / `
 * **Hybrid Retrieval (`HybridVectorStore`)**: Combines dense cosine-similarity vector search with a real BM25 sparse keyword score (IDF-weighted, `k1`/`b` length-normalization, incremental corpus statistics maintained on `addChunks`/`deleteChunk`). Fusion strategy is configurable via `fusionMethod`: `'weighted'` (default) blends max-normalized raw scores by `vectorWeight`; `'rrf'` combines the two rankers' rank positions via Reciprocal Rank Fusion (`reciprocalRankFusion`, smoothing constant `rrfK`, default `60`), avoiding cross-scale score normalization.
 * **Relational Traversal (`GraphRAGStrategy` + `InMemoryKnowledgeGraphProvider`)**: Traverses a manually or programmatically populated entity-relationship graph (imports, callers, inheritance) via BFS sub-graph queries, boosting chunks that mention matched entities.
 * **Pluggable Reranking (`RerankerStrategy`)**: A post-retrieval hook accepting any custom `rerankFn`, with built-in `createCohereRerankProvider`/`createVoyageRerankProvider` factories, a `minScore` cutoff to drop low-relevance chunks outright, and an observable `onRerankFailure`/`onRerankFailureMode` (`'fallback'` | `'throw'`) for when `rerankFn` fails, instead of silently degrading to term-overlap scoring.
+* **Diversity Selection (`MmrStrategy`)**: A post-retrieval Maximal Marginal Relevance strategy that greedily balances relevance (`context.scores`) against similarity to already-selected chunks (via a shared `cosineSimilarity` utility), reducing near-duplicate chunks (e.g. overlapping parent/child sections) crowding out distinct context. Tunable via `lambda` (relevance/diversity balance, default `0.5`) and `topK`.
 
 ---
 

docs/ROADMAP.md

@@ -153,7 +153,7 @@ Goal: bring `@nestjs-agentic/rag`'s retrieval and reranking up to what its own d
 - [x] Implement real Reciprocal Rank Fusion (RRF) for combining dense and sparse result lists ([#130](https://github.com/irzix/nestjs-agentic/issues/130)).
 - [x] Replace `HybridVectorStore`'s term-frequency-only sparse score with real BM25 (IDF, k1/b saturation) ([#131](https://github.com/irzix/nestjs-agentic/issues/131)).
 - [x] Ship built-in reranker provider adapters (Cohere, Voyage) and a `minScore` cutoff ([#132](https://github.com/irzix/nestjs-agentic/issues/132)).
-- [ ] Add an MMR (Maximal Marginal Relevance) diversity strategy to reduce near-duplicate chunks in context ([#133](https://github.com/irzix/nestjs-agentic/issues/133)).
+- [x] Add an MMR (Maximal Marginal Relevance) diversity strategy to reduce near-duplicate chunks in context ([#133](https://github.com/irzix/nestjs-agentic/issues/133)).
 - [x] Fix `HybridVectorStore.addChunks` to embed via batched `embedDocuments` instead of one `embedQuery` call per chunk ([#134](https://github.com/irzix/nestjs-agentic/issues/134)).
 - [ ] Add an embedding cache (in-memory LRU, pluggable Redis backend) wrapping any `EmbeddingProvider` ([#134](https://github.com/irzix/nestjs-agentic/issues/134)).
 

packages/rag/src/index.ts

@@ -19,6 +19,8 @@ export * from './strategies/late-chunking.strategy';
 export * from './strategies/parent-child-hydration.strategy';
 export * from './strategies/contextual-compression.strategy';
 export * from './strategies/reranker.strategy';
+export * from './strategies/mmr.strategy';
+export * from './utils/cosine-similarity';
 export * from './strategies/graph-rag.strategy';
 export * from './strategies/graph-dependency.strategy';
 export * from './strategies/u-shaped-context.strategy';

packages/rag/src/stores/hybrid-vector.store.ts

@@ -3,6 +3,7 @@ import type { DocumentChunk } from '../interfaces/document.interface';
 import type { EmbeddingProvider } from '../interfaces/embedding.interface';
 import type { ScoredDocumentChunk, VectorStoreAdapter } from '../interfaces/vector-store.interface';
 import { reciprocalRankFusion } from '../utils/rrf-fusion';
+import { cosineSimilarity } from '../utils/cosine-similarity';
 
 /**
  * Options for configuring HybridVectorStore.
@@ -311,19 +312,7 @@ export class HybridVectorStore implements SemanticStoreProvider, VectorStoreAdap
     const rawScores = chunksToSearch.map((chunk) => {
       const bm25Score = this.bm25Score(chunk.id, queryTermCounts);
 
-      let vectorScore = 0;
-      if (queryVector && chunk.embedding && queryVector.length === chunk.embedding.length) {
-        let dotProduct = 0;
-        let normA = 0;
-        let normB = 0;
-        for (let i = 0; i < queryVector.length; i++) {
-          dotProduct += queryVector[i] * chunk.embedding[i];
-          normA += queryVector[i] * queryVector[i];
-          normB += chunk.embedding[i] * chunk.embedding[i];
-        }
-        const denominator = Math.sqrt(normA) * Math.sqrt(normB);
-        vectorScore = denominator > 0 ? dotProduct / denominator : 0;
-      }
+      const vectorScore = queryVector && chunk.embedding ? cosineSimilarity(queryVector, chunk.embedding) : 0;
 
       return { chunk, bm25Score, vectorScore };
     });

packages/rag/src/strategies/mmr.strategy.ts

@@ -0,0 +1,115 @@
+import type { DocumentChunk } from '../interfaces/document.interface';
+import type { RAGContext, RAGStrategy } from '../interfaces/strategy.interface';
+import { cosineSimilarity } from '../utils/cosine-similarity';
+
+/**
+ * Options for configuring MmrStrategy.
+ */
+export interface MmrStrategyOptions {
+  /** Maximum number of chunks to select. Default: `5` */
+  topK?: number;
+
+  /**
+   * Balances relevance to the query against diversity from already-selected
+   * chunks: `1` is pure relevance (no diversity), `0` is pure diversity
+   * (ignores relevance after the first pick). Default: `0.5`
+   */
+  lambda?: number;
+}
+
+/**
+ * Post-retrieval RAG Strategy implementing Maximal Marginal Relevance (MMR):
+ * greedily selects chunks that are relevant to the query but dissimilar to
+ * chunks already selected, reducing near-duplicate context (e.g. overlapping
+ * parent/child chunks or repeated sections) crowding out distinct information.
+ *
+ * `MMR = argmax_{d in R \ S} [ lambda * Sim(d, q) - (1 - lambda) * max_{d' in S} Sim(d, d') ]`
+ *
+ * `Sim(d, q)` uses `context.scores` (the retrieval relevance score already
+ * populated by `RAGPipeline`). `Sim(d, d')` requires chunk embeddings — a
+ * chunk without an `embedding` is treated as having zero similarity to every
+ * other chunk, so it can still be selected but never penalizes or is
+ * penalized by diversity against the ones that do carry embeddings.
+ */
+export class MmrStrategy implements RAGStrategy {
+  readonly name = 'MMR';
+  readonly phase = 'post-retrieval' as const;
+  private readonly topK: number;
+  private readonly lambda: number;
+
+  /**
+   * Creates a new instance of MmrStrategy.
+   * @param options Configuration for top-K cutoff and the relevance/diversity balance (`lambda`).
+   */
+  constructor(options?: MmrStrategyOptions) {
+    const topK = options?.topK ?? 5;
+    if (!Number.isInteger(topK) || topK < 0) {
+      throw new RangeError(`MmrStrategy: topK must be a non-negative integer, got ${topK}`);
+    }
+    this.topK = topK;
+
+    const lambda = options?.lambda ?? 0.5;
+    if (!Number.isFinite(lambda) || lambda < 0 || lambda > 1) {
+      throw new RangeError(`MmrStrategy: lambda must be a finite number in [0, 1], got ${lambda}`);
+    }
+    this.lambda = lambda;
+  }
+
+  /**
+   * Selects a diverse top-K subset of `context.chunks` via MMR.
+   *
+   * @param context RAGContext payload containing retrieved chunks and their relevance `scores`.
+   * @returns Updated RAGContext with `chunks` replaced by the MMR-selected subset.
+   */
+  process(context: RAGContext): RAGContext {
+    const chunks = context.chunks ?? [];
+    if (chunks.length === 0) return context;
+
+    // Without any chunk embeddings there's no diversity signal to select by;
+    // pass through the incoming order (already relevance-ranked upstream).
+    if (!chunks.some((c) => c.embedding)) {
+      return { ...context, chunks: chunks.slice(0, this.topK) };
+    }
+
+    const scores = context.scores;
+    const relevance = (chunk: DocumentChunk): number => scores?.get(chunk.id) ?? 0;
+
+    const remaining = [...chunks];
+    const selected: DocumentChunk[] = [];
+
+    while (remaining.length > 0 && selected.length < this.topK) {
+      let bestIndex = 0;
+      let bestScore = -Infinity;
+
+      for (let i = 0; i < remaining.length; i++) {
+        const candidate = remaining[i];
+        const relevanceScore = relevance(candidate);
+
+        // Chunks without an embedding can't be compared for similarity, so
+        // they never get diversity-penalized (or credited) against selected chunks.
+        // Starts at -Infinity (not 0) so a genuinely negative cosine similarity
+        // — an anti-correlated embedding — still counts as the max, per the MMR formula.
+        let maxSimToSelected = -Infinity;
+        if (candidate.embedding) {
+          for (const s of selected) {
+            if (!s.embedding) continue;
+            const sim = cosineSimilarity(candidate.embedding, s.embedding);
+            if (sim > maxSimToSelected) maxSimToSelected = sim;
+          }
+        }
+        if (maxSimToSelected === -Infinity) maxSimToSelected = 0;
+
+        const mmrScore = this.lambda * relevanceScore - (1 - this.lambda) * maxSimToSelected;
+        if (mmrScore > bestScore) {
+          bestScore = mmrScore;
+          bestIndex = i;
+        }
+      }
+
+      selected.push(remaining[bestIndex]);
+      remaining.splice(bestIndex, 1);
+    }
+
+    return { ...context, chunks: selected };
+  }
+}

packages/rag/src/utils/cosine-similarity.ts

@@ -0,0 +1,24 @@
+/**
+ * Cosine similarity between two vectors of equal length. Returns `0` for
+ * mismatched lengths or zero-magnitude vectors, rather than throwing or
+ * producing `NaN`.
+ *
+ * @param a First vector.
+ * @param b Second vector, compared against `a`.
+ * @returns Cosine similarity in `[-1, 1]`, or `0` if the inputs are incomparable.
+ */
+export function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length || a.length === 0) return 0;
+
+  let dotProduct = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dotProduct += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+
+  const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+  return denominator > 0 ? dotProduct / denominator : 0;
+}

packages/rag/test/rag.spec.ts

@@ -1037,6 +1037,114 @@ export class BenchmarkService${i} {
     assert(false, 'Test 16: Built-in Cohere/Voyage rerank provider adapters', err.message);
   }
 
+  // TEST 17: MmrStrategy diversity selection (#133)
+  try {
+    const { MmrStrategy, cosineSimilarity } = await import('../src');
+
+    // 17a. cosineSimilarity utility: known values and edge cases
+    assert(Math.abs(cosineSimilarity([1, 0], [1, 0]) - 1) < 1e-9, 'Test 17a: cosineSimilarity of identical vectors is 1');
+    assert(Math.abs(cosineSimilarity([1, 0], [0, 1])) < 1e-9, 'Test 17a2: cosineSimilarity of orthogonal vectors is 0');
+    assert(cosineSimilarity([1, 0], [1, 0, 0]) === 0, 'Test 17a3: cosineSimilarity of mismatched-length vectors returns 0, not a throw');
+    assert(cosineSimilarity([0, 0], [1, 0]) === 0, 'Test 17a4: cosineSimilarity of a zero-magnitude vector returns 0, not NaN');
+
+    // A and B are near-duplicates (identical embedding); C is distinct but lower-scored.
+    const chunkA = { id: 'a', parentId: 'p', content: 'auth token validation', metadata: {}, embedding: [1, 0] };
+    const chunkB = { id: 'b', parentId: 'p', content: 'auth token validation (near dup)', metadata: {}, embedding: [1, 0] };
+    const chunkC = { id: 'c', parentId: 'p', content: 'unrelated billing export', metadata: {}, embedding: [0, 1] };
+    const scores = new Map([['a', 0.9], ['b', 0.85], ['c', 0.5]]);
+
+    // 17b. Plain top-K by score would pick A, B (both near-duplicates) — establish the baseline being improved on.
+    const plainTopK = [chunkA, chunkB, chunkC].sort((x, y) => scores.get(y.id)! - scores.get(x.id)!).slice(0, 2);
+    assert(
+      plainTopK.map((c) => c.id).sort().join(',') === 'a,b',
+      'Test 17b: baseline top-K by score selects the two near-duplicate chunks (A, B)',
+    );
+
+    // 17c. MMR selects A (most relevant) then C (distinct), not A+B, given the near-duplicate penalty
+    const mmr = new MmrStrategy({ topK: 2, lambda: 0.5 });
+    const mmrResult = mmr.process({ query: 'auth', chunks: [chunkA, chunkB, chunkC], scores });
+    const mmrIds = mmrResult.chunks!.map((c) => c.id).sort();
+    assert(mmrIds.join(',') === 'a,c', 'Test 17c: MMR selects the relevant chunk plus a distinct one (A, C), surfacing more unique context than plain top-K (A, B)');
+
+    // 17d. lambda close to 1 behaves like pure relevance ranking (ignores diversity)
+    const pureRelevance = new MmrStrategy({ topK: 2, lambda: 1 });
+    const pureResult = pureRelevance.process({ query: 'auth', chunks: [chunkA, chunkB, chunkC], scores });
+    assert(
+      pureResult.chunks!.map((c) => c.id).sort().join(',') === 'a,b',
+      'Test 17d: lambda=1 (pure relevance) reduces to plain top-K by score, picking A and B',
+    );
+
+    // 17e. topK is respected
+    const cappedResult = mmr.process({ query: 'auth', chunks: [chunkA, chunkB, chunkC], scores: scores });
+    assert(cappedResult.chunks!.length === 2, 'Test 17e: MmrStrategy respects the configured topK');
+
+    // 17f. Chunks without embeddings pass through unchanged (capped at topK), no throw
+    const noEmbedChunks = [
+      { id: 'x', parentId: 'p', content: 'x', metadata: {} },
+      { id: 'y', parentId: 'p', content: 'y', metadata: {} },
+    ];
+    const noEmbedResult = mmr.process({ query: 'q', chunks: noEmbedChunks });
+    assert(noEmbedResult.chunks!.length === 2, 'Test 17f: chunks without embeddings pass through without throwing');
+
+    // 17g. Empty chunks array is a no-op
+    const emptyResult = mmr.process({ query: 'q', chunks: [] });
+    assert(emptyResult.chunks!.length === 0, 'Test 17g: an empty chunks array is handled without throwing');
+
+    // 17h. Selection order matters, not just membership: the most relevant chunk must be picked first
+    assert(mmrResult.chunks![0].id === 'a', 'Test 17h: MMR selects the most relevant chunk (A) first, not just as a set member');
+
+    // 17i. Invalid topK/lambda are rejected at construction, per review feedback
+    let rejectedTopK = false;
+    try {
+      new MmrStrategy({ topK: -1 });
+    } catch {
+      rejectedTopK = true;
+    }
+    assert(rejectedTopK, 'Test 17i: MmrStrategy rejects a negative topK at construction');
+
+    let rejectedLambda = false;
+    try {
+      new MmrStrategy({ lambda: 1.5 });
+    } catch {
+      rejectedLambda = true;
+    }
+    assert(rejectedLambda, 'Test 17j: MmrStrategy rejects a lambda outside [0, 1] at construction');
+
+    // 17k. Anti-correlated (negative cosine similarity) embeddings still participate
+    // in the diversity penalty per the MMR formula, instead of being clamped to 0, per review feedback
+    const chunkP = { id: 'p1', parentId: 'p', content: 'p', metadata: {}, embedding: [1, 0] };
+    const chunkQ = { id: 'q1', parentId: 'p', content: 'q', metadata: {}, embedding: [-1, 0] }; // anti-correlated with P
+    const antiScores = new Map([['p1', 1], ['q1', 0.99]]);
+    // lambda=0 -> pure diversity: after picking P, the score for Q becomes -(1)*(-1) = +1 (rewarded for being anti-correlated),
+    // which must be strictly greater than picking a chunk identical to P would score (-(1)*(1) = -1).
+    const pureDiversity = new MmrStrategy({ topK: 2, lambda: 0 });
+    const chunkR = { id: 'r1', parentId: 'p', content: 'r', metadata: {}, embedding: [1, 0] }; // identical to P
+    const antiResult = pureDiversity.process({
+      query: 'q',
+      chunks: [chunkP, chunkQ, chunkR],
+      scores: new Map([...antiScores, ['r1', 0.98]]),
+    });
+    assert(
+      antiResult.chunks![1].id === 'q1',
+      'Test 17k: an anti-correlated (negative cosine similarity) chunk is preferred over a duplicate under pure diversity, proving negative similarity is not clamped to 0',
+    );
+
+    // 17l. Mixed embedded/non-embedded chunks: the non-embedded chunk still participates via its score
+    const embedded = { id: 'e1', parentId: 'p', content: 'e', metadata: {}, embedding: [1, 0] };
+    const noEmbed = { id: 'n1', parentId: 'p', content: 'n', metadata: {} };
+    const mixedResult = mmr.process({
+      query: 'q',
+      chunks: [embedded, noEmbed],
+      scores: new Map([['e1', 0.5], ['n1', 0.9]]),
+    });
+    assert(
+      mixedResult.chunks!.length === 2 && mixedResult.chunks!.some((c) => c.id === 'n1'),
+      'Test 17l: a chunk without an embedding still participates in selection via its relevance score, in a mixed set',
+    );
+  } catch (err: any) {
+    assert(false, 'Test 17: MmrStrategy diversity selection', err.message);
+  }
+
   console.log(`\n  📊 Core RAG Test Results: ${passed} passed, ${failed} failed.\n`);
   if (failed > 0) {
     throw new Error('RAG Unit Tests Failed');