aethergraph 0.1.0a1__py3-none-any.whl

aethergraph/core/graph/task_node.py

@@ -0,0 +1,82 @@
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any
+
+from .node_spec import TaskNodeSpec
+from .node_state import NodeStatus, TaskNodeState
+
+
+@dataclass
+class TaskNodeRuntime:
+    spec: TaskNodeSpec
+    state: TaskNodeState
+    _parent_graph: Any  # back-reference to parent graph
+
+    # ---- Spec pass-through ----
+    @property
+    def node_id(self) -> str:
+        return self.spec.node_id
+
+    @property
+    def type(self) -> str:
+        return self.spec.type
+
+    @property
+    def logic(self) -> Any:
+        return self.spec.logic
+
+    @property
+    def dependencies(self) -> list[str]:
+        return self.spec.dependencies
+
+    @property
+    def inputs(self) -> dict[str, Any]:
+        return self.spec.inputs
+
+    @property
+    def expected_input_keys(self) -> list[str]:
+        return self.spec.expected_input_keys
+
+    @property
+    def expected_output_keys(self) -> list[str]:
+        return self.spec.output_keys
+
+    @property
+    def condition(self) -> Any:
+        return self.spec.condition
+
+    @property
+    def metadata(self) -> dict[str, Any]:
+        return self.spec.metadata
+
+    @property
+    def tool_name(self) -> str | None:
+        return self.spec.tool_name
+
+    @property
+    def tool_version(self) -> str | None:
+        return self.spec.tool_version
+
+    # ---- State pass-through ----
+    @property
+    def status(self) -> NodeStatus:
+        return self.state.status
+
+    @property
+    def outputs(self) -> dict[str, Any]:
+        return self.state.outputs
+
+    @property
+    def output(self) -> Any:
+        return self.state.output
+
+    # --- Compat helpers ---
+    def allow(self, reads: Iterable[str] | None, writes: Iterable[str] | None) -> "TaskNodeRuntime":
+        """Return ad *new* spec via a patch rather than mutating in place."""
+        patch = {"node_id": self.node_id}
+        if reads:
+            patch["reads_add"] = list(reads)
+        if writes:
+            patch["writes_add"] = list(writes)
+        self._parent_graph.add_acl_patch(patch)
+        return self

aethergraph/core/graph/utils.py

@@ -0,0 +1,37 @@
+import inspect
+from typing import Any
+
+
+# ---------- helpers for printing and debugging ----------
+def _short(x: Any, maxlen: int = 42) -> str:
+    """Shorten a string representation to maxlen, adding ellipsis if needed."""
+    s = str(x)
+    return s if len(s) <= maxlen else s[: maxlen - 1] + "…"
+
+
+def _status_label(s: Any) -> str:
+    """Return a string label for a status value.
+
+    E.g., if s is an Enum-like object with a .name attribute, return that.
+    """
+    # Accept Enum-like (with .name), strings, or None
+    if s is None:
+        return "-"
+    return getattr(s, "name", str(s))
+
+
+def _logic_label(logic: Any) -> str:
+    """Return a string label for a logic value.
+
+    E.g., if logic is a function, return its module and name.
+    """
+    # Show a dotted path when possible; fall back to repr/str
+    if isinstance(logic, str):
+        return logic
+    # Unwrap @tool proxies if present
+    impl = getattr(logic, "__aether_impl__", logic)
+    if inspect.isfunction(impl) or inspect.ismethod(impl):
+        mod = getattr(impl, "__module__", None) or ""
+        name = getattr(impl, "__name__", None) or "tool"
+        return f"{mod}.{name}".strip(".")
+    return _short(repr(logic), 80)

