ltcai 8.7.0 → 8.9.0

package/latticeai/app_factory.py

@@ -15,6 +15,7 @@ lazily via module ``__getattr__`` for backwards compatibility.
 from __future__ import annotations
 
 import threading
+from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Dict, List, Optional
 
 from latticeai.runtime.app_context_runtime import build_app_context
@@ -94,7 +95,7 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
     from pydantic import BaseModel
 
     from latticeai.models.router import LLMRouter, normalize_branding
-    from lattice_brain._kg_common import set_llm_router
+    from lattice_brain.graph.runtime import set_llm_router
     from lattice_brain.graph.schema import set_embed_dim
     from latticeai.core.security import (
         hash_password,
@@ -234,6 +235,8 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
     ENABLE_GRAPH    = _config_runtime["ENABLE_GRAPH"]
     AUTOLOAD_MODELS = _config_runtime["AUTOLOAD_MODELS"]
     MODEL_IDLE_UNLOAD_SECONDS = _config_runtime["MODEL_IDLE_UNLOAD_SECONDS"]
+    ALLOW_MODEL_DOWNLOADS = _config_runtime["ALLOW_MODEL_DOWNLOADS"]
+    MODEL_DOWNLOAD_TIMEOUT = _config_runtime["MODEL_DOWNLOAD_TIMEOUT"]
     ALLOW_LOCAL_MODELS = _config_runtime["ALLOW_LOCAL_MODELS"]
     REQUIRE_AUTH = _config_runtime["REQUIRE_AUTH"]
     ALLOW_PLAINTEXT_API_KEYS = _config_runtime["ALLOW_PLAINTEXT_API_KEYS"]
@@ -636,9 +639,33 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
     get_audit_log = _audit_rt["get_audit_log"]
     append_audit_event = _audit_rt["append_audit_event"]
 
-    def get_history():
+    def _history_allowed_workspaces_for(user_email: Optional[str]):
+        if not REQUIRE_AUTH or not user_email:
+            return None
+        try:
+            return set(WORKSPACE_SERVICE.readable_workspaces(user_email))
+        except Exception as exc:
+            logging.warning("history workspace scope resolution failed for %s: %s", user_email, exc)
+            return set()
+
+    def _history_include_legacy_global(user_email: Optional[str]) -> bool:
+        return not REQUIRE_AUTH or not user_email
+
+    def get_history(
+        user_email: Optional[str] = None,
+        allowed_workspaces=None,
+        include_legacy_global: Optional[bool] = None,
+    ):
         try:
-            return CONVERSATIONS.history()
+            if allowed_workspaces is None and user_email:
+                allowed_workspaces = _history_allowed_workspaces_for(user_email)
+            if include_legacy_global is None:
+                include_legacy_global = _history_include_legacy_global(user_email)
+            return CONVERSATIONS.history(
+                user_email=user_email,
+                allowed_workspaces=allowed_workspaces,
+                include_legacy_global=include_legacy_global,
+            )
         except Exception as e:
             logging.warning("get_history failed: %s", e)
             return []
@@ -683,17 +710,59 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
 
         return sorted((conversations[key] for key in order), key=lambda item: item.get("updated_at") or "", reverse=True)
 
-    def get_conversation_messages(conversation_id: str) -> List[Dict]:
-        history = get_history()
+    def get_conversation_messages(
+        conversation_id: str,
+        *,
+        user_email: Optional[str] = None,
+        allowed_workspaces=None,
+        include_legacy_global: Optional[bool] = None,
+    ) -> List[Dict]:
+        history = get_history(
+            user_email=user_email,
+            allowed_workspaces=allowed_workspaces,
+            include_legacy_global=include_legacy_global,
+        )
         if conversation_id == "legacy-previous-history":
             return [item for item in history if not item.get("conversation_id")]
         return [item for item in history if item.get("conversation_id") == conversation_id]
 
-    def clear_history(keep_last: int = 0) -> Dict:
-        return CONVERSATIONS.clear_all(keep_last=keep_last)
+    def clear_history(
+        keep_last: int = 0,
+        *,
+        user_email: Optional[str] = None,
+        allowed_workspaces=None,
+        include_legacy_global: Optional[bool] = None,
+    ) -> Dict:
+        if allowed_workspaces is None and user_email:
+            allowed_workspaces = _history_allowed_workspaces_for(user_email)
+        if include_legacy_global is None:
+            include_legacy_global = _history_include_legacy_global(user_email)
+        return CONVERSATIONS.clear_all(
+            keep_last=keep_last,
+            user_email=user_email,
+            allowed_workspaces=allowed_workspaces,
+            include_legacy_global=include_legacy_global,
+        )
 
-    def clear_conversation(conversation_id: str, started_at: Optional[str] = None) -> Dict:
-        return CONVERSATIONS.clear_conversation(conversation_id, started_at=started_at)
+    def clear_conversation(
+        conversation_id: str,
+        started_at: Optional[str] = None,
+        *,
+        user_email: Optional[str] = None,
+        allowed_workspaces=None,
+        include_legacy_global: Optional[bool] = None,
+    ) -> Dict:
+        if allowed_workspaces is None and user_email:
+            allowed_workspaces = _history_allowed_workspaces_for(user_email)
+        if include_legacy_global is None:
+            include_legacy_global = _history_include_legacy_global(user_email)
+        return CONVERSATIONS.clear_conversation(
+            conversation_id,
+            started_at=started_at,
+            user_email=user_email,
+            allowed_workspaces=allowed_workspaces,
+            include_legacy_global=include_legacy_global,
+        )
 
     _access_runtime = build_access_runtime(
         config=CONFIG,
@@ -942,6 +1011,8 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         ENABLE_GRAPH=ENABLE_GRAPH,
         AUTOLOAD_MODELS=AUTOLOAD_MODELS,
         MODEL_IDLE_UNLOAD_SECONDS=MODEL_IDLE_UNLOAD_SECONDS,
+        ALLOW_MODEL_DOWNLOADS=ALLOW_MODEL_DOWNLOADS,
+        MODEL_DOWNLOAD_TIMEOUT=MODEL_DOWNLOAD_TIMEOUT,
         ALLOW_LOCAL_MODELS=ALLOW_LOCAL_MODELS,
         REQUIRE_AUTH=REQUIRE_AUTH,
         INVITE_GATE_ENABLED=INVITE_GATE_ENABLED,
@@ -1136,6 +1207,7 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         load_users=load_users,
         get_user_role=get_user_role,
         enforce_rate_limit=enforce_rate_limit,
+        allowed_workspaces_for=_history_allowed_workspaces_for,
         append_audit_event=append_audit_event,
         get_audit_log=get_audit_log,
         get_history=get_history,
@@ -1383,6 +1455,16 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
     return dict(locals())
 
 
+@dataclass(frozen=True)
+class LegacyRuntimeNamespace:
+    """Compatibility adapter for the historical module-level runtime surface."""
+
+    namespace: Dict[str, Any]
+
+    def bind(self, runtime: "AppRuntime") -> None:
+        runtime.__dict__.update(self.namespace)
+
+
 class AppRuntime:
     """The constructed application namespace.
 
@@ -1391,7 +1473,8 @@ class AppRuntime:
     """
 
     def __init__(self, namespace: Dict[str, Any]) -> None:
-        self.__dict__.update(namespace)
+        self._legacy_namespace = LegacyRuntimeNamespace(namespace)
+        self._legacy_namespace.bind(self)
 
 
 _runtime_lock = threading.RLock()

package/latticeai/core/agent.py

@@ -52,7 +52,7 @@ class AgentRunContext:
     """Mutable state carrier passed through all agent phases."""
     __slots__ = ("state", "plan", "transcript", "retry_count",
                  "state_history", "corrections", "final_message", "rollback_log",
-                 "executing_model", "reviewing_model")
+                 "executing_model", "reviewing_model", "approved_by_human")
 
     def __init__(self) -> None:
         self.state:           AgentState   = AgentState.IDLE
@@ -65,6 +65,7 @@ class AgentRunContext:
         self.rollback_log:    list         = []
         self.executing_model: Optional[str] = None
         self.reviewing_model: Optional[str] = None
+        self.approved_by_human: bool       = False
 
 
 def extract_action(raw: str) -> Dict:
@@ -207,7 +208,7 @@ class SingleAgentRuntime:
         ctx.state = AgentState.WAITING_APPROVAL
 
     # ── APPROVAL ─────────────────────────────────────────────────────
-    def approve(self, ctx: AgentRunContext, current_user: str) -> None:
+    def approve(self, ctx: AgentRunContext, current_user: str, *, approved_by_human: bool = False) -> None:
         """APPROVAL: Check governance, log decision, auto-approve (future: UI prompt)."""
         d = self.deps
         auto_approve_tools = {name for name, p in d.tool_governance.items() if p["auto_approve"]}
@@ -219,12 +220,22 @@ class SingleAgentRuntime:
             "state": AgentState.WAITING_APPROVAL.value,
             "requires_approval": requires,
             "non_auto_approve_steps": non_auto,
-            "decision": "auto_approved",
+            "decision": "human_approved" if requires and approved_by_human else ("blocked_pending_approval" if requires else "auto_approved"),
         })
         d.audit(
             "agent_approval", user_email=current_user,
-            requires_approval=requires, non_auto_steps=non_auto, decision="auto_approved",
+            requires_approval=requires,
+            non_auto_steps=non_auto,
+            decision="human_approved" if requires and approved_by_human else ("blocked_pending_approval" if requires else "auto_approved"),
         )
+        if requires and not approved_by_human:
+            ctx.final_message = (
+                "이 작업에는 명시 승인이 필요한 도구가 포함되어 있어 자동 실행을 중단했습니다. "
+                "human_in_loop 승인 흐름으로 다시 실행해 주세요."
+            )
+            ctx.state = AgentState.FAILED
+            return
+        ctx.approved_by_human = bool(approved_by_human)
         ctx.state = AgentState.EXECUTING
 
     # ── EXECUTE ──────────────────────────────────────────────────────
@@ -317,7 +328,7 @@ class SingleAgentRuntime:
                 )
                 continue
 
-            if not policy["auto_approve"]:
+            if not policy["auto_approve"] and not ctx.approved_by_human:
                 d.audit(
                     "agent_exec", user_email=current_user, source=getattr(req, "source", None) or "agent",
                     state=AgentState.EXECUTING.value, action=name, risk=risk,
@@ -326,6 +337,13 @@ class SingleAgentRuntime:
                     rollback=policy["rollback"],
                     args={k: v for k, v in args.items() if k != "content"},
                 )
+                ctx.transcript.append({
+                    "state": AgentState.EXECUTING.value, "action": name,
+                    "thoughts": thoughts, "args": args, "risk": risk,
+                    "governance": dict(policy),
+                    "error": f"BLOCKED: action '{name}' requires explicit approval.",
+                })
+                continue
 
             try:
                 d.check_role(name, current_user)
