kailash 0.1.3__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/base.py

@@ -214,24 +214,23 @@ class Node(ABC):
         - During workflow creation: Used for connection validation
         - During export: Included in workflow manifests
 
-        Example::
-
-            def get_parameters(self):
-                return {
-                    'input_file': NodeParameter(
-                        name='input_file',
-                        type=str,
-                        required=True,
-                        description='Path to input CSV file'
-                    ),
-                    'delimiter': NodeParameter(
-                        name='delimiter',
-                        type=str,
-                        required=False,
-                        default=',',
-                        description='CSV delimiter character'
-                    )
-                }
+        Example:
+            >>> def get_parameters(self):
+            ...     return {
+            ...         'input_file': NodeParameter(
+            ...             name='input_file',
+            ...             type=str,
+            ...             required=True,
+            ...             description='Path to input CSV file'
+            ...         ),
+            ...         'delimiter': NodeParameter(
+            ...             name='delimiter',
+            ...             type=str,
+            ...             required=False,
+            ...             default=',',
+            ...             description='CSV delimiter character'
+            ...         )
+            ...     }
 
         Returns:
             Dictionary mapping parameter names to their definitions
@@ -265,29 +264,28 @@ class Node(ABC):
         3. Workflow connection validation
         4. Export manifest generation
 
-        Example::
-
-            def get_output_schema(self):
-                return {
-                    'dataframe': NodeParameter(
-                        name='dataframe',
-                        type=dict,
-                        required=True,
-                        description='Processed data as dictionary'
-                    ),
-                    'row_count': NodeParameter(
-                        name='row_count',
-                        type=int,
-                        required=True,
-                        description='Number of rows processed'
-                    ),
-                    'processing_time': NodeParameter(
-                        name='processing_time',
-                        type=float,
-                        required=False,
-                        description='Time taken to process in seconds'
-                    )
-                }
+        Example:
+            >>> def get_output_schema(self):
+            ...     return {
+            ...         'dataframe': NodeParameter(
+            ...             name='dataframe',
+            ...             type=dict,
+            ...             required=True,
+            ...             description='Processed data as dictionary'
+            ...         ),
+            ...         'row_count': NodeParameter(
+            ...             name='row_count',
+            ...             type=int,
+            ...             required=True,
+            ...             description='Number of rows processed'
+            ...         ),
+            ...         'processing_time': NodeParameter(
+            ...             name='processing_time',
+            ...             type=float,
+            ...             required=False,
+            ...             description='Time taken to process in seconds'
+            ...         )
+            ...     }
 
         Returns:
             Dictionary mapping output names to their parameter definitions
@@ -325,15 +323,14 @@ class Node(ABC):
         - Error wrapping and logging
         - Execution timing and metrics
 
-        Example::
-
-            def run(self, input_file, delimiter=','):
-                df = pd.read_csv(input_file, delimiter=delimiter)
-                return {
-                    'dataframe': df.to_dict(),
-                    'row_count': len(df),
-                    'columns': list(df.columns)
-                }
+        Example:
+            >>> def run(self, input_file, delimiter=','):
+            ...     df = pd.read_csv(input_file, delimiter=delimiter)
+            ...     return {
+            ...         'dataframe': df.to_dict(),
+            ...         'row_count': len(df),
+            ...         'columns': list(df.columns)
+            ...     }
 
         Args:
             **kwargs: Validated input parameters matching get_parameters()
@@ -1010,11 +1007,11 @@ class NodeRegistry:
             - Logs the clearing action
             - Existing node instances remain valid
 
-        Warning::
-
-        - Subsequent get() calls will fail
-        - Workflows may not deserialize
-        - Should re-register needed nodes
+        Warning:
+            >>> # Warning: This affects all future operations
+            >>> # - Subsequent get() calls will fail
+            >>> # - Workflows may not deserialize
+            >>> # - Should re-register needed nodes
         """
         cls._nodes.clear()
         logging.info("Cleared all registered nodes")
@@ -1057,15 +1054,14 @@ def register_node(alias: Optional[str] = None):
         - Returns the unmodified class
         - Handles registration errors
 
-    Example::
-
-        @register_node(alias='CSV')
-        class CSVReaderNode(Node):
-            def get_parameters(self):
-                return {'file': NodeParameter(...)}
-
-            def run(self, file):
-                return pd.read_csv(file)
+    Example:
+        >>> @register_node(alias='CSV')
+        ... class CSVReaderNode(Node):
+        ...     def get_parameters(self):
+        ...         return {'file': NodeParameter(...)}
+        ...
+        ...     def run(self, file):
+        ...         return pd.read_csv(file)
     """
 
     def decorator(node_class: Type[Node]):

kailash/nodes/code/python.py

@@ -144,6 +144,7 @@ class CodeExecutor:
             "filter",
             "float",
             "int",
+            "isinstance",  # Common type checking
             "len",
             "list",
             "map",
@@ -546,48 +547,47 @@ class PythonCodeNode(Node):
     - State management for class-based nodes
     - AST-based security validation
 
