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

aethergraph/core/runtime/run_manager_local.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+from aethergraph.contracts.errors.errors import GraphHasPendingWaits
+from aethergraph.contracts.services.runs import RunStore
+from aethergraph.core.runtime.run_types import RunRecord, RunStatus
+from aethergraph.core.runtime.runtime_metering import current_metering
+from aethergraph.core.runtime.runtime_registry import current_registry
+from aethergraph.services.registry.unified_registry import UnifiedRegistry
+
+
+def _utcnow() -> datetime:
+    return datetime.now(tz=timezone.utc)
+
+
+def _is_task_graph(obj: Any) -> bool:
+    return hasattr(obj, "spec") and hasattr(obj, "io_signature")
+
+
+def _is_graphfn(obj: Any) -> bool:
+    from aethergraph.core.graph.graph_fn import GraphFunction  # adjust path
+
+    return isinstance(obj, GraphFunction)
+
+
+class RunManager:
+    """
+    Core coordinator for runs:
+
+    - Resolves targets from the UnifiedRegistry.
+    - Calls run_or_resume_async for TaskGraph/GraphFunction.
+    - Records metadata in RunStore.
+    - TODO: (Later) can coordinate cancellation via sched_registry or best effort with graph_fn.
+    """
+
+    def __init__(
+        self, *, run_store: RunStore | None = None, registry: UnifiedRegistry | None = None
+    ):
+        self._store = run_store
+        self._registry = registry
+
+    def registry(self) -> UnifiedRegistry:
+        return self._registry or current_registry()
+
+    async def _resolve_target(self, graph_id: str) -> Any:
+        reg = self.registry()
+        # Try static TaskGraph
+        try:
+            return reg.get_graph(name=graph_id, version=None)
+        except KeyError:
+            pass
+        # Try GraphFunction
+        try:
+            return reg.get_graphfn(name=graph_id, version=None)
+        except KeyError:
+            pass
+        raise KeyError(f"Graph '{graph_id}' not found")
+
+    async def start_run(
+        self,
+        graph_id: str,
+        *,
+        inputs: dict[str, Any],
+        run_id: str | None = None,
+        tags: list[str] | None = None,
+        user_id: str | None = None,
+        org_id: str | None = None,
+    ) -> tuple[RunRecord, dict[str, Any] | None, bool, list[dict[str, Any]]]:
+        """
+        The main entrypoint for the API layer.
+
+        Returns:
+          (record, outputs, has_waits, continuations)
+        """
+        from aethergraph.core.runtime.graph_runner import run_or_resume_async
+
+        tags = tags or []
+        target = await self._resolve_target(graph_id)
+        rid = run_id or f"run-{uuid4().hex[:8]}"
+
+        started_at = _utcnow()
+
+        if _is_task_graph(target):
+            kind = "taskgraph"
+        elif _is_graphfn(target):
+            kind = "graphfn"
+        else:
+            kind = "other"
+
+        # Initial record
+        record = RunRecord(
+            run_id=rid,
+            graph_id=graph_id,
+            kind=kind,
+            status=RunStatus.running,  # or pending, but we jump straight to running
+            started_at=started_at,
+            tags=list(tags),
+            user_id=user_id,
+            org_id=org_id,
+        )
+
+        if self._store is not None:
+            await self._store.create(record)
+
+        outputs: dict[str, Any] | None = None
+        has_waits = False
+        continuations: list[dict[str, Any]] = []
+        error_msg: str | None = None
+
+        try:
+            result = await run_or_resume_async(target, inputs or {}, run_id=rid)
+            # If we get here without GraphHasPendingWaits, run is completed
+            outputs = result if isinstance(result, dict) else {"result": result}
+            record.status = RunStatus.succeeded
+            record.finished_at = _utcnow()
+
+        except GraphHasPendingWaits as e:
+            # Graph quiesced with pending waits
+            record.status = RunStatus.running
+            has_waits = True
+            continuations = getattr(e, "continuations", [])
+            # outputs stay None
+
+        except Exception as exc:
+            record.status = RunStatus.failed
+            record.finished_at = _utcnow()
+            error_msg = str(exc)
+            record.error = error_msg
+            # TODO: log here with current_logger_factory if desired
+            import logging
+
+            logging.getLogger("aethergraph.runtime.run_manager").exception(
+                "Run %s failed with exception with %s", rid, error_msg
+            )
+
+        if self._store is not None:
+            await self._store.update_status(
+                rid,
+                record.status,
+                finished_at=record.finished_at,
+                error=error_msg,
+            )
+
+        meter = current_metering()
+        # Duration: if finished_at is None, use now()
+        finished_at = record.finished_at or _utcnow()
+        duration_s = (finished_at - started_at).total_seconds()
+        # Map Runstatus + waits to status string for metering
+        if has_waits:
+            meter_status = "waiting"
+        else:
+            status_str = getattr(record.status, "value", str(record.status))
+            meter_status = status_str
+
+        try:
+            await meter.record_run(
+                user_id=user_id,
+                org_id=org_id,
+                run_id=rid,
+                graph_id=graph_id,
+                status=meter_status,
+                duration_s=duration_s,
+            )
+        except Exception:
+            # Never fail the run due to metering issues
+            import logging
+
+            logging.getLogger("aethergraph.runtime.run_manager").exception(
+                "Error recording run metering for run_id=%s", rid
+            )
+
+        return record, outputs, has_waits, continuations
+
+    async def get_record(self, run_id: str) -> RunRecord | None:
+        if self._store is None:
+            return None
+        return await self._store.get(run_id)
+
+    async def list_records(
+        self,
+        *,
+        graph_id: str | None = None,
+        status: RunStatus | None = None,
+        limit: int = 100,
+    ) -> list[RunRecord]:
+        if self._store is None:
+            return []
+        return await self._store.list(graph_id=graph_id, status=status, limit=limit)
+
+    # Placeholder for future cancellation
+    async def cancel_run(self, run_id: str) -> RunRecord | None:
+        """
+        Later: use container.sched_registry to find scheduler and request cancellation.
+
+        For now, it's a stub that just reads the current record.
+        """
+        # Future:
+        #  - container = current_services()
+        #  - sched = container.sched_registry.get(run_id)
+        #  - if sched: sched.request_cancel() or sched.terminate()
+        return await self.get_record(run_id)

