kailash 0.2.2__py3-none-any.whl → 0.3.1__py3-none-any.whl

kailash/workflow/cyclic_runner.py

@@ -99,8 +99,8 @@ See Also:
 """
 
 import logging
-from datetime import datetime, timezone
-from typing import Any, Dict, List, Optional, Set, Tuple
+from datetime import UTC, datetime
+from typing import Any, Optional
 
 import networkx as nx
 
@@ -127,15 +127,15 @@ class WorkflowState:
             run_id: Unique execution run ID
         """
         self.run_id = run_id
-        self.node_outputs: Dict[str, Any] = {}
-        self.execution_order: List[str] = []
-        self.metadata: Dict[str, Any] = {}
+        self.node_outputs: dict[str, Any] = {}
+        self.execution_order: list[str] = []
+        self.metadata: dict[str, Any] = {}
 
 
 class CyclicWorkflowExecutor:
     """Execution engine supporting cyclic workflows with fixed parameter propagation."""
 
-    def __init__(self, safety_manager: Optional[CycleSafetyManager] = None):
+    def __init__(self, safety_manager: CycleSafetyManager | None = None):
         """Initialize cyclic workflow executor.
 
         Args:
@@ -148,10 +148,10 @@ class CyclicWorkflowExecutor:
     def execute(
         self,
         workflow: Workflow,
-        parameters: Optional[Dict[str, Any]] = None,
-        task_manager: Optional[TaskManager] = None,
-        run_id: Optional[str] = None,
-    ) -> Tuple[Dict[str, Any], str]:
+        parameters: dict[str, Any] | None = None,
+        task_manager: TaskManager | None = None,
+        run_id: str | None = None,
+    ) -> tuple[dict[str, Any], str]:
         """Execute workflow with cycle support.
 
         Args:
@@ -168,7 +168,7 @@ class CyclicWorkflowExecutor:
             WorkflowValidationError: If workflow is invalid
         """
         # Validate workflow (including cycles)
-        workflow.validate()
+        workflow.validate(runtime_parameters=parameters)
 
         # Generate run ID if not provided
         if not run_id:
@@ -223,10 +223,10 @@ class CyclicWorkflowExecutor:
     def _execute_with_cycles(
         self,
         workflow: Workflow,
-        parameters: Optional[Dict[str, Any]],
+        parameters: dict[str, Any] | None,
         run_id: str,
-        task_manager: Optional[TaskManager] = None,
-    ) -> Dict[str, Any]:
+        task_manager: TaskManager | None = None,
+    ) -> dict[str, Any]:
         """Execute workflow with cycle handling.
 
         Args:
@@ -264,8 +264,8 @@ class CyclicWorkflowExecutor:
     def _create_execution_plan(
         self,
         workflow: Workflow,
-        dag_edges: List[Tuple],
-        cycle_groups: Dict[str, List[Tuple]],
+        dag_edges: list[tuple],
+        cycle_groups: dict[str, list[tuple]],
     ) -> "ExecutionPlan":
         """Create execution plan handling cycles.
 
@@ -329,8 +329,8 @@ class CyclicWorkflowExecutor:
         workflow: Workflow,
         plan: "ExecutionPlan",
         state: WorkflowState,
-        task_manager: Optional[TaskManager] = None,
-    ) -> Dict[str, Any]:
+        task_manager: TaskManager | None = None,
+    ) -> dict[str, Any]:
         """Execute the workflow plan.
 
         Args:
@@ -377,8 +377,8 @@ class CyclicWorkflowExecutor:
         workflow: Workflow,
         cycle_group: "CycleGroup",
         state: WorkflowState,
