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

kailash/workflow/cycle_builder.py

@@ -8,7 +8,7 @@ full backward compatibility with existing workflow construction methods.
 
 Examples:
     Basic cycle creation:
-    
+
     >>> workflow = Workflow("optimization", "Optimization Loop")
     >>> cycle = workflow.create_cycle("quality_improvement")
     >>> cycle.connect("processor", "evaluator") \
@@ -16,9 +16,9 @@ Examples:
     ...      .converge_when("quality > 0.9") \
     ...      .timeout(300) \
     ...      .build()
-    
+
     Advanced configuration:
-    
+
     >>> cycle = workflow.create_cycle("complex_optimization") \
     ...     .connect("optimizer", "evaluator", {"result": "input_data"}) \
     ...     .max_iterations(100) \
@@ -28,9 +28,9 @@ Examples:
     ...     .when("needs_optimization == True") \
     ...     .nested_in("outer_cycle") \
     ...     .build()
-    
+
     Template integration:
-    
+
     >>> from kailash.workflow.cycle_config import CycleTemplates
     >>> config = CycleTemplates.optimization_loop(max_iterations=50)
     >>> cycle = CycleBuilder.from_config(workflow, config) \
@@ -40,17 +40,17 @@ Examples:
 """
 
 import logging
-from typing import Dict, Optional, TYPE_CHECKING
+from typing import TYPE_CHECKING, Dict, Optional
 
 from kailash.sdk_exceptions import WorkflowValidationError
 from kailash.workflow.cycle_exceptions import (
     CycleConfigurationError,
-    CycleConnectionError
+    CycleConnectionError,
 )
 
 if TYPE_CHECKING:
-    from .graph import Workflow
     from .cycle_config import CycleConfig
+    from .graph import Workflow
 
 logger = logging.getLogger(__name__)
 
@@ -59,13 +59,13 @@ class CycleBuilder:
     """
     Fluent builder for creating cyclic workflow connections.
 
-    This class provides an intuitive, chainable API for configuring cyclic 
+    This class provides an intuitive, chainable API for configuring cyclic
     connections in workflows. It replaces the verbose parameter-heavy approach
     with a more discoverable and type-safe builder pattern.
 
     Examples:
         Creating a basic cycle:
-        
+
         >>> workflow = Workflow("optimization", "Optimization Loop")
         >>> cycle = workflow.create_cycle("quality_improvement")
         >>> cycle.connect("processor", "evaluator") \
@@ -85,12 +85,12 @@ class CycleBuilder:
         """
         self._workflow = workflow
         self._cycle_id = cycle_id
-        
+
         # Connection parameters
         self._source_node: Optional[str] = None
         self._target_node: Optional[str] = None
         self._mapping: Optional[Dict[str, str]] = None
-        
+
         # Cycle parameters
         self._max_iterations: Optional[int] = None
         self._convergence_check: Optional[str] = None
@@ -99,20 +99,24 @@ class CycleBuilder:
         self._condition: Optional[str] = None
         self._parent_cycle: Optional[str] = None
 
-    def connect(self, source_node: str, target_node: str, 
-                mapping: Optional[Dict[str, str]] = None) -> "CycleBuilder":
+    def connect(
+        self,
+        source_node: str,
+        target_node: str,
+        mapping: Optional[Dict[str, str]] = None,
+    ) -> "CycleBuilder":
         """
         Configure the source and target nodes for the cycle connection.
 
-        Establishes which nodes will be connected in a cyclic pattern. The 
-        mapping parameter defines how outputs from the source node map to 
+        Establishes which nodes will be connected in a cyclic pattern. The
+        mapping parameter defines how outputs from the source node map to
         inputs of the target node.
 
         Args:
             source_node: Node ID that produces output for the cycle.
             target_node: Node ID that receives input from the cycle.
-            mapping: Output-to-input mapping. Keys are source output fields, 
-                values are target input fields. If None, attempts automatic 
+            mapping: Output-to-input mapping. Keys are source output fields,
+                values are target input fields. If None, attempts automatic
                 mapping based on parameter names.
 
         Returns:
@@ -129,27 +133,27 @@ class CycleBuilder:
         """
         # Validate nodes exist in workflow
         available_nodes = list(self._workflow.nodes.keys())
-        
+
         if source_node not in self._workflow.nodes:
             raise CycleConnectionError(
                 f"Source node '{source_node}' not found in workflow",
                 source_node=source_node,
                 available_nodes=available_nodes,
-                error_code="CYCLE_CONN_001"
+                error_code="CYCLE_CONN_001",
             )
-        
+
         if target_node not in self._workflow.nodes:
             raise CycleConnectionError(
                 f"Target node '{target_node}' not found in workflow",
                 target_node=target_node,
                 available_nodes=available_nodes,
-                error_code="CYCLE_CONN_002"
+                error_code="CYCLE_CONN_002",
             )
 
         self._source_node = source_node
         self._target_node = target_node
         self._mapping = mapping
-        
+
         return self
 
     def max_iterations(self, iterations: int) -> "CycleBuilder":
@@ -160,7 +164,7 @@ class CycleBuilder:
         This is a critical safety mechanism for production workflows.
 
         Args:
-            iterations: Maximum number of iterations allowed. Must be positive. 
+            iterations: Maximum number of iterations allowed. Must be positive.
                 Recommended range: 10-1000 depending on use case.
 
         Returns:
@@ -182,10 +186,10 @@ class CycleBuilder:
                 suggestions=[
                     "Use 10-100 iterations for quick convergence",
                     "Use 100-1000 iterations for complex optimization",
-                    "Consider adding convergence_check for early termination"
-                ]
+                    "Consider adding convergence_check for early termination",
+                ],
             )
-        
+
         self._max_iterations = iterations
         return self
 
@@ -193,8 +197,8 @@ class CycleBuilder:
         """
         Set the convergence condition to terminate the cycle early.
 
-        Defines an expression that, when true, will stop cycle execution 
-        before reaching max_iterations. This enables efficient early 
+        Defines an expression that, when true, will stop cycle execution
+        before reaching max_iterations. This enables efficient early
         termination when the desired result is achieved.
 
         Args:
@@ -218,16 +222,16 @@ class CycleBuilder:
                 "Convergence condition must be a non-empty string expression. "
                 "Examples: 'error < 0.01', 'quality > 0.9', 'count >= 10'"
             )
-        
+
         # Basic validation - check for dangerous operations
-        dangerous_patterns = ['import ', 'exec(', 'eval(', '__']
+        dangerous_patterns = ["import ", "exec(", "eval(", "__"]
         for pattern in dangerous_patterns:
             if pattern in condition:
                 raise CycleConfigurationError(
                     f"Convergence condition contains potentially unsafe operation: '{pattern}'. "
                     "Use simple comparison expressions only."
                 )
-        
+
         self._convergence_check = condition
         return self
 
@@ -235,12 +239,12 @@ class CycleBuilder:
         """
         Set a timeout limit for cycle execution.
 
-        Provides time-based safety limit to prevent cycles from running 
-        indefinitely. Useful for cycles that might have unpredictable 
+        Provides time-based safety limit to prevent cycles from running
+        indefinitely. Useful for cycles that might have unpredictable
         convergence times.
 
         Args:
-            seconds: Maximum execution time in seconds. Must be positive. 
+            seconds: Maximum execution time in seconds. Must be positive.
                 Recommended: 30-3600 seconds.
 
         Returns:
@@ -259,7 +263,7 @@ class CycleBuilder:
                 "Recommendation: Use 30-300 seconds for most cycles, "
                 "up to 3600 seconds for long-running optimization."
             )
-        
+
         self._timeout = seconds
         return self
 
@@ -271,7 +275,7 @@ class CycleBuilder:
         excessive memory through data accumulation across iterations.
 
         Args:
-            mb: Maximum memory usage in megabytes. Must be positive. 
+            mb: Maximum memory usage in megabytes. Must be positive.
                 Recommended: 100-10000 MB.
 
         Returns:
@@ -290,7 +294,7 @@ class CycleBuilder:
                 "Recommendation: Use 100-1000 MB for most cycles, "
                 "up to 10000 MB for data-intensive processing."
             )
-        
+
         self._memory_limit = mb
         return self
 
@@ -298,7 +302,7 @@ class CycleBuilder:
         """
         Set a conditional expression for cycle routing.
 
-        Enables conditional cycle execution where the cycle only runs 
+        Enables conditional cycle execution where the cycle only runs
         when the specified condition is met. Useful for adaptive workflows.
 
         Args:
@@ -320,7 +324,7 @@ class CycleBuilder:
                 "Condition must be a non-empty string expression. "
                 "Examples: 'retry_count < 3', 'needs_improvement == True'"
             )
-        
+
         self._condition = condition
         return self
 
@@ -328,8 +332,8 @@ class CycleBuilder:
         """
         Make this cycle nested within another cycle.
 
-        Enables hierarchical cycle structures where one cycle operates 
-        within the iterations of a parent cycle. Useful for multi-level 
+        Enables hierarchical cycle structures where one cycle operates
+        within the iterations of a parent cycle. Useful for multi-level
         optimization scenarios.
 
         Args:
@@ -345,10 +349,8 @@ class CycleBuilder:
             >>> cycle.nested_in("outer_optimization")  # This cycle runs inside outer_optimization
         """
         if not parent_cycle_id or not isinstance(parent_cycle_id, str):
-            raise CycleConfigurationError(
-                "Parent cycle ID must be a non-empty string"
-            )
-        
+            raise CycleConfigurationError("Parent cycle ID must be a non-empty string")
+
         self._parent_cycle = parent_cycle_id
         return self
 
@@ -356,8 +358,8 @@ class CycleBuilder:
         """
         Build and add the configured cycle to the workflow.
 
-        Validates the cycle configuration and creates the actual cyclic 
-        connection in the workflow. This finalizes the cycle builder 
+        Validates the cycle configuration and creates the actual cyclic
+        connection in the workflow. This finalizes the cycle builder
         pattern and applies all configured settings.
 
         Raises:
@@ -376,15 +378,19 @@ class CycleBuilder:
                 "Cycle must have source and target nodes configured. "
                 "Call connect(source_node, target_node) before build()."
             )
-        
+
         # Validate at least one termination condition
-        if not self._max_iterations and not self._convergence_check and not self._timeout:
+        if (
+            not self._max_iterations
+            and not self._convergence_check
+            and not self._timeout
+        ):
             raise CycleConfigurationError(
                 "Cycle must have at least one termination condition. "
                 "Add max_iterations(), converge_when(), or timeout() before build(). "
                 "Recommendation: Always include max_iterations() as a safety net."
             )
-        
+
         # Create the connection using the workflow's connect method
         try:
             self._workflow.connect(
@@ -398,16 +404,16 @@ class CycleBuilder:
                 timeout=self._timeout,
                 memory_limit=self._memory_limit,
                 condition=self._condition,
-                parent_cycle=self._parent_cycle
+                parent_cycle=self._parent_cycle,
             )
-            
+
             logger.info(
                 f"Created cycle '{self._cycle_id or 'unnamed'}' from "
                 f"{self._source_node} to {self._target_node} with "
                 f"max_iterations={self._max_iterations}, "
                 f"convergence='{self._convergence_check}'"
             )
-            
+
         except Exception as e:
             raise WorkflowValidationError(
                 f"Failed to create cycle connection: {e}"
@@ -436,13 +442,13 @@ class CycleBuilder:
 
         Examples:
             Using a template:
-            
+
             >>> config = CycleTemplates.optimization_loop(max_iterations=50)
             >>> builder = CycleBuilder.from_config(workflow, config)
             >>> builder.connect("optimizer", "evaluator").build()
-            
+
             Using custom configuration:
-            
+
             >>> config = CycleConfig(max_iterations=100, timeout=300)
             >>> builder = CycleBuilder.from_config(workflow, config)
             >>> builder.connect("processor", "evaluator").build()
@@ -463,27 +469,27 @@ class CycleBuilder:
 
         # Create builder with config values
         builder = cls(workflow=workflow, cycle_id=config.cycle_id)
-        
+
         # Apply configuration parameters
         if config.max_iterations is not None:
             builder._max_iterations = config.max_iterations
-        
+
         if config.convergence_check is not None:
             if isinstance(config.convergence_check, str):
                 builder._convergence_check = config.convergence_check
             else:
                 # For callable convergence checks, convert to description
                 builder._convergence_check = "<callable_convergence_check>"
-        
+
         if config.timeout is not None:
             builder._timeout = config.timeout
-        
+
         if config.memory_limit is not None:
             builder._memory_limit = config.memory_limit
-        
+
         if config.condition is not None:
             builder._condition = config.condition
-        
+
         if config.parent_cycle is not None:
             builder._parent_cycle = config.parent_cycle
 
@@ -528,20 +534,20 @@ class CycleBuilder:
         # Apply non-None configuration values
         if config.max_iterations is not None:
             self._max_iterations = config.max_iterations
-        
+
         if config.convergence_check is not None:
             if isinstance(config.convergence_check, str):
                 self._convergence_check = config.convergence_check
-        
+
         if config.timeout is not None:
             self._timeout = config.timeout
-        
+
         if config.memory_limit is not None:
             self._memory_limit = config.memory_limit
-        
+
         if config.condition is not None:
             self._condition = config.condition
-        
+
         if config.parent_cycle is not None:
             self._parent_cycle = config.parent_cycle
 
@@ -570,4 +576,4 @@ class CycleBuilder:
             f"max_iterations={self._max_iterations}, "
             f"convergence='{self._convergence_check}'"
             f")"
-        )
+        )