aethergraph 0.1.0a1__py3-none-any.whl → 0.1.0a3__py3-none-any.whl

aethergraph/services/scope/scope.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Scope:
+    # Tenant / actor
+    org_id: str | None = None
+    user_id: str | None = None
+    client_id: str | None = None
+    mode: str | None = None  # "cloud", "demo", "local", etc.
+
+    # App / execution context
+    app_id: str | None = None
+    session_id: str | None = None
+    run_id: str | None = None
+    graph_id: str | None = None
+    node_id: str | None = None
+    flow_id: str | None = None  # optional flow ID within a graph -- not implemented yet
+
+    # Tooling / proveance (optional)
+    tool_name: str | None = None
+    tool_version: str | None = None
+
+    # Extra tags
+    labels: dict[str, Any] = field(default_factory=dict)
+
+    # Internal override for memory scope ID
+    _memory_scope_id: str | None = None
+
+    def __item__(self, key: str) -> Any:
+        return getattr(self, key)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return getattr(self, key, default)
+
+    def artifact_scope_labels(self) -> dict[str, str]:
+        """
+        Labels to attach to every artifact for this scope.
+        These will be mirrored both into Artifact.labels and the index.
+        """
+        out: dict[str, str] = {}
+        if self.org_id:
+            out["org_id"] = self.org_id
+        if self.user_id:
+            out["user_id"] = self.user_id
+        if self.client_id:
+            out["client_id"] = self.client_id
+        if self.app_id:
+            out["app_id"] = self.app_id
+        if self.session_id:
+            out["session_id"] = self.session_id
+        if self.run_id:
+            out["run_id"] = self.run_id
+        if self.graph_id:
+            out["graph_id"] = self.graph_id
+        if self.node_id:
+            out["node_id"] = self.node_id
+
+        # canonicial scope ids
+        if self.session_id:
+            out["scope_id"] = self.session_id  # session-centric
+        elif self.run_id:
+            out["scope_id"] = self.run_id  # run-centric for non-session runs
+        elif self.graph_id:
+            out["scope_id"] = f"graph:{self.graph_id}"  # graph-centric for non-run artifacts
+        elif self.node_id:
+            out["scope_id"] = f"node:{self.node_id}"  # node-centric for non-graph artifacts
+        return out
+
+    def metering_dimensions(self) -> dict[str, Any]:
+        """Dimensions for MeteringService: what to attach to events."""
+        out: dict[str, Any] = {}
+        if self.user_id:
+            out["user_id"] = self.user_id
+        if self.org_id:
+            out["org_id"] = self.org_id
+        if self.client_id:
+            out["client_id"] = self.client_id
+        if self.app_id:
+            out["app_id"] = self.app_id
+        if self.session_id:
+            out["session_id"] = self.session_id
+        if self.run_id:
+            out["run_id"] = self.run_id
+        if self.graph_id:
+            out["graph_id"] = self.graph_id
+        if self.node_id:
+            out["node_id"] = self.node_id
+        if self.flow_id:
+            out["flow_id"] = self.flow_id
+        return out
+
+    def with_memory_scope(self, mem_scope_id: str) -> Scope:
+        """Return a copy with explicit memory scope override"""
+        return replace(self, _memory_scope_id=mem_scope_id)
+
+    def memory_scope_id(self) -> str:
+        """
+        Stable key for “memory bucket”.
+        Default precedence: explicit override > session > user > run > org > app.
+        """
+        if self._memory_scope_id:
+            return self._memory_scope_id
+        if self.session_id:
+            return f"session:{self.session_id}"
+        if self.user_id:
+            return f"user:{self.user_id}"
+        if self.run_id:
+            return f"run:{self.run_id}"
+        if self.org_id:
+            return f"org:{self.org_id}"
+        if self.app_id:
+            return f"app:{self.app_id}"
+        return "global"
+
+    def rag_labels(self, *, scope_id: str | None = None) -> dict[str, Any]:
+        """
+        Labels that should be stamped on RAG docs/chunks.
+        scope_id is usually memory_scope_id (for memory-tied corpora),
+        but can be any logical scope key.
+        """
+        out: dict[str, Any] = {}
+        if self.user_id:
+            out["user_id"] = self.user_id
+        if self.org_id:
+            out["org_id"] = self.org_id
+        if self.client_id:
+            out["client_id"] = self.client_id
+        if self.app_id:
+            out["app_id"] = self.app_id
+        if self.session_id:
+            out["session_id"] = self.session_id
+        if self.run_id:
+            out["run_id"] = self.run_id
+        if self.graph_id:
+            out["graph_id"] = self.graph_id
+        if self.node_id:
+            out["node_id"] = self.node_id
+        if scope_id:
+            out["scope_id"] = scope_id
+        return out
+
+    def rag_filter(self, *, scope_id: str | None = None) -> dict[str, Any]:
+        """
+        Default filter for RAG search based on identity.
+        You can adjust strictness (e.g., ignore run_id for per-user corpora).
+        """
+        out: dict[str, Any] = {}
+        if self.user_id:
+            out["user_id"] = self.user_id
+        if self.org_id:
+            out["org_id"] = self.org_id
+        if scope_id:
+            out["scope_id"] = scope_id
+        # you can choose to include session_id / run_id only for very strict isolation
+        return out