aethergraph/core/graph/visualize.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+_STATUS_COLOR = {
+    "PENDING": "#d3d3d3",
+    "RUNNING": "#ffd966",
+    "DONE": "#b6d7a8",
+    "FAILED": "#e06666",
+    "FAILED_TIMEOUT": "#e69138",
+    "SKIPPED": "#cccccc",
+    "WAITING_HUMAN": "#9fc5e8",
+    "WAITING_ROBOT": "#9fc5e8",
+    "WAITING_EXTERNAL": "#9fc5e8",
+    "WAITING_TIME": "#9fc5e8",
+    "WAITING_EVENT": "#9fc5e8",
+}
+
+_NODE_SHAPE = {
+    "tool": "box",
+    "llm": "component",
+    "human": "oval",
+    "robot": "hexagon",
+    "custom": "box3d",
+}
+
+
+def _safe_get(d, key, default=None):
+    try:
+        return d.get(key, default)
+    except Exception:
+        return default
+
+
+def _escape(s: str) -> str:
+    return str(s).replace('"', r"\"")
+
+
+def _fmt_multiline(*lines):
+    return "\\n".join(str(x) for x in lines if x is not None and str(x) != "")
+
+
+@dataclass
+class _VizConfig:
+    rankdir: str = "LR"
+    fontname: str = "Inter,Helvetica,Arial,sans-serif"
+    fontsize: int = 11
+    show_io_brief: bool = True
+    show_logic: bool = True
+    dashed_control_deps: bool = True
+
+
+# === Add these methods onto TaskGraph ========================================
+
+
+def to_dot(self, cfg: _VizConfig | None = None) -> str:
+    """
+    Build a Graphviz DOT string of the graph with status-aware coloring and
+    dashed control-deps (if present in node.metadata['control_deps']).
+    """
+    cfg = cfg or _VizConfig()
+    lines = []
+    L = lines.append
+
+    L("digraph TaskGraph {")
+    L(f"  rankdir={cfg.rankdir};")
+    L(f'  graph [fontname="{cfg.fontname}"];')
+    L(
+        f'  node  [fontname="{cfg.fontname}", fontsize={cfg.fontsize}, style="rounded,filled", shape=box];'
+    )
+    L(f'  edge  [fontname="{cfg.fontname}", fontsize={cfg.fontsize}];')
+
+    # (optional) graph IO summary as a note
+    try:
+        io_lines = self.spec.io_summary_lines() if cfg.show_io_brief else []
+    except Exception:
+        io_lines = []
+    if io_lines:
+        label = _escape(_fmt_multiline("IO", *io_lines))
+        L('  subgraph cluster_io { style=dashed; color="#cccccc"; label="";')
+        L(
+            f'    io_summary [shape=note, style="rounded,filled", fillcolor="#f7f7f7", label="{label}"];'
+        )
+        L("  }")
+
+    # nodes
+    for node_id, node in self.spec.nodes.items():
+        # Node attributes
+        status = _safe_get(self.state.node_status, node_id, "PENDING") or "PENDING"
+        fill = _STATUS_COLOR.get(status, "#d3d3d3")
+        ntype = getattr(node, "node_type", None)
+        shape = _NODE_SHAPE.get(str(ntype).lower() if ntype else "", "box")
+
+        # Label: id + type/status (+ logic)
+        logic = getattr(node, "logic", None)
+        logic_s = None
+        if cfg.show_logic and logic is not None:
+            logic_s = (
+                logic
+                if isinstance(logic, str)
+                else getattr(logic, "__name__", type(logic).__name__)
+            )
+            # shorten registry path a bit
+            if isinstance(logic_s, str) and logic_s.startswith("registry:"):
+                logic_s = logic_s.replace("registry:", "")
+
+        label = _escape(
+            _fmt_multiline(
+                f"{node_id}",
+                f"[{str(ntype).lower()}]" if ntype else None,
+                f"status: {status}",
+                logic_s,
+            )
+        )
+
+        L(f'  "{_escape(node_id)}" [shape={shape}, fillcolor="{fill}", label="{label}"];')
+
+    # edges (data/control)
+    for node_id, node in self.spec.nodes.items():
+        deps = getattr(node, "dependencies", []) or []
+        ctrl = set(_safe_get(getattr(node, "metadata", {}) or {}, "control_deps", []) or [])
+
+        for dep in deps:
+            style = "dashed" if (cfg.dashed_control_deps and dep in ctrl) else "solid"
+            color = "#999999" if style == "dashed" else "#555555"
+            L(f'  "{_escape(dep)}" -> "{_escape(node_id)}" [style={style}, color="{color}"];')
+
+    # (optional) Legend
+    L("  subgraph cluster_legend {")
+    L('    label="Legend"; style=dashed; color="#cccccc";')
+    L("    key_status [shape=plaintext, label=<")
+    L('      <TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="6">')
+    L('        <TR><TD COLSPAN="2"><B>Status Colors</B></TD></TR>')
+    for k, v in _STATUS_COLOR.items():
+        L(f'        <TR><TD>{k}</TD><TD BGCOLOR="{v}"> </TD></TR>')
+    L("      </TABLE>")
+    L("    >];")
+    L("    key_edge [shape=plaintext, label=<")
+    L('      <TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="6">')
+    L('        <TR><TD COLSPAN="2"><B>Edge Types</B></TD></TR>')
+    L('        <TR><TD>data dependency</TD><TD><FONT COLOR="#555555">solid</FONT></TD></TR>')
+    L('        <TR><TD>control dependency</TD><TD><FONT COLOR="#999999">dashed</FONT></TD></TR>')
+    L("      </TABLE>")
+    L("    >];")
+    L("  }")
+
+    L("}")
+    return "\n".join(lines)
+
+
+def visualize(
+    self,
+    outfile: str | None = None,
+    fmt: str = "svg",
+    view: bool = False,
+    cfg: _VizConfig | None = None,
+    return_dot: bool = False,
+) -> str:
+    """
+    Render or export the graph.
+
+    Args:
+        outfile: Path prefix without extension (e.g., 'out/graph').
+        fmt:     'svg' | 'png' | 'pdf' ...
+        view:    If True, open the rendered file (if possible).
+        cfg:     Visualization config (_VizConfig).
+        return_dot:
+            - If True, always return the raw DOT string so the user can paste
+              it into webgraphviz or other tools.
+            - If outfile is also provided, a .dot file will be exported to
+              `outfile + ".dot"` in addition to any rendering.
+
+    Returns:
+        - DOT string if return_dot=True
+        - Rendered file path if rendering was successful
+        - DOT string fallback if rendering fails
+    """
+    dot = self.to_dot(cfg)
+
+    dot_path = None
+    if outfile and return_dot:
+        dot_path = f"{outfile}.dot"
+        with open(dot_path, "w", encoding="utf-8") as f:
+            f.write(dot)
+        import logging
+
+        log = logging.getLogger("aethergraph.core.graph.visualize")
+        log.info(
+            f"DOT file written to: {dot_path}. View the graph at https://dreampuf.github.io/GraphvizOnline/"
+        )
+
+    if return_dot and (outfile is None):
+        # Only return DOT (no rendering)
+        return dot
+
+    try:
+        import graphviz
+
+        src = graphviz.Source(dot, format=fmt)
+        if outfile:
+            path = src.render(
+                outfile, view=view, cleanup=True
+            )  # This will also create outfile but without .dot extension?
+            # If return_dot, return DOT text (but still render the file)
+            return dot if return_dot else path
+        elif view:
+            # View only, no outfile
+            import tempfile
+
+            tmp = tempfile.mkstemp(prefix="taskgraph_", suffix=f".{fmt}")[1]
+            src.render(tmp[: -len(f".{fmt}")], view=True, cleanup=True)
+            return dot if return_dot else tmp
+    except Exception:
+        import logging
+
+        log = logging.getLogger("aethergraph.core.graph.visualize")
+        log.warning("Graph rendering failed; returning DOT string instead.")
+        pass
+
+    return dot
+
+
+def ascii_overview(self) -> str:
+    """
+    Minimal text view: one line per node with deps and status.
+    """
+    lines = []
+    for node_id, node in self.spec.nodes.items():
+        status = _safe_get(self.state.node_status, node_id, "PENDING") or "PENDING"
+        deps = getattr(node, "dependencies", []) or []
+        ntype = getattr(node, "node_type", "tool")
+        logic = getattr(node, "logic", None)
+        logic_s = (
+            (logic if isinstance(logic, str) else getattr(logic, "__name__", type(logic).__name__))
+            if logic
+            else ""
+        )
+        lines.append(f"- {node_id} [{ntype} | {status}] deps={deps} logic={logic_s}")
+    return "\n".join(lines)

