ltcai 10.9.0 → 11.0.1

package/lattice_brain/graph/proactive.py

@@ -48,6 +48,21 @@ _DEFAULT_CONTRADICTION_NODES = 300
 _DEFAULT_NEAR_THRESHOLD = 0.75
 _DEFAULT_MAX_PAIRS = 200
 _DEFAULT_STALE_DAYS = 90  # mirrors MemoryQualityManager.apply_retention
+_DEFAULT_HALF_LIFE_DAYS = 30.0
+# Node types that record *what happened* rather than *what is known*. Only
+# these are offered for consolidation: folding a Decision or a Document into a
+# summary would lose the thing the user actually keeps a Brain for.
+_EPISODIC_TYPES = frozenset(
+    {
+        "chat",
+        "conversation",
+        "message",
+        "airesponse",
+        "ai_response",
+        "event",
+        "chunk",
+    }
+)
 
 
 def _parse_ts(value: Any) -> Optional[datetime]:
@@ -78,6 +93,28 @@ def _node_text(node: Dict[str, Any]) -> str:
     return f"{title} {summary}".strip()
 
 
+def _is_episodic(node: Dict[str, Any]) -> bool:
+    return str(node.get("type") or "").strip().lower() in _EPISODIC_TYPES
+
+
+def _access_count(node: Dict[str, Any], stored: Optional[Dict[str, Any]]) -> float:
+    """Access count for a node: ingested metadata first, then the store counter.
+
+    A surface that already tracks reads (``metadata.access_count``) is more
+    accurate than our own read-path counter, so it wins; ``0`` from metadata is
+    a real answer and is not treated as "missing".
+    """
+    metadata = node.get("metadata")
+    if isinstance(metadata, dict):
+        for key in ("access_count", "accesses", "access"):
+            value = metadata.get(key)
+            if isinstance(value, (int, float)) and not isinstance(value, bool):
+                return float(value)
+    if stored is None:
+        return 0.0
+    return float(stored.get("accesses") or 0.0)
+
+
 def _slim(node: Dict[str, Any]) -> Dict[str, Any]:
     return {
         "id": node.get("id"),
@@ -129,6 +166,17 @@ class ProactiveBrain:
             edges.append(normalized)
         return {"nodes": nodes, "edges": edges}
 
+    def sample(
+        self, *, workspace_id: Optional[str] = None, limit: Optional[int] = None
+    ) -> Dict[str, List[Dict[str, Any]]]:
+        """One normalized graph sample (``source``/``target`` edge keys).
+
+        Public seam for :mod:`lattice_brain.synthesis`, which needs the *same*
+        sample for several passes; taking it once keeps a synthesis run to one
+        graph read and keeps every pass looking at identical data.
+        """
+        return self._sample(workspace_id=workspace_id, limit=limit)
+
     # ── duplicates ───────────────────────────────────────────────────────
 
     def find_duplicates(
@@ -246,6 +294,16 @@ class ProactiveBrain:
             sample["nodes"], sample["edges"], max_nodes=max_nodes
         )
 
+    def contradictions_in(
+        self,
+        nodes: List[Dict[str, Any]],
+        edges: List[Dict[str, Any]],
+        *,
+        max_nodes: int = _DEFAULT_CONTRADICTION_NODES,
+    ) -> Dict[str, Any]:
+        """Contradiction signals over an already-taken :meth:`sample`."""
+        return self._detect_contradictions_in(nodes, edges, max_nodes=max_nodes)
+
     def _detect_contradictions_in(
         self,
         nodes: List[Dict[str, Any]],
@@ -403,6 +461,85 @@ class ProactiveBrain:
             "generated_at": datetime.now(timezone.utc).isoformat(),
         }
 
+    # ── importance & decay (v11.1.0) ─────────────────────────────────────
+
+    def importance_report(
+        self,
+        *,
+        workspace_id: Optional[str] = None,
+        limit: Optional[int] = None,
+        half_life_days: float = _DEFAULT_HALF_LIFE_DAYS,
+        max_candidates: int = 20,
+        sample: Optional[Dict[str, List[Dict[str, Any]]]] = None,
+    ) -> Dict[str, Any]:
+        """Score every sampled node by use, then name the weakest episodic ones.
+
+        The score is deliberately boring and reproducible — no model, no
+        randomness::
+
+            score = (1 + accesses + degree) * 0.5 ** (age_days / half_life)
+
+        *accesses* prefers a real counter: ``metadata.access_count`` when the
+        ingesting surface recorded one, otherwise the store's own read-path
+        counter (``access_stats``), otherwise zero. *Episodic* types (chats,
+        messages, events, chunks) are the only consolidation candidates —
+        a decayed Document or Decision is stale knowledge to review, not
+        noise to fold away.
+        """
+        data = sample if sample is not None else self._sample(
+            workspace_id=workspace_id, limit=limit
+        )
+        nodes, edges = data["nodes"], data["edges"]
+        degree: Dict[str, int] = {}
+        for edge in edges:
+            for key in ("source", "target"):
+                node_id = str(edge.get(key) or "")
+                if node_id:
+                    degree[node_id] = degree.get(node_id, 0) + 1
+
+        stats_fn = getattr(self._store, "access_stats", None)
+        stored: Dict[str, Any] = {}
+        if callable(stats_fn):
+            try:
+                stored = dict(stats_fn([n.get("id") for n in nodes]) or {})
+            except Exception:  # noqa: BLE001 — the report degrades, never fails
+                logger.exception("access stats read failed")
+
+        now = datetime.now(timezone.utc)
+        half_life = max(0.5, float(half_life_days))
+        scored: List[Dict[str, Any]] = []
+        for node in nodes:
+            node_id = str(node.get("id") or "")
+            accesses = _access_count(node, stored.get(node_id))
+            ts = _parse_ts(node.get("updated_at"))
+            age_days = 0.0 if ts is None else max(
+                0.0, (now - ts).total_seconds() / 86400.0
+            )
+            decay = 0.5 ** (age_days / half_life)
+            scored.append(
+                {
+                    **_slim(node),
+                    "accesses": accesses,
+                    "degree": degree.get(node_id, 0),
+                    "age_days": round(age_days, 2),
+                    "score": round((1.0 + accesses + degree.get(node_id, 0)) * decay, 4),
+                    "episodic": _is_episodic(node),
+                }
+            )
+        scored.sort(key=lambda item: (item["score"], str(item.get("id") or "")))
+        candidates = [item for item in scored if item["episodic"]][
+            : max(1, int(max_candidates))
+        ]
+        return {
+            "nodes_scanned": len(nodes),
+            "half_life_days": half_life,
+            "access_source": "store" if stored else "metadata",
+            "candidates": candidates,
+            "candidate_count": len(candidates),
+            "strongest": list(reversed(scored[-5:])),
+            "generated_at": datetime.now(timezone.utc).isoformat(),
+        }
+
     # ── consolidation ────────────────────────────────────────────────────
 
     def consolidate_duplicates(
@@ -470,7 +607,7 @@ class ProactiveBrain:
             for group in groups:
                 try:
                     if merge_fn is None:  # guarded by apply_supported above
-                        raise RuntimeError("store has no merge_nodes")
+                        raise RuntimeError("store has no merge_nodes")  # pragma: no cover — unreachable: callable(merge_fn) above proves it is not None
                     result = merge_fn(group["keep"], group["remove"])
                     applied.append({"keep": group["keep"], "result": result})
                 except Exception as exc:  # keep going; report per-group failure

package/lattice_brain/graph/projection.py

@@ -52,6 +52,12 @@ class KnowledgeGraphProjectionMixin(_Core):
         END;
         """
 
+    # The temporal columns pass through *raw* (v11.1.0). ``type`` is COALESCEd
+    # because ``legacy_type`` carries the label a reader expects; validity is
+    # not a label — a COALESCE there would turn "still valid" (NULL) into a
+    # value, which is exactly the ``kgv2_edges`` trap noted in the 11.0.1
+    # review. NULL in, NULL out; the fallback to ``created_at`` belongs to the
+    # read predicate (``schema.TEMPORAL_PREDICATE_SQL``), not to the view.
     _V2_VIEWS_SQL = """
         CREATE VIEW IF NOT EXISTS kgv2_nodes AS
           SELECT id,
@@ -59,14 +65,16 @@ class KnowledgeGraphProjectionMixin(_Core):
                  label AS title,
                  summary,
                  attrs AS metadata_json,
-                 created_at, updated_at
+                 created_at, updated_at,
+                 valid_from, valid_to, superseded_by
           FROM nodes_v2;
         CREATE VIEW IF NOT EXISTS kgv2_edges AS
           SELECT id, source AS from_node, target AS to_node,
                  COALESCE(legacy_type, type) AS type,
                  weight,
                  metadata AS metadata_json,
-                 created_at
+                 created_at,
+                 valid_from, valid_to, superseded_by
           FROM edges_v2;
         """
 

package/lattice_brain/graph/retrieval.py

@@ -20,6 +20,13 @@ else:
 # traverse / stats) moved byte-identically to .retrieval_reads as
 # KnowledgeGraphReadsMixin. Re-exported here so any legacy
 # ``from lattice_brain.graph.retrieval import ...`` site keeps resolving.
+from .fusion import (
+    DEFAULT_EXPANSION_CAP,
+    DEFAULT_EXPANSION_SEEDS,
+    expand_with_neighbors,
+    graph_expansion_enabled,
+    rrf_fuse,
+)
 from .retrieval_reads import KnowledgeGraphReadsMixin  # noqa: F401
 
 
@@ -28,6 +35,7 @@ def context_quality_signal(
     nodes: int,
     *,
     reason: Optional[str] = None,
+    vector: Optional[Dict[str, Any]] = None,
 ) -> Dict[str, Any]:
     """Honest RAG context-quality signal (v9.8.0, additive contract).
 
@@ -37,6 +45,15 @@ def context_quality_signal(
     ``"none"``; ``limited`` is true whenever the context is thin (0–1 nodes)
     or the vector side fell back to lexical-only retrieval. ``reason`` is a
     short human-readable Korean phrase, only present when limited.
+
+    ``vector`` (v11.1.0) carries the vector channel's own honesty block —
+    which backend scored, whether it was approximate, whether the candidate
+    scan was truncated. "hybrid, 6 nodes" describes two different answers
+    depending on those bits, and the caller that has to say "I did not find
+    it" deserves to know which one it got. The key is present **only when
+    there is a caveat to report**: an exact, complete vector scan is the
+    contract's baseline assumption, so annotating it would be noise, and the
+    four-key shape stays exactly what existing consumers pin.
     """
     nodes = max(0, int(nodes or 0))
     mode = str(mode or "none")
@@ -54,7 +71,15 @@ def context_quality_signal(
             reason = "그래프 기반 컨텍스트가 제한적입니다"
     if not limited:
         reason = None
-    return {"mode": mode, "nodes": nodes, "limited": limited, "reason": reason}
+    signal: Dict[str, Any] = {
+        "mode": mode,
+        "nodes": nodes,
+        "limited": limited,
+        "reason": reason,
+    }
+    if vector is not None:
+        signal["vector"] = dict(vector)
+    return signal
 
 
 class KnowledgeGraphRetrievalMixin(_Core):
@@ -162,7 +187,7 @@ class KnowledgeGraphRetrievalMixin(_Core):
             from_node = node_by_id.get(edge["from"])
             to_node = node_by_id.get(edge["to"])
             if not from_node or not to_node:
-                continue
+                continue  # pragma: no cover — unreachable: the edge query selects endpoints from the same node window
             for topic_node, other_node in ((from_node, to_node), (to_node, from_node)):
                 if topic_node["type"] != "Topic":
                     continue
@@ -404,6 +429,10 @@ class KnowledgeGraphRetrievalMixin(_Core):
         search_query = query
         rewrite_rules: List[str] = []
         recency_half_life_days: Optional[float] = None
+        # "alpha" is the historical linear fusion; the policy may select RRF
+        # per query class. An explicitly pinned ``alpha`` argument means the
+        # caller is asking for linear fusion by name, so it stays linear.
+        fusion_strategy = "alpha"
         if alpha is None:
             try:
                 from .retrieval_policy import resolve_policy
@@ -411,6 +440,7 @@ class KnowledgeGraphRetrievalMixin(_Core):
                 policy = resolve_policy(query)
                 query_class = policy["query_class"]
                 alpha = float(policy["alpha"])
+                fusion_strategy = str(policy.get("fusion_strategy") or "alpha")
                 rewrite_rules = list(policy.get("rewrite_rules") or [])
                 rewritten = str(policy.get("search_query") or "")
                 if rewritten and rewritten != query:
@@ -438,6 +468,7 @@ class KnowledgeGraphRetrievalMixin(_Core):
                 "sources": {"lexical": 0, "vector": 0},
                 "matches": [],
                 "policy": {"search_query": search_query, "rewrite_rules": rewrite_rules},
+                "fusion_strategy": fusion_strategy,
                 "detail": None,
             }
 
@@ -455,6 +486,16 @@ class KnowledgeGraphRetrievalMixin(_Core):
         detail: Optional[str] = None
         vector_matches: List[Dict[str, Any]] = []
         vector_recall: Optional[Dict[str, Any]] = None
+        # The vector channel's own honesty block, echoed additively so a
+        # caller can tell an exact "not found" from an approximate one.
+        vector_meta: Dict[str, Any] = {
+            "backend": None,
+            "approx": None,
+            "exhaustive": None,
+            "truncated": None,
+            "embedded_rows": None,
+            "degraded": None,
+        }
         vector_fn = getattr(self, "vector_search", None)
         if not callable(vector_fn):
             mode = "lexical_only"
@@ -471,8 +512,16 @@ class KnowledgeGraphRetrievalMixin(_Core):
                 # retrieval_vector.vector_search), and a fused answer built on
                 # a truncated scan is not the same claim as a complete one.
                 recall = vector_payload.get("recall")
-                if isinstance(recall, dict) and recall.get("truncated"):
-                    vector_recall = dict(recall)
+                if isinstance(recall, dict):
+                    vector_meta["backend"] = recall.get("backend")
+                    vector_meta["truncated"] = bool(recall.get("truncated"))
+                    vector_meta["embedded_rows"] = recall.get("candidates_total")
+                    if recall.get("truncated"):
+                        vector_recall = dict(recall)
+                index_block = vector_payload.get("index")
+                if isinstance(index_block, dict):
+                    vector_meta["approx"] = bool(index_block.get("approx"))
+                    vector_meta["exhaustive"] = bool(index_block.get("exhaustive"))
             except Exception as exc:  # noqa: BLE001 — degrade, never fail the search
                 mode = "lexical_only"
                 detail = f"vector index unavailable: {exc}"
@@ -525,6 +574,11 @@ class KnowledgeGraphRetrievalMixin(_Core):
                 entries[node_id] = entry
             return entry
 
+        # Per-channel id order (best first) — the only input RRF needs, and
+        # the one thing a normalized score cannot reconstruct.
+        lexical_order: List[str] = []
+        vector_order: List[str] = []
+
         for rank, match in enumerate(lexical_matches, start=1):
             node_id = _parent_node_id(match)
             if not node_id:
@@ -534,6 +588,7 @@ class KnowledgeGraphRetrievalMixin(_Core):
                 entry["scores"]["lexical"], round(1.0 / rank, 6)
             )
             entry["_lexical"] = True
+            lexical_order.append(node_id)
 
         # Max-normalize cosine scores into [0, 1] (guard the score-0 falsy trap
         # by comparing explicitly, never with truthiness).
@@ -551,27 +606,86 @@ class KnowledgeGraphRetrievalMixin(_Core):
             entry = _entry_for(node_id, match)
             entry["scores"]["vector"] = max(entry["scores"]["vector"], round(vec_norm, 6))
             entry["_vector"] = True
+            vector_order.append(node_id)
             # Prefer a real snippet when the lexical row had no summary.
             if not entry.get("summary") and match.get("summary"):
                 entry["summary"] = match.get("summary")
 
+        # Graph traversal candidate expansion (opt-in, capped, counted): pull
+        # the one-hop neighbours of the strongest hits into the candidate pool
+        # so an answer that is adjacent to the match — not in it — is
+        # reachable at all. Off by default; see fusion.GRAPH_EXPANSION_ENV.
+        expansion_report: Dict[str, Any] = {
+            "enabled": False,
+            "seeds": 0,
+            "added": 0,
+            "cap": DEFAULT_EXPANSION_CAP,
+            "truncated": False,
+            "failed_seeds": 0,
+        }
+        if entries and graph_expansion_enabled():
+            seeds = sorted(
+                (
+                    (node_id, float(entry["scores"]["vector"]))
+                    for node_id, entry in entries.items()
+                ),
+                key=lambda pair: -pair[1],
+            )[:DEFAULT_EXPANSION_SEEDS]
+            expanded, expansion_report = expand_with_neighbors(
+                seeds,
+                self.neighbors,
+                exclude=list(entries),
+                cap=DEFAULT_EXPANSION_CAP,
+            )
+            for candidate in expanded:
+                node = candidate["node"]
+                entry = _entry_for(str(node.get("id")), dict(node))
+                entry["scores"]["graph"] = candidate["score"]
+                entry["metadata"] = {
+                    **(entry.get("metadata") or {}),
+                    "expanded_from": candidate["seed"],
+                }
+                entry["_graph"] = True
+
+        rrf_normalized: Dict[str, float] = {}
+        if fusion_strategy == "rrf":
+            raw_rrf = rrf_fuse(
+                {
+                    "lexical": list(dict.fromkeys(lexical_order)),
+                    "vector": list(dict.fromkeys(vector_order)),
+                }
+            )
+            peak = max(raw_rrf.values(), default=0.0)
+            if peak > 0:
+                # Rescale to [0, 1] so the score column keeps the same meaning
+                # across strategies; RRF's raw values live around 1/60.
+                rrf_normalized = {key: value / peak for key, value in raw_rrf.items()}
+
         matches: List[Dict[str, Any]] = []
         for entry in entries.values():
             lex_score = float(entry["scores"]["lexical"])
             vec_score = float(entry["scores"]["vector"])
             if mode == "lexical_only":
                 fused = lex_score
+            elif fusion_strategy == "rrf":
+                fused = float(rrf_normalized.get(entry["node_id"], 0.0))
+                entry["scores"]["rrf"] = round(fused, 6)
             else:
                 fused = alpha * vec_score + (1.0 - alpha) * lex_score
-            entry["score"] = round(fused, 6)
             from_lexical = bool(entry.pop("_lexical", False))
             from_vector = bool(entry.pop("_vector", False))
-            if from_lexical and from_vector:
+            if entry.pop("_graph", False):
+                # A one-hop neighbour of a hit: related to the answer, never
+                # itself a match, so it carries only its damped seed score.
+                fused = float(entry["scores"]["graph"])
+                entry["fusion"] = "graph"
+            elif from_lexical and from_vector:
                 entry["fusion"] = "both"
             elif from_vector:
                 entry["fusion"] = "vector"
             else:
                 entry["fusion"] = "lexical"
+            entry["score"] = round(fused, 6)
             matches.append(entry)
 
         # Recency-class age decay (retrieval_policy): dampen each fused score
@@ -622,6 +736,8 @@ class KnowledgeGraphRetrievalMixin(_Core):
             "sources": {"lexical": len(lexical_matches), "vector": len(vector_matches)},
             "matches": matches,
             "policy": {"search_query": search_query, "rewrite_rules": rewrite_rules},
+            "fusion_strategy": fusion_strategy,
+            "graph_expansion": expansion_report,
             "rerank": rerank_meta,
             "detail": detail,
         }
@@ -631,6 +747,8 @@ class KnowledgeGraphRetrievalMixin(_Core):
             result["vector_recall"] = vector_recall
             if vector_degraded is None:
                 result["vector_degraded"] = "partial_recall"
+        vector_meta["degraded"] = result.get("vector_degraded")
+        result["vector"] = vector_meta
         return result
 
     def context_for_query(
@@ -669,6 +787,7 @@ class KnowledgeGraphRetrievalMixin(_Core):
             return ""
         matches: List[Dict[str, Any]] = []
         retrieval_mode = "none"
+        vector_meta: Optional[Dict[str, Any]] = None
         if use_hybrid:
             try:
                 hybrid = self.hybrid_search(
@@ -678,6 +797,15 @@ class KnowledgeGraphRetrievalMixin(_Core):
                     include_legacy_global=include_legacy_global,
                 )
                 matches = hybrid.get("matches", [])
+                vector_block = hybrid.get("vector") or {}
+                # Only a caveat is worth carrying: approximate scoring, a
+                # truncated candidate scan, or an already-flagged degradation.
+                if (
+                    vector_block.get("approx")
+                    or vector_block.get("truncated")
+                    or vector_block.get("degraded")
+                ):
+                    vector_meta = dict(vector_block)
                 if matches:
                     retrieval_mode = str(hybrid.get("mode") or "hybrid")
             except Exception:  # noqa: BLE001 — context building must never fail
@@ -754,7 +882,9 @@ class KnowledgeGraphRetrievalMixin(_Core):
             return context
         return {
             "context": context,
-            "quality": context_quality_signal(retrieval_mode, len(matches[:limit])),
+            "quality": context_quality_signal(
+                retrieval_mode, len(matches[:limit]), vector=vector_meta
+            ),
         }
 
     def context_for_query_with_meta(

package/lattice_brain/graph/retrieval_docgen.py

@@ -46,26 +46,26 @@ class KnowledgeGraphDocGenMixin(_Core):
             candidate_rows = []
             seen_ids = set()
 
-            if query:
-                q = f"%{query}%"
-                rows = conn.execute(
-                    f"""
-                        SELECT id, type, title, summary, metadata_json, updated_at
-                        FROM {nt}
-                        WHERE (title LIKE ? OR summary LIKE ? OR metadata_json LIKE ?)
-                          AND type IN ('Document', 'File', 'CodeFile', 'SlideDeck',
-                                       'Spreadsheet', 'Image', 'ImageText', 'Chat',
-                                       'Decision', 'Task', 'Concept', 'Feature',
-                                       'Page', 'Slide')
-                        ORDER BY updated_at DESC, id ASC
-                        LIMIT ?
-                        """,
-                    (q, q, q, limit * 5),
-                ).fetchall()
-                for row in rows:
-                    if row["id"] not in seen_ids:
-                        seen_ids.add(row["id"])
-                        candidate_rows.append(row)
+            # `query` is non-empty here — the early return above took the blank case.
+            q = f"%{query}%"
+            rows = conn.execute(
+                f"""
+                    SELECT id, type, title, summary, metadata_json, updated_at
+                    FROM {nt}
+                    WHERE (title LIKE ? OR summary LIKE ? OR metadata_json LIKE ?)
+                      AND type IN ('Document', 'File', 'CodeFile', 'SlideDeck',
+                                   'Spreadsheet', 'Image', 'ImageText', 'Chat',
+                                   'Decision', 'Task', 'Concept', 'Feature',
+                                   'Page', 'Slide')
+                    ORDER BY updated_at DESC, id ASC
+                    LIMIT ?
+                    """,
+                (q, q, q, limit * 5),
+            ).fetchall()
+            for row in rows:
+                if row["id"] not in seen_ids:
+                    seen_ids.add(row["id"])
+                    candidate_rows.append(row)
 
             for term in terms:
                 t = f"%{term}%"

package/lattice_brain/graph/retrieval_policy.py

@@ -139,12 +139,17 @@ def resolve_policy(
           "query_class": "fact" | "code" | "person" | "recency",
           "weights": {"keyword", "vector", "graph"},   # service fusion
           "alpha": float,                              # graph-layer fusion
+          "fusion_strategy": "alpha" | "rrf",          # how they combine
           "original_query": str,
           "search_query": str,       # the rewritten form to search with
           "rewrite_rules": [str],
           "recency_half_life_days": float | None,      # 14.0 only for recency
         }
 
+    ``fusion_strategy`` is ``"alpha"`` for every class unless
+    ``LATTICEAI_FUSION_STRATEGY`` says otherwise, so the default policy is
+    byte-identical to the pre-11.1.0 one.
+
     ``recency_half_life_days`` is non-``None`` only for the ``recency``
     class — the honest contract that age decay applies exactly where the
     fusion layers wire it, and nowhere else.
@@ -157,6 +162,7 @@ def resolve_policy(
         "query_class": query_class,
         "weights": dict(profile["weights"]),
         "alpha": float(profile["alpha"]),
+        "fusion_strategy": str(profile["strategy"]),
         "original_query": rewrite["original"],
         "search_query": search_query,
         "rewrite_rules": list(rewrite["rules"]),