ltcai 9.6.0 → 9.8.0

package/latticeai/services/automation_intelligence.py

@@ -22,6 +22,14 @@ automation suggestions:
 
 Every suggestion id is deterministic, so install calls are idempotent and the
 UI can safely re-request suggestions without duplicates.
+
+v9.8.0 quality layer (additive): every suggestion carries a deterministic
+``confidence`` score plus its ``confidence_factors`` evidence (repeat count,
+distinct phrasings, intent match, related Brain nodes / indexed files);
+suggestions below a minimum confidence are suppressed, duplicate suggestions
+targeting an already-suggested or already-installed starter recipe are
+deduplicated, and the response reports the suppression counters under
+``quality``.
 """
 
 from __future__ import annotations
@@ -40,6 +48,50 @@ _MIN_PATTERN_COUNT = 2
 _MAX_HISTORY = 4000
 _SIGNATURE_SIMILARITY = 0.6
 
+# Suggestion quality gates (v9.8.0, additive). Suggestions below the minimum
+# confidence are suppressed (insufficient evidence); suggestions between the
+# minimum and the low-confidence threshold are shown but flagged so the UI
+# can render them less prominently.
+_MIN_SUGGESTION_CONFIDENCE = 0.35
+_LOW_CONFIDENCE_THRESHOLD = 0.5
+_KG_GROUNDING_LIMIT = 5
+
+
+def _question_confidence(
+    count: int,
+    examples: List[str],
+    recipe_id: Optional[str],
+    kg_related: Optional[int],
+) -> tuple:
+    """Deterministic confidence for a recurring-question suggestion.
+
+    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.
+    """
+    score = 0.3 + 0.5 * min(1.0, (int(count) - 1) / 4)
+    score += min(0.15, 0.05 * len(examples or []))
+    if recipe_id:
+        score += 0.15
+    if kg_related:
+        score += min(0.2, 0.05 * int(kg_related))
+    factors = {
+        "repeat_count": int(count),
+        "distinct_examples": len(examples or []),
+        "intent_match": bool(recipe_id),
+        "kg_related_nodes": kg_related,
+    }
+    return round(min(1.0, score), 2), factors
+
+
+def _source_confidence(indexed: int, watch_enabled: bool) -> tuple:
+    """Deterministic confidence for a knowledge-source digest suggestion."""
+    score = 0.25 + 0.6 * min(1.0, int(indexed) / 25)
+    if watch_enabled:
+        score += 0.1
+    factors = {"indexed_files": int(indexed), "watch_enabled": bool(watch_enabled)}
+    return round(min(1.0, score), 2), factors
+
 _QUESTION_HINT_RE = re.compile(
     r"(\?|어때|뭐야|뭐가|뭘까|알려줘|보여줘|정리해|요약해|정리 좀|요약 좀|해줘"
     r"|what|how|why|when|where|status|summar|remind|list|show me|tell me)",
@@ -223,38 +275,101 @@ class AutomationIntelligenceService:
             LOGGER.exception("automation intelligence source read failed")
             return []
 
+    def _kg_related_count(
+        self, text: str, *, workspace_id: Optional[str]
+    ) -> Optional[int]:
+        """Count Brain nodes related to a recurring question (grounding evidence).
+
+        Returns ``None`` when the graph is unavailable so confidence scoring can
+        distinguish "grounding impossible" from "grounded with zero hits".
+        Scoping mirrors the conversation-history read: an explicit workspace is
+        strict, no workspace falls back to the unscoped/legacy view.
+        """
+        if not self._enable_graph or not hasattr(self._kg, "search"):
+            return None
+        try:
+            report = self._kg.search(
+                str(text or "")[:200],
+                limit=_KG_GROUNDING_LIMIT,
+                allowed_workspaces={workspace_id} if workspace_id is not None else None,
+                include_legacy_global=workspace_id is None,
+            )
+        except Exception:
+            LOGGER.exception("automation intelligence KG grounding failed")
+            return None
+        if not isinstance(report, dict):
+            return None
+        return len(report.get("matches") or [])
+
     # ── suggestions ──────────────────────────────────────────────────────
 
-    def _installed_suggestion_ids(self, *, workspace_id: Optional[str]) -> Dict[str, Dict[str, Any]]:
-        installed: Dict[str, Dict[str, Any]] = {}
+    def _installed_workflows(
+        self, *, workspace_id: Optional[str]
+    ) -> tuple:
+        """Map installed automation workflows by suggestion id and recipe id.
+
+        The recipe map lets a recurring-question suggestion that targets an
+        already-installed starter recipe surface as *installed* instead of
+        re-suggesting the same automation — the install API is idempotent on
+        exactly this provenance, so the read side must agree.
+        """
+        by_suggestion: Dict[str, Dict[str, Any]] = {}
+        by_recipe: Dict[str, Dict[str, Any]] = {}
         if self._store is None:
-            return installed
+            return by_suggestion, by_recipe
         try:
             workflows = self._store.list_workflows(workspace_id=workspace_id).get("workflows") or []
         except Exception:
             LOGGER.exception("automation intelligence workflow read failed")
-            return installed
+            return by_suggestion, by_recipe
         for workflow in workflows:
             metadata = (workflow or {}).get("metadata") or {}
-            suggestion_id = metadata.get("suggestion_id")
-            if metadata.get("created_from") == "automation_suggestion" and suggestion_id:
-                installed[str(suggestion_id)] = workflow
-        return installed
+            created_from = metadata.get("created_from")
+            if created_from == "automation_suggestion" and metadata.get("suggestion_id"):
+                by_suggestion[str(metadata["suggestion_id"])] = workflow
+            elif created_from == "brain_automation_recipe" and metadata.get("recipe_id"):
+                by_recipe[str(metadata["recipe_id"])] = workflow
+        return by_suggestion, by_recipe
 
     def suggestions(
         self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None
     ) -> Dict[str, Any]:
         pattern_report = self.question_patterns(user_email=user_email, workspace_id=workspace_id)
-        installed = self._installed_suggestion_ids(workspace_id=workspace_id)
+        by_suggestion, by_recipe = self._installed_workflows(workspace_id=workspace_id)
 
         items: List[Dict[str, Any]] = []
+        suppressed_low_confidence = 0
+        suppressed_duplicates = 0
+        seen_recipe_ids: set = set()
+
+        # Patterns arrive sorted by (count, last_asked) desc, so the first
+        # suggestion per recipe is the strongest — later ones targeting the
+        # same recipe would install the identical workflow and are suppressed.
         for pattern in pattern_report["patterns"]:
+            recipe_id = pattern["recipe_id"]
+            if recipe_id and recipe_id in seen_recipe_ids:
+                suppressed_duplicates += 1
+                continue
+            kg_related = self._kg_related_count(
+                pattern["representative"], workspace_id=workspace_id
+            )
+            confidence, factors = _question_confidence(
+                pattern["count"], pattern["examples"], recipe_id, kg_related
+            )
+            if confidence < _MIN_SUGGESTION_CONFIDENCE:
+                suppressed_low_confidence += 1
+                continue
+            if recipe_id:
+                seen_recipe_ids.add(recipe_id)
             suggestion_id = _stable_id("sug-q", pattern["id"])
+            workflow = by_suggestion.get(suggestion_id) or (
+                by_recipe.get(str(recipe_id)) if recipe_id else None
+            )
             items.append({
                 "id": suggestion_id,
                 "kind": "recurring_question",
                 "intent": pattern["intent"],
-                "recipe_id": pattern["recipe_id"],
+                "recipe_id": recipe_id,
                 "title": pattern["representative"],
                 "reason": {
                     "type": "repeated_question",
@@ -263,8 +378,11 @@ class AutomationIntelligenceService:
                     "examples": pattern["examples"],
                 },
                 "cadence": "daily",
-                "installed": suggestion_id in installed,
-                "workflow_id": (installed.get(suggestion_id) or {}).get("id"),
+                "confidence": confidence,
+                "confidence_factors": factors,
+                "low_confidence": confidence < _LOW_CONFIDENCE_THRESHOLD,
+                "installed": workflow is not None,
+                "workflow_id": (workflow or {}).get("id"),
             })
 
         for source in self._knowledge_sources():
@@ -272,6 +390,14 @@ class AutomationIntelligenceService:
             indexed = sum(int(v or 0) for v in file_status.values())
             if indexed <= 0:
                 continue
+            confidence, factors = _source_confidence(
+                indexed, bool(source.get("watch_enabled"))
+            )
+            if confidence < _MIN_SUGGESTION_CONFIDENCE:
+                # A barely-indexed folder is not enough evidence for a digest
+                # automation yet — do not suggest.
+                suppressed_low_confidence += 1
+                continue
             suggestion_id = _stable_id("sug-src", str(source.get("id") or source.get("root_path") or ""))
             items.append({
                 "id": suggestion_id,
@@ -286,13 +412,22 @@ class AutomationIntelligenceService:
                     "watch_enabled": bool(source.get("watch_enabled")),
                 },
                 "cadence": "when new knowledge arrives",
-                "installed": suggestion_id in installed,
-                "workflow_id": (installed.get(suggestion_id) or {}).get("id"),
+                "confidence": confidence,
+                "confidence_factors": factors,
+                "low_confidence": confidence < _LOW_CONFIDENCE_THRESHOLD,
+                "installed": suggestion_id in by_suggestion,
+                "workflow_id": (by_suggestion.get(suggestion_id) or {}).get("id"),
             })
 
         return {
             "suggestions": items,
             "questions_scanned": pattern_report["questions_scanned"],
+            "quality": {
+                "min_confidence": _MIN_SUGGESTION_CONFIDENCE,
+                "low_confidence_threshold": _LOW_CONFIDENCE_THRESHOLD,
+                "suppressed_low_confidence": suppressed_low_confidence,
+                "suppressed_duplicates": suppressed_duplicates,
+            },
             "consent": {
                 "default_state": "draft_disabled",
                 "local_only": True,
@@ -403,6 +538,7 @@ class AutomationIntelligenceService:
                 "suggestion_kind": kind,
                 "suggestion_title": title,
                 "suggestion_reason": suggestion.get("reason"),
+                "suggestion_confidence": suggestion.get("confidence"),
                 "automation_state": "enabled" if enabled else "draft_disabled",
                 "local_only": True,
                 "external_actions": False,
@@ -442,6 +578,7 @@ class AutomationIntelligenceService:
             "suggestions": suggestion_report["suggestions"],
             "questions_scanned": suggestion_report["questions_scanned"],
             "installed": installed,
+            "quality": suggestion_report["quality"],
             "consent": suggestion_report["consent"],
             "generated_at": _now(),
         }

package/latticeai/services/brain_intelligence.py

@@ -65,6 +65,23 @@ class BrainIntelligenceService:
         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
+
+    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 ─────────────────────────────────────────────
 
@@ -240,6 +257,78 @@ class BrainIntelligenceService:
             "generated_at": _now(),
         }
 
+    # ── vector freshness (v9.8.0) ────────────────────────────────────────
+
+    def vector_freshness(
+        self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Fixed-contract vector index freshness for ``/api/brain/vector-freshness``.
+
+        Always returns ``{"status": "ready"|"pending"|"unavailable",
+        "pending_items": int, "total_items": int, "detail": str}`` and never
+        raises. The vector index is store-global (not workspace-partitioned);
+        scope arguments are accepted for router symmetry but do not narrow
+        the report.
+        """
+
+        def _unavailable(detail: str) -> Dict[str, Any]:
+            return {
+                "status": "unavailable",
+                "pending_items": 0,
+                "total_items": 0,
+                "detail": detail,
+            }
+
+        if not self._enable_graph or self._kg is None:
+            return _unavailable("knowledge graph is disabled; no vector index is configured")
+
+        freshness_fn = getattr(self._kg, "vector_freshness", None)
+        if callable(freshness_fn):
+            try:
+                raw = freshness_fn() or {}
+            except Exception as exc:
+                LOGGER.exception("vector freshness read failed")
+                return _unavailable(f"vector freshness read failed: {exc}")
+            status = str(raw.get("status") or "unavailable")
+            if status == "needs_reindex":
+                status = "pending"
+            if status not in {"ready", "pending", "unavailable"}:
+                status = "unavailable"
+            return {
+                "status": status,
+                "pending_items": int(raw.get("pending_items") or 0),
+                "total_items": int(raw.get("total_items") or 0),
+                "detail": str(raw.get("detail") or ""),
+            }
+
+        # Older/lighter stores: summarize index_status directly.
+        status_fn = getattr(self._kg, "index_status", None)
+        if callable(status_fn):
+            try:
+                raw = status_fn() or {}
+            except Exception as exc:
+                LOGGER.exception("vector index status read failed")
+                return _unavailable(f"vector index status unavailable: {exc}")
+            pending = int(raw.get("pending_items") or 0)
+            total = int(raw.get("source_items") or 0)
+            if pending > 0:
+                return {
+                    "status": "pending",
+                    "pending_items": pending,
+                    "total_items": total,
+                    "detail": (
+                        f"{pending} of {total} items are missing or stale in the vector index"
+                    ),
+                }
+            return {
+                "status": "ready",
+                "pending_items": 0,
+                "total_items": total,
+                "detail": "vector index is up to date",
+            }
+
+        return _unavailable("this knowledge store does not expose a vector index")
+
     # ── insights digest ──────────────────────────────────────────────────
 
     def insights(
@@ -302,6 +391,56 @@ class BrainIntelligenceService:
             "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
+        result["generated_at"] = _now()
+        return result
+
     # ── contradictions ───────────────────────────────────────────────────
 
     def contradictions(
@@ -365,7 +504,21 @@ class BrainIntelligenceService:
                     "signal": "contradicts_edge",
                 })
 
-        items = conflicts + temporal_items + edge_items
+        # 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),
@@ -373,6 +526,7 @@ class BrainIntelligenceService:
                 "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(),
@@ -422,6 +576,19 @@ class BrainIntelligenceService:
             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),
@@ -432,6 +599,7 @@ class BrainIntelligenceService:
             # 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/change_proposals.py

@@ -71,6 +71,7 @@ class ChangeProposalService:
         policy: Optional[Dict[str, Any]] = None,
         user_email: Optional[str] = None,
         workspace_id: Optional[str] = None,
+        conversation_id: Optional[str] = None,
     ) -> Optional[Dict[str, Any]]:
         """Governor port for the agent loop.
 
@@ -102,6 +103,15 @@ class ChangeProposalService:
                 reason=verdict["reason"],
                 user_email=user_email,
                 workspace_id=workspace_id,
+                context={
+                    # Full provenance for the Review Center: which tool asked,
+                    # how the governor classified it, and the policy risk.
+                    "tool": name,
+                    "change_class": verdict.get("change_class"),
+                    "risk": (policy or {}).get("risk"),
+                    "conversation_id": conversation_id,
+                    "source_detail": "agent change governor",
+                },
             )
         except Exception:
             LOGGER.exception("change proposal staging failed")
@@ -152,10 +162,15 @@ class ChangeProposalService:
         reason: str = "",
         user_email: Optional[str] = None,
         workspace_id: Optional[str] = None,
+        context: Optional[Dict[str, Any]] = None,
     ) -> Dict[str, Any]:
         before = self._read_before(path)
         diff = _unified_diff(before, new_content, path)
         tier = "small" if len(diff) <= _SMALL_TIER_DIFF_LINES else "large"
+        provenance: Dict[str, Any] = {"proposed_by": proposed_by, "reason": reason}
+        for key, value in (context or {}).items():
+            if value is not None and key not in provenance:
+                provenance[key] = value
         item = self._review_queue.create(
             title=f"파일 수정 제안: {path}",
             summary=reason or "기존 파일을 변경하는 작업이라 검토 후 적용됩니다.",
@@ -169,7 +184,7 @@ class ChangeProposalService:
                 "before_bytes": len(before.encode("utf-8")),
                 "after_bytes": len(new_content.encode("utf-8")),
             },
-            provenance={"proposed_by": proposed_by, "reason": reason},
+            provenance=provenance,
             user_email=user_email,
             workspace_id=workspace_id,
         )
@@ -232,11 +247,36 @@ class ChangeProposalService:
             },
         }
 
+    def counts(
+        self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Pending proposal count for the Review Center badge."""
+        listed = self._review_queue.list(
+            workspace_id=workspace_id, user_email=user_email,
+            status="pending", source="change_proposal",
+        )
+        return {"pending": len(listed.get("items") or [])}
+
+    def get_proposal(
+        self, item_id: str, *, workspace_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Full proposal detail (diff + staged content) for the preview UI.
+
+        Raises ``KeyError`` when the id exists but is not a change proposal,
+        so the API surface cannot leak arbitrary review items.
+        """
+        item = self._review_queue.get(item_id, workspace_id=workspace_id)
+        if item.get("source") != "change_proposal":
+            raise KeyError(f"not a change proposal: {item_id}")
+        return item
+
     def approve_and_apply(
         self, item_id: str, *, user_email: Optional[str] = None,
         workspace_id: Optional[str] = None,
     ) -> Dict[str, Any]:
         item = self._review_queue.get(item_id, workspace_id=workspace_id)
+        if item.get("source") != "change_proposal":
+            raise KeyError(f"not a change proposal: {item_id}")
         payload = item.get("payload") or {}
         kind = item.get("kind")
         path = str(payload.get("path") or "")
@@ -258,13 +298,25 @@ class ChangeProposalService:
 
     def reject(
         self, item_id: str, *, user_email: Optional[str] = None,
-        workspace_id: Optional[str] = None,
+        workspace_id: Optional[str] = None, reason: str = "",
     ) -> Dict[str, Any]:
-        dismissed = self._review_queue.dismiss(item_id, workspace_id=workspace_id)
+        self.get_proposal(item_id, workspace_id=workspace_id)  # source guard
+        reason = str(reason or "").strip()[:500]
+        if reason:
+            try:
+                dismissed = self._review_queue.dismiss(
+                    item_id, workspace_id=workspace_id, reason=reason
+                )
+            except TypeError:
+                # Older/fake queues without reason support still dismiss.
+                dismissed = self._review_queue.dismiss(item_id, workspace_id=workspace_id)
+        else:
+            dismissed = self._review_queue.dismiss(item_id, workspace_id=workspace_id)
         self._audit(
             "change_proposal_rejected", user_email=user_email, proposal_id=item_id,
+            reason=reason or None,
         )
-        return {"item": dismissed, "applied": False}
+        return {"item": dismissed, "applied": False, "reason": reason}
 
 
 __all__ = ["ChangeProposalService"]

package/latticeai/services/product_readiness.py

@@ -18,7 +18,7 @@ from typing import Any, Dict, List
 
 from latticeai.services.architecture_readiness import architecture_readiness
 
-PRODUCT_VERSION_TARGET = "9.6.0"
+PRODUCT_VERSION_TARGET = "9.8.0"
 
 
 @dataclass(frozen=True)

package/latticeai/services/review_queue.py

@@ -141,8 +141,49 @@ class ReviewQueueService:
         updated = self._store.update_review_item(item_id, workspace_id=workspace_id, **patch)
         return self._view(updated)
 
-    def dismiss(self, item_id: str, *, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        return self._transition(item_id, "dismiss", "dismissed", workspace_id=workspace_id)
+    def dismiss(
+        self, item_id: str, *, workspace_id: Optional[str] = None,
+        reason: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Dismiss an item; an optional ``reason`` is kept in provenance.
+
+        The reason matters most for ``change_proposal`` items — the review
+        timeline doubles as the change audit log, so "why was this rejected"
+        should survive next to the staged diff.
+        """
+        if not reason:
+            return self._transition(item_id, "dismiss", "dismissed", workspace_id=workspace_id)
+        item = self._store.get_review_item(item_id, workspace_id=workspace_id)
+        self._guard("dismiss", item)
+        provenance = dict(item.get("provenance") or {})
+        provenance["dismiss_reason"] = str(reason)[:500]
+        patch: Dict[str, Any] = {"status": "dismissed", "provenance": provenance}
+        if item.get("snoozed_until") is not None:
+            patch["snoozed_until"] = None
+        updated = self._store.update_review_item(item_id, workspace_id=workspace_id, **patch)
+        return self._view(updated)
+
+    def counts(
+        self, *, workspace_id: Optional[str] = None, user_email: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Badge-friendly effective-status counts (pending includes expired snoozes)."""
+        items = [
+            self._view(it)
+            for it in self._store.list_review_items(
+                workspace_id=workspace_id, user_email=user_email,
+            )
+        ]
+        pending = [it for it in items if it["effective_status"] == "pending"]
+        snoozed = [it for it in items if it["effective_status"] == "snoozed"]
+        by_source: Dict[str, int] = {}
+        for it in pending:
+            source = str(it.get("source") or "workflow_run")
+            by_source[source] = by_source.get(source, 0) + 1
+        return {
+            "pending": len(pending),
+            "snoozed": len(snoozed),
+            "pending_by_source": by_source,
+        }
 
     def snooze(
         self, item_id: str, *, until: str, workspace_id: Optional[str] = None,

package/llm_router.py

@@ -5,7 +5,16 @@ monkeypatching keep working through the old import path.
 """
 
 import sys
+import warnings
 
-import latticeai.models.router as _impl
+warnings.warn(
+    "Importing 'llm_router' from the repository root is deprecated; "
+    "use 'import latticeai.models.router' instead. "
+    "The root shim will be removed in a future major release.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+import latticeai.models.router as _impl  # noqa: E402
 
 sys.modules[__name__] = _impl

package/local_knowledge_api.py

@@ -1,7 +1,16 @@
 """Compatibility shim for :mod:`latticeai.services.local_knowledge`."""
 
 import sys
+import warnings
 
-from latticeai.services import local_knowledge as _impl
+warnings.warn(
+    "Importing 'local_knowledge_api' from the repository root is deprecated; "
+    "use 'from latticeai.services import local_knowledge' instead. "
+    "The root shim will be removed in a future major release.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from latticeai.services import local_knowledge as _impl  # noqa: E402
 
 sys.modules[__name__] = _impl