-        task_manager: Optional[TaskManager] = None,
-    ) -> Dict[str, Any]:
+        task_manager: TaskManager | None = None,
+    ) -> dict[str, Any]:
         """Execute a cycle group with proper parameter propagation.
 
         Args:
@@ -432,7 +432,7 @@ class CyclicWorkflowExecutor:
                         run_id=state.run_id,
                         node_id=f"cycle_group_{cycle_id}",
                         node_type="CycleGroup",
-                        started_at=datetime.now(timezone.utc),
+                        started_at=datetime.now(UTC),
                         metadata={
                             "cycle_id": cycle_id,
                             "max_iterations": cycle_config.get("max_iterations"),
@@ -463,7 +463,7 @@ class CyclicWorkflowExecutor:
                             run_id=state.run_id,
                             node_id=f"cycle_{cycle_id}_iteration_{loop_count}",
                             node_type="CycleIteration",
-                            started_at=datetime.now(timezone.utc),
+                            started_at=datetime.now(UTC),
                             metadata={
                                 "cycle_id": cycle_id,
                                 "iteration": loop_count,
@@ -552,7 +552,7 @@ class CyclicWorkflowExecutor:
                         task_manager.update_task_status(
                             iteration_task_id,
                             TaskStatus.COMPLETED,
-                            ended_at=datetime.now(timezone.utc),
+                            ended_at=datetime.now(UTC),
                             result=iteration_results,
                             metadata={
                                 "converged": (
@@ -579,7 +579,7 @@ class CyclicWorkflowExecutor:
                     task_manager.update_task_status(
                         cycle_task_id,
                         TaskStatus.COMPLETED,
-                        ended_at=datetime.now(timezone.utc),
+                        ended_at=datetime.now(UTC),
                         result=results,
                         metadata={
                             "total_iterations": loop_count,
@@ -603,11 +603,11 @@ class CyclicWorkflowExecutor:
         workflow: Workflow,
         node_id: str,
         state: WorkflowState,
-        cycle_state: Optional[CycleState] = None,
-        cycle_edges: Optional[List[Tuple]] = None,
-        previous_iteration_results: Optional[Dict[str, Any]] = None,
-        task_manager: Optional[TaskManager] = None,
-        iteration: Optional[int] = None,
+        cycle_state: CycleState | None = None,
+        cycle_edges: list[tuple] | None = None,
+        previous_iteration_results: dict[str, Any] | None = None,
+        task_manager: TaskManager | None = None,
+        iteration: int | None = None,
     ) -> Any:
         """Execute a single node with proper parameter handling for cycles.
 
@@ -757,7 +757,7 @@ class CyclicWorkflowExecutor:
                     run_id=state.run_id,
                     node_id=task_node_id,
                     node_type=node.__class__.__name__,
-                    started_at=datetime.now(timezone.utc),
+                    started_at=datetime.now(UTC),
                     metadata=task_metadata,
                 )
                 if task:
@@ -794,7 +794,7 @@ class CyclicWorkflowExecutor:
                         task.task_id,
                         TaskStatus.COMPLETED,
                         result=result,
-                        ended_at=datetime.now(timezone.utc),
+                        ended_at=datetime.now(UTC),
                         metadata={"execution_time": performance_metrics.duration},
                     )
 
@@ -811,7 +811,7 @@ class CyclicWorkflowExecutor:
                         task.task_id,
                         TaskStatus.FAILED,
                         error=str(e),
