detectkit 0.2.4__py3-none-any.whl

detectkit/__init__.py

@@ -0,0 +1,17 @@
+"""
+detectk - Anomaly Detection for Time-Series Metrics
+
+A Python library for data analysts and engineers to monitor metrics with automatic anomaly detection.
+"""
+
+__version__ = "0.1.0"
+
+from detectkit.core.interval import Interval
+from detectkit.core.models import ColumnDefinition, TableModel
+
+__all__ = [
+    "Interval",
+    "ColumnDefinition",
+    "TableModel",
+    "__version__",
+]

detectkit/alerting/__init__.py

@@ -0,0 +1,13 @@
+"""Alerting functionality for detectk."""
+
+from detectkit.alerting.orchestrator import (
+    AlertConditions,
+    AlertOrchestrator,
+    DetectionRecord,
+)
+
+__all__ = [
+    "AlertOrchestrator",
+    "AlertConditions",
+    "DetectionRecord",
+]

detectkit/alerting/channels/__init__.py

@@ -0,0 +1,21 @@
+"""Alert channels for external notifications."""
+
+from detectkit.alerting.channels.base import AlertData, BaseAlertChannel
+from detectkit.alerting.channels.mattermost import MattermostChannel
+from detectkit.alerting.channels.slack import SlackChannel
+from detectkit.alerting.channels.webhook import WebhookChannel
+from detectkit.alerting.channels.telegram import TelegramChannel
+from detectkit.alerting.channels.email import EmailChannel
+
+from detectkit.alerting.channels.factory import AlertChannelFactory
+
+__all__ = [
+    "AlertData",
+    "BaseAlertChannel",
+    "WebhookChannel",
+    "MattermostChannel",
+    "SlackChannel",
+    "TelegramChannel",
+    "EmailChannel",
+    "AlertChannelFactory",
+]

detectkit/alerting/channels/base.py

@@ -0,0 +1,193 @@
+"""
+Base alert channel interface.
+
+All alert channels must inherit from BaseAlertChannel and implement
+the send() method for delivering alerts to specific destinations.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from detectkit.detectors.base import DetectionResult
+
+
+@dataclass
+class AlertData:
+    """
+    Data for alert message.
+
+    Contains all information needed to format and send an alert.
+
+    Attributes:
+        metric_name: Name of the metric
+        timestamp: Timestamp of the anomaly (datetime64)
+        timezone: Timezone for display (e.g., "Europe/Moscow")
+        value: Actual metric value
+        confidence_lower: Lower confidence bound
+        confidence_upper: Upper confidence bound
+        detector_name: Name/ID of detector that found the anomaly
+        detector_params: Detector parameters (JSON string)
+        direction: Direction of anomaly ("above" or "below")
+        severity: Severity score
+        detection_metadata: Additional metadata from detector
+        consecutive_count: Number of consecutive anomalies
+    """
+
+    metric_name: str
+    timestamp: Any  # datetime64 or datetime
+    timezone: str
+    value: float
+    confidence_lower: Optional[float]
+    confidence_upper: Optional[float]
+    detector_name: str
+    detector_params: str
+    direction: str
+    severity: float
+    detection_metadata: Dict[str, Any]
+    consecutive_count: int = 1
+
+
+class BaseAlertChannel(ABC):
+    """
+    Abstract base class for alert channels.
+
+    Alert channels deliver notifications to external systems when
+    anomalies are detected. Each channel implements a specific
+    delivery mechanism (webhook, email, etc.).
+
+    Example:
+        >>> class MyChannel(BaseAlertChannel):
+        ...     def send(self, alert_data, template=None):
+        ...         message = self.format_message(alert_data, template)
+        ...         # Send via specific mechanism
+        ...         return True
+    """
+
+    @abstractmethod
+    def send(
+        self,
+        alert_data: AlertData,
+        template: Optional[str] = None,
+    ) -> bool:
+        """
+        Send alert to this channel.
+
+        Args:
+            alert_data: Alert data to send
+            template: Optional custom message template
+                     Uses default template if None
+
+        Returns:
+            True if sent successfully, False otherwise
+
+        Raises:
+            Exception: If sending fails critically
+
+        Example:
+            >>> alert = AlertData(
+            ...     metric_name="cpu_usage",
+            ...     timestamp=datetime.now(),
+            ...     value=95.0,
+            ...     ...
+            ... )
+            >>> success = channel.send(alert)
+        """
+        pass
+
+    def format_message(
+        self,
+        alert_data: AlertData,
+        template: Optional[str] = None,
+    ) -> str:
+        """
+        Format alert message from template.
+
+        Uses default template if none provided. Template variables:
+        - {metric_name}
+        - {timestamp}
+        - {timezone}
+        - {value}
+        - {confidence_lower}
+        - {confidence_upper}
+        - {detector_name}
+        - {direction}
+        - {severity}
+        - {consecutive_count}
+
+        Args:
+            alert_data: Alert data to format
+            template: Optional custom template string
+
+        Returns:
+            Formatted message string
+
+        Example:
+            >>> template = "Anomaly in {metric_name}: {value}"
+            >>> message = channel.format_message(alert_data, template)
+        """
+        if template is None:
+            template = self.get_default_template()
+
+        # Format timestamp to string
+        from datetime import datetime
+        import numpy as np
+
+        ts = alert_data.timestamp
+        if isinstance(ts, np.datetime64):
+            ts = ts.astype(datetime)
+
+        # Format timestamp with timezone
+        ts_str = ts.strftime("%Y-%m-%d %H:%M:%S")
+        if alert_data.timezone:
+            ts_str = f"{ts_str} ({alert_data.timezone})"
+
+        # Format confidence interval
+        if alert_data.confidence_lower is not None and alert_data.confidence_upper is not None:
+            confidence_str = f"[{alert_data.confidence_lower:.2f}, {alert_data.confidence_upper:.2f}]"
+        else:
+            confidence_str = "N/A"
+
+        # Format message
+        try:
+            message = template.format(
+                metric_name=alert_data.metric_name,
+                timestamp=ts_str,
+                timezone=alert_data.timezone,
+                value=alert_data.value,
+                confidence_lower=alert_data.confidence_lower,
+                confidence_upper=alert_data.confidence_upper,
+                confidence_interval=confidence_str,
+                detector_name=alert_data.detector_name,
+                detector_params=alert_data.detector_params,
+                direction=alert_data.direction,
+                severity=alert_data.severity,
+                consecutive_count=alert_data.consecutive_count,
+            )
+        except KeyError as e:
+            # If template has unknown variables, fall back to default
+            message = self.format_message(alert_data, self.get_default_template())
+
+        return message
+
+    def get_default_template(self) -> str:
+        """
+        Get default message template.
+
+        Returns:
+            Default template string
+        """
+        return (
+            "Anomaly detected in metric: {metric_name}\n"
+            "Time: {timestamp}\n"
+            "Value: {value}\n"
+            "Confidence interval: {confidence_interval}\n"
+            "Detector: {detector_name}\n"
+            "Parameters: {detector_params}\n"
+            "Direction: {direction}\n"
+            "Severity: {severity:.2f}"
+        )
+
+    def __repr__(self) -> str:
+        """String representation of channel."""
+        return f"{self.__class__.__name__}()"

detectkit/alerting/channels/email.py

@@ -0,0 +1,146 @@
+"""
+Email alert channel implementation.
+
+Sends anomaly alerts via SMTP email.
+"""
+
+import smtplib
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from typing import List, Optional
+
+from detectkit.alerting.channels.base import AlertData, BaseAlertChannel
+
+
+class EmailChannel(BaseAlertChannel):
+    """
+    Email alert channel using SMTP.
+
+    Sends formatted emails via SMTP server.
+
+    Attributes:
+        smtp_host: SMTP server hostname
+        smtp_port: SMTP server port
+        smtp_username: SMTP authentication username
+        smtp_password: SMTP authentication password
+        from_email: Sender email address
+        to_emails: List of recipient email addresses
+        use_tls: Whether to use TLS encryption
+        subject_template: Email subject template
+
+    Example:
+        >>> channel = EmailChannel(
+        ...     smtp_host="smtp.gmail.com",
+        ...     smtp_port=587,
+        ...     smtp_username="alerts@example.com",
+        ...     smtp_password="password",
+        ...     from_email="alerts@example.com",
+        ...     to_emails=["team@example.com"]
+        ... )
+        >>> alert = AlertData(
+        ...     metric_name="cpu_usage",
+        ...     timestamp=np.datetime64("2024-01-01T10:00:00"),
+        ...     value=95.0,
+        ...     is_anomaly=True
+        ... )
+        >>> channel.send(alert)
+    """
+
+    def __init__(
+        self,
+        smtp_host: str,
+        smtp_port: int,
+        from_email: str,
+        to_emails: List[str],
+        smtp_username: Optional[str] = None,
+        smtp_password: Optional[str] = None,
+        use_tls: bool = True,
+        subject_template: str = "Anomaly Alert: {metric_name}",
+        template: Optional[str] = None,
+        **kwargs,
+    ):
+        """
+        Initialize email channel.
+
+        Args:
+            smtp_host: SMTP server hostname
+            smtp_port: SMTP server port (typically 587 for TLS, 465 for SSL)
+            from_email: Sender email address
+            to_emails: List of recipient email addresses
+            smtp_username: SMTP authentication username (optional)
+            smtp_password: SMTP authentication password (optional)
+            use_tls: Whether to use STARTTLS (default: True)
+            subject_template: Email subject template with {metric_name} placeholder
+            template: Custom message template (optional)
+            **kwargs: Additional parameters (ignored)
+
+        Raises:
+            ValueError: If required parameters are missing
+        """
+        if not smtp_host:
+            raise ValueError("smtp_host is required for EmailChannel")
+        if not smtp_port:
+            raise ValueError("smtp_port is required for EmailChannel")
+        if not from_email:
+            raise ValueError("from_email is required for EmailChannel")
+        if not to_emails:
+            raise ValueError("to_emails is required for EmailChannel")
+
+        self.smtp_host = smtp_host
+        self.smtp_port = smtp_port
+        self.smtp_username = smtp_username
+        self.smtp_password = smtp_password
+        self.from_email = from_email
+        self.to_emails = to_emails
+        self.use_tls = use_tls
+        self.subject_template = subject_template
+        self.template = template
+
+    def send(self, alert_data: AlertData) -> None:
+        """
+        Send alert via email.
+
+        Args:
+            alert_data: Alert information to send
+
+        Raises:
+            smtplib.SMTPException: If email sending fails
+
+        Example:
+            >>> channel.send(alert_data)
+        """
+        message_body = self.format_message(alert_data, self.template)
+
+        # Create email message
+        msg = MIMEMultipart("alternative")
+        msg["From"] = self.from_email
+        msg["To"] = ", ".join(self.to_emails)
+        msg["Subject"] = self.subject_template.format(
+            metric_name=alert_data.metric_name
+        )
+
+        # Attach plain text body
+        msg.attach(MIMEText(message_body, "plain"))
+
+        try:
+            # Connect to SMTP server
+            if self.use_tls:
+                server = smtplib.SMTP(self.smtp_host, self.smtp_port, timeout=10)
+                server.starttls()
+            else:
+                server = smtplib.SMTP_SSL(self.smtp_host, self.smtp_port, timeout=10)
+
+            # Login if credentials provided
+            if self.smtp_username and self.smtp_password:
+                server.login(self.smtp_username, self.smtp_password)
+
+            # Send email
+            server.sendmail(self.from_email, self.to_emails, msg.as_string())
+            server.quit()
+
+        except smtplib.SMTPException as e:
+            raise smtplib.SMTPException(f"Failed to send email alert: {e}")
+
+    def __repr__(self) -> str:
+        """String representation."""
+        return f"EmailChannel(to={self.to_emails})"

detectkit/alerting/channels/factory.py

@@ -0,0 +1,193 @@
+"""
+Alert channel factory for creating channel instances from configuration.
+"""
+
+import os
+from typing import Dict, List
+
+from detectkit.alerting.channels.base import BaseAlertChannel
+from detectkit.alerting.channels.mattermost import MattermostChannel
+from detectkit.alerting.channels.slack import SlackChannel
+from detectkit.alerting.channels.webhook import WebhookChannel
+from detectkit.alerting.channels.telegram import TelegramChannel
+from detectkit.alerting.channels.email import EmailChannel
+
+
+class AlertChannelFactory:
+    """
+    Factory for creating alert channel instances from configuration.
+
+    Supports environment variable interpolation in config values.
+
+    Example:
+        >>> factory = AlertChannelFactory()
+        >>> channel = factory.create("mattermost", {"webhook_url": "https://..."})
+        >>> isinstance(channel, MattermostChannel)
+        True
+    """
+
+    # Registry of available channel types
+    CHANNEL_TYPES = {
+        "webhook": WebhookChannel,
+        "mattermost": MattermostChannel,
+        "slack": SlackChannel,
+        "telegram": TelegramChannel,
+        "email": EmailChannel,
+    }
+
+    @classmethod
+    def create(cls, channel_type: str, params: Dict) -> BaseAlertChannel:
+        """
+        Create alert channel instance from type and parameters.
+
+        Supports environment variable interpolation:
+        - ${ENV_VAR} or {{ env_var('ENV_VAR') }}
+
+        Args:
+            channel_type: Type of channel (e.g., "mattermost", "slack")
+            params: Channel parameters
+
+        Returns:
+            Alert channel instance
+
+        Raises:
+            ValueError: If channel type is unknown
+
+        Example:
+            >>> channel = AlertChannelFactory.create(
+            ...     "mattermost",
+            ...     {"webhook_url": "${MATTERMOST_WEBHOOK}"}
+            ... )
+        """
+        channel_type = channel_type.lower()
+
+        if channel_type not in cls.CHANNEL_TYPES:
+            available = ", ".join(sorted(cls.CHANNEL_TYPES.keys()))
+            raise ValueError(
+                f"Unknown channel type: '{channel_type}'. "
+                f"Available types: {available}"
+            )
+
+        # Interpolate environment variables in params
+        interpolated_params = cls._interpolate_env_vars(params)
+
+        channel_class = cls.CHANNEL_TYPES[channel_type]
+
+        try:
+            return channel_class(**interpolated_params)
+        except TypeError as e:
+            raise ValueError(
+                f"Invalid parameters for {channel_type} channel: {e}"
+            ) from e
+
+    @classmethod
+    def _interpolate_env_vars(cls, params: Dict) -> Dict:
+        """
+        Interpolate environment variables in parameter values.
+
+        Supports formats:
+        - ${VAR_NAME}
+        - {{ env_var('VAR_NAME') }}
+
+        Args:
+            params: Parameters dictionary
+
+        Returns:
+            Parameters with interpolated values
+        """
+        import re
+
+        interpolated = {}
+
+        for key, value in params.items():
+            if isinstance(value, str):
+                # Handle ${VAR} format
+                value = re.sub(
+                    r'\$\{([^}]+)\}',
+                    lambda m: os.environ.get(m.group(1), m.group(0)),
+                    value,
+                )
+
+                # Handle {{ env_var('VAR') }} format
+                value = re.sub(
+                    r"\{\{\s*env_var\(['\"]([^'\"]+)['\"]\)\s*\}\}",
+                    lambda m: os.environ.get(m.group(1), m.group(0)),
+                    value,
+                )
+
+            interpolated[key] = value
+
+        return interpolated
+
+    @classmethod
+    def create_from_config(cls, channel_config: Dict) -> BaseAlertChannel:
+        """
+        Create channel from configuration dictionary.
+
+        Args:
+            channel_config: Configuration with 'type' and channel-specific params
+                Example: {
+                    "type": "mattermost",
+                    "webhook_url": "${MATTERMOST_WEBHOOK}",
+                    "username": "detectkit"
+                }
+
+        Returns:
+            Alert channel instance
+
+        Example:
+            >>> config = {
+            ...     "type": "mattermost",
+            ...     "webhook_url": "https://example.com/hooks/xxx"
+            ... }
+            >>> channel = AlertChannelFactory.create_from_config(config)
+        """
+        channel_type = channel_config.get("type")
+        if not channel_type:
+            raise ValueError("Channel config must have 'type' field")
+
+        # Extract all params except 'type'
+        params = {k: v for k, v in channel_config.items() if k != "type"}
+
+        return cls.create(channel_type, params)
+
+    @classmethod
+    def create_multiple(cls, channel_configs: List[Dict]) -> List[BaseAlertChannel]:
+        """
+        Create multiple channels from list of configurations.
+
+        Args:
+            channel_configs: List of channel configurations
+
+        Returns:
+            List of channel instances
+
+        Example:
+            >>> configs = [
+            ...     {"type": "mattermost", "webhook_url": "https://..."},
+            ...     {"type": "slack", "webhook_url": "https://...", "channel": "#alerts"},
+            ... ]
+            >>> channels = AlertChannelFactory.create_multiple(configs)
+            >>> len(channels)
+            2
+        """
+        channels = []
+        for config in channel_configs:
+            channel = cls.create_from_config(config)
+            channels.append(channel)
+        return channels
+
+    @classmethod
+    def list_available_types(cls) -> List[str]:
+        """
+        Get list of available channel types.
+
+        Returns:
+            List of channel type names
+
+        Example:
+            >>> types = AlertChannelFactory.list_available_types()
+            >>> "mattermost" in types
+            True
+        """
+        return sorted(cls.CHANNEL_TYPES.keys())

detectkit/alerting/channels/mattermost.py

@@ -0,0 +1,53 @@
+"""
+Mattermost alert channel.
+
+Convenience wrapper around WebhookChannel for Mattermost.
+"""
+
+from typing import Optional
+
+from detectkit.alerting.channels.webhook import WebhookChannel
+
+
+class MattermostChannel(WebhookChannel):
+    """
+    Mattermost alert channel using incoming webhooks.
+
+    This is a convenience wrapper around WebhookChannel specifically
+    for Mattermost. Mattermost webhooks are compatible with Slack API,
+    so WebhookChannel can be used directly.
+
+    Parameters:
+        webhook_url (str): Mattermost incoming webhook URL
+        username (str): Bot username to display (default: "detectk")
+        icon_emoji (str): Bot emoji icon (default: ":warning:")
+        timeout (int): Request timeout in seconds (default: 10)
+
+    Example:
+        >>> channel = MattermostChannel(
+        ...     webhook_url="https://mattermost.example.com/hooks/xxx"
+        ... )
+        >>> success = channel.send(alert_data)
+    """
+
+    def __init__(
+        self,
+        webhook_url: str,
+        username: str = "detectk",
+        icon_emoji: str = ":warning:",
+        channel: Optional[str] = None,
+        timeout: int = 10,
+    ):
+        """Initialize Mattermost channel with webhook URL."""
+        super().__init__(
+            webhook_url=webhook_url,
+            username=username,
+            icon_emoji=icon_emoji,
+            channel=channel,  # Optional: override webhook's default channel
+            timeout=timeout,
+        )
+
+    def __repr__(self) -> str:
+        """String representation."""
+        url_preview = self.webhook_url[:30] + "..." if len(self.webhook_url) > 30 else self.webhook_url
+        return f"MattermostChannel(url='{url_preview}', username='{self.username}')"

detectkit/alerting/channels/slack.py

@@ -0,0 +1,55 @@
+"""
+Slack alert channel.
+
+Convenience wrapper around WebhookChannel for Slack.
+"""
+
+from typing import Optional
+
+from detectkit.alerting.channels.webhook import WebhookChannel
+
+
+class SlackChannel(WebhookChannel):
+    """
+    Slack alert channel using incoming webhooks.
+
+    This is a convenience wrapper around WebhookChannel specifically
+    for Slack. Slack and Mattermost use compatible webhook formats.
+
+    Parameters:
+        webhook_url (str): Slack incoming webhook URL
+        username (str): Bot username to display (default: "detectk")
+        icon_emoji (str): Bot emoji icon (default: ":warning:")
+        channel (str): Target Slack channel (optional, e.g., "#alerts")
+        timeout (int): Request timeout in seconds (default: 10)
+
+    Example:
+        >>> channel = SlackChannel(
+        ...     webhook_url="https://hooks.slack.com/services/xxx",
+        ...     channel="#alerts"
+        ... )
+        >>> success = channel.send(alert_data)
+    """
+
+    def __init__(
+        self,
+        webhook_url: str,
+        username: str = "detectk",
+        icon_emoji: str = ":warning:",
+        channel: Optional[str] = None,
+        timeout: int = 10,
+    ):
+        """Initialize Slack channel with webhook URL."""
+        super().__init__(
+            webhook_url=webhook_url,
+            username=username,
+            icon_emoji=icon_emoji,
+            channel=channel,
+            timeout=timeout,
+        )
+
+    def __repr__(self) -> str:
+        """String representation."""
+        url_preview = self.webhook_url[:30] + "..." if len(self.webhook_url) > 30 else self.webhook_url
+        channel_info = f", channel='{self.channel}'" if self.channel else ""
+        return f"SlackChannel(url='{url_preview}', username='{self.username}'{channel_info})"