ltcai 3.6.0 → 4.0.1

package/latticeai/core/users.py

@@ -0,0 +1,147 @@
+"""User identity store and v4 UUID migration helpers."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import sqlite3
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+USER_NAMESPACE = uuid.UUID("5d6d4480-cf79-49c3-a6d0-4c6eec3224d6")
+
+
+def _now() -> str:
+    return datetime.now().isoformat(timespec="seconds")
+
+
+def _atomic_write_json(path: Path, data: Dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+    tmp.replace(path)
+
+
+def normalize_email(email: str) -> str:
+    return str(email or "").strip().lower()
+
+
+def stable_user_id(email: str) -> str:
+    return f"user:{uuid.uuid5(USER_NAMESPACE, normalize_email(email))}"
+
+
+def ensure_user_identity(email: str, user: Dict[str, Any]) -> bool:
+    changed = False
+    normalized = normalize_email(email or user.get("email") or "")
+    if not user.get("id"):
+        user["id"] = stable_user_id(normalized)
+        changed = True
+    if user.get("email") != normalized:
+        user["email"] = normalized
+        changed = True
+    return changed
+
+
+def migrate_users(users: Dict[str, Any]) -> tuple[Dict[str, Any], Dict[str, str], bool]:
+    migrated: Dict[str, Any] = {}
+    email_to_id: Dict[str, str] = {}
+    changed = False
+    for raw_email, raw_user in (users or {}).items():
+        if not isinstance(raw_user, dict):
+            continue
+        email = normalize_email(raw_user.get("email") or raw_email)
+        user = dict(raw_user)
+        changed = ensure_user_identity(email, user) or changed
+        if raw_email != email:
+            changed = True
+        if email in migrated:
+            existing = migrated[email]
+            merged = {**existing, **user}
+            merged["id"] = existing.get("id") or user.get("id") or stable_user_id(email)
+            if isinstance(existing.get("api_keys"), dict) or isinstance(user.get("api_keys"), dict):
+                merged["api_keys"] = {**(existing.get("api_keys") or {}), **(user.get("api_keys") or {})}
+            user = merged
+            changed = True
+        migrated[email] = user
+        email_to_id[email] = user["id"]
+    return migrated, email_to_id, changed
+
+
+def load_users_file(path: Path) -> Dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        loaded = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(loaded, dict):
+            loaded = {}
+    except Exception:
+        loaded = {}
+    migrated, _, changed = migrate_users(loaded)
+    if changed:
+        backup = path.with_name(f"{path.name}.pre-user-uuid.{_now().replace(':', '-')}.json")
+        try:
+            shutil.copy2(path, backup)
+        except Exception:
+            pass
+        _atomic_write_json(path, migrated)
+    return migrated
+
+
+def save_users_file(path: Path, users: Dict[str, Any]) -> None:
+    migrated, _, _ = migrate_users(users)
+    _atomic_write_json(path, migrated)
+
+
+def user_id_for_email(users: Dict[str, Any], email: Optional[str]) -> Optional[str]:
+    if not email:
+        return None
+    if str(email).startswith("user:"):
+        return str(email)
+    normalized = normalize_email(email)
+    user = (users or {}).get(normalized)
+    if isinstance(user, dict):
+        return user.get("id") or stable_user_id(normalized)
+    return stable_user_id(normalized)
+
+
+def email_for_user_id(users: Dict[str, Any], user_id: Optional[str]) -> Optional[str]:
+    if not user_id:
+        return None
+    for email, user in (users or {}).items():
+        if isinstance(user, dict) and user.get("id") == user_id:
+            return email
+    return None
+
+
+def migrate_knowledge_graph_identity(db_path: Path, email_to_id: Dict[str, str]) -> int:
+    """Rewrite KG owner/creator identity columns from email to stable UUIDs."""
+    if not db_path.exists() or not email_to_id:
+        return 0
+    changed = 0
+    with sqlite3.connect(db_path) as conn:
+        tables = {
+            row[0] for row in conn.execute("SELECT name FROM sqlite_master WHERE type='table'")
+        }
+        for email, user_id in email_to_id.items():
+            normalized = normalize_email(email)
+            if "nodes_v2" in tables:
+                cur = conn.execute("UPDATE nodes_v2 SET owner_id=? WHERE LOWER(owner_id)=?", (user_id, normalized))
+                changed += cur.rowcount if cur.rowcount and cur.rowcount > 0 else 0
+            if "edges_v2" in tables:
+                cur = conn.execute("UPDATE edges_v2 SET created_by=? WHERE LOWER(created_by)=?", (user_id, normalized))
+                changed += cur.rowcount if cur.rowcount and cur.rowcount > 0 else 0
+            if "ingestion_provenance" in tables:
+                cur = conn.execute("UPDATE ingestion_provenance SET owner=? WHERE LOWER(owner)=?", (user_id, normalized))
+                changed += cur.rowcount if cur.rowcount and cur.rowcount > 0 else 0
+        if changed:
+            conn.execute(
+                "CREATE TABLE IF NOT EXISTS kg_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)"
+            )
+            conn.execute(
+                "INSERT OR REPLACE INTO kg_meta(key, value) VALUES('identity_uuid_migrated_at', ?)",
+                (_now(),),
+            )
+    return changed

package/latticeai/core/workflow_engine.py

@@ -185,11 +185,17 @@ def _evaluate_condition(config: Dict[str, Any], context: Dict[str, Any]) -> bool
 class WorkflowRun:
     workflow_id: Optional[str]
     name: str
-    status: str = "ok"  # ok | failed | partial
+    status: str = "ok"  # ok | failed | partial | awaiting_approval
     timeline: List[Dict[str, Any]] = field(default_factory=list)
     outputs: Dict[str, Any] = field(default_factory=dict)
     started_at: str = field(default_factory=_now)
     finished_at: Optional[str] = None
+    # Suspension cursor (status == awaiting_approval): the paused node, what
+    # it is waiting for, and a JSON-serializable context snapshot resume()
+    # re-enters with — completed nodes are never re-executed.
+    paused_node: Optional[str] = None
+    pending_approval: Optional[Dict[str, Any]] = None
+    paused_context: Optional[Dict[str, Any]] = None
 
     def as_dict(self) -> Dict[str, Any]:
         return {
@@ -201,9 +207,36 @@ class WorkflowRun:
             "started_at": self.started_at,
             "finished_at": self.finished_at,
             "step_count": len(self.timeline),
+            "paused_node": self.paused_node,
+            "pending_approval": self.pending_approval,
+            "paused_context": self.paused_context,
         }
 
 
+class ApprovalRequired(Exception):
+    """A node needs an explicit human decision before it may execute.
+
+    Raised by governed runners (e.g. a non-auto-approve tool). The engine
+    pauses the run into ``awaiting_approval`` with a serializable cursor —
+    it never records a fake success and never silently skips the node.
+    """
+
+    def __init__(self, message: str, *, tool: Optional[str] = None,
+                 args: Optional[Dict[str, Any]] = None,
+                 permission: Optional[Dict[str, Any]] = None):
+        super().__init__(message)
+        self.tool = tool
+        self.args = args or {}
+        self.permission = permission or {}
+
+
+def _json_safe(value: Any) -> Any:
+    """Round-trip through JSON so paused context is durably serializable."""
+    import json as _json
+
+    return _json.loads(_json.dumps(value, ensure_ascii=False, default=str))
+
+
 class WorkflowEngine:
     """Interprets a validated workflow definition over injected runners.
 