-                        ended_at=datetime.now(timezone.utc),
+                        ended_at=datetime.now(UTC),
                     )
                 except Exception as update_error:
                     logger.warning(
@@ -831,16 +831,16 @@ class ExecutionPlan:
 
     def __init__(self):
         """Initialize execution plan."""
-        self.stages: List["ExecutionStage"] = []
-        self.cycle_groups: Dict[str, "CycleGroup"] = {}
+        self.stages: list["ExecutionStage"] = []
+        self.cycle_groups: dict[str, "CycleGroup"] = {}
 
     def add_cycle_group(
         self,
         cycle_id: str,
-        nodes: Set[str],
-        entry_nodes: Set[str],
-        exit_nodes: Set[str],
-        edges: List[Tuple],
+        nodes: set[str],
+        entry_nodes: set[str],
+        exit_nodes: set[str],
+        edges: list[tuple],
     ) -> None:
         """Add a cycle group to the plan.
 
@@ -859,7 +859,7 @@ class ExecutionPlan:
             edges=edges,
         )
 
-    def build_stages(self, topo_order: List[str], dag_graph: nx.DiGraph) -> None:
+    def build_stages(self, topo_order: list[str], dag_graph: nx.DiGraph) -> None:
         """Build execution stages.
 
         Args:
@@ -914,7 +914,7 @@ class ExecutionStage:
     def __init__(
         self,
         is_cycle: bool,
-        nodes: Optional[List[str]] = None,
+        nodes: list[str] | None = None,
         cycle_group: Optional["CycleGroup"] = None,
     ):
         """Initialize execution stage.
@@ -935,10 +935,10 @@ class CycleGroup:
     def __init__(
         self,
         cycle_id: str,
-        nodes: Set[str],
-        entry_nodes: Set[str],
-        exit_nodes: Set[str],
-        edges: List[Tuple],
+        nodes: set[str],
+        entry_nodes: set[str],
+        exit_nodes: set[str],
+        edges: list[tuple],
     ):
         """Initialize cycle group.
 
@@ -955,7 +955,7 @@ class CycleGroup:
         self.exit_nodes = exit_nodes
         self.edges = edges
 
-    def get_execution_order(self, full_graph: nx.DiGraph) -> List[str]:
+    def get_execution_order(self, full_graph: nx.DiGraph) -> list[str]:
         """Get execution order for nodes in cycle.
 
         Args:

kailash/workflow/graph.py

@@ -4,8 +4,8 @@ import json
 import logging
 import uuid
 import warnings
-from datetime import datetime, timezone
-from typing import Any, Dict, List, Optional, Tuple
+from datetime import UTC, datetime
+from typing import Any
 
 import networkx as nx
 import yaml
@@ -38,10 +38,10 @@ class NodeInstance(BaseModel):
 
     node_id: str = Field(..., description="Unique identifier for this instance")
     node_type: str = Field(..., description="Type of node")
-    config: Dict[str, Any] = Field(
+    config: dict[str, Any] = Field(
         default_factory=dict, description="Node configuration"
     )
-    position: Tuple[float, float] = Field(default=(0, 0), description="Visual position")
+    position: tuple[float, float] = Field(default=(0, 0), description="Visual position")
 
 
 class Connection(BaseModel):
@@ -59,23 +59,21 @@ class CyclicConnection(Connection):
     cycle: bool = Field(
         default=False, description="Whether this connection creates a cycle"
     )
-    max_iterations: Optional[int] = Field(
+    max_iterations: int | None = Field(
         default=None, description="Maximum cycle iterations"
     )
-    convergence_check: Optional[str] = Field(
+    convergence_check: str | None = Field(
         default=None, description="Convergence condition expression"
     )
-    cycle_id: Optional[str] = Field(
+    cycle_id: str | None = Field(
         default=None, description="Logical cycle group identifier"
     )
-    timeout: Optional[float] = Field(
-        default=None, description="Cycle timeout in seconds"
-    )
-    memory_limit: Optional[int] = Field(default=None, description="Memory limit in MB")
-    condition: Optional[str] = Field(
+    timeout: float | None = Field(default=None, description="Cycle timeout in seconds")
+    memory_limit: int | None = Field(default=None, description="Memory limit in MB")
+    condition: str | None = Field(
         default=None, description="Conditional cycle routing expression"
     )
-    parent_cycle: Optional[str] = Field(
+    parent_cycle: str | None = Field(
         default=None, description="Parent cycle for nested cycles"
     )
 
@@ -90,7 +88,7 @@ class Workflow:
         description: str = "",
         version: str = "1.0.0",
         author: str = "",
-        metadata: Optional[Dict[str, Any]] = None,
+        metadata: dict[str, Any] | None = None,
     ):
         """Initialize a workflow.
 
@@ -118,7 +116,7 @@ class Workflow:
         if "version" not in self.metadata and version:
             self.metadata["version"] = version
         if "created_at" not in self.metadata:
-            self.metadata["created_at"] = datetime.now(timezone.utc).isoformat()
+            self.metadata["created_at"] = datetime.now(UTC).isoformat()
 
         # Create directed graph for the workflow
         self.graph = nx.DiGraph()
@@ -191,10 +189,12 @@ class Workflow:
 
         # Store node instance and metadata
         try:
+            # Use the node instance's actual config, which includes both original config and any updates
+            actual_config = node_instance.config.copy()
             node_instance_data = NodeInstance(
                 node_id=node_id,
                 node_type=node_type,
-                config=config,
+                config=actual_config,
                 position=(len(self.nodes) * 150, 100),
             )
             self.nodes[node_id] = node_instance_data
@@ -203,12 +203,14 @@ class Workflow:
 
         self._node_instances[node_id] = node_instance
 
-        # Add to graph
-        self.graph.add_node(node_id, node=node_instance, type=node_type, config=config)
+        # Add to graph with actual config
+        self.graph.add_node(
+            node_id, node=node_instance, type=node_type, config=actual_config
+        )
         logger.info(f"Added node '{node_id}' of type '{node_type}'")
 
     def _add_node_internal(
-        self, node_id: str, node_type: str, config: Optional[Dict[str, Any]] = None
+        self, node_id: str, node_type: str, config: dict[str, Any] | None = None
     ) -> None:
         """Add a node to the workflow (internal method).
 
@@ -225,15 +227,15 @@ class Workflow:
         self,
         source_node: str,
         target_node: str,
-        mapping: Optional[Dict[str, str]] = None,
+        mapping: dict[str, str] | None = None,
         cycle: bool = False,
-        max_iterations: Optional[int] = None,
-        convergence_check: Optional[str] = None,
-        cycle_id: Optional[str] = None,
-        timeout: Optional[float] = None,
-        memory_limit: Optional[int] = None,
-        condition: Optional[str] = None,
-        parent_cycle: Optional[str] = None,
+        max_iterations: int | None = None,
+        convergence_check: str | None = None,
+        cycle_id: str | None = None,
+        timeout: float | None = None,
+        memory_limit: int | None = None,
+        condition: str | None = None,
+        parent_cycle: str | None = None,
     ) -> None:
         """Connect two nodes in the workflow.
 
@@ -439,7 +441,7 @@ class Workflow:
                 f"Connected '{source_node}' to '{target_node}' with mapping: {mapping}"
             )
 
