kailash 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

kailash/nodes/logic/async_operations.py

@@ -13,14 +13,14 @@ from kailash.nodes.base_async import AsyncNode
 
 
 @register_node()
-class AsyncMerge(AsyncNode):
+class AsyncMergeNode(AsyncNode):
     """Asynchronously merges multiple data sources.
 
     Note: We implement run() to fulfill the Node abstract base class requirement,
     but it's just a pass-through to async_run().
 
 
-    This node extends the standard Merge node with asynchronous execution capabilities,
+    This node extends the standard MergeNode with asynchronous execution capabilities,
     making it more efficient for:
 
     1. Combining large datasets from parallel branches
@@ -28,23 +28,33 @@ class AsyncMerge(AsyncNode):
     3. Processing streaming data in chunks
     4. Aggregating results from various API calls
 
-    The merge operation supports the same types as the standard Merge node:
+    The merge operation supports the same types as the standard MergeNode:
     concat (list concatenation), zip (parallel iteration), and merge_dict
     (dictionary merging with optional key-based joining).
 
-    Usage example:
-        # Create an AsyncMerge node in a workflow
-        async_merge = AsyncMerge(merge_type="merge_dict", key="id")
-        workflow.add_node("data_combine", async_merge)
-
-        # Connect multiple data sources
-        workflow.connect("api_results", "data_combine", {"output": "data1"})
-        workflow.connect("database_query", "data_combine", {"results": "data2"})
-        workflow.connect("file_processor", "data_combine", {"processed_data": "data3"})
+    Example usage:
+        >>> # Create an AsyncMergeNode
+        >>> async_merge = AsyncMergeNode(merge_type="merge_dict", key="id")
+        >>> async_merge.metadata.name
+        'AsyncMergeNode'
+
+        >>> # Using in a workflow
+        >>> from kailash.workflow.graph import Workflow
+        >>> workflow = Workflow("wf-001", "async_example")
+        >>> workflow.add_node("data_combine", async_merge)
+        >>> "data_combine" in workflow.nodes
+        True
+
+        >>> # Async execution with concat
+        >>> import asyncio
+        >>> async_merge = AsyncMergeNode(merge_type="concat")
+        >>> result = asyncio.run(async_merge.execute_async(data1=[1, 2], data2=[3, 4]))
+        >>> result['merged_data']
+        [1, 2, 3, 4]
     """
 
     def get_parameters(self) -> Dict[str, NodeParameter]:
-        """Define parameters for the AsyncMerge node."""
+        """Define parameters for the AsyncMergeNode."""
         # Reuse parameters from SyncMerge
         return {
             "data1": NodeParameter(
@@ -107,7 +117,7 @@ class AsyncMerge(AsyncNode):
         }
 
     def get_output_schema(self) -> Dict[str, NodeParameter]:
-        """Define the output schema for AsyncMerge."""
+        """Define the output schema for AsyncMergeNode."""
         return {
             "merged_data": NodeParameter(
                 name="merged_data",
@@ -155,7 +165,7 @@ class AsyncMerge(AsyncNode):
 
         # Check if we have at least one valid input
         if not data_inputs:
-            self.logger.warning("No valid data inputs provided to AsyncMerge node")
+            self.logger.warning("No valid data inputs provided to AsyncMergeNode")
             return {"merged_data": None}
 
         # If only one input was provided, return it directly
@@ -207,7 +217,7 @@ class AsyncMerge(AsyncNode):
         # This will be properly wrapped by the execute() method
         # which will call it in a sync context
         raise RuntimeError(
-            "AsyncMerge.run() was called directly. Use execute() or execute_async() instead."
+            "AsyncMergeNode.run() was called directly. Use execute() or execute_async() instead."
         )
 
     async def _async_concat(self, data_inputs: List[Any], chunk_size: int) -> Any:
@@ -349,25 +359,54 @@ class AsyncMerge(AsyncNode):
 
 
 @register_node()
-class AsyncSwitch(AsyncNode):
+class AsyncSwitchNode(AsyncNode):
     """Asynchronously routes data to different outputs based on conditions.
 
     Note: We implement run() to fulfill the Node abstract base class requirement,
     but it's just a pass-through to async_run().
 
-    This node extends the standard Switch node with asynchronous execution capabilities,
+    This node extends the standard SwitchNode with asynchronous execution capabilities,
     making it more efficient for:
 
     1. Processing conditional routing with I/O-bound condition evaluation
     2. Handling large datasets that need to be routed based on complex criteria
     3. Integrating with other asynchronous nodes in a workflow
 
-    The basic functionality is the same as the synchronous Switch node but optimized
+    The basic functionality is the same as the synchronous SwitchNode but optimized
     for asynchronous execution.
+
+    Example usage:
+        >>> # Boolean condition routing
+        >>> import asyncio
+        >>> async_switch = AsyncSwitchNode(
+        ...     condition_field="status",
+        ...     operator="==",
+        ...     value="active"
+        ... )
+        >>> result = asyncio.run(async_switch.execute_async(
+        ...     input_data={"status": "active", "data": "test"}
+        ... ))
+        >>> result['true_output']
+        {'status': 'active', 'data': 'test'}
+        >>> result['false_output'] is None
+        True
+
+        >>> # Multi-case switching
+        >>> async_switch = AsyncSwitchNode(
+        ...     condition_field="priority",
+        ...     cases=["high", "medium", "low"]
+        ... )
+        >>> result = asyncio.run(async_switch.execute_async(
+        ...     input_data={"priority": "high", "task": "urgent"}
+        ... ))
+        >>> result['case_high']
+        {'priority': 'high', 'task': 'urgent'}
+        >>> result['default']
+        {'priority': 'high', 'task': 'urgent'}
     """
 
     def get_parameters(self) -> Dict[str, NodeParameter]:
-        """Define parameters for the AsyncSwitch node."""
+        """Define parameters for the AsyncSwitchNode."""
         return {
             "input_data": NodeParameter(
                 name="input_data",
@@ -603,7 +642,7 @@ class AsyncSwitch(AsyncNode):
         # This will be properly wrapped by the execute() method
         # which will call it in a sync context
         raise RuntimeError(
-            "AsyncSwitch.run() was called directly. Use execute() or execute_async() instead."
+            "AsyncSwitchNode.run() was called directly. Use execute() or execute_async() instead."
         )
 
     async def _evaluate_condition(

kailash/nodes/logic/operations.py

@@ -11,7 +11,7 @@ from kailash.nodes.base import Node, NodeParameter, register_node
 
 
 @register_node()
-class Switch(Node):
+class SwitchNode(Node):
     """Routes data to different outputs based on conditions.
 
     The Switch node enables conditional branching in workflows by evaluating
@@ -23,25 +23,21 @@ class Switch(Node):
     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 Merge node.
-
-    Example usage::
-
-        # Simple boolean condition
-        switch_node = Switch(condition_field="status", operator="==", value="success")
-        workflow.add_node("router", switch_node)
-        workflow.connect("router", "success_handler", {"true_output": "input"})
-        workflow.connect("router", "error_handler", {"false_output": "input"})
-
-        # Multi-case switching
-        switch_node = Switch(
-            condition_field="status",
-            cases=["success", "warning", "error"]
-        )
-        workflow.connect("router", "success_handler", {"case_success": "input"})
-        workflow.connect("router", "warning_handler", {"case_warning": "input"})
-        workflow.connect("router", "error_handler", {"case_error": "input"})
-        workflow.connect("router", "default_handler", {"default": "input"})
+    nodes, and those branches can be rejoined later using a MergeNode.
+
+    Example usage:
+        >>> # Simple boolean condition
+        >>> switch_node = SwitchNode(condition_field="status", operator="==", value="success")
+        >>> switch_node.metadata.name
+        'SwitchNode'
+
+        >>> # Multi-case switching
+        >>> switch_node = SwitchNode(
+        ...     condition_field="status",
+        ...     cases=["success", "warning", "error"]
+        ... )
+        >>> 'cases' in switch_node.get_parameters()
+        True
     """
 
     def get_parameters(self) -> Dict[str, NodeParameter]:
@@ -360,7 +356,7 @@ class Switch(Node):
 
 
 @register_node()
-class Merge(Node):
+class MergeNode(Node):
     """Merges multiple data sources.
 
     This node can combine data from multiple input sources in various ways,
@@ -368,12 +364,37 @@ class Merge(Node):
 
     1. Combining results from parallel branches in a workflow
     2. Joining related data sets
-    3. Combining outputs after conditional branching with the Switch node
+    3. Combining outputs after conditional branching with the SwitchNode
     4. Aggregating collections of data
 
     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/mcp/client.py

@@ -22,7 +22,7 @@ class MCPClient(Node):
     - Input parameters for resource requests and tool calls
 
     Downstream Consumers:
-    - LLMAgent nodes that need context from MCP servers
+    - LLMAgentNode nodes that need context from MCP servers
     - Workflow nodes that orchestrate multi-step MCP interactions
     - Data processing nodes that consume MCP resources
 
@@ -53,38 +53,34 @@ class MCPClient(Node):
     - Logs connection events and errors for debugging
 
     Examples:
-
-        Connect to an MCP server and list resources::
-
-        client = MCPClient()
-        result = client.run(
-            server_config={
-                "name": "filesystem-server",
-                "command": "python",
-                "args": ["-m", "mcp_filesystem"]
-            },
-            operation="list_resources"
-        )
-
-        Fetch a specific resource:
-
-        resource = client.run(
-            server_config=server_config,
-            operation="read_resource",
-            resource_uri="file:///path/to/document.txt"
-        )
-
-        Call a tool on the server:
-
-        tool_result = client.run(
-            server_config=server_config,
-            operation="call_tool",
-            tool_name="create_file",
-            tool_arguments={
-                "path": "/path/to/new_file.txt",
-                "content": "Hello, World!"
-            }
-        )
+        >>> # Connect to an MCP server and list resources
+        >>> client = MCPClient()
+        >>> result = client.run(
+        ...     server_config={
+        ...         "name": "filesystem-server",
+        ...         "command": "python",
+        ...         "args": ["-m", "mcp_filesystem"]
+        ...     },
+        ...     operation="list_resources"
+        ... )
+
+        >>> # Fetch a specific resource
+        >>> resource = client.run(
+        ...     server_config=server_config,
+        ...     operation="read_resource",
+        ...     resource_uri="file:///path/to/document.txt"
+        ... )
+
+        >>> # Call a tool on the server
+        >>> tool_result = client.run(
+        ...     server_config=server_config,
+        ...     operation="call_tool",
+        ...     tool_name="create_file",
+        ...     tool_arguments={
+        ...         "path": "/path/to/new_file.txt",
+        ...         "content": "Hello, World!"
+        ...     }
+        ... )
     """
 
     def get_parameters(self) -> Dict[str, NodeParameter]:

kailash/nodes/transform/__init__.py

@@ -6,10 +6,17 @@ from kailash.nodes.transform.formatters import (
     ContextFormatterNode,
     QueryTextWrapperNode,
 )
-from kailash.nodes.transform.processors import DataTransformer, Filter, Map, Sort
+from kailash.nodes.transform.processors import (
+    DataTransformer,
+    Filter,
+    FilterNode,
+    Map,
+    Sort,
+)
 
 __all__ = [
     "Filter",
+    "FilterNode",
     "Map",
     "Sort",
     "DataTransformer",

kailash/nodes/transform/formatters.py

@@ -90,7 +90,7 @@ Context:
 
 Please provide a comprehensive answer based on the information provided above."""
 
-        # Create messages list for LLMAgent
+        # Create messages list for LLMAgentNode
         messages = [{"role": "user", "content": prompt}]
 
         return {"formatted_prompt": prompt, "messages": messages, "context": context}

kailash/nodes/transform/processors.py

@@ -7,8 +7,117 @@ from kailash.nodes.base import Node, NodeParameter, register_node
 
 
 @register_node()
-class Filter(Node):
-    """Filters data based on a condition."""
+class FilterNode(Node):
+    """
+    Filters data based on configurable conditions and operators.
+
+    This node provides flexible data filtering capabilities for lists and collections,
+    supporting various comparison operators and field-based filtering for structured
+    data. It's designed to work seamlessly in data processing pipelines, reducing
+    datasets to items that match specific criteria.
+
+    Design Philosophy:
+        The FilterNode embodies the principle of "declarative data selection." Rather
+        than writing custom filtering code, users declare their filtering criteria
+        through simple configuration. The design supports both simple value filtering
+        and complex field-based filtering for dictionaries, making it versatile for
+        various data structures.
+
+    Upstream Dependencies:
+        - Data source nodes providing lists to filter
+        - Transform nodes producing structured data
+        - Aggregation nodes generating collections
+        - API nodes returning result sets
+        - File readers loading datasets
+
+    Downstream Consumers:
+        - Processing nodes working with filtered subsets
+        - Aggregation nodes summarizing filtered data
+        - Writer nodes exporting filtered results
+        - Visualization nodes displaying subsets
+        - Decision nodes based on filter results
+
+    Configuration:
+        The node supports flexible filtering options:
+        - Field selection for dictionary filtering
+        - Multiple comparison operators
+        - Type-aware comparisons
+        - Null value handling
+        - String contains operations
+
+    Implementation Details:
+        - Handles lists of any type (dicts, primitives, objects)
+        - Type coercion for numeric comparisons
+        - Null-safe operations
+        - String conversion for contains operator
+        - Preserves original data structure
+        - Zero-copy filtering (returns references)
+
+    Error Handling:
+        - Graceful handling of type mismatches
+        - Null value comparison logic
+        - Empty data returns empty result
+        - Invalid field names return no matches
+        - Operator errors fail safely
+
+    Side Effects:
+        - No side effects (pure function)
+        - Does not modify input data
+        - Returns new filtered list
+
+    Examples:
+        >>> # Filter list of numbers
+        >>> filter_node = FilterNode()
+        >>> result = filter_node.run(
+        ...     data=[1, 2, 3, 4, 5],
+        ...     operator=">",
+        ...     value=3
+        ... )
+        >>> assert result["filtered_data"] == [4, 5]
+        >>>
+        >>> # Filter list of dictionaries by field
+        >>> users = [
+        ...     {"name": "Alice", "age": 30},
+        ...     {"name": "Bob", "age": 25},
+        ...     {"name": "Charlie", "age": 35}
+        ... ]
+        >>> result = filter_node.run(
+        ...     data=users,
+        ...     field="age",
+        ...     operator=">=",
+        ...     value=30
+        ... )
+        >>> assert len(result["filtered_data"]) == 2
+        >>> assert result["filtered_data"][0]["name"] == "Alice"
+        >>>
+        >>> # String contains filtering
+        >>> items = [
+        ...     {"title": "Python Programming"},
+        ...     {"title": "Java Development"},
+        ...     {"title": "Python for Data Science"}
+        ... ]
+        >>> result = filter_node.run(
+        ...     data=items,
+        ...     field="title",
+        ...     operator="contains",
+        ...     value="Python"
+        ... )
+        >>> assert len(result["filtered_data"]) == 2
+        >>>
+        >>> # Null value handling
+        >>> data_with_nulls = [
+        ...     {"value": 10},
+        ...     {"value": None},
+        ...     {"value": 20}
+        ... ]
+        >>> result = filter_node.run(
+        ...     data=data_with_nulls,
+        ...     field="value",
+        ...     operator="!=",
+        ...     value=None
+        ... )
+        >>> assert len(result["filtered_data"]) == 2
+    """
 
     def get_parameters(self) -> Dict[str, NodeParameter]:
         return {
@@ -67,8 +176,10 @@ class Filter(Node):
         try:
             # Handle None values - they fail most comparisons
             if item_value is None:
-                if operator in ["==", "!="]:
-                    return (operator == "==") == (compare_value is None)
+                if operator == "==":
+                    return compare_value is None
+                elif operator == "!=":
+                    return compare_value is not None
                 else:
                     return False  # None fails all other comparisons
 
@@ -379,3 +490,7 @@ class Sort(Node):
             sorted_data = sorted(data, reverse=reverse)
 
         return {"sorted_data": sorted_data}
+
+
+# Backward compatibility aliases
+Filter = FilterNode

kailash/tracking/metrics_collector.py

@@ -88,13 +88,12 @@ class MetricsCollector:
     metrics during node execution, with support for both process-level and
     system-level monitoring.
 
-    Usage::
-
-        collector = MetricsCollector()
-        with collector.collect() as metrics:
-            # Execute node code here
-            pass
-        performance_data = metrics.result()
+    Usage:
+        >>> collector = MetricsCollector()
+        >>> with collector.collect() as metrics:
+        ...     # Execute node code here
+        ...     pass
+        >>> performance_data = metrics.result()
     """
 
     def __init__(self, sampling_interval: float = 0.1):

kailash/utils/export.py

@@ -88,8 +88,8 @@ class NodeMapper:
             resources=ResourceSpec(cpu="100m", memory="256Mi"),
         )
 
-        self.mappings["CSVReader"] = ContainerMapping(
-            python_node="CSVReader",
+        self.mappings["CSVReaderNode"] = ContainerMapping(
+            python_node="CSVReaderNode",
             container_image="kailash/csv-reader:latest",
             command=["python", "-m", "kailash.nodes.data.csv_reader"],
             resources=ResourceSpec(cpu="100m", memory="512Mi"),