structuremappingmemory 1.0.0__py3-none-any.whl

sma/eval/agentic_qa/pools.py

@@ -0,0 +1,197 @@
+"""Registered question pools for the Phase 5 LLM-QA "trustworthy specialist" phase.
+
+This builds the three pre-registered question pools of
+``configs/preregistration_v2_llmqa.md`` from the flagship medicine arm
+(HPO + ``phenotype.hpoa``), holding the index fixed so attribution stays clean:
+
+* **answerable** — cases whose true disease IS indexed (the agent should answer + cite);
+* **out-of-knowledge / novel** — cases whose true disease is HELD OUT of the index
+  (the agent should ABSTAIN *and* flag NOVEL). The held-out cases are, by
+  construction, both unanswerable and novel, so ``ook`` and ``novel`` are the
+  same list of :class:`QAItem`.
+
+Each clinical case is a *hard* partial/imprecise observation generated exactly
+like ``sma/eval/ontology_bench.run_arm``: sample a few of the disease's
+phenotypes, climb 0-2 is-a levels (imprecision), and add a few noise terms, then
+render the surviving terms as a natural-language presentation. Determinism: every
+``set`` is sorted to a list before use and the single RNG is explicitly seeded,
+so identical ``(seed, n_index, ...)`` yields identical pools.
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass, field
+
+from sma.ontology import MountedOntology
+
+
+@dataclass
+class QAItem:
+    """One pre-registered LLM-QA case.
+
+    ``case_text`` is the NL presentation shown to the agent; ``case_terms`` are
+    the (possibly climbed/noised) ontology term ids backing it; ``gold_id`` /
+    ``gold_name`` are the true disease. ``answerable`` is True iff the gold
+    disease is indexed; ``novel`` is True iff the gold disease was held out.
+    """
+
+    case_text: str
+    case_terms: frozenset[str]
+    gold_id: str
+    gold_name: str
+    answerable: bool
+    novel: bool
+
+
+def _parse_hpoa(hpoa_path: str) -> dict[str, tuple[str, set[str]]]:
+    """Parse ``phenotype.hpoa`` into ``disease_id -> (name, {hpo_term_id})``.
+
+    Mirrors the flagship record construction (medicine arm /
+    ``scripts/bench_ontology_suite.load_hpo_records``): skip header/comment
+    lines, tab-split, keep only phenotypic-abnormality rows (column 10 == ``"P"``),
+    and read column 0 as the disease id, column 1 as the disease name, column 3
+    as the HPO term.
+    """
+    rec: dict[str, tuple[str, set[str]]] = {}
+    with open(hpoa_path, "r", encoding="utf-8") as handle:
+        for line in handle:
+            if line.startswith(("#", "database_id")):
+                continue
+            p = line.rstrip("\n").split("\t")
+            if len(p) < 11 or p[10] != "P":
+                continue
+            disease_id, disease_name, hpo_term = p[0], p[1], p[3]
+            name, terms = rec.setdefault(disease_id, (disease_name, set()))
+            terms.add(hpo_term)
+    return rec
+
+
+def build_pools(
+    mounted: MountedOntology,
+    hpoa_path: str,
+    *,
+    seed: int = 7,
+    n_index: int = 1500,
+    n_answerable: int = 120,
+    n_held: int = 120,
+    n_calib: int = 60,
+    min_ph: int = 7,
+    max_ph: int = 30,
+) -> dict:
+    """Build the registered LLM-QA pools over the medicine (HPO) arm.
+
+    ``mounted`` is the mounted HPO ontology; ``hpoa_path`` points at
+    ``phenotype.hpoa``. Returns a dict with keys:
+
+    * ``"index_items"`` — ``list[IndexItem]`` for the INDEXED diseases (the
+      shared knowledge every memory is built over);
+    * ``"answerable"`` — ``n_answerable`` :class:`QAItem`\\ s drawn from INDEXED
+      diseases (``answerable=True, novel=False``);
+    * ``"ook"`` / ``"novel"`` — ``n_held`` :class:`QAItem`\\ s drawn from
+      HELD-OUT diseases (``answerable=False, novel=True``); the same list is
+      returned under both keys because held-out cases are both unanswerable and
+      novel.
+    * ``"calib_answerable"`` / ``"calib_ook"`` — up to ``n_calib`` :class:`QAItem`\\
+      s each, drawn from the SPARE indexed / held-out diseases (disjoint from the
+      test pools above). The driver scores these retrieval-only (no LLM spend) to
+      calibrate the cite-or-abstain threshold without ever touching the test
+      split. Empty when no spare diseases remain.
+
+    Eligible diseases carry ``min_ph..max_ph`` phenotypes that are present in
+    ``mounted.graph.terms``; their ids are sorted then shuffled under ``seed``.
+    The first ``n_index`` are INDEXED; the remainder are HELD-OUT. The test pools
+    are drawn first (so their cases are unchanged by ``n_calib``), then the
+    calibration pools from the remaining ids.
+    """
+    # Local import keeps this module importable even while the sibling
+    # agentic_qa.metrics is mid-construction (the package __init__ imports it).
+    from sma.eval.agentic import IndexItem
+
+    graph = mounted.graph
+
+    def term_text(t: str) -> str:
+        nm = graph.terms[t].name if t in graph.terms else ""
+        return nm or t
+
+    parents = {tid: tuple(term.parents) for tid, term in graph.terms.items()}
+    parsed = _parse_hpoa(hpoa_path)
+
+    # Eligibility: known phenotypes only, count in [min_ph, max_ph]. SORTED ids.
+    known: dict[str, tuple[str, list[str]]] = {}
+    for did in sorted(parsed):
+        name, terms = parsed[did]
+        present = sorted(t for t in terms if t in graph.terms)
+        if min_ph <= len(present) <= max_ph:
+            known[did] = (name, present)
+
+    eligible = sorted(known)
+    rng = random.Random(seed)
+    rng.shuffle(eligible)
+
+    indexed_ids = eligible[:n_index]
+    held_ids = eligible[n_index:]
+
+    # Shared index: IndexItem(key=id, term_ids, text=space-joined term NAMES, meta).
+    index_items = [
+        IndexItem(
+            key=did,
+            term_ids=frozenset(known[did][1]),
+            text=" ".join(term_text(t) for t in known[did][1]),
+            meta={"name": known[did][0]},
+        )
+        for did in indexed_ids
+    ]
+
+    # Noise pool: every phenotype present across the INDEXED diseases (SORTED), so
+    # injected distractors are in-vocabulary, matching the ontology_bench generator.
+    noise_pool = sorted({t for did in indexed_ids for t in known[did][1]})
+
+    def make_case(terms: list[str]) -> tuple[frozenset[str], str]:
+        """Hard query: sample <=5 phenotypes, climb 0-2 is-a levels, +3 noise."""
+        keep = rng.sample(terms, min(5, len(terms)))
+        q: list[str] = []
+        for t in keep:
+            cur = t
+            for _ in range(rng.choice([0, 0, 1, 1, 2])):
+                ps = parents.get(cur)
+                if ps:
+                    cur = rng.choice(sorted(ps))
+            q.append(cur)
+        if noise_pool:
+            q += rng.sample(noise_pool, min(3, len(noise_pool)))
+        text = "Patient presents with: " + ", ".join(term_text(t) for t in q)
+        return frozenset(q), text
+
+    def qitems(ids: list[str], n: int, *, answerable: bool) -> list[QAItem]:
+        out: list[QAItem] = []
+        for did in ids[:n]:
+            name, terms = known[did]
+            case_terms, case_text = make_case(terms)
+            out.append(
+                QAItem(
+                    case_text=case_text,
+                    case_terms=case_terms,
+                    gold_id=did,
+                    gold_name=name,
+                    answerable=answerable,
+                    novel=not answerable,
+                )
+            )
+        return out
+
+    answerable = qitems(indexed_ids, n_answerable, answerable=True)
+    novel = qitems(held_ids, n_held, answerable=False)
+    # Calibration pools: SPARE ids beyond the test draws (disjoint), scored
+    # retrieval-only to fit the abstention threshold without test-set leakage.
+    calib_answerable = qitems(indexed_ids[n_answerable:], n_calib, answerable=True)
+    calib_ook = qitems(held_ids[n_held:], n_calib, answerable=False)
+
+    return {
+        "index_items": index_items,
+        "answerable": answerable,
+        "ook": novel,
+        "novel": novel,
+        "calib_answerable": calib_answerable,
+        "calib_ook": calib_ook,
+    }

sma/eval/arn.py

@@ -0,0 +1,65 @@
+"""ARN dataset helpers."""
+
+from __future__ import annotations
+
+import csv
+import pathlib
+
+
+DEFAULT_ARN_PATH = pathlib.Path(
+    "data/raw/arn/Analogical Reasoning on Narratives (ARN) dataset.xlsx - Sheet1.csv"
+)
+
+ARN_REQUIRED_COLUMNS = {
+    "id",
+    "proverb",
+    "query_narrative",
+    "first_choice",
+    "second_choice",
+    "distractor_similarity",
+    "analogy_level",
+    "correct_answer",
+}
+
+
+def validate_columns(columns: list[str]) -> bool:
+    return ARN_REQUIRED_COLUMNS.issubset(set(columns))
+
+
+def load_arn_rows(path: str | pathlib.Path = DEFAULT_ARN_PATH, limit: int | None = None) -> list[dict[str, str]]:
+    source = pathlib.Path(path)
+    with source.open(encoding="utf-8-sig", newline="") as fh:
+        reader = csv.DictReader(fh)
+        if not reader.fieldnames or not validate_columns(reader.fieldnames):
+            raise ValueError(f"ARN CSV has unexpected columns: {reader.fieldnames}")
+        rows = []
+        for row in reader:
+            rows.append(dict(row))
+            if limit is not None and len(rows) >= limit:
+                break
+        return rows
+
+
+def arn_choice_corpus(path: str | pathlib.Path = DEFAULT_ARN_PATH, limit: int = 12) -> tuple[str, str]:
+    """Return a raw text corpus of answer choices plus one suggested query."""
+
+    rows = load_arn_rows(path, limit=limit)
+    blocks: list[str] = []
+    suggested_query = ""
+    for row in rows:
+        if not suggested_query:
+            suggested_query = row["query_narrative"]
+        correct = row["correct_answer"].strip()
+        for choice_number, column in (("1", "first_choice"), ("2", "second_choice")):
+            label = "correct" if choice_number == correct else "distractor"
+            blocks.append(
+                "\n".join(
+                    [
+                        f"ARN id={row['id']} choice={choice_number} label={label}",
+                        f"proverb: {row['proverb']}",
+                        f"analogy_level: {row['analogy_level']}",
+                        row[column],
+                    ]
+                )
+            )
+    return "\n\n".join(blocks), suggested_query

sma/eval/baselines/__init__.py

@@ -0,0 +1,6 @@
+"""Baseline retrieval implementations for the LogHub evaluation ladder.
+
+Modules here are deliberately self-contained: each baseline owns its model
+loading and scoring so `scripts/baseline_ladder.py` can compose them under the
+exact protocol of `sma.eval.loghub_eval` without touching that file.
+"""

sma/eval/baselines/bge_dense.py

@@ -0,0 +1,54 @@
+"""Dense retrieval with BAAI/bge-base-en-v1.5 (blueprint B2's specified embedder).
+
+CPU-only. Index embeddings are batch-encoded once; queries are encoded per
+call so per-query latency includes the real encode cost (same convention as
+the MiniLM dense baseline in sma.eval.loghub_eval).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+MODEL_NAME = "BAAI/bge-base-en-v1.5"
+# Per the BGE model card, short queries in retrieval tasks should carry this
+# instruction prefix; documents are encoded without it.
+QUERY_PREFIX = "Represent this sentence for searching relevant passages: "
+
+
+class BGEDenseRetriever:
+    def __init__(self, model_name: str = MODEL_NAME, batch_size: int = 16):
+        from sentence_transformers import SentenceTransformer
+
+        self.model = SentenceTransformer(model_name, device="cpu")
+        self.batch_size = batch_size
+        self.doc_ids: list[str] = []
+        self.doc_matrix: np.ndarray | None = None
+
+    def build(self, documents: list[tuple[str, str]]) -> None:
+        self.doc_ids = [doc_id for doc_id, _ in documents]
+        texts = [text for _, text in documents]
+        self.doc_matrix = self.model.encode(
+            texts,
+            batch_size=self.batch_size,
+            convert_to_numpy=True,
+            normalize_embeddings=True,
+            show_progress_bar=False,
+        )
+
+    def encode_query(self, query_text: str) -> np.ndarray:
+        return self.model.encode(
+            [QUERY_PREFIX + query_text],
+            convert_to_numpy=True,
+            normalize_embeddings=True,
+            show_progress_bar=False,
+        )[0]
+
+    def retrieve(self, query_text: str, k: int = 10) -> list[tuple[str, float]]:
+        if self.doc_matrix is None:
+            return []
+        q = self.encode_query(query_text)
+        scores = self.doc_matrix @ q  # cosine: both sides L2-normalized
+        ranked = sorted(
+            zip(self.doc_ids, map(float, scores)), key=lambda row: (-row[1], row[0])
+        )
+        return ranked[:k]

sma/eval/baselines/bm25.py

@@ -0,0 +1,18 @@
+"""Simple lexical baseline."""
+
+from __future__ import annotations
+
+from collections import Counter
+
+
+def lexical_score(query: str, document: str) -> float:
+    q = Counter(query.lower().split())
+    d = Counter(document.lower().split())
+    return sum(min(v, d.get(k, 0)) for k, v in q.items())
+
+
+def rank_bm25_like(query: str, documents: list[tuple[str, str]], k: int = 10) -> list[tuple[str, float]]:
+    rows = [(doc_id, lexical_score(query, text)) for doc_id, text in documents]
+    rows.sort(key=lambda row: (-row[1], row[0]))
+    return rows[:k]
+

sma/eval/baselines/dense.py

@@ -0,0 +1,42 @@
+"""Dense-RAG style baseline with local deterministic TF-IDF fallback.
+
+This is not the final sentence-transformer baseline from the paper plan. It is
+the CPU-safe baseline used in MVP reports when no embedding model is installed.
+"""
+
+from __future__ import annotations
+
+from sklearn.feature_extraction.text import TfidfVectorizer
+from sklearn.metrics.pairwise import cosine_similarity
+
+
+def rank_tfidf_dense(query: str, documents: list[tuple[str, str]], k: int = 10) -> list[tuple[str, float]]:
+    if not documents:
+        return []
+    ids = [doc_id for doc_id, _ in documents]
+    texts = [text for _, text in documents]
+    vectorizer = TfidfVectorizer(ngram_range=(1, 2), lowercase=True)
+    matrix = vectorizer.fit_transform(texts + [query])
+    sims = cosine_similarity(matrix[-1], matrix[:-1]).ravel()
+    rows = list(zip(ids, map(float, sims)))
+    rows.sort(key=lambda row: (-row[1], row[0]))
+    return rows[:k]
+
+
+def rank_tfidf_dense_batch(queries: list[str], documents: list[tuple[str, str]], k: int = 10) -> list[list[tuple[str, float]]]:
+    if not documents:
+        return [[] for _ in queries]
+    ids = [doc_id for doc_id, _ in documents]
+    texts = [text for _, text in documents]
+    vectorizer = TfidfVectorizer(ngram_range=(1, 2), lowercase=True)
+    doc_matrix = vectorizer.fit_transform(texts)
+    query_matrix = vectorizer.transform(queries)
+    sims = query_matrix @ doc_matrix.T
+    ranked: list[list[tuple[str, float]]] = []
+    for row_idx in range(sims.shape[0]):
+        row = sims.getrow(row_idx)
+        scores = row.toarray().ravel()
+        pairs = list(zip(ids, map(float, scores)))
+        pairs.sort(key=lambda item: (-item[1], item[0]))
+        ranked.append(pairs[:k])
+    return ranked

sma/eval/baselines/hipporag.py

@@ -0,0 +1,235 @@
+"""HippoRAG-2-style KG retrieval comparator (blueprint B5, deterministic adaptation).
+
+Adapted from HippoRAG / HippoRAG 2 (Gutierrez et al., NeurIPS'24 / ICML'25):
+  - a phrase graph over OpenIE triples with passage (document) nodes,
+  - synonym edges linking near-identical phrases,
+  - Personalized PageRank (damping 0.5, as published) with personalization
+    mass on query phrase nodes, weighted by node specificity 1/df
+    (HippoRAG's inverse passage-frequency seed weighting),
+  - documents scored by the PPR mass landing on their document nodes
+    (chosen over summing contained-entity mass: it is the published
+    HippoRAG 2 passage-node scoring and needs no extra idf heuristic).
+
+Substitutions for a fair, deterministic, LLM-free comparison:
+  - LLM OpenIE is replaced by rule-based triple extraction: per log/code
+    line, regex-extracted entity-like tokens (block ids, IPs, hostnames,
+    paths, hex ids, dotted/CamelCase identifiers, content words) and a
+    fixed verb lexicon for relations; lines with no relation token fall
+    back to entity co-occurrence edges.
+  - The embedding-based synonym model is replaced by case/punctuation-
+    normalized string equality plus token-Jaccard >= 0.8 on split
+    identifiers.
+No randomness anywhere: iteration is over sorted structures and PageRank
+is the deterministic scipy power iteration.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter, defaultdict
+
+import networkx as nx
+
+DAMPING = 0.5  # HippoRAG's published PPR damping factor
+JACCARD_SYNONYM = 0.8
+MAX_ENTITIES_PER_LINE = 16
+
+# Pattern priority matters: earlier patterns mask their spans so later,
+# more generic ones do not re-extract fragments.
+ENTITY_PATTERNS: list[re.Pattern[str]] = [
+    re.compile(r"blk_-?\d+"),                                  # HDFS block ids
+    re.compile(r"\b\d{1,3}(?:\.\d{1,3}){3}(?::\d+)?\b"),       # IPv4(:port)
+    re.compile(r"\b0x[0-9a-fA-F]+\b|\b[0-9a-f]{8,}\b"),        # hex ids
+    re.compile(r"(?<![\w/])/(?:[\w.\-]+/)+[\w.\-]+"),          # file paths
+    re.compile(r"\b[A-Za-z_][\w$\-]*(?:\.[A-Za-z_][\w$\-]*)+\b"),  # dotted: classes, hostnames
+    re.compile(r"\b[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]+)+\b"),      # CamelCase (exceptions, services)
+    re.compile(r"\b[A-Za-z][\w]*(?:[-_][\w]+)+\b"),            # snake/hyphen identifiers
+]
+WORD_PATTERN = re.compile(r"\b[A-Za-z]{2,}\b")
+
+STOPWORDS = frozenset(
+    "the a an to of in on at for is was were be been being and or not with by "
+    "from this that it its as are has have had while when then than but if "
+    "else into over under after before during no none null true false via per "
+    "info debug trace warn".split()
+)
+RELATION_LEXICON = frozenset(
+    "received receiving sent send sending terminating terminated starting "
+    "started start stop stopping stopped failed failing fails fail connect "
+    "connected connecting disconnect disconnected deleting deleted delete "
+    "created creating create opened opening open closed closing close read "
+    "reading write writing wrote allocated allocating exceeded aborted "
+    "aborting retrying retried refused raised threw throw throws thrown "
+    "caught calling called returned returning killed killing launched "
+    "launching completed completing finished exited timed waiting blocked "
+    "serving served added adding removed removing updated updating "
+    "registered succeeded".split()
+)
+
+
+def _normalize(phrase: str) -> str:
+    return re.sub(r"[^0-9a-z]+", "", phrase.lower())
+
+
+def _phrase_tokens(phrase: str) -> frozenset[str]:
+    """Split an identifier on case boundaries and punctuation for Jaccard."""
+    spaced = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", " ", phrase)
+    return frozenset(t.lower() for t in re.split(r"[^0-9A-Za-z]+", spaced) if t)
+
+
+def _line_triples(line: str) -> tuple[list[tuple[str, str, str]], list[tuple[str, str]], list[str]]:
+    """Extract (triples, co-occurrence pairs, all entities) from one line."""
+    found: list[tuple[int, str, str]] = []
+    masked = line
+    for pattern in ENTITY_PATTERNS:
+        for m in pattern.finditer(masked):
+            found.append((m.start(), "entity", m.group(0)))
+        masked = pattern.sub(lambda m: " " * len(m.group(0)), masked)
+    for m in WORD_PATTERN.finditer(masked):
+        word = m.group(0)
+        lower = word.lower()
+        if lower in STOPWORDS:
+            continue
+        if lower in RELATION_LEXICON or (len(lower) >= 5 and lower.endswith(("ing", "ed"))):
+            found.append((m.start(), "relation", lower))
+        else:
+            found.append((m.start(), "entity", word))
+    found.sort()
+    ents = [(pos, s) for pos, kind, s in found if kind == "entity"][:MAX_ENTITIES_PER_LINE]
+    rels = [(pos, s) for pos, kind, s in found if kind == "relation"]
+    entities = [s for _, s in ents]
+    triples: list[tuple[str, str, str]] = []
+    pairs: list[tuple[str, str]] = []
+    if rels:
+        for (p1, e1), (p2, e2) in zip(ents, ents[1:]):
+            between = [r for pr, r in rels if p1 < pr < p2]
+            rel = between[0] if between else rels[0][1]
+            triples.append((e1, rel, e2))
+    else:
+        for i, (_, e1) in enumerate(ents):
+            for _, e2 in ents[i + 1:]:
+                if e1 != e2:
+                    pairs.append((e1, e2))
+    return triples, pairs, entities
+
+
+def extract_phrases(text: str) -> list[str]:
+    """Entity-like phrases for a whole text, in order of first appearance."""
+    out: list[str] = []
+    seen: set[str] = set()
+    for line in text.splitlines() or [text]:
+        _, _, entities = _line_triples(line)
+        for e in entities:
+            if e not in seen:
+                seen.add(e)
+                out.append(e)
+    return out
+
+
+class HippoRAGRetriever:
+    """Phrase graph + Personalized PageRank retriever (see module docstring)."""
+
+    def __init__(self, damping: float = DAMPING):
+        self.damping = damping
+        self.graph = nx.Graph()
+        self.doc_ids: list[str] = []
+        self._norm_index: dict[str, list[str]] = {}
+
+    @staticmethod
+    def _doc_node(doc_id: str) -> str:
+        return f"d::{doc_id}"
+
+    @staticmethod
+    def _ent_node(phrase: str) -> str:
+        return f"e::{phrase}"
+
+    def _bump(self, u: str, v: str, w: float) -> None:
+        if self.graph.has_edge(u, v):
+            self.graph[u][v]["weight"] += w
+        else:
+            self.graph.add_edge(u, v, weight=w)
+
+    def build(self, documents: list[tuple[str, str]]) -> None:
+        self.graph = nx.Graph()
+        self.doc_ids = [doc_id for doc_id, _ in documents]
+        for doc_id, text in documents:
+            dnode = self._doc_node(doc_id)
+            self.graph.add_node(dnode, kind="doc")
+            doc_counts: Counter[str] = Counter()
+            for line in text.splitlines() or [text]:
+                triples, pairs, entities = _line_triples(line)
+                doc_counts.update(entities)
+                for s, _rel, o in triples:
+                    if s != o:
+                        self._bump(self._ent_node(s), self._ent_node(o), 1.0)
+                for e1, e2 in pairs:
+                    self._bump(self._ent_node(e1), self._ent_node(e2), 1.0)
+            for phrase in sorted(doc_counts):
+                enode = self._ent_node(phrase)
+                self.graph.add_node(enode, kind="entity")
+                self._bump(enode, dnode, float(doc_counts[phrase]))
+        self._add_synonym_edges()
+        self._norm_index = defaultdict(list)
+        for node in sorted(self.graph.nodes):
+            if node.startswith("e::"):
+                self._norm_index[_normalize(node[3:])].append(node)
+        self._norm_index = dict(self._norm_index)
+
+    def _add_synonym_edges(self) -> None:
+        phrases = sorted(n[3:] for n in self.graph.nodes if n.startswith("e::"))
+        by_norm: dict[str, list[str]] = defaultdict(list)
+        for p in phrases:
+            by_norm[_normalize(p)].append(p)
+        for _norm, group in sorted(by_norm.items()):
+            for i, p1 in enumerate(group):
+                for p2 in group[i + 1:]:
+                    self._bump(self._ent_node(p1), self._ent_node(p2), 1.0)
+        # Token-Jaccard synonyms among multi-token identifiers sharing a token.
+        token_sets = {p: _phrase_tokens(p) for p in phrases}
+        by_token: dict[str, list[str]] = defaultdict(list)
+        for p in phrases:
+            if len(token_sets[p]) >= 2:
+                for t in sorted(token_sets[p]):
+                    by_token[t].append(p)
+        compared: set[tuple[str, str]] = set()
+        for _token, group in sorted(by_token.items()):
+            for i, p1 in enumerate(group):
+                for p2 in group[i + 1:]:
+                    key = (p1, p2)
+                    if key in compared or _normalize(p1) == _normalize(p2):
+                        continue
+                    compared.add(key)
+                    t1, t2 = token_sets[p1], token_sets[p2]
+                    jac = len(t1 & t2) / len(t1 | t2)
+                    if jac >= JACCARD_SYNONYM:
+                        self._bump(self._ent_node(p1), self._ent_node(p2), 1.0)
+
+    def _specificity(self, node: str) -> float:
+        df = sum(1 for nb in self.graph[node] if nb.startswith("d::"))
+        return 1.0 / max(1, df)
+
+    def retrieve(self, query_text: str, k: int = 10) -> list[tuple[str, float]]:
+        if not self.doc_ids:
+            return []
+        seeds: dict[str, float] = {}
+        for phrase in extract_phrases(query_text):
+            for node in self._norm_index.get(_normalize(phrase), []):
+                seeds[node] = max(seeds.get(node, 0.0), self._specificity(node))
+        personalization = dict(sorted(seeds.items())) if seeds else None
+        scores = nx.pagerank(
+            self.graph,
+            alpha=self.damping,
+            personalization=personalization,
+            weight="weight",
+        )
+        ranked = sorted(
+            ((doc_id, float(scores.get(self._doc_node(doc_id), 0.0))) for doc_id in self.doc_ids),
+            key=lambda row: (-row[1], row[0]),
+        )
+        return ranked[:k]
+
+
+def rank_hipporag(query_text: str, documents: list[tuple[str, str]], k: int = 10) -> list[tuple[str, float]]:
+    retriever = HippoRAGRetriever()
+    retriever.build(documents)
+    return retriever.retrieve(query_text, k=k)

sma/eval/baselines/hybrid_rrf.py

@@ -0,0 +1,30 @@
+"""Reciprocal-rank fusion (blueprint B3: the strong practical RAG).
+
+Fuses any number of ranked lists with the standard RRF constant k=60
+(Cormack, Clarke & Buettcher 2009). Scores are sum(1 / (k + rank)) with
+1-based ranks; ties break on doc id for determinism.
+"""
+
+from __future__ import annotations
+
+RRF_K = 60
+
+
+def rrf_fuse(
+    rankings: list[list[tuple[str, float]]],
+    k: int = RRF_K,
+    top_k: int | None = None,
+) -> list[tuple[str, float]]:
+    """Fuse ranked (doc_id, score) lists by reciprocal rank.
+
+    Input scores are ignored; only rank order matters (that is the point of
+    RRF -- it is scale-free across heterogeneous retrievers).
+    """
+    fused: dict[str, float] = {}
+    for ranking in rankings:
+        for rank, (doc_id, _score) in enumerate(ranking, start=1):
+            fused[doc_id] = fused.get(doc_id, 0.0) + 1.0 / (k + rank)
+    ranked = sorted(fused.items(), key=lambda row: (-row[1], row[0]))
+    if top_k is not None:
+        ranked = ranked[:top_k]
+    return ranked