aethergraph/core/runtime/run_registration.py

@@ -17,8 +17,8 @@ class RunRegistrationGuard(AbstractContextManager):
         reg = self.container.sched_registry
         existing = reg.get(self.run_id)
         if existing is not None and existing is not self.scheduler:
-            # Be explicit to avoid silent clobbering
-            raise RuntimeError(f"Scheduler already registered for run_id={self.run_id}")
+            # Do nothing if already registered
+            return self
         reg.register(self.run_id, self.scheduler)
         self._did_reg = True
         return self

aethergraph/core/runtime/run_types.py

@@ -0,0 +1,89 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+# used to represent the status of a run, primiarily used in endpoint with RunManager
+
+
+class RunStatus(str, Enum):
+    pending = "pending"
+    running = "running"
+    succeeded = "succeeded"
+    failed = "failed"
+    waiting = "waiting"
+    canceled = "canceled"
+    cancellation_requested = "cancellation_requested"
+
+
+class RunOrigin(str, Enum):
+    app = "app"  # launched from an application UI
+    agent = "agent"  # launched by an AI agent
+    chat = "chat"  # launched from a chat interface
+    playground = "playground"  # launched from a playground environment (sidecar/SDK/local dev)
+    api = "api"  # launched from an API call
+    system = "system"  # launched from a system process (internal maintenance, cron job, etc.)
+
+
+class RunVisibility(str, Enum):
+    normal = "normal"  # visible to all users with access to the org/client
+    inline = "inline"  # hidden from run listings, only shown in session / debug views
+    hidden = "hidden"  # hidden from all UIs (used in quick tests, ephemeral runs, etc.)
+
+
+class RunImportance(str, Enum):
+    normal = "normal"  # standard run
+    ephemeral = "ephemeral"  # low-importance run, noisy or temporary (may be pruned sooner)
+
+
+@dataclass
+class RunRecord:
+    """
+    Core-level representation of a run.
+
+    This is independent from any Pydantic model used by the HTTP API.
+    """
+
+    run_id: str
+    graph_id: str
+    kind: str  # "taskgraph" | "graphfn" | other in the future
+    status: RunStatus
+    started_at: datetime
+    finished_at: datetime | None = None
+
+    tags: list[str] = field(default_factory=list)
+    user_id: str | None = None
+    org_id: str | None = None
+    error: str | None = None
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    session_id: str | None = None
+    origin: RunOrigin = RunOrigin.app
+    visibility: RunVisibility = RunVisibility.normal
+    importance: RunImportance = RunImportance.normal
+
+    # optional agent/app linkage
+    agent_id: str | None = None
+    app_id: str | None = None
+
+    # Artifact statistics
+    artifact_count: int = 0
+    first_artifact_at: datetime | None = None
+    last_artifact_at: datetime | None = None
+
+    # Optional: keep a small rolling window of recent artifact IDs
+    recent_artifact_ids: list[str] = field(default_factory=list)
+
+    def __item__(self, key: str) -> Any:
+        return getattr(self, key)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return getattr(self, key, default)
+
+
+# Session-related run types
+class SessionKind(str, Enum):
+    chat = "chat"
+    playground = "playground"
+    notebook = "notebook"
+    pipline = "pipeline"  # future

