ltcai 11.2.0 → 11.4.0

package/latticeai/services/brain_intelligence/_contract.py

@@ -0,0 +1,71 @@
+"""The seam the Brain Intelligence mixins share.
+
+``BrainIntelligenceService`` is assembled from the proposal, sampling, health,
+digest and consistency mixins. Each reads constructor state it does not own,
+and several call methods another mixin implements — ``_graph_sample`` feeds
+almost everything, ``_proactive`` gates the graph-layer surfaces, and the
+garden view composes the contradiction scan. That contract existed as an
+unwritten convention inside one class; this module writes it down.
+
+Typing-only, exactly like :mod:`lattice_brain.portability._contract`: every
+body below is a bare ``raise NotImplementedError`` that the composed class
+always overrides, so the MRO and every method resolution stay what the
+single-file class had. Adding a cross-mixin call without declaring it here is a
+type error.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+
+class BrainIntelligenceCore:
+    """What any Brain Intelligence mixin may assume about ``self``.
+
+    Members are declared, not implemented: the implementation lives in
+    ``service.py`` (constructor state) or in whichever mixin owns the method.
+    """
+
+    # ── State owned by BrainIntelligenceService.__init__ ─────────────────────
+    _kg: Any
+    _memory: Any
+    _enable_graph: bool
+    _memory_quality: Any
+    _edge_quality: Any
+    _proactive_brain: Any
+    _review_queue_service: Any
+    _synthesizer: Any
+
+    # ── proposals.py: the review-queue seam every write door goes through ────
+    def _review_queue(self) -> Any:
+        raise NotImplementedError
+
+    def _synthesis(self) -> Any:
+        raise NotImplementedError
+
+    @staticmethod
+    def _no_queue(detail: str) -> Dict[str, Any]:
+        raise NotImplementedError
+
+    def importance_report(
+        self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        raise NotImplementedError
+
+    # ── sampling.py: the graph slice and the memory tier ─────────────────────
+    def _proactive(self) -> Any:
+        raise NotImplementedError
+
+    def _graph_sample(self, *, workspace_id: Optional[str]) -> Dict[str, Any]:
+        raise NotImplementedError
+
+    def _workspace_memories(
+        self, *, user_email: Optional[str], workspace_id: Optional[str]
+    ) -> List[Dict[str, Any]]:
+        raise NotImplementedError
+
+    # ── consistency.py: what the garden view composes ────────────────────────
+    def contradictions(
+        self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        raise NotImplementedError

package/latticeai/services/brain_intelligence/consistency.py

@@ -0,0 +1,193 @@
+"""What the Brain disagrees with itself about, and what it says twice.
+
+Two scans that wire the previously dormant quality layer
+(:mod:`lattice_brain.quality`) to real stores:
+
+* :meth:`contradictions` — four independent signals in one list: negation and
+  preference conflicts between workspace memories, temporal contradictions,
+  explicit ``CONTRADICTS`` edges already recorded in the graph, and the graph
+  layer's own node-content detector. Each item carries the signal that found
+  it, so a reviewer can weigh them differently.
+* :meth:`consolidate` — duplicate memories and duplicate edges. Dry-run by
+  default, consent-first like every Brain automation. ``apply=True`` prunes
+  only exact duplicate *workspace memories*, through the audited MemoryService
+  path; graph content is never mutated here — the node merge plan is surfaced
+  for a governed apply path to adopt.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from latticeai.core.timeutil import now_iso as _now
+
+from ._contract import BrainIntelligenceCore as _Core
+from .constants import LOGGER
+
+
+class BrainConsistencyMixin(_Core):
+    """Contradiction and consolidation scans. Mixed into the service."""
+
+    # ── contradictions ───────────────────────────────────────────────────
+
+    def contradictions(
+        self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        memories = self._workspace_memories(user_email=user_email, workspace_id=workspace_id)
+        memory_rows = [
+            {
+                "id": str(m.get("id") or f"mem-{i}"),
+                "content": str(m.get("content") or ""),
+                "score": 0.6,
+                "source": "workspace",
+                "timestamp": m.get("created_at") or m.get("timestamp") or 0,
+            }
+            for i, m in enumerate(memories)
+            if str(m.get("content") or "").strip()
+        ]
+
+        conflicts: List[Dict[str, Any]] = []
+        candidates = self._memory_quality.extract_candidates(memory_rows)
+        for candidate in self._memory_quality.detect_conflicts(candidates):
+            pair_conflicts = [c for c in candidate.conflicts if c.startswith("conflict:contradicts:")]
+            for marker in pair_conflicts:
+                other_id = marker.rsplit(":", 1)[-1]
+                if any(
+                    c["kind"] == "memory_pair"
+                    and {c["left_id"], c["right_id"]} == {candidate.id, other_id}
+                    for c in conflicts
+                ):
+                    continue
+                other: Dict[str, Any] | None = next(
+                    (r for r in memory_rows if r["id"] == other_id), None
+                )
+                conflicts.append({
+                    "kind": "memory_pair",
+                    "left_id": candidate.id,
+                    "left_content": candidate.content[:200],
+                    "right_id": other_id,
+                    "right_content": (other or {}).get("content", "")[:200],
+                    "signal": "preference_negation",
+                })
+
+        temporal = self._memory_quality.detect_temporal_contradictions(memory_rows)
+        temporal_items = [
+            {
+                "kind": "temporal",
+                "id": item.get("id"),
+                "content": str(item.get("content") or "")[:200],
+                "signal": item.get("proactive_flag"),
+            }
+            for item in temporal
+        ]
+
+        edge_items: List[Dict[str, Any]] = []
+        sample = self._graph_sample(workspace_id=workspace_id)
+        for edge in sample["edges"]:
+            if "CONTRADICT" in str(edge.get("type") or "").upper():
+                edge_items.append({
+                    "kind": "graph_edge",
+                    "id": edge.get("id"),
+                    "source": edge.get("source") or edge.get("from_node"),
+                    "target": edge.get("target") or edge.get("to_node"),
+                    "signal": "contradicts_edge",
+                })
+
+        # v9.6.x additive: graph-layer node-content contradictions (proactive
+        # detector over node title/summary), on top of the memory + edge scans.
+        graph_pair_items: List[Dict[str, Any]] = []
+        proactive = self._proactive()
+        if proactive is not None:
+            try:
+                graph_result = proactive.detect_contradictions(workspace_id=workspace_id)
+                graph_pair_items = [
+                    {"kind": "graph_node_pair", **pair}
+                    for pair in graph_result.get("node_pairs") or []
+                ]
+            except Exception:
+                LOGGER.exception("graph contradiction scan failed")
+
+        items = conflicts + temporal_items + edge_items + graph_pair_items
+        return {
+            "items": items,
+            "count": len(items),
+            "sources": {
+                "memory_pairs": len(conflicts),
+                "temporal": len(temporal_items),
+                "graph_edges": len(edge_items),
+                "graph_node_pairs": len(graph_pair_items),
+            },
+            "memories_scanned": len(memory_rows),
+            "generated_at": _now(),
+        }
+
+    # ── consolidation ────────────────────────────────────────────────────
+
+    def consolidate(
+        self,
+        *,
+        apply: bool = False,
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        memories = self._workspace_memories(user_email=user_email, workspace_id=workspace_id)
+        memory_rows = [
+            {
+                "id": str(m.get("id") or f"mem-{i}"),
+                "content": str(m.get("content") or ""),
+                "score": 0.6,
+                "source": "workspace",
+            }
+            for i, m in enumerate(memories)
+            if str(m.get("content") or "").strip()
+        ]
+        candidates = self._memory_quality.extract_candidates(memory_rows)
+        kept = self._memory_quality.dedupe(candidates)
+        kept_ids = {c.id for c in kept}
+        duplicate_memory_ids = [c.id for c in candidates if c.id not in kept_ids]
+
+        sample = self._graph_sample(workspace_id=workspace_id)
+        duplicate_edge_ids = [
+            edge_id
+            for edge_id in self._edge_quality.detect_duplicate_edges(sample["edges"])
+            if edge_id
+        ]
+
+        pruned = 0
+        if apply and duplicate_memory_ids and self._memory is not None:
+            try:
+                result = self._memory.prune(
+                    ids=duplicate_memory_ids,
+                    user_email=user_email,
+                    workspace_id=workspace_id,
+                )
+                pruned = int(result.get("count") or 0)
+            except Exception:
+                LOGGER.exception("consolidation prune failed")
+
+        # v9.6.x additive: graph-layer node merge plan. Always dry-run from
+        # this service — graph content changes stay proposal-first; the plan
+        # is surfaced so a governed apply path can adopt it later.
+        graph_consolidation: Optional[Dict[str, Any]] = None
+        proactive = self._proactive()
+        if proactive is not None:
+            try:
+                graph_consolidation = proactive.consolidate_duplicates(
+                    workspace_id=workspace_id, dry_run=True
+                )
+            except Exception:
+                LOGGER.exception("graph consolidation plan failed")
+
+        return {
+            "mode": "applied" if apply else "dry_run",
+            "memories_scanned": len(memory_rows),
+            "duplicate_memories": duplicate_memory_ids,
+            "duplicate_memory_count": len(duplicate_memory_ids),
+            "pruned": pruned,
+            # Graph edges are reported for review only; consolidation never
+            # mutates graph content directly.
+            "duplicate_edges": duplicate_edge_ids[:50],
+            "duplicate_edge_count": len(duplicate_edge_ids),
+            "graph_consolidation": graph_consolidation,
+            "generated_at": _now(),
+        }

package/latticeai/services/brain_intelligence/constants.py

@@ -0,0 +1,47 @@
+"""Windows, sample sizes, and the two readings every surface shares.
+
+Leaf module: literals and pure functions only, no service and no store. The
+health report, the insights digest, the garden and the contradiction scan all
+measure against the same windows, which is what makes their numbers
+comparable.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+LOGGER = logging.getLogger(__name__)
+
+_STALE_DAYS = 45
+_RECENT_DAYS = 7
+_GRAPH_SAMPLE_LIMIT = 800
+
+
+def _parse_ts(value: Any) -> Optional[datetime]:
+    text = str(value or "").strip()
+    if not text:
+        return None
+    try:
+        parsed = datetime.fromisoformat(text.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed
+
+
+def _no_graph_reason(graph_available: bool) -> str:
+    """Why a graph-derived health dimension has nothing to say.
+
+    Two different situations that both end in ``status: "unavailable"``: the
+    graph could not be read at all, and the graph read fine but holds nothing
+    yet. Telling them apart is the difference between "something is broken"
+    and "you have not saved anything yet".
+    """
+    return (
+        "no knowledge saved yet"
+        if graph_available
+        else "the knowledge graph could not be read"
+    )

package/latticeai/services/brain_intelligence/digest.py

@@ -0,0 +1,258 @@
+"""What the Brain would tell you if you asked "what's going on in there?"
+
+Three read-only views over the same graph slice, each answering a different
+shape of that question:
+
+* :meth:`insights` — the proactive digest: recent growth, trending types, stale
+  knowledge, orphans, and questions grounded in real node titles;
+* :meth:`garden_overview` — the same knowledge as four beds a gardener tends
+  (new growth, weeds, neglect, load-bearing), because "how healthy is my
+  knowledge?" in aggregate is not a question anyone acts on;
+* :meth:`graph_duplicates` / :meth:`quality_report` — the graph layer's own
+  proactive scans, surfaced without applying anything.
+
+Honest when empty: an unavailable graph produces empty beds and
+``available: False``, never invented plants.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, List, Optional
+
+from latticeai.core.timeutil import now_iso as _now
+
+from ._contract import BrainIntelligenceCore as _Core
+from .constants import _RECENT_DAYS, _STALE_DAYS, LOGGER, _parse_ts
+
+
+class BrainDigestMixin(_Core):
+    """Insights, garden, and the graph-layer quality reads."""
+
+    # ── insights digest ──────────────────────────────────────────────────
+
+    def insights(
+        self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        sample = self._graph_sample(workspace_id=workspace_id)
+        nodes, edges = sample["nodes"], sample["edges"]
+        now = datetime.now(timezone.utc)
+        recent_cutoff = now - timedelta(days=_RECENT_DAYS)
+        stale_cutoff = now - timedelta(days=_STALE_DAYS)
+
+        recent_nodes: List[Dict[str, Any]] = []
+        stale_nodes: List[Dict[str, Any]] = []
+        type_counts: Dict[str, int] = {}
+        for node in nodes:
+            node_type = str(node.get("type") or "node")
+            ts = _parse_ts(node.get("updated_at"))
+            if ts is not None and ts >= recent_cutoff:
+                recent_nodes.append(node)
+                type_counts[node_type] = type_counts.get(node_type, 0) + 1
+            elif ts is not None and ts < stale_cutoff:
+                stale_nodes.append(node)
+
+        connected = set()
+        for edge in edges:
+            connected.add(str(edge.get("source") or edge.get("from_node") or ""))
+            connected.add(str(edge.get("target") or edge.get("to_node") or ""))
+        orphans = [n for n in nodes if str(n.get("id")) not in connected]
+
+        def _slim(node: Dict[str, Any]) -> Dict[str, Any]:
+            return {
+                "id": node.get("id"),
+                "type": node.get("type"),
+                "title": str(node.get("title") or "")[:120],
+                "updated_at": node.get("updated_at"),
+            }
+
+        trending = sorted(type_counts.items(), key=lambda kv: kv[1], reverse=True)[:5]
+        suggested_questions = [
+            f"{str(node.get('title') or '').strip()[:60]}에 대해 지금까지 알고 있는 것을 정리해줘"
+            for node in recent_nodes[:3]
+            if str(node.get("title") or "").strip()
+        ]
+
+        return {
+            "window_days": _RECENT_DAYS,
+            "activity": {
+                "recent_nodes": len(recent_nodes),
+                "recent_samples": [_slim(n) for n in recent_nodes[:8]],
+                "trending_types": [{"type": t, "count": c} for t, c in trending],
+            },
+            "attention": {
+                "stale_nodes": len(stale_nodes),
+                "stale_samples": [_slim(n) for n in stale_nodes[:8]],
+                "orphan_nodes": len(orphans),
+                "orphan_samples": [_slim(n) for n in orphans[:8]],
+            },
+            "suggested_questions": suggested_questions,
+            "graph_available": sample["available"],
+            "generated_at": _now(),
+        }
+
+    def garden_overview(
+        self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None,
+        limit: int = 8,
+    ) -> Dict[str, Any]:
+        """The knowledge garden in four beds (v9.9.7).
+
+        Living Brain answers "how healthy is my knowledge?" in aggregate.
+        A gardener asks four concrete questions instead, and this answers all
+        four from one workspace-scoped graph sample plus the memory tier:
+
+        * **recent** — what came in lately (the garden's new growth);
+        * **contradictions** — what disagrees with itself (needs weeding);
+        * **stale** — what has not been touched in a long time;
+        * **frequent** — what the rest of the graph leans on most (by degree).
+
+        Read-only and honest: when the graph is unavailable every bed is empty
+        and ``available`` is false — the view never invents plants.
+        """
+        # Explicit 0 clamps to 1 — `limit or 8` would silently re-expand it.
+        try:
+            limit = max(1, min(int(limit), 50))
+        except (TypeError, ValueError):
+            limit = 8
+        sample = self._graph_sample(workspace_id=workspace_id)
+        nodes, edges = sample["nodes"], sample["edges"]
+        now = datetime.now(timezone.utc)
+        recent_cutoff = now - timedelta(days=_RECENT_DAYS)
+        stale_cutoff = now - timedelta(days=_STALE_DAYS)
+
+        def _slim(node: Dict[str, Any], **extra: Any) -> Dict[str, Any]:
+            return {
+                "id": node.get("id"),
+                "type": node.get("type"),
+                "title": str(node.get("title") or "")[:120],
+                "updated_at": node.get("updated_at"),
+                **extra,
+            }
+
+        recent: List[Dict[str, Any]] = []
+        stale: List[Dict[str, Any]] = []
+        for node in nodes:
+            # Chunks are retrieval plumbing, not knowledge a gardener tends.
+            if str(node.get("type") or "") == "Chunk":
+                continue
+            ts = _parse_ts(node.get("updated_at"))
+            if ts is None:
+                continue
+            if ts >= recent_cutoff:
+                recent.append(node)
+            elif ts < stale_cutoff:
+                stale.append(node)
+        recent.sort(key=lambda n: str(n.get("updated_at") or ""), reverse=True)
+        stale.sort(key=lambda n: str(n.get("updated_at") or ""))
+
+        # "Frequent" is degree, not a guess: how many relations actually point
+        # at a node. Chunks are retrieval plumbing, never garden plants.
+        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
+        by_id = {str(node.get("id")): node for node in nodes}
+        frequent = [
+            _slim(by_id[node_id], degree=count)
+            for node_id, count in sorted(degree.items(), key=lambda kv: kv[1], reverse=True)
+            if node_id in by_id and str(by_id[node_id].get("type") or "") != "Chunk"
+        ][:limit]
+
+        contradiction_items: List[Dict[str, Any]] = []
+        contradiction_count = 0
+        try:
+            found = self.contradictions(user_email=user_email, workspace_id=workspace_id)
+            items = found.get("items") if isinstance(found, dict) else None
+            if isinstance(items, list):
+                contradiction_count = len(items)
+                contradiction_items = items[:limit]
+        except Exception:  # noqa: BLE001 — one empty bed, never a broken view
+            LOGGER.exception("garden overview contradictions failed")
+
+        return {
+            "available": sample["available"],
+            "window_days": _RECENT_DAYS,
+            "stale_threshold_days": _STALE_DAYS,
+            "beds": {
+                "recent": {
+                    "count": len(recent),
+                    "items": [_slim(node) for node in recent[:limit]],
+                },
+                "contradictions": {
+                    "count": contradiction_count,
+                    "items": contradiction_items,
+                },
+                "stale": {
+                    "count": len(stale),
+                    "items": [_slim(node) for node in stale[:limit]],
+                },
+                "frequent": {
+                    "count": len(frequent),
+                    "items": frequent,
+                },
+            },
+            "generated_at": _now(),
+        }
+
+    # ── graph-layer proactive quality (v9.6.x) ───────────────────────────
+
+    def graph_duplicates(
+        self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Duplicate graph nodes (exact groups + near pairs) — read only."""
+        proactive = self._proactive()
+        if proactive is None:
+            return {
+                "available": False,
+                "exact_groups": [],
+                "near_pairs": [],
+                "exact_duplicate_nodes": 0,
+                "nodes_scanned": 0,
+                "generated_at": _now(),
+            }
+        try:
+            result = dict(proactive.find_duplicates(workspace_id=workspace_id))
+        except Exception as exc:
+            LOGGER.exception("graph duplicates scan failed")
+            return {
+                "available": False,
+                "error": str(exc),
+                "exact_groups": [],
+                "near_pairs": [],
+                "exact_duplicate_nodes": 0,
+                "nodes_scanned": 0,
+                "generated_at": _now(),
+            }
+        result["available"] = True
+        result["generated_at"] = _now()
+        return result
+
+    def quality_report(
+        self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Combined graph quality report: duplicates, contradictions, stale
+        nodes, edge quality — one workspace-scoped graph sample."""
+        proactive = self._proactive()
+        if proactive is None:
+            return {"available": False, "generated_at": _now()}
+        try:
+            result = dict(proactive.quality_report(workspace_id=workspace_id))
+        except Exception as exc:
+            LOGGER.exception("graph quality report failed")
+            return {"available": False, "error": str(exc), "generated_at": _now()}
+        result["available"] = True
+        # v11.1.0: decay is part of quality, and "the Brain is tidying up" is a
+        # state the user is entitled to see rather than a background surprise.
+        importance = self.importance_report(
+            user_email=user_email, workspace_id=workspace_id
+        )
+        candidates = len(importance.get("candidates") or [])
+        result["importance"] = importance
+        result["tidying"] = bool(importance.get("available")) and candidates > 0
+        summary = dict(result.get("summary") or {})
+        summary["consolidation_candidates"] = candidates
+        result["summary"] = summary
+        result["generated_at"] = _now()
+        return result