kailash 0.4.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

kailash/nodes/ai/vision_utils.py

@@ -0,0 +1,148 @@
+"""Vision utilities for AI providers - lazy loaded to avoid overhead."""
+
+from pathlib import Path
+from typing import Optional, Tuple
+
+
+def encode_image(image_path: str) -> str:
+    """
+    Encode image file to base64 string.
+
+    Args:
+        image_path: Path to the image file
+
+    Returns:
+        Base64 encoded string of the image
+
+    Raises:
+        FileNotFoundError: If image file doesn't exist
+        IOError: If unable to read the image file
+    """
+    # Lazy import to avoid overhead when not using vision
+    import base64
+
+    image_path = Path(image_path).resolve()
+    if not image_path.exists():
+        raise FileNotFoundError(f"Image file not found: {image_path}")
+
+    try:
+        with open(image_path, "rb") as image_file:
+            return base64.b64encode(image_file.read()).decode("utf-8")
+    except Exception as e:
+        raise IOError(f"Failed to read image file: {e}")
+
+
+def get_media_type(image_path: str) -> str:
+    """
+    Get media type from file extension.
+
+    Args:
+        image_path: Path to the image file
+
+    Returns:
+        Media type string (e.g., "image/jpeg")
+    """
+    ext = Path(image_path).suffix.lower()
+    media_types = {
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".png": "image/png",
+        ".gif": "image/gif",
+        ".webp": "image/webp",
+        ".bmp": "image/bmp",
+        ".tiff": "image/tiff",
+        ".tif": "image/tiff",
+    }
+    return media_types.get(ext, "image/jpeg")
+
+
+def validate_image_size(
+    image_path: str, max_size_mb: float = 20.0
+) -> Tuple[bool, Optional[str]]:
+    """
+    Validate image file size.
+
+    Args:
+        image_path: Path to the image file
+        max_size_mb: Maximum allowed size in megabytes
+
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    import os
+
+    try:
+        size_bytes = os.path.getsize(image_path)
+        size_mb = size_bytes / (1024 * 1024)
+
+        if size_mb > max_size_mb:
+            return False, f"Image size {size_mb:.1f}MB exceeds maximum {max_size_mb}MB"
+
+        return True, None
+    except Exception as e:
+        return False, f"Failed to check image size: {e}"
+
+
+def resize_image_if_needed(
+    image_path: str, max_size_mb: float = 20.0, max_dimension: int = 4096
+) -> Optional[str]:
+    """
+    Resize image if it exceeds size or dimension limits.
+
+    Args:
+        image_path: Path to the image file
+        max_size_mb: Maximum file size in MB
+        max_dimension: Maximum width or height in pixels
+
+    Returns:
+        Base64 encoded resized image, or None if no resize needed
+    """
+    try:
+        # Lazy import to avoid PIL dependency when not using vision
+        import base64
+        import io
+
+        from PIL import Image
+
+        # Check if resize is needed
+        is_valid, _ = validate_image_size(image_path, max_size_mb)
+
+        with Image.open(image_path) as img:
+            # Check dimensions
+            needs_resize = (
+                not is_valid or img.width > max_dimension or img.height > max_dimension
+            )
+
+            if not needs_resize:
+                return None
+
+            # Calculate new size maintaining aspect ratio
+            ratio = min(max_dimension / img.width, max_dimension / img.height, 1.0)
+            new_size = (int(img.width * ratio), int(img.height * ratio))
+
+            # Resize image
+            img = img.resize(new_size, Image.Resampling.LANCZOS)
+
+            # Convert to RGB if necessary (for JPEG)
+            if img.mode not in ("RGB", "L"):
+                img = img.convert("RGB")
+
+            # Save to bytes
+            output = io.BytesIO()
+            img_format = (
+                "JPEG"
+                if Path(image_path).suffix.lower() in [".jpg", ".jpeg"]
+                else "PNG"
+            )
+            img.save(output, format=img_format, optimize=True, quality=85)
+
+            # Encode to base64
+            output.seek(0)
+            return base64.b64encode(output.read()).decode("utf-8")
+
+    except ImportError:
+        # PIL not available, skip resizing
+        return None
+    except Exception:
+        # Any error in resizing, return None to use original
+        return None

kailash/nodes/alerts/__init__.py

@@ -0,0 +1,26 @@
+"""Alert and notification nodes for the Kailash SDK.
+
+This module provides specialized nodes for sending alerts and notifications
+through various channels. Each alert node follows a consistent interface while
+providing channel-specific features and optimizations.
+
+The module includes:
+- Base alert node infrastructure
+- Discord webhook integration
+- (Future) Slack, email, webhook, and other integrations
+
+Design Philosophy:
+- Provide purpose-built nodes for common alert patterns
+- Abstract channel-specific complexity
+- Support both simple and advanced use cases
+- Enable consistent alert formatting across channels
+"""
+
+from .base import AlertNode, AlertSeverity
+from .discord import DiscordAlertNode
+
+__all__ = [
+    "AlertNode",
+    "AlertSeverity",
+    "DiscordAlertNode",
+]

kailash/nodes/alerts/base.py

@@ -0,0 +1,234 @@
+"""Base alert node class for the Kailash SDK.
+
+This module provides the foundation for all alert and notification nodes in the system.
+It defines common parameters, severity levels, and formatting utilities that are shared
+across different alert implementations.
+
+The alert system is designed to provide:
+- Consistent interface across different notification channels
+- Severity-based formatting and colors
+- Structured context data support
+- Easy extensibility for new alert types
+"""
+
+from abc import abstractmethod
+from enum import Enum
+from typing import Any
+
+from kailash.nodes.base import Node, NodeParameter
+
+
+class AlertSeverity(str, Enum):
+    """Standard alert severity levels with associated colors."""
+
+    SUCCESS = "success"
+    WARNING = "warning"
+    ERROR = "error"
+    CRITICAL = "critical"
+    INFO = "info"
+
+    def get_color(self) -> int:
+        """Get the color code for this severity level (Discord/Slack compatible)."""
+        colors = {
+            AlertSeverity.SUCCESS: 0x28A745,  # Green
+            AlertSeverity.WARNING: 0xFFC107,  # Yellow/Amber
+            AlertSeverity.ERROR: 0xDC3545,  # Red
+            AlertSeverity.CRITICAL: 0x8B0000,  # Dark Red
+            AlertSeverity.INFO: 0x007BFF,  # Blue
+        }
+        return colors.get(self, 0x808080)  # Default to gray
+
+
+class AlertNode(Node):
+    """
+    Base class for all alert and notification nodes in the Kailash SDK.
+
+    This abstract base class provides common functionality for sending alerts
+    through various channels (Discord, Slack, email, webhooks, etc.). It defines
+    standard parameters that all alert nodes should support and provides utilities
+    for formatting messages consistently.
+
+    Design Philosophy:
+        Alert nodes should provide a simple, consistent interface for sending
+        notifications while allowing channel-specific features when needed.
+        The base class handles common concerns like severity levels, titles,
+        and context data, while subclasses implement channel-specific logic.
+
+    Common Parameters:
+        - alert_type: Severity level (success, warning, error, critical, info)
+        - title: Alert title/subject
+        - message: Main alert message body
+        - context: Additional structured data
+
+    Subclasses must implement:
+        - get_channel_parameters(): Define channel-specific parameters
+        - send_alert(): Implement the actual alert sending logic
+    """
+
+    category = "alerts"
+
+    def get_parameters(self) -> dict[str, NodeParameter]:
+        """Define common parameters for all alert nodes.
+
+        Returns:
+            Dictionary of common alert parameters merged with channel-specific ones
+        """
+        common_params = {
+            "alert_type": NodeParameter(
+                name="alert_type",
+                type=str,
+                required=False,
+                default="info",
+                description="Alert severity level: success, warning, error, critical, info",
+            ),
+            "title": NodeParameter(
+                name="title",
+                type=str,
+                required=True,
+                description="Alert title or subject",
+            ),
+            "message": NodeParameter(
+                name="message",
+                type=str,
+                required=False,
+                default="",
+                description="Main alert message body",
+            ),
+            "context": NodeParameter(
+                name="context",
+                type=dict,
+                required=False,
+                default={},
+                description="Additional context data to include in the alert",
+            ),
+        }
+
+        # Merge with channel-specific parameters
+        channel_params = self.get_channel_parameters()
+        return {**common_params, **channel_params}
+
+    @abstractmethod
+    def get_channel_parameters(self) -> dict[str, NodeParameter]:
+        """Define channel-specific parameters.
+
+        Subclasses must implement this to add their specific parameters
+        like webhook URLs, authentication tokens, formatting options, etc.
+
+        Returns:
+            Dictionary of channel-specific parameters
+        """
+        pass
+
+    def validate_alert_type(self, alert_type: str) -> AlertSeverity:
+        """Validate and normalize the alert type.
+
+        Args:
+            alert_type: String representation of alert severity
+
+        Returns:
+            Normalized AlertSeverity enum value
+
+        Raises:
+            ValueError: If alert_type is not valid
+        """
+        try:
+            return AlertSeverity(alert_type.lower())
+        except ValueError:
+            valid_types = [s.value for s in AlertSeverity]
+            raise ValueError(
+                f"Invalid alert_type '{alert_type}'. Must be one of: {', '.join(valid_types)}"
+            )
+
+    def format_context(self, context: dict[str, Any]) -> str:
+        """Format context dictionary for display.
+
+        Args:
+            context: Dictionary of context data
+
+        Returns:
+            Formatted string representation of context
+        """
+        if not context:
+            return ""
+
+        lines = []
+        for key, value in context.items():
+            # Handle nested dictionaries and lists
+            if isinstance(value, (dict, list)):
+                import json
+
+                value_str = json.dumps(value)  # No indent for single-line format
+            else:
+                value_str = str(value)
+
+            lines.append(f"**{key}**: {value_str}")
+
+        return "\n".join(lines)
+
+    def run(self, **kwargs) -> dict[str, Any]:
+        """Execute the alert node.
+
+        This method validates common parameters, normalizes the alert type,
+        and delegates to the subclass's send_alert method.
+
+        Args:
+            **kwargs: Alert parameters including common and channel-specific ones
+
+        Returns:
+            Dictionary with alert execution results
+        """
+        # Validate and normalize alert type
+        alert_type_str = kwargs.get("alert_type", "info")
+        alert_severity = self.validate_alert_type(alert_type_str)
+
+        # Extract common parameters
+        title = kwargs["title"]
+        message = kwargs.get("message", "")
+        context = kwargs.get("context", {})
+
+        # Extract channel-specific parameters only
+        channel_params = {
+            k: v
+            for k, v in kwargs.items()
+            if k not in ["alert_type", "title", "message", "context"]
+        }
+
+        # Call subclass implementation
+        result = self.send_alert(
+            severity=alert_severity,
+            title=title,
+            message=message,
+            context=context,
+            **channel_params,  # Pass only channel-specific params
+        )
+
+        # Add standard metadata to result
+        result["alert_type"] = alert_severity.value
+        result["title"] = title
+
+        return result
+
+    @abstractmethod
+    def send_alert(
+        self,
+        severity: AlertSeverity,
+        title: str,
+        message: str,
+        context: dict[str, Any],
+        **kwargs,
+    ) -> dict[str, Any]:
+        """Send the alert through the specific channel.
+
+        Subclasses must implement this method to handle the actual alert delivery.
+
+        Args:
+            severity: Normalized alert severity
+            title: Alert title
+            message: Alert message body
+            context: Additional context data
+            **kwargs: Channel-specific parameters
+
+        Returns:
+            Dictionary with channel-specific response data
+        """
+        pass