aethergraph/core/runtime/runtime_env.py

@@ -2,9 +2,11 @@ from collections.abc import Callable
 from dataclasses import dataclass, field
 from typing import Any
 
+from aethergraph.api.v1.deps import RequestIdentity
+from aethergraph.contracts.storage.artifact_index import AsyncArtifactIndex
+
 # ---- artifact services ----
-from aethergraph.services.artifacts.fs_store import FSArtifactStore  # AsyncArtifactStore
-from aethergraph.services.artifacts.jsonl_index import JsonlArtifactIndex  # AsyncArtifactIndex
+from aethergraph.contracts.storage.artifact_store import AsyncArtifactStore
 
 # ---- channel services ----
 from aethergraph.services.channel.channel_bus import ChannelBus
@@ -16,7 +18,9 @@ from aethergraph.services.continuations.stores.fs_store import (
 
 # ---- memory services ----
 from aethergraph.services.memory.facade import MemoryFacade
+from aethergraph.services.rag.node_rag import NodeRAG
 from aethergraph.services.resume.router import ResumeRouter
+from aethergraph.services.viz.facade import VizFacade
 from aethergraph.services.waits.wait_registry import WaitRegistry
 
 from ..graph.task_node import TaskNodeRuntime
@@ -31,9 +35,15 @@ class RuntimeEnv:
 
     run_id: str
     graph_id: str | None = None
+    session_id: str | None = None
+    identity: RequestIdentity | None = None
     graph_inputs: dict[str, Any] = field(default_factory=dict)
     outputs_by_node: dict[str, dict[str, Any]] = field(default_factory=dict)
 
+    # agent and app ids
+    agent_id: str | None = None  # for agent-invoked runs
+    app_id: str | None = None  # for app-invoked runs
+
     # container (DI)
     container: DefaultContainer = field(default_factory=get_container)
 
@@ -70,11 +80,11 @@ class RuntimeEnv:
         return self.container.wait_registry
 
     @property
-    def artifacts(self) -> FSArtifactStore:
+    def artifacts(self) -> AsyncArtifactStore:
         return self.container.artifacts
 
     @property
-    def artifact_index(self) -> JsonlArtifactIndex:
+    def artifact_index(self) -> AsyncArtifactIndex:
         return self.container.artifact_index
 
     @property
@@ -104,15 +114,43 @@ class RuntimeEnv:
             "run_id": self.run_id,
             "graph_id": self.graph_id,
             "node_id": node.node_id,
-            "agent_id": getattr(node, "tool_name", None),
             "tags": [],
             "entities": [],
         }
+
+        level, custom_scope_id = self._resolve_memory_config()
+        mem_scope = (
+            self.container.scope_factory.for_memory(
+                identity=self.identity,
+                run_id=self.run_id,
+                graph_id=self.graph_id,
+                node_id=node.node_id,
+                session_id=self.session_id,
+                level=level,
+                custom_scope_id=custom_scope_id,
+            )
+            if self.container.scope_factory
+            else None
+        )
+
         mem: MemoryFacade = self.memory_factory.for_session(
             run_id=self.run_id,
             graph_id=self.graph_id,
             node_id=node.node_id,
-            agent_id=defaults["agent_id"],
+            session_id=self.session_id,
+            scope=mem_scope,
+        )
+
+        node_scope = (
+            self.container.scope_factory.for_node(
+                identity=self.identity,
+                run_id=self.run_id,
+                graph_id=self.graph_id,
+                node_id=node.node_id,
+                session_id=self.session_id,
+            )
+            if self.container.scope_factory
+            else None
         )
 
         from aethergraph.services.artifacts.facade import ArtifactFacade
