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

aethergraph/services/planning/dependency_index.py

@@ -0,0 +1,65 @@
+# aethergraph/services/planning/dependency_index.py
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Literal
+
+from aethergraph.core.graph.action_spec import ActionSpec, IOSlot
+from aethergraph.services.planning.action_catalog import ActionCatalog
+
+
+@dataclass
+class DependencyIndex:
+    actions: list[ActionSpec]
+
+    @classmethod
+    def from_catalog(
+        cls,
+        catalog: ActionCatalog,
+        *,
+        flow_ids: list[str] | None = None,
+        kinds: Iterable[Literal["graph", "graphfn"]] | None = ("graph", "graphfn"),
+        include_global: bool = True,
+    ) -> DependencyIndex:
+        return cls(
+            actions=list(
+                catalog.list_actions(
+                    flow_ids=flow_ids,
+                    kinds=kinds,
+                    include_global=include_global,
+                )
+            )
+        )
+
+    def find_producers(
+        self,
+        needed: IOSlot,
+        *,
+        flow_ids: list[str] | None = None,
+    ) -> list[tuple[ActionSpec, IOSlot]]:
+        """
+        Find (action, output_slot) pairs whose outputs are compatible with the given input slot.
+        If flow_ids is provided, only consider actions within those flows or global ones (the
+        actions list is usually pre-filtered by from_catalog).
+        """
+        matches: list[tuple[ActionSpec, IOSlot]] = []
+        for act in self.actions:
+            if flow_ids is not None:  # noqa: SIM102
+                # respect pre-filtering convention: allow actions with flow_id in flow_ids or None
+                if act.flow_id not in flow_ids and act.flow_id is not None:
+                    continue
+            for out_slot in act.outputs:
+                if self._compatible(needed, out_slot):
+                    matches.append((act, out_slot))
+        return matches
+
+    @staticmethod
+    def _compatible(inp: IOSlot, out: IOSlot) -> bool:
+        if inp.type is None or out.type is None:
+            return True
+        if inp.type == out.type:
+            return True
+        if inp.type in {"object", "any"} or out.type in {"object", "any"}:  # noqa: SIM103
+            return True
+        return False

aethergraph/services/planning/flow_validator.py