@@ -422,8 +440,8 @@ class SingleAgentRuntime:
             if gov.get("rollback") != "git":
                 continue
             result = step.get("result", {})
-            if not (isinstance(result, dict) and result.get("success")):
-                continue
+            if not isinstance(result, dict):
+                result = {}
             path = result.get("path") or (step.get("args") or {}).get("path", "")
             if not path:
                 continue

package/latticeai/core/legacy_compatibility.py

@@ -14,7 +14,7 @@ from pathlib import Path
 from typing import Any, Dict, List
 
 
-LEGACY_COMPATIBILITY_VERSION = "8.5.0"
+LEGACY_COMPATIBILITY_VERSION = "8.9.0"
 
 
 @dataclass(frozen=True)
@@ -43,7 +43,7 @@ LEGACY_SHIMS: List[LegacyShim] = [
     LegacyShim(
         path="knowledge_graph.py",
         owner="lattice_brain.graph",
-        replacement="from lattice_brain.store import KnowledgeGraphStore",
+        replacement="from lattice_brain.graph.store import KnowledgeGraphStore",
         reason="Historical scripts imported the graph store from the repo root.",
         removal_phase="major-release-after-8.x",
     ),
@@ -57,7 +57,7 @@ LEGACY_SHIMS: List[LegacyShim] = [
     LegacyShim(
         path="kg_schema.py",
         owner="lattice_brain.graph.schema",
-        replacement="from lattice_brain.schema import ...",
+        replacement="from lattice_brain.graph.schema import ...",
         reason="Historical graph schema tests and tools referenced root schema symbols.",
         removal_phase="major-release-after-8.x",
     ),
@@ -96,53 +96,59 @@ LEGACY_SHIMS: List[LegacyShim] = [
         reason="Local folder ingestion integrations used the root local knowledge API.",
         removal_phase="requires-api-route-migration",
     ),
+]
+
+# Shim layers that have completed their compatibility window and were
+# physically deleted. Kept in the report so consumers (docs, tests, release
+# notes) can tell "removed on purpose" apart from "missing by accident".
+# Removing the internal-only layers is the first step of extracting
+# ``lattice_brain`` as a standalone Brain Core package: the package now has
+# exactly one import surface (``lattice_brain.*`` physical paths).
+REMOVED_SHIMS: List[LegacyShim] = [
     LegacyShim(
         path="lattice_brain/store.py",
         owner="lattice_brain.graph.store",
         replacement="from lattice_brain.graph.store import KnowledgeGraphStore",
-        reason="Pre-graph-package imports used the flat Brain store module.",
-        removal_phase="major-release-after-8.x",
+        reason="Pre-graph-package flat modules were internal-only; removed in 8.8.0.",
+        removal_phase="removed-8.8.0",
         layer="brain-flat",
+        status="removed",
     ),
     LegacyShim(
         path="lattice_brain/ingest.py",
         owner="lattice_brain.graph.ingest",
         replacement="from lattice_brain.graph.ingest import KnowledgeGraphIngestMixin",
-        reason="Pre-graph-package imports used the flat Brain ingest module.",
-        removal_phase="major-release-after-8.x",
+        reason="Pre-graph-package flat modules were internal-only; removed in 8.8.0.",
+        removal_phase="removed-8.8.0",
         layer="brain-flat",
+        status="removed",
     ),
     LegacyShim(
         path="lattice_brain/retrieval.py",
         owner="lattice_brain.graph.retrieval",
         replacement="from lattice_brain.graph.retrieval import KnowledgeGraphRetrievalMixin",
-        reason="Pre-graph-package imports used the flat Brain retrieval module.",
-        removal_phase="major-release-after-8.x",
+        reason="Pre-graph-package flat modules were internal-only; removed in 8.8.0.",
+        removal_phase="removed-8.8.0",
         layer="brain-flat",
+        status="removed",
     ),
     LegacyShim(
-        path="latticeai/brain/store.py",
-        owner="lattice_brain.graph.store",
-        replacement="from lattice_brain.graph.store import KnowledgeGraphStore",
-        reason="The deprecated latticeai.brain namespace remains for package users.",
-        removal_phase="major-release-after-8.x",
-        layer="deprecated-namespace",
-    ),
-    LegacyShim(
-        path="latticeai/brain/ingest.py",
-        owner="lattice_brain.graph.ingest",
-        replacement="from lattice_brain.graph.ingest import KnowledgeGraphIngestMixin",
-        reason="The deprecated latticeai.brain namespace remains for package users.",
-        removal_phase="major-release-after-8.x",
+        path="latticeai/brain/",
+        owner="lattice_brain",
+        replacement="import lattice_brain",
+        reason="The deprecated latticeai.brain namespace completed its window; removed in 8.8.0.",
+        removal_phase="removed-8.8.0",
         layer="deprecated-namespace",
+        status="removed",
     ),
     LegacyShim(
         path="latticeai/services/agent_runtime.py",
         owner="lattice_brain.runtime.agent_runtime",
         replacement="from lattice_brain.runtime.agent_runtime import AgentRuntime",
-        reason="Service-layer imports existed before AgentRuntime moved into Brain runtime.",
-        removal_phase="major-release-after-8.x",
+        reason="The service-layer alias completed its window; removed in 8.8.0.",
+        removal_phase="removed-8.8.0",
         layer="service-alias",
+        status="removed",
     ),
 ]
 
@@ -152,23 +158,28 @@ def legacy_shim_report(root: Path | None = None) -> Dict[str, Any]:
         root = Path(__file__).resolve().parents[2]
     entries = [shim.as_dict() for shim in LEGACY_SHIMS]
     missing = [shim.path for shim in LEGACY_SHIMS if not (root / shim.path).exists()]
+    lingering = [shim.path for shim in REMOVED_SHIMS if (root / shim.path).exists()]
     phases = sorted({shim.removal_phase for shim in LEGACY_SHIMS})
     layers = sorted({shim.layer for shim in LEGACY_SHIMS})
     return {
         "schema_version": "legacy-compatibility/v1",
         "version_target": LEGACY_COMPATIBILITY_VERSION,
-        "status": "managed" if not missing else "incomplete",
+        "status": "managed" if not missing and not lingering else "incomplete",
         "remaining_count": len(LEGACY_SHIMS),
+        "removed_count": len(REMOVED_SHIMS),
         "missing": missing,
+        "lingering": lingering,
         "removal_phases": phases,
         "layers": layers,
         "shims": entries,
+        "removed": [shim.as_dict() for shim in REMOVED_SHIMS],
     }
 
 
 __all__ = [
     "LEGACY_COMPATIBILITY_VERSION",
     "LEGACY_SHIMS",
+    "REMOVED_SHIMS",
     "LegacyShim",
     "legacy_shim_report",
 ]

package/latticeai/core/marketplace.py

@@ -11,7 +11,7 @@ from copy import deepcopy
 from typing import Any, Dict, List, Optional
 
 
-MARKETPLACE_VERSION = "8.7.0"
+MARKETPLACE_VERSION = "8.9.0"
 TEMPLATE_KINDS = ("plugin", "workflow", "agent")
 
 

package/latticeai/core/sessions.py

@@ -90,8 +90,16 @@ def _entry_created_at(entry: tuple) -> float:
 
 
 class SessionStore:
-    def __init__(self, data_dir: Optional[Path] = None):
+    def __init__(
+        self,
+        data_dir: Optional[Path] = None,
+        *,
+        ttl_seconds: int = SESSION_TTL,
+        refresh_threshold_seconds: int = SESSION_REFRESH_THRESHOLD,
+    ):
         self._data_dir = data_dir
+        self._ttl_seconds = int(ttl_seconds or SESSION_TTL)
+        self._refresh_threshold_seconds = int(refresh_threshold_seconds or SESSION_REFRESH_THRESHOLD)
         self._sessions: Dict[str, tuple] = load_sessions(data_dir)
 
     def create(self, subject: str, *, email: Optional[str] = None) -> str:
@@ -117,11 +125,11 @@ class SessionStore:
             if entry is None:
                 return None
             created_at = _entry_created_at(entry)
-            if now - created_at > SESSION_TTL:
+            if now - created_at > self._ttl_seconds:
                 self._sessions.pop(key, None)
                 persist_sessions(self._sessions, self._data_dir)
                 return None
-            if now - created_at > SESSION_REFRESH_THRESHOLD:
+            if now - created_at > self._refresh_threshold_seconds:
                 refreshed = (_entry_subject(entry), now, _entry_email(entry))
                 self._sessions[key] = refreshed
                 persist_sessions(self._sessions, self._data_dir)

package/latticeai/core/tool_registry.py

@@ -109,6 +109,13 @@ def _w(sandbox: str = "workspace", rollback: str = "none") -> ToolPolicy:
     )
 
 
