ltcai 11.1.0 → 11.4.0

package/latticeai/services/app_context.py

@@ -76,6 +76,14 @@ class AppContext:
     workspace_graph: Optional[Callable[[], Any]] = None
     graph_stats: Optional[Callable[[], dict]] = None
 
+    # ── review center ─────────────────────────────────────────────────────
+    # ``ReviewQueueService``, reached through a provider like
+    # ``workspace_graph`` above: the queue is built in a later runtime phase
+    # than this context, so a value captured here would be ``None`` forever.
+    # Call it per request; ``None`` means no Review Center is wired (tests,
+    # headless helpers) and the callers stage nothing rather than writing.
+    review_queue: Optional[Callable[[], Any]] = None
+
     # ── workspace payload providers / skills ──────────────────────────────
     workspace_models: Optional[Callable[[], dict]] = None
     workspace_settings: Optional[Callable[[], dict]] = None

package/latticeai/services/architecture_readiness.py

@@ -16,7 +16,7 @@ from typing import Any, Dict, List
 
 from latticeai.core.legacy_compatibility import legacy_shim_report
 
-ARCHITECTURE_VERSION_TARGET = "11.1.0"
+ARCHITECTURE_VERSION_TARGET = "11.4.0"
 
 PREFERRED_REFACTORING_ORDER = [
     "agent-runtime",
@@ -53,6 +53,19 @@ def _symbol_exists(dotted: str) -> bool:
         return False
 
 
+def _package_sources(root: Path, relative_package: str) -> List[str]:
+    """Every ``*.py`` in a package, as repo-relative paths.
+
+    Returns the missing marker path when the package is absent, so a gate that
+    scans a package fails the same way it would for a deleted single file.
+    """
+    directory = root / relative_package
+    sources = sorted(directory.glob("*.py")) if directory.is_dir() else []
+    if not sources:
+        return [f"{relative_package}/__init__.py"]
+    return [str(path.relative_to(root)) for path in sources]
+
+
 def _forbidden_patterns(root: Path, relative_path: str, patterns: List[str]) -> List[str]:
     path = root / relative_path
     try:
@@ -71,18 +84,26 @@ def architecture_readiness(root: Path | None = None) -> Dict[str, Any]:
         "latticeai/app_factory.py",
         ["build_runtime_namespace(locals", "dict(locals())"],
     )
-    model_runtime_forbidden = _forbidden_patterns(
-        root,
-        "latticeai/services/model_runtime.py",
-        [
-            "def _sync_globals",
-            "global router",
-            "STATE = ModelRuntimeState",
-            "_STATE_EXPORTS",
-            "def __getattr__(name:",
-            "from fastapi import HTTPException",
-        ],
-    )
+    # v11.3.0: model_runtime.py became a package. The ambient-state patterns
+    # below could reappear in any of its submodules, so every file in the
+    # package is scanned — checking only __init__.py would leave the gate
+    # blind one directory down.
+    model_runtime_forbidden = [
+        finding
+        for relative_path in _package_sources(root, "latticeai/services/model_runtime")
+        for finding in _forbidden_patterns(
+            root,
+            relative_path,
+            [
+                "def _sync_globals",
+                "global router",
+                "STATE = ModelRuntimeState",
+                "_STATE_EXPORTS",
+                "def __getattr__(name:",
+                "from fastapi import HTTPException",
+            ],
+        )
+    ]
     model_runtime_forbidden.extend(
         _forbidden_patterns(
             root,
@@ -97,11 +118,19 @@ def architecture_readiness(root: Path | None = None) -> Dict[str, Any]:
             ["from fastapi import HTTPException", "raise HTTPException"],
         )
     )
