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

kailash/nodes/api/http.py

@@ -57,33 +57,114 @@ class HTTPResponse(BaseModel):
 
 @register_node()
 class HTTPRequestNode(Node):
-    """Enhanced node for making HTTP requests to external APIs.
-
-    This node provides a flexible interface for making HTTP requests with support for:
-        * All common HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
-        * Multiple authentication methods (Bearer, Basic, API Key, OAuth2)
-        * JSON, form, and multipart request bodies
-        * Custom headers and query parameters
-        * Response parsing (JSON, text, binary)
-        * Error handling and retries with recovery suggestions
-        * Rate limiting support
-        * Request/response logging
-
-    Design Purpose:
-        * Enable workflow integration with external HTTP APIs
-        * Provide a consistent interface for HTTP operations
-        * Support common authentication patterns
-        * Handle response parsing and error handling
-        * Offer enterprise-grade features like rate limiting
-
-    Upstream Usage:
-        * Workflow: Creates and configures node for API integration
-        * Specialized API nodes: May extend this node for specific APIs
+    """
+    Enhanced node for making HTTP requests to external APIs.
+
+    This node provides a comprehensive HTTP client with enterprise-grade features for
+    integrating external APIs into Kailash workflows. It supports all common HTTP
+    operations with built-in authentication, error handling, and response parsing,
+    making it the foundation for API integration in the SDK.
+
+    Design Philosophy:
+        The HTTPRequestNode embodies the principle of "API integration made simple."
+        It abstracts the complexity of HTTP operations behind a clean interface while
+        providing advanced features when needed. The design prioritizes flexibility,
+        reliability, and ease of use, supporting everything from simple REST calls
+        to complex authentication flows and multipart uploads.
+
+    Upstream Dependencies:
+        - Workflow orchestrators configuring API endpoints
+        - Authentication nodes providing credentials
+        - Configuration systems supplying API settings
+        - Data transformation nodes preparing request payloads
+        - Rate limiting controllers managing API quotas
 
     Downstream Consumers:
-        * Data processing nodes: Consume API response data
-        * Decision nodes: Route workflow based on API responses
-        * Custom nodes: Process API-specific data formats
+        - Data processing nodes consuming API responses
+        - Decision nodes routing based on HTTP status
+        - Error handling nodes managing failures
+        - Caching nodes storing API results
+        - Analytics nodes tracking API usage
+
+    Configuration:
+        The node supports extensive configuration options:
+        - URL with template variable support
+        - All standard HTTP methods
+        - Custom headers and query parameters
+        - Multiple body formats (JSON, form, multipart)
+        - Authentication methods (Bearer, Basic, API Key, OAuth2)
+        - Timeout and retry settings
+        - Response format preferences
+
+    Implementation Details:
+        - Uses requests library for synchronous operations
+        - Automatic response format detection based on Content-Type
+        - Built-in JSON parsing with error handling
+        - Support for binary responses (files, images)
+        - Connection pooling for performance
+        - Comprehensive error messages with recovery hints
+        - Optional request/response logging
+        - Metrics collection for monitoring
+
+    Error Handling:
+        - Connection errors with retry suggestions
+        - Timeout handling with configurable limits
+        - HTTP error status codes with detailed messages
+        - JSON parsing errors with fallback to text
+        - Authentication failures with setup guidance
+        - Rate limit detection and backoff
+
+    Side Effects:
+        - Makes external HTTP requests
+        - May consume API rate limits
+        - Logs requests/responses when enabled
+        - Updates internal metrics
+        - May modify external resources (POST/PUT/DELETE)
+
+    Examples:
+        >>> # Simple GET request
+        >>> node = HTTPRequestNode()
+        >>> result = node.run(
+        ...     url="https://api.example.com/users",
+        ...     method="GET",
+        ...     headers={"Accept": "application/json"}
+        ... )
+        >>> assert result["status_code"] == 200
+        >>> assert isinstance(result["content"], dict)
+        >>>
+        >>> # POST request with JSON body
+        >>> result = node.run(
+        ...     url="https://api.example.com/users",
+        ...     method="POST",
+        ...     json_data={"name": "John", "email": "john@example.com"},
+        ...     headers={"Authorization": "Bearer token123"}
+        ... )
+        >>> assert result["status_code"] in [200, 201]
+        >>> assert result["headers"]["content-type"].startswith("application/json")
+        >>>
+        >>> # Form data submission
+        >>> result = node.run(
+        ...     url="https://api.example.com/form",
+        ...     method="POST",
+        ...     data={"field1": "value1", "field2": "value2"},
+        ...     headers={"Content-Type": "application/x-www-form-urlencoded"}
+        ... )
+        >>>
+        >>> # File upload with multipart
+        >>> result = node.run(
+        ...     url="https://api.example.com/upload",
+        ...     method="POST",
+        ...     files={"file": ("data.csv", b"col1,col2\\n1,2", "text/csv")},
+        ...     data={"description": "Sample data"}
+        ... )
+        >>>
+        >>> # Error handling example
+        >>> result = node.run(
+        ...     url="https://api.example.com/protected",
+        ...     method="GET"
+        ... )
+        >>> if result["status_code"] == 401:
+        ...     print("Authentication required")
     """
 
     def __init__(self, **kwargs):

kailash/nodes/api/rest.py

@@ -20,29 +20,124 @@ from kailash.sdk_exceptions import NodeExecutionError, NodeValidationError
 
 @register_node()
 class RESTClientNode(Node):
-    """Node for interacting with REST APIs.
-
-    This node provides a higher-level interface for interacting with REST APIs,
-    with built-in support for:
-        * Resource-based operations (e.g., GET /users/{id})
-        * Common REST patterns (list, get, create, update, delete)
-        * Pagination handling
-        * Response schema validation
-        * Error response handling
-
-    Design Purpose:
-        * Simplify REST API integration in workflows
-        * Provide consistent interfaces for common REST operations
-        * Support standard REST conventions and patterns
-        * Handle common REST-specific error cases
-
-    Upstream Usage:
-        * Workflow: Creates and configures for specific REST APIs
-        * API integration workflows: Uses for external service integration
+    """
+    Node for interacting with REST APIs using resource-oriented patterns.
+
+    This node provides a higher-level abstraction over HTTP operations, specifically
+    designed for REST APIs. It understands REST conventions and provides convenient
+    methods for resource-based operations, making it easier to integrate RESTful
+    services into Kailash workflows.
+
+    Design Philosophy:
+        The RESTClientNode embraces REST principles and conventions, providing an
+        intuitive interface for resource manipulation. It abstracts common patterns
+        like path parameter substitution, pagination, and error handling while
+        maintaining flexibility for API-specific requirements. The design promotes
+        clean, maintainable API integration code.
+
+    Upstream Dependencies:
+        - Workflow orchestrators defining API endpoints
+        - Configuration nodes providing API credentials
+        - Data transformation nodes preparing resources
+        - Authentication nodes managing tokens
+        - Schema validation nodes defining expected formats
 
     Downstream Consumers:
-        * Data processing nodes: Consume API response data
-        * Custom nodes: Process API-specific data formats
+        - Data processing nodes working with API responses
+        - Pagination handlers managing result sets
+        - Error recovery nodes handling failures
+        - Caching nodes storing resource data
+        - Analytics nodes tracking API usage patterns
+
+    Configuration:
+        The node supports REST-specific configuration:
+        - Base URL for API endpoints
+        - Resource paths with parameter placeholders
+        - Default headers and authentication
+        - API versioning strategies
+        - Pagination parameters
+        - Response format expectations
+
+    Implementation Details:
+        - Built on HTTPRequestNode for core functionality
+        - Automatic URL construction from base + resource
+        - Path parameter substitution (e.g., /users/{id})
+        - Query parameter handling with encoding
+        - Standard REST method mapping
+        - Response format negotiation
+        - Error response parsing for API-specific errors
+        - Link header parsing for pagination
+
+    Error Handling:
+        - 404 errors for missing resources
+        - 422 validation errors with field details
+        - 401/403 authentication/authorization errors
+        - Rate limiting (429) with retry headers
+        - 5xx server errors with backoff
+        - Network failures with retry logic
+        - Malformed response handling
+
+    Side Effects:
+        - Performs HTTP requests to external APIs
+        - May modify remote resources (POST/PUT/DELETE)
+        - Consumes API rate limits
+        - May trigger webhooks or notifications
+        - Updates internal request metrics
+
+    Examples:
+        >>> # Initialize REST client
+        >>> client = RESTClientNode()
+        >>>
+        >>> # Get a single resource
+        >>> result = client.run(
+        ...     base_url="https://api.example.com/v1",
+        ...     resource="users/{id}",
+        ...     method="GET",
+        ...     path_params={"id": 123},
+        ...     headers={"Authorization": "Bearer token"}
+        ... )
+        >>> assert result["status_code"] == 200
+        >>> user = result["content"]
+        >>> assert user["id"] == 123
+        >>>
+        >>> # List resources with pagination
+        >>> result = client.run(
+        ...     base_url="https://api.example.com/v1",
+        ...     resource="products",
+        ...     method="GET",
+        ...     query_params={"page": 1, "per_page": 20, "category": "electronics"}
+        ... )
+        >>> assert len(result["content"]) <= 20
+        >>>
+        >>> # Create a new resource
+        >>> result = client.run(
+        ...     base_url="https://api.example.com/v1",
+        ...     resource="posts",
+        ...     method="POST",
+        ...     data={"title": "New Post", "content": "Post content"},
+        ...     headers={"Content-Type": "application/json"}
+        ... )
+        >>> assert result["status_code"] == 201
+        >>> assert "id" in result["content"]
+        >>>
+        >>> # Update a resource
+        >>> result = client.run(
+        ...     base_url="https://api.example.com/v1",
+        ...     resource="users/{id}",
+        ...     method="PATCH",
+        ...     path_params={"id": 123},
+        ...     data={"email": "newemail@example.com"}
+        ... )
+        >>> assert result["status_code"] == 200
+        >>>
+        >>> # Delete a resource
+        >>> result = client.run(
+        ...     base_url="https://api.example.com/v1",
+        ...     resource="comments/{id}",
+        ...     method="DELETE",
+        ...     path_params={"id": 456}
+        ... )
+        >>> assert result["status_code"] in [200, 204]
     """
 
     def __init__(self, **kwargs):