aethergraph/services/scope/scope_factory.py

@@ -0,0 +1,164 @@
+from dataclasses import dataclass
+from typing import Literal
+
+from aethergraph.api.v1.deps import RequestIdentity
+from aethergraph.services.scope.scope import Scope
+
+
+@dataclass(frozen=True)
+class ScopeFactory:
+    default_app_id: str | None = None
+
+    def base_from_identity(self, identity: RequestIdentity | None) -> Scope:
+        """
+        Create a base Scope from a RequestIdentity.
+        """
+        if identity is None:
+            return Scope(mode="local")
+
+        return Scope(
+            org_id=identity.org_id,
+            user_id=identity.user_id,
+            client_id=identity.client_id,
+            mode=identity.mode,
+            app_id=self.default_app_id,
+        )
+
+    def for_node(
+        self,
+        *,
+        identity: RequestIdentity | None = None,
+        run_id: str | None = None,
+        graph_id: str | None = None,
+        node_id: str | None = None,
+        session_id: str | None = None,
+        app_id: str | None = None,
+        tool_name: str | None = None,
+        tool_version: str | None = None,
+    ) -> Scope:
+        """
+        Create a Scope for a specific node execution.
+        """
+        base = self.base_from_identity(identity)
+        return Scope(
+            org_id=base.org_id,
+            user_id=base.user_id,
+            client_id=base.client_id,
+            mode=base.mode,
+            app_id=app_id or base.app_id,
+            session_id=session_id,
+            run_id=run_id,
+            graph_id=graph_id,
+            node_id=node_id,
+            tool_name=tool_name,
+            tool_version=tool_version,
+        )
+
+    def for_run(
+        self,
+        *,
+        identity: RequestIdentity | None = None,
+        run_id: str,
+        graph_id: str | None = None,
+        session_id: str | None = None,
+        flow_id: str | None = None,
+    ) -> Scope:
+        s = self.base_from_identity(identity)
+        s.run_id = run_id
+        s.graph_id = graph_id
+        s.session_id = session_id
+        s.flow_id = flow_id
+        return s
+
+    def for_memory_custom_override(
+        self,
+        *,
+        identity: RequestIdentity | None = None,
+        run_id: str,
+        graph_id: str | None = None,
+        node_id: str | None = None,
+        session_id: str | None = None,
+        level: Literal["session", "user", "run", "org"] = "session",
+        custom_scope_id: str | None = None,
+    ):
+        """
+        Scope for MemoryFacade. level defines how we group memory:
+        - "session": per-session (default)
+        - "user":    across runs/sessions for a given user
+        - "run":     per-run
+        - "org":     org-level memory
+        """
+        s = self.for_node(
+            identity=identity,
+            run_id=run_id,
+            graph_id=graph_id,
+            node_id=node_id,
+            session_id=session_id,
+        )
+        if custom_scope_id is not None:
+            mem_id = custom_scope_id
+        else:
+            if level == "session":
+                base = session_id or run_id
+                mem_id = f"session:{base}"
+            elif level == "user":
+                u = s.user_id or s.client_id or "anon"
+                mem_id = f"user:{u}"
+            elif level == "run":
+                mem_id = f"run:{run_id}"
+            elif level == "org":
+                o = s.org_id or "orgless"
+                mem_id = f"org:{o}"
+            else:  # pragma: no cover
+                mem_id = f"run:{run_id}"
+
+        return s.with_memory_scope(mem_id)
+
+    def for_memory(
+        self,
+        *,
+        identity: RequestIdentity | None = None,
+        run_id: str,
+        graph_id: str | None = None,
+        node_id: str | None = None,
+        session_id: str | None = None,
+        level: Literal["session", "user", "run", "org"] = "session",
+        custom_scope_id: str | None = None,
+    ):
+        """
+        Rule of thumb for memory scope IDs:
+        - session-level:   "session:{session_id}" or "session:{run_id}" if no session
+        - user-level:      "user:{user_id}" or "user:{client_id}"
+        - run-level:       "run:{run_id}"
+        - org-level:       "org:{org_id}"
+        1) Compute the base ID from the level
+        2) If a custom scope is provided, treat it as a suffix under the root
+            e.g. "session:{base}:{custom_scope_id}"
+        """
+        s = self.for_node(
+            identity=identity,
+            run_id=run_id,
+            graph_id=graph_id,
+            node_id=node_id,
+            session_id=session_id,
+        )
+
+        # 1) Compute the base ID from the level
+        if level == "session":
+            base = session_id or run_id
+            root = f"session:{base}"
+        elif level == "user":
+            u = s.user_id or s.client_id or "anon"
+            root = f"user:{u}"
+        elif level == "run":
+            root = f"run:{run_id}"
+        elif level == "org":
+            o = s.org_id or "orgless"
+            root = f"org:{o}"
+        else:  # pragma: no cover
+            root = f"run:{run_id}"
+
+        # 2) If a custom scope is provided, treat it as a suffix under the root
+        mem_id = f"{root}:{custom_scope_id}" if custom_scope_id else root
+
+        return s.with_memory_scope(mem_id)