-    agent_alias_forbidden = _forbidden_patterns(
-        root,
-        "latticeai/core/agent.py",
-        ["AgentRuntime = SingleAgentRuntime"],
-    )
+    # v11.3.0: the single-agent loop is a package. The compatibility alias
+    # could reappear in any of its submodules, so every file in the package is
+    # scanned — checking only __init__.py would leave the gate blind one
+    # directory down.
+    agent_alias_forbidden = [
+        finding
+        for relative_path in _package_sources(root, "latticeai/core/agent")
+        for finding in _forbidden_patterns(
+            root,
+            relative_path,
+            ["AgentRuntime = SingleAgentRuntime"],
+        )
+    ]
 
     gates = [
         ArchitectureGate(
@@ -180,7 +209,7 @@ def architecture_readiness(root: Path | None = None) -> Dict[str, Any]:
             evidence=[
                 "frontend/src/components/ProductFlow.tsx Wake Brain entry",
                 "frontend/src/features/brain/BrainHome.tsx memory rings",
-                "tests/visual/v3.spec.js first-run and Brain depth coverage",
+                "tests/visual/v3.home.spec.js first-run and Brain depth coverage",
             ],
         ),
         ArchitectureGate(

package/latticeai/services/automation_intelligence.py

@@ -55,6 +55,13 @@ _SIGNATURE_SIMILARITY = 0.6
 _MIN_SUGGESTION_CONFIDENCE = 0.35
 _LOW_CONFIDENCE_THRESHOLD = 0.5
 _KG_GROUNDING_LIMIT = 5
+#: Charged when the graph *was* consulted and found nothing related. v11.2.0
+#: fixes a dead policy: the floor above was unreachable for recurring questions
+#: (the cheapest possible question — asked twice, one phrasing, no recipe —
+#: scored 0.475), so the suppression branch could only ever be exercised by a
+#: test that moved the constant. Absence of grounding is real evidence, and
+#: charging for it is what makes the floor mean something again.
+_UNGROUNDED_PENALTY = 0.15
 
 
 def _question_confidence(
@@ -67,7 +74,13 @@ def _question_confidence(
 
     Evidence factors: how often the question repeats, how many distinct
     phrasings exist, whether it maps onto a known starter-recipe intent, and
-    (when the graph is available) how many Brain nodes relate to it.
+    what the Brain knows about it.
+
+    That last factor is three-valued on purpose. ``None`` means the graph could
+    not be consulted — unknown, so nothing is added or taken away. A positive
+    count is supporting evidence. **Zero** is not the same as unknown: the
+    graph was asked, and it knows nothing about this question, which is a
+    reason to be less sure rather than a reason to be neutral.
     """
     score = 0.3 + 0.5 * min(1.0, (int(count) - 1) / 4)
     score += min(0.15, 0.05 * len(examples or []))
@@ -75,13 +88,16 @@ def _question_confidence(
         score += 0.15
     if kg_related:
         score += min(0.2, 0.05 * int(kg_related))
+    elif kg_related == 0:
+        score -= _UNGROUNDED_PENALTY
     factors = {
         "repeat_count": int(count),
         "distinct_examples": len(examples or []),
         "intent_match": bool(recipe_id),
         "kg_related_nodes": kg_related,
+        "kg_grounded": None if kg_related is None else bool(kg_related),
     }
-    return round(min(1.0, score), 2), factors
+    return round(max(0.0, min(1.0, score)), 2), factors
 
 
 def _source_confidence(indexed: int, watch_enabled: bool) -> tuple:
@@ -357,6 +373,10 @@ class AutomationIntelligenceService:
                 pattern["count"], pattern["examples"], recipe_id, kg_related
             )
             if confidence < _MIN_SUGGESTION_CONFIDENCE:
+                # Asked a couple of times, phrased one way, matching no recipe,
+                # and the Brain knows nothing about it — not enough to propose
+                # automating. Counted, so the surface can say how many were held
+                # back rather than silently showing fewer.
                 suppressed_low_confidence += 1
                 continue
             if recipe_id:

package/latticeai/services/brain_intelligence/__init__.py

@@ -0,0 +1,58 @@
+"""Proactive Brain Intelligence service (v9.3.0).
+
+The Brain graduates from a passive store to an active steward of its own
+knowledge. This service wires the previously dormant quality layer
+(:mod:`lattice_brain.quality` — dedupe, merge, conflict and temporal
+contradiction detection, retention) into router-facing capabilities:
+
+* **health_report** — scored diagnosis of the Brain across freshness,
+  connectivity, embedding coverage, and contradiction pressure, with
+  recommended next actions. Every number is read from the live stores;
+  a missing store degrades the dimension to ``unavailable``, never a guess.
+* **insights** — a proactive digest: recent knowledge growth, most active
+  types, stale knowledge, orphan (disconnected) nodes, and suggested
+  questions grounded in real node titles.
+* **contradictions** — surfaced conflicts across workspace memories
+  (negation/preference conflicts, temporal contradictions) plus explicit
+  CONTRADICTS edges already recorded in the graph.
+* **consolidate** — duplicate-memory and duplicate-edge detection. Dry-run
+  by default (consent-first, like every Brain automation); ``apply=True``
+  prunes only exact duplicate workspace memories through the audited
+  MemoryService path and never touches graph content.
+
+Pure service: no FastAPI, no globals. Collaborators are injected.
+
+Split into cohesive submodules in v11.3.0 (no behaviour change): ``constants``
+(windows + the two shared readings), ``proposals`` (the review-queue path and
+the proactive brief), ``sampling`` (the shared graph slice and memory read),
+``health`` (the scored diagnosis and vector freshness), ``digest`` (insights,
+garden, graph-layer quality reads), ``consistency`` (contradiction and
+consolidation scans), and ``service`` (the composed class). This module
+re-exports every name the single file exposed, so
+``latticeai.services.brain_intelligence.X`` keeps working.
+
+Stubbing note: rebinding one of these *here* changes only this module's name.
+The submodule that calls it holds its own reference, so a test standing in for
+``LOGGER`` or ``_parse_ts`` patches the submodule that uses it.
+"""
+
+from __future__ import annotations
+
+from lattice_brain.quality import GraphEdgeQualityManager as GraphEdgeQualityManager
+from lattice_brain.quality import MemoryQualityManager as MemoryQualityManager
+
+# noqa on the next line, not a redundant alias: the single file exposed this
+# name *renamed* (``brain_intelligence._now``), and reproducing that surface
+# exactly is the point — importing it as ``now_iso`` would add a name the
+# module never had.
+from latticeai.core.timeutil import now_iso as _now  # noqa: F401
+
+from .constants import _GRAPH_SAMPLE_LIMIT as _GRAPH_SAMPLE_LIMIT
+from .constants import _RECENT_DAYS as _RECENT_DAYS
+from .constants import _STALE_DAYS as _STALE_DAYS
+from .constants import LOGGER as LOGGER
+from .constants import _no_graph_reason as _no_graph_reason
+from .constants import _parse_ts as _parse_ts
+from .service import BrainIntelligenceService as BrainIntelligenceService
+
+__all__ = ["BrainIntelligenceService"]

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"
+    )