phlo-alerting 0.1.0__tar.gz

phlo_alerting-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: phlo-alerting
+Version: 0.1.0
+Summary: Alerting destinations and hooks for Phlo
+Author-email: Phlo Team <team@phlo.dev>
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/plain
+Requires-Dist: phlo>=0.1.0
+Requires-Dist: click>=8.3.0
+Requires-Dist: rich>=14.2.0
+Requires-Dist: requests>=2.32.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+Alerting support for Phlo.

phlo_alerting-0.1.0/README.md

@@ -0,0 +1,73 @@
+# phlo-alerting
+
+Alert routing and notification plugin for Phlo.
+
+## Description
+
+Routes alerts from quality check failures, telemetry events, and pipeline errors to configured destinations (Slack, PagerDuty, Email).
+
+## Installation
+
+```bash
+pip install phlo-alerting
+# or
+phlo plugin install alerting
+```
+
+## Configuration
+
+| Variable                         | Default | Description                             |
+| -------------------------------- | ------- | --------------------------------------- |
+| `PHLO_ALERT_SLACK_WEBHOOK`       | -       | Slack incoming webhook URL              |
+| `PHLO_ALERT_SLACK_CHANNEL`       | -       | Default Slack channel                   |
+| `PHLO_ALERT_PAGERDUTY_KEY`       | -       | PagerDuty Events API v2 key             |
+| `PHLO_ALERT_EMAIL_SMTP_HOST`     | -       | SMTP server hostname                    |
+| `PHLO_ALERT_EMAIL_SMTP_PORT`     | `587`   | SMTP server port                        |
+| `PHLO_ALERT_EMAIL_SMTP_USER`     | -       | SMTP username                           |
+| `PHLO_ALERT_EMAIL_SMTP_PASSWORD` | -       | SMTP password                           |
+| `PHLO_ALERT_EMAIL_RECIPIENTS`    | `[]`    | Comma-separated list: `a@x.com,b@y.com` |
+
+## Auto-Configuration
+
+This package is **fully auto-configured**:
+
+| Feature               | How It Works                                                    |
+| --------------------- | --------------------------------------------------------------- |
+| **Hook Registration** | Automatically registers as a hook plugin via entry points       |
+| **Event Handling**    | Listens for `quality.result` and `telemetry.*` events           |
+| **Severity Mapping**  | Maps event severities to alert levels (critical, warning, info) |
+
+### Supported Events
+
+- `quality.result` - Receives quality check results and sends alerts on failures
+- `telemetry.*` - Receives telemetry events and forwards to configured destinations
+
+## Usage
+
+### CLI Commands
+
+```bash
+# Send a test alert
+phlo alerts test --destination slack
+
+# List configured destinations
+phlo alerts list-destinations
+```
+
+### Programmatic
+
+```python
+from phlo_alerting.manager import AlertManager
+
+manager = AlertManager()
+manager.send_alert(
+    title="Quality Check Failed",
+    message="Null check failed on table users",
+    severity="critical"
+)
+```
+
+## Entry Points
+
+- `phlo.plugins.cli` - Provides `alerts` CLI command
+- `phlo.plugins.hooks` - Registers `AlertingHookPlugin` for event handling

phlo_alerting-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "phlo-alerting"
+version = "0.1.0"
+description = "Alerting destinations and hooks for Phlo"
+readme = {text = "Alerting support for Phlo.", content-type = "text/plain"}
+requires-python = ">=3.11"
+authors = [
+    {name = "Phlo Team", email = "team@phlo.dev"},
+]
+license = {text = "MIT"}
+dependencies = [
+    "phlo>=0.1.0",
+    "click>=8.3.0",
+    "rich>=14.2.0",
+    "requests>=2.32.5",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.1.0",
+]
+
+[project.entry-points."phlo.plugins.cli"]
+alerts = "phlo_alerting.cli_plugin:AlertingCliPlugin"
+
+[project.entry-points."phlo.plugins.hooks"]
+alerting = "phlo_alerting.hooks_plugin:AlertingHookPlugin"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

phlo_alerting-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

phlo_alerting-0.1.0/src/phlo_alerting/__init__.py

@@ -0,0 +1,18 @@
+"""Alerting integration for Phlo pipelines."""
+
+from phlo_alerting.manager import (
+    Alert,
+    AlertManager,
+    AlertSeverity,
+    get_alert_manager,
+)
+from phlo_alerting.settings import AlertingSettings, get_settings
+
+__all__ = [
+    "AlertManager",
+    "Alert",
+    "AlertSeverity",
+    "AlertingSettings",
+    "get_alert_manager",
+    "get_settings",
+]

phlo_alerting-0.1.0/src/phlo_alerting/cli_alerts.py

