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

aethergraph/core/graph/graph_builder.py

@@ -22,8 +22,12 @@ def current_builder() -> GraphBuilder | None:
 class GraphBuilder:
     _auto_counter = itertools.count(1)
 
-    def __init__(self, *, name: str = "default_graph"):
-        self.spec = TaskGraphSpec(graph_id=name, nodes={}, meta={})
+    def __init__(
+        self, *, name: str = "default_graph", agent_id: str | None = None, app_id: str | None = None
+    ):
+        self.spec = TaskGraphSpec(
+            graph_id=name, nodes={}, meta={}, agent_id=agent_id, app_id=app_id
+        )
         self.graph = TaskGraph(spec=self.spec)
         self.graph.ensure_inputs_node()
 
@@ -181,9 +185,9 @@ class GraphBuilder:
 
 
 @contextmanager
-def graph(*, name: str = "default_graph"):
+def graph(*, name: str = "default_graph", agent_id: str | None = None, app_id: str | None = None):
     """Context manager that yields a GraphBuilder to build a TaskGraph."""
-    builder = GraphBuilder(name=name)
+    builder = GraphBuilder(name=name, agent_id=agent_id, app_id=app_id)
     token = _GRAPH_CTX.set(builder)
     try:
         yield builder.graph

aethergraph/core/graph/graph_fn.py

@@ -2,8 +2,13 @@ from __future__ import annotations
 
 from collections.abc import Callable
 import inspect
+from typing import Any
 
 from aethergraph.core.runtime.run_registration import RunRegistrationGuard
+from aethergraph.services.registry.agent_app_meta import (
+    build_agent_meta,
+    build_app_meta,
+)
 
 from ..execution.retry_policy import RetryPolicy
 from ..runtime.runtime_env import RuntimeEnv
@@ -22,6 +27,8 @@ class GraphFunction:
         inputs: list[str] | None = None,
         outputs: list[str] | None = None,
         version: str = "0.1.0",
+        agent_id: str | None = None,
+        app_id: str | None = None,
     ):
         self.graph_id = name
         self.name = name
@@ -33,6 +40,8 @@ class GraphFunction:
         self.last_graph = None
         self.last_context = None
         self.last_memory_snapshot = None
+        self.agent_id = agent_id
+        self.app_id = app_id
 
     async def run(
         self,
@@ -62,7 +71,7 @@ class GraphFunction:
         )
         node_ctx = runtime_ctx.create_node_context(node=node_spec)
 
-        with graph(name=self.graph_id) as G:
+        with graph(name=self.graph_id, agent_id=self.agent_id, app_id=self.app_id) as G:
             interp = Interpreter(G, env, retry=retry, max_concurrency=max_concurrency)
             run_id = env.run_id
 
@@ -192,28 +201,160 @@ def graph_fn(
     inputs: list[str] | None = None,
     outputs: list[str] | None = None,
     version: str = "0.1.0",
-    agent: str | None = None,  # if agent is set, register this graph fn as an agent with given name
+    *,
+    entrypoint: bool = False,
+    flow_id: str | None = None,
+    tags: list[str] | None = None,
+    as_agent: dict[str, Any] | None = None,
+    as_app: dict[str, Any] | None = None,
 ) -> Callable[[Callable], GraphFunction]:
-    """Decorator to define a graph function."""
+    """
+    Decorator to define a graph function and optionally register it as an agent or app.
+
+    This decorator wraps a Python function as a `GraphFunction`, enabling it to be executed
+    as a node-based graph with runtime context, retry policy, and concurrency controls.
+    It also supports rich metadata registration for agent and app discovery.
 
-    def decorator(fn: Callable):
-        gf = GraphFunction(name=name, fn=fn, inputs=inputs, outputs=outputs, version=version)
-        # Register in registry if given
+    Examples:
+        Basic usage:
+        ```python
+        @graph_fn(
+            name="add_numbers",
+            inputs=["a", "b"],
+            outputs=["sum"],
+        )
+        async def add_numbers(a: int, b: int):
+            return {"sum": a + b}
+        ```
+
+        Registering as an agent with metadata:
+        ```python
+        @graph_fn(
+            name="chat_agent",
+            inputs=["message", "files", "context_refs", "session_id", "user_meta"],
+            outputs=["response"],
+            as_agent={
+                "id": "chatbot",
+                "title": "Chat Agent",
+                "description": "Conversational AI agent.",
+                "mode": "chat_v1",
+                "icon": "chat",
+                "tags": ["chat", "nlp"],
+            },
+        )
+        async def chat_agent(...):
+            ...
+        ```
+
+        Registering as an app:
+        ```python
+        @graph_fn(
+            name="summarizer",
+            inputs=[],
+            outputs=["summary"],
+            as_app={
+                "id": "summarizer-app",
+                "name": "Text Summarizer",
+                "description": "Summarizes input text.",
+                "category": "Productivity",
+                "tags": ["nlp", "summary"],
+            },
+        )
+        async def summarizer():
+            ...
+        ```
+
+    Args:
+        name: Unique name for the graph function.
+        inputs: List of input parameter names. If `as_agent` is provided with `mode="chat_v1"`,
+            this must match `["message", "files", "context_refs", "session_id", "user_meta"]`.
+        outputs: List of output keys returned by the function.
+        version: Version string for the graph function (default: "0.1.0").
+        entrypoint: If True, marks this graph as the main entrypoint for a flow.  [Currently unused]
+        flow_id: Optional flow identifier for grouping related graphs.
+        tags: List of string tags for discovery and categorization.
+        as_agent: Optional dictionary defining agent metadata. Used when running through Aethergraph UI. See additional information below.
+        as_app: Optional dictionary defining app metadata. Used when running through Aethergraph UI. See additional information below.
+
+    Returns:
+        Callable: A decorator that wraps the function as a `GraphFunction` and registers it
+        in the runtime registry, with agent/app metadata if provided.
+
+    Notes:
+        - as_agent and as_app are not needed to define a graph; they are only for registration purposes for use in Aethergraph UI.
+        - When registering as an agent, the `as_agent` dictionary should include at least an "id" key.
+        - When registering as an app, the `as_app` dictionary should include at least an "id" key.
+        - The decorated function can be either synchronous or asynchronous.
+        - Fields `inputs` and `outputs` are can be inferred from the function signature if not explicitly provided, but it's recommended to declare them for clarity.
+    """
+
+    def decorator(fn: Callable) -> GraphFunction:
+        agent_id = as_agent.get("id") if as_agent else None
+        app_id = as_app.get("id") if as_app else None
+        gf = GraphFunction(
+            name=name,
+            fn=fn,
+            inputs=inputs,
+            outputs=outputs,
+            version=version,
+            agent_id=agent_id,
+            app_id=app_id,
+        )
         registry = current_registry()
 
-        if registry is not None:
+        if registry is None:
+            # no registry available, just return the graph function
+            return gf
+
+        base_tags = tags or []
+        graph_meta: dict[str, Any] = {
+            "kind": "graphfn",
+            "entrypoint": entrypoint,
+            "flow_id": flow_id or name,
+            "tags": base_tags,
+        }
+
+        registry.register(
+            nspace="graphfn",
+            name=name,
+            version=version,
+            obj=gf,
+            meta=graph_meta,
+        )
+
+        # Register as agent if requested
+        # 4Agent meta (if any)
+        agent_meta = build_agent_meta(
+            graph_name=name,
+            version=version,
+            graph_meta=graph_meta,
+            agent_cfg=as_agent,
+        )
+        if agent_meta is not None:
+            registry.register(
+                nspace="agent",
+                name=agent_meta["id"],
+                version=version,
+                obj=gf,
+                meta=agent_meta,
+            )
+
+        # 5) App meta (if any)
+        app_meta = build_app_meta(
+            graph_name=name,
+            version=version,
+            graph_meta=graph_meta,
+            app_cfg=as_app,
+        )
+        if app_meta is not None:
             registry.register(
-                nspace="graphfn",
-                name=name,
+                nspace="app",
+                name=app_meta["id"],
                 version=version,
-                obj=gf,  # we register GraphFunction directly without spec -- graph function is already a runtime object
+                obj=gf,
+                meta=app_meta,
             )
 
-        if agent:
-            assert (
-                registry is not None
-            ), "No registry available to register agent, make sure to have a current_registry() set up."
-            registry.register(nspace="agent", name=agent, version=version, obj=gf)
         return gf
 
     return decorator

aethergraph/core/graph/graph_spec.py

@@ -14,6 +14,8 @@ class TaskGraphSpec:
     io: IOSpec = field(default_factory=IOSpec)  # inputs/outputs
     bindings: IOBindings | None = None  # input/output bindings
     meta: dict[str, Any] = field(default_factory=dict)  # additional metadata
+    agent_id: str | None = None  # for agent-invoked runs
+    app_id: str | None = None  # for app-invoked runs
 
     def canonical(self) -> str:
         return f"graph:{self.graph_id}@{self.version}"
@@ -37,6 +39,12 @@ class TaskGraphSpec:
             f"outputs:  {_fmt_outputs_map(self.outputs)}",
         ]
 
+    def __items__(self, key: str) -> Any:
+        return getattr(self, key)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return getattr(self, key, default)
+
 
 @dataclass
 class GraphView:

aethergraph/core/graph/graphify.py

@@ -1,29 +1,103 @@
 from __future__ import annotations
 
 import inspect
+from typing import Any
+
+from aethergraph.services.registry.agent_app_meta import build_agent_meta, build_app_meta
 
 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
+    name="default_graph",
+    inputs=(),
+    outputs=None,
+    version="0.1.0",
+    *,
+    entrypoint: bool = False,
+    flow_id: str | None = None,
+    tags: list[str] | None = None,
+    as_agent: dict[str, Any] | None = None,
+    as_app: dict[str, Any] | 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()
+    Decorator to define a `TaskGraph` and optionally register it as an agent or app.
+
+    This decorator wraps a Python function as a `TaskGraph`, enabling it to be executed
+    as a node-based graph with runtime context, retry policy, and concurrency controls.
+    It also supports rich metadata registration for agent and app discovery.
+
+    Examples:
+        Basic usage:
+        ```python
+        @graphify(
+            name="add_numbers",
+            inputs=["a", "b"],
+            outputs=["sum"],
+        )
+        async def add_numbers(a: int, b: int):
+            return {"sum": a + b}
+        ```
+
+        Registering as an agent with metadata:
+        ```python
+        @graphify(
+            name="chat_agent",
+            inputs=["message", "files", "context_refs", "session_id", "user_meta"],
+            outputs=["response"],
+            as_agent={
+                "id": "chatbot",
+                "title": "Chat Agent",
+                "description": "Conversational AI agent.",
+                "mode": "chat_v1",
+                "icon": "chat",
+                "tags": ["chat", "nlp"],
+            },
+        )
+        async def chat_agent(...):
+            ...
+        ```
+
+        Registering as an app:
+        ```python
+        @graphify(
+            name="summarizer",
+            inputs=[],
+            outputs=["summary"],
+            as_app={
+                "id": "summarizer-app",
+                "name": "Text Summarizer",
+                "description": "Summarizes input text.",
+                "category": "Productivity",
+                "tags": ["nlp", "summary"],
+            },
+        )
+        async def summarizer():
+            ...
+        ```
+
+    Args:
+        name: Unique name for the graph function.
+        inputs: List of input parameter names. If `as_agent` is provided with `mode="chat_v1"`,
+            this must match `["message", "files", "context_refs", "session_id", "user_meta"]`.
+        outputs: List of output keys returned by the function.
+        version: Version string for the graph function (default: "0.1.0").
+        entrypoint: If True, marks this graph as the main entrypoint for a flow.  [Currently unused]
+        flow_id: Optional flow identifier for grouping related graphs.
+        tags: List of string tags for discovery and categorization.
+        as_agent: Optional dictionary defining agent metadata. Used when running through Aethergraph UI. See additional information below.
+        as_app: Optional dictionary defining app metadata. Used when running through Aethergraph UI. See additional information below.
+
+    Returns:
+        TaskGraph: A decorator that transforms a function into a TaskGraph with the specified configuration.
+
+    Notes:
+        - as_agent and as_app are not needed to define a graph; they are only for registration purposes for use in Aethergraph UI.
+        - When registering as an agent, the `as_agent` dictionary should include at least an "id" key.
+        - When registering as an app, the `as_app` dictionary should include at least an "id" key.
+        - The decorated function is a sync function (generate the TaskGraph), despite the underlying `@tool` can be async.
+        - Fields `inputs` and `outputs` are can be inferred from the function signature if not explicitly provided, but it's recommended to declare them for clarity.
     """
 
     def _wrap(fn):
@@ -41,7 +115,10 @@ def graphify(
             from .graph_builder import graph
             from .graph_refs import arg
 
-            with graph(name=name) as g:
+            agent_id = as_agent.get("id") if as_agent else None
+            app_id = as_app.get("id") if as_app else None
+
+            with graph(name=name, agent_id=agent_id, app_id=app_id) as g:
                 # declarations unchanged...
                 if isinstance(inputs, dict):
                     g.declare_inputs(required=[], optional=inputs)
@@ -52,7 +129,7 @@ def graphify(
                 injected_kwargs = {p: arg(p) for p in overlap}
 
                 # Run user body
-                ret = fn(**injected_kwargs)  # ← key line
+                ret = fn(**injected_kwargs)
 
                 # expose logic (fixed typo + single-output collapse)
                 def _is_ref(x):
@@ -112,16 +189,58 @@ def graphify(
         _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())
+
+        registry = current_registry()
+        if registry is None:
+            return _build
+
+        base_tags = tags or []
+        graph_meta: dict[str, Any] = {
+            "kind": "graph",
+            "entrypoint": entrypoint,
+            "flow_id": flow_id or name,
+            "tags": base_tags,
+        }
+
+        registry.register(
+            nspace="graph",
+            name=name,
+            version=version,
+            obj=_build(),
+            meta=graph_meta,
+        )
+
+        # Agent meta (if any)
+        agent_meta = build_agent_meta(
+            graph_name=name,
+            version=version,
+            graph_meta=graph_meta,
+            agent_cfg=as_agent,
+        )
+        if agent_meta is not None:
+            registry.register(
+                nspace="agent",
+                name=agent_meta["id"],
+                version=version,
+                obj=_build(),
+                meta=agent_meta,
+            )
+
+        # App meta (if any)
+        app_meta = build_app_meta(
+            graph_name=name,
+            version=version,
+            graph_meta=graph_meta,
+            app_cfg=as_app,
+        )
+        if app_meta is not None:
+            registry.register(
+                nspace="app",
+                name=app_meta["id"],
+                version=version,
+                obj=_build(),
+                meta=app_meta,
+            )
 
         return _build
 

aethergraph/core/graph/node_spec.py

@@ -39,8 +39,6 @@ class TaskNodeSpec:
     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

@@ -10,6 +10,7 @@ class NodeStatus:
     DONE = "DONE"
     FAILED = "FAILED"
     SKIPPED = "SKIPPED"
+    CANCELLED = "CANCELLED"
     FAILED_TIMEOUT = "FAILED_TIMEOUT"
     WAITING_HUMAN = "WAITING_HUMAN"
     WAITING_ROBOT = "WAITING_ROBOT"
@@ -56,6 +57,8 @@ class TaskNodeState:
     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.)
+    started_at: str | None = None  # ISO timestamp
+    finished_at: str | None = None  # ISO timestamp
 
     @property
     def output(self):

aethergraph/core/graph/task_graph.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from collections.abc import Iterable
 from dataclasses import asdict, dataclass, field, is_dataclass
+import datetime
 import inspect
 from typing import Any
 import uuid
@@ -21,6 +22,10 @@ def _dataclass_to_plain(d):
     return asdict(d) if is_dataclass(d) else d
 
 
+def _utc_ts() -> float:
+    return datetime.datetime.now(tz=datetime.timezone.utc).timestamp()
+
+
 @dataclass
 class TaskGraph:
     spec: TaskGraphSpec
@@ -412,10 +417,43 @@ class TaskGraph:
             "set_outputs() is not implemented yet. Use set_node_outputs() instead."
         )
 
+    # async def set_node_status(self, node_id: str, status: NodeStatus) -> None:
+    #     state = self.state.nodes.get(node_id)
+    #     if state.status is status:
+    #         return
+    #     state.status = status
+    #     self.state.rev += 1
+    #     await self._notify_status_change(node_id)
+
     async def set_node_status(self, node_id: str, status: NodeStatus) -> None:
         state = self.state.nodes.get(node_id)
-        if state.status is status:
+        if state is None:
+            raise KeyError(f"Unknown node_id: {node_id}")
+
+        # no-op if unchanged
+        if state.status is status or state.status == status:
             return
+
+        # --- timestamps ---
+
+        # 1) First time we go to RUNNING → set started_at (but don't overwrite on resume)
+        if status == NodeStatus.RUNNING and getattr(state, "started_at", None) is None:
+            state.started_at = _utc_ts()
+
+        # 2) Terminal states → set finished_at if not already set
+        TERMINAL_STATES = {
+            getattr(NodeStatus, "DONE", "DONE"),
+            getattr(NodeStatus, "FAILED", "FAILED"),
+            getattr(NodeStatus, "SKIPPED", "SKIPPED"),
+            getattr(NodeStatus, "CANCELLED", None) or getattr(NodeStatus, "CANCELED", None),
+        }
+        # filter out any Nones in case some names don't exist
+        TERMINAL_STATES = {s for s in TERMINAL_STATES if s is not None}
+
+        if status in TERMINAL_STATES and getattr(state, "finished_at", None) is None:
+            state.finished_at = _utc_ts()
+
+        # --- actual status change + rev bump ---
         state.status = status
         self.state.rev += 1
         await self._notify_status_change(node_id)

aethergraph/core/runtime/ad_hoc_context.py

@@ -17,12 +17,40 @@ class _AdhocNode:
 
 
 async def build_adhoc_context(
-    *,
     run_id: str | None = None,
     graph_id: str = "adhoc",
     node_id: str = "adhoc",
     **rt_overrides,
 ) -> ExecutionContext:
+    """
+    Build an ad-hoc execution context for running a single node outside of a scheduled graph.
+    This function creates a minimal runtime environment suitable for quick, one-off executions,
+    such as testing or interactive exploration. It generates a temporary run and graph context,
+    instantiates an ad-hoc node, and returns a node-specific execution context.
+    Examples:
+        Basic usage with default parameters:
+        ```python
+        node_ctx = await build_adhoc_context()
+        ```
+        Customizing the run and session IDs:
+        ```python
+        node_ctx = await build_adhoc_context(run_id="test-run", session_id="dev-session")
+        ```
+        Overriding runtime parameters:
+        ```python
+        node_ctx = await build_adhoc_context(max_concurrency=4)
+        ```
+    Args:
+        run_id: Optional string to uniquely identify this run. If not provided,
+            a random ID is generated.
+        session_id: Optional string to associate this context with a session.
+        graph_id: Identifier for the graph. Defaults to `"adhoc"`.
+        node_id: Identifier for the node. Defaults to `"adhoc"`.
+        **rt_overrides: Additional runtime overrides, such as `max_concurrency`.
+    Returns:
+        NodeExecutionContext: The execution context for the ad-hoc node, ready for use.
+    """
+
     # Owner can be anything with max_concurrency; we won't really schedule
     class _Owner:
         max_concurrency = rt_overrides.get("max_concurrency", 1)
@@ -41,15 +69,47 @@ async def build_adhoc_context(
 
 @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.
+    Open an ad-hoc session context for advanced or scripting use.
+
+    This asynchronous context manager yields a temporary context that mimics a `NodeContext`
+    without requiring a real graph run. It is intended for advanced scenarios where a lightweight,
+    ephemeral execution environment is needed, such as scripting, testing, or prototyping.
+
+    Examples:
+        Basic usage to open an ad-hoc session:
+        ```python
+        async with open_session() as ctx:
+            # Use ctx as you would a NodeContext
+            ...
+        ```
+
+        Overriding runtime parameters:
+        ```python
+        async with open_session(graph_id="mygraph", node_id="customnode", foo="bar") as ctx:
+            ...
+        ```
+
+    Args:
+        run_id: Optional unique identifier for the run. If None, a random or default value is used.
+        graph_id: Identifier for the graph context. Defaults to "adhoc".
+        node_id: Identifier for the node context. Defaults to "adhoc".
+        **rt_overrides: Arbitrary keyword arguments to override runtime context parameters.
+
+    Yields:
+        NodeContext: An ad-hoc context object suitable for advanced scripting or testing.
+
+    Raises:
+        Any exception raised during context construction or teardown will propagate.
+
+    Note:
+        This context does not persist state or artifacts beyond its lifetime. Use only for
+        non-production, ephemeral tasks.
     """
     ctx = await build_adhoc_context(
         run_id=run_id, graph_id=graph_id, node_id=node_id, **rt_overrides