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

aethergraph/core/graph/action_spec.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+JsonType = Literal["string", "number", "boolean", "object", "array"]
+
+
+@dataclass
+class IOSlot:
+    """
+    One input or output slot for a graph action.
+
+    - `type` is a coarse JSON-like type for LLM/tool matching.
+    """
+
+    name: str
+    type: JsonType | None = None
+    description: str | None = None
+    required: bool = True
+    default: Any | None = None
+
+
+@dataclass
+class ActionSpec:
+    """
+    Docstring for ActionSpec
+    """
+
+    name: str  # hunman name: usually the graph/graphfn name
+    ref: str  # canonical ref: e.g. "graph:mygraph:1.0.0"
+    kind: Literal["graph", "graphfn"]  # kind of action
+    version: str  # version string
+
+    inputs: list[IOSlot]  # input slots
+    outputs: list[IOSlot]  # output slots
+
+    description: str | None = None  # human description for LLM/tool matching
+    tags: list[str] = None  # optional tags
+    flow_id: str | None = None  # optional flow ID. If None, treat it globally.
+
+
+def _map_py_type_to_json_type(tp: Any) -> JsonType | None:
+    """
+    Docstring for _map_py_type_to_json_type
+
+    :param tp: Description
+    :type tp: Any
+    :return: Description
+    :rtype: JsonType | None
+    """
+    origin = getattr(tp, "__origin__", None)
+
+    if tp in (str, bytes):
+        return "string"
+    if tp in (int, float):
+        return "number"
+    if tp is bool:
+        return "boolean"
+
+    # collections
+    if origin in (list, tuple, set) or tp in (list, tuple, set):
+        return "array"
+
+    # dict / mapping -> treat as object
+    if origin in (dict,) or tp in (dict,):
+        return "object"
+
+    # Optional[T] / Union[T, None] etc: peel outer layer and re-map
+    if origin is __import__("typing").Union:
+        args = [a for a in tp.__args__ if a is not type(None)]  # noqa: E721
+        if len(args) == 1:
+            return _map_py_type_to_json_type(args[0])
+
+    # Fallback = "object" or None; for now we return object
+    return "object"

aethergraph/core/graph/graph_fn.py

@@ -2,8 +2,9 @@ from __future__ import annotations
 
 from collections.abc import Callable
 import inspect
-from typing import Any
+from typing import Any, get_type_hints
 