-    Example::
-
-        # Function-based node
-        def custom_filter(data: pd.DataFrame, threshold: float) -> pd.DataFrame:
-            return data[data['value'] > threshold]
-
-        node = PythonCodeNode.from_function(
-            func=custom_filter,
-            name="threshold_filter"
-        )
-
-        # Class-based stateful node
-        class MovingAverage:
-            def __init__(self, window_size: int = 3):
-                self.window_size = window_size
-                self.values = []
-
-            def process(self, value: float) -> float:
-                self.values.append(value)
-                if len(self.values) > self.window_size:
-                    self.values.pop(0)
-                return sum(self.values) / len(self.values)
-
-        node = PythonCodeNode.from_class(
-            cls=MovingAverage,
-            name="moving_avg"
-        )
-
-        # Code string node
-        code = '''
-        result = []
-        for item in data:
-            if item > threshold:
-                result.append(item * 2)
-        '''
-
-        node = PythonCodeNode(
-            name="custom_processor",
-            code=code,
-            input_types={'data': list, 'threshold': float},
-            output_type=list
-        )
+    Example:
+        >>> # Function-based node
+        >>> def custom_filter(data: pd.DataFrame, threshold: float) -> pd.DataFrame:
+        ...     return data[data['value'] > threshold]
+
+        >>> node = PythonCodeNode.from_function(
+        ...     func=custom_filter,
+        ...     name="threshold_filter"
+        ... )
+
+        >>> # Class-based stateful node
+        >>> class MovingAverage:
+        ...     def __init__(self, window_size: int = 3):
+        ...         self.window_size = window_size
+        ...         self.values = []
+        ...
+        ...     def process(self, value: float) -> float:
+        ...         self.values.append(value)
+        ...         if len(self.values) > self.window_size:
+        ...             self.values.pop(0)
+        ...         return sum(self.values) / len(self.values)
+
+        >>> node = PythonCodeNode.from_class(
+        ...     cls=MovingAverage,
+        ...     name="moving_avg"
+        ... )
+
+        >>> # Code string node
+        >>> code = '''
+        ... result = []
+        ... for item in data:
+        ...     if item > threshold:
+        ...         result.append(item * 2)
+        ... '''
+
+        >>> node = PythonCodeNode(
+        ...     name="custom_processor",
+        ...     code=code,
+        ...     input_types={'data': list, 'threshold': float},
+        ...     output_type=list
+        ... )
     """
 
     def __init__(
@@ -727,6 +727,25 @@ class PythonCodeNode(Node):
 
         return parameters
 
+    def validate_inputs(self, **kwargs) -> Dict[str, Any]:
+        """Validate runtime inputs.
+
+        For code-based nodes, we accept any inputs since the code
+        can use whatever variables it needs.
+
+        Args:
+            **kwargs: Runtime inputs
+
+        Returns:
+            All inputs as-is for code nodes, validated inputs for function/class nodes
+        """
+        # If using code string, pass through all inputs
+        if self.code:
+            return kwargs
+
+        # Otherwise use standard validation for function/class nodes
+        return super().validate_inputs(**kwargs)
+
     def get_output_schema(self) -> Dict[str, "NodeParameter"]:
         """Define output parameters for this node.
 

kailash/nodes/data/__init__.py

@@ -57,9 +57,9 @@ All nodes provide detailed error messages for:
 Example Workflows:
     # Traditional ETL
     workflow = Workflow()
-    workflow.add_node('read', CSVReader(file_path='input.csv'))
+    workflow.add_node('read', CSVReaderNode(file_path='input.csv'))
     workflow.add_node('transform', DataTransform())
-    workflow.add_node('write', JSONWriter(file_path='output.json'))
+    workflow.add_node('write', JSONWriterNode(file_path='output.json'))
     workflow.connect('read', 'transform')
     workflow.connect('transform', 'write')
 
@@ -80,7 +80,7 @@ Example Workflows:
     workflow.connect('process', 'publish')
 """
 
-from kailash.nodes.data.readers import CSVReader, JSONReader, TextReader
+from kailash.nodes.data.readers import CSVReaderNode, JSONReaderNode, TextReaderNode
 from kailash.nodes.data.retrieval import RelevanceScorerNode
 from kailash.nodes.data.sharepoint_graph import (
     SharePointGraphReader,
@@ -99,18 +99,18 @@ from kailash.nodes.data.vector_db import (
     TextSplitterNode,
     VectorDatabaseNode,
 )
-from kailash.nodes.data.writers import CSVWriter, JSONWriter, TextWriter
+from kailash.nodes.data.writers import CSVWriterNode, JSONWriterNode, TextWriterNode
 
 __all__ = [
     # Readers
-    "CSVReader",
-    "JSONReader",
-    "TextReader",
+    "CSVReaderNode",
+    "JSONReaderNode",
+    "TextReaderNode",
     "SharePointGraphReader",
     # Writers
-    "CSVWriter",
-    "JSONWriter",
-    "TextWriter",
+    "CSVWriterNode",
+    "JSONWriterNode",
+    "TextWriterNode",
     "SharePointGraphWriter",
     # Sources
     "DocumentSourceNode",