aethergraph/core/runtime/ad_hoc_context.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+import uuid
+
+from aethergraph.core.runtime.execution_context import ExecutionContext
+from aethergraph.core.runtime.graph_runner import _build_env
+
+
+# Ad-hoc node for temporary tasks
+@dataclass
+class _AdhocNode:
+    node_id: str = "adhoc"
+    tool_name: str | None = None
+    tool_version: str | None = None
+
+
+async def build_adhoc_context(
+    *,
+    run_id: str | None = None,
+    graph_id: str = "adhoc",
+    node_id: str = "adhoc",
+    **rt_overrides,
+) -> ExecutionContext:
+    # Owner can be anything with max_concurrency; we won't really schedule
+    class _Owner:
+        max_concurrency = rt_overrides.get("max_concurrency", 1)
+
+    env, retry, max_conc = await _build_env(_Owner(), inputs={}, **rt_overrides)
+
+    env.run_id = run_id or f"adhoc-{uuid.uuid4().hex[:8]}"
+    env.graph_id = graph_id
+
+    node = _AdhocNode(node_id=node_id)
+    exe_ctx = env.make_ctx(node=node, resume_payload=None)
+    node_ctx = exe_ctx.create_node_context(node)
+
+    return node_ctx
+
+
+@asynccontextmanager
+async def open_session(
+    *,
+    run_id: str | None = None,
+    graph_id: str = "adhoc",
+    node_id: str = "adhoc",
+    **rt_overrides,
+):
+    """
+    Open an 'adhoc' context that behaves like a NodeContext, without a real graph run.
+    Advanced / scripting use only.
+    """
+    ctx = await build_adhoc_context(
+        run_id=run_id, graph_id=graph_id, node_id=node_id, **rt_overrides
+    )
+    try:
+        yield ctx
+    finally:
+        # optional: flush / close memory, artifacts, etc.
+        pass

