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

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)

kailash/nodes/mixins.py

@@ -0,0 +1,387 @@
+"""
+Node mixins for the Kailash SDK.
+
+This module provides mixins that add common functionality to nodes,
+including security features, validation, and utility methods.
+
+Design Philosophy:
+    - Composition over inheritance for optional features
+    - Security by default
+    - Minimal performance overhead
+    - Easy to integrate with existing nodes
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+from kailash.security import (
+    SecurityConfig,
+    SecurityError,
+    get_security_config,
+    sanitize_input,
+    validate_node_parameters,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SecurityMixin:
+    """
+    Mixin that adds security features to nodes.
+
+    This mixin provides:
+    - Input parameter validation and sanitization
+    - Security policy enforcement
+    - Audit logging for security events
+    - Protection against common attack vectors
+
+    Usage:
+        class MySecureNode(SecurityMixin, Node):
+            def run(self, **kwargs):
+                # Input is automatically sanitized
+                safe_params = self.validate_and_sanitize_inputs(kwargs)
+                return self.process_safely(safe_params)
+    """
+
+    def __init__(
+        self, *args, security_config: Optional[SecurityConfig] = None, **kwargs
+    ):
+        """
+        Initialize security mixin.
+
+        Args:
+            security_config: Security configuration to use
+            *args: Arguments passed to parent class
+            **kwargs: Keyword arguments passed to parent class
+        """
+        super().__init__(*args, **kwargs)
+        self.security_config = security_config or get_security_config()
+
+        if self.security_config.enable_audit_logging:
+            logger.info(f"Security mixin initialized for {self.__class__.__name__}")
+
+    def validate_and_sanitize_inputs(self, inputs: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Validate and sanitize input parameters.
+
+        Args:
+            inputs: Dictionary of input parameters
+
+        Returns:
+            Dictionary of validated and sanitized parameters
+
+        Raises:
+            SecurityError: If validation fails
+        """
+        try:
+            # First validate using the security framework
+            validated_inputs = validate_node_parameters(inputs, self.security_config)
+
+            if self.security_config.enable_audit_logging:
+                logger.debug(
+                    f"Inputs validated for {self.__class__.__name__}: {list(validated_inputs.keys())}"
+                )
+
+            return validated_inputs
+
+        except SecurityError as e:
+            if self.security_config.enable_audit_logging:
+                logger.error(
+                    f"Security validation failed for {self.__class__.__name__}: {e}"
+                )
+            raise
+        except Exception as e:
+            if self.security_config.enable_audit_logging:
+                logger.error(
+                    f"Unexpected validation error for {self.__class__.__name__}: {e}"
+                )
+            raise SecurityError(f"Input validation failed: {e}")
+
+    def sanitize_single_input(self, value: Any, max_length: int = 10000) -> Any:
+        """
+        Sanitize a single input value.
+
+        Args:
+            value: Value to sanitize
+            max_length: Maximum string length
+
+        Returns:
+            Sanitized value
+        """
+        return sanitize_input(value, max_length, config=self.security_config)
+
+    def is_security_enabled(self) -> bool:
+        """Check if security features are enabled."""
+        return (
+            self.security_config.enable_path_validation
+            or self.security_config.enable_command_validation
+            or hasattr(self, "security_config")
+        )
+
+    def log_security_event(self, event: str, level: str = "INFO") -> None:
+        """
+        Log a security-related event.
+
+        Args:
+            event: Description of the security event
+            level: Log level (INFO, WARNING, ERROR)
+        """
+        if not self.security_config.enable_audit_logging:
+            return
+
+        log_msg = f"Security event in {self.__class__.__name__}: {event}"
+
+        if level.upper() == "ERROR":
+            logger.error(log_msg)
+        elif level.upper() == "WARNING":
+            logger.warning(log_msg)
+        else:
+            logger.info(log_msg)
+
+
+class ValidationMixin:
+    """
+    Mixin that adds enhanced input validation to nodes.
+
+    This mixin provides:
+    - Type checking and conversion
+    - Range and constraint validation
+    - Custom validation rules
+    - Detailed error reporting
+    """
+
+    def validate_required_params(
+        self, inputs: Dict[str, Any], required_params: list
+    ) -> None:
+        """
+        Validate that all required parameters are present.
+
+        Args:
+            inputs: Input parameters
+            required_params: List of required parameter names
+
+        Raises:
+            ValueError: If required parameters are missing
+        """
+        missing_params = [param for param in required_params if param not in inputs]
+        if missing_params:
+            raise ValueError(f"Missing required parameters: {missing_params}")
+
+    def validate_param_types(
+        self, inputs: Dict[str, Any], type_mapping: Dict[str, type]
+    ) -> Dict[str, Any]:
+        """
+        Validate and convert parameter types.
+
+        Args:
+            inputs: Input parameters
+            type_mapping: Dictionary mapping parameter names to expected types
+
+        Returns:
+            Dictionary with converted types
+
+        Raises:
+            TypeError: If type conversion fails
+        """
+        converted = {}
+
+        for param_name, value in inputs.items():
+            if param_name in type_mapping:
+                expected_type = type_mapping[param_name]
+                try:
+                    if isinstance(value, expected_type):
+                        converted[param_name] = value
+                    else:
+                        converted[param_name] = expected_type(value)
+                except (ValueError, TypeError) as e:
+                    raise TypeError(
+                        f"Cannot convert {param_name} to {expected_type.__name__}: {e}"
+                    )
+            else:
+                converted[param_name] = value
+
+        return converted
+
+    def validate_param_ranges(
+        self, inputs: Dict[str, Any], range_mapping: Dict[str, tuple]
+    ) -> None:
+        """
+        Validate that numeric parameters are within acceptable ranges.
+
+        Args:
+            inputs: Input parameters
+            range_mapping: Dictionary mapping parameter names to (min, max) tuples
+
+        Raises:
+            ValueError: If parameters are out of range
+        """
+        for param_name, (min_val, max_val) in range_mapping.items():
+            if param_name in inputs:
+                value = inputs[param_name]
+                if isinstance(value, (int, float)):
+                    if value < min_val or value > max_val:
+                        raise ValueError(
+                            f"{param_name} must be between {min_val} and {max_val}, got {value}"
+                        )
+
+
+class PerformanceMixin:
+    """
+    Mixin that adds performance monitoring to nodes.
+
+    This mixin provides:
+    - Execution time tracking
+    - Memory usage monitoring
+    - Performance metrics collection
+    - Optimization hints
+    """
+
+    def __init__(self, *args, **kwargs):
+        """Initialize performance mixin."""
+        super().__init__(*args, **kwargs)
+        self.execution_times = []
+        self.memory_usage = []
+        self.performance_enabled = True
+
+    def track_performance(self, func):
+        """
+        Decorator to track performance of node methods.
+
+        Args:
+            func: Function to wrap
+
+        Returns:
+            Wrapped function with performance tracking
+        """
+        import time
+        import tracemalloc
+        from functools import wraps
+
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            if not self.performance_enabled:
+                return func(*args, **kwargs)
+
+            # Start tracking
+            start_time = time.time()
+            tracemalloc.start()
+
+            try:
+                result = func(*args, **kwargs)
+                return result
+            finally:
+                # Record metrics
+                execution_time = time.time() - start_time
+                current, peak = tracemalloc.get_traced_memory()
+                tracemalloc.stop()
+
+                self.execution_times.append(execution_time)
+                self.memory_usage.append(peak)
+
+                if len(self.execution_times) > 100:  # Keep last 100 measurements
+                    self.execution_times = self.execution_times[-100:]
+                    self.memory_usage = self.memory_usage[-100:]
+
+        return wrapper
+
+    def get_performance_stats(self) -> Dict[str, Any]:
+        """
+        Get performance statistics for this node.
+
+        Returns:
+            Dictionary containing performance metrics
+        """
+        if not self.execution_times:
+            return {"status": "No performance data available"}
+
+        import statistics
+
+        return {
+            "executions": len(self.execution_times),
+            "avg_execution_time": statistics.mean(self.execution_times),
+            "min_execution_time": min(self.execution_times),
+            "max_execution_time": max(self.execution_times),
+            "avg_memory_usage": (
+                statistics.mean(self.memory_usage) if self.memory_usage else 0
+            ),
+            "peak_memory_usage": max(self.memory_usage) if self.memory_usage else 0,
+        }
+
+    def reset_performance_stats(self) -> None:
+        """Reset performance statistics."""
+        self.execution_times.clear()
+        self.memory_usage.clear()
+
+
+class LoggingMixin:
+    """
+    Mixin that adds enhanced logging capabilities to nodes.
+
+    This mixin provides:
+    - Structured logging with context
+    - Log level management
+    - Performance logging
+    - Debug information
+    """
+
+    def __init__(self, *args, log_level: str = "INFO", **kwargs):
+        """
+        Initialize logging mixin.
+
+        Args:
+            log_level: Default log level for this node
+            *args: Arguments passed to parent class
+            **kwargs: Keyword arguments passed to parent class
+        """
+        super().__init__(*args, **kwargs)
+        self.logger = logging.getLogger(
+            f"{self.__class__.__module__}.{self.__class__.__name__}"
+        )
+        self.logger.setLevel(getattr(logging, log_level.upper()))
+        self.log_context = {"node_class": self.__class__.__name__}
+
+    def log_with_context(self, level: str, message: str, **context) -> None:
+        """
+        Log a message with additional context.
+
+        Args:
+            level: Log level
+            message: Log message
+            **context: Additional context to include
+        """
+        full_context = {**self.log_context, **context}
+        context_str = " | ".join(f"{k}={v}" for k, v in full_context.items())
+        full_message = f"{message} | {context_str}"
+
+        log_func = getattr(self.logger, level.lower())
+        log_func(full_message)
+
+    def log_node_execution(self, operation: str, **context) -> None:
+        """
+        Log node execution information.
+
+        Args:
+            operation: Type of operation being performed
+            **context: Additional context
+        """
+        self.log_with_context("INFO", f"Node operation: {operation}", **context)
+
+    def log_error_with_traceback(
+        self, error: Exception, operation: str = "unknown"
+    ) -> None:
+        """
+        Log an error with full traceback information.
+
+        Args:
+            error: Exception that occurred
+            operation: Operation that failed
+        """
+        import traceback
+
+        self.log_with_context(
+            "ERROR",
+            f"Operation failed: {operation}",
+            error_type=type(error).__name__,
+            error_message=str(error),
+            traceback=traceback.format_exc(),
+        )

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