+def _wa(sandbox: str = "workspace", rollback: str = "none") -> ToolPolicy:
+    return ToolPolicy(
+        risk="write", destructive=False, shell=False, network=False,
+        auto_approve=True, sandbox=sandbox, rollback=rollback,
+    )
+
+
 def _e(sandbox: str = "workspace", rollback: str = "none") -> ToolPolicy:
     return ToolPolicy(
         risk="exec", destructive=False, shell=True, network=False,
@@ -137,6 +144,7 @@ TOOL_GOVERNANCE: Dict[str, ToolPolicy] = {
     "search_files": _r(),
     "grep": _r(),
     "inspect_html": _r(),
+    "preview_url": _r(),
     "todo_read": _r(),
     "local_list": _r(sandbox="home"),
     "local_read": _r(sandbox="home"),
@@ -161,7 +169,6 @@ TOOL_GOVERNANCE: Dict[str, ToolPolicy] = {
     "create_xlsx": _w(),
     "create_pptx": _w(),
     "create_pdf": _w(),
-    "preview_url": _w(),
     "todo_write": _w(),
     "knowledge_save": _w(sandbox="home"),
     "obsidian_save": _w(sandbox="home"),
@@ -325,9 +332,13 @@ class ToolRegistry:
 
     def policy_for(self, action_name: str, args: Optional[dict] = None) -> ToolPolicy:
         policy = self.governance.get(action_name, self.default_policy)
-        if action_name == "local_write":
-            path = str((args or {}).get("path", ""))
-            if any(path.startswith(prefix) for prefix in self.local_write_blocked_prefixes):
+        if action_name in {"local_write", "write_file", "edit_file"}:
+            path = str((args or {}).get("path", "")).replace("\\", "/")
+            for prefix in self.local_write_blocked_prefixes:
+                normalized_prefix = str(prefix).rstrip("/")
+                blocked = path == normalized_prefix or path.startswith(f"{normalized_prefix}/")
+                if not blocked:
+                    continue
                 return ToolPolicy(
                     risk="destructive", destructive=True, shell=False, network=False,
                     auto_approve=False, sandbox="system", rollback="none",

package/latticeai/core/workspace_os.py

@@ -49,7 +49,7 @@ __all__ = [
     "remove_skill_directory",
 ]
 
-WORKSPACE_OS_VERSION = "8.7.0"
+WORKSPACE_OS_VERSION = "8.9.0"
 
 # Workspace types separate single-user Personal workspaces from shared
 # Organization workspaces. Both keep the same local-first JSON store; the type

package/latticeai/runtime/bootstrap.py

@@ -24,7 +24,7 @@ def build_session_runtime(
 
     from latticeai.core.sessions import SessionStore
 
-    session_store = SessionStore()
+    session_store = SessionStore(ttl_seconds=ttl_seconds)
 
     def create_session(email: str) -> str:
         return session_store.create(user_id_resolver(email) or email, email=email)

package/latticeai/runtime/persistence_runtime.py

@@ -27,7 +27,7 @@ def build_persistence_runtime(
     import os
     from pathlib import Path
 
-    from lattice_brain.identity import DeviceIdentity
+    from lattice_brain.graph.identity import DeviceIdentity
     from lattice_brain.ingestion import IngestionPipeline
     from lattice_brain.portability import KGPortabilityService
     from latticeai.core.agent_registry import AgentRegistry

package/latticeai/runtime/platform_services_runtime.py

@@ -30,7 +30,7 @@ def build_brain_network(
 ) -> Any:
     """Construct peer sync/network service for brain portability routes."""
 
-    from lattice_brain.network import BrainNetwork
+    from lattice_brain.graph.network import BrainNetwork
 
     return BrainNetwork(
         identity=identity,

package/latticeai/services/app_context.py

@@ -47,6 +47,7 @@ class AppContext:
     load_users: Optional[Callable[[], dict]] = None
     get_user_role: Optional[Callable[..., str]] = None
     enforce_rate_limit: Optional[Callable[..., None]] = None
+    allowed_workspaces_for: Optional[Callable[..., Any]] = None
 
     # ── audit / history callables ─────────────────────────────────────────
     append_audit_event: Optional[Callable[..., None]] = None

package/latticeai/services/architecture_readiness.py

@@ -1,6 +1,6 @@
 """Machine-checkable architecture readiness gates for release work.
 
-8.7.0 keeps the major architecture priorities under an explicit release
+8.9.0 keeps the major architecture priorities under an explicit release
 contract while product maturity work reduces visible beta seams. AgentRuntime, ToolRegistry,
 central Config, decomposed server runtime, and Knowledge Graph stabilization
 must remain discoverable, ordered, and backed by tests before the release can be
@@ -17,7 +17,7 @@ from typing import Any, Dict, List
 from latticeai.core.legacy_compatibility import legacy_shim_report
 
 
-ARCHITECTURE_VERSION_TARGET = "8.7.0"
+ARCHITECTURE_VERSION_TARGET = "8.9.0"
 
 PREFERRED_REFACTORING_ORDER = [
     "agent-runtime",

package/latticeai/services/memory_service.py

@@ -533,6 +533,10 @@ class MemoryService:
                 "title": item.get("title"),
                 "snippet": item.get("snippet"),
                 "score": item.get("score", 0),
+                # Evidence explainability: why this item was recalled, so the
+                # citation UI can show the matched terms instead of a bare score.
+                "matched_terms": item.get("matched_terms") or [],
+                "confidence": item.get("confidence") or "low",
             }
             for item in recall.get("results", [])[: max(1, min(limit, 8))]
         ]
@@ -616,15 +620,17 @@ class MemoryService:
         q = str(query or "").strip()
         query_tokens = [tok for tok in q.lower().split() if tok]
 
-        def _lexical_score(*texts: Any) -> float:
+        def _matched_terms(*texts: Any) -> List[str]:
+            haystack = " ".join(str(t or "") for t in texts).lower()
+            return [tok for tok in query_tokens if tok in haystack]
+
+        def _lexical_score(matched: List[str]) -> float:
             # Honest, comparable relevance: fraction of query tokens present.
             # Both tiers share this scorer so the cross-tier ranking is real,
             # not an artifact of per-tier constants.
             if not query_tokens:
                 return 0.0
-            haystack = " ".join(str(t or "") for t in texts).lower()
-            hits = sum(1 for tok in query_tokens if tok in haystack)
-            return round(hits / len(query_tokens), 4)
+            return round(len(matched) / len(query_tokens), 4)
 
         results: List[Dict[str, Any]] = []
 
@@ -633,13 +639,15 @@ class MemoryService:
         except Exception:
             mem = []
         for m in mem:
+            matched = _matched_terms(m.get("content"), " ".join(m.get("tags") or []), m.get("kind"))
             results.append({
                 "source": "workspace",
                 "id": m.get("id"),
                 "title": (m.get("kind") or "memory"),
                 "snippet": str(m.get("content") or "")[:240],
                 "kind": m.get("kind"),
-                "score": _lexical_score(m.get("content"), " ".join(m.get("tags") or []), m.get("kind")),
+                "score": _lexical_score(matched),
+                "matched_terms": matched,
                 "tags": m.get("tags") or [],
             })
 
@@ -650,17 +658,40 @@ class MemoryService:
             except Exception:
                 hits = []
             for hit in hits[:limit]:
+                matched = _matched_terms(hit.get("title"), hit.get("name"), hit.get("summary"), hit.get("content"))
                 results.append({
                     "source": "graph",
                     "id": hit.get("id") or hit.get("node_id"),
                     "title": hit.get("title") or hit.get("name") or "node",
                     "snippet": str(hit.get("summary") or hit.get("content") or "")[:240],
                     "kind": hit.get("type") or "node",
-                    "score": _lexical_score(hit.get("title"), hit.get("name"), hit.get("summary"), hit.get("content")),
+                    "score": _lexical_score(matched),
+                    "matched_terms": matched,
                 })
 
+        # Quality gate: when at least one result carries real lexical evidence,
+        # zero-score rows are noise relative to it and are dropped. When nothing
+        # scores (e.g. tokenization mismatch), everything is kept so the tiers'
+        # own search filters still decide — the gate never empties a recall.
+        candidates = len(results)
+        if query_tokens and any(r.get("score", 0) > 0 for r in results):
+            results = [r for r in results if r.get("score", 0) > 0]
+        for r in results:
+            r["confidence"] = "high" if r.get("score", 0) >= 0.65 else "medium" if r.get("score", 0) >= 0.3 else "low"
+
         results.sort(key=lambda r: r.get("score", 0), reverse=True)
-        return {"query": q, "results": results[: max(1, min(limit, 100))], "count": len(results), "source": "live"}
+        return {
+            "query": q,
+            "results": results[: max(1, min(limit, 100))],
+            "count": len(results),
+            "source": "live",
+            "quality_gate": {
+                "candidates": candidates,
+                "passed": len(results),
+                "filtered": candidates - len(results),
+                "gate": "lexical-evidence/v1",
+            },
+        }
 
     # ── inspect a single tier ─────────────────────────────────────────────
     def inspect(self, source: str, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None, limit: int = 50) -> Dict[str, Any]: