aethergraph 0.1.0a1__py3-none-any.whl

aethergraph/core/graph/graphify.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import inspect
+
+from ..runtime.runtime_registry import current_registry
+from .task_graph import TaskGraph
+
+
+def graphify(
+    *, name="default_graph", inputs=(), outputs=None, version="0.1.0", agent: str | None = None
+):
+    """
+    Decorator that builds a TaskGraph from a function body using the builder context.
+    The function author writes sequential code with tool calls returning NodeHandles.
+
+    Usage:
+    @graphify(name="my_graph", inputs=["input1", "input2"], outputs=["output"])
+    def my_graph(input1, input2):
+        # function body using graph builder API
+        pass
+        return {"output": some_node_handle}
+
+    The decorated function returns a builder function that constructs the TaskGraph.
+
+    To build the graph, call the returned function:
+    graph_instance = my_graph.build()
+    """
+
+    def _wrap(fn):
+        fn_sig = inspect.signature(fn)
+        fn_params = list(fn_sig.parameters.keys())
+
+        # Normalize declared inputs into a list of names
+        required_inputs = list(inputs.keys()) if isinstance(inputs, dict) else list(inputs)
+
+        # Optional: validate the signature matches declared inputs
+        # (or keep permissive: inject only the overlap)
+        overlap = [p for p in fn_params if p in required_inputs]
+
+        def _build() -> TaskGraph:
+            from .graph_builder import graph
+            from .graph_refs import arg
+
+            with graph(name=name) as g:
+                # declarations unchanged...
+                if isinstance(inputs, dict):
+                    g.declare_inputs(required=[], optional=inputs)
+                else:
+                    g.declare_inputs(required=required_inputs, optional={})
+
+                # --- Inject args: map fn params -> arg("<name>")
+                injected_kwargs = {p: arg(p) for p in overlap}
+
+                # Run user body
+                ret = fn(**injected_kwargs)  # ← key line
+
+                # expose logic (fixed typo + single-output collapse)
+                def _is_ref(x):
+                    return (
+                        isinstance(x, dict)
+                        and x.get("_type") == "ref"
+                        and "from" in x
+                        and "key" in x
+                    )
+
+                def _expose_from_handle(prefix, handle):
+                    oks = list(getattr(handle, "output_keys", []))
+                    if prefix and len(oks) == 1:
+                        g.expose(prefix, getattr(handle, oks[0]))
+                    else:
+                        for k in oks:
+                            g.expose(f"{prefix}.{k}" if prefix else k, getattr(handle, k))
+
+                if isinstance(ret, dict):
+                    for k, v in ret.items():
+                        if _is_ref(v):
+                            g.expose(k, v)
+                        elif hasattr(v, "node_id"):
+                            _expose_from_handle(k, v)
+                        else:
+                            g.expose(k, v)
+                elif hasattr(ret, "node_id"):
+                    _expose_from_handle("", ret)
+                else:
+                    if outputs:
+                        if len(outputs) != 1:
+                            raise ValueError(
+                                "Returning a single literal but multiple outputs are declared."
+                            )
+                        g.expose(outputs[0], ret)
+                    else:
+                        raise ValueError(
+                            "Returning a single literal but no output name is declared."
+                        )
+            return g
+
+        _build.__name__ = fn.__name__
+        _build.build = _build  # alias
+        _build.graph_name = name
+        _build.version = version
+
+        def _spec():
+            g = _build()
+            return g.spec
+
+        _build.spec = _spec
+
+        def _io():
+            g = _build()
+            return g.io_signature()
+
+        _build.io = _io
+
+        # ---- Register graph + optional agent ----
+        hub = current_registry()
+        if hub is not None:
+            # Prefer registering the FACTORY, not a single built instance
+            # fallback: register a concrete instance now
+            hub.register(nspace="graph", name=name, version=version, obj=_build())
+
+            if agent:
+                # we will have agent API later, now just register a graph as agent
+                agent_id = agent
+                hub.register(nspace="agent", name=agent_id, version=version, obj=_build())
+
+        return _build
+
+    return _wrap

aethergraph/core/graph/interpreter.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..execution.retry_policy import RetryPolicy
+from ..runtime.runtime_env import RuntimeEnv
+from .task_graph import TaskGraph
+from .task_node import TaskNodeRuntime
+
+# Public ContextVar for current runtime environment
+_INTERP_CTX: ContextVar[Interpreter | None] = ContextVar("_INTERP_CTX", default=None)
+
+
+class SimpleNS:
+    """
+    Lightweight attribute-access wrapper for a dict.
+    Used as a 'handle' for tool nodes during graph build and also as a thin
+    outputs view at runtime. Must carry node_id so the scheduler can target it.
+    """
+
+    __slots__ = ("_data", "_node_id")
+
+    def __init__(self, d: dict[str, Any] | None = None, *, node_id: str | None = None):
+        self._data = dict(d or {})
+        self._node_id = node_id  # may be None for plain dict-like use
+
+    # ---- Introspection ----
+    @property
+    def node_id(self) -> str | None:
+        return self._node_id
+
+    def has_node(self) -> bool:
+        return self._node_id is not None
+
+    # ---- Dict-ish API ----
+    def to_dict(self) -> dict[str, Any]:
+        # do NOT include node_id in the payload view
+        return dict(self._data)
+
+    def get(self, name, default=None):
+        return self._data.get(name, default)
+
+    def __getitem__(self, key: str):
+        return self._data[key]
+
+    def __getattr__(self, name: str):
+        try:
+            return self._data[name]
+        except KeyError:
+            raise AttributeError(f"No such attribute: {name}") from None
+
+    def __repr__(self):
+        nid = f" node_id={self._node_id}" if self._node_id else ""
+        return f"SimpleNS({self._data!r}{nid})"
+
+    # ---- Builder-time ref helpers ----
+    def ref(self, *path: str) -> dict[str, Any]:
+        """
+        Return a binding-ref dict usable as an input to another node during build:
+            handle.ref("result")  -> {'_type':'ref','from':<node_id>,'path':['result']}
+        If no path is given, refers to the entire outputs dict.
+        """
+        if not self._node_id:
+            raise RuntimeError("Cannot create ref(): handle has no node_id (not a tool handle?)")
+        return {"_type": "ref", "from": self._node_id, "path": list(path or [])}
+
+    def on(self, key: str) -> dict[str, Any]:
+        """Alias for ref(key)."""
+        return self.ref(key)
+
+
+class AwaitableResult:
+    """Lightweight awaitable wrapper for a result value."""
+
+    def __init__(self, coro: Callable[[], Any], *, node_id: str | None = None):
+        self._coro = coro
+        self.node_id = node_id
+
+    def __await__(self):
+        return self._coro().__await__()
+
+
+@dataclass
+class Interpreter:
+    """Binds a TaskGraph to a scheduler, let tools add+run nodes on the fly."""
+
+    graph: TaskGraph
+    env: RuntimeEnv
+    retry: RetryPolicy = field(default_factory=RetryPolicy)
+    max_concurrency: int = 1
+
+    def __post_init__(self):
+        from ..execution.forward_scheduler import ForwardScheduler
+
+        # get logger from env's container
+        from ..runtime.runtime_services import current_logger_factory
+
+        logger = current_logger_factory().for_scheduler()
+
+        self.scheduler = ForwardScheduler(
+            self.graph, self.env, self.retry, max_concurrency=self.max_concurrency, logger=logger
+        )
+
+    # NEW: convenience pass-through
+    def add_listener(self, cb):
+        self.scheduler.add_listener(cb)
+
+    # NEW: run the whole plan (mirrors ForwardScheduler.run)
+    async def run(self):
+        """Run the entire graph to completion."""
+        return await self.scheduler.run()
+
+    def enter(self):
+        """Enter the interpreter context."""
+
+        class _Guard:
+            def __init__(_g, interp: Interpreter):
+                _g.interp = interp
+                _g.token = None
+
+            def __enter__(_g):
+                _g.token = _INTERP_CTX.set(_g.interp)
+                return _g.interp
+
+            def __exit__(_g, exc_type, exc_val, exc_tb):
+                """Exit the interpreter context.
+                Args:
+                    exc_type, exc_val, exc_tb: exception info if any
+                """
+                _INTERP_CTX.reset(_g.token)
+
+        return _Guard(self)
+
+    async def run_one(self, node: TaskNodeRuntime) -> dict[str, Any]:
+        """Run a single node by ID, return its outputs."""
+        return await self.scheduler.run_one(node)
+
+
+# Convenience helpers
+def current_interpreter() -> Interpreter | None:
+    """Get the current interpreter from context, or None if not in one."""
+    return _INTERP_CTX.get()

aethergraph/core/graph/node_handle.py

@@ -0,0 +1,33 @@
+from dataclasses import dataclass
+
+from .graph_refs import ref as _ref
+
+
+@dataclass
+class NodeHandle:
+    """A handle to a node's outputs in the graph.
+    Allows access to outputs via attribute or key.
+    """
+
+    node_id: str
+    output_keys: list[str]
+
+    def __getattr__(self, name: str) -> dict[str, str]:
+        """Access output by attribute, e.g. node.output_key"""
+        # Allow handle.path or handle.analysis -> Ref
+        if name in self.output_keys:
+            return _ref(self.node_id, name)
+        raise AttributeError(f"NodeHandle has no output '{name}'")
+
+    def __getitem__(self, key: str) -> dict[str, str]:
+        """Access output by key, e.g. node["output_key"]"""
+        # Allow handle["path"] or handle["analysis"] -> Ref
+        if key in self.output_keys:
+            return _ref(self.node_id, key)
+        raise KeyError(f"NodeHandle has no output '{key}'")
+
+    def tuple(self, n: int):
+        return [_ref(self.node_id, f"out{i}") for i in range(n)]
+
+    def unpack(self, *names: str):
+        return [_ref(self.node_id, name) for name in names]

aethergraph/core/graph/node_spec.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class NodeType(str, Enum):
+    TOOL = "tool"
+    LLM = "llm"
+    HUMAN = "human"
+    ROBOT = "robot"
+    CUSTOM = "custom"
+
+
+@dataclass
+class NodeEvent:
+    run_id: str
+    graph_id: str
+    node_id: str
+    status: str  # one of NodeStatus
+    outputs: dict[str, Any]
+    timestamp: float  # event time (time.time())
+
+
+@dataclass
+class TaskNodeSpec:
+    node_id: str
+    type: str | NodeType  # one of NodeType
+    logic: str | callable | None = None
+    dependencies: list[str] = field(default_factory=list)
+    inputs: dict[str, Any] = field(default_factory=dict)  # static inputs
+
+    expected_input_keys: list[str] = field(default_factory=list)
+    expected_output_keys: list[str] = field(default_factory=lambda: ["result"])
+    output_keys: list[str] = field(default_factory=lambda: ["result"])
+
+    # Allowed if it's *static* condition -- NOT IMPLEMENTED YET
+    condition: bool | dict[str, Any] | callable[[dict[str, Any]], bool] = True
+
+    metadata: dict[str, Any] = field(default_factory=dict)
+    reads: set[str] = field(default_factory=set)  # state keys to read
+    writes: set[str] = field(default_factory=set)  # state keys to write
+
+    tool_name: str | None = None  # used for logging/monitoring
+    tool_version: str | None = None  # used for logging/monitoring

aethergraph/core/graph/node_state.py

@@ -0,0 +1,63 @@
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+NodeWaitingKind = Literal["human", "robot", "external", "time", "event"]
+
+
+class NodeStatus:
+    PENDING = "PENDING"
+    RUNNING = "RUNNING"
+    DONE = "DONE"
+    FAILED = "FAILED"
+    SKIPPED = "SKIPPED"
+    FAILED_TIMEOUT = "FAILED_TIMEOUT"
+    WAITING_HUMAN = "WAITING_HUMAN"
+    WAITING_ROBOT = "WAITING_ROBOT"
+    WAITING_EXTERNAL = "WAITING_EXTERNAL"
+    WAITING_TIME = "WAITING_TIME"
+    WAITING_EVENT = "WAITING_EVENT"
+
+    @classmethod
+    def from_kind(cls, kind: NodeWaitingKind) -> str:
+        """Map waiting kind to status."""
+        return {
+            "human": cls.WAITING_HUMAN,
+            "approval": cls.WAITING_HUMAN,
+            "user_approval": cls.WAITING_HUMAN,  # alias to keep backward compatibility
+            "user_input": cls.WAITING_HUMAN,
+            "user_files": cls.WAITING_HUMAN,
+            "robot": cls.WAITING_ROBOT,
+            "external": cls.WAITING_EXTERNAL,
+            "time": cls.WAITING_TIME,
+            "event": cls.WAITING_EVENT,
+        }[kind]
+
+    @classmethod
+    def is_waiting(cls, status: str) -> bool:
+        return status.startswith("WAITING_")
+
+
+TERMINAL_STATES = {NodeStatus.DONE, NodeStatus.FAILED, NodeStatus.SKIPPED}
+WAITING_STATES = {
+    NodeStatus.WAITING_HUMAN,
+    NodeStatus.WAITING_ROBOT,
+    NodeStatus.WAITING_EXTERNAL,
+    NodeStatus.WAITING_TIME,
+    NodeStatus.WAITING_EVENT,
+}
+
+
+@dataclass
+class TaskNodeState:
+    status: NodeStatus = NodeStatus.PENDING
+    outputs: dict[str, any] = field(default_factory=dict)
+    error: str | None = None
+    attempts: int = 0
+    next_wakeup_at: str | None = None  # ISO timestamp
+    wait_token: str | None = None  # for external wait/resume with Continuation
+    wait_spec: dict[str, Any] | None = None  # spec for waiting (kind, channel, meta, etc.)
+
+    @property
+    def output(self):
+        # convenience for single-output nodes
+        return self.outputs.get("result")