Skip to content
Python
39.6 KB
Raw Blame
"""读侧:记忆关系图怎么参与打分。

三种用法需要三套不同的数学,最常见的错误是拿一套加权去干这三件事:

| 用法 | 做什么 | 解决什么失败 | 引入新候选 |
|---|---|---|---|
| **A** `propagate_support` | 在**截断前的扩池结果内部**重排 | 分数接近时排序是噪声 | **不会** |
| **B** `relax_admission` | 让被强命中支持的候选**降低准入门槛** | 相关但相似度低,被阈值挡掉 | 会(有界) |
| **C** `find_relation_paths` | 输出连接两个命中的**路径** | 关系语义在平铺列表里丢了 | 少量 |

关键取舍(详见 `docs/pro_graph_design.md` §3):

1. **A 必须作用在截断前的扩池结果上**。只把已选出的 top-10 换个顺序收益很小;
   有价值的是从几十条候选里重新决定哪 10 条进最终结果。
2. **B 绝不给扩展候选"发明"图分数**。图分和语义分不同量纲,硬融合就是靠拍系数把不可比的
   东西凑一起。正确做法是图只动态放宽准入阈值,最终分仍是候选自己与 query 的相似度 ——
   图修正的是**召回漏检**,不是相关性判断,所以永远不可能把真正不相关的东西捧上来。
3. **tag 共属不作为遍历边**(τ=0)。它是分类关系而非关联关系:一个 `work` 标签下 200 条
   记忆彼此"相关度相同",既弱又均匀,且高频 tag 形成 hub。tag 的正确用法是读侧
   **打分通道**(query BM25 terms ∩ mem.tags,权重高于 co_occur)以及 filter/boost。
4. **用法 B 硬闸**:`sim(cand) ≥ seed_sim − δ`(默认 δ=0.2),替代旧的
   `min_score·(1−γ·support)` 松弛门槛。扩展通过闸后按时间并进 seed(`\\n\\n`),
   不单独占 top-k 坑。
"""

import logging
import math
import re
from typing import Any, Dict, Iterable, List, Optional, Set, Tuple

logger = logging.getLogger(__name__)


# 边类型先验 τ。判据是**这条边能否提供向量检索本身拿不到的信息**。
TYPE_PRIOR: Dict[str, float] = {
    # LLM 标注:两端余弦往往很低,向量检索永远发现不了 → 信息量最高
    "causes": 0.9,
    "contrasts": 0.7,
    "elaborates": 0.9,
    # Independent dated occurrences of the same concrete activity/event type.
    "same_series": 0.85,
    # 时序脊:同 Topic 内的递进关系,有向。回答"X 之后/之前"靠它
    "temporal_next": 0.7,
    # 共同写入:仍参与邻域扩展,但先验低于 typed 边;最终分里 co_occur 通道权重也更低
    # (相对 tag∩keyword)。噪声靠度数归一化 + seed_sim 硬闸控制。
    "co_occurs": 0.55,
    # 确定性:记录的就是"语义相近",而这正是向量索引本来就知道的事 → 高度冗余
    "semantic_neighbor": 0.35,
    # Episode 共属:同一次讨论(跨 write 批次)。不走边,由 episode_id 字段框出,
    # 本质是"跨批次延长的 co_occurs",先验与之对齐
    "episode": 0.55,
    # 兜底(老数据里 System 2 写的无类型 RELATED_TO)
    "related": 0.5,
}
_DEFAULT_PRIOR = 0.5

# 读侧一律过滤的图节点状态:被判重逻辑删除的记忆不能从图里绕回来
_EXCLUDED_STATUS = {"shadow"}


def edge_prior(relation_type: Optional[str]) -> float:
    return TYPE_PRIOR.get((relation_type or "").lower(), _DEFAULT_PRIOR)


def filter_relation_edges(
    edges: Iterable[Dict[str, Any]], *, include_same_series: bool,
) -> List[Dict[str, Any]]:
    """Apply feature gates before graph edges affect ranking or admission."""
    return [
        edge for edge in (edges or [])
        if include_same_series
        or str(edge.get("relation_type") or "").lower() != "same_series"
    ]


def build_adjacency(
    edges: Iterable[Dict[str, Any]],
    *,
    exclude_status: Optional[Set[str]] = None,
) -> Dict[str, List[Tuple[str, str, float]]]:
    """把 `graph_store.get_related_edges()` 的结果建成无向邻接表。

    同一对节点之间可能有多种关系(既 `co_occurs` 又 `causes`)。这里**折叠成一条、
    取有效权重最大的那种**:度数应该数"有多少个不同的邻居",而不是"有多少条平行边",
    否则 hub 降权(`sqrt(deg)`)会被平行边稀释,支持度也会重复计。

    Returns:
        {node_id: [(neighbor_id, relation_type, effective_weight), ...]}
        `effective_weight` = 边权 × 类型先验 τ,后续公式直接用它。
    """
    excluded = exclude_status if exclude_status is not None else _EXCLUDED_STATUS
    # (node, neighbor) -> (relation_type, effective_weight),只保留最强的
    best: Dict[Tuple[str, str], Tuple[str, float]] = {}

    for e in edges or []:
        src, tgt = e.get("source_id"), e.get("target_id")
        if not src or not tgt or src == tgt:
            continue
        if (e.get("target_status") or "").lower() in excluded:
            continue
        # 有向边(TEMPORAL_NEXT)从两端都可能命中,source 侧也要过滤 shadow
        if (e.get("source_status") or "").lower() in excluded:
            continue
        rtype = e.get("relation_type") or "related"
        try:
            w = float(e.get("weight", 1.0))
        except (TypeError, ValueError):
            w = 1.0
        eff = max(0.0, min(w, 1.0)) * edge_prior(rtype)
        # 邻接表本身是无向的(A/B 只关心"挨着");方向信息由 forward_dirs 单独保留
        for a, b in ((src, tgt), (tgt, src)):
            prev = best.get((a, b))
            if prev is None or eff > prev[1]:
                best[(a, b)] = (rtype, eff)

    adj: Dict[str, List[Tuple[str, str, float]]] = {}
    for (a, b), (rtype, eff) in best.items():
        adj.setdefault(a, []).append((b, rtype, eff))
    return adj


def collect_directed_edges(edges: Iterable[Dict[str, Any]]) -> Set[Tuple[str, str]]:
    """收集有向边的正向 (source, target) 集合(目前只有 `temporal_next`)。

    邻接表刻意做成无向的 —— 用法 A/B 只关心"挨着"。但用法 C 输出路径时要能说清
    方向,否则"X 之后发生了什么"和"X 之前"分不开。
    """
    out: Set[Tuple[str, str]] = set()
    for e in edges or []:
        if not e.get("directed"):
            continue
        src, tgt = e.get("source_id"), e.get("target_id")
        if src and tgt and src != tgt:
            out.add((src, tgt))
    return out


# ================================================================
# 用法 A:池内支持度传播
# ================================================================

def propagate_support(
    scores: Dict[str, float],
    adjacency: Dict[str, List[Tuple[str, str, float]]],
    *,
    beta: float = 0.15,
    iterations: int = 1,
    support_cap: float = 1.0,
) -> Tuple[Dict[str, float], Dict[str, float]]:
    """在**已召回池内部**做图正则化重排。

        support(v) = Σ_{u ∈ N(v) ∩ P, u≠v}  eff_w(u,v) · s(u)  /  sqrt(deg_pool(v))
        s'(v)      = s0(v) + beta · min(support(v), support_cap)

    三个护栏都在公式里:
      - `∩ P`(只在池内传播)→ 不引入新候选,不会 hub fan-out;
      - `sqrt(deg_pool(v))` 度数归一化 → 这是 tag hub 问题的直接解药(图上的 IDF 类比);
      - `beta` 小 + `support_cap` → 这是**微调**而非重写排序。beta 大到能让排序翻天覆地,
        就说明在用图代替检索,一定掉精度。

    Args:
        scores: {node_id: s0},直接召回分(**截断前的扩池结果**)
        adjacency: build_adjacency() 的产物
        iterations: 传播轮数,1~2 足够;更多轮收益递减且开始糊化

    Returns:
        (新分数 dict, support dict)。support 单独返回,供观测和用法 B 复用。
    """
    if not scores or not adjacency or beta <= 0:
        return dict(scores), {}

    pool = set(scores)
    # 池内度数(只算两端都在池里的边)
    deg: Dict[str, int] = {}
    for v in pool:
        deg[v] = sum(1 for (nb, _t, _w) in adjacency.get(v, []) if nb in pool)

    s0 = dict(scores)
    cur = dict(scores)
    support: Dict[str, float] = {}

    for _ in range(max(1, iterations)):
        nxt: Dict[str, float] = {}
        for v in pool:
            raw = 0.0
            for nb, _rtype, eff_w in adjacency.get(v, []):
                if nb == v or nb not in pool:
                    continue
                raw += eff_w * cur.get(nb, 0.0)
            d = deg.get(v, 0)
            sup = raw / (d ** 0.5) if d > 0 else 0.0
            support[v] = sup
            nxt[v] = s0[v] + beta * min(sup, support_cap)
        cur = nxt

    return cur, support


# ================================================================
# 用法 B:阈值松弛(图只降低门槛,绝不发明相关性)
# ================================================================

# 边类型分组,用于扩展时按类型分配配额。
#
# 时间边数量天然最多、信息量最低(同一天写的东西不一定有关系);关系边最少但信息量最高
# (`causes` 两端的向量相似度可能很低,是向量检索永远找不到的)。不分配额的话,
# 时间边会把关系边从 top-N 里挤出去 —— 这和 tag hub 淹没结果是同一类问题。
_RELATIONAL_TYPES = {"causes", "elaborates", "contrasts", "same_series",
                     "co_occurs", "related",
                     "episode"}
_TEMPORAL_TYPES = {"temporal_next"}


def edge_group(relation_type: Optional[str]) -> str:
    rt = (relation_type or "").lower()
    if rt in _TEMPORAL_TYPES:
        return "temporal"
    if rt == "semantic_neighbor":
        return "semantic"
    return "relational"


def normalize_by_degree(
    adjacency: Dict[str, List[Tuple[str, str, float]]],
) -> Dict[str, List[Tuple[str, str, float]]]:
    """按度数给边权贬值:`eff_w /= sqrt(deg(neighbor))`。

    高连接节点(同一天写了很多条、或话题 hub)的每一条边都更不具区分度。
    这是图上的 IDF 类比,也是时间边能不能安全参与扩展的前提 ——
    否则一个高产的日子会把当天所有记忆等权拉进来。
    """
    deg = {n: len(nbs) for n, nbs in (adjacency or {}).items()}
    out: Dict[str, List[Tuple[str, str, float]]] = {}
    for node, nbs in (adjacency or {}).items():
        scaled = []
        for nb, rtype, eff in nbs:
            d = deg.get(nb, 1) or 1
            scaled.append((nb, rtype, eff / (d ** 0.5)))
        out[node] = scaled
    return out


def reachable_within(
    seed_scores: Dict[str, float],
    adjacency: Dict[str, List[Tuple[str, str, float]]],
    *,
    hops: int = 2,
    seed_floor: float = 0.6,
    hop_decay: float = 0.5,
    max_nodes: int = 200,
    multi_seed_bonus: float = 0.5,
) -> Dict[str, Tuple[float, str, str, int]]:
    """从高分 seed 出发做 BFS,返回池外可达节点的结构支持度。

    这是**关系型结构多跳**的实现:`causes` / `co_occurs` / `temporal_next` 这些边
    可以串起来走,"朋友推荐的餐厅"这类问题的两端往往隔着一个中间节点。

    支持度沿路衰减:`support = Π(eff_w) · hop_decay^(hop-1) · s0(seed)`。
    衰减 + 节点预算是必须的 —— 2 跳不加约束就等于把整个连通分量拉进来。

    **多 seed 佐证**:单个 seed 指向一个候选可能是巧合,**两个不同 seed 同时指向它**
    才是真正的佐证(同一个"互相佐证"逻辑,用法 A 用在池内、这里用在扩展)。
    所以 support 不是简单取 max,而是"最强路径 + 其余 seed 的贡献 × multi_seed_bonus"。
    例:query 同时命中「吃饭」和「骑车」,两者都指向「公园」→ 公园显著上浮。

    Returns:
        {node_id: (support, via_seed, relation_type_of_first_edge, hop)}
    """
    if hops < 1 or not seed_scores or not adjacency:
        return {}

    in_pool = set(seed_scores)
    seeds = sorted(
        [(nid, s) for nid, s in seed_scores.items() if s >= seed_floor],
        key=lambda x: x[1], reverse=True,
    )
    if not seeds:
        return {}

    # cand -> {seed: (best_support_from_that_seed, first_rel, hop)}
    per_seed: Dict[str, Dict[str, Tuple[float, str, int]]] = {}
    # frontier: (node, 累计权重, via_seed, 首跳关系, hop)
    frontier: List[Tuple[str, float, str, str, int]] = [
        (nid, s, nid, "", 0) for nid, s in seeds
    ]
    visited = set(in_pool)

    for hop in range(1, hops + 1):
        nxt: List[Tuple[str, float, str, str, int]] = []
        for cur, acc, via, first_rel, _h in frontier:
            for nb, rtype, eff_w in adjacency.get(cur, []):
                if nb == cur:
                    continue
                # 跳数衰减:第 1 跳不衰减,之后每跳乘 hop_decay
                sup = acc * eff_w * (hop_decay ** (hop - 1))
                rel = first_rel or rtype
                if nb not in in_pool:
                    slot = per_seed.setdefault(nb, {})
                    prev = slot.get(via)
                    if prev is None or sup > prev[0]:
                        slot[via] = (sup, rel, hop)
                if nb not in visited and hop < hops:
                    visited.add(nb)
                    nxt.append((nb, acc * eff_w, via, rel, hop))
            if len(per_seed) >= max_nodes:
                break
        if len(per_seed) >= max_nodes:
            break
        frontier = nxt
        if not frontier:
            break

    # 合成:最强路径全额 + 其余 seed 的贡献打折累加(有界,避免多 seed 无限叠)
    best: Dict[str, Tuple[float, str, str, int]] = {}
    for cand, slots in per_seed.items():
        ranked = sorted(slots.items(), key=lambda kv: kv[1][0], reverse=True)
        top_seed, (top_sup, top_rel, top_hop) = ranked[0]
        extra = sum(s[0] for _sid, s in ranked[1:])
        best[cand] = (
            top_sup + multi_seed_bonus * extra, top_seed, top_rel, top_hop,
        )
    return best


def apply_type_quota(
    reach: Dict[str, Tuple[float, str, str, int]],
    *,
    top_n: int,
    quotas: Optional[Dict[str, float]] = None,
) -> Dict[str, Tuple[float, str, str, int]]:
    """按边类型分配 top-N 配额,再按 support 截断。

    为什么必须分组:时间边数量天然最多、信息量最低;关系边最少但信息量最高
    (`causes` 两端余弦可能很低,向量检索永远找不到)。不分配额的话时间边会把关系边
    从 top-N 里挤出去。

    这一步是**免费的**(纯本地排序),必须放在"批量取向量算相似度"之前 ——
    算相似度是整条链路上唯一有 I/O 成本的一步。
    """
    if top_n <= 0 or not reach:
        return {}
    q = quotas or {"relational": 0.5, "temporal": 0.3, "semantic": 0.2}

    grouped: Dict[str, List[Tuple[str, Tuple[float, str, str, int]]]] = {}
    for cand, val in reach.items():
        grouped.setdefault(edge_group(val[2]), []).append((cand, val))

    out: Dict[str, Tuple[float, str, str, int]] = {}
    for group, items in grouped.items():
        items.sort(key=lambda kv: kv[1][0], reverse=True)
        budget = max(1, int(round(top_n * q.get(group, 0.0))))
        for cand, val in items[:budget]:
            out[cand] = val

    # 配额没用满时,用全局最强的候选补齐
    if len(out) < top_n:
        rest = sorted(
            ((c, v) for c, v in reach.items() if c not in out),
            key=lambda kv: kv[1][0], reverse=True,
        )
        for cand, val in rest[: top_n - len(out)]:
            out[cand] = val
    return out


def episode_support(
    hits: List[Dict[str, Any]],
    episode_members: Dict[str, List[str]],
    *,
    seed_floor: float = 0.6,
    weight: float = 0.7,
    multi_seed_bonus: float = 0.5,
) -> Dict[str, Tuple[float, str, str, int]]:
    """把 episode 共属折算成结构支持度,形状与 `reachable_within` 一致,可直接进同一漏斗。

    Episode 是"一次讨论"(跨 write 批次,SDK 内部按时间间隔切)。同一 episode 的记忆
    彼此有真实关联,但向量可能互不相似 —— 这正是向量检索找不到的那部分。

    为什么用字段而不是边:一个 episode 10-30 条记忆,两两连边是 45-435 条;
    一个 `episode_id` + 一次过滤查询就够,而且**不依赖图**(graph 关掉也能用)。

    与 tag 桥接(τ=0,已否决)的区别:`work` 标签下可能有跨年的 200 条,是**分类关系**;
    episode 是同一次讨论的 10-30 条,是**情节关系** —— 本质上是"跨批次延长的 co_occurs"。

        support(c) = weight / sqrt(episode_size) · s0(seed)

    `sqrt(episode_size)` 归一化:episode 越大,单条共属越不具区分度(同 tag hub 的道理)。
    多 seed 佐证同样适用:两个高分命中同属一个 episode 时,该 episode 的成员更可信。

    Args:
        hits: 直接命中(用来挑 seed,也用来排除已在池内的)
        episode_members: {episode_id: [member_node_id, ...]},调用方从 VDB 框出来

    Returns:
        {node_id: (support, via_seed, "episode", 1)}
    """
    if not hits or not episode_members:
        return {}

    in_pool = {h.get("node_id") for h in hits if h.get("node_id")}
    # episode_id → 该 episode 下分数最高的几个 seed
    seeds_by_ep: Dict[str, List[Tuple[str, float]]] = {}
    for h in hits:
        score = float(h.get("score", 0.0))
        if score < seed_floor:
            continue
        node = h.get("node")
        ep = (getattr(node, "episode_id", "") or "") if node is not None else ""
        if not ep or ep not in episode_members:
            continue
        seeds_by_ep.setdefault(ep, []).append((h.get("node_id") or "", score))

    out: Dict[str, Tuple[float, str, str, int]] = {}
    for ep, seeds in seeds_by_ep.items():
        members = [m for m in episode_members.get(ep, []) if m and m not in in_pool]
        if not members:
            continue
        size = max(2, len(episode_members.get(ep, [])))
        base = weight / (size ** 0.5)
        seeds.sort(key=lambda x: x[1], reverse=True)
        top_seed, top_score = seeds[0]
        extra = sum(s for _sid, s in seeds[1:])
        sup = base * (top_score + multi_seed_bonus * extra)
        for m in members:
            prev = out.get(m)
            if prev is None or sup > prev[0]:
                out[m] = (sup, top_seed, "episode", 1)
    return out


def blend_support(
    graph_reach: Dict[str, Tuple[float, str, str, int]],
    episode_reach: Dict[str, Tuple[float, str, str, int]],
    *,
    lam: float = 0.3,
    support_cap: float = 1.0,
) -> Dict[str, Tuple[float, str, str, int]]:
    """把「图边可达」与「episode 共属」两条来源的支持度**有界叠加**,而不是取 max。

    为什么不能取 max:这是**两个独立观察**。`co_occurs` 说"这两条是同一段话里抽出来的",
    episode 共属说"这两条属于同一件事,哪怕隔了几次写入"。两者同时成立时,该候选比
    只成立一个更可信;取 max 等于宣布"多一个独立证据不加分"。

    而且取 max 会**系统性偏向粗粒度信号**:episode 的支持度被 `sqrt(episode_size)`
    归一化压着,天然小于 `co_occurs`,所以 max 几乎总是选中图边 —— episode 通道在
    "有共现边的候选"上等于完全不起作用,只在跨批次、无共现边的候选上才有效。

        support = min(support_cap, s_graph + lam · s_episode)

    用折扣系数而不是直接相加,是为了避免两个弱证据叠出一个强结论;`support_cap`
    封顶保证准入门槛最多降到 `(1 - gamma) · min_score`,护栏不变。
    这与 `reachable_within` 里对多 seed 佐证的处理是同一套逻辑(最强的全额 + 其余打折)。

    归属信息(via_seed / relation_type / hop)取**支持度更强**的那一侧,便于观测。
    """
    if not episode_reach:
        return dict(graph_reach or {})
    out: Dict[str, Tuple[float, str, str, int]] = dict(graph_reach or {})
    for cand, (ep_sup, ep_seed, ep_type, ep_hop) in episode_reach.items():
        prev = out.get(cand)
        if prev is None:
            out[cand] = (min(ep_sup, support_cap), ep_seed, ep_type, ep_hop)
            continue
        g_sup, g_seed, g_type, g_hop = prev
        merged = min(g_sup + lam * ep_sup, support_cap)
        if ep_sup > g_sup:
            out[cand] = (merged, ep_seed, ep_type, ep_hop)
        else:
            out[cand] = (merged, g_seed, g_type, g_hop)
    return out


def apply_temporal_affinity(
    reach: Dict[str, Tuple[float, str, str, int]],
    *,
    times: Dict[str, float],
    tau_days: float = 7.0,
    floor: float = 0.3,
) -> Dict[str, Tuple[float, str, str, int]]:
    """给结构支持度乘一个**时间亲和**因子:与锚点写得越近,联系越可能真实。

    这是打分的第二个维度(第一个是内容:边权 × 候选自身与 query 的相似度)。

    动机来自这样一次写入:"我今天去公园玩了,是骑车去的,今天还去吃了东西" ——
    公园 / 骑车 / 吃饭是**一起**被记下来的。之后问"上周吃饭的地方在哪",
    向量检索可能只捞到「吃饭」而捞不到「公园」,但它们同一时间点写入这件事本身
    就是强信号。同批次的 `co_occurs` 边天然满足 Δt≈0 → 因子=1。

        factor = clamp(exp(-Δdays / tau_days), floor, 1.0)

    `floor` 不设 0:时间远但关系强(如 LLM 标的 `causes`)的边不该被时间抹平。
    取不到时间的节点按 1.0 处理 —— 不因缺字段惩罚。
    """
    if not reach or not times:
        return reach
    out: Dict[str, Tuple[float, str, str, int]] = {}
    tau_sec = max(1.0, tau_days * 86400.0)
    for cand, (sup, via, rel, hop) in reach.items():
        t_c, t_s = times.get(cand), times.get(via)
        if t_c is None or t_s is None:
            out[cand] = (sup, via, rel, hop)
            continue
        factor = math.exp(-abs(t_c - t_s) / tau_sec)
        factor = max(floor, min(1.0, factor))
        out[cand] = (sup * factor, via, rel, hop)
    return out


def temporal_affinity_factor(
    t_cand: Optional[float],
    t_seed: Optional[float],
    *,
    tau_days: float = 7.0,
    floor: float = 0.3,
) -> float:
    """单对 (cand, seed) 的时间亲和 ∈ [floor, 1];缺时间按 1.0。"""
    if t_cand is None or t_seed is None:
        return 1.0
    tau_sec = max(1.0, tau_days * 86400.0)
    factor = math.exp(-abs(t_cand - t_seed) / tau_sec)
    return max(floor, min(1.0, factor))


_TERM_RE = re.compile(r"[a-z0-9\u4e00-\u9fff]+", re.I)


def tokenize_query_terms(query: str) -> List[str]:
    """轻量分词:用于 BM25/tag 通道(不引入 LLM;评测单 query 路径可用)。"""
    if not query:
        return []
    return [t.lower() for t in _TERM_RE.findall(query) if len(t) > 1]


def keyword_content_overlap(terms: List[str], content: str) -> float:
    """query terms 命中 content 的比例 ∈ [0, 1]。"""
    if not terms or not content:
        return 0.0
    blob = content.lower()
    hit = sum(1 for t in terms if t in blob)
    return hit / len(terms)


def tag_keyword_overlap(terms: List[str], tags: Optional[Iterable[str]]) -> float:
    """query BM25 terms ∩ mem.tags(大小写不敏感)的覆盖率 ∈ [0, 1]。

    tag 通道权重要高于 co_occur:专名/主题词对齐比弱共现边更可信。
    """
    if not terms or not tags:
        return 0.0
    tag_set = {str(t).lower().strip() for t in tags if t}
    if not tag_set:
        return 0.0
    # 精确交集 + tag 被 term 包含 / term 被 tag 包含(travel ↔ traveling)
    hit = 0
    for t in terms:
        if t in tag_set:
            hit += 1
            continue
        if any(t in tag or tag in t for tag in tag_set if len(tag) > 2):
            hit += 1
    return hit / len(terms)


def score_expanded_candidate(
    *,
    sim: float,
    bm25: float = 0.0,
    tag_overlap: float = 0.0,
    temporal: float = 1.0,
    support: float = 0.0,
    relation_type: Optional[str] = None,
    w_sem: float = 1.0,
    w_bm25: float = 0.3,
    w_tag: float = 0.5,
    w_temporal: float = 0.2,
    w_co_occur: float = 0.15,
    w_struct: float = 0.25,
) -> float:
    """扩展候选多通道融合分(无 LLM)。

        score = w_sem·sim + w_bm25·bm25 + w_tag·tag
              + w_temporal·temporal + w_edge·min(support,1)

    `co_occurs` / `episode` 走较低的 `w_co_occur`;typed 边走 `w_struct`。
    """
    rtype = (relation_type or "").lower()
    if rtype in ("co_occurs", "episode"):
        struct = w_co_occur * min(max(support, 0.0), 1.0)
    else:
        struct = w_struct * min(max(support, 0.0), 1.0)
    return (
        w_sem * float(sim)
        + w_bm25 * float(bm25)
        + w_tag * float(tag_overlap)
        + w_temporal * float(temporal)
        + struct
    )


def relax_admission(
    *,
    seed_scores: Dict[str, float],
    adjacency: Dict[str, List[Tuple[str, str, float]]],
    candidate_sims: Dict[str, float],
    min_score: float = 0.0,
    gamma: float = 0.3,
    seed_floor: float = 0.6,
    max_admit: int = 20,
    hops: int = 1,
    hop_decay: float = 0.5,
    boost_beta: float = 0.0,
    boost_cap: float = 1.0,
    reach: Optional[Dict[str, Tuple[float, str, str, int]]] = None,
    seed_sim_delta: float = 0.2,
    candidate_bm25: Optional[Dict[str, float]] = None,
    candidate_tag: Optional[Dict[str, float]] = None,
    candidate_temporal: Optional[Dict[str, float]] = None,
    channel_weights: Optional[Dict[str, float]] = None,
) -> List[Dict[str, Any]]:
    """从高分 seed 的 k 跳邻域里捞回被漏检的候选,并**重新打分**。

    **硬闸(用法 B 准入)**:

        admit(c) iff sim(c) ≥ seed_sim(via) − δ     (默认 δ=0.2)

    `seed_sim` 是把 c 拉进来的 via_seed 相对 query 的分数。比旧的
    `min_score·(1−γ·support)` 更直观:扩展不能比自己的种子低太多。

    `gamma ≤ 0` 仍表示**关闭**用法 B(兼容 `MEMORY_GRAPH_RELAX_GAMMA=0`)。

    **多通道打分**(可选特征字典齐全时启用;否则退回 `sim + boost_beta·support`):

        语义 + BM25(content) + tag∩keyword(高)+ 时序 + co_occur/结构(低)

    Args:
        candidate_sims: {candidate_id: sim(query, candidate)}
        seed_sim_delta: 硬闸 δ,env `MEMORY_GRAPH_SEED_SIM_DELTA`
        candidate_bm25 / candidate_tag / candidate_temporal: 可选通道特征 ∈ [0,1]
        channel_weights: {sem,bm25,tag,temporal,co_occur,struct} 覆盖默认权重
        reach: 可选,预先算好(并已乘过时间亲和)的可达集

    Returns:
        [{"node_id", "score", "sim", "support", "threshold", "via_seed",
          "relation_type", "hop", ...}],按 score 降序,最多 max_admit 条。
    """
    if gamma <= 0 or not seed_scores or not candidate_sims:
        return []
    # 无邻接且无预计算 reach(例如只靠 episode)时也允许
    if reach is None and not adjacency:
        return []

    if reach is None:
        reach = reachable_within(
            seed_scores, adjacency,
            hops=max(1, hops), seed_floor=seed_floor, hop_decay=hop_decay,
        )

    delta = max(0.0, float(seed_sim_delta))
    use_channels = bool(
        candidate_bm25 is not None
        or candidate_tag is not None
        or candidate_temporal is not None
        or channel_weights
    )
    cw = channel_weights or {}

    admitted: List[Dict[str, Any]] = []
    for cand_id, (sup, seed_id, rtype, hop) in reach.items():
        if cand_id not in candidate_sims:
            continue
        sim = float(candidate_sims.get(cand_id, 0.0))
        seed_sim = float(seed_scores.get(seed_id, 0.0))
        threshold = seed_sim - delta
        if sim < threshold:
            continue

        bm25 = float((candidate_bm25 or {}).get(cand_id, 0.0))
        tag_ov = float((candidate_tag or {}).get(cand_id, 0.0))
        temporal = float((candidate_temporal or {}).get(cand_id, 1.0))

        if use_channels:
            score = score_expanded_candidate(
                sim=sim, bm25=bm25, tag_overlap=tag_ov, temporal=temporal,
                support=sup, relation_type=rtype,
                w_sem=float(cw.get("sem", 1.0)),
                w_bm25=float(cw.get("bm25", 0.3)),
                w_tag=float(cw.get("tag", 0.5)),
                w_temporal=float(cw.get("temporal", 0.2)),
                w_co_occur=float(cw.get("co_occur", 0.15)),
                w_struct=float(cw.get("struct", 0.25)),
            )
        else:
            score = sim + boost_beta * min(sup, boost_cap)

        admitted.append({
            "node_id": cand_id,
            "score": score,
            "sim": sim,
            "support": sup,
            "threshold": threshold,
            "seed_sim": seed_sim,
            "via_seed": seed_id,
            "relation_type": rtype,
            "hop": hop,
            "bm25": bm25,
            "tag_overlap": tag_ov,
            "temporal": temporal,
        })

    admitted.sort(key=lambda x: x["score"], reverse=True)
    return admitted[:max_admit]


def _item_time_seconds(item: Dict[str, Any]) -> float:
    node = item.get("node")
    if node is None:
        return 0.0
    value = getattr(node, "memory_at", None) or getattr(node, "gmt_created", None)
    if value is None:
        return 0.0
    try:
        return float(value.timestamp())
    except Exception:
        return 0.0


def _canonical_content(item: Dict[str, Any]) -> str:
    node = item.get("node")
    if node is not None and getattr(node, "content", None):
        return str(node.content)
    return str(item.get("content") or "")


def merge_expansions_into_seeds(
    hits: List[Dict[str, Any]],
    admitted_hits: List[Dict[str, Any]],
) -> List[Dict[str, Any]]:
    """把通过硬闸的扩展 mem **按时间并进**对应 seed,用 ``\\n\\n`` 分隔。

    - 合成后仍占 **1** 个 top-k 坑(保留 seed 原 score / 排序位置)
    - 同一 cand 只并进 via 最强的那条 seed(admitted 已是单 via)
    - 块顺序:seed + expansions 全部按 `memory_at`(缺则 `gmt_created`)升序
    - 不写回 VDB;只改读侧返回的 content
    """
    if not admitted_hits:
        return hits

    by_seed: Dict[str, List[Dict[str, Any]]] = {}
    for a in admitted_hits:
        via = a.get("graph_via") or a.get("via_seed")
        if not via:
            continue
        by_seed.setdefault(via, []).append(a)

    if not by_seed:
        return hits

    hit_by_id = {h.get("node_id"): h for h in hits if h.get("node_id")}

    for seed_id, exps in by_seed.items():
        seed_hit = hit_by_id.get(seed_id)
        if seed_hit is None:
            continue
        existing = list(seed_hit.get("_graph_merged_items") or [])
        if not existing:
            existing = [seed_hit]
        elif not any(piece.get("node_id") == seed_id for piece in existing):
            existing.insert(0, seed_hit)
        pieces = existing + list(exps)
        deduped = []
        seen_ids: Set[str] = set()
        seen_contents: Set[str] = set()
        for piece in pieces:
            piece_id = str(piece.get("node_id") or "")
            piece_content = " ".join(_canonical_content(piece).split()).casefold()
            if ((piece_id and piece_id in seen_ids)
                    or (piece_content and piece_content in seen_contents)):
                continue
            if piece_id:
                seen_ids.add(piece_id)
            if piece_content:
                seen_contents.add(piece_content)
            deduped.append(piece)
        pieces = deduped
        pieces.sort(key=_item_time_seconds)
        merged_items = [
            {**piece, "content": _canonical_content(piece)}
            for piece in pieces
        ]
        merged = "\n\n".join(
            c for c in (_canonical_content(p) for p in pieces) if c
        )
        if not merged:
            continue
        # 写到 hit 上:下游组 response 时优先用 item["content"] 覆盖 node.content
        seed_hit["content"] = merged
        seed_hit["graph_merged"] = True
        seed_hit["_graph_merged_items"] = merged_items
        seed_hit["graph_merged_ids"] = [
            e.get("node_id") for e in exps if e.get("node_id")
        ]
        # 保留最强扩展的观测字段,便于 trace
        best = max(exps, key=lambda x: float(x.get("score", 0.0)))
        seed_hit["graph_support"] = best.get("graph_support") or best.get("support")
        seed_hit["graph_relation"] = best.get("graph_relation") or best.get("relation_type")
        if all(
            (e.get("graph_relation") or e.get("relation_type")) == "same_series"
            for e in exps
        ):
            seed_hit["_timeline_member_ids"] = [
                piece.get("node_id") for piece in merged_items if piece.get("node_id")
            ]
            seed_hit["_timeline"] = [
                {
                    "memory_id": piece.get("node_id"),
                    "memory_at": _item_time_seconds(piece),
                }
                for piece in merged_items if piece.get("node_id")
            ]

    # 扩展不再作为独立 hit 返回
    return hits


def annotate_same_series_in_pool(
    hits: List[Dict[str, Any]],
    adjacency: Dict[str, List[Tuple[str, str, float]]],
) -> List[Dict[str, Any]]:
    """Mark explicit same-series neighbors that are already query candidates."""
    pool_ids = {item.get("node_id") for item in hits if item.get("node_id")}
    for item in hits:
        node_id = item.get("node_id")
        if not node_id:
            continue
        members = sorted({
            neighbor for neighbor, relation, _weight in adjacency.get(node_id, [])
            if relation == "same_series" and neighbor in pool_ids
        })
        if members:
            item["_same_series_pool_ids"] = members
    return hits


def merge_same_series_in_pool(hits: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
    """Fold connected same-series candidates into one chronological L2 slot."""
    by_id = {item.get("node_id"): item for item in hits if item.get("node_id")}
    adjacency = {
        node_id: {
            member for member in item.get("_same_series_pool_ids") or []
            if member in by_id
        }
        for node_id, item in by_id.items()
    }
    visited: Set[str] = set()
    remove: Set[str] = set()
    for start in list(adjacency):
        if start in visited or not adjacency[start]:
            continue
        component: Set[str] = set()
        stack = [start]
        while stack:
            current = stack.pop()
            if current in visited:
                continue
            visited.add(current)
            component.add(current)
            stack.extend(adjacency.get(current, set()) - visited)
        if len(component) < 2:
            continue
        members = [by_id[node_id] for node_id in component]
        if any(member.get("graph_merged") for member in members):
            continue
        seed = max(
            members,
            key=lambda item: (float(item.get("score", 0.0)), -hits.index(item)),
        )
        pieces = sorted(members, key=_item_time_seconds)
        seed["content"] = "\n\n".join(
            text for text in (_canonical_content(piece) for piece in pieces) if text
        )
        seed["graph_merged"] = True
        seed["graph_relation"] = "same_series"
        seed["_graph_merged_items"] = [
            {**piece, "content": _canonical_content(piece)} for piece in pieces
        ]
        seed["graph_merged_ids"] = [
            piece.get("node_id") for piece in pieces
            if piece.get("node_id") and piece is not seed
        ]
        seed["_timeline_member_ids"] = [
            piece.get("node_id") for piece in pieces if piece.get("node_id")
        ]
        seed["_timeline"] = [
            {
                "memory_id": piece.get("node_id"),
                "memory_at": _item_time_seconds(piece),
            }
            for piece in pieces if piece.get("node_id")
        ]
        remove.update(component - {seed.get("node_id")})
    return [item for item in hits if item.get("node_id") not in remove]


# ================================================================
# 用法 C:关系路径(独立输出通道,不进主排序)
# ================================================================

def find_relation_paths(
    *,
    hit_scores: Dict[str, float],
    adjacency: Dict[str, List[Tuple[str, str, float]]],
    high_floor: float = 0.6,
    max_paths: int = 5,
    typed_only: bool = True,
    forward_dirs: Optional[Set[Tuple[str, str]]] = None,
) -> List[Dict[str, Any]]:
    """找出连接两个高分命中的 ≤2 跳路径。

    关系型问题("推荐那家餐厅的朋友是谁")要的不是排好序的列表,而是一条**路径**。
    把路径节点混进平铺的召回列表会丢掉关系语义 —— 答案 LLM 只看到几条互不相干的记忆。
    所以这里作为独立字段返回,**不参与主排序**。

    中间节点(1 跳路径没有;2 跳路径的桥接点)即使自己分数很低也会带上 —— 它是路径的一部分。

    Args:
        hit_scores: 直接命中 {node_id: score}
        high_floor: 只在分数 ≥ 该值的命中之间找路径
        typed_only: 只用信息量高的边(排除 semantic_neighbor —— 它只说明"语义相近",
            两条语义相近的记忆之间连一条路径对答案没有解释价值)
        forward_dirs: `collect_directed_edges()` 的产物。有向边(`temporal_next`)
            据此标出方向 —— `direction="forward"` 表示 A 在 B **之前**发生。
            不标方向的话"X 之后"和"X 之前"在输出里分不开。

    Returns:
        [{"score", "hops", "nodes": [id...], "relations": [{type, direction}...]}]
        按 score 降序
    """
    fwd = forward_dirs or set()

    def _rel(a: str, b: str, rtype: str) -> Dict[str, str]:
        """描述 a→b 这一步的关系。有向边给出 forward / backward。"""
        item = {"type": rtype}
        if (a, b) in fwd:
            item["direction"] = "forward"    # a 早于 b
        elif (b, a) in fwd:
            item["direction"] = "backward"   # a 晚于 b
        return item
    anchors = sorted(
        [(nid, s) for nid, s in (hit_scores or {}).items() if s >= high_floor],
        key=lambda x: x[1], reverse=True,
    )
    if len(anchors) < 2 or not adjacency:
        return []

    anchor_ids = {nid for nid, _ in anchors}
    anchor_score = dict(anchors)

    def _usable(rtype: str) -> bool:
        if not typed_only:
            return True
        return (rtype or "").lower() != "semantic_neighbor"

    paths: List[Dict[str, Any]] = []
    seen: Set[Tuple[str, ...]] = set()

    def _emit(nodes: List[str], relations: List[Dict[str, str]], score: float) -> None:
        key = tuple(sorted((nodes[0], nodes[-1]))) + tuple(
            sorted(r["type"] for r in relations)
        )
        if key in seen:
            return
        seen.add(key)
        paths.append({
            "score": round(score, 6),
            "hops": len(nodes) - 1,
            "nodes": nodes,
            "relations": relations,
        })

    for a_id, a_s in anchors:
        # 1 跳:两个 anchor 直接相连
        for nb, rtype, eff_w in adjacency.get(a_id, []):
            if not _usable(rtype):
                continue
            if nb in anchor_ids and nb != a_id:
                _emit(
                    [a_id, nb], [_rel(a_id, nb, rtype)],
                    min(a_s, anchor_score[nb]) * eff_w,
                )

        # 2 跳:经一个中间节点连到另一个 anchor
        for mid, r1, w1 in adjacency.get(a_id, []):
            if mid in anchor_ids or not _usable(r1):
                continue
            for nb, r2, w2 in adjacency.get(mid, []):
                if nb == a_id or nb not in anchor_ids or not _usable(r2):
                    continue
                _emit(
                    [a_id, mid, nb],
                    [_rel(a_id, mid, r1), _rel(mid, nb, r2)],
                    min(a_s, anchor_score[nb]) * w1 * w2,
                )

    paths.sort(key=lambda p: p["score"], reverse=True)
    return paths[:max_paths]