@@ -0,0 +1,141 @@
+"""CLI commands for alert management."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from phlo_alerting import AlertSeverity
+from phlo_alerting.manager import get_alert_manager
+
+console = Console()
+
+
+@click.group(name="alerts")
+def alerts_group():
+    """Alert management and configuration."""
+    pass
+
+
+@alerts_group.command(name="test")
+@click.option(
+    "--severity",
+    type=click.Choice(["info", "warning", "error", "critical"]),
+    default="warning",
+    help="Alert severity",
+)
+@click.option(
+    "--destination",
+    type=str,
+    default=None,
+    help="Specific destination to test (default: all)",
+)
+def test_alerts(severity: str, destination: Optional[str]) -> None:
+    """
+    Send a test alert to configured destinations.
+
+    Useful for verifying alert configuration.
+    """
+    from phlo_alerting import Alert
+
+    manager = get_alert_manager()
+
+    if not manager.destinations:
+        console.print(
+            "[red]✗[/red] No alert destinations configured. "
+            "Set PHLO_ALERT_SLACK_WEBHOOK, PHLO_ALERT_PAGERDUTY_KEY, or PHLO_ALERT_EMAIL_* environment variables."
+        )
+        return
+
+    # Create test alert
+    alert = Alert(
+        title="🧪 Phlo Test Alert",
+        message="This is a test alert from the Phlo CLI. If you see this, alerts are working!",
+        severity=AlertSeverity(severity),
+        asset_name="phlo_test",
+        run_id="test_run_123",
+        error_message=None,
+    )
+
+    # Send to specific or all destinations
+    destinations = [destination] if destination else None
+
+    if manager.send(alert, destinations=destinations):
+        console.print(
+            "[green]✓[/green] Test alert sent successfully! "
+            "Check your configured alert destinations."
+        )
+    else:
+        console.print("[red]✗[/red] Failed to send test alert.")
+
+
+@alerts_group.command(name="list")
+def list_destinations() -> None:
+    """List configured alert destinations."""
+    manager = get_alert_manager()
+
+    if not manager.destinations:
+        console.print(
+            "[yellow]⚠[/yellow]  No alert destinations configured.\n"
+            "To enable alerts, set environment variables:"
+        )
+        console.print(
+            """
+  PHLO_ALERT_SLACK_WEBHOOK=https://hooks.slack.com/services/...
+  PHLO_ALERT_SLACK_CHANNEL=#alerts        (optional)
+  PHLO_ALERT_PAGERDUTY_KEY=...
+  PHLO_ALERT_EMAIL_SMTP_HOST=smtp.example.com
+  PHLO_ALERT_EMAIL_SMTP_PORT=587          (optional, default: 587)
+  PHLO_ALERT_EMAIL_SMTP_USER=user@example.com
+  PHLO_ALERT_EMAIL_SMTP_PASSWORD=password
+  PHLO_ALERT_EMAIL_RECIPIENTS=team@example.com,admin@example.com
+        """
+        )
+        return
+
+    table = Table(title="Configured Alert Destinations")
+    table.add_column("Name", style="cyan")
+    table.add_column("Type", style="magenta")
+    table.add_column("Status", style="green")
+
+    for name, destination in manager.destinations.items():
+        dest_type = destination.__class__.__name__
+        status = "✓ Ready"
+
+        table.add_row(name, dest_type, status)
+
+    console.print(table)
+
+
+@alerts_group.command(name="status")
+def check_status() -> None:
+    """Check alert system status."""
+    manager = get_alert_manager()
+
+    console.print("[bold]Alert System Status[/bold]\n")
+
+    # Check destinations
+    console.print(f"Configured Destinations: {len(manager.destinations)}")
+    for name in manager.destinations:
+        console.print(f"  • {name}")
+
+    if not manager.destinations:
+        console.print("  [yellow]None configured[/yellow]")
+
+    # Show statistics
+    console.print(f"\nRecent Alerts Sent: {len(manager._sent_alerts)}")
+    console.print(f"Deduplication Window: {manager._dedup_window_minutes} minutes")
+
+    # Show configuration guidance
+    if len(manager.destinations) == 0:
+        console.print("\n[bold]Next Steps[/bold]")
+        console.print("1. Configure at least one alert destination via environment variables")
+        console.print("2. Run [cyan]phlo alerts test[/cyan] to verify configuration")
+        console.print("3. Alerts will automatically trigger on run failures")
+
+
+if __name__ == "__main__":
+    alerts_group()

phlo_alerting-0.1.0/src/phlo_alerting/cli_plugin.py

@@ -0,0 +1,21 @@
+"""CLI plugin for alerting commands."""
+
+from __future__ import annotations
+
+import click
+
+from phlo.plugins.base import CliCommandPlugin, PluginMetadata
+from phlo_alerting.cli_alerts import alerts_group
+
+
+class AlertingCliPlugin(CliCommandPlugin):
+    @property
+    def metadata(self) -> PluginMetadata:
+        return PluginMetadata(
+            name="alerts",
+            version="0.1.0",
+            description="Alerting CLI commands",
+        )
+
+    def get_cli_commands(self) -> list[click.Command]:
+        return [alerts_group]

phlo_alerting-0.1.0/src/phlo_alerting/destinations/__init__.py

@@ -0,0 +1 @@
+"""Alert destination implementations."""

phlo_alerting-0.1.0/src/phlo_alerting/destinations/email.py

@@ -0,0 +1,166 @@
+"""Email alert destination."""
+
+from __future__ import annotations
+
+import smtplib
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from typing import Optional
+
+from phlo.logging import get_logger
+from phlo_alerting.manager import Alert, AlertDestination, AlertSeverity
+
+logger = get_logger(__name__)
+
+
+class EmailAlertDestination(AlertDestination):
+    """Send alerts via email."""
+
+    def __init__(
+        self,
+        smtp_host: str,
+        smtp_port: int = 587,
+        smtp_user: Optional[str] = None,
+        smtp_password: Optional[str] = None,
+        recipients: Optional[list[str]] = None,
+    ):
+        """
+        Initialize email destination.
+
+        Args:
+            smtp_host: SMTP server hostname
+            smtp_port: SMTP server port (default: 587)
+            smtp_user: SMTP username (optional)
+            smtp_password: SMTP password (optional)
+            recipients: List of email addresses to send to
+        """
+        self.smtp_host = smtp_host
+        self.smtp_port = smtp_port
+        self.smtp_user = smtp_user
+        self.smtp_password = smtp_password
+        self.recipients = recipients or []
+
+    def send(self, alert: Alert) -> bool:
+        """Send alert via email."""
+        if not self.recipients:
+            logger.warning("No email recipients configured")
+            return False
+
+        try:
+            # Build email
+            msg = MIMEMultipart("alternative")
+            msg["Subject"] = f"[{alert.severity.value.upper()}] {alert.title}"
+            msg["From"] = self.smtp_user or "phlo@example.com"
+            msg["To"] = ", ".join(self.recipients)
+
+            # Build plain text and HTML versions
+            text_content = self._build_text(alert)
+            html_content = self._build_html(alert)
+
+            msg.attach(MIMEText(text_content, "plain"))
+            msg.attach(MIMEText(html_content, "html"))
+
+            # Send email
+            with smtplib.SMTP(self.smtp_host, self.smtp_port) as server:
+                server.starttls()
+                if self.smtp_user and self.smtp_password:
+                    server.login(self.smtp_user, self.smtp_password)
+                server.sendmail(msg["From"], self.recipients, msg.as_string())
+
+            return True
+
+        except Exception as e:
+            logger.exception(f"Failed to send email alert: {e}")
+            return False
+
+    def _build_text(self, alert: Alert) -> str:
+        """Build plain text email content."""
+        content = f"""
+Phlo Alert Notification
+=======================
+
+Title: {alert.title}
+Severity: {alert.severity.value.upper()}
+Time: {alert.timestamp.isoformat() if alert.timestamp else "N/A"}
+
+Message:
+{alert.message}
+"""
+
+        if alert.asset_name:
+            content += f"\nAsset: {alert.asset_name}"
+
+        if alert.run_id:
+            content += f"\nRun ID: {alert.run_id}"
+
+        if alert.error_message:
+            content += f"\n\nError Details:\n{alert.error_message}"
+
+        return content
+
+    def _build_html(self, alert: Alert) -> str:
+        """Build HTML email content."""
+        severity_color = {
+            AlertSeverity.INFO: "#36a64f",
+            AlertSeverity.WARNING: "#ff9900",
+            AlertSeverity.ERROR: "#ff3333",
+            AlertSeverity.CRITICAL: "#cc0000",
+        }.get(alert.severity, "#999999")
+
+        html = f"""
+        <html>
+            <body style="font-family: Arial, sans-serif;">
+                <div style="border-left: 4px solid {severity_color}; padding: 15px; background: #f9f9f9; margin: 10px 0;">
+                    <h2 style="margin-top: 0; color: {severity_color};">{alert.title}</h2>
+                    
+                    <table style="width: 100%; margin: 15px 0;">
+                        <tr>
+                            <td style="font-weight: bold; width: 120px;">Severity:</td>
+                            <td style="color: {severity_color}; font-weight: bold;">{alert.severity.value.upper()}</td>
+                        </tr>
+                        <tr>
+                            <td style="font-weight: bold;">Time:</td>
+                            <td>{alert.timestamp.isoformat() if alert.timestamp else "N/A"}</td>
+                        </tr>
+        """
+
+        if alert.asset_name:
+            html += f"""
+                        <tr>
+                            <td style="font-weight: bold;">Asset:</td>
+                            <td>{alert.asset_name}</td>
+                        </tr>
+            """
+
+        if alert.run_id:
+            html += f"""
+                        <tr>
+                            <td style="font-weight: bold;">Run ID:</td>
+                            <td><code>{alert.run_id}</code></td>
+                        </tr>
+            """
+
+        html += """
+                    </table>
+                    
+                    <div style="margin: 15px 0;">
+                        <h3>Message</h3>
+                        <p>{}</p>
+                    </div>
+        """.format(alert.message)
+
+        if alert.error_message:
+            html += f"""
+                    <div style="background: #f0f0f0; padding: 10px; border-radius: 3px; margin: 15px 0;">
+                        <h3>Error Details</h3>
+                        <pre style="margin: 0; font-size: 12px;">{alert.error_message}</pre>
+                    </div>
+            """
+
+        html += """
+                </div>
+            </body>
+        </html>
+        """
+
+        return html

phlo_alerting-0.1.0/src/phlo_alerting/destinations/pagerduty.py

@@ -0,0 +1,80 @@
+"""PagerDuty alert destination."""
+
+from __future__ import annotations
+
+import requests
+
+from phlo.logging import get_logger
+from phlo_alerting.manager import Alert, AlertDestination, AlertSeverity
+
+logger = get_logger(__name__)
+
+
+class PagerDutyAlertDestination(AlertDestination):
+    """Send alerts to PagerDuty via Events API."""
+
+    def __init__(self, integration_key: str):
+        """
+        Initialize PagerDuty destination.
+
+        Args:
+            integration_key: PagerDuty Events API v2 integration key
+        """
+        self.integration_key = integration_key
+        self.api_url = "https://events.pagerduty.com/v2/enqueue"
+
+    def send(self, alert: Alert) -> bool:
+        """Send alert to PagerDuty."""
+        try:
+            payload = self._build_payload(alert)
+            response = requests.post(self.api_url, json=payload, timeout=10)
+            return response.status_code == 202  # Accepted
+        except Exception as e:
+            logger.exception(f"Failed to send PagerDuty alert: {e}")
+            return False
+
+    def _build_payload(self, alert: Alert) -> dict:
+        """Build PagerDuty event payload."""
+        # Map severity to PagerDuty severity
+        severity_map = {
+            AlertSeverity.INFO: "info",
+            AlertSeverity.WARNING: "warning",
+            AlertSeverity.ERROR: "error",
+            AlertSeverity.CRITICAL: "critical",
+        }
+
+        pd_severity = severity_map.get(alert.severity, "error")
+
+        # Build custom details
+        custom_details = {
+            "severity": alert.severity.value,
+            "message": alert.message,
+            "timestamp": alert.timestamp.isoformat() if alert.timestamp else None,
+        }
+
+        if alert.asset_name:
+            custom_details["asset"] = alert.asset_name
+
+        if alert.run_id:
+            custom_details["run_id"] = alert.run_id
+
+        if alert.error_message:
+            custom_details["error"] = alert.error_message
+
+        # Generate dedup key for alert grouping
+        dedup_key = f"phlo-{alert.asset_name or 'unknown'}-{alert.run_id or 'unknown'}"
+
+        payload = {
+            "routing_key": self.integration_key,
+            "event_action": "trigger",
+            "dedup_key": dedup_key,
+            "payload": {
+                "summary": alert.title,
+                "severity": pd_severity,
+                "source": "Phlo",
+                "timestamp": alert.timestamp.isoformat() if alert.timestamp else None,
+                "custom_details": custom_details,
+            },
+        }
+
+        return payload

phlo_alerting-0.1.0/src/phlo_alerting/destinations/slack.py

@@ -0,0 +1,107 @@
+"""Slack alert destination."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import requests
+
+from phlo.logging import get_logger
+from phlo_alerting.manager import Alert, AlertDestination, AlertSeverity
+
+logger = get_logger(__name__)
+
+
+class SlackAlertDestination(AlertDestination):
+    """Send alerts to Slack via webhook."""
+
+    def __init__(self, webhook_url: str, channel: Optional[str] = None):
+        """
+        Initialize Slack destination.
+
+        Args:
+            webhook_url: Slack incoming webhook URL
+            channel: Optional channel to override (e.g., #alerts)
+        """
+        self.webhook_url = webhook_url
+        self.channel = channel
+
+    def send(self, alert: Alert) -> bool:
+        """Send alert to Slack."""
+        try:
+            payload = self._build_payload(alert)
+            response = requests.post(self.webhook_url, json=payload, timeout=10)
+            return response.status_code == 200
+        except Exception as e:
+            logger.exception(f"Failed to send Slack alert: {e}")
+            return False
+
+    def _build_payload(self, alert: Alert) -> dict:
+        """Build Slack message payload."""
+        # Color based on severity
+        severity_colors = {
+            AlertSeverity.INFO: "#36a64f",  # Green
+            AlertSeverity.WARNING: "#ff9900",  # Orange
+            AlertSeverity.ERROR: "#ff3333",  # Red
+            AlertSeverity.CRITICAL: "#cc0000",  # Dark red
+        }
+
+        color = severity_colors.get(alert.severity, "#999999")
+
+        # Build message blocks
+        fields: list[dict[str, object]] = [
+            {
+                "title": "Severity",
+                "value": alert.severity.value.upper(),
+                "short": True,
+            },
+            {
+                "title": "Time",
+                "value": alert.timestamp.isoformat() if alert.timestamp else "N/A",
+                "short": True,
+            },
+        ]
+
+        if alert.asset_name:
+            fields.append(
+                {
+                    "title": "Asset",
+                    "value": alert.asset_name,
+                    "short": True,
+                }
+            )
+
+        if alert.run_id:
+            fields.append(
+                {
+                    "title": "Run ID",
+                    "value": alert.run_id[:8],
+                    "short": True,
+                }
+            )
+
+        if alert.error_message:
+            fields.append(
+                {
+                    "title": "Error",
+                    "value": f"```{alert.error_message[:500]}```",
+                    "short": False,
+                }
+            )
+
+        # Build attachment
+        attachment: dict[str, object] = {
+            "color": color,
+            "title": alert.title,
+            "text": alert.message,
+            "fields": fields,
+        }
+
+        payload = {
+            "attachments": [attachment],
+        }
+
+        if self.channel:
+            payload["channel"] = self.channel
+
+        return payload