-    def create_cycle(self, cycle_id: Optional[str] = None):
+    def create_cycle(self, cycle_id: str | None = None):
         """
         Create a new CycleBuilder for intuitive cycle configuration.
 
@@ -537,7 +539,7 @@ class Workflow:
             source_node=from_node, target_node=to_node, mapping={from_output: to_input}
         )
 
-    def get_node(self, node_id: str) -> Optional[Node]:
+    def get_node(self, node_id: str) -> Node | None:
         """Get node instance by ID.
 
         Args:
@@ -557,7 +559,7 @@ class Workflow:
         # Fallback to _node_instances
         return self._node_instances.get(node_id)
 
-    def separate_dag_and_cycle_edges(self) -> Tuple[List[Tuple], List[Tuple]]:
+    def separate_dag_and_cycle_edges(self) -> tuple[list[tuple], list[tuple]]:
         """Separate DAG edges from cycle edges.
 
         Returns:
@@ -574,7 +576,7 @@ class Workflow:
 
         return dag_edges, cycle_edges
 
-    def get_cycle_groups(self) -> Dict[str, List[Tuple]]:
+    def get_cycle_groups(self) -> dict[str, list[tuple]]:
         """Get cycle edges grouped by cycle_id with enhanced multi-node cycle detection.
 
         For multi-node cycles like A → B → C → A where only C → A is marked as cycle,
