kailash 0.1.4__py3-none-any.whl → 0.2.0__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

@@ -60,7 +60,8 @@ class NodeMetadata(BaseModel):
     version: str = Field("1.0.0", description="Node version")
     author: str = Field("", description="Node author")
     created_at: datetime = Field(
-        default_factory=datetime.utcnow, description="Node creation date"
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="Node creation date",
     )
     tags: Set[str] = Field(default_factory=set, description="Node tags")
 
@@ -185,7 +186,19 @@ class Node(ABC):
                 ),
             )
             self.logger = logging.getLogger(f"kailash.nodes.{self.id}")
-            self.config = kwargs
+
+            # Filter out internal fields from config
+            internal_fields = {
+                "id",
+                "name",
+                "description",
+                "version",
+                "author",
+                "tags",
+                "metadata",
+            }
+            self.config = {k: v for k, v in kwargs.items() if k not in internal_fields}
+
             self._validate_config()
         except ValidationError as e:
             raise NodeConfigurationError(f"Invalid node metadata: {e}") from e

kailash/nodes/base_async.py

@@ -45,6 +45,51 @@ class AsyncNode(Node):
     - TaskManager: Tracks node execution status
     """
 
+    def execute(self, **runtime_inputs) -> Dict[str, Any]:
+        """Execute the node synchronously by running async code in a new event loop.
+
+        This override allows AsyncNode to work with synchronous runtimes like LocalRuntime.
+        It creates a new event loop to run the async code if needed.
+
+        Args:
+            **runtime_inputs: Runtime inputs for node execution
+
+        Returns:
+            Dictionary of validated outputs
+
+        Raises:
+            NodeValidationError: If inputs or outputs are invalid
+            NodeExecutionError: If execution fails
+        """
+        import asyncio
+        import sys
+
+        # Check if we're already in an event loop
+        try:
+            asyncio.get_running_loop()
+            # We're in an event loop - this is problematic for sync execution
+            # Try to use nest_asyncio if available
+            try:
+                import nest_asyncio
+
+                nest_asyncio.apply()
+                return asyncio.run(self.execute_async(**runtime_inputs))
+            except ImportError:
+                # Fall back to running in a thread pool
+                import concurrent.futures
+
+                with concurrent.futures.ThreadPoolExecutor() as executor:
+                    future = executor.submit(
+                        asyncio.run, self.execute_async(**runtime_inputs)
+                    )
+                    return future.result()
+        except RuntimeError:
+            # No event loop running, we can create one
+            if sys.platform == "win32":
+                # Windows requires special handling
+                asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())
+            return asyncio.run(self.execute_async(**runtime_inputs))
+
     async def async_run(self, **kwargs) -> Dict[str, Any]:
         """Asynchronous execution method for the node.