empathy-framework 4.6.6__py3-none-any.whl → 4.7.1__py3-none-any.whl

empathy_os/monitoring/alerts.py

@@ -3,21 +3,950 @@
 Provides threshold-based alerting for LLM usage metrics.
 
 **Features:**
-- Interactive CLI wizard (`empathy alerts init`)
+- Interactive CLI workflow (`empathy alerts init`)
 - Multiple notification channels (webhook, email, stdout)
 - Threshold triggers (daily cost, error rate, etc.)
 - Cooldown mechanism (prevent spam)
 - Enterprise background daemon (`empathy alerts watch --daemon`)
 
-**Implementation Status:** Sprint 3 (Week 3)
+**Supported Metrics:**
+- daily_cost: Total USD spent in the last 24 hours
+- error_rate: Percentage of failed LLM calls
+- avg_latency: Average response time in milliseconds
+- token_usage: Total tokens used in the last 24 hours
 
-Copyright 2025 Smart-AI-Memory
+Copyright 2025-2026 Smart-AI-Memory
 Licensed under Fair Source License 0.9
 """
 
-# TODO: Implement in Sprint 3
-# - AlertEngine class
-# - CLI wizard for setup
-# - Background watcher (optional daemon)
-# - Webhook delivery
-# - Email notifications
+from __future__ import annotations
+
+import ipaddress
+import json
+import logging
+import smtplib
+import sqlite3
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def _validate_webhook_url(url: str) -> str:
+    """Validate webhook URL to prevent SSRF attacks.
+
+    Args:
+        url: Webhook URL to validate
+
+    Returns:
+        Validated URL (unchanged if valid)
+
+    Raises:
+        ValueError: If URL is invalid or targets unsafe destinations
+
+    Security:
+        Prevents Server-Side Request Forgery (SSRF) by blocking:
+        - Non-HTTP(S) schemes (file://, gopher://, ftp://)
+        - Localhost and loopback addresses (127.0.0.1, ::1)
+        - Cloud metadata services (169.254.169.254)
+        - Private IP ranges (10.x, 172.16-31.x, 192.168.x)
+        - Common internal service ports (Redis, PostgreSQL, etc.)
+    """
+    if not url or not isinstance(url, str):
+        raise ValueError("webhook_url must be a non-empty string")
+
+    # Parse URL
+    try:
+        parsed = urllib.parse.urlparse(url)
+    except Exception as e:
+        raise ValueError(f"Invalid URL format: {e}")
+
+    # Only allow http and https schemes
+    if parsed.scheme not in ("http", "https"):
+        raise ValueError(
+            f"Invalid scheme '{parsed.scheme}'. Only http and https allowed for webhooks."
+        )
+
+    # Check hostname exists
+    hostname = parsed.hostname
+    if not hostname:
+        raise ValueError("Webhook URL must contain a valid hostname")
+
+    # Blocked hostnames (localhost, metadata services)
+    blocked_hosts = {
+        "localhost",
+        "127.0.0.1",
+        "0.0.0.0",
+        "::1",
+        "[::1]",
+        "169.254.169.254",  # AWS metadata
+        "metadata.google.internal",  # GCP metadata
+        "instance-data",  # Azure metadata pattern
+    }
+
+    hostname_lower = hostname.lower()
+    if hostname_lower in blocked_hosts:
+        raise ValueError(f"Webhook URL cannot target local or metadata address: {hostname}")
+
+    # Check for private/internal IPs
+    try:
+        ip = ipaddress.ip_address(hostname)
+        if ip.is_private:
+            raise ValueError(f"Webhook URL cannot target private IP: {hostname}")
+        if ip.is_loopback:
+            raise ValueError(f"Webhook URL cannot target loopback address: {hostname}")
+        if ip.is_link_local:
+            raise ValueError(f"Webhook URL cannot target link-local address: {hostname}")
+        if ip.is_reserved:
+            raise ValueError(f"Webhook URL cannot target reserved IP: {hostname}")
+    except ValueError as e:
+        # Check if this is our own validation error
+        if "cannot target" in str(e):
+            raise
+        # Not an IP address (it's a hostname) - that's fine, continue
+
+    # Block common internal service ports
+    if parsed.port is not None:
+        blocked_ports = {
+            22,     # SSH
+            23,     # Telnet
+            3306,   # MySQL
+            5432,   # PostgreSQL
+            6379,   # Redis
+            27017,  # MongoDB
+            9200,   # Elasticsearch
+            2379,   # etcd
+            8500,   # Consul
+        }
+        if parsed.port in blocked_ports:
+            raise ValueError(
+                f"Webhook URL cannot target internal service port {parsed.port}. "
+                "Use standard HTTP (80) or HTTPS (443) ports."
+            )
+
+    return url
+
+
+class AlertChannel(Enum):
+    """Notification channels for alerts."""
+
+    WEBHOOK = "webhook"
+    EMAIL = "email"
+    VSCODE_OUTPUT = "vscode_output"
+    STDOUT = "stdout"
+
+
+class AlertMetric(Enum):
+    """Metrics that can be monitored."""
+
+    DAILY_COST = "daily_cost"
+    ERROR_RATE = "error_rate"
+    AVG_LATENCY = "avg_latency"
+    TOKEN_USAGE = "token_usage"
+
+
+class AlertSeverity(Enum):
+    """Alert severity levels."""
+
+    INFO = "info"
+    WARNING = "warning"
+    CRITICAL = "critical"
+
+
+@dataclass
+class AlertConfig:
+    """Configuration for a single alert."""
+
+    alert_id: str
+    name: str
+    metric: AlertMetric
+    threshold: float
+    channel: AlertChannel
+    webhook_url: str | None = None
+    email: str | None = None
+    enabled: bool = True
+    cooldown_seconds: int = 3600  # 1 hour default
+    severity: AlertSeverity = AlertSeverity.WARNING
+    created_at: datetime | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "alert_id": self.alert_id,
+            "name": self.name,
+            "metric": self.metric.value,
+            "threshold": self.threshold,
+            "channel": self.channel.value,
+            "webhook_url": self.webhook_url,
+            "email": self.email,
+            "enabled": self.enabled,
+            "cooldown_seconds": self.cooldown_seconds,
+            "severity": self.severity.value,
+            "created_at": self.created_at.isoformat() if self.created_at else None,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AlertConfig:
+        """Create from dictionary."""
+        return cls(
+            alert_id=data["alert_id"],
+            name=data["name"],
+            metric=AlertMetric(data["metric"]),
+            threshold=data["threshold"],
+            channel=AlertChannel(data["channel"]),
+            webhook_url=data.get("webhook_url"),
+            email=data.get("email"),
+            enabled=data.get("enabled", True),
+            cooldown_seconds=data.get("cooldown_seconds", 3600),
+            severity=AlertSeverity(data.get("severity", "warning")),
+            created_at=datetime.fromisoformat(data["created_at"])
+            if data.get("created_at")
+            else None,
+        )
+
+
+@dataclass
+class AlertEvent:
+    """An alert event that was triggered."""
+
+    alert_id: str
+    alert_name: str
+    metric: AlertMetric
+    current_value: float
+    threshold: float
+    severity: AlertSeverity
+    triggered_at: datetime
+    message: str
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "alert_id": self.alert_id,
+            "alert_name": self.alert_name,
+            "metric": self.metric.value,
+            "current_value": self.current_value,
+            "threshold": self.threshold,
+            "severity": self.severity.value,
+            "triggered_at": self.triggered_at.isoformat(),
+            "message": self.message,
+        }
+
+
+class AlertEngine:
+    """Alert engine with SQLite storage and notification delivery.
+
+    Monitors telemetry metrics and sends alerts when thresholds are exceeded.
+
+    Example:
+        >>> engine = AlertEngine()
+        >>> engine.add_alert(
+        ...     alert_id="cost_alert",
+        ...     name="Daily Cost Alert",
+        ...     metric=AlertMetric.DAILY_COST,
+        ...     threshold=10.0,
+        ...     channel=AlertChannel.WEBHOOK,
+        ...     webhook_url="https://hooks.slack.com/..."
+        ... )
+        >>> events = engine.check_and_trigger()
+        >>> for event in events:
+        ...     print(f"Alert: {event.message}")
+    """
+
+    def __init__(
+        self,
+        db_path: str | Path = ".empathy/alerts.db",
+        telemetry_dir: str | Path | None = None,
+    ):
+        """Initialize AlertEngine.
+
+        Args:
+            db_path: Path to SQLite database for alert storage
+            telemetry_dir: Path to telemetry directory (default: ~/.empathy/telemetry)
+        """
+        self.db_path = Path(db_path)
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+
+        self.telemetry_dir = (
+            Path(telemetry_dir)
+            if telemetry_dir
+            else Path.home() / ".empathy" / "telemetry"
+        )
+
+        self._cooldown_cache: dict[str, float] = {}  # alert_id -> last_triggered_time
+        self._init_db()
+
+    def _init_db(self) -> None:
+        """Initialize SQLite database with alerts and history tables."""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        # Alerts configuration table
+        cursor.execute(
+            """
+            CREATE TABLE IF NOT EXISTS alerts (
+                id TEXT PRIMARY KEY,
+                name TEXT NOT NULL,
+                metric TEXT NOT NULL,
+                threshold REAL NOT NULL,
+                channel TEXT NOT NULL,
+                webhook_url TEXT,
+                email TEXT,
+                enabled INTEGER DEFAULT 1,
+                cooldown INTEGER DEFAULT 3600,
+                severity TEXT DEFAULT 'warning',
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+        """
+        )
+
+        # Alert history table for audit trail
+        cursor.execute(
+            """
+            CREATE TABLE IF NOT EXISTS alert_history (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                alert_id TEXT NOT NULL,
+                metric TEXT NOT NULL,
+                current_value REAL NOT NULL,
+                threshold REAL NOT NULL,
+                severity TEXT NOT NULL,
+                triggered_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                delivered INTEGER DEFAULT 0,
+                delivery_error TEXT,
+                FOREIGN KEY (alert_id) REFERENCES alerts(id)
+            )
+        """
+        )
+
+        conn.commit()
+        conn.close()
+
+    def add_alert(
+        self,
+        alert_id: str,
+        name: str,
+        metric: AlertMetric | str,
+        threshold: float,
+        channel: AlertChannel | str,
+        webhook_url: str | None = None,
+        email: str | None = None,
+        cooldown_seconds: int = 3600,
+        severity: AlertSeverity | str = AlertSeverity.WARNING,
+    ) -> AlertConfig:
+        """Add a new alert configuration.
+
+        Args:
+            alert_id: Unique identifier for the alert
+            name: Human-readable name
+            metric: Metric to monitor
+            threshold: Threshold value that triggers the alert
+            channel: Notification channel
+            webhook_url: Webhook URL (required for webhook channel)
+            email: Email address (required for email channel)
+            cooldown_seconds: Minimum seconds between alerts
+            severity: Alert severity level
+
+        Returns:
+            AlertConfig for the created alert
+
+        Raises:
+            ValueError: If webhook_url missing for webhook channel or email missing for email channel
+        """
+        # Normalize enum values
+        if isinstance(metric, str):
+            metric = AlertMetric(metric)
+        if isinstance(channel, str):
+            channel = AlertChannel(channel)
+        if isinstance(severity, str):
+            severity = AlertSeverity(severity)
+
+        # Validate channel requirements
+        if channel == AlertChannel.WEBHOOK and not webhook_url:
+            raise ValueError("webhook_url required for webhook channel")
+        if channel == AlertChannel.EMAIL and not email:
+            raise ValueError("email required for email channel")
+
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        cursor.execute(
+            """
+            INSERT OR REPLACE INTO alerts
+            (id, name, metric, threshold, channel, webhook_url, email, cooldown, severity)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+            (
+                alert_id,
+                name,
+                metric.value,
+                threshold,
+                channel.value,
+                webhook_url,
+                email,
+                cooldown_seconds,
+                severity.value,
+            ),
+        )
+
+        conn.commit()
+        conn.close()
+
+        logger.info(
+            "alert_created",
+            alert_id=alert_id,
+            metric=metric.value,
+            threshold=threshold,
+            channel=channel.value,
+        )
+
+        return AlertConfig(
+            alert_id=alert_id,
+            name=name,
+            metric=metric,
+            threshold=threshold,
+            channel=channel,
+            webhook_url=webhook_url,
+            email=email,
+            cooldown_seconds=cooldown_seconds,
+            severity=severity,
+            created_at=datetime.now(),
+        )
+
+    def list_alerts(self) -> list[AlertConfig]:
+        """List all configured alerts.
+
+        Returns:
+            List of AlertConfig objects
+        """
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        cursor.execute(
+            "SELECT id, name, metric, threshold, channel, webhook_url, email, "
+            "enabled, cooldown, severity, created_at FROM alerts"
+        )
+        rows = cursor.fetchall()
+        conn.close()
+
+        alerts = []
+        for row in rows:
+            alerts.append(
+                AlertConfig(
+                    alert_id=row[0],
+                    name=row[1],
+                    metric=AlertMetric(row[2]),
+                    threshold=row[3],
+                    channel=AlertChannel(row[4]),
+                    webhook_url=row[5],
+                    email=row[6],
+                    enabled=bool(row[7]),
+                    cooldown_seconds=row[8],
+                    severity=AlertSeverity(row[9]) if row[9] else AlertSeverity.WARNING,
+                    created_at=datetime.fromisoformat(row[10]) if row[10] else None,
+                )
+            )
+
+        return alerts
+
+    def get_alert(self, alert_id: str) -> AlertConfig | None:
+        """Get a specific alert by ID.
+
+        Args:
+            alert_id: The alert ID
+
+        Returns:
+            AlertConfig or None if not found
+        """
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        cursor.execute(
+            "SELECT id, name, metric, threshold, channel, webhook_url, email, "
+            "enabled, cooldown, severity, created_at FROM alerts WHERE id = ?",
+            (alert_id,),
+        )
+        row = cursor.fetchone()
+        conn.close()
+
+        if not row:
+            return None
+
+        return AlertConfig(
+            alert_id=row[0],
+            name=row[1],
+            metric=AlertMetric(row[2]),
+            threshold=row[3],
+            channel=AlertChannel(row[4]),
+            webhook_url=row[5],
+            email=row[6],
+            enabled=bool(row[7]),
+            cooldown_seconds=row[8],
+            severity=AlertSeverity(row[9]) if row[9] else AlertSeverity.WARNING,
+            created_at=datetime.fromisoformat(row[10]) if row[10] else None,
+        )
+
+    def delete_alert(self, alert_id: str) -> bool:
+        """Delete an alert by ID.
+
+        Args:
+            alert_id: The alert ID to delete
+
+        Returns:
+            True if deleted, False if not found
+        """
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        cursor.execute("DELETE FROM alerts WHERE id = ?", (alert_id,))
+        deleted = cursor.rowcount > 0
+
+        conn.commit()
+        conn.close()
+
+        if deleted:
+            logger.info("alert_deleted", alert_id=alert_id)
+
+        return deleted
+
+    def enable_alert(self, alert_id: str) -> bool:
+        """Enable an alert."""
+        return self._set_alert_enabled(alert_id, True)
+
+    def disable_alert(self, alert_id: str) -> bool:
+        """Disable an alert."""
+        return self._set_alert_enabled(alert_id, False)
+
+    def _set_alert_enabled(self, alert_id: str, enabled: bool) -> bool:
+        """Set alert enabled status."""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        cursor.execute(
+            "UPDATE alerts SET enabled = ? WHERE id = ?", (int(enabled), alert_id)
+        )
+        updated = cursor.rowcount > 0
+
+        conn.commit()
+        conn.close()
+
+        return updated
+
+    def get_metrics(self) -> dict[str, float]:
+        """Get current telemetry metrics.
+
+        Reads from telemetry files and calculates:
+        - daily_cost: Total cost in last 24 hours
+        - error_rate: Percentage of errors
+        - avg_latency: Average latency in ms
+        - token_usage: Total tokens in last 24 hours
+
+        Returns:
+            Dictionary of metric name to current value
+        """
+        usage_file = self.telemetry_dir / "usage.jsonl"
+
+        if not usage_file.exists():
+            logger.debug("telemetry_file_not_found", path=str(usage_file))
+            return {
+                "daily_cost": 0.0,
+                "error_rate": 0.0,
+                "avg_latency": 0.0,
+                "token_usage": 0,
+            }
+
+        # Read last 24 hours of data
+        cutoff = datetime.now() - timedelta(hours=24)
+        total_cost = 0.0
+        total_tokens = 0
+        total_latency = 0.0
+        total_calls = 0
+        error_calls = 0
+
+        try:
+            with open(usage_file) as f:
+                for line in f:
+                    if not line.strip():
+                        continue
+                    try:
+                        entry = json.loads(line)
+                        timestamp = datetime.fromisoformat(
+                            entry.get("timestamp", "2000-01-01")
+                        )
+                        if timestamp < cutoff:
+                            continue
+
+                        total_calls += 1
+                        total_cost += entry.get("cost", 0.0)
+                        total_tokens += entry.get("tokens", {}).get("total", 0)
+                        total_latency += entry.get("duration_ms", 0)
+
+                        if entry.get("error"):
+                            error_calls += 1
+                    except (json.JSONDecodeError, KeyError):
+                        continue
+        except (OSError, PermissionError) as e:
+            logger.warning("telemetry_read_error", error=str(e))
+            return {
+                "daily_cost": 0.0,
+                "error_rate": 0.0,
+                "avg_latency": 0.0,
+                "token_usage": 0,
+            }
+
+        return {
+            "daily_cost": total_cost,
+            "error_rate": (error_calls / total_calls * 100) if total_calls > 0 else 0.0,
+            "avg_latency": (total_latency / total_calls) if total_calls > 0 else 0.0,
+            "token_usage": total_tokens,
+        }
+
+    def check_and_trigger(self) -> list[AlertEvent]:
+        """Check all alerts and trigger notifications if thresholds exceeded.
+
+        Returns:
+            List of AlertEvent objects for triggered alerts
+        """
+        alerts = self.list_alerts()
+        metrics = self.get_metrics()
+        triggered_events = []
+
+        for alert in alerts:
+            if not alert.enabled:
+                continue
+
+            # Check cooldown
+            last_triggered = self._cooldown_cache.get(alert.alert_id, 0)
+            if time.time() - last_triggered < alert.cooldown_seconds:
+                logger.debug(
+                    "alert_in_cooldown",
+                    alert_id=alert.alert_id,
+                    remaining=alert.cooldown_seconds - (time.time() - last_triggered),
+                )
+                continue
+
+            # Get current metric value
+            current_value = metrics.get(alert.metric.value, 0.0)
+
+            # Check threshold
+            if current_value >= alert.threshold:
+                event = AlertEvent(
+                    alert_id=alert.alert_id,
+                    alert_name=alert.name,
+                    metric=alert.metric,
+                    current_value=current_value,
+                    threshold=alert.threshold,
+                    severity=alert.severity,
+                    triggered_at=datetime.now(),
+                    message=self._format_alert_message(alert, current_value),
+                )
+
+                # Deliver notification
+                success = self._deliver_notification(alert, event)
+
+                # Record in history
+                self._record_alert_history(event, success)
+
+                # Update cooldown
+                self._cooldown_cache[alert.alert_id] = time.time()
+
+                triggered_events.append(event)
+
+                logger.info(
+                    "alert_triggered",
+                    alert_id=alert.alert_id,
+                    metric=alert.metric.value,
+                    current_value=current_value,
+                    threshold=alert.threshold,
+                    delivered=success,
+                )
+
+        return triggered_events
+
+    def _format_alert_message(self, alert: AlertConfig, current_value: float) -> str:
+        """Format human-readable alert message."""
+        metric_units = {
+            AlertMetric.DAILY_COST: "USD",
+            AlertMetric.ERROR_RATE: "%",
+            AlertMetric.AVG_LATENCY: "ms",
+            AlertMetric.TOKEN_USAGE: "tokens",
+        }
+        unit = metric_units.get(alert.metric, "")
+
+        return (
+            f"[{alert.severity.value.upper()}] {alert.name}\n"
+            f"Metric: {alert.metric.value}\n"
+            f"Current: {current_value:.2f} {unit}\n"
+            f"Threshold: {alert.threshold:.2f} {unit}\n"
+            f"Triggered at: {datetime.now().isoformat()}"
+        )
+
+    def _deliver_notification(self, alert: AlertConfig, event: AlertEvent) -> bool:
+        """Deliver notification through configured channel.
+
+        Args:
+            alert: The alert configuration
+            event: The alert event
+
+        Returns:
+            True if delivered successfully
+        """
+        try:
+            if alert.channel == AlertChannel.WEBHOOK:
+                return self._deliver_webhook(alert, event)
+            elif alert.channel == AlertChannel.EMAIL:
+                return self._deliver_email(alert, event)
+            elif alert.channel in (AlertChannel.VSCODE_OUTPUT, AlertChannel.STDOUT):
+                return self._deliver_stdout(event)
+            else:
+                logger.warning("unknown_alert_channel", channel=alert.channel.value)
+                return False
+        except Exception as e:
+            logger.error(
+                "alert_delivery_failed",
+                alert_id=alert.alert_id,
+                channel=alert.channel.value,
+                error=str(e),
+            )
+            return False
+
+    def _deliver_webhook(self, alert: AlertConfig, event: AlertEvent) -> bool:
+        """Deliver alert via webhook (Slack, Discord, etc.).
+
+        Security:
+            Validates webhook URL to prevent SSRF attacks before making request.
+            See _validate_webhook_url() for details on blocked targets.
+        """
+        if not alert.webhook_url:
+            return False
+
+        # Validate webhook URL to prevent SSRF (CWE-918)
+        try:
+            validated_url = _validate_webhook_url(alert.webhook_url)
+        except ValueError as e:
+            logger.warning(
+                "invalid_webhook_url",
+                url=alert.webhook_url,
+                error=str(e),
+            )
+            return False
+
+        payload = {
+            "text": event.message,
+            "blocks": [
+                {
+                    "type": "header",
+                    "text": {
+                        "type": "plain_text",
+                        "text": f"🚨 {event.alert_name}",
+                    },
+                },
+                {
+                    "type": "section",
+                    "fields": [
+                        {
+                            "type": "mrkdwn",
+                            "text": f"*Metric:*\n{event.metric.value}",
+                        },
+                        {
+                            "type": "mrkdwn",
+                            "text": f"*Severity:*\n{event.severity.value}",
+                        },
+                        {
+                            "type": "mrkdwn",
+                            "text": f"*Current Value:*\n{event.current_value:.2f}",
+                        },
+                        {
+                            "type": "mrkdwn",
+                            "text": f"*Threshold:*\n{event.threshold:.2f}",
+                        },
+                    ],
+                },
+            ],
+        }
+
+        data = json.dumps(payload).encode("utf-8")
+        req = urllib.request.Request(
+            validated_url,
+            data=data,
+            headers={"Content-Type": "application/json"},
+        )
+
+        try:
+            with urllib.request.urlopen(req, timeout=10) as response:
+                if response.status == 200:
+                    logger.info("webhook_delivered", url=validated_url)
+                    return True
+                else:
+                    logger.warning(
+                        "webhook_unexpected_status",
+                        url=validated_url,
+                        status=response.status,
+                    )
+                    return False
+        except urllib.error.HTTPError as e:
+            logger.warning(
+                "webhook_http_error",
+                url=validated_url,
+                status=e.code,
+                error=str(e),
+            )
+            return False
+        except urllib.error.URLError as e:
+            logger.error("webhook_delivery_failed", url=validated_url, error=str(e))
+            return False
+
+    def _deliver_email(self, alert: AlertConfig, event: AlertEvent) -> bool:
+        """Deliver alert via email.
+
+        Requires SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD environment variables.
+        """
+        if not alert.email:
+            return False
+
+        import os
+
+        smtp_host = os.environ.get("SMTP_HOST", "localhost")
+        smtp_port = int(os.environ.get("SMTP_PORT", "587"))
+        smtp_user = os.environ.get("SMTP_USER", "")
+        smtp_password = os.environ.get("SMTP_PASSWORD", "")
+        from_email = os.environ.get("SMTP_FROM", "alerts@empathy-framework.local")
+
+        msg = MIMEMultipart()
+        msg["From"] = from_email
+        msg["To"] = alert.email
+        msg["Subject"] = f"[{event.severity.value.upper()}] {event.alert_name}"
+
+        body = f"""
+Empathy Framework Alert
+
+Alert: {event.alert_name}
+Metric: {event.metric.value}
+Current Value: {event.current_value:.2f}
+Threshold: {event.threshold:.2f}
+Severity: {event.severity.value}
+Triggered: {event.triggered_at.isoformat()}
+
+--
+Empathy Framework Monitoring
+"""
+        msg.attach(MIMEText(body, "plain"))
+
+        try:
+            with smtplib.SMTP(smtp_host, smtp_port) as server:
+                if smtp_user and smtp_password:
+                    server.starttls()
+                    server.login(smtp_user, smtp_password)
+                server.sendmail(from_email, alert.email, msg.as_string())
+            return True
+        except (smtplib.SMTPException, OSError) as e:
+            logger.error("email_delivery_failed", email=alert.email, error=str(e))
+            return False
+
+    def _deliver_stdout(self, event: AlertEvent) -> bool:
+        """Deliver alert to stdout/console."""
+        print(f"\n{'='*60}")
+        print(event.message)
+        print(f"{'='*60}\n")
+        return True
+
+    def _record_alert_history(self, event: AlertEvent, delivered: bool) -> None:
+        """Record alert event in history table."""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        cursor.execute(
+            """
+            INSERT INTO alert_history
+            (alert_id, metric, current_value, threshold, severity, delivered)
+            VALUES (?, ?, ?, ?, ?, ?)
+        """,
+            (
+                event.alert_id,
+                event.metric.value,
+                event.current_value,
+                event.threshold,
+                event.severity.value,
+                int(delivered),
+            ),
+        )
+
+        conn.commit()
+        conn.close()
+
+    def get_alert_history(
+        self, alert_id: str | None = None, limit: int = 100
+    ) -> list[dict[str, Any]]:
+        """Get alert history.
+
+        Args:
+            alert_id: Filter by alert ID (optional)
+            limit: Maximum number of records to return
+
+        Returns:
+            List of alert history records
+        """
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        if alert_id:
+            cursor.execute(
+                """
+                SELECT alert_id, metric, current_value, threshold, severity,
+                       triggered_at, delivered, delivery_error
+                FROM alert_history
+                WHERE alert_id = ?
+                ORDER BY triggered_at DESC
+                LIMIT ?
+            """,
+                (alert_id, limit),
+            )
+        else:
+            cursor.execute(
+                """
+                SELECT alert_id, metric, current_value, threshold, severity,
+                       triggered_at, delivered, delivery_error
+                FROM alert_history
+                ORDER BY triggered_at DESC
+                LIMIT ?
+            """,
+                (limit,),
+            )
+
+        rows = cursor.fetchall()
+        conn.close()
+
+        return [
+            {
+                "alert_id": row[0],
+                "metric": row[1],
+                "current_value": row[2],
+                "threshold": row[3],
+                "severity": row[4],
+                "triggered_at": row[5],
+                "delivered": bool(row[6]),
+                "delivery_error": row[7],
+            }
+            for row in rows
+        ]
+
+
+def get_alert_engine(
+    db_path: str | Path = ".empathy/alerts.db",
+) -> AlertEngine:
+    """Get an AlertEngine instance.
+
+    Args:
+        db_path: Path to SQLite database
+
+    Returns:
+        Configured AlertEngine instance
+    """
+    return AlertEngine(db_path=db_path)