aethergraph/services/state_stores/serialize.py

@@ -207,6 +207,8 @@ async def state_to_json_safe(
     for nid, ns in state_obj.nodes.items():
         status = getattr(ns, "status", None)
         status_name = getattr(status, "name", status)  # Enum.name or string
+        started_at = getattr(ns, "started_at", None)
+        finished_at = getattr(ns, "finished_at", None)
         tool_name = getattr(ns, "tool_name", None) or getattr(
             getattr(ns, "spec", None), "tool_name", None
         )
@@ -232,7 +234,10 @@ async def state_to_json_safe(
             "attempts": getattr(ns, "attempts", 0),
             "next_wakeup_at": getattr(ns, "next_wakeup_at", None),
             "wait_token": getattr(ns, "wait_token", None),
+            "started_at": started_at,
+            "finished_at": finished_at,
         }
+
         if include_wait_spec:
             ws = getattr(ns, "wait_spec", None)
             if ws:

aethergraph/services/state_stores/utils.py

@@ -29,7 +29,7 @@ async def snapshot_from_graph(
         allow_externalize=allow_externalize,
         include_wait_spec=include_wait_spec,
     )
-    return GraphSnapshot(
+    snap = GraphSnapshot(
         run_id=run_id,
         graph_id=graph_id,
         rev=rev,
@@ -37,6 +37,7 @@ async def snapshot_from_graph(
         spec_hash=spec_hash,
         state=json_state,
     )
+    return snap
 
 
 def _status_to_str(s) -> str: