67 lines
2.0 KiB
Python
67 lines
2.0 KiB
Python
"""Similarity × recency re-ranking over merged retrieval hits (pure).
|
||
|
||
pgvector returns cosine *distance* (0 = identical). We map it to a
|
||
similarity in [0, 1], blend with an exponential recency decay, and keep
|
||
the best chunk per item so one long comment can't fill the context.
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from dataclasses import dataclass, replace
|
||
from datetime import date
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class Hit:
|
||
text: str
|
||
metadata: dict[str, str]
|
||
distance: float
|
||
score: float = 0.0
|
||
|
||
|
||
def recency(when: str, *, now: date, half_life_days: float) -> float:
|
||
"""1.0 for today (or future), halving every ``half_life_days``; 0.0
|
||
when ``when`` is empty or unparsable."""
|
||
try:
|
||
d = date.fromisoformat(when[:10])
|
||
except (ValueError, TypeError):
|
||
return 0.0
|
||
age = (now - d).days
|
||
if age <= 0:
|
||
return 1.0
|
||
return 0.5 ** (age / half_life_days)
|
||
|
||
|
||
def _similarity(distance: float) -> float:
|
||
return min(1.0, max(0.0, 1.0 - distance))
|
||
|
||
|
||
def blend(
|
||
hits: list[Hit],
|
||
*,
|
||
weight: float,
|
||
half_life_days: float,
|
||
now: date,
|
||
top_n: int,
|
||
) -> list[Hit]:
|
||
"""Score, dedupe per ``item_key`` (best chunk wins), sort desc, cut."""
|
||
best: dict[str, Hit] = {}
|
||
for h in hits:
|
||
score = (1.0 - weight) * _similarity(h.distance) + weight * recency(
|
||
h.metadata.get("date", ""), now=now, half_life_days=half_life_days
|
||
)
|
||
scored = replace(h, score=score)
|
||
key = h.metadata.get("item_key", "") or str(id(h))
|
||
if key not in best or scored.score > best[key].score:
|
||
best[key] = scored
|
||
ranked = sorted(best.values(), key=lambda h: h.score, reverse=True)
|
||
return ranked[:top_n]
|
||
|
||
|
||
def filter_since(hits: list[Hit], since: str) -> list[Hit]:
|
||
"""Keep hits dated on/after ``since`` (ISO date); undated hits are
|
||
dropped when a cutoff is active. Empty ``since`` is a no-op."""
|
||
if not since:
|
||
return hits
|
||
return [h for h in hits if h.metadata.get("date", "")[:10] >= since[:10]]
|