@@ -674,7 +676,7 @@ class Workflow:
         _, cycle_edges = self.separate_dag_and_cycle_edges()
         return len(cycle_edges) > 0
 
-    def get_execution_order(self) -> List[str]:
+    def get_execution_order(self) -> list[str]:
         """Get topological execution order for nodes, handling cycles gracefully.
 
         Returns:
@@ -707,9 +709,12 @@ class Workflow:
                 # This shouldn't happen, but handle gracefully
                 raise WorkflowValidationError("Unable to determine execution order")
 
-    def validate(self) -> None:
+    def validate(self, runtime_parameters: dict[str, Any] | None = None) -> None:
         """Validate the workflow structure.
 
+        Args:
+            runtime_parameters: Parameters that will be provided at runtime (Session 061)
+
         Raises:
             WorkflowValidationError: If workflow is invalid
         """
@@ -758,14 +763,19 @@ class Workflow:
                         # Check nested config
                         found_in_config = param_name in node_instance.config["config"]
 
-                    if not found_in_config:
+                    # Session 061: Check if parameter will be provided at runtime
+                    found_in_runtime = False
+                    if runtime_parameters and node_id in runtime_parameters:
+                        found_in_runtime = param_name in runtime_parameters[node_id]
+
+                    if not found_in_config and not found_in_runtime:
                         if param_def.default is None:
                             missing_inputs.append(param_name)
 
             if missing_inputs:
                 raise WorkflowValidationError(
                     f"Node '{node_id}' missing required inputs: {missing_inputs}. "
-                    f"Provide these inputs via connections or node configuration"
+                    f"Provide these inputs via connections, node configuration, or runtime parameters"
                 )
 
         logger.info(f"Workflow '{self.name}' validated successfully")
@@ -831,8 +841,8 @@ class Workflow:
                 )
 
     def run(
-        self, task_manager: Optional[TaskManager] = None, **overrides
-    ) -> Tuple[Dict[str, Any], Optional[str]]:
+        self, task_manager: TaskManager | None = None, **overrides
+    ) -> tuple[dict[str, Any], str | None]:
         """Execute the workflow.
 
         Args:
@@ -851,9 +861,9 @@ class Workflow:
 
     def execute(
         self,
-        inputs: Optional[Dict[str, Any]] = None,
-        task_manager: Optional[TaskManager] = None,
-    ) -> Dict[str, Any]:
+        inputs: dict[str, Any] | None = None,
+        task_manager: TaskManager | None = None,
+    ) -> dict[str, Any]:
         """Execute the workflow.
 
         Args:
@@ -951,7 +961,9 @@ class Workflow:
                         )
 
                         # Process each mapping pair
-                        for i, (src, dst) in enumerate(zip(from_outputs, to_inputs)):
+                        for i, (src, dst) in enumerate(
+                            zip(from_outputs, to_inputs, strict=False)
+                        ):
                             if src in source_results:
                                 node_inputs[dst] = source_results[src]
 
@@ -1033,7 +1045,7 @@ class Workflow:
                 f"Failed to export workflow to '{output_path}': {e}"
             ) from e
 
-    def to_dict(self) -> Dict[str, Any]:
+    def to_dict(self) -> dict[str, Any]:
         """Convert workflow to dictionary.
 
         Returns:
@@ -1095,7 +1107,7 @@ class Workflow:
             raise ValueError(f"Unsupported format: {format}")
 
     @classmethod
