ltcai 11.1.0 → 11.4.0

package/latticeai/services/brain_intelligence/proposals.py

@@ -0,0 +1,264 @@
+"""Synthesis never writes: it proposes, and the Review Center decides.
+
+Everything the Brain notices on its own arrives as a review proposal — new
+connections, contradictions, consolidation candidates, decayed importance. That
+makes the review queue a hard dependency of every method here: when it is
+absent they report ``available: False`` rather than falling back to a direct
+write.
+
+:meth:`proactive_brief` is the read-only counterpart. It counts what is already
+waiting rather than raising anything new, so opening the home screen never
+mutates the Brain.
+"""
+
+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 BrainProposalsMixin(_Core):
+    """The proposal path and the proactive brief. Mixed into the service."""
+
+    # ── proposal path (v11.1.0) ───────────────────────────────────────────
+    #
+    # Synthesis never writes: it proposes, and the Review Center decides. That
+    # makes the review queue a hard dependency of every method below — when it
+    # is absent they report ``available: False`` rather than falling back to a
+    # direct write.
+
+    def attach_review_queue(self, review_queue: Any) -> None:
+        """Bind the review queue proposals are written to (composition root)."""
+        self._review_queue_service = review_queue
+        self._synthesizer = None
+
+    def _review_queue(self) -> Any:
+        """The queue to propose into, or ``None`` when there is none.
+
+        Prefers an explicitly injected service. Otherwise it builds one over
+        the workspace store the memory service already holds — the same
+        ``WorkspaceOSStore`` every other ``ReviewQueueService`` in the process
+        is constructed over, so proposals land in the one inbox the user reads
+        even before the composition root injects the service directly.
+        """
+        if self._review_queue_service is not None:
+            return self._review_queue_service
+        store = getattr(self._memory, "_store", None)
+        if store is None or not hasattr(store, "create_review_item"):
+            return None
+        from latticeai.services.review_queue import ReviewQueueService
+
+        self._review_queue_service = ReviewQueueService(store=store)
+        return self._review_queue_service
+
+    def _synthesis(self) -> Any:
+        """Lazy :class:`BrainSynthesizer` over the graph + review queue."""
+        if self._synthesizer is not None:
+            return self._synthesizer
+        queue = self._review_queue()
+        if not self._enable_graph or queue is None:
+            return None
+        from lattice_brain.synthesis import BrainSynthesizer
+
+        self._synthesizer = BrainSynthesizer(self._kg, queue)
+        return self._synthesizer
+
+    @staticmethod
+    def _no_queue(detail: str) -> Dict[str, Any]:
+        return {"available": False, "detail": detail, "generated_at": _now()}
+
+    def synthesize(
+        self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Run one synthesis pass; every finding becomes a review proposal."""
+        synthesizer = self._synthesis()
+        if synthesizer is None:
+            return self._no_queue(
+                "synthesis needs both the knowledge graph and the review queue"
+            )
+        try:
+            result = dict(
+                synthesizer.run(workspace_id=workspace_id, user_email=user_email)
+            )
+        except Exception as exc:  # noqa: BLE001 — a failed pass is reported, not raised
+            LOGGER.exception("brain synthesis failed")
+            return {"available": False, "error": str(exc), "generated_at": _now()}
+        result["available"] = True
+        return result
+
+    def note_ingest(
+        self,
+        result: Any,
+        *,
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Ingest-driven trigger seam.
+
+        Hand every ingest result here; synthesis runs only once the configured
+        number of genuinely new nodes has accumulated. Returns the run result
+        when one fired, ``None`` otherwise — so an ingest path can call this
+        unconditionally and cheaply.
+        """
+        synthesizer = self._synthesis()
+        if synthesizer is None:
+            return None
+        try:
+            return synthesizer.run_if_due(
+                result, workspace_id=workspace_id, user_email=user_email
+            )
+        except Exception:  # noqa: BLE001 — synthesis must never break an ingest
+            LOGGER.exception("ingest-triggered synthesis failed")
+            return None
+
+    def propose_contradictions(
+        self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Raise a review proposal for every contradicting pair of memories."""
+        queue = self._review_queue()
+        if not self._enable_graph or queue is None:
+            return self._no_queue(
+                "contradiction proposals need both the knowledge graph and the review queue"
+            )
+        from lattice_brain.synthesis import propose_contradictions
+
+        try:
+            return propose_contradictions(
+                self._kg, queue, workspace_id=workspace_id, user_email=user_email
+            )
+        except Exception as exc:  # noqa: BLE001
+            LOGGER.exception("contradiction proposal pass failed")
+            return {"available": False, "error": str(exc), "generated_at": _now()}
+
+    def resolve_contradiction(
+        self,
+        item_id: str,
+        *,
+        resolution: str,
+        workspace_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Approve a contradiction proposal and apply its temporal stamps.
+
+        Raises ``ContradictionResolutionError`` (a ``ValueError``) for an
+        unknown resolution or a review item that is not a contradiction — the
+        router turns those into 400s.
+        """
+        queue = self._review_queue()
+        if not self._enable_graph or queue is None:
+            return self._no_queue(
+                "resolving a contradiction needs both the knowledge graph and the review queue"
+            )
+        from lattice_brain.synthesis import resolve_contradiction
+
+        result = dict(
+            resolve_contradiction(
+                self._kg,
+                queue,
+                item_id,
+                resolution=resolution,
+                workspace_id=workspace_id,
+            )
+        )
+        result["available"] = True
+        return result
+
+    def importance_report(
+        self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Which memories are load-bearing, and which have decayed into noise."""
+        proactive = self._proactive()
+        if proactive is None:
+            return {"available": False, "candidates": [], "generated_at": _now()}
+        try:
+            report = dict(proactive.importance_report(workspace_id=workspace_id))
+        except Exception as exc:  # noqa: BLE001
+            LOGGER.exception("importance report failed")
+            return {
+                "available": False,
+                "error": str(exc),
+                "candidates": [],
+                "generated_at": _now(),
+            }
+        report["available"] = True
+        return report
+
+    def proactive_brief(
+        self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """The Brain Brief's proactive section: what the Brain noticed on its own.
+
+        Read-only. It counts the proposals already waiting in the Review Center
+        rather than raising new ones, so opening the home screen never mutates
+        anything — and reports honestly when there is no queue to read.
+        """
+        section: Dict[str, Any] = {
+            "available": False,
+            "pending": {"total": 0, "by_kind": {}},
+            "tidying": False,
+            "headline": "",
+            "lines": [],
+            "generated_at": _now(),
+        }
+        queue = self._review_queue()
+        if queue is None:
+            section["detail"] = "the review queue is not available on this deployment"
+            return section
+        pending = self._pending_synthesis_items(queue, workspace_id=workspace_id)
+        by_kind: Dict[str, int] = {}
+        for item in pending:
+            kind = str(item.get("kind") or "suggestion")
+            by_kind[kind] = by_kind.get(kind, 0) + 1
+        synthesizer = self._synthesis()
+        brief: Dict[str, Any] = {}
+        if synthesizer is not None:
+            try:
+                brief = dict(
+                    synthesizer.brief_section(
+                        counts=by_kind, workspace_id=workspace_id
+                    )
+                )
+            except Exception:  # noqa: BLE001 — the section degrades, never raises
+                LOGGER.exception("synthesis brief section failed")
+        section.update(
+            {
+                "available": True,
+                "pending": {"total": len(pending), "by_kind": by_kind},
+                "items": [
+                    {
+                        "id": item.get("id"),
+                        "kind": item.get("kind"),
+                        "title": item.get("title"),
+                        "summary": item.get("summary"),
+                    }
+                    for item in pending[:5]
+                ],
+                "tidying": by_kind.get("consolidation", 0) > 0,
+                "headline": str(brief.get("headline") or ""),
+                "lines": list(brief.get("lines") or []),
+                "recent_nodes": brief.get("recent_nodes"),
+            }
+        )
+        return section
+
+    @staticmethod
+    def _pending_synthesis_items(
+        queue: Any, *, workspace_id: Optional[str]
+    ) -> List[Dict[str, Any]]:
+        from lattice_brain.synthesis import SYNTHESIS_REVIEW_SOURCE
+
+        try:
+            listing = queue.list(
+                workspace_id=workspace_id, source=SYNTHESIS_REVIEW_SOURCE
+            )
+        except Exception:  # noqa: BLE001 — an unreadable inbox reads as empty
+            LOGGER.exception("review queue listing failed")
+            return []
+        return [
+            item
+            for item in listing.get("items") or []
+            if str(item.get("effective_status") or item.get("status")) == "pending"
+        ]

package/latticeai/services/brain_intelligence/sampling.py

@@ -0,0 +1,84 @@
+"""How the service reaches the graph layer and the memory tier.
+
+One workspace-scoped graph slice (:meth:`_graph_sample`) feeds the health
+report, the insights digest, the garden and both consistency scans, so they all
+measure the same knowledge. The slice normalizes the store's ``from``/``to``
+edge keys to the ``source``/``target`` the quality layer expects — once, here,
+instead of at four call sites.
+
+Both readers degrade rather than raise: an unreadable graph reports
+``available: False`` and an unreadable memory tier reads as empty, because a
+diagnosis that crashes is worse than one that says it could not measure.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from ._contract import BrainIntelligenceCore as _Core
+from .constants import _GRAPH_SAMPLE_LIMIT, LOGGER
+
+
+class BrainSamplingMixin(_Core):
+    """The shared graph slice and memory read. Mixed into the service."""
+
+    def _proactive(self) -> Any:
+        """Lazy graph-layer ProactiveBrain over the injected store (or None)."""
+        if not self._enable_graph:
+            return None
+        if self._proactive_brain is None:
+            try:
+                from lattice_brain.graph.proactive import ProactiveBrain
+
+                self._proactive_brain = ProactiveBrain(
+                    self._kg, sample_limit=_GRAPH_SAMPLE_LIMIT
+                )
+            except Exception:
+                LOGGER.exception("proactive brain initialization failed")
+                return None
+        return self._proactive_brain
+
+    # ── shared graph sampling ─────────────────────────────────────────────
+
+    def _graph_sample(self, *, workspace_id: Optional[str]) -> Dict[str, Any]:
+        """Recent graph slice with scoping applied. Empty when graph is off."""
+        if not self._enable_graph:
+            return {"nodes": [], "edges": [], "available": False}
+        try:
+            kwargs: Dict[str, Any] = {}
+            if workspace_id is not None:
+                kwargs["allowed_workspaces"] = {workspace_id}
+            data = self._kg.graph(_GRAPH_SAMPLE_LIMIT, **kwargs)
+            edges = []
+            for edge in data.get("edges") or []:
+                # Store emits "from"/"to"; the quality layer expects
+                # "source"/"target". Normalize once here.
+                normalized = dict(edge)
+                normalized.setdefault("source", edge.get("from"))
+                normalized.setdefault("target", edge.get("to"))
+                edges.append(normalized)
+            return {
+                "nodes": list(data.get("nodes") or []),
+                "edges": edges,
+                "available": True,
+            }
+        except Exception as exc:
+            LOGGER.exception("brain intelligence graph sample failed")
+            return {"nodes": [], "edges": [], "available": False, "error": str(exc)}
+
+    def _workspace_memories(
+        self, *, user_email: Optional[str], workspace_id: Optional[str]
+    ) -> List[Dict[str, Any]]:
+        if self._memory is None:
+            return []
+        try:
+            inspected = self._memory.inspect(
+                "workspace",
+                user_email=user_email,
+                workspace_id=workspace_id or "personal",
+                limit=500,
+            )
+            return list(inspected.get("items") or [])
+        except Exception:
+            LOGGER.exception("brain intelligence memory read failed")
+            return []

package/latticeai/services/brain_intelligence/service.py

@@ -0,0 +1,48 @@
+"""The composed Brain Intelligence service — injected collaborators, five surfaces.
+
+``BrainIntelligenceService`` owns the state every mixin reads (the Knowledge
+Graph, the memory service, the two quality managers, and the lazily built
+proactive brain / synthesizer) and inherits its behaviour from the proposal,
+sampling, health, digest and consistency mixins. Same public surface, same
+method resolution, in six readable files instead of one eleven-hundred-line
+one.
+
+Pure service: no FastAPI, no globals. Collaborators are injected.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from lattice_brain.quality import GraphEdgeQualityManager, MemoryQualityManager
+
+from .consistency import BrainConsistencyMixin
+from .digest import BrainDigestMixin
+from .health import BrainHealthMixin
+from .proposals import BrainProposalsMixin
+from .sampling import BrainSamplingMixin
+
+
+class BrainIntelligenceService(
+    BrainProposalsMixin,
+    BrainSamplingMixin,
+    BrainHealthMixin,
+    BrainDigestMixin,
+    BrainConsistencyMixin,
+):
+    def __init__(
+        self,
+        *,
+        knowledge_graph: Any = None,
+        memory_service: Any = None,
+        enable_graph: bool = True,
+        review_queue: Any = None,
+    ) -> None:
+        self._kg = knowledge_graph
+        self._memory = memory_service
+        self._enable_graph = bool(enable_graph and knowledge_graph is not None)
+        self._memory_quality = MemoryQualityManager()
+        self._edge_quality = GraphEdgeQualityManager()
+        self._proactive_brain: Any = None
+        self._review_queue_service = review_queue
+        self._synthesizer: Any = None