kailash/nodes/data/readers.py

@@ -37,59 +37,112 @@ from kailash.nodes.base import Node, NodeParameter, register_node
 
 @register_node()
 class CSVReaderNode(Node):
-    """Reads data from a CSV file.
-
-    This node provides robust CSV file reading capabilities with support for
-    various delimiters, header detection, and encoding options. It's designed
-    to handle common CSV formats and edge cases.
-
-    Design Features:
-    1. Automatic header detection
-    2. Configurable delimiters
-    3. Memory-efficient line-by-line reading
-    4. Consistent dictionary output format
-    5. Unicode support through encoding parameter
-
-    Data Flow:
-    - Input: File path and configuration parameters
-    - Processing: Reads CSV line by line, converting to dictionaries
-    - Output: List of dictionaries (with headers) or list of lists
-
-    Common Usage Patterns:
-    1. Reading data exports from databases
-    2. Processing spreadsheet data
-    3. Loading configuration from CSV
-    4. Ingesting sensor data logs
-
-    Upstream Sources:
-    - File system paths from user input
-    - Output paths from previous nodes
-    - Configuration management systems
+    """
+    Reads data from CSV files with automatic header detection and type inference.
+
+    This node provides comprehensive CSV file reading capabilities, handling various
+    formats, encodings, and edge cases. It automatically detects headers, infers data
+    types, and provides consistent structured output for downstream processing in
+    Kailash workflows.
+
+    Design Philosophy:
+        The CSVReaderNode embodies the principle of "data accessibility without
+        complexity." It abstracts the intricacies of CSV parsing while providing
+        flexibility for various formats. The design prioritizes memory efficiency,
+        automatic format detection, and consistent output structure, making it easy
+        to integrate diverse CSV data sources into workflows.
+
+    Upstream Dependencies:
+        - File system providing CSV files
+        - Workflow orchestrators specifying file paths
+        - Configuration systems providing parsing options
+        - Previous nodes generating CSV file paths
+        - User inputs defining data sources
 
     Downstream Consumers:
-    - DataTransformer: Processes tabular data
-    - Aggregator: Summarizes data
-    - CSVWriter: Reformats and saves
-    - Visualizer: Creates charts from data
+        - DataTransformNode: Processes tabular data
+        - FilterNode: Applies row/column filtering
+        - AggregatorNode: Summarizes data
+        - PythonCodeNode: Custom data processing
+        - WriterNodes: Exports to other formats
+        - Visualization nodes: Creates charts
+        - ML nodes: Uses as training data
+
+    Configuration:
+        The node supports extensive CSV parsing options:
+        - Delimiter detection (comma, tab, pipe, etc.)
+        - Header row identification
+        - Encoding specification (UTF-8, Latin-1, etc.)
+        - Quote character handling
+        - Skip rows/comments functionality
+        - Column type inference
+        - Missing value handling
+
+    Implementation Details:
+        - Uses Python's csv module for robust parsing
+        - Implements streaming for large files
+        - Automatic delimiter detection when not specified
+        - Header detection based on first row analysis
+        - Type inference for numeric/date columns
+        - Memory-efficient processing with generators
+        - Unicode normalization for consistent encoding
 
     Error Handling:
-    - FileNotFoundError: Invalid file path
-    - PermissionError: Insufficient read permissions
-    - UnicodeDecodeError: Encoding mismatch
-    - csv.Error: Malformed CSV data
-
-    Example:
-        >>> # Read customer data with headers
-        >>> reader = CSVReaderNode(
-        ...     file_path='customers.csv',
-        ...     headers=True,
-        ...     delimiter=','
+        - FileNotFoundError: Clear message with path
+        - PermissionError: Access rights guidance
+        - UnicodeDecodeError: Encoding detection hints
+        - csv.Error: Malformed data diagnostics
+        - EmptyFileError: Handles zero-byte files
+        - Partial read recovery for corrupted files
+
+    Side Effects:
+        - Reads from file system
+        - May consume significant memory for large files
+        - Creates file handles (properly closed)
+        - Updates internal read statistics
+
+    Examples:
+        >>> # Basic CSV reading with headers
+        >>> reader = CSVReaderNode()
+        >>> result = reader.run(
+        ...     file_path="customers.csv",
+        ...     headers=True
         ... )
-        >>> result = reader.execute()
-        >>> # result['data'] = [
-        >>> #     {'id': '1', 'name': 'John', 'age': '30'},
-        >>> #     {'id': '2', 'name': 'Jane', 'age': '25'}
+        >>> assert isinstance(result["data"], list)
+        >>> assert all(isinstance(row, dict) for row in result["data"])
+        >>> # Example output:
+        >>> # result["data"] = [
+        >>> #     {"id": "1", "name": "John Doe", "age": "30"},
+        >>> #     {"id": "2", "name": "Jane Smith", "age": "25"}
         >>> # ]
+        >>>
+        >>> # Reading with custom delimiter
+        >>> result = reader.run(
+        ...     file_path="data.tsv",
+        ...     delimiter="\\t",
+        ...     headers=True
+        ... )
+        >>>
+        >>> # Reading without headers (returns list of lists)
+        >>> result = reader.run(
+        ...     file_path="data.csv",
+        ...     headers=False
+        ... )
+        >>> assert all(isinstance(row, list) for row in result["data"])
+        >>>
+        >>> # Reading with specific encoding
+        >>> result = reader.run(
+        ...     file_path="european_data.csv",
+        ...     encoding="iso-8859-1",
+        ...     headers=True
+        ... )
+        >>>
+        >>> # Handling quoted fields
+        >>> result = reader.run(
+        ...     file_path="complex.csv",
+        ...     headers=True,
+        ...     quotechar='"'
+        ... )
     """
 
     def get_parameters(self) -> Dict[str, NodeParameter]:

kailash/nodes/logic/async_operations.py

@@ -32,15 +32,25 @@ class AsyncMergeNode(AsyncNode):
     concat (list concatenation), zip (parallel iteration), and merge_dict
     (dictionary merging with optional key-based joining).
 
-    Usage example:
-        # Create an AsyncMergeNode in a workflow
-        async_merge = AsyncMergeNode(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]:
@@ -364,6 +374,35 @@ class AsyncSwitchNode(AsyncNode):
 
     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]:

kailash/nodes/logic/operations.py

@@ -370,6 +370,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/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",