+from aethergraph.core.graph.action_spec import IOSlot, _map_py_type_to_json_type
 from aethergraph.core.runtime.run_registration import RunRegistrationGuard
 from aethergraph.services.registry.agent_app_meta import (
     build_agent_meta,
@@ -113,6 +114,68 @@ class GraphFunction:
 
         return run(self, inputs)
 
+    def io_signature(self) -> dict[str, list[IOSlot]]:
+        """
+        Infer typed IO based on decorator inputs/outputs and Python annotations.
+
+        Rule of thumbs:
+        - Inputs: use decorator list; if missing, use all params except 'context'.
+        - Outputs: use decorator list; if missing, use return annotation if any.
+
+        """
+        sig = inspect.signature(self.fn)
+        hints = get_type_hints(self.fn)
+
+        # --- Inputs ---
+        if self.inputs is not None:
+            input_names = list(self.inputs)
+        else:
+            # fallback: all params except 'context'
+            input_names = [p for p in sig.parameters if p != "context"]
+
+        input_slots: list[IOSlot] = []
+        for name in input_names:
+            param = sig.parameters.get(name)
+            if param is None:
+                # decorator said it's a input but not in signature
+                # treat as unknown, required
+                input_slots.append(IOSlot(name=name, type=None, required=True))
+                continue
+
+            anno = hints.get(name)
+            j_type = _map_py_type_to_json_type(anno) if anno is not None else None
+            required = param.default is inspect._empty
+            default = None if required else param.default
+
+            input_slots.append(
+                IOSlot(
+                    name=name,
+                    type=j_type,
+                    required=required,
+                    default=default,
+                )
+            )
+
+        # --- Outputs ---
+        output_slots: list[IOSlot] = []
+        out_names = list(self.outputs or [])
+
+        ret_anno = hints.get("return")
+        if out_names:
+            if len(out_names) == 1 and ret_anno is not None:
+                j_type = _map_py_type_to_json_type(ret_anno)
+                output_slots.append(IOSlot(name=out_names[0], type=j_type, required=True))
+            else:
+                # Multi-output or no return type: names only
+                for name in out_names:
+                    output_slots.append(IOSlot(name=name, type=None, required=True))
+        elif ret_anno is not None:
+            # No explicit output names but we *do* know the type: create a single output
+            j_type = _map_py_type_to_json_type(ret_anno)
+            output_slots.append(IOSlot(name="result", type=j_type, required=True))
+
+        return {"inputs": input_slots, "outputs": output_slots}
+
 
 def _is_ref(x: object) -> bool:
     return isinstance(x, dict) and x.get("_type") == "ref" and "from" in x and "key" in x
@@ -207,6 +270,7 @@ def graph_fn(
     tags: list[str] | None = None,
     as_agent: dict[str, Any] | None = None,
     as_app: dict[str, Any] | None = None,
+    description: str | None = None,
 ) -> Callable[[Callable], GraphFunction]:
     """
     Decorator to define a graph function and optionally register it as an agent or app.
@@ -275,6 +339,7 @@ def graph_fn(
         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.
+        description: Optional human-readable description of the graph function.
 
     Returns:
         Callable: A decorator that wraps the function as a `GraphFunction` and registers it
@@ -307,11 +372,19 @@ def graph_fn(
             return gf
 
         base_tags = tags or []
+
+        # prefer explicit description; then docstring; else name
+        doc_desc = inspect.getdoc(fn) or None
+        eff_description = description or doc_desc or name
+
         graph_meta: dict[str, Any] = {
             "kind": "graphfn",
             "entrypoint": entrypoint,
-            "flow_id": flow_id or name,
+            "flow_id": flow_id,
             "tags": base_tags,
+            "description": eff_description,
+            "inputs": inputs,
+            "outputs": outputs,
         }
 
         registry.register(

aethergraph/core/graph/graphify.py

@@ -1,14 +1,45 @@
 from __future__ import annotations
 
 import inspect
-from typing import Any
+from typing import Any, get_origin, get_type_hints
 
+from aethergraph.core.graph.action_spec import _map_py_type_to_json_type
 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 _normalize_type_hint(ann: Any) -> str:
+    """Convert a Python annotation into a simple string for IO types."""
+    if ann is inspect._empty:
+        return "any"
+
+    origin = get_origin(ann)
+    # args = get_args(ann)
+
+    # Builtins
+    if ann is str:
+        return "string"
+    if ann is int:
+        return "int"
+    if ann is float:
+        return "float"
+    if ann is bool:
+        return "bool"
+    if ann is dict or origin is dict:
+        # e.g. dict[str, float]
+        return "object"
+    if ann in (list, tuple) or origin in (list, tuple):
+        # e.g. list[int] / list[dict[str, float]]
+        return "array"
+    if ann is Any:
+        return "any"
+
+    # Fallback: stringified type name
+    return getattr(ann, "__name__", str(ann))
+
+
 def graphify(
     name="default_graph",
     inputs=(),
@@ -20,6 +51,7 @@ def graphify(
     tags: list[str] | None = None,
     as_agent: dict[str, Any] | None = None,
     as_app: dict[str, Any] | None = None,
+    description: str | None = None,
 ):
     """
     Decorator to define a `TaskGraph` and optionally register it as an agent or app.
@@ -88,6 +120,7 @@ def graphify(
         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.
+        description: Optional human-readable description of the graph function.
 
     Returns:
         TaskGraph: A decorator that transforms a function into a TaskGraph with the specified configuration.
@@ -195,11 +228,50 @@ def graphify(
             return _build
 
         base_tags = tags or []
+
+        # Effective description
+        doc_desc = inspect.getdoc(fn) or None
+        eff_description = description or doc_desc or name
+
+        # Infer IO types from annotations if possible
+        try:
+            resolved_hints = get_type_hints(fn)
+        except Exception:
+            # Fallback: use raw __annotations__ if get_type_hints blows up
+            resolved_hints = getattr(fn, "__annotations__", {}) or {}
+
+        # Infer IO types from annotations in a JSON-ish schema
+        input_type_map: dict[str, str] = {}
+        for pname in required_inputs:
+            param = fn_sig.parameters.get(pname)
+            if param is None:
+                continue
+
+            # Prefer resolved type hint; fall back to the raw annotation
+            ann = resolved_hints.get(pname, param.annotation)
+            if ann is inspect._empty:
+                continue
+
+            j = _map_py_type_to_json_type(ann)
+            if j is not None:
+                input_type_map[pname] = j
+
+        # for outputs, we only have the return annotation as a whole
+        output_names = list(outputs or [])
+        output_type_map: dict[str, str] = {n: "any" for n in output_names}
+
         graph_meta: dict[str, Any] = {
             "kind": "graph",
             "entrypoint": entrypoint,
-            "flow_id": flow_id or name,
+            "flow_id": flow_id,
             "tags": base_tags,
+            "description": eff_description,
+            "inputs": inputs,
+            "outputs": outputs,
+            "io_types": {
+                "inputs": input_type_map,
+                "outputs": output_type_map,
+            },
         }
 
         registry.register(

aethergraph/core/runtime/graph_runner.py

@@ -10,7 +10,6 @@ from aethergraph.contracts.errors.errors import GraphHasPendingWaits
 from aethergraph.contracts.services.state_stores import GraphSnapshot
 from aethergraph.core.graph.task_graph import TaskGraph
 from aethergraph.core.runtime.recovery import hash_spec, recover_graph_run
-from aethergraph.services.container.default_container import build_default_container  # adjust path
 from aethergraph.services.state_stores.graph_observer import PersistenceObserver
 from aethergraph.services.state_stores.resume_policy import (
     assert_snapshot_json_only,
@@ -29,6 +28,8 @@ from .run_registration import RunRegistrationGuard
 
 # ---------- env helpers ----------
 def _get_container():
+    from aethergraph.services.container.default_container import build_default_container
+
     # install once if not installed by sidecar/server
     return ensure_services_installed(build_default_container)
 

aethergraph/core/runtime/node_context.py

@@ -2,7 +2,15 @@ from dataclasses import dataclass
 from datetime import timedelta
 from typing import TYPE_CHECKING, Any
 
+from aethergraph.contracts.services.execution import (
+    CodeExecutionRequest,
+    CodeExecutionResult,
+    ExecutionService,
+)
 from aethergraph.services.artifacts.facade import ArtifactFacade
+from aethergraph.services.indices.scoped_indices import ScopedIndices
+from aethergraph.services.planning.node_planner import NodePlanner
+from aethergraph.services.skills.skill_registry import SkillRegistry
 
 if TYPE_CHECKING:
     from aethergraph.core.runtime.run_manager import RunManager
@@ -41,10 +49,37 @@ class NodeContext:
     app_id: str | None = None  # for app-invoked runs
     bound_memory: BoundMemoryAdapter | None = None  # back-compat
 
+    _planner_facade: NodePlanner | None = None  # lazy init
+
     # --- accessors (compatible names) ---
     def runtime(self) -> NodeServices:
         return self.services
 
+    async def execute(
+        self,
+        code: str,
+        *,
+        language: str = "python",
+        timeout_s: float = 30.0,
+        args: list[str] | None = None,
+        workdir: str | None = None,
+        env: dict[str, str] | None = None,
+    ) -> CodeExecutionResult:
+        """ """
+        exe_svs: ExecutionService | None = getattr(self.services, "execution", None)
+        if exe_svs is None:
+            raise RuntimeError("NodeContext.services.execution is not configured")
+
+        req = CodeExecutionRequest(
+            language=language,
+            code=code,
+            args=args or [],
+            timeout_s=timeout_s,
+            workdir=workdir,
+            env=env,
+        )
+        return await exe_svs.execute(req)
+
     async def spawn_run(
         self,
         graph_id: str,
@@ -83,7 +118,7 @@ class NodeContext:
                 inputs={"foo": "bar"},
                 tags=["experiment", "priority"],
                 agent_id="agent-123",    # associate with an agent if applicable
-                visibility=RunVisibility.ineline, # not shown in UI
+                visibility=RunVisibility.inline, # not shown in UI
             )
             ```
 
@@ -232,6 +267,7 @@ class NodeContext:
         run_id: str,
         *,
         timeout_s: float | None = None,
+        return_outputs: bool = False,
     ) -> RunRecord:
         """
         Wait for a run to complete and retrieve its final record.
@@ -249,16 +285,18 @@ class NodeContext:
 
             Waiting with a timeout:
             ```python
-            record = await context.wait_run(run_id, timeout_s=30)
+            record, outputs = await context.wait_run(run_id, timeout_s=30, return_outputs=True)
             ```
 
         Args:
             run_id: The unique identifier of the run to wait for.
             timeout_s: Optional timeout in seconds. If set, the method will raise
                 a TimeoutError if the run does not complete in time.
+            return_outputs: If True, also return the run's outputs along with the record.
 
         Returns:
             RunRecord: The final record of the completed run.
+            Output: If `return_outputs` is True, returns a tuple of (RunRecord, outputs dict).
 
         Raises:
             RuntimeError: If the RunManager service is not configured in the context.
@@ -273,7 +311,7 @@ class NodeContext:
         rm: RunManager | None = getattr(self.services, "run_manager", None)
         if rm is None:
             raise RuntimeError("NodeContext.services.run_manager is not configured")
-        return await rm.wait_run(run_id, timeout_s=timeout_s)
+        return await rm.wait_run(run_id, timeout_s=timeout_s, return_outputs=return_outputs)
 
     async def cancel_run(self, run_id: str) -> None:
         """
@@ -315,6 +353,16 @@ class NodeContext:
             raise RuntimeError("NodeContext.services.run_manager is not configured")
         await rm.cancel_run(run_id)
 
+    def planner(self) -> "NodePlanner":
+        if self._planner_facade is None:
+            if self.services.planner_service is None:
+                raise RuntimeError("NodeContext.services.planner_service is not configured")
+            self._planner_facade = NodePlanner(
+                service=self.services.planner_service,
+                node_ctx=self,
+            )
+        return self._planner_facade
+
     def logger(self):
         return self.services.logger.for_node_ctx(
             run_id=self.run_id, node_id=self.node_id, graph_id=self.graph_id
@@ -346,6 +394,11 @@ class NodeContext:
         """
         return ChannelSession(self, f"ui:run/{self.run_id}")
 
+    def skills(self) -> SkillRegistry:
+        if not self.services.skills:
+            raise RuntimeError("NodeContext.services.skills is not configured")
+        return self.services.skills
+
     def channel(self, channel_key: str | None = None):
         """
         Set up a new ChannelSession for the current node context.
@@ -521,6 +574,16 @@ class NodeContext:
             raise RuntimeError("MCPService not available")
         return self.services.mcp.get(name)
 
+    def indices(self) -> ScopedIndices:
+        if not self.services.indices:
+            raise RuntimeError("ScopedIndices not available")
+        return self.services.indices
+
+    # def run_manager(self) -> RunManager:
+    #     if not self.services.run_manager:
+    #         raise RuntimeError("RunManager not available")
+    #     return self.services.run_manager
+
     def continuations(self):
         return self.services.continuation_store
 

aethergraph/core/runtime/node_services.py

@@ -3,6 +3,10 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 
+from aethergraph.services.indices.scoped_indices import ScopedIndices
+from aethergraph.services.planning.planner_service import PlannerService
+from aethergraph.services.skills.skill_registry import SkillRegistry
+
 if TYPE_CHECKING:
     from aethergraph.core.runtime.run_manager import RunManager
 from aethergraph.services.channel.channel_bus import ChannelBus
@@ -35,3 +39,7 @@ class NodeServices:
     rag: NodeRAG | None = None  # RAGService
     mcp: MCPService | None = None  # MCPService
     run_manager: RunManager | None = None  # RunManager
+    indices: ScopedIndices | None = None  # ScopedIndices for this node
+    execution: Any | None = None  # ExecutionService
+    planner_service: PlannerService | None = None  # PlannerService
+    skills: SkillRegistry | None = None  # SkillRegistry