@@ -0,0 +1,263 @@
+# aethergraph/services/planning/flow_validator.py
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Literal
+
+from aethergraph.core.graph.action_spec import ActionSpec, IOSlot
+
+from .action_catalog import ActionCatalog
+from .bindings import parse_binding
+from .dependency_index import DependencyIndex
+from .plan_types import CandidatePlan, PlanStep, ValidationIssue, ValidationResult
+
+
+@dataclass
+class FlowValidator:
+    catalog: ActionCatalog
+    dep_index: DependencyIndex | None = None
+
+    def _action_index(
+        self,
+        *,
+        flow_ids: list[str] | None = None,
+        kinds: Iterable[Literal["graph", "graphfn"]] | None = ("graph", "graphfn"),
+    ) -> dict[str, ActionSpec]:
+        idx: dict[str, ActionSpec] = {}
+        for spec in self.catalog.iter_actions(
+            flow_ids=flow_ids,
+            kinds=kinds,
+            include_global=True,
+        ):
+            idx[spec.ref] = spec
+        return idx
+
+    @staticmethod
+    def _is_strict_type_mismatch(
+        expected: str | None,
+        actual: str | None,
+    ) -> bool:
+        if not expected or not actual:
+            return False
+        wildcard = {"any", "object"}
+        if expected in wildcard or actual in wildcard:
+            return False
+        return expected != actual
+
+    def validate(
+        self,
+        plan: CandidatePlan,
+        *,
+        external_inputs: dict[str, IOSlot] | None = None,
+        flow_ids: list[str] | None = None,
+    ) -> ValidationResult:
+        issues: list[ValidationIssue] = []
+        external_inputs = external_inputs or {}
+        missing_user_bindings: dict[str, list[str]] = {}
+
+        action_index = self._action_index(flow_ids=flow_ids)
+        step_index: dict[str, PlanStep] = {step.id: step for step in plan.steps}
+
+        # 1) unknown actions
+        for step in plan.steps:
+            if step.action_ref not in action_index:
+                issues.append(
+                    ValidationIssue(
+                        kind="unknown_action",
+                        step_id=step.id,
+                        field=None,
+                        message=f"Action '{step.action_ref}' is not recognized.",
+                    )
+                )
+
+        if any(iss.kind == "unknown_action" for iss in issues):
+            # structural error, no missing_user_bindings in this path
+            return ValidationResult(
+                ok=False,
+                issues=issues,
+                has_structural_errors=True,
+                missing_user_bindings={},
+            )
+
+        # 2) dependency graph
+        edges: dict[str, set[str]] = {step.id: set() for step in plan.steps}
+        for step in plan.steps:
+            for raw in (step.inputs or {}).values():
+                binding = parse_binding(raw)
+                if binding.kind == "step_output" and binding.source_step_id in step_index:
+                    edges[step.id].add(binding.source_step_id)
+
+        # 3) detect cycles
+        visiting: set[str] = set()
+        visited: set[str] = set()
+        has_cycle = False
+
+        def dfs(node: str) -> None:
+            nonlocal has_cycle
+            if node in visited or has_cycle:
+                return
+            if node in visiting:
+                has_cycle = True
+                return
+            visiting.add(node)
+            for dep in edges[node]:
+                dfs(dep)
+            visiting.remove(node)
+            visited.add(node)
+
+        for step_id in edges:
+            if step_id not in visited:
+                dfs(step_id)
+
+        if has_cycle:
+            issues.append(
+                ValidationIssue(
+                    kind="cycle",
+                    step_id="",
+                    field=None,
+                    message="The plan contains cyclic dependencies among steps.",
+                )
+            )
+            return ValidationResult(
+                ok=False,
+                issues=issues,
+                has_structural_errors=True,
+                missing_user_bindings={},
+            )
+
+        # 4) topo order
+        in_deg: dict[str, int] = {step_id: 0 for step_id in edges}
+        for step_id, deps in edges.items():
+            for _ in deps:
+                in_deg[step_id] += 1
+
+        ready = [sid for sid, deg in in_deg.items() if deg == 0]
+        topo_order: list[str] = []
+        while ready:
+            sid = ready.pop()
+            topo_order.append(sid)
+            for consumer, deps in edges.items():
+                if sid in deps:
+                    in_deg[consumer] -= 1
+                    if in_deg[consumer] == 0:
+                        ready.append(consumer)
+
+        # 5) validate inputs along topo order
+        available_outputs: dict[str, IOSlot] = {}
+
+        for step_id in topo_order:
+            step = step_index[step_id]
+            spec = action_index[step.action_ref]
+            input_by_name = {slot.name: slot for slot in spec.inputs}
+
+            for name, slot in input_by_name.items():
+                raw_value = step.inputs.get(name)
+
+                if raw_value is None and slot.required:
+                    details: dict = {}
+                    if self.dep_index is not None:
+                        cands = self.dep_index.find_producers(
+                            slot,
+                            flow_ids=flow_ids,
+                        )
+                        details["candidates"] = [
+                            {
+                                "action_ref": a.ref,
+                                "output": out.name,
+                                "description": a.description,
+                            }
+                            for (a, out) in cands
+                        ]
+                    issues.append(
+                        ValidationIssue(
+                            kind="missing_input",
+                            step_id=step_id,
+                            field=name,
+                            message=(
+                                f"Required input '{name}' is not provided "
+                                f"for action '{spec.name}'."
+                            ),
+                            details=details,
+                        )
+                    )
+                    continue
+
+                if raw_value is None:
+                    continue
+
+                binding = parse_binding(raw_value)
+
+                if binding.kind == "external":
+                    key = binding.external_key or ""
+                    ext_slot = external_inputs.get(key)
+                    if ext_slot is None:
+                        # treat as “needs user value”, not structural error
+                        loc = f"{step_id}.{name}"
+                        missing_user_bindings.setdefault(key, []).append(loc)
+                        continue
+
+                    # ext_slot can be an IOSlot OR a bare value (when planner passes user_inputs).
+                    # In the latter case we don't have type info, so we skip strict type checking.
+                    ext_type = getattr(ext_slot, "type", None)
+                    if self._is_strict_type_mismatch(slot.type, ext_type):
+                        issues.append(
+                            ValidationIssue(
+                                kind="type_mismatch",
+                                step_id=step_id,
+                                field=name,
+                                message=(
+                                    f"Type mismatch for external input '{key}': "
+                                    f"expected '{slot.type}', got '{ext_slot.type}'."
+                                ),
+                            )
+                        )
+
+                elif binding.kind == "step_output":
+                    src_id = binding.source_step_id or ""
+                    out_name = binding.source_output_name or ""
+                    key = f"{src_id}.{out_name}"
+                    out_slot = available_outputs.get(key)
+                    if out_slot is None:
+                        issues.append(
+                            ValidationIssue(
+                                kind="missing_input",
+                                step_id=step_id,
+                                field=name,
+                                message=(
+                                    f"Input '{name}' refers to '{key}', "
+                                    "which is not produced by any previous step."
+                                ),
+                            )
+                        )
+                    else:
+                        if self._is_strict_type_mismatch(slot.type, out_slot.type):
+                            issues.append(
+                                ValidationIssue(
+                                    kind="type_mismatch",
+                                    step_id=step_id,
+                                    field=name,
+                                    message=(
+                                        f"Input '{name}' expects type '{slot.type}' "
+                                        f"but is wired from '{key}' with type '{out_slot.type}'."
+                                    ),
+                                )
+                            )
+
+                # literals: accepted, no extra checks yet
+
+            for out in spec.outputs:
+                available_outputs[f"{step_id}.{out.name}"] = out
+
+        # Decide what counts as “structural” (vs. “needs user values”)
+        structural_kinds = {"unknown_action", "cycle", "missing_input", "type_mismatch"}
+        has_structural_errors = any(iss.kind in structural_kinds for iss in issues)
+
+        ok = (not has_structural_errors) and (len(missing_user_bindings) == 0)
+
+        return ValidationResult(
+            ok=ok,
+            issues=issues,
+            has_structural_errors=has_structural_errors,
+            missing_user_bindings=missing_user_bindings,
+        )

