abstractflow 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

abstractflow/core/__init__.py

@@ -0,0 +1,5 @@
+"""AbstractFlow core module."""
+
+from .flow import Flow, FlowNode, FlowEdge
+
+__all__ = ["Flow", "FlowNode", "FlowEdge"]

abstractflow/core/flow.py

@@ -0,0 +1,247 @@
+"""Flow definition classes for AbstractFlow.
+
+This module provides the core data structures for defining flows:
+- Flow: A directed graph of nodes connected by edges
+- FlowNode: A node in the flow (agent, function, or nested flow)
+- FlowEdge: An edge connecting two nodes
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Optional, Union, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # Avoid circular import - only used for type hints
+    pass
+
+
+@dataclass
+class FlowNode:
+    """A node in a flow graph.
+
+    Attributes:
+        id: Unique identifier for the node within the flow
+        handler: The handler for this node - can be an agent, function, or nested flow
+        input_key: Key in run.vars to read input from (optional)
+        output_key: Key in run.vars to write output to (optional)
+        effect_type: Effect type for effect nodes (ask_user, wait_until, etc.)
+        effect_config: Additional configuration for effect nodes
+    """
+    id: str
+    handler: Any  # Union[BaseAgent, Callable, Flow] - Any to avoid circular imports
+    input_key: Optional[str] = None
+    output_key: Optional[str] = None
+    effect_type: Optional[str] = None  # e.g., "ask_user", "wait_until", etc.
+    effect_config: Optional[Dict[str, Any]] = None  # Effect-specific configuration
+
+
+@dataclass
+class FlowEdge:
+    """An edge connecting two nodes in a flow.
+
+    Attributes:
+        source: ID of the source node
+        target: ID of the target node
+        condition: Optional condition function for conditional routing (future)
+        source_handle: Optional execution output handle id (visual flows).
+    """
+    source: str
+    target: str
+    condition: Optional[Callable[[Dict[str, Any]], bool]] = None
+    source_handle: Optional[str] = None
+
+
+class Flow:
+    """Declarative flow definition that compiles to WorkflowSpec.
+
+    A Flow represents a directed graph of nodes (agents, functions, or nested flows)
+    connected by edges. Flows can be compiled to AbstractRuntime WorkflowSpec for
+    durable execution.
+
+    Example:
+        >>> flow = Flow("my_flow")
+        >>> flow.add_node("start", my_function, output_key="data")
+        >>> flow.add_node("process", process_function, input_key="data")
+        >>> flow.add_edge("start", "process")
+        >>> flow.set_entry("start")
+    """
+
+    def __init__(self, flow_id: str):
+        """Initialize a new flow.
+
+        Args:
+            flow_id: Unique identifier for this flow
+        """
+        self.flow_id = flow_id
+        self.nodes: Dict[str, FlowNode] = {}
+        self.edges: List[FlowEdge] = []
+        self.entry_node: Optional[str] = None
+        self.exit_node: Optional[str] = None
+
+    def add_node(
+        self,
+        node_id: str,
+        handler: Any,
+        *,
+        input_key: Optional[str] = None,
+        output_key: Optional[str] = None,
+        effect_type: Optional[str] = None,
+        effect_config: Optional[Dict[str, Any]] = None,
+    ) -> "Flow":
+        """Add a node to the flow.
+
+        Args:
+            node_id: Unique identifier for this node
+            handler: The handler - an agent, callable function, or nested Flow
+            input_key: Key in run.vars to read input from
+            output_key: Key in run.vars to write output to
+            effect_type: Effect type for effect nodes (ask_user, wait_until, etc.)
+            effect_config: Additional configuration for effect nodes
+
+        Returns:
+            Self for method chaining
+        """
+        if node_id in self.nodes:
+            raise ValueError(f"Node '{node_id}' already exists in flow '{self.flow_id}'")
+
+        self.nodes[node_id] = FlowNode(
+            id=node_id,
+            handler=handler,
+            input_key=input_key,
+            output_key=output_key,
+            effect_type=effect_type,
+            effect_config=effect_config,
+        )
+        return self
+
+    def add_edge(
+        self,
+        source: str,
+        target: str,
+        *,
+        condition: Optional[Callable[[Dict[str, Any]], bool]] = None,
+        source_handle: Optional[str] = None,
+    ) -> "Flow":
+        """Add an edge between nodes.
+
+        Args:
+            source: ID of the source node
+            target: ID of the target node
+            condition: Optional condition function for conditional routing
+
+        Returns:
+            Self for method chaining
+        """
+        self.edges.append(
+            FlowEdge(
+                source=source,
+                target=target,
+                condition=condition,
+                source_handle=source_handle,
+            )
+        )
+        return self
+
+    def set_entry(self, node_id: str) -> "Flow":
+        """Set the entry node for the flow.
+
+        Args:
+            node_id: ID of the entry node
+
+        Returns:
+            Self for method chaining
+        """
+        if node_id not in self.nodes:
+            raise ValueError(f"Entry node '{node_id}' not found in flow '{self.flow_id}'")
+        self.entry_node = node_id
+        return self
+
+    def set_exit(self, node_id: str) -> "Flow":
+        """Set the exit node for the flow (optional, can be inferred).
+
+        Args:
+            node_id: ID of the exit node
+
+        Returns:
+            Self for method chaining
+        """
+        if node_id not in self.nodes:
+            raise ValueError(f"Exit node '{node_id}' not found in flow '{self.flow_id}'")
+        self.exit_node = node_id
+        return self
+
+    def validate(self) -> List[str]:
+        """Validate the flow definition.
+
+        Returns:
+            List of validation error messages (empty if valid)
+        """
+        errors = []
+
+        if not self.entry_node:
+            errors.append("Flow must have an entry node")
+        elif self.entry_node not in self.nodes:
+            errors.append(f"Entry node '{self.entry_node}' not found")
+
+        # Check that all edge endpoints exist
+        for edge in self.edges:
+            if edge.source not in self.nodes:
+                errors.append(f"Edge source '{edge.source}' not found")
+            if edge.target not in self.nodes:
+                errors.append(f"Edge target '{edge.target}' not found")
+
+        # Check for unreachable nodes
+        if self.entry_node:
+            reachable = self._find_reachable_nodes(self.entry_node)
+            for node_id in self.nodes:
+                if node_id not in reachable:
+                    errors.append(f"Node '{node_id}' is unreachable from entry")
+
+        return errors
+
+    def _find_reachable_nodes(self, start: str) -> set:
+        """Find all nodes reachable from a starting node."""
+        reachable = set()
+        to_visit = [start]
+
+        while to_visit:
+            current = to_visit.pop()
+            if current in reachable:
+                continue
+            reachable.add(current)
+
+            # Find outgoing edges
+            for edge in self.edges:
+                if edge.source == current and edge.target not in reachable:
+                    to_visit.append(edge.target)
+
+        return reachable
+
+    def get_next_nodes(self, node_id: str) -> List[str]:
+        """Get the next nodes from a given node.
+
+        Args:
+            node_id: ID of the current node
+
+        Returns:
+            List of target node IDs
+        """
+        return [edge.target for edge in self.edges if edge.source == node_id]
+
+    def get_terminal_nodes(self) -> List[str]:
+        """Get nodes with no outgoing edges (terminal nodes).
+
+        Returns:
+            List of terminal node IDs
+        """
+        sources = {edge.source for edge in self.edges}
+        return [node_id for node_id in self.nodes if node_id not in sources]
+
+    def __repr__(self) -> str:
+        return (
+            f"Flow(id={self.flow_id!r}, "
+            f"nodes={len(self.nodes)}, "
+            f"edges={len(self.edges)}, "
+            f"entry={self.entry_node!r})"
+        )

abstractflow/py.typed

@@ -1 +1,3 @@
 # Marker file for PEP 561 - indicates this package supports type checking
+
+

abstractflow/runner.py

@@ -0,0 +1,348 @@
+"""FlowRunner - executes flows using AbstractRuntime."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, TYPE_CHECKING
+
+from .core.flow import Flow
+from .compiler import compile_flow
+
+if TYPE_CHECKING:
+    from abstractruntime.core.models import RunState
+    from abstractruntime.core.runtime import Runtime
+    from abstractruntime.core.spec import WorkflowSpec
+
+
+class FlowRunner:
+    """Executes flows using AbstractRuntime.
+
+    FlowRunner provides a high-level interface for running flows. It handles:
+    - Compiling the flow to a WorkflowSpec
+    - Creating a default runtime if not provided
+    - Managing run lifecycle (start, step, run, resume)
+
+    Example:
+        >>> flow = Flow("my_flow")
+        >>> flow.add_node("start", lambda x: x * 2, input_key="value")
+        >>> flow.set_entry("start")
+        >>>
+        >>> runner = FlowRunner(flow)
+        >>> result = runner.run({"value": 21})
+        >>> print(result)  # {'result': 42, 'success': True}
+    """
+
+    def __init__(
+        self,
+        flow: Flow,
+        runtime: Optional["Runtime"] = None,
+    ):
+        """Initialize a FlowRunner.
+
+        Args:
+            flow: The Flow definition to run
+            runtime: Optional AbstractRuntime instance. If not provided,
+                     a default in-memory runtime will be created.
+        """
+        self.flow = flow
+        self.workflow: "WorkflowSpec" = compile_flow(flow)
+        self.runtime = runtime or self._create_default_runtime()
+        self._current_run_id: Optional[str] = None
+
+    def _create_default_runtime(self) -> "Runtime":
+        """Create a default in-memory runtime."""
+        try:
+            from abstractruntime import Runtime, InMemoryRunStore, InMemoryLedgerStore  # type: ignore
+        except Exception:  # pragma: no cover
+            from abstractruntime.core.runtime import Runtime  # type: ignore
+            from abstractruntime.storage.in_memory import InMemoryLedgerStore, InMemoryRunStore  # type: ignore
+
+        return Runtime(
+            run_store=InMemoryRunStore(),
+            ledger_store=InMemoryLedgerStore(),
+        )
+
+    @property
+    def run_id(self) -> Optional[str]:
+        """Get the current run ID."""
+        return self._current_run_id
+
+    def start(self, input_data: Optional[Dict[str, Any]] = None) -> str:
+        """Start flow execution.
+
+        Args:
+            input_data: Initial variables for the flow
+
+        Returns:
+            The run ID for this execution
+        """
+        vars_dict = input_data or {}
+        self._current_run_id = self.runtime.start(
+            workflow=self.workflow,
+            vars=vars_dict,
+        )
+        return self._current_run_id
+
+    def step(self, max_steps: int = 1) -> "RunState":
+        """Execute one or more steps.
+
+        Args:
+            max_steps: Maximum number of steps to execute
+
+        Returns:
+            The current RunState after stepping
+
+        Raises:
+            ValueError: If no run has been started
+        """
+        if not self._current_run_id:
+            raise ValueError("No active run. Call start() first.")
+
+        return self.runtime.tick(
+            workflow=self.workflow,
+            run_id=self._current_run_id,
+            max_steps=max_steps,
+        )
+
+    def run(self, input_data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Execute flow to completion.
+
+        This method starts the flow and runs until it completes, fails,
+        or enters a waiting state.
+
+        Args:
+            input_data: Initial variables for the flow
+
+        Returns:
+            The flow's output dictionary. If the flow is waiting,
+            returns {"waiting": True, "state": <RunState>}.
+
+        Raises:
+            RuntimeError: If the flow fails
+        """
+        from abstractruntime.core.models import RunStatus, WaitReason
+
+        self.start(input_data)
+
+        while True:
+            state = self.runtime.tick(
+                workflow=self.workflow,
+                run_id=self._current_run_id,
+            )
+
+            if state.status == RunStatus.COMPLETED:
+                return state.output or {}
+
+            if state.status == RunStatus.FAILED:
+                raise RuntimeError(f"Flow failed: {state.error}")
+
+            if state.status == RunStatus.WAITING:
+                # Convenience: when waiting on a SUBWORKFLOW, FlowRunner.run() can
+                # auto-drive the child to completion and resume the parent.
+                #
+                # Visual Agent nodes use async+wait START_SUBWORKFLOW so web hosts
+                # can stream traces. In non-interactive contexts (unit tests, CLI),
+                # we still want a synchronous `run()` to complete when possible.
+                wait = getattr(state, "waiting", None)
+                if (
+                    wait is not None
+                    and getattr(wait, "reason", None) == WaitReason.SUBWORKFLOW
+                    and getattr(self.runtime, "workflow_registry", None) is not None
+                ):
+                    registry = getattr(self.runtime, "workflow_registry", None)
+
+                    def _extract_sub_run_id(wait_state: Any) -> Optional[str]:
+                        details2 = getattr(wait_state, "details", None)
+                        if isinstance(details2, dict):
+                            rid2 = details2.get("sub_run_id")
+                            if isinstance(rid2, str) and rid2:
+                                return rid2
+                        wk = getattr(wait_state, "wait_key", None)
+                        if isinstance(wk, str) and wk.startswith("subworkflow:"):
+                            return wk.split("subworkflow:", 1)[1] or None
+                        return None
+
+                    def _spec_for(run_state: Any):
+                        wf_id = getattr(run_state, "workflow_id", None)
+                        # FlowRunner always has the root workflow spec (self.workflow).
+                        # The runtime registry is required only for *child* workflows.
+                        #
+                        # Without this fallback, synchronous `FlowRunner.run()` can hang on
+                        # SUBWORKFLOW waits if callers register only subworkflows (common in
+                        # unit tests where the parent spec is not registered).
+                        if wf_id == getattr(self.workflow, "workflow_id", None):
+                            return self.workflow
+                        return registry.get(wf_id) if registry is not None else None
+
+                    top_run_id = self._current_run_id  # type: ignore[assignment]
+                    if isinstance(top_run_id, str) and top_run_id:
+                        # Find the deepest run in a SUBWORKFLOW wait chain.
+                        target_run_id = top_run_id
+                        for _ in range(50):
+                            cur_state = self.runtime.get_state(target_run_id)
+                            if cur_state.status != RunStatus.WAITING or cur_state.waiting is None:
+                                break
+                            if cur_state.waiting.reason != WaitReason.SUBWORKFLOW:
+                                break
+                            next_id = _extract_sub_run_id(cur_state.waiting)
+                            if not next_id:
+                                break
+                            target_run_id = next_id
+
+                        # Drive runs bottom-up: tick the deepest runnable run, then bubble completion
+                        # payloads to waiting parents until we either block on external input or
+                        # the chain unwinds.
+                        current_run_id = target_run_id
+                        for _ in range(10_000):
+                            cur_state = self.runtime.get_state(current_run_id)
+                            if cur_state.status == RunStatus.RUNNING:
+                                wf = _spec_for(cur_state)
+                                if wf is None:
+                                    break
+                                cur_state = self.runtime.tick(workflow=wf, run_id=current_run_id)
+
+                            if cur_state.status == RunStatus.WAITING:
+                                # If this is a subworkflow wait, descend further.
+                                if cur_state.waiting is not None and cur_state.waiting.reason == WaitReason.SUBWORKFLOW:
+                                    next_id = _extract_sub_run_id(cur_state.waiting)
+                                    if next_id:
+                                        current_run_id = next_id
+                                        continue
+                                # Blocked on non-subworkflow input (ASK_USER / EVENT / UNTIL).
+                                break
+
+                            if cur_state.status == RunStatus.FAILED:
+                                raise RuntimeError(f"Subworkflow failed: {cur_state.error}")
+                            if cur_state.status == RunStatus.CANCELLED:
+                                raise RuntimeError("Subworkflow cancelled")
+                            if cur_state.status != RunStatus.COMPLETED:
+                                break
+
+                            parent_id = getattr(cur_state, "parent_run_id", None)
+                            if not isinstance(parent_id, str) or not parent_id:
+                                break
+
+                            parent_state = self.runtime.get_state(parent_id)
+                            if (
+                                parent_state.status == RunStatus.WAITING
+                                and parent_state.waiting is not None
+                                and parent_state.waiting.reason == WaitReason.SUBWORKFLOW
+                            ):
+                                parent_wf = _spec_for(parent_state)
+                                if parent_wf is None:
+                                    break
+
+                                node_traces = None
+                                try:
+                                    node_traces = self.runtime.get_node_traces(cur_state.run_id)
+                                except Exception:
+                                    node_traces = None
+
+                                self.runtime.resume(
+                                    workflow=parent_wf,
+                                    run_id=parent_id,
+                                    wait_key=None,
+                                    payload={
+                                        "sub_run_id": cur_state.run_id,
+                                        "output": cur_state.output,
+                                        "node_traces": node_traces,
+                                    },
+                                    max_steps=0,
+                                )
+                                current_run_id = parent_id
+                                # Continue bubbling (and ticking resumed parents) until we unwind.
+                                continue
+
+                            break
+
+                        # After driving/bubbling, re-enter the main loop and tick the top run again.
+                        continue
+
+                # Flow is waiting for external input
+                return {
+                    "waiting": True,
+                    "state": state,
+                    "wait_key": state.waiting.wait_key if state.waiting else None,
+                }
+
+    def resume(
+        self,
+        wait_key: Optional[str] = None,
+        payload: Optional[Dict[str, Any]] = None,
+        *,
+        max_steps: int = 100,
+    ) -> "RunState":
+        """Resume a waiting flow.
+
+        Args:
+            wait_key: The wait key to resume (optional, uses current if not specified)
+            payload: Data to provide to the waiting node
+
+        Returns:
+            The RunState after resuming
+        """
+        if not self._current_run_id:
+            raise ValueError("No active run to resume.")
+
+        return self.runtime.resume(
+            workflow=self.workflow,
+            run_id=self._current_run_id,
+            wait_key=wait_key,
+            payload=payload or {},
+            max_steps=max_steps,
+        )
+
+    def get_state(self) -> Optional["RunState"]:
+        """Get the current run state.
+
+        Returns:
+            The current RunState, or None if no run is active
+        """
+        if not self._current_run_id:
+            return None
+        return self.runtime.get_state(self._current_run_id)
+
+    def get_ledger(self) -> list:
+        """Get the execution ledger for the current run.
+
+        Returns:
+            List of step records, or empty list if no run
+        """
+        if not self._current_run_id:
+            return []
+        return self.runtime.get_ledger(self._current_run_id)
+
+    def is_running(self) -> bool:
+        """Check if the flow is currently running."""
+        from abstractruntime.core.models import RunStatus
+
+        state = self.get_state()
+        return state is not None and state.status == RunStatus.RUNNING
+
+    def is_waiting(self) -> bool:
+        """Check if the flow is waiting for input."""
+        from abstractruntime.core.models import RunStatus
+
+        state = self.get_state()
+        return state is not None and state.status == RunStatus.WAITING
+
+    def is_complete(self) -> bool:
+        """Check if the flow has completed."""
+        from abstractruntime.core.models import RunStatus
+
+        state = self.get_state()
+        return state is not None and state.status == RunStatus.COMPLETED
+
+    def is_failed(self) -> bool:
+        """Check if the flow has failed."""
+        from abstractruntime.core.models import RunStatus
+
+        state = self.get_state()
+        return state is not None and state.status == RunStatus.FAILED
+
+    def __repr__(self) -> str:
+        status = "not started"
+        if self._current_run_id:
+            state = self.get_state()
+            if state:
+                status = state.status.value
+        return f"FlowRunner(flow={self.flow.flow_id!r}, status={status!r})"

abstractflow/visual/__init__.py

@@ -0,0 +1,43 @@
+"""Portable utilities for AbstractFlow visual workflows.
+
+The visual editor saves flows as JSON (nodes/edges). These helpers compile that
+representation into an `abstractflow.Flow` / `abstractruntime.WorkflowSpec` so
+the same workflow can be executed from other hosts (e.g. AbstractCode, CLI),
+not only the web backend.
+"""
+
+from .executor import create_visual_runner, execute_visual_flow, visual_to_flow
+from .models import (
+    ExecutionEvent,
+    FlowCreateRequest,
+    FlowRunRequest,
+    FlowRunResult,
+    FlowUpdateRequest,
+    NodeType,
+    Pin,
+    PinType,
+    Position,
+    VisualEdge,
+    VisualFlow,
+    VisualNode,
+)
+
+__all__ = [
+    "create_visual_runner",
+    "execute_visual_flow",
+    "visual_to_flow",
+    # Models
+    "ExecutionEvent",
+    "FlowCreateRequest",
+    "FlowRunRequest",
+    "FlowRunResult",
+    "FlowUpdateRequest",
+    "NodeType",
+    "Pin",
+    "PinType",
+    "Position",
+    "VisualEdge",
+    "VisualFlow",
+    "VisualNode",
+]
+

abstractflow/visual/agent_ids.py

@@ -0,0 +1,29 @@
+"""Deterministic workflow IDs for VisualFlow Agent nodes.
+
+Visual Agent nodes are compiled into `START_SUBWORKFLOW` effects that reference
+an AbstractAgent ReAct workflow registered in the runtime's WorkflowRegistry.
+
+IDs must be stable across hosts so a VisualFlow JSON document can be executed
+outside the web editor (CLI, AbstractCode, third-party apps).
+"""
+
+from __future__ import annotations
+
+import re
+
+
+_SAFE_ID_RE = re.compile(r"[^a-zA-Z0-9_-]+")
+
+
+def _sanitize(value: str) -> str:
+    value = str(value or "").strip()
+    if not value:
+        return "unknown"
+    value = _SAFE_ID_RE.sub("_", value)
+    return value or "unknown"
+
+
+def visual_react_workflow_id(*, flow_id: str, node_id: str) -> str:
+    """Return the workflow_id used for a VisualFlow Agent node's ReAct subworkflow."""
+    return f"visual_react_agent_{_sanitize(flow_id)}_{_sanitize(node_id)}"
+