kailash 0.1.5__py3-none-any.whl → 0.2.1__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]

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",
+]

kailash/nodes/mixins/mcp.py

@@ -0,0 +1,228 @@
+"""MCP Capability Mixin for Nodes.
+
+This mixin provides MCP (Model Context Protocol) capabilities to any node,
+allowing them to discover and use MCP tools without being an LLM agent.
+"""
+
+import asyncio
+from typing import Any, Dict, List, Union
+
+from kailash.mcp import MCPClient
+
+
+class MCPCapabilityMixin:
+    """Mixin to add MCP capabilities to any node.
+
+    This mixin allows non-LLM nodes to interact with MCP servers,
+    discover tools, retrieve resources, and execute tool calls.
+
+    Examples:
+        >>> from kailash.nodes.base import BaseNode
+        >>> from kailash.nodes.mixins.mcp import MCPCapabilityMixin
+        >>>
+        >>> class DataProcessorWithMCP(BaseNode, MCPCapabilityMixin):
+        ...     def run(self, context, **kwargs):
+        ...         # Discover available tools
+        ...         tools = self.discover_mcp_tools_sync(
+        ...             ["http://localhost:8080"]
+        ...         )
+        ...
+        ...         # Call a specific tool
+        ...         result = self.call_mcp_tool_sync(
+        ...             "http://localhost:8080",
+        ...             "process_data",
+        ...             {"data": kwargs.get("data")}
+        ...         )
+        ...
+        ...         return {"processed": result}
+    """
+
+    def __init__(self, *args, **kwargs):
+        """Initialize the mixin."""
+        super().__init__(*args, **kwargs)
+        self._mcp_client = None
+
+    @property
+    def mcp_client(self) -> MCPClient:
+        """Get or create MCP client instance."""
+        if self._mcp_client is None:
+            self._mcp_client = MCPClient()
+        return self._mcp_client
+
+    async def discover_mcp_tools(
+        self, mcp_servers: List[Union[str, Dict[str, Any]]]
+    ) -> List[Dict[str, Any]]:
+        """Discover tools from MCP servers asynchronously.
+
+        Args:
+            mcp_servers: List of MCP server configurations
+
+        Returns:
+            List of discovered tools in OpenAI function format
+        """
+        all_tools = []
+
+        for server in mcp_servers:
+            try:
+                tools = await self.mcp_client.discover_tools(server)
+                all_tools.extend(tools)
+            except Exception as e:
+                # Log error but continue with other servers
+                if hasattr(self, "logger"):
+                    self.logger.warning(f"Failed to discover tools from {server}: {e}")
+
+        return all_tools
+
+    async def call_mcp_tool(
+        self,
+        server_config: Union[str, Dict[str, Any]],
+        tool_name: str,
+        arguments: Dict[str, Any],
+    ) -> Any:
+        """Call an MCP tool asynchronously.
+
+        Args:
+            server_config: MCP server configuration
+            tool_name: Name of the tool to call
+            arguments: Tool arguments
+
+        Returns:
+            Tool execution result
+        """
+        return await self.mcp_client.call_tool(server_config, tool_name, arguments)
+
+    async def list_mcp_resources(
+        self, server_config: Union[str, Dict[str, Any]]
+    ) -> List[Dict[str, Any]]:
+        """List available resources from an MCP server.
+
+        Args:
+            server_config: MCP server configuration
+
+        Returns:
+            List of available resources
+        """
+        return await self.mcp_client.list_resources(server_config)
+
+    async def read_mcp_resource(
+        self, server_config: Union[str, Dict[str, Any]], uri: str
+    ) -> Any:
+        """Read a resource from an MCP server.
+
+        Args:
+            server_config: MCP server configuration
+            uri: Resource URI
+
+        Returns:
+            Resource content
+        """
+        return await self.mcp_client.read_resource(server_config, uri)
+
+    # Synchronous wrappers for non-async nodes
+
+    def discover_mcp_tools_sync(
+        self, mcp_servers: List[Union[str, Dict[str, Any]]]
+    ) -> List[Dict[str, Any]]:
+        """Synchronous wrapper for discovering MCP tools.
+
+        Args:
+            mcp_servers: List of MCP server configurations
+
+        Returns:
+            List of discovered tools
+        """
+        loop = asyncio.new_event_loop()
+        try:
+            return loop.run_until_complete(self.discover_mcp_tools(mcp_servers))
+        finally:
+            loop.close()
+
+    def call_mcp_tool_sync(
+        self,
+        server_config: Union[str, Dict[str, Any]],
+        tool_name: str,
+        arguments: Dict[str, Any],
+    ) -> Any:
+        """Synchronous wrapper for calling MCP tools.
+
+        Args:
+            server_config: MCP server configuration
+            tool_name: Name of the tool to call
+            arguments: Tool arguments
+
+        Returns:
+            Tool execution result
+        """
+        loop = asyncio.new_event_loop()
+        try:
+            return loop.run_until_complete(
+                self.call_mcp_tool(server_config, tool_name, arguments)
+            )
+        finally:
+            loop.close()
+
+    def list_mcp_resources_sync(
+        self, server_config: Union[str, Dict[str, Any]]
+    ) -> List[Dict[str, Any]]:
+        """Synchronous wrapper for listing MCP resources.
+
+        Args:
+            server_config: MCP server configuration
+
+        Returns:
+            List of available resources
+        """
+        loop = asyncio.new_event_loop()
+        try:
+            return loop.run_until_complete(self.list_mcp_resources(server_config))
+        finally:
+            loop.close()
+
+    def read_mcp_resource_sync(
+        self, server_config: Union[str, Dict[str, Any]], uri: str
+    ) -> Any:
+        """Synchronous wrapper for reading MCP resources.
+
+        Args:
+            server_config: MCP server configuration
+            uri: Resource URI
+
+        Returns:
+            Resource content
+        """
+        loop = asyncio.new_event_loop()
+        try:
+            return loop.run_until_complete(self.read_mcp_resource(server_config, uri))
+        finally:
+            loop.close()
+
+    # Helper methods for common patterns
+
+    def get_mcp_parameter_defaults(self) -> Dict[str, Any]:
+        """Get default MCP-related parameters for nodes.
+
+        Returns:
+            Dictionary of MCP parameter defaults
+        """
+        return {"mcp_servers": [], "mcp_context": [], "auto_discover_tools": False}
+
+    def format_mcp_tools_for_display(self, tools: List[Dict[str, Any]]) -> str:
+        """Format MCP tools for human-readable display.
+
+        Args:
+            tools: List of tools in OpenAI format
+
+        Returns:
+            Formatted string representation
+        """
+        if not tools:
+            return "No tools available"
+
+        lines = ["Available MCP Tools:"]
+        for tool in tools:
+            func = tool.get("function", {})
+            name = func.get("name", "unknown")
+            desc = func.get("description", "No description")
+            lines.append(f"  - {name}: {desc}")
+
+        return "\n".join(lines)