phlo_alerting-0.1.0/src/phlo_alerting/hooks_plugin.py

@@ -0,0 +1,111 @@
+"""Hook plugin for alerting on quality and telemetry events."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from phlo.hooks import QualityResultEvent, TelemetryEvent
+from phlo.plugins.base import PluginMetadata
+from phlo.plugins.hooks import HookFilter, HookPlugin, HookRegistration
+
+from phlo_alerting.manager import Alert, AlertSeverity, get_alert_manager
+
+
+class AlertingHookPlugin(HookPlugin):
+    """Emit alerts based on quality and telemetry events."""
+
+    @property
+    def metadata(self) -> PluginMetadata:
+        """Metadata for the alerting hook plugin."""
+
+        return PluginMetadata(
+            name="alerting",
+            version="0.1.0",
+            description="Alerting hooks for quality and telemetry events",
+        )
+
+    def get_hooks(self) -> list[HookRegistration]:
+        """Register quality and telemetry hook handlers."""
+
+        return [
+            HookRegistration(
+                hook_name="alerting_quality",
+                handler=self._handle_quality,
+                filters=HookFilter(event_types={"quality.result"}),
+            ),
+            HookRegistration(
+                hook_name="alerting_telemetry",
+                handler=self._handle_telemetry,
+                filters=HookFilter(event_types={"telemetry.log", "telemetry.metric"}),
+            ),
+        ]
+
+    def _handle_quality(self, event: Any) -> None:
+        """Send an alert for failed quality checks."""
+
+        if not isinstance(event, QualityResultEvent):
+            return
+        if event.passed:
+            return
+        severity = _map_quality_severity(event.severity)
+        message = _format_quality_message(event)
+        alert = Alert(
+            title=f"Quality check failed: {event.check_name}",
+            message=message,
+            severity=severity,
+            asset_name=event.asset_key,
+        )
+        get_alert_manager().send(alert)
+
+    def _handle_telemetry(self, event: Any) -> None:
+        """Send an alert for error-level telemetry events."""
+
+        if not isinstance(event, TelemetryEvent):
+            return
+        if not event.level or event.level.lower() not in {"error", "critical"}:
+            return
+        alert = Alert(
+            title=f"Telemetry {event.level} event: {event.name}",
+            message=str(event.payload or event.value or ""),
+            severity=_map_telemetry_severity(event.level),
+            asset_name=event.tags.get("asset"),
+        )
+        get_alert_manager().send(alert)
+
+
+def _map_quality_severity(severity: str | None) -> AlertSeverity:
+    """Map quality severity strings to alert severities."""
+
+    if not severity:
+        return AlertSeverity.ERROR
+    value = severity.upper()
+    if value == "WARN":
+        return AlertSeverity.WARNING
+    if value in {"CRITICAL", "FATAL"}:
+        return AlertSeverity.CRITICAL
+    return AlertSeverity.ERROR
+
+
+def _map_telemetry_severity(level: str) -> AlertSeverity:
+    """Map telemetry levels to alert severities."""
+
+    value = level.lower()
+    if value == "critical":
+        return AlertSeverity.CRITICAL
+    return AlertSeverity.ERROR
+
+
+def _format_quality_message(event: QualityResultEvent) -> str:
+    """Format a human-readable quality failure message."""
+
+    parts = [
+        f"Asset: {event.asset_key}",
+        f"Check: {event.check_name}",
+    ]
+    if event.partition_key:
+        parts.append(f"Partition: {event.partition_key}")
+    if event.metadata.get("error"):
+        parts.append(f"Error: {event.metadata['error']}")
+    if event.metadata.get("failure_message"):
+        parts.append(f"Details: {event.metadata['failure_message']}")
+    return "\n".join(parts)

phlo_alerting-0.1.0/src/phlo_alerting/manager.py

@@ -0,0 +1,181 @@
+"""Alert manager for sending notifications to multiple destinations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Optional
+
+from phlo.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class AlertSeverity(str, Enum):
+    """Alert severity levels."""
+
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+    CRITICAL = "critical"
+
+
+@dataclass(slots=True)
+class Alert:
+    """Alert payload."""
+
+    title: str
+    message: str
+    severity: AlertSeverity = AlertSeverity.ERROR
+    asset_name: Optional[str] = None
+    run_id: Optional[str] = None
+    error_message: Optional[str] = None
+    timestamp: Optional[datetime] = None
+
+    def __post_init__(self) -> None:
+        """Set default timestamp."""
+        if self.timestamp is None:
+            self.timestamp = datetime.now(timezone.utc)
+
+
+class AlertDestination:
+    """Base class for alert destinations."""
+
+    def send(self, alert: Alert) -> bool:
+        """
+        Send an alert.
+
+        Args:
+            alert: Alert to send
+
+        Returns:
+            True if sent successfully, False otherwise
+        """
+        raise NotImplementedError
+
+
+class AlertManager:
+    """Manages alert destinations and deduplication."""
+
+    def __init__(self):
+        """Initialize alert manager."""
+        self.destinations: dict[str, AlertDestination] = {}
+        self._sent_alerts: set[str] = set()  # For deduplication
+        self._dedup_window_minutes = 60
+
+    def register_destination(self, name: str, destination: AlertDestination) -> None:
+        """
+        Register an alert destination.
+
+        Args:
+            name: Name of the destination
+            destination: AlertDestination instance
+        """
+        self.destinations[name] = destination
+        logger.info(f"Registered alert destination: {name}")
+
+    def send(self, alert: Alert, destinations: Optional[list[str]] = None) -> bool:
+        """
+        Send an alert to registered destinations.
+
+        Args:
+            alert: Alert to send
+            destinations: Specific destinations to use (None = all)
+
+        Returns:
+            True if sent to at least one destination successfully
+        """
+        # Check for duplicates
+        alert_key = self._get_alert_key(alert)
+        if self._is_duplicate(alert_key):
+            logger.debug(f"Skipping duplicate alert: {alert_key}")
+            return False
+
+        # Determine which destinations to use
+        targets = destinations or list(self.destinations.keys())
+
+        # Send to each destination
+        sent = False
+        for dest_name in targets:
+            if dest_name not in self.destinations:
+                logger.warning(f"Unknown destination: {dest_name}")
+                continue
+
+            try:
+                dest = self.destinations[dest_name]
+                if dest.send(alert):
+                    sent = True
+                    logger.info(f"Sent alert to {dest_name}: {alert.title}")
+            except Exception as e:
+                logger.exception(f"Failed to send alert to {dest_name}: {e}")
+
+        # Mark as sent
+        if sent:
+            self._sent_alerts.add(alert_key)
+
+        return sent
+
+    def _get_alert_key(self, alert: Alert) -> str:
+        """Generate deduplication key for an alert."""
+        return f"{alert.asset_name}:{alert.error_message}:{alert.severity.value}"
+
+    def _is_duplicate(self, key: str) -> bool:
+        """Check if alert is a duplicate."""
+        return key in self._sent_alerts
+
+
+# Global alert manager instance
+_alert_manager: Optional[AlertManager] = None
+
+
+def get_alert_manager() -> AlertManager:
+    """Get or create global alert manager."""
+    global _alert_manager
+    if _alert_manager is None:
+        _alert_manager = AlertManager()
+        _register_default_destinations(_alert_manager)
+    return _alert_manager
+
+
+def _register_default_destinations(manager: AlertManager) -> None:
+    """Register default alert destinations from config."""
+    from phlo_alerting.destinations.email import EmailAlertDestination
+    from phlo_alerting.destinations.pagerduty import PagerDutyAlertDestination
+    from phlo_alerting.destinations.slack import SlackAlertDestination
+    from phlo_alerting.settings import get_settings
+
+    config = get_settings()
+
+    # Register Slack if configured
+    if config.phlo_alert_slack_webhook:
+        try:
+            slack = SlackAlertDestination(
+                webhook_url=config.phlo_alert_slack_webhook,
+                channel=config.phlo_alert_slack_channel,
+            )
+            manager.register_destination("slack", slack)
+        except Exception as e:
+            logger.warning(f"Failed to register Slack destination: {e}")
+
+    # Register PagerDuty if configured
+    if config.phlo_alert_pagerduty_key:
+        try:
+            pagerduty = PagerDutyAlertDestination(integration_key=config.phlo_alert_pagerduty_key)
+            manager.register_destination("pagerduty", pagerduty)
+        except Exception as e:
+            logger.warning(f"Failed to register PagerDuty destination: {e}")
+
+    # Register Email if configured
+    if config.phlo_alert_email_smtp_host:
+        try:
+            email = EmailAlertDestination(
+                smtp_host=config.phlo_alert_email_smtp_host,
+                smtp_port=config.phlo_alert_email_smtp_port,
+                smtp_user=config.phlo_alert_email_smtp_user,
+                smtp_password=config.phlo_alert_email_smtp_password,
+                recipients=config.phlo_alert_email_recipients,
+            )
+            manager.register_destination("email", email)
+        except Exception as e:
+            logger.warning(f"Failed to register Email destination: {e}")

phlo_alerting-0.1.0/src/phlo_alerting/settings.py

@@ -0,0 +1,35 @@
+"""Alerting settings."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pydantic import Field
+
+from phlo.config.base import BaseConfig
+
+
+class AlertingSettings(BaseConfig):
+    """Alert integration configuration (Slack, PagerDuty, Email)."""
+
+    phlo_alert_slack_webhook: str | None = Field(
+        default=None, description="Slack incoming webhook URL"
+    )
+    phlo_alert_slack_channel: str | None = Field(
+        default=None, description="Default Slack channel for alerts"
+    )
+    phlo_alert_pagerduty_key: str | None = Field(
+        default=None, description="PagerDuty Events API v2 integration key"
+    )
+    phlo_alert_email_smtp_host: str | None = Field(default=None, description="SMTP server hostname")
+    phlo_alert_email_smtp_port: int = Field(default=587, description="SMTP server port")
+    phlo_alert_email_smtp_user: str | None = Field(default=None, description="SMTP username")
+    phlo_alert_email_smtp_password: str | None = Field(default=None, description="SMTP password")
+    phlo_alert_email_recipients: list[str] = Field(
+        default_factory=list, description="Email recipients for alerts"
+    )
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> AlertingSettings:
+    return AlertingSettings()

phlo_alerting-0.1.0/src/phlo_alerting.egg-info/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: phlo-alerting
+Version: 0.1.0
+Summary: Alerting destinations and hooks for Phlo
+Author-email: Phlo Team <team@phlo.dev>
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/plain
+Requires-Dist: phlo>=0.1.0
+Requires-Dist: click>=8.3.0
+Requires-Dist: rich>=14.2.0
+Requires-Dist: requests>=2.32.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+Alerting support for Phlo.

phlo_alerting-0.1.0/src/phlo_alerting.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+README.md
+pyproject.toml
+src/phlo_alerting/__init__.py
+src/phlo_alerting/cli_alerts.py
+src/phlo_alerting/cli_plugin.py
+src/phlo_alerting/hooks_plugin.py
+src/phlo_alerting/manager.py
+src/phlo_alerting/settings.py
+src/phlo_alerting.egg-info/PKG-INFO
+src/phlo_alerting.egg-info/SOURCES.txt
+src/phlo_alerting.egg-info/dependency_links.txt
+src/phlo_alerting.egg-info/entry_points.txt
+src/phlo_alerting.egg-info/requires.txt
+src/phlo_alerting.egg-info/top_level.txt
+src/phlo_alerting/destinations/__init__.py
+src/phlo_alerting/destinations/email.py
+src/phlo_alerting/destinations/pagerduty.py
+src/phlo_alerting/destinations/slack.py
+tests/test_alerting.py
+tests/test_integration_alerting.py

phlo_alerting-0.1.0/src/phlo_alerting.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

phlo_alerting-0.1.0/src/phlo_alerting.egg-info/entry_points.txt

@@ -0,0 +1,5 @@
+[phlo.plugins.cli]
+alerts = phlo_alerting.cli_plugin:AlertingCliPlugin
+
+[phlo.plugins.hooks]
+alerting = phlo_alerting.hooks_plugin:AlertingHookPlugin

phlo_alerting-0.1.0/src/phlo_alerting.egg-info/requires.txt

@@ -0,0 +1,8 @@
+phlo>=0.1.0
+click>=8.3.0
+rich>=14.2.0
+requests>=2.32.5
+
+[dev]
+pytest>=7.0
+ruff>=0.1.0

phlo_alerting-0.1.0/src/phlo_alerting.egg-info/top_level.txt

@@ -0,0 +1 @@
+phlo_alerting

phlo_alerting-0.1.0/tests/test_alerting.py

@@ -0,0 +1,92 @@
+"""Unit tests for phlo-alerting."""
+
+from phlo_alerting.manager import Alert, AlertManager, AlertDestination, AlertSeverity
+from phlo_alerting.hooks_plugin import (
+    AlertingHookPlugin,
+    _map_quality_severity,
+    _map_telemetry_severity,
+)
+from phlo_alerting.settings import AlertingSettings
+
+
+class MockDestination(AlertDestination):
+    def __init__(self):
+        self.alerts: list[Alert] = []
+
+    def send(self, alert: Alert) -> bool:
+        self.alerts.append(alert)
+        return True
+
+
+def test_alert_defaults():
+    alert = Alert(title="Test", message="hello")
+    assert alert.severity == AlertSeverity.ERROR
+    assert alert.timestamp is not None
+
+
+def test_alert_severity_values():
+    assert AlertSeverity.INFO.value == "info"
+    assert AlertSeverity.CRITICAL.value == "critical"
+
+
+def test_alert_manager_register_and_send():
+    manager = AlertManager()
+    dest = MockDestination()
+    manager.register_destination("mock", dest)
+
+    alert = Alert(title="T", message="M", asset_name="a1", error_message="e1")
+    assert manager.send(alert) is True
+    assert len(dest.alerts) == 1
+
+
+def test_alert_manager_deduplication():
+    manager = AlertManager()
+    dest = MockDestination()
+    manager.register_destination("mock", dest)
+
+    alert = Alert(title="T", message="M", asset_name="a1", error_message="e1")
+    manager.send(alert)
+    assert manager.send(alert) is False
+    assert len(dest.alerts) == 1
+
+
+def test_alert_manager_targeted_destinations():
+    manager = AlertManager()
+    d1 = MockDestination()
+    d2 = MockDestination()
+    manager.register_destination("d1", d1)
+    manager.register_destination("d2", d2)
+
+    alert = Alert(title="T", message="M")
+    manager.send(alert, destinations=["d1"])
+    assert len(d1.alerts) == 1
+    assert len(d2.alerts) == 0
+
+
+def test_map_quality_severity():
+    assert _map_quality_severity(None) == AlertSeverity.ERROR
+    assert _map_quality_severity("WARN") == AlertSeverity.WARNING
+    assert _map_quality_severity("CRITICAL") == AlertSeverity.CRITICAL
+    assert _map_quality_severity("FATAL") == AlertSeverity.CRITICAL
+    assert _map_quality_severity("error") == AlertSeverity.ERROR
+
+
+def test_map_telemetry_severity():
+    assert _map_telemetry_severity("critical") == AlertSeverity.CRITICAL
+    assert _map_telemetry_severity("error") == AlertSeverity.ERROR
+
+
+def test_alerting_hooks_plugin_registrations():
+    plugin = AlertingHookPlugin()
+    hooks = plugin.get_hooks()
+    assert len(hooks) == 2
+    names = {h.hook_name for h in hooks}
+    assert "alerting_quality" in names
+    assert "alerting_telemetry" in names
+
+
+def test_alerting_settings_defaults():
+    settings = AlertingSettings()
+    assert settings.phlo_alert_email_smtp_port == 587
+    assert settings.phlo_alert_email_recipients == []
+    assert settings.phlo_alert_slack_webhook is None

phlo_alerting-0.1.0/tests/test_integration_alerting.py

@@ -0,0 +1,167 @@
+"""Integration tests for phlo-alerting."""
+
+import pytest
+
+pytestmark = pytest.mark.integration
+
+
+def test_alert_manager_initializes():
+    """Test that AlertManager initializes correctly."""
+    from phlo_alerting import AlertManager, get_alert_manager
+
+    manager = get_alert_manager()
+    assert isinstance(manager, AlertManager)
+
+
+def test_alert_payload_defaults():
+    """Test that Alert has correct default values."""
+    from phlo_alerting import Alert, AlertSeverity
+
+    alert = Alert(title="Test", message="hello")
+    assert alert.severity == AlertSeverity.ERROR
+    assert alert.timestamp is not None
+
+
+def test_alert_severity_enum():
+    """Test AlertSeverity enum values."""
+    from phlo_alerting import AlertSeverity
+
+    assert AlertSeverity.INFO.value == "info"
+    assert AlertSeverity.WARNING.value == "warning"
+    assert AlertSeverity.ERROR.value == "error"
+    assert AlertSeverity.CRITICAL.value == "critical"
+
+
+def test_alert_destination_registration():
+    """Test custom destination registration."""
+    from phlo_alerting.manager import AlertManager, AlertDestination, Alert
+
+    class MockDestination(AlertDestination):
+        def __init__(self):
+            self.alerts = []
+
+        def send(self, alert: Alert) -> bool:
+            self.alerts.append(alert)
+            return True
+
+    manager = AlertManager()
+    mock_dest = MockDestination()
+    manager.register_destination("mock", mock_dest)
+
+    assert "mock" in manager.destinations
+    assert manager.destinations["mock"] is mock_dest
+
+
+def test_alert_sending_to_destination():
+    """Test sending alerts to registered destinations."""
+    from phlo_alerting.manager import AlertManager, AlertDestination, Alert, AlertSeverity
+
+    class MockDestination(AlertDestination):
+        def __init__(self):
+            self.alerts = []
+
+        def send(self, alert: Alert) -> bool:
+            self.alerts.append(alert)
+            return True
+
+    manager = AlertManager()
+    mock_dest = MockDestination()
+    manager.register_destination("mock", mock_dest)
+
+    alert = Alert(
+        title="Test Alert",
+        message="This is a test",
+        severity=AlertSeverity.WARNING,
+        asset_name="test_asset",
+    )
+
+    result = manager.send(alert)
+
+    assert result is True
+    assert len(mock_dest.alerts) == 1
+    assert mock_dest.alerts[0].title == "Test Alert"
+
+
+def test_alert_deduplication():
+    """Test that duplicate alerts are not sent."""
+    from phlo_alerting.manager import AlertManager, AlertDestination, Alert, AlertSeverity
+
+    class MockDestination(AlertDestination):
+        def __init__(self):
+            self.alerts = []
+
+        def send(self, alert: Alert) -> bool:
+            self.alerts.append(alert)
+            return True
+
+    manager = AlertManager()
+    mock_dest = MockDestination()
+    manager.register_destination("mock", mock_dest)
+
+    alert = Alert(
+        title="Duplicate Test",
+        message="Same alert",
+        severity=AlertSeverity.ERROR,
+        asset_name="dup_asset",
+        error_message="same error",
+    )
+
+    # First send should succeed
+    result1 = manager.send(alert)
+    assert result1 is True
+    assert len(mock_dest.alerts) == 1
+
+    # Second send (duplicate) should be skipped
+    result2 = manager.send(alert)
+    assert result2 is False
+    assert len(mock_dest.alerts) == 1  # Still only 1
+
+
+def test_alert_to_specific_destination():
+    """Test sending to specific destinations only."""
+    from phlo_alerting.manager import AlertManager, AlertDestination, Alert
+
+    class MockDestination(AlertDestination):
+        def __init__(self, name):
+            self.name = name
+            self.alerts = []
+
+        def send(self, alert: Alert) -> bool:
+            self.alerts.append(alert)
+            return True
+
+    manager = AlertManager()
+    dest1 = MockDestination("dest1")
+    dest2 = MockDestination("dest2")
+    manager.register_destination("dest1", dest1)
+    manager.register_destination("dest2", dest2)
+
+    alert = Alert(title="Specific Test", message="Only to dest1")
+
+    # Send only to dest1
+    result = manager.send(alert, destinations=["dest1"])
+
+    assert result is True
+    assert len(dest1.alerts) == 1
+    assert len(dest2.alerts) == 0
+
+
+def test_alerting_hooks_plugin_exists():
+    """Test that hooks plugin is properly defined."""
+    from phlo_alerting.hooks_plugin import AlertingHookPlugin
+
+    plugin = AlertingHookPlugin()
+    assert plugin is not None
+    # Check it has required hook method(s)
+    assert hasattr(plugin, "get_hooks")
+    assert hasattr(plugin, "metadata")
+
+
+def test_alerting_exports():
+    """Test that phlo-alerting exports required classes."""
+    import phlo_alerting
+
+    assert hasattr(phlo_alerting, "Alert")
+    assert hasattr(phlo_alerting, "AlertManager")
+    assert hasattr(phlo_alerting, "AlertSeverity")
+    assert hasattr(phlo_alerting, "get_alert_manager")