aethergraph/services/planning/graph_io_adapter.py

@@ -0,0 +1,150 @@
+# aethergraph/services/planning/graph_io_adapter.py
+from __future__ import annotations
+
+from typing import Any
+
+from aethergraph.core.graph.action_spec import IOSlot, _map_py_type_to_json_type
+from aethergraph.core.graph.task_graph import TaskGraph
+
+
+def graph_io_to_slots(
+    graph: TaskGraph,
+    meta: dict[str, Any] | None = None,
+) -> dict[str, list[IOSlot]]:
+    """
+    Adapter: TaskGraph.io_signature() + IOSpec + optional registry meta -> IOSlot lists.
+
+    Priority for types:
+      1) registry meta["io_types"]["inputs"/"outputs"]  (set by @graphify)
+      2) ParamSpec.annotation from IOSpec
+      3) None (treated as "any" by planner)
+    """
+    sig = graph.io_signature(include_values=False)
+    io_spec = getattr(graph.spec, "io", None)  # IOSpec if present
+
+    inputs_info = sig.get("inputs", {}) or {}
+    outputs_info = sig.get("outputs", {}) or {}
+
+    # ---- io_types from registry meta (preferred) ----
+    io_types = (meta or {}).get("io_types") or {}
+    input_type_map: dict[str, str] = io_types.get("inputs", {}) or {}
+    output_type_map: dict[str, str] = io_types.get("outputs", {}) or {}
+
+    # --- INPUTS ---
+
+    req_raw = inputs_info.get("required") or []
+    opt_raw = inputs_info.get("optional") or {}
+
+    required_names = list(req_raw.keys()) if isinstance(req_raw, dict) else list(req_raw)
+    optional_names = list(opt_raw.keys()) if isinstance(opt_raw, dict) else list(opt_raw)
+
+    input_slots: list[IOSlot] = []
+
+    def _param_for(name: str):
+        if io_spec is None:
+            return None
+        if hasattr(io_spec, "required") and name in io_spec.required:
+            return io_spec.required[name]
+        if hasattr(io_spec, "optional") and name in io_spec.optional:
+            return io_spec.optional[name]
+        return None
+
+    # required inputs
+    for name in required_names:
+        ps = _param_for(name)
+
+        # 1) type from meta.io_types if present
+        t_from_meta = input_type_map.get(name)
+
+        # 2) else type from ParamSpec.annotation
+        j_type = None
+        default = None
+        description = None
+        required_flag = True
+
+        if ps is not None:
+            anno = getattr(ps, "annotation", None)
+            default = getattr(ps, "default", None)
+            required_flag = getattr(ps, "required", True)
+            description = getattr(ps, "description", None)
+            if t_from_meta is None and anno is not None:
+                j_type = _map_py_type_to_json_type(anno)
+
+        # final type choice
+        final_type = t_from_meta or j_type
+
+        input_slots.append(
+            IOSlot(
+                name=name,
+                type=final_type,
+                required=required_flag,
+                default=None if required_flag else default,
+                description=description,
+            )
+        )
+
+    # optional inputs
+    for name in optional_names:
+        ps = _param_for(name)
+
+        t_from_meta = input_type_map.get(name)
+
+        j_type = None
+        default = None
+        description = None
+
+        if ps is not None:
+            anno = getattr(ps, "annotation", None)
+            default = getattr(ps, "default", None)
+            description = getattr(ps, "description", None)
+            if t_from_meta is None and anno is not None:
+                j_type = _map_py_type_to_json_type(anno)
+
+        final_type = t_from_meta or j_type
+
+        input_slots.append(
+            IOSlot(
+                name=name,
+                type=final_type,
+                required=False,
+                default=default,
+                description=description,
+            )
+        )
+
+    # --- OUTPUTS ---
+
+    output_keys = outputs_info.get("keys") or []
+    output_slots: list[IOSlot] = []
+
+    def _output_param_for(name: str):
+        if io_spec is None or not hasattr(io_spec, "outputs"):
+            return None
+        return io_spec.outputs.get(name)
+
+    for name in output_keys:
+        ps = _output_param_for(name)
+
+        t_from_meta = output_type_map.get(name)
+
+        j_type = None
+        description = None
+
+        if ps is not None:
+            anno = getattr(ps, "annotation", None)
+            description = getattr(ps, "description", None)
+            if t_from_meta is None and anno is not None:
+                j_type = _map_py_type_to_json_type(anno)
+
+        final_type = t_from_meta or j_type
+
+        output_slots.append(
+            IOSlot(
+                name=name,
+                type=final_type,
+                required=True,  # outputs are logically “present”
+                description=description,
+            )
+        )
+
+    return {"inputs": input_slots, "outputs": output_slots}