aethergraph/core/runtime/base_service.py

@@ -0,0 +1,153 @@
+"""Base services are used for external context services and other common patterns.
+Here we register service in the main runtime, and provide base classes for
+TODO: confirm that external services runs with the main event loop locally, not the sidecar loop, such that asyncio.locks work as expected.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .node_context import NodeContext
+
+__all__ = [
+    "AsyncRWLock",
+    "BaseContextService",
+    "Service",
+    "maybe_await",
+]
+
+
+class _ServiceHandle:
+    """
+    A callable, transparent handle around a bound service.
+    - Attribute access delegates to the underlying service.
+    - Calling with no args returns the service (ergonomic parity with built-ins).
+    - Calling with args forwards to service.__call__ if present.
+    """
+
+    __slots__ = ("_name", "_svc")
+
+    def __init__(self, name: str, bound_service: object):
+        self._svc = bound_service
+        self._name = name
+
+    def __getattr__(self, attr):
+        return getattr(self._svc, attr)
+
+    def __call__(self, *args, **kwargs):
+        # No-arg call => return the service instance (consistent, non-surprising)
+        if not args and not kwargs:
+            return self._svc
+
+        # If the underlying service is callable, forward the call
+        if callable(self._svc):
+            return self._svc(*args, **kwargs)
+
+        raise TypeError(
+            f"Service '{self._name}' is not directly callable; "
+            "call with no arguments to get the service instance, "
+            "then invoke its methods."
+        )
+
+    def __repr__(self):
+        return f"<ServiceHandle {self._name}: {self._svc!r}>"
+
+
+async def maybe_await(x: Any) -> Any:
+    """If x is awaitable, await it; else return it directly."""
+    if asyncio.iscoroutine(x) or isinstance(x, Awaitable):
+        return await x
+    return x
+
+
+class AsyncRWLock:
+    """Simple async RW lock: many readers or one writer."""
+
+    def __init__(self):
+        self._readers = 0
+        self._r_lock = asyncio.Lock()
+        self._w_lock = asyncio.Lock()
+
+    async def read(self):
+        lock = self
+
+        class _Guard:
+            async def __aenter__(self):
+                async with lock._r_lock:
+                    lock._readers += 1
+                    if lock._readers == 1:
+                        await lock._w_lock.acquire()
+
+            async def __aexit__(self, exc_type, exc, tb):
+                async with lock._r_lock:
+                    lock._readers -= 1
+                    if lock._readers == 0:
+                        lock._w_lock.release()
+
+        return _Guard()
+
+    async def write(self):
+        return self._w_lock
+
+
+class BaseContextService:
+    """
+        Batteries-included base for context services.
+    - Lifecycle: start/close (async)
+    - Binding: bind(context) returns a context-aware handle (default: self with ContextVar)
+    - Concurrency: critical() async mutex, AsyncRWLock for R/W scenarios
+    - Utilities: run_blocking() for CPU/IO-bound sync functions
+    """
+
+    _current_ctx: ContextVar = ContextVar("_aeg_ctx", default=None)
+
+    def __init__(self) -> None:
+        self._lock = asyncio.Lock()
+        self._closing = False
+
+    # ---------- lifecycle ----------
+    async def start(self) -> None:
+        """Async startup hook."""
+        return None
+
+    async def close(self) -> None:
+        """Async shutdown hook."""
+        self._closing = True
+        return None
+
+    # ---------- binding ----------
+    def bind(self, *, context: NodeContext) -> BaseContextService:
+        """Return a context-bound handle to this service."""
+        self._current_ctx.set(context)
+        return self
+
+    def ctx(self) -> NodeContext:
+        ctx = self._current_ctx.get()
+        if ctx is None:
+            raise RuntimeError("No context bound to this service. Call bind(context) first.")
+        return ctx
+
+    # ---------- concurrency ----------
+    def critical(self):
+        """Decorator for async critical section (mutex)."""
+
+        def deco(fn: Callable[..., Any]) -> Any:
+            async def wrapped(*a, **kw):
+                async with self._lock:
+                    return await maybe_await(fn(*a, **kw))
+
+            return wrapped
+
+        return deco
+
+    async def run_blocking(self, fn: Callable[..., Any], *args, **kwargs) -> Any:
+        """Run a blocking function in a thread pool."""
+        return await asyncio.to_thread(fn, *args, **kwargs)
+
+
+# Alias for ergonomics
+Service = BaseContextService

aethergraph/core/runtime/bind_adapter.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+__all__ = ["BindAdapter"]
+
+
+class BindAdapter:
+    """
+    Wrap any object and make it context-bindable.
+    Convention: if a wrapped method wants NodeContext, accept kwarg `_ctx`.
+    """
+
+    def __init__(self, obj: Any):
+        self._obj = obj
+
+    def bind(self, *, context):
+        obj = self._obj
+        ctx = context
+
+        class Bound:
+            def __getattr__(self, name: str):
+                attr = getattr(obj, name)
+                if callable(attr):
+                    if asyncio.iscoroutinefunction(attr):
+
+                        async def aw(*a, **k):
+                            k.setdefault("_ctx", ctx)
+                            return await attr(*a, **k)
+
+                        return aw
+                    else:
+
+                        def sw(*a, **k):
+                            k.setdefault("_ctx", ctx)
+                            return attr(*a, **k)
+
+                        return sw
+                return attr
+
+        return Bound()

aethergraph/core/runtime/bound_memory.py

@@ -0,0 +1,69 @@
+from typing import Any
+
+from aethergraph.services.memory.facade import MemoryFacade
+from aethergraph.services.memory.io_helpers import Value
+
+# TODO: Deprecate this adapter in favor of direct MemoryFacade usage in runtime contexts.
+
+
+class BoundMemoryAdapter:
+    """Minimal adapter to preserve ctx.mem().* API while delegating to MemoryFacade."""
+
+    def __init__(self, mem: MemoryFacade, defaults: dict[str, Any]):
+        self._mem = mem
+        self._defaults = defaults
+
+    async def record(
+        self,
+        *,
+        kind: str,
+        text: str | None = None,
+        severity: int = 2,
+        stage: str | None = None,
+        tags: list[str] | None = None,
+        entities: list[str] | None = None,
+        metrics: dict[str, Any] | None = None,
+        inputs_ref: dict[str, Any] | None = None,
+        outputs_ref: dict[str, Any] | None = None,
+        sources: list[str] | None = None,
+        signal: float | None = None,
+    ):
+        base = dict(
+            **self._defaults,
+            kind=kind,
+            stage=stage,
+            severity=severity,
+            tags=tags or [],
+            entities=entities or [],
+            inputs_ref=inputs_ref,
+            outputs_ref=outputs_ref,
+            signal=signal,
+        )
+        return await self._mem.record_raw(base=base, text=text, metrics=metrics, sources=sources)
+
+    async def user(self, text: str):
+        return await self.record(kind="user_msg", text=text, stage="observe")
+
+    async def assistant(self, text: str):
+        return await self.record(kind="assistant_msg", text=text, stage="act")
+
+    async def write_result(
+        self,
+        *,
+        topic: str,
+        inputs: list[Value] | None = None,
+        outputs: list[Value] | None = None,
+        tags: list[str] | None = None,
+        metrics: dict[str, float] | None = None,
+        message: str | None = None,
+        severity: int = 3,
+    ):
+        return await self._mem.write_result(
+            topic=topic,
+            inputs=inputs or [],
+            outputs=outputs or [],
+            tags=tags,
+            metrics=metrics,
+            message=message,
+            severity=severity,
+        )