Prerequisites and retrieval contract
A retrieved candidate list can contain several passages explaining the same point. Passing all of them to a generator spends context on repetition. Maximal marginal relevance, or MMR, adds a redundancy penalty while selecting passages. This standalone Python 3.12 example uses a small relevance table and symmetric passage-similarity table. It needs no embedding service, vector database or additional package.
The input contract deliberately puts relevance and pair similarity in the range zero through one. These are synthetic scores selected to make the behavior inspectable. If your real retriever emits distances, logits or negative cosine values, define and evaluate a compatible transformation before using this implementation. A distance in which smaller means closer cannot be substituted directly for similarity.
Follow one selection step
The greedy score is weight times relevance minus the product of (one minus weight) and the largest similarity to a selected passage. Initially the redundancy penalty is zero. With weight 0.5, candidate a wins first with 0.45. After a is selected, b scores 0.425 minus 0.475, while c scores 0.35 minus 0.05. Candidate c therefore wins the second slot despite having lower raw relevance.
With weight one the penalty disappears and the fixture returns a followed by b. This gives a useful regression baseline: increasing diversification should change the ordering for a reason visible in the pair scores. MMR is a selection heuristic; it does not prove that the resulting context covers all required facts or that a generated answer will be correct.
Policies, limits and troubleshooting
The dictionary provides one entry per candidate identifier. Reject repeated identifiers when building that dictionary from external rows, rather than silently letting a later row overwrite an earlier passage. Each unordered pair is represented by a frozenset, so the sample has a symmetric similarity contract and never needs a candidate compared with itself.
The example validates all pair scores before selection, including when k is zero. Missing comparisons therefore fail consistently rather than only when a particular candidate happens to be chosen. Ties follow input dictionary order. Preserve that order when reproducible results matter. A request larger than the candidate pool returns all available candidates once; a negative k is invalid.
The full pair table uses quadratic storage, and this straightforward greedy implementation rescans selected passages. Keep the initial candidate pool bounded. If unrelated passages rise too high, inspect score scales and weight before changing the algorithm. Tests cover the two expected rankings, zero selection, an oversized request, a tie and a missing similarity table. Retrieval quality and live model generation remain untested.
Complete example
Save as mmr.py.
import math
def rerank(relevance, similarities, k, weight):
if type(k) is not int or k < 0 or not 0 <= weight <= 1:
raise ValueError("invalid selection policy")
ids = list(relevance)
if any(not math.isfinite(v) or not 0 <= v <= 1
for v in relevance.values()):
raise ValueError("invalid relevance")
for i, a in enumerate(ids):
for b in ids[i + 1:]:
value = similarities.get(frozenset((a, b)))
if value is None or not math.isfinite(value) or not 0 <= value <= 1:
raise ValueError("missing or invalid pair similarity")
chosen = []
remaining = ids.copy()
while remaining and len(chosen) < k:
def marginal(a):
redundancy = max((similarities[frozenset((a, b))]
for b in chosen), default=0.0)
return weight * relevance[a] - (1 - weight) * redundancy
winner = max(remaining, key=marginal)
chosen.append(winner)
remaining.remove(winner)
return chosen
relevance = {"a": 0.90, "b": 0.85, "c": 0.70}
pairs = {frozenset("ab"): 0.95, frozenset("ac"): 0.10,
frozenset("bc"): 0.20}
assert rerank(relevance, pairs, 2, 1.0) == ["a", "b"]
assert rerank(relevance, pairs, 2, 0.5) == ["a", "c"]
assert rerank(relevance, pairs, 0, 0.5) == []
assert len(rerank(relevance, pairs, 9, 0.5)) == 3
assert rerank({"x": 0.5, "y": 0.5}, {frozenset(("x", "y")): 0}, 1, 1) == ["x"]
try:
rerank(relevance, {}, 2, 0.5)
except ValueError:
pass
else:
raise AssertionError("missing pairs accepted")
print("relevance-only: a b")
print("diversified: a c")
Run and expected output
python3 mmr.pyrelevance-only: a b
diversified: a cPrimary references
- Original MMR paper bibliographic record
- Goldstein and colleagues: multi-document summarization and MMR
Continue with AI tutorials.