@@ -125,8 +163,30 @@ class RuntimeEnv:
             tool_version=node.tool_version,  # to be filled from node if available
             store=self.artifacts,
             index=self.artifact_index,
+            scope=node_scope,
+        )
+
+        # ------- Viz Service tied to this node/run -------'
+        vis_facade = VizFacade(
+            run_id=self.run_id,
+            graph_id=self.graph_id,
+            node_id=node.node_id,
+            tool_name=node.tool_name,
+            tool_version=node.tool_version,
+            artifacts=artifact_facade,
+            viz_service=self.container.viz_service,
+            scope=node_scope,
         )
 
+        # ------- RAG Facade in Memory tied to this node/run -------'
+        rag_for_node = None
+        if self.rag_facade is not None and node_scope is not None:
+            rag_for_node = NodeRAG(
+                rag=self.rag_facade,
+                scope=node_scope,
+                default_scope_id=(mem_scope.memory_scope_id() if mem_scope else None),
+            )
+
         services = NodeServices(
             channels=self.channels,
             continuation_store=self.continuation_store,
@@ -137,13 +197,19 @@ class RuntimeEnv:
             kv=self.container.kv_hot,  # keep using hot kv for ephemeral
             memory=self.memory_factory,  # factory (for other sessions if needed)
             memory_facade=mem,  # bound memory for this run/node
+            viz=vis_facade,
             llm=self.llm_service,  # LLMService
-            rag=self.rag_facade,  # RAGService
+            rag=rag_for_node,  # RAGService
             mcp=self.mcp_service,  # MCPService
+            run_manager=self.container.run_manager,  # RunManager
         )
         return ExecutionContext(
             run_id=self.run_id,
+            session_id=self.session_id,
+            identity=self.identity,
             graph_id=self.graph_id,
+            agent_id=self.agent_id,
+            app_id=self.app_id,
             graph_inputs=self.graph_inputs,
             outputs_by_node=self.outputs_by_node,
             services=services,
@@ -151,7 +217,70 @@ class RuntimeEnv:
             clock=self.clock,
             resume_payload=resume_payload,
             should_run_fn=self.should_run_fn,
+            scope=node_scope,
             # Back-compat shim for old ctx.mem()
             bound_memory=BoundMemoryAdapter(mem, defaults),
             resume_router=self.resume_router,
         )
+
+    def _resolve_memory_config(self) -> tuple[str, str | None]:
+        """
+        Returns (level, custom_scope_id).
+
+        Resolution order:
+        1) If this run has an agent_id, read from the agent registry meta.
+        2) Else if this run has an app_id, read from the app registry meta.
+        3) Else fall back to graph/graphfn meta.
+        4) Defaults:
+           - agent/app-backed runs -> "session"
+           - plain graph runs      -> "run"
+        """
+        registry = self.registry
+        level: str = "session"  # safe default
+        custom_scope_id: str | None = None
+        meta: dict[str, Any] = {}
+
+        if registry:
+            # Prefer agent meta
+            if self.agent_id:
+                meta = (
+                    registry.get_meta(
+                        nspace="agent",
+                        name=self.agent_id,
+                        version=None,
+                    )
+                    or {}
+                )
+            # Then app meta
+            elif self.app_id:
+                meta = (
+                    registry.get_meta(
+                        nspace="app",
+                        name=self.app_id,
+                        version=None,
+                    )
+                    or {}
+                )
+            # Finally, bare graph meta (graphfn or taskgraph)
+            elif self.graph_id:
+                meta = (
+                    registry.get_meta("graphfn", self.graph_id, None)
+                    or registry.get_meta("graph", self.graph_id, None)
+                    or {}
+                )
+
+        if meta:
+            # Top-level keys from as_agent/as_app extras
+            if "memory_level" in meta:
+                level = meta["memory_level"]
+            else:
+                # Fallback by kind if not explicitly set
+                kind = meta.get("kind")
+                level = "session" if kind == "agent" else "run"
+
+            custom_scope_id = meta.get("memory_scope")
+        else:
+            # If we have an agent_id but no meta, still bias to session-level
+            level = "session" if self.agent_id else "run"
+
+        return level, custom_scope_id

aethergraph/core/runtime/runtime_metering.py

@@ -0,0 +1,71 @@
+from contextvars import ContextVar
+
+from aethergraph.contracts.services.metering import MeteringService
+from aethergraph.services.metering.noop import NoopMeteringService
+
+MeterContext = dict[str, str | None]
+current_meter_context: ContextVar[MeterContext] = ContextVar("ag_meter_context", default={})
+
+
+# Process-wide default (can be replaced during app startup)
+__singleton_metering: MeteringService = NoopMeteringService()
+
+# Optional per-context override
+_current_metering: ContextVar[MeteringService | None] = ContextVar("ag_metering", default=None)
+
+
+def install_global_metering(svc: MeteringService) -> None:
+    """
+    Called at server startup to install the real metering service.
+
+    E.g. in create_app():
+      install_global_metering(EventLogMeteringService(meter_store))
+    """
+    global __singleton_metering
+    __singleton_metering = svc
+
+
+def set_current_metering(svc: MeteringService) -> None:
+    """
+    Override the metering service for the current context (tests, special scopes).
+    """
+    _current_metering.set(svc)
+
+
+def global_metering() -> MeteringService:
+    """
+    Return the process-wide singleton (usually a real service after startup,
+    or NoopMeteringService in CLI/tests).
+    """
+    return __singleton_metering
+
+
+def current_metering() -> MeteringService:
+    """
+    Get the current metering service.
+
+    Priority:
+      1) Container services (if installed) and they hold a .metering
+      2) ContextVar override (set_current_metering)
+      3) Global singleton (Noop by default)
+    """
+    from ..runtime.runtime_services import current_services  # lazy import
+
+    # 1) Prefer container services.metering if present
+    try:
+        svc_container = current_services()
+        svc = getattr(svc_container, "metering", None)
+        # install the metering from services container
+        set_current_metering(svc)
+        if isinstance(svc, MeteringService.__constraints__):  # type: ignore[attr-defined]
+            return svc
+    except Exception:
+        pass
+
+    # 2) ContextVar
+    svc = _current_metering.get()
+    if svc is not None:
+        return svc
+
+    # 3) Fallback
+    return __singleton_metering

aethergraph/core/runtime/runtime_registry.py

@@ -2,31 +2,54 @@ from contextvars import ContextVar
 
 from aethergraph.services.registry.unified_registry import UnifiedRegistry
 
+# Single process-wide registry instance
 __singleton_registry: UnifiedRegistry = UnifiedRegistry()
+
+# Optional overrides per-context (rarely needed)
 _current_registry: ContextVar[UnifiedRegistry | None] = ContextVar("ag_registry", default=None)
 
 
-def set_current_registry(reg: UnifiedRegistry):
-    """Set the current registry in contextvar."""
+def global_registry() -> UnifiedRegistry:
+    """
+    Return the process-wide global registry instance.
+
+    Use this when you explicitly want the singleton, e.g. wiring into containers.
+    """
+    return __singleton_registry
+
+
+def set_current_registry(reg: UnifiedRegistry) -> None:
+    """
+    Override the registry for the current context (e.g., tests or special scopes).
+    """
     _current_registry.set(reg)
 
 
 def current_registry() -> UnifiedRegistry:
-    """Get the current registry from contextvar, or raise if not set."""
-    # first try if services has a registry set
-    from .runtime_services import current_services
+    """
+    Get the current registry.
+
+    Priority:
+      1) Container services (if installed) and they hold a registry.
+      2) ContextVar override (set_current_registry).
+      3) Global singleton.
+    """
+    from .runtime_services import current_services  # lazy import to avoid cycles
 
-    svc = None
+    # 1) If services are installed and have a registry, prefer that
     try:
-        # get current services and registry from there
         svc = current_services()
-        if hasattr(svc, "registry") and svc.registry is not None:
-            return svc.registry
+        reg = getattr(svc, "registry", None)
+        if isinstance(reg, UnifiedRegistry):
+            return reg
     except Exception:
+        # services not installed or not accessible in this context
         pass
 
-    # otherwise use contextvar
+    # 2) ContextVar
     reg = _current_registry.get()
-    if reg is None:
-        return __singleton_registry  # fallback to singleton if not set in local context
-    return reg
+    if reg is not None:
+        return reg
+
+    # 3) Fallback to singleton
+    return __singleton_registry