mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
refactor(proxy): drop the test-only memory ranker and file-backed native memory ops
MemoryHandler carried two pieces of machinery that only tests reached: - memory_ranker.py and the ranker= kwarg on search_and_format_context. No production caller passes ranker=; all five handler call sites pass query= only, so the re-rank branch never ran. The cosine + min_similarity branch is kept as the only path, unchanged. - The file-backed native memory ops (_resolve_native_path, _native_view, _native_create, _native_str_replace, _native_insert, _native_delete_file, _native_rename). _execute_native_memory_tool dispatches only to the *_semantic variants. _init_native_memory_dir is kept: it still creates the private native memory directory and test_private_state_files asserts its mode. Evidence: grep for memory_ranker, RecencyBoostRanker, ranker= and each removed method across headroom, plugins, docs, tests and the consumer repos finds only the definitions and their own tests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Assisted-by: claude-code:claude-opus-5-5 Headline-Session: 6e77a807-8dd4-4a77-a2fa-ddce6dc2515e Headline-AI-Share: 100% strict / 100% weighted
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
a9815bbb5f
commit
89fa67c3f4
@@ -718,7 +718,6 @@ class MemoryHandler:
|
||||
messages: list[dict[str, Any]],
|
||||
request_context: RequestContext | None = None,
|
||||
*,
|
||||
ranker: Any | None = None,
|
||||
query: Any | None = None,
|
||||
budget: Any | None = None,
|
||||
) -> str | None:
|
||||
@@ -736,14 +735,6 @@ class MemoryHandler:
|
||||
omitted, behaves as before this fix — single-bucket search
|
||||
against the legacy backend. Production handlers always
|
||||
pass it; tests / mocks can keep the simpler call shape.
|
||||
ranker: Optional :class:`~headroom.proxy.memory_ranker.MemoryRanker`
|
||||
— re-ranks the backend's cosine-only candidates by an
|
||||
additional signal (recency, source, access count, …).
|
||||
When ``None`` (default), behaviour is pure cosine +
|
||||
``budget.min_similarity`` floor. When provided, candidates
|
||||
are adapted to :class:`MemoryCandidate`, re-ranked, then
|
||||
re-filtered by ``budget.min_similarity`` on the boosted
|
||||
score.
|
||||
query: Optional :class:`MemoryQuery` — multi-source, full-
|
||||
fidelity retrieval query. When provided, takes precedence
|
||||
over the ``messages``-derived query. Constructed at the
|
||||
@@ -754,8 +745,7 @@ class MemoryHandler:
|
||||
returned formatted block by tokens / entries / min
|
||||
similarity. When ``None``, defaults are taken from
|
||||
``self.config`` so the existing top_k / min_similarity
|
||||
contract is preserved. Both the no-ranker and the with-
|
||||
ranker paths honour the same budget.
|
||||
contract is preserved.
|
||||
|
||||
Returns:
|
||||
Formatted context string, or None if no relevant memories.
|
||||
@@ -848,71 +838,34 @@ class MemoryHandler:
|
||||
)
|
||||
return None
|
||||
|
||||
# Optional re-rank: when a MemoryRanker is provided, adapt
|
||||
# results to MemoryCandidate, re-rank, then filter by
|
||||
# ``budget.min_similarity`` on the BOOSTED score. The re-rank
|
||||
# can promote a fresh weak-cosine memory above a stale
|
||||
# strong-cosine one (RecencyBoostRanker default behaviour).
|
||||
# Cap by ``budget.max_entries`` after filtering so the budget
|
||||
# contract is honoured on both branches.
|
||||
# Pure cosine + budget min_similarity floor.
|
||||
# Each rendered row carries the memory ID in [brackets] so
|
||||
# the model can address it directly via memory_update /
|
||||
# memory_delete without round-tripping through memory_search.
|
||||
# Both branches below render the same `i. [id] content` shape
|
||||
# so the format is stable regardless of whether a ranker is
|
||||
# in play.
|
||||
selected_memory_ids: list[str] = []
|
||||
if ranker is not None:
|
||||
from headroom.proxy.memory_ranker import MemoryCandidate
|
||||
filtered_results = [r for r in results if r.score >= effective_budget.min_similarity]
|
||||
|
||||
candidates = [MemoryCandidate.from_backend_result(r) for r in results]
|
||||
ranked = ranker.rank(candidates)
|
||||
# Filter on the post-rank score (the ranker may have
|
||||
# boosted or attenuated original cosine values).
|
||||
ranked = [c for c in ranked if c.score >= effective_budget.min_similarity]
|
||||
if not ranked:
|
||||
logger.debug(
|
||||
f"Memory: {len(results)} memories found but none above threshold "
|
||||
f"{effective_budget.min_similarity} after re-rank"
|
||||
)
|
||||
return None
|
||||
ranked = ranked[: effective_budget.max_entries]
|
||||
memory_lines = []
|
||||
for i, candidate in enumerate(ranked, 1):
|
||||
memory_id = candidate.id or "?"
|
||||
if candidate.id:
|
||||
selected_memory_ids.append(candidate.id)
|
||||
memory_lines.append(f"{i}. [{memory_id}] {candidate.content}")
|
||||
if candidate.related_entities:
|
||||
entities_str = ", ".join(candidate.related_entities[:3])
|
||||
memory_lines.append(f" (Related: {entities_str})")
|
||||
else:
|
||||
# No ranker: pure cosine + budget min_similarity floor.
|
||||
filtered_results = [
|
||||
r for r in results if r.score >= effective_budget.min_similarity
|
||||
]
|
||||
if not filtered_results:
|
||||
logger.debug(
|
||||
f"Memory: {len(results)} memories found but none above threshold "
|
||||
f"{effective_budget.min_similarity}"
|
||||
)
|
||||
return None
|
||||
|
||||
if not filtered_results:
|
||||
logger.debug(
|
||||
f"Memory: {len(results)} memories found but none above threshold "
|
||||
f"{effective_budget.min_similarity}"
|
||||
)
|
||||
return None
|
||||
# Cap entry count via the budget (defence-in-depth —
|
||||
# backend already gets top_k=max_entries but this enforces
|
||||
# it on post-filter results too).
|
||||
filtered_results = filtered_results[: effective_budget.max_entries]
|
||||
|
||||
# Cap entry count via the budget (defence-in-depth —
|
||||
# backend already gets top_k=max_entries but this enforces
|
||||
# it on post-filter results too).
|
||||
filtered_results = filtered_results[: effective_budget.max_entries]
|
||||
|
||||
memory_lines = []
|
||||
for i, result in enumerate(filtered_results, 1):
|
||||
memory_id = getattr(result.memory, "id", None) or "?"
|
||||
if memory_id != "?":
|
||||
selected_memory_ids.append(memory_id)
|
||||
memory_lines.append(f"{i}. [{memory_id}] {result.memory.content}")
|
||||
if hasattr(result, "related_entities") and result.related_entities:
|
||||
entities_str = ", ".join(result.related_entities[:3])
|
||||
memory_lines.append(f" (Related: {entities_str})")
|
||||
memory_lines = []
|
||||
for i, result in enumerate(filtered_results, 1):
|
||||
memory_id = getattr(result.memory, "id", None) or "?"
|
||||
if memory_id != "?":
|
||||
selected_memory_ids.append(memory_id)
|
||||
memory_lines.append(f"{i}. [{memory_id}] {result.memory.content}")
|
||||
if hasattr(result, "related_entities") and result.related_entities:
|
||||
entities_str = ", ".join(result.related_entities[:3])
|
||||
memory_lines.append(f" (Related: {entities_str})")
|
||||
|
||||
except Exception as e:
|
||||
logger.warning(f"Memory: Search failed for user {effective_user_id}: {e}")
|
||||
@@ -1617,269 +1570,6 @@ your responses, not to drive new actions."""
|
||||
logger.error(f"Memory: Native tool error: {e}")
|
||||
return f"Error: {e}"
|
||||
|
||||
def _resolve_native_path(self, path: str, user_id: str) -> Path:
|
||||
"""Resolve path within user's memory directory safely.
|
||||
|
||||
Prevents path traversal attacks by ensuring path stays within
|
||||
the user's memory directory.
|
||||
"""
|
||||
assert self._native_memory_dir is not None
|
||||
|
||||
# User-scoped memory directory
|
||||
user_dir = self._native_memory_dir / user_id
|
||||
user_dir.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
# Normalize path (remove /memories prefix if present)
|
||||
if path.startswith("/memories"):
|
||||
path = path[len("/memories") :]
|
||||
if path.startswith("/"):
|
||||
path = path[1:]
|
||||
|
||||
# Resolve and validate
|
||||
resolved = (user_dir / path).resolve()
|
||||
|
||||
# Security: ensure path is within user directory
|
||||
try:
|
||||
resolved.relative_to(user_dir.resolve())
|
||||
except ValueError:
|
||||
raise ValueError(f"Path traversal detected: {path}") from None
|
||||
|
||||
return resolved
|
||||
|
||||
def _native_view(self, input_data: dict[str, Any], user_id: str) -> str:
|
||||
"""View directory contents or file contents."""
|
||||
path = input_data.get("path", "/memories")
|
||||
view_range = input_data.get("view_range")
|
||||
|
||||
resolved = self._resolve_native_path(path, user_id)
|
||||
|
||||
if not resolved.exists():
|
||||
return f"The path {path} does not exist. Please provide a valid path."
|
||||
|
||||
if resolved.is_dir():
|
||||
# List directory contents
|
||||
lines = [
|
||||
f"Here're the files and directories up to 2 levels deep in {path}, "
|
||||
"excluding hidden items and node_modules:"
|
||||
]
|
||||
|
||||
def get_size(p: Path) -> str:
|
||||
if p.is_file():
|
||||
size = p.stat().st_size
|
||||
if size < 1024:
|
||||
return f"{size}B"
|
||||
elif size < 1024 * 1024:
|
||||
return f"{size / 1024:.1f}K"
|
||||
else:
|
||||
return f"{size / (1024 * 1024):.1f}M"
|
||||
return "4.0K" # Default for directories
|
||||
|
||||
def list_recursive(p: Path, rel_path: str, depth: int) -> None:
|
||||
if depth > 2:
|
||||
return
|
||||
if p.name.startswith(".") or p.name == "node_modules":
|
||||
return
|
||||
|
||||
lines.append(f"{get_size(p)}\t{rel_path}")
|
||||
|
||||
if p.is_dir() and depth < 2:
|
||||
try:
|
||||
for child in sorted(p.iterdir()):
|
||||
child_rel = (
|
||||
f"{rel_path}/{child.name}"
|
||||
if rel_path != path
|
||||
else f"{path}/{child.name}"
|
||||
)
|
||||
list_recursive(child, child_rel, depth + 1)
|
||||
except PermissionError:
|
||||
pass
|
||||
|
||||
list_recursive(resolved, path, 0)
|
||||
return "\n".join(lines)
|
||||
|
||||
else:
|
||||
# Read file contents with line numbers
|
||||
try:
|
||||
content = resolved.read_text(encoding="utf-8")
|
||||
except UnicodeDecodeError:
|
||||
content = resolved.read_text(encoding="latin-1")
|
||||
|
||||
lines_content = content.split("\n")
|
||||
|
||||
if len(lines_content) > 999999:
|
||||
return f"File {path} exceeds maximum line limit of 999,999 lines."
|
||||
|
||||
# Apply view_range if specified
|
||||
start_line = 1
|
||||
end_line = len(lines_content)
|
||||
if view_range and len(view_range) >= 2:
|
||||
start_line = max(1, view_range[0])
|
||||
end_line = min(len(lines_content), view_range[1])
|
||||
|
||||
result_lines = [f"Here's the content of {path} with line numbers:"]
|
||||
for i, line in enumerate(lines_content[start_line - 1 : end_line], start=start_line):
|
||||
result_lines.append(f"{i:6d}\t{line}")
|
||||
|
||||
return "\n".join(result_lines)
|
||||
|
||||
def _native_create(self, input_data: dict[str, Any], user_id: str) -> str:
|
||||
"""Create a new file."""
|
||||
path = input_data.get("path", "")
|
||||
file_text = input_data.get("file_text", "")
|
||||
|
||||
if not path:
|
||||
return "Error: path is required"
|
||||
|
||||
resolved = self._resolve_native_path(path, user_id)
|
||||
|
||||
if resolved.exists():
|
||||
return f"Error: File {path} already exists"
|
||||
|
||||
# Create parent directories if needed
|
||||
resolved.parent.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
resolved.write_text(file_text, encoding="utf-8")
|
||||
logger.info(f"Memory: Native create: {path} for user {user_id}")
|
||||
|
||||
return f"File created successfully at: {path}"
|
||||
|
||||
def _native_str_replace(self, input_data: dict[str, Any], user_id: str) -> str:
|
||||
"""Replace text in a file."""
|
||||
path = input_data.get("path", "")
|
||||
old_str = input_data.get("old_str", "")
|
||||
new_str = input_data.get("new_str", "")
|
||||
|
||||
if not path:
|
||||
return "Error: path is required"
|
||||
if not old_str:
|
||||
return "Error: old_str is required"
|
||||
|
||||
resolved = self._resolve_native_path(path, user_id)
|
||||
|
||||
if not resolved.exists():
|
||||
return f"Error: The path {path} does not exist. Please provide a valid path."
|
||||
|
||||
if resolved.is_dir():
|
||||
return f"Error: The path {path} does not exist. Please provide a valid path."
|
||||
|
||||
content = resolved.read_text(encoding="utf-8")
|
||||
|
||||
# Check for occurrences
|
||||
occurrences = content.count(old_str)
|
||||
if occurrences == 0:
|
||||
return f"No replacement was performed, old_str `{old_str}` did not appear verbatim in {path}."
|
||||
if occurrences > 1:
|
||||
# Find line numbers
|
||||
lines = content.split("\n")
|
||||
found_lines = []
|
||||
for i, line in enumerate(lines, 1):
|
||||
if old_str in line:
|
||||
found_lines.append(str(i))
|
||||
return (
|
||||
f"No replacement was performed. Multiple occurrences of old_str `{old_str}` "
|
||||
f"in lines: {', '.join(found_lines)}. Please ensure it is unique"
|
||||
)
|
||||
|
||||
# Perform replacement
|
||||
new_content = content.replace(old_str, new_str, 1)
|
||||
resolved.write_text(new_content, encoding="utf-8")
|
||||
|
||||
# Show snippet around the change
|
||||
lines = new_content.split("\n")
|
||||
for i, line in enumerate(lines):
|
||||
if new_str in line:
|
||||
start = max(0, i - 2)
|
||||
end = min(len(lines), i + 3)
|
||||
snippet_lines = ["The memory file has been edited."]
|
||||
for j in range(start, end):
|
||||
snippet_lines.append(f"{j + 1:6d}\t{lines[j]}")
|
||||
return "\n".join(snippet_lines)
|
||||
|
||||
return "The memory file has been edited."
|
||||
|
||||
def _native_insert(self, input_data: dict[str, Any], user_id: str) -> str:
|
||||
"""Insert text at a specific line."""
|
||||
path = input_data.get("path", "")
|
||||
insert_line = input_data.get("insert_line", 0)
|
||||
insert_text = input_data.get("insert_text", "")
|
||||
|
||||
if not path:
|
||||
return "Error: path is required"
|
||||
|
||||
resolved = self._resolve_native_path(path, user_id)
|
||||
|
||||
if not resolved.exists():
|
||||
return f"Error: The path {path} does not exist"
|
||||
|
||||
if resolved.is_dir():
|
||||
return f"Error: The path {path} does not exist"
|
||||
|
||||
content = resolved.read_text(encoding="utf-8")
|
||||
lines = content.split("\n")
|
||||
n_lines = len(lines)
|
||||
|
||||
if insert_line < 0 or insert_line > n_lines:
|
||||
return (
|
||||
f"Error: Invalid `insert_line` parameter: {insert_line}. "
|
||||
f"It should be within the range of lines of the file: [0, {n_lines}]"
|
||||
)
|
||||
|
||||
# Insert at specified line
|
||||
lines.insert(insert_line, insert_text.rstrip("\n"))
|
||||
|
||||
resolved.write_text("\n".join(lines), encoding="utf-8")
|
||||
|
||||
return f"The file {path} has been edited."
|
||||
|
||||
def _native_delete_file(self, input_data: dict[str, Any], user_id: str) -> str:
|
||||
"""Delete a file or directory."""
|
||||
path = input_data.get("path", "")
|
||||
|
||||
if not path:
|
||||
return "Error: path is required"
|
||||
|
||||
resolved = self._resolve_native_path(path, user_id)
|
||||
|
||||
if not resolved.exists():
|
||||
return f"Error: The path {path} does not exist"
|
||||
|
||||
import shutil
|
||||
|
||||
if resolved.is_dir():
|
||||
shutil.rmtree(resolved)
|
||||
else:
|
||||
resolved.unlink()
|
||||
|
||||
logger.info(f"Memory: Native delete: {path} for user {user_id}")
|
||||
return f"Successfully deleted {path}"
|
||||
|
||||
def _native_rename(self, input_data: dict[str, Any], user_id: str) -> str:
|
||||
"""Rename or move a file/directory."""
|
||||
old_path = input_data.get("old_path", "")
|
||||
new_path = input_data.get("new_path", "")
|
||||
|
||||
if not old_path:
|
||||
return "Error: old_path is required"
|
||||
if not new_path:
|
||||
return "Error: new_path is required"
|
||||
|
||||
resolved_old = self._resolve_native_path(old_path, user_id)
|
||||
resolved_new = self._resolve_native_path(new_path, user_id)
|
||||
|
||||
if not resolved_old.exists():
|
||||
return f"Error: The path {old_path} does not exist"
|
||||
|
||||
if resolved_new.exists():
|
||||
return f"Error: The destination {new_path} already exists"
|
||||
|
||||
# Create parent directory if needed
|
||||
resolved_new.parent.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
resolved_old.rename(resolved_new)
|
||||
|
||||
logger.info(f"Memory: Native rename: {old_path} -> {new_path} for user {user_id}")
|
||||
return f"Successfully renamed {old_path} to {new_path}"
|
||||
|
||||
# =========================================================================
|
||||
# Semantic Translation Methods (Native Tool → Vector Store)
|
||||
# =========================================================================
|
||||
|
||||
@@ -1,202 +0,0 @@
|
||||
"""``MemoryRanker``: pluggable re-ranker for memory candidates.
|
||||
|
||||
Pre-this-PR Headroom ranked memory candidates by pure cosine
|
||||
similarity. Every other memory system we surveyed
|
||||
(Letta / Mem0 / Cognee / Supermemory) re-ranks beyond cosine — recency,
|
||||
source weight, access count, and decay are table-stakes for not
|
||||
returning 6-month-old "winners" when fresh signal exists.
|
||||
|
||||
This module ships the first ranker — :class:`RecencyBoostRanker` —
|
||||
plus the :class:`MemoryRanker` protocol that future rankers
|
||||
(source-weight, access-count) plug into.
|
||||
|
||||
The ranker is **pure**: ``rank(candidates) -> ranked_candidates``,
|
||||
no I/O, no state, no mutation of inputs. Same Rust-port shape as
|
||||
``CompressionDecision`` and ``MemoryDecision``.
|
||||
|
||||
Performance: O(N) over candidates where N = top_k. One ``math.exp()``
|
||||
per candidate. Sub-microsecond per request — no embedding compute,
|
||||
no network, no disk.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
from datetime import datetime, timezone
|
||||
from typing import Protocol
|
||||
|
||||
from headroom.proxy.memory_rank_policy import (
|
||||
boost_memory_score,
|
||||
memory_recency_factor,
|
||||
parse_memory_created_at,
|
||||
)
|
||||
|
||||
# Use ``timezone.utc`` (always available) instead of ``datetime.UTC``
|
||||
# (Python 3.11+) so this module imports cleanly on older interpreters.
|
||||
_UTC = timezone.utc
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class MemoryCandidate:
|
||||
"""Immutable retrieval candidate as it flows through the ranker.
|
||||
|
||||
The shape is the **proxy-side internal contract** — the backend's
|
||||
return type (typically ``MemoryResult`` with nested
|
||||
``MemoryResult.memory.created_at``) is adapted into this flatter
|
||||
shape at the ranker boundary so the ranker stays backend-agnostic.
|
||||
|
||||
``score`` is the cosine similarity as returned by the backend.
|
||||
Rankers MAY mutate ``score`` by returning a new candidate with an
|
||||
updated score (frozen dataclass means they cannot mutate in place).
|
||||
"""
|
||||
|
||||
content: str
|
||||
score: float
|
||||
created_at: datetime | None = None
|
||||
source: str | None = None # e.g. "memory_save" | "traffic_learner" | "inline"
|
||||
related_entities: tuple[str, ...] = field(default_factory=tuple)
|
||||
# Backend memory ID. Empty string when not preserved (test fixtures,
|
||||
# legacy callers). Rendered as ``[id]`` in the auto-tail block so the
|
||||
# model can pass it to memory_update / memory_delete directly.
|
||||
id: str = ""
|
||||
|
||||
@classmethod
|
||||
def from_backend_result(cls, result: object) -> MemoryCandidate:
|
||||
"""Adapter from backend ``MemoryResult`` shape to ``MemoryCandidate``.
|
||||
|
||||
The backend returns objects with ``.score``, ``.memory.content``,
|
||||
``.memory.id``, and (optionally) ``.memory.created_at`` (str ISO
|
||||
timestamp) + ``.related_entities``. This adapter flattens that to
|
||||
the ranker's expected shape and parses the timestamp to
|
||||
``datetime``.
|
||||
|
||||
Missing / unparseable timestamps → ``None`` (recency-neutral).
|
||||
Missing IDs → ``""`` (rendered as ``[?]`` in the auto-tail block).
|
||||
"""
|
||||
score = float(getattr(result, "score", 0.0))
|
||||
memory = getattr(result, "memory", None)
|
||||
content = str(getattr(memory, "content", "")) if memory is not None else ""
|
||||
memory_id = str(getattr(memory, "id", "") or "") if memory is not None else ""
|
||||
raw_dt = getattr(memory, "created_at", None) if memory is not None else None
|
||||
created_at = parse_memory_created_at(raw_dt)
|
||||
raw_related = getattr(result, "related_entities", None) or ()
|
||||
related = tuple(str(x) for x in raw_related)
|
||||
source_meta = getattr(memory, "metadata", None) or {}
|
||||
source = source_meta.get("source") if isinstance(source_meta, dict) else None
|
||||
return cls(
|
||||
content=content,
|
||||
score=score,
|
||||
created_at=created_at,
|
||||
source=source,
|
||||
related_entities=related,
|
||||
id=memory_id,
|
||||
)
|
||||
|
||||
|
||||
def _parse_created_at(value: object) -> datetime | None:
|
||||
"""Best-effort parse of a timestamp into a UTC-aware datetime.
|
||||
|
||||
Accepts ``datetime`` (returned as-is, UTC-normalized) or ISO-8601
|
||||
string (with or without trailing ``Z``). Anything else → ``None``
|
||||
so the ranker treats the candidate as recency-neutral.
|
||||
"""
|
||||
return parse_memory_created_at(value)
|
||||
|
||||
|
||||
class MemoryRanker(Protocol):
|
||||
"""Re-ranks retrieval candidates. Pure function.
|
||||
|
||||
Implementations MUST:
|
||||
* Not mutate the input list or its elements
|
||||
* Be deterministic (same input → same output) for prefix-cache
|
||||
stability across consecutive turns
|
||||
* Be backend-agnostic — work with any
|
||||
:class:`MemoryCandidate`, regardless of which backend produced it
|
||||
"""
|
||||
|
||||
def rank(self, candidates: list[MemoryCandidate]) -> list[MemoryCandidate]: ...
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class RecencyBoostRanker:
|
||||
"""Re-ranker applying an exponential recency decay to cosine scores.
|
||||
|
||||
Final score: ``cosine × exp(-age_days / decay_days)``.
|
||||
|
||||
At ``decay_days=30``:
|
||||
* age = 0 days → factor 1.000
|
||||
* age = 15 days → factor 0.607
|
||||
* age = 30 days → factor 0.368
|
||||
* age = 60 days → factor 0.135
|
||||
* age = 90 days → factor 0.050
|
||||
|
||||
Tuned so a fresh memory with weak cosine doesn't dominate (factor
|
||||
decays gradually), but a 6-month-old strong-cosine can't dominate
|
||||
either (factor approaches zero). Operators tune ``decay_days`` for
|
||||
their codebase's rate of change — 7 days for rapidly-evolving
|
||||
repos, 90 days for stable archival.
|
||||
|
||||
Backwards-compat: candidates with ``created_at=None`` get factor
|
||||
1.0 — treated as recency-neutral. Lets a backend during a
|
||||
migration return some rows with timestamps and some without
|
||||
without breaking the ranker.
|
||||
|
||||
Defensive: negative ages (clock skew on future-timestamped rows)
|
||||
are clamped to factor 1.0 — a clock-skewed candidate cannot
|
||||
outrank a real fresh one with the same cosine.
|
||||
"""
|
||||
|
||||
decay_days: float = 30.0
|
||||
|
||||
def rank(self, candidates: list[MemoryCandidate]) -> list[MemoryCandidate]:
|
||||
"""Re-rank by ``score × recency_factor``. Pure; input unchanged.
|
||||
|
||||
Sorts descending by boosted score. Ties broken by input order
|
||||
(Python's sort is stable) — deterministic output for prefix-
|
||||
cache stability across turns.
|
||||
"""
|
||||
if not candidates:
|
||||
return []
|
||||
|
||||
now = datetime.now(_UTC)
|
||||
boosted: list[tuple[int, MemoryCandidate, float]] = []
|
||||
for idx, c in enumerate(candidates):
|
||||
new_score = boost_memory_score(
|
||||
score=c.score,
|
||||
now=now,
|
||||
created_at=c.created_at,
|
||||
decay_days=self.decay_days,
|
||||
)
|
||||
boosted.append((idx, c, new_score))
|
||||
|
||||
# Sort descending by boosted score; stable on ties via the
|
||||
# captured idx — same input order preserved on ties for
|
||||
# deterministic output across turns.
|
||||
boosted.sort(key=lambda triple: (-triple[2], triple[0]))
|
||||
|
||||
# Return new candidates with the boosted score so downstream
|
||||
# consumers (logging, budget filter) see the post-boost number.
|
||||
return [
|
||||
MemoryCandidate(
|
||||
content=c.content,
|
||||
score=new_score,
|
||||
created_at=c.created_at,
|
||||
source=c.source,
|
||||
related_entities=c.related_entities,
|
||||
id=c.id,
|
||||
)
|
||||
for _, c, new_score in boosted
|
||||
]
|
||||
|
||||
def _recency_factor(self, now: datetime, created_at: datetime | None) -> float:
|
||||
"""Compute the recency multiplier for a single candidate.
|
||||
|
||||
``None`` timestamp → 1.0 (recency-neutral, backwards-compat).
|
||||
Future timestamps → 1.0 (clock-skew defence).
|
||||
Otherwise: ``exp(-age_days / decay_days)``.
|
||||
"""
|
||||
return memory_recency_factor(
|
||||
now=now,
|
||||
created_at=created_at,
|
||||
decay_days=self.decay_days,
|
||||
)
|
||||
@@ -86,155 +86,6 @@ def make_result(
|
||||
)
|
||||
|
||||
|
||||
def test_resolve_native_path_blocks_traversal(handler: MemoryHandler) -> None:
|
||||
resolved = handler._resolve_native_path("/memories/topic.txt", "u1")
|
||||
assert resolved.name == "topic.txt"
|
||||
assert "u1" in str(resolved)
|
||||
|
||||
with pytest.raises(ValueError, match="Path traversal detected"):
|
||||
handler._resolve_native_path("/memories/../escape.txt", "u1")
|
||||
|
||||
|
||||
def test_native_view_lists_directory_and_reads_files(handler: MemoryHandler) -> None:
|
||||
root = handler._resolve_native_path("/memories", "u1")
|
||||
(root / "alpha.txt").write_text("line1\nline2\nline3", encoding="utf-8")
|
||||
(root / "nested").mkdir()
|
||||
(root / "nested" / "beta.txt").write_text("nested", encoding="utf-8")
|
||||
(root / ".hidden").write_text("skip", encoding="utf-8")
|
||||
(root / "node_modules").mkdir()
|
||||
|
||||
listing = handler._native_view({"path": "/memories"}, "u1")
|
||||
assert "/memories/alpha.txt" in listing
|
||||
assert "/memories/nested/beta.txt" in listing
|
||||
assert ".hidden" not in listing
|
||||
assert "/memories/node_modules" not in listing
|
||||
|
||||
file_view = handler._native_view({"path": "/memories/alpha.txt", "view_range": [2, 3]}, "u1")
|
||||
assert "2\tline2" in file_view
|
||||
assert "3\tline3" in file_view
|
||||
|
||||
|
||||
def test_native_view_handles_missing_paths_and_latin1(handler: MemoryHandler) -> None:
|
||||
missing = handler._native_view({"path": "/memories/missing.txt"}, "u1")
|
||||
assert "does not exist" in missing
|
||||
|
||||
latin_path = handler._resolve_native_path("/memories/latin.txt", "u1")
|
||||
latin_path.write_bytes("caf\xe9".encode("latin-1"))
|
||||
viewed = handler._native_view({"path": "/memories/latin.txt"}, "u1")
|
||||
assert "cafe" not in viewed
|
||||
assert "café" in viewed
|
||||
|
||||
|
||||
def test_native_create_insert_delete_and_rename(handler: MemoryHandler) -> None:
|
||||
assert handler._native_create(
|
||||
{"path": "/memories/note.txt", "file_text": "a\nb"}, "u1"
|
||||
).startswith("File created successfully")
|
||||
assert handler._native_create(
|
||||
{"path": "/memories/note.txt", "file_text": "dup"}, "u1"
|
||||
).startswith("Error: File /memories/note.txt already exists")
|
||||
|
||||
inserted = handler._native_insert(
|
||||
{"path": "/memories/note.txt", "insert_line": 1, "insert_text": "middle"},
|
||||
"u1",
|
||||
)
|
||||
assert inserted == "The file /memories/note.txt has been edited."
|
||||
assert "middle" in handler._resolve_native_path("/memories/note.txt", "u1").read_text(
|
||||
encoding="utf-8"
|
||||
)
|
||||
|
||||
renamed = handler._native_rename(
|
||||
{"old_path": "/memories/note.txt", "new_path": "/memories/archive/renamed.txt"},
|
||||
"u1",
|
||||
)
|
||||
assert renamed == "Successfully renamed /memories/note.txt to /memories/archive/renamed.txt"
|
||||
|
||||
deleted = handler._native_delete_file({"path": "/memories/archive"}, "u1")
|
||||
assert deleted == "Successfully deleted /memories/archive"
|
||||
|
||||
|
||||
def test_native_insert_validates_range_and_path(handler: MemoryHandler) -> None:
|
||||
assert (
|
||||
handler._native_insert({"insert_line": 0, "insert_text": "x"}, "u1")
|
||||
== "Error: path is required"
|
||||
)
|
||||
assert "does not exist" in handler._native_insert(
|
||||
{"path": "/memories/missing.txt", "insert_line": 0, "insert_text": "x"},
|
||||
"u1",
|
||||
)
|
||||
|
||||
note = handler._resolve_native_path("/memories/note.txt", "u1")
|
||||
note.write_text("a\nb", encoding="utf-8")
|
||||
invalid = handler._native_insert(
|
||||
{"path": "/memories/note.txt", "insert_line": 4, "insert_text": "x"},
|
||||
"u1",
|
||||
)
|
||||
assert "Invalid `insert_line` parameter: 4" in invalid
|
||||
|
||||
|
||||
def test_native_str_replace_covers_missing_multiple_and_success(handler: MemoryHandler) -> None:
|
||||
note = handler._resolve_native_path("/memories/note.txt", "u1")
|
||||
note.write_text("hello\nhello\nworld", encoding="utf-8")
|
||||
|
||||
assert (
|
||||
handler._native_str_replace({"old_str": "hello", "new_str": "bye"}, "u1")
|
||||
== "Error: path is required"
|
||||
)
|
||||
assert (
|
||||
handler._native_str_replace({"path": "/memories/note.txt", "new_str": "bye"}, "u1")
|
||||
== "Error: old_str is required"
|
||||
)
|
||||
|
||||
multiple = handler._native_str_replace(
|
||||
{"path": "/memories/note.txt", "old_str": "hello", "new_str": "bye"},
|
||||
"u1",
|
||||
)
|
||||
assert "Multiple occurrences of old_str `hello` in lines: 1, 2" in multiple
|
||||
|
||||
note.write_text("hello\nworld", encoding="utf-8")
|
||||
missing = handler._native_str_replace(
|
||||
{"path": "/memories/note.txt", "old_str": "nope", "new_str": "bye"},
|
||||
"u1",
|
||||
)
|
||||
assert "did not appear verbatim" in missing
|
||||
|
||||
success = handler._native_str_replace(
|
||||
{"path": "/memories/note.txt", "old_str": "hello", "new_str": "bye"},
|
||||
"u1",
|
||||
)
|
||||
assert "The memory file has been edited." in success
|
||||
assert "bye" in note.read_text(encoding="utf-8")
|
||||
|
||||
|
||||
def test_native_delete_and_rename_validate_inputs(handler: MemoryHandler) -> None:
|
||||
assert handler._native_delete_file({}, "u1") == "Error: path is required"
|
||||
assert "does not exist" in handler._native_delete_file({"path": "/memories/missing.txt"}, "u1")
|
||||
|
||||
assert (
|
||||
handler._native_rename({"new_path": "/memories/new.txt"}, "u1")
|
||||
== "Error: old_path is required"
|
||||
)
|
||||
assert (
|
||||
handler._native_rename({"old_path": "/memories/old.txt"}, "u1")
|
||||
== "Error: new_path is required"
|
||||
)
|
||||
assert "does not exist" in handler._native_rename(
|
||||
{"old_path": "/memories/old.txt", "new_path": "/memories/new.txt"},
|
||||
"u1",
|
||||
)
|
||||
|
||||
old = handler._resolve_native_path("/memories/old.txt", "u1")
|
||||
new = handler._resolve_native_path("/memories/new.txt", "u1")
|
||||
old.write_text("x", encoding="utf-8")
|
||||
new.write_text("y", encoding="utf-8")
|
||||
assert (
|
||||
handler._native_rename(
|
||||
{"old_path": "/memories/old.txt", "new_path": "/memories/new.txt"},
|
||||
"u1",
|
||||
)
|
||||
== "Error: The destination /memories/new.txt already exists"
|
||||
)
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_execute_native_memory_tool_dispatches_and_wraps_errors(
|
||||
handler: MemoryHandler, monkeypatch: pytest.MonkeyPatch
|
||||
|
||||
@@ -1,293 +0,0 @@
|
||||
"""Tests for :class:`headroom.proxy.memory_ranker.MemoryRanker` +
|
||||
:class:`RecencyBoostRanker`.
|
||||
|
||||
Pre-this-PR Headroom ranked memory candidates by pure cosine
|
||||
similarity. Every other memory system we surveyed (Letta, Mem0,
|
||||
Cognee, Supermemory) re-ranks beyond cosine — recency / source /
|
||||
access-count / decay are table-stakes. The pure-cosine baseline
|
||||
returns 6-month-old memories with 0.9 similarity ahead of fresh
|
||||
memories with 0.5 — wrong for most use cases.
|
||||
|
||||
``RecencyBoostRanker`` is the first ranker we ship: a pure-function
|
||||
``score = cosine × exp(-age_days / decay_days)`` re-ranker. Default
|
||||
``decay_days=30`` (half-life ~21 days). Other rankers (source-weight,
|
||||
access-count) plug into the same :class:`MemoryRanker` protocol in
|
||||
follow-on PRs.
|
||||
|
||||
Performance: O(N) over candidates where N = top_k = ~10. One ``exp()``
|
||||
per candidate. Sub-microsecond per request — no embedding compute, no
|
||||
I/O. The ranker is pure and Rust-portable.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import FrozenInstanceError
|
||||
from datetime import datetime, timedelta, timezone
|
||||
|
||||
from headroom.proxy.memory_ranker import (
|
||||
MemoryCandidate,
|
||||
RecencyBoostRanker,
|
||||
)
|
||||
|
||||
_UTC = timezone.utc
|
||||
|
||||
# ── Helpers ───────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def _candidate(content: str, score: float, age_days: float = 0.0) -> MemoryCandidate:
|
||||
"""Build a MemoryCandidate at the given cosine score and age."""
|
||||
created = datetime.now(_UTC) - timedelta(days=age_days)
|
||||
return MemoryCandidate(content=content, score=score, created_at=created)
|
||||
|
||||
|
||||
def _candidate_no_timestamp(content: str, score: float) -> MemoryCandidate:
|
||||
"""Build a MemoryCandidate without a created_at (back-compat shape)."""
|
||||
return MemoryCandidate(content=content, score=score, created_at=None)
|
||||
|
||||
|
||||
# ── MemoryCandidate value-type contract ──────────────────────────────
|
||||
|
||||
|
||||
def test_candidate_is_frozen() -> None:
|
||||
"""Frozen so a ranker can't mutate a candidate's score and lie about
|
||||
which candidates it returned."""
|
||||
c = _candidate("x", 0.9, age_days=0)
|
||||
try:
|
||||
c.score = 0.1 # type: ignore[misc]
|
||||
except FrozenInstanceError:
|
||||
pass
|
||||
else:
|
||||
raise AssertionError("MemoryCandidate must be frozen")
|
||||
|
||||
|
||||
def test_from_backend_result_preserves_memory_id() -> None:
|
||||
"""The adapter must carry ``memory.id`` through to MemoryCandidate.id
|
||||
so the auto-tail block can render it as the bracketed handle the
|
||||
model uses for memory_update / memory_delete. Pre-this-fix the
|
||||
adapter dropped the ID, which silently regressed the [id] auto-tail
|
||||
format on the ranker path."""
|
||||
|
||||
class _Mem:
|
||||
id = "mem_abc_123"
|
||||
content = "User prefers Python."
|
||||
created_at = None
|
||||
metadata = {"source": "memory_save"}
|
||||
|
||||
class _Result:
|
||||
memory = _Mem()
|
||||
score = 0.91
|
||||
related_entities = ("python",)
|
||||
|
||||
cand = MemoryCandidate.from_backend_result(_Result())
|
||||
assert cand.id == "mem_abc_123"
|
||||
assert cand.content == "User prefers Python."
|
||||
assert cand.score == 0.91
|
||||
|
||||
|
||||
def test_rank_preserves_memory_id() -> None:
|
||||
"""The ranker must not drop the backend ID when rebuilding candidates."""
|
||||
cand = MemoryCandidate(content="User prefers Python.", score=0.91, id="mem_abc_123")
|
||||
out = RecencyBoostRanker().rank([cand])
|
||||
assert out[0].id == "mem_abc_123"
|
||||
|
||||
|
||||
def test_from_backend_result_handles_missing_id() -> None:
|
||||
"""Defensive: legacy backend rows without an ID become ``id=""``;
|
||||
the auto-tail formatter renders ``[?]`` for those rows, no crash."""
|
||||
|
||||
class _Mem:
|
||||
# no .id attribute
|
||||
content = "legacy row"
|
||||
created_at = None
|
||||
metadata = {}
|
||||
|
||||
class _Result:
|
||||
memory = _Mem()
|
||||
score = 0.5
|
||||
related_entities = ()
|
||||
|
||||
cand = MemoryCandidate.from_backend_result(_Result())
|
||||
assert cand.id == ""
|
||||
|
||||
|
||||
# ── RecencyBoostRanker contract ──────────────────────────────────────
|
||||
|
||||
|
||||
def test_ranker_is_frozen() -> None:
|
||||
"""The ranker config is itself immutable — operators set
|
||||
``decay_days`` at construction; runtime cannot edit it."""
|
||||
r = RecencyBoostRanker()
|
||||
try:
|
||||
r.decay_days = 99 # type: ignore[misc]
|
||||
except FrozenInstanceError:
|
||||
pass
|
||||
else:
|
||||
raise AssertionError("RecencyBoostRanker must be frozen")
|
||||
|
||||
|
||||
def test_ranker_default_decay_is_thirty_days() -> None:
|
||||
"""30-day decay is the conservative default. At 30 days, factor is
|
||||
~0.37 (e^{-1}); at 90 days, ~0.05. Tuned so a fresh memory with
|
||||
weak cosine doesn't dominate, but a 6-month-old strong-cosine
|
||||
can't dominate either."""
|
||||
assert RecencyBoostRanker().decay_days == 30.0
|
||||
|
||||
|
||||
def test_ranker_default_decay_is_configurable() -> None:
|
||||
"""Operators can tune decay; e.g., 7 days for an aggressive
|
||||
recency bias on rapidly-evolving codebases."""
|
||||
r = RecencyBoostRanker(decay_days=7.0)
|
||||
assert r.decay_days == 7.0
|
||||
|
||||
|
||||
def test_ranker_returns_list_preserving_shape() -> None:
|
||||
"""Output is a list of candidates (re-ranked). Length matches
|
||||
input length — the ranker does NOT filter, only re-orders. The
|
||||
budget filters; the ranker ranks."""
|
||||
candidates = [_candidate("a", 0.9), _candidate("b", 0.5)]
|
||||
out = RecencyBoostRanker().rank(candidates)
|
||||
assert len(out) == 2
|
||||
assert {c.content for c in out} == {"a", "b"}
|
||||
|
||||
|
||||
# ── Recency boost behaviour ──────────────────────────────────────────
|
||||
|
||||
|
||||
def test_equal_cosine_younger_wins() -> None:
|
||||
"""Two candidates with identical cosine score — the younger one
|
||||
wins because its recency factor is closer to 1.0."""
|
||||
fresh = _candidate("fresh", 0.5, age_days=0)
|
||||
old = _candidate("old", 0.5, age_days=60)
|
||||
out = RecencyBoostRanker().rank([old, fresh])
|
||||
assert out[0].content == "fresh"
|
||||
assert out[1].content == "old"
|
||||
|
||||
|
||||
def test_old_strong_cosine_can_still_beat_young_weak_cosine() -> None:
|
||||
"""The boost is multiplicative, not absolute — a 60-day-old memory
|
||||
with 0.9 cosine (0.9 × 0.135 ≈ 0.12) still loses to a 0-day-old
|
||||
memory with 0.5 cosine (0.5 × 1.0 = 0.5). But a 5-day-old memory
|
||||
with 0.9 (0.9 × 0.847 ≈ 0.76) beats a 0-day-old with 0.5."""
|
||||
very_old_strong = _candidate("old_strong", 0.9, age_days=60)
|
||||
fresh_weak = _candidate("fresh_weak", 0.5, age_days=0)
|
||||
out = RecencyBoostRanker().rank([very_old_strong, fresh_weak])
|
||||
# fresh_weak should win because 60-day decay flattens the strong cosine
|
||||
assert out[0].content == "fresh_weak"
|
||||
|
||||
# Versus: slightly-old strong beats fresh weak
|
||||
slightly_old_strong = _candidate("slightly_old_strong", 0.9, age_days=5)
|
||||
fresh_weak2 = _candidate("fresh_weak2", 0.5, age_days=0)
|
||||
out2 = RecencyBoostRanker().rank([fresh_weak2, slightly_old_strong])
|
||||
assert out2[0].content == "slightly_old_strong"
|
||||
|
||||
|
||||
def test_decay_rate_changes_winner() -> None:
|
||||
"""An aggressive decay_days=7 makes a 30-day-old memory much
|
||||
weaker than a default decay_days=30. Locks the configurability
|
||||
contract."""
|
||||
old_strong = _candidate("old_strong", 0.9, age_days=30)
|
||||
fresh_weak = _candidate("fresh_weak", 0.6, age_days=0)
|
||||
|
||||
# decay_days=30: old × e^{-1} ≈ 0.331; fresh = 0.6 → fresh wins
|
||||
r_default = RecencyBoostRanker(decay_days=30.0)
|
||||
out_default = r_default.rank([old_strong, fresh_weak])
|
||||
assert out_default[0].content == "fresh_weak"
|
||||
|
||||
# decay_days=120 (loose): old × e^{-0.25} ≈ 0.701; fresh = 0.6 → old wins
|
||||
r_loose = RecencyBoostRanker(decay_days=120.0)
|
||||
out_loose = r_loose.rank([old_strong, fresh_weak])
|
||||
assert out_loose[0].content == "old_strong"
|
||||
|
||||
|
||||
def test_zero_age_memory_keeps_full_cosine() -> None:
|
||||
"""At age=0 days, the recency factor is e^0 = 1.0 — the boosted
|
||||
score equals the original cosine. Fresh memories see no penalty."""
|
||||
fresh = _candidate("fresh", 0.7, age_days=0)
|
||||
out = RecencyBoostRanker().rank([fresh])
|
||||
# Compare with tolerance — datetime.now() drift between
|
||||
# _candidate() and rank() is microseconds, so factor ~ 1.0.
|
||||
assert out[0].score == 0.7 or abs(out[0].score - 0.7) < 1e-3
|
||||
|
||||
|
||||
def test_candidate_without_timestamp_keeps_pure_cosine() -> None:
|
||||
"""Backwards-compat: pre-this-PR candidates may not have a
|
||||
``created_at`` (older rows / older backends). NULL timestamp
|
||||
means "treat as recency-neutral" — factor 1.0. Pure cosine."""
|
||||
no_ts = _candidate_no_timestamp("legacy", 0.8)
|
||||
out = RecencyBoostRanker().rank([no_ts])
|
||||
assert out[0].score == 0.8
|
||||
|
||||
|
||||
def test_mixed_with_and_without_timestamps() -> None:
|
||||
"""A backend that returns SOME candidates with timestamps and
|
||||
SOME without (e.g., during a migration) must still produce a
|
||||
sensible ranking. NULL-timestamp candidates get factor 1.0,
|
||||
timestamped ones get their decay."""
|
||||
fresh_ts = _candidate("fresh_ts", 0.6, age_days=0)
|
||||
old_ts = _candidate("old_ts", 0.6, age_days=60)
|
||||
no_ts_neutral = _candidate_no_timestamp("no_ts", 0.6)
|
||||
out = RecencyBoostRanker().rank([old_ts, no_ts_neutral, fresh_ts])
|
||||
# fresh_ts (~0.6) and no_ts (=0.6) tied at top — old_ts decayed.
|
||||
assert out[-1].content == "old_ts"
|
||||
assert {out[0].content, out[1].content} == {"fresh_ts", "no_ts"}
|
||||
|
||||
|
||||
# ── Stability + edge cases ───────────────────────────────────────────
|
||||
|
||||
|
||||
def test_empty_input_returns_empty_output() -> None:
|
||||
"""No candidates → no candidates. Boundary case."""
|
||||
assert RecencyBoostRanker().rank([]) == []
|
||||
|
||||
|
||||
def test_ranking_is_stable_for_identical_candidates() -> None:
|
||||
"""Two candidates with identical content + score + age → stable
|
||||
order (no spurious reshuffling). Important for prefix-cache
|
||||
stability: a deterministic ranker means consecutive turns inject
|
||||
the same memory in the same order, preserving byte-stable
|
||||
output."""
|
||||
a = _candidate("same", 0.5, age_days=10)
|
||||
b = _candidate("same", 0.5, age_days=10)
|
||||
out = RecencyBoostRanker().rank([a, b])
|
||||
assert len(out) == 2
|
||||
|
||||
|
||||
def test_negative_age_treated_as_zero() -> None:
|
||||
"""Defensive: a candidate with a future ``created_at`` (clock
|
||||
skew) shouldn't crash or give a > 1.0 factor. ``exp(-age/decay)``
|
||||
with negative age gives > 1; we clamp to 1.0 so a clock-skewed
|
||||
candidate can't outrank a real fresh one with score=1.0
|
||||
artifically."""
|
||||
future = _candidate("future", 0.5, age_days=-10) # 10 days in future
|
||||
fresh = _candidate("fresh", 0.5, age_days=0)
|
||||
out = RecencyBoostRanker().rank([future, fresh])
|
||||
# Both should have factor 1.0 (clamped) — score equal → stable order
|
||||
assert {out[0].content, out[1].content} == {"future", "fresh"}
|
||||
assert out[0].score == 0.5 or abs(out[0].score - 0.5) < 1e-3
|
||||
|
||||
|
||||
# ── Rust-port shape ─────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_ranker_is_pure_no_side_effects() -> None:
|
||||
"""Calling rank() twice with the same input gives the same
|
||||
output. No state on the ranker; no I/O. Rust-portable."""
|
||||
candidates = [_candidate("a", 0.7, age_days=5), _candidate("b", 0.5, age_days=20)]
|
||||
r = RecencyBoostRanker()
|
||||
out1 = r.rank(candidates)
|
||||
out2 = r.rank(candidates)
|
||||
assert [c.content for c in out1] == [c.content for c in out2]
|
||||
# Inputs preserved — ranker did not mutate
|
||||
assert candidates[0].content == "a"
|
||||
assert candidates[1].content == "b"
|
||||
|
||||
|
||||
def test_ranker_does_not_mutate_input_list() -> None:
|
||||
"""Defence-in-depth: the input list and its elements must be
|
||||
unchanged after ranking. Frozen candidates make element mutation
|
||||
impossible; the list order itself must also be preserved."""
|
||||
a = _candidate("a", 0.5, age_days=20)
|
||||
b = _candidate("b", 0.5, age_days=5)
|
||||
candidates = [a, b]
|
||||
RecencyBoostRanker().rank(candidates)
|
||||
assert candidates == [a, b] # original list order preserved
|
||||
Reference in New Issue
Block a user