-    def from_dict(cls, data: Dict[str, Any]) -> "Workflow":
+    def from_dict(cls, data: dict[str, Any]) -> "Workflow":
         """Create workflow from dictionary.
 
         Args:
@@ -1216,9 +1228,9 @@ class Workflow:
         self,
         state_model: BaseModel,
         wrap_state: bool = True,
-        task_manager: Optional[TaskManager] = None,
+        task_manager: TaskManager | None = None,
         **overrides,
-    ) -> Tuple[BaseModel, Dict[str, Any]]:
+    ) -> tuple[BaseModel, dict[str, Any]]:
         """Execute the workflow with state management.
 
         This method provides a simplified interface for executing workflows

kailash/workflow/mermaid_visualizer.py

@@ -5,8 +5,6 @@ offering a text-based format that can be embedded in markdown files and
 rendered in various documentation platforms.
 """
 
-from typing import Dict, Optional, Tuple
-
 from kailash.workflow.graph import Workflow
 
 
@@ -27,7 +25,7 @@ class MermaidVisualizer:
         self,
         workflow: Workflow,
         direction: str = "TB",
-        node_styles: Optional[Dict[str, str]] = None,
+        node_styles: dict[str, str] | None = None,
     ):
         """Initialize the Mermaid visualizer.
 
@@ -40,7 +38,7 @@ class MermaidVisualizer:
         self.direction = direction
         self.node_styles = node_styles or self._default_node_styles()
 
-    def _default_node_styles(self) -> Dict[str, str]:
+    def _default_node_styles(self) -> dict[str, str]:
         """Get default node styles for different node types.
 
         Returns:
@@ -79,7 +77,7 @@ class MermaidVisualizer:
         # Use line break without parentheses to avoid Mermaid parsing issues
         return f"{clean_type}<br/>{node_id}"
 
-    def _get_pattern_edge_label(self, source: str, target: str, data: Dict) -> str:
+    def _get_pattern_edge_label(self, source: str, target: str, data: dict) -> str:
         """Get a pattern-oriented edge label.
 
         Args:
@@ -262,7 +260,7 @@ class MermaidVisualizer:
             return node_type[:-4]
         return node_type
 
-    def _get_node_shape(self, node_type: str) -> Tuple[str, str]:
+    def _get_node_shape(self, node_type: str) -> tuple[str, str]:
         """Get the shape brackets for a node type.
 
         Args:
@@ -460,7 +458,7 @@ class MermaidVisualizer:
 
         return "\n".join(lines)
 
-    def _get_edge_label(self, source: str, target: str, data: Dict) -> str:
+    def _get_edge_label(self, source: str, target: str, data: dict) -> str:
         """Get label for an edge.
 
         Args:
@@ -491,7 +489,7 @@ class MermaidVisualizer:
 
         return ""
 
-    def generate_markdown(self, title: Optional[str] = None) -> str:
+    def generate_markdown(self, title: str | None = None) -> str:
         """Generate a complete markdown section with the Mermaid diagram.
 
         Args:
@@ -559,7 +557,7 @@ class MermaidVisualizer:
 
         return "\n".join(lines)
 
-    def save_markdown(self, filepath: str, title: Optional[str] = None) -> None:
+    def save_markdown(self, filepath: str, title: str | None = None) -> None:
         """Save the Mermaid diagram as a markdown file.
 
         Args:
@@ -596,7 +594,7 @@ def add_mermaid_to_workflow():
         visualizer = MermaidVisualizer(self, direction=direction)
         return visualizer.generate()
 
-    def to_mermaid_markdown(self, title: Optional[str] = None) -> str:
+    def to_mermaid_markdown(self, title: str | None = None) -> str:
         """Generate markdown with embedded Mermaid diagram.
 
         Args:
@@ -608,7 +606,7 @@ def add_mermaid_to_workflow():
         visualizer = MermaidVisualizer(self)
         return visualizer.generate_markdown(title)
 
-    def save_mermaid_markdown(self, filepath: str, title: Optional[str] = None) -> None:
+    def save_mermaid_markdown(self, filepath: str, title: str | None = None) -> None:
         """Save workflow as markdown with Mermaid diagram.
 
         Args: