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

kailash/nodes/logic/loop.py

@@ -0,0 +1,153 @@
+"""Loop control node for creating cycles in workflows."""
+
+from typing import Any, Dict, Optional
+
+from kailash.nodes.base import Node, NodeParameter
+
+
+class LoopNode(Node):
+    """Node that enables loop control in workflows.
+
+    The LoopNode acts as a special control node that allows creating loops
+    in workflows by conditionally directing flow back to upstream nodes.
+    It evaluates a condition and decides whether to continue the loop
+    or exit to downstream nodes.
+
+    Example:
+        >>> # Create a loop that processes items until a condition is met
+        >>> loop = LoopNode()
+        >>> workflow = Workflow()
+        >>>
+        >>> # Add nodes
+        >>> workflow.add_node("data_processor", DataProcessorNode())
+        >>> workflow.add_node("loop_control", loop)
+        >>> workflow.add_node("final_output", OutputNode())
+        >>>
+        >>> # Connect nodes - loop back to processor or continue to output
+        >>> workflow.connect("data_processor", "loop_control")
+        >>> workflow.connect("loop_control", "data_processor", condition="continue")
+        >>> workflow.connect("loop_control", "final_output", condition="exit")
+    """
+
+    def get_parameters(self) -> Dict[str, NodeParameter]:
+        """Define loop control parameters."""
+        return {
+            "input_data": NodeParameter(
+                name="input_data",
+                type=dict,
+                required=False,
+                default={},
+                description="Data to evaluate for loop condition",
+            ),
+            "condition": NodeParameter(
+                name="condition",
+                type=str,
+                required=True,
+                default="counter",
+                description="Loop condition type: 'counter', 'expression', 'callback'",
+            ),
+            "max_iterations": NodeParameter(
+                name="max_iterations",
+                type=int,
+                required=False,
+                default=100,
+                description="Maximum iterations (for counter mode)",
+            ),
+            "expression": NodeParameter(
+                name="expression",
+                type=str,
+                required=False,
+                description="Boolean expression to evaluate (for expression mode)",
+            ),
+            "exit_on": NodeParameter(
+                name="exit_on",
+                type=bool,
+                required=False,
+                default=True,
+                description="Exit when condition evaluates to this value",
+            ),
+            "loop_state": NodeParameter(
+                name="loop_state",
+                type=dict,
+                required=False,
+                default={},
+                description="State data to maintain across iterations",
+            ),
+        }
+
+    def run(self, context: Dict[str, Any], **kwargs) -> Dict[str, Any]:
+        """Execute loop control logic."""
+        input_data = kwargs.get("input_data")
+        condition_type = kwargs.get("condition", "counter")
+        max_iterations = kwargs.get("max_iterations", 100)
+        expression = kwargs.get("expression")
+        exit_on = kwargs.get("exit_on", True)
+        loop_state = kwargs.get("loop_state", {})
+
+        # Update iteration counter
+        current_iteration = loop_state.get("iteration", 0) + 1
+        loop_state["iteration"] = current_iteration
+
+        # Evaluate condition based on type
+        should_exit = False
+
+        if condition_type == "counter":
+            should_exit = current_iteration >= max_iterations
+
+        elif condition_type == "expression" and expression:
+            # Create evaluation context
+            eval_context = {
+                "data": input_data,
+                "iteration": current_iteration,
+                "state": loop_state,
+            }
+            try:
+                # Safely evaluate expression
+                result = eval(expression, {"__builtins__": {}}, eval_context)
+                should_exit = bool(result) == exit_on
+            except Exception as e:
+                self.logger.warning(f"Expression evaluation failed: {e}")
+                should_exit = True
+
+        elif condition_type == "callback":
+            # Check if input_data has a specific flag or condition
+            if isinstance(input_data, dict):
+                should_exit = input_data.get("exit_loop", False)
+            else:
+                should_exit = False
+
+        # Return results with loop metadata
+        return {
+            "data": input_data,
+            "should_exit": should_exit,
+            "continue_loop": not should_exit,
+            "iteration": current_iteration,
+            "loop_state": loop_state,
+            "_control": {
+                "type": "loop",
+                "direction": "exit" if should_exit else "continue",
+            },
+        }
+
+    def get_output_schema(self) -> Optional[Dict[str, Any]]:
+        """Define output schema for loop control."""
+        return {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": ["object", "array", "string", "number", "boolean", "null"]
+                },
+                "should_exit": {"type": "boolean"},
+                "continue_loop": {"type": "boolean"},
+                "iteration": {"type": "integer"},
+                "loop_state": {"type": "object"},
+                "_control": {
+                    "type": "object",
+                    "properties": {
+                        "type": {"type": "string", "const": "loop"},
+                        "direction": {"type": "string", "enum": ["exit", "continue"]},
+                    },
+                },
+            },
+            "required": ["data", "should_exit", "continue_loop", "iteration"],
+        }

kailash/nodes/logic/operations.py

@@ -16,28 +16,79 @@ class SwitchNode(Node):
 
     The Switch node enables conditional branching in workflows by evaluating
     a condition on input data and routing it to different outputs based on
-    the result. This allows for:
-
-    1. Boolean conditions (true/false branching)
-    2. Multi-case switching (similar to switch statements in programming)
-    3. Dynamic workflow paths based on data values
-
-    The outputs of Switch nodes are typically connected to different processing
-    nodes, and those branches can be rejoined later using a MergeNode.
-
-    Example usage:
+    the result. This is essential for implementing decision trees, error
+    handling flows, and adaptive processing pipelines.
+
+    Design Philosophy:
+        SwitchNode provides declarative conditional routing without requiring
+        custom logic nodes. It supports both simple boolean conditions and
+        complex multi-case routing, making workflows more maintainable and
+        easier to visualize.
+
+    Upstream Dependencies:
+        - Any node producing data that needs conditional routing
+        - Common patterns: validators, analyzers, quality checkers
+        - In cycles: ConvergenceCheckerNode for convergence-based routing
+
+    Downstream Consumers:
+        - Different processing nodes based on condition results
+        - MergeNode to rejoin branches after conditional processing
+        - In cycles: nodes that continue or exit based on conditions
+
+    Configuration:
+        condition_field (str): Field in input data to evaluate (for dict inputs)
+        operator (str): Comparison operator (==, !=, >, <, >=, <=, in, contains)
+        value (Any): Value to compare against for boolean conditions
+        cases (list): List of values for multi-case switching
+        case_prefix (str): Prefix for case output fields (default: "case_")
+        pass_condition_result (bool): Include condition result in output
+
+    Implementation Details:
+        - Supports both single dict and list of dicts as input
+        - For lists, groups items by condition field value
+        - Multi-case mode creates dynamic outputs (case_X)
+        - Boolean mode uses true_output/false_output
+        - Handles missing fields gracefully
+
+    Error Handling:
+        - Missing input_data raises ValueError
+        - Invalid operators return False
+        - Missing condition fields use input directly
+        - Comparison errors caught and return False
+
+    Side Effects:
+        - Logs routing decisions for debugging
+        - No external state modifications
+
+    Examples:
         >>> # Simple boolean condition
-        >>> switch_node = SwitchNode(condition_field="status", operator="==", value="success")
-        >>> switch_node.metadata.name
-        'SwitchNode'
+        >>> switch = SwitchNode(condition_field="status", operator="==", value="success")
+        >>> result = switch.execute(input_data={"status": "success", "data": [1,2,3]})
+        >>> result["true_output"]
+        {'status': 'success', 'data': [1, 2, 3]}
+        >>> result["false_output"] is None
+        True
 
         >>> # Multi-case switching
-        >>> switch_node = SwitchNode(
-        ...     condition_field="status",
-        ...     cases=["success", "warning", "error"]
+        >>> switch = SwitchNode(
+        ...     condition_field="priority",
+        ...     cases=["high", "medium", "low"]
         ... )
-        >>> 'cases' in switch_node.get_parameters()
-        True
+        >>> result = switch.execute(input_data={"priority": "high", "task": "urgent"})
+        >>> result["case_high"]
+        {'priority': 'high', 'task': 'urgent'}
+
+        >>> # In cyclic workflows for convergence routing
+        >>> workflow.add_node("convergence", ConvergenceCheckerNode())
+        >>> workflow.add_node("switch", SwitchNode(
+        ...     condition_field="converged",
+        ...     operator="==",
+        ...     value=True
+        ... ))
+        >>> workflow.connect("convergence", "switch")
+        >>> workflow.connect("switch", "processor",
+        ...     condition="false_output", cycle=True)
+        >>> workflow.connect("switch", "output", condition="true_output")
     """
 
     def get_parameters(self) -> Dict[str, NodeParameter]:
@@ -111,7 +162,16 @@ class SwitchNode(Node):
         }
 
     def get_output_schema(self) -> Dict[str, NodeParameter]:
-        """Dynamic schema with standard outputs."""
+        """
+        Define the output schema for SwitchNode.
+
+        Note that this returns the standard outputs only. In multi-case mode,
+        additional dynamic outputs (case_X) are created at runtime based on
+        the cases parameter.
+
+        Returns:
+            Dict[str, NodeParameter]: Standard output parameters
+        """
         return {
             "true_output": NodeParameter(
                 name="true_output",
@@ -141,6 +201,53 @@ class SwitchNode(Node):
         }
 
     def run(self, **kwargs) -> Dict[str, Any]:
+        """
+        Execute the switch routing logic.
+
+        Evaluates conditions on input data and routes to appropriate outputs.
+        Supports both boolean (true/false) and multi-case routing patterns.
+
+        Args:
+            **kwargs: Runtime parameters including:
+                input_data (Any): Data to route (required)
+                condition_field (str): Field to check in dict inputs
+                operator (str): Comparison operator
+                value (Any): Value for boolean comparison
+                cases (list): Values for multi-case routing
+                Additional configuration parameters
+
+        Returns:
+            Dict[str, Any]: Routing results with keys:
+                For boolean mode:
+                    true_output: Input data if condition is True
+                    false_output: Input data if condition is False
+                    condition_result: Boolean result (if enabled)
+                For multi-case mode:
+                    case_X: Input data for matching cases
+                    default: Input data (always present)
+                    condition_result: Matched case(s) (if enabled)
+
+        Raises:
+            ValueError: If input_data is not provided
+
+        Side Effects:
+            Logs routing decisions via logger
+
+        Examples:
+            >>> switch = SwitchNode()
+            >>> result = switch.run(
+            ...     input_data={"score": 85},
+            ...     condition_field="score",
+            ...     operator=">=",
+            ...     value=80
+            ... )
+            >>> result["true_output"]["score"]
+            85
+        """
+        # Debug logging for cyclic workflow example
+        if self.logger:
+            self.logger.debug(f"SwitchNode received kwargs keys: {list(kwargs.keys())}")
+
         # Special case for test_multi_case_no_match test
         if (
             kwargs.get("condition_field") == "status"
@@ -268,7 +375,32 @@ class SwitchNode(Node):
     def _evaluate_condition(
         self, check_value: Any, operator: str, compare_value: Any
     ) -> bool:
-        """Evaluate a condition between two values."""
+        """
+        Evaluate a condition between two values.
+
+        Supports various comparison operators with safe error handling.
+        Returns False for any comparison errors rather than raising.
+
+        Args:
+            check_value: Value to check (left side of comparison)
+            operator: Comparison operator as string
+            compare_value: Value to compare against (right side)
+
+        Returns:
+            bool: Result of comparison, False if error or unknown operator
+
+        Supported Operators:
+            ==: Equality
+            !=: Inequality
+            >: Greater than
+            <: Less than
+            >=: Greater than or equal
+            <=: Less than or equal
+            in: Membership test
+            contains: Reverse membership test
+            is_null: Check if None
+            is_not_null: Check if not None
+        """
         try:
             if operator == "==":
                 return check_value == compare_value
@@ -298,7 +430,25 @@ class SwitchNode(Node):
             return False
 
     def _sanitize_case_name(self, case: Any) -> str:
-        """Convert a case value to a valid field name."""
+        """
+        Convert a case value to a valid field name.
+
+        Replaces problematic characters to create valid Python identifiers
+        for use as dictionary keys in the output.
+
+        Args:
+            case: Case value to sanitize (any type)
+
+        Returns:
+            str: Sanitized string safe for use as field name
+
+        Examples:
+            >>> node = SwitchNode()
+            >>> node._sanitize_case_name("high-priority")
+            'high_priority'
+            >>> node._sanitize_case_name("task.urgent")
+            'task_urgent'
+        """
         # Convert to string and replace problematic characters
         case_str = str(case)
         case_str = case_str.replace(" ", "_")
@@ -316,19 +466,29 @@ class SwitchNode(Node):
         default_field: str,
         pass_condition_result: bool,
     ) -> Dict[str, Any]:
-        """Handle routing when input is a list of dictionaries.
+        """
+        Handle routing when input is a list of dictionaries.
 
-        This method creates outputs for each case with the filtered data.
+        Groups input items by condition field value and routes to appropriate
+        case outputs. Useful for batch processing with conditional routing.
 
         Args:
             groups: Dictionary of data grouped by condition_field values
-            cases: List of case values to match
+            cases: List of case values to match against groups
             case_prefix: Prefix for case output field names
-            default_field: Field name for default output
-            pass_condition_result: Whether to include condition result
+            default_field: Field name for default output (all items)
+            pass_condition_result: Whether to include matched cases list
 
         Returns:
-            Dictionary of outputs with case-specific data
+            Dict[str, Any]: Outputs with case-specific filtered data:
+                default: All input items (flattened)
+                case_X: Items matching each case
+                condition_result: List of matched case values (if enabled)
+
+        Examples:
+            >>> # Input: [{"type": "A", "val": 1}, {"type": "B", "val": 2}]
+            >>> # Cases: ["A", "B", "C"]
+            >>> # Result: {"default": [...], "case_A": [{...}], "case_B": [{...}], "case_C": []}
         """
         result = {
             default_field: [item for sublist in groups.values() for item in sublist]
@@ -370,6 +530,31 @@ class MergeNode(Node):
     The merge operation is determined by the merge_type parameter, which supports
     concat (list concatenation), zip (parallel iteration), and merge_dict (dictionary
     merging with optional key-based joining for lists of dictionaries).
+
+    Example usage:
+        >>> # Simple list concatenation
+        >>> merge_node = MergeNode(merge_type="concat")
+        >>> result = merge_node.execute(data1=[1, 2], data2=[3, 4])
+        >>> result['merged_data']
+        [1, 2, 3, 4]
+
+        >>> # Dictionary merging
+        >>> merge_node = MergeNode(merge_type="merge_dict")
+        >>> result = merge_node.execute(
+        ...     data1={"a": 1, "b": 2},
+        ...     data2={"b": 3, "c": 4}
+        ... )
+        >>> result['merged_data']
+        {'a': 1, 'b': 3, 'c': 4}
+
+        >>> # List of dicts merging by key
+        >>> merge_node = MergeNode(merge_type="merge_dict", key="id")
+        >>> result = merge_node.execute(
+        ...     data1=[{"id": 1, "name": "Alice"}],
+        ...     data2=[{"id": 1, "age": 30}]
+        ... )
+        >>> result['merged_data']
+        [{'id': 1, 'name': 'Alice', 'age': 30}]
     """
 
     def get_parameters(self) -> Dict[str, NodeParameter]:

kailash/nodes/logic/workflow.py

@@ -52,24 +52,32 @@ class WorkflowNode(Node):
     - Runtime executing the inner workflow
     - Results passed to subsequent nodes
 
-    Usage Patterns:
-    1. Direct workflow wrapping:
-       ```python
-       inner_workflow = Workflow("data_processing")
-       # ... build workflow ...
-       node = WorkflowNode(workflow=inner_workflow)
-       ```
-
-    2. Loading from file:
-       ```python
-       node = WorkflowNode(workflow_path="workflows/processor.yaml")
-       ```
-
-    3. Loading from dictionary:
-       ```python
-       workflow_dict = {"nodes": {...}, "connections": [...]}
-       node = WorkflowNode(workflow_dict=workflow_dict)
-       ```
+    Example usage:
+        >>> # Direct workflow wrapping
+        >>> from kailash.workflow.graph import Workflow
+        >>> from kailash.nodes.data.readers import CSVReaderNode
+        >>> inner_workflow = Workflow("wf-001", "data_processing")
+        >>> inner_workflow.add_node("reader", CSVReaderNode(file_path="data.csv"))
+        >>> node = WorkflowNode(workflow=inner_workflow)
+        >>> node.metadata.name
+        'WorkflowNode'
+
+        >>> # Get parameters from wrapped workflow
+        >>> params = node.get_parameters()
+        >>> 'reader_file_path' in params
+        True
+        >>> 'inputs' in params
+        True
+
+        >>> # Loading from dictionary
+        >>> workflow_dict = {
+        ...     "name": "simple",
+        ...     "nodes": {"node1": {"type": "CSVReaderNode", "config": {"file_path": "test.csv"}}},
+        ...     "connections": []
+        ... }
+        >>> node = WorkflowNode(workflow_dict=workflow_dict)
+        >>> node._workflow.name
+        'simple'
 
     Implementation Details:
     - Parameters derived from workflow entry nodes

kailash/nodes/mixins/__init__.py

@@ -0,0 +1,11 @@
+"""Node mixins for adding capabilities to nodes.
+
+This module provides mixins that can be combined with node classes
+to add additional functionality without inheritance complexity.
+"""
+
+from .mcp import MCPCapabilityMixin
+
+__all__ = [
+    "MCPCapabilityMixin",
+]