@@ -212,6 +245,11 @@ class WorkflowEngine:
     node as ``skipped`` with a reason rather than failing the whole run, so a
     workflow that references a capability the host has not wired degrades
     gracefully (and the gap is visible in the timeline).
+
+    Suspension model (v4): a runner raising :class:`ApprovalRequired` pauses
+    the run (status ``awaiting_approval``) with the node cursor and a
+    JSON-serializable context snapshot. :meth:`resume` re-enters at the
+    paused node — completed nodes are NEVER re-executed.
     """
 
     def __init__(self, runners: Optional[Dict[str, Callable[..., Any]]] = None, *, hooks: Any = None):
@@ -243,8 +281,60 @@ class WorkflowEngine:
 
         nodes = {node["id"]: node for node in definition["nodes"]}
         context: Dict[str, Any] = {"inputs": inputs or {}, **(inputs or {})}
-
         current = _entry_node(definition["nodes"])
+        return self._execute(definition, run, nodes, context, current)
+
+    def resume(
+        self,
+        workflow: Dict[str, Any],
+        *,
+        paused_node: str,
+        paused_context: Dict[str, Any],
+        approved: bool,
+        prior_timeline: Optional[List[Dict[str, Any]]] = None,
+    ) -> WorkflowRun:
+        """Re-enter a paused run at its cursor; completed nodes never re-run.
+
+        ``approved=True`` marks the paused node as human-approved (its runner
+        sees the node id in ``context['__approved_nodes__']``); ``False``
+        records an explicit denial and fails the run honestly.
+        """
+        definition = normalize_definition(workflow)
+        nodes = {node["id"]: node for node in definition["nodes"]}
+        node = nodes.get(paused_node)
+        run = WorkflowRun(workflow_id=definition.get("id"), name=definition.get("name") or "workflow")
+        if prior_timeline:
+            run.timeline.extend(prior_timeline)
+        if node is None:
+            run.status = "failed"
+            run.timeline.append({"node": paused_node, "type": "resume", "status": "failed",
+                                 "reason": "paused node no longer exists in the definition",
+                                 "timestamp": _now()})
+            run.finished_at = _now()
+            return run
+        context: Dict[str, Any] = dict(paused_context or {})
+        if not approved:
+            run.status = "failed"
+            run.timeline.append({"node": paused_node, "type": node.get("type"),
+                                 "name": node.get("name") or paused_node,
+                                 "status": "denied",
+                                 "reason": "approval denied by the user",
+                                 "timestamp": _now()})
+            run.finished_at = _now()
+            return run
+        approvals = set(context.get("__approved_nodes__") or [])
+        approvals.add(paused_node)
+        context["__approved_nodes__"] = sorted(approvals)
+        return self._execute(definition, run, nodes, context, node)
+
+    def _execute(
+        self,
+        definition: Dict[str, Any],
+        run: WorkflowRun,
+        nodes: Dict[str, Dict[str, Any]],
+        context: Dict[str, Any],
+        current: Optional[Dict[str, Any]],
+    ) -> WorkflowRun:
         steps = 0
         had_error = False
         had_skip = False
@@ -301,6 +391,28 @@ class WorkflowEngine:
                 entry["result"] = result
                 context["last_output"] = result
                 context[nid] = result
+            except ApprovalRequired as pause:
+                # Suspend — never a fake success, never a silent skip.
+                entry["status"] = "awaiting_approval"
+                entry["pending"] = {
+                    "tool": pause.tool, "args": pause.args,
+                    "permission": pause.permission, "reason": str(pause),
+                }
+                run.timeline.append(entry)
+                run.status = "awaiting_approval"
+                run.paused_node = nid
+                run.pending_approval = entry["pending"]
+                try:
+                    run.paused_context = _json_safe(context)
+                except Exception:
+                    run.paused_context = {"inputs": context.get("inputs") or {}}
+                if self.hooks is not None:
+                    self.hooks.fire_hook(
+                        "post_workflow", "workflow.paused",
+                        payload={"workflow_id": definition.get("id"),
+                                 "status": run.status, "node": nid},
+                    )
+                return run
             except Exception as exc:
                 entry["status"] = "error"
                 entry["reason"] = str(exc)