empathy-framework 2.4.0__py3-none-any.whl → 3.8.2__py3-none-any.whl

empathy_os/monitoring/alerts.py

@@ -0,0 +1,23 @@
+"""Alert System for LLM Telemetry Monitoring
+
+Provides threshold-based alerting for LLM usage metrics.
+
+**Features:**
+- Interactive CLI wizard (`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)
+
+Copyright 2025 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

empathy_os/monitoring/alerts_cli.py

@@ -0,0 +1,268 @@
+"""Alert CLI Wizard
+
+Interactive wizard for setting up LLM telemetry alerts.
+
+**Usage:**
+    empathy alerts init
+    empathy alerts list
+    empathy alerts delete <id>
+    empathy alerts watch [--daemon]
+
+**Implementation:** Sprint 3 (Week 3)
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+import click
+
+
+class AlertEngine:
+    """Alert engine with SQLite storage"""
+
+    def __init__(self, db_path: str = ".empathy/alerts.db"):
+        self.db_path = Path(db_path)
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._init_db()
+
+    def _init_db(self) -> None:
+        """Initialize SQLite database"""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        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,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+        """
+        )
+
+        conn.commit()
+        conn.close()
+
+    def add_alert(
+        self,
+        alert_id: str,
+        name: str,
+        metric: str,
+        threshold: float,
+        channel: str,
+        webhook_url: str | None = None,
+        email: str | None = None,
+    ) -> None:
+        """Add a new alert"""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        cursor.execute(
+            """
+            INSERT INTO alerts (id, name, metric, threshold, channel, webhook_url, email)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+        """,
+            (alert_id, name, metric, threshold, channel, webhook_url, email),
+        )
+
+        conn.commit()
+        conn.close()
+
+    def list_alerts(self) -> list[dict[str, Any]]:
+        """List all alerts"""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        cursor.execute("SELECT * FROM alerts")
+        rows = cursor.fetchall()
+
+        conn.close()
+
+        alerts = []
+        for row in rows:
+            alerts.append(
+                {
+                    "id": row[0],
+                    "name": row[1],
+                    "metric": row[2],
+                    "threshold": row[3],
+                    "channel": row[4],
+                    "webhook_url": row[5],
+                    "email": row[6],
+                    "enabled": bool(row[7]),
+                    "cooldown": row[8],
+                    "created_at": row[9],
+                }
+            )
+
+        return alerts
+
+    def delete_alert(self, alert_id: str) -> bool:
+        """Delete an alert by ID"""
+        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()
+
+        return deleted
+
+
+@click.group()
+def alerts():
+    """Alert management commands"""
+    pass
+
+
+@alerts.command()
+def init():
+    """Initialize alert with interactive wizard"""
+    click.echo("🔔 Alert Setup Wizard\n")
+
+    # Question 1: What metric?
+    click.echo("1. What metric do you want to monitor?")
+    click.echo("   a) Daily cost")
+    click.echo("   b) Error rate")
+    click.echo("   c) Latency (avg response time)")
+    click.echo("   d) Token usage")
+
+    metric_choice = click.prompt("Choose (a/b/c/d)", type=click.Choice(["a", "b", "c", "d"]))
+
+    metric_map = {
+        "a": ("daily_cost", "Daily Cost"),
+        "b": ("error_rate", "Error Rate"),
+        "c": ("avg_latency", "Average Latency"),
+        "d": ("token_usage", "Token Usage"),
+    }
+
+    metric, metric_name = metric_map[metric_choice]
+
+    # Question 2: What threshold?
+    click.echo(f"\n2. What threshold for {metric_name}?")
+    if metric == "daily_cost":
+        threshold = click.prompt("Daily cost threshold (USD)", type=float, default=10.0)
+    elif metric == "error_rate":
+        threshold = click.prompt("Error rate threshold (%)", type=float, default=10.0)
+    elif metric == "avg_latency":
+        threshold = click.prompt("Latency threshold (ms)", type=int, default=3000)
+    else:  # token_usage
+        threshold = click.prompt("Token usage threshold", type=int, default=100000)
+
+    # Question 3: Where to send?
+    click.echo("\n3. Where should alerts be sent?")
+    click.echo("   a) Webhook (Slack, Discord, etc.)")
+    click.echo("   b) Email")
+    click.echo("   c) VSCode output (console)")
+
+    channel_choice = click.prompt("Choose (a/b/c)", type=click.Choice(["a", "b", "c"]))
+
+    channel_map = {
+        "a": "webhook",
+        "b": "email",
+        "c": "vscode_output",
+    }
+
+    channel = channel_map[channel_choice]
+
+    webhook_url = None
+    email = None
+
+    if channel == "webhook":
+        webhook_url = click.prompt("Webhook URL")
+    elif channel == "email":
+        email = click.prompt("Email address")
+
+    # Create alert
+    engine = AlertEngine()
+    alert_id = f"alert_{metric}_{int(__import__('time').time())}"
+
+    engine.add_alert(
+        alert_id=alert_id,
+        name=f"{metric_name} Alert",
+        metric=metric,
+        threshold=threshold,
+        channel=channel,
+        webhook_url=webhook_url,
+        email=email,
+    )
+
+    click.echo("\n✅ Alert created successfully!")
+    click.echo(f"   ID: {alert_id}")
+    click.echo(f"   Metric: {metric_name}")
+    click.echo(f"   Threshold: {threshold}")
+    click.echo(f"   Channel: {channel}")
+
+    click.echo("\n💡 Tip: Run 'empathy alerts watch' to start monitoring")
+
+
+@alerts.command(name="list")
+def list_cmd():
+    """List all configured alerts"""
+    engine = AlertEngine()
+    alerts_list = engine.list_alerts()
+
+    if not alerts_list:
+        click.echo("No alerts configured. Run 'empathy alerts init' to create one.")
+        return
+
+    click.echo("📋 Configured Alerts:\n")
+
+    for alert in alerts_list:
+        status = "✓ Enabled" if alert["enabled"] else "✗ Disabled"
+        click.echo(f"  [{status}] {alert['name']}")
+        click.echo(f"    ID: {alert['id']}")
+        click.echo(f"    Metric: {alert['metric']} > {alert['threshold']}")
+        click.echo(f"    Channel: {alert['channel']}")
+        click.echo()
+
+
+@alerts.command()
+@click.argument("alert_id")
+def delete(alert_id: str):
+    """Delete an alert by ID"""
+    engine = AlertEngine()
+    deleted = engine.delete_alert(alert_id)
+
+    if deleted:
+        click.echo(f"✅ Alert '{alert_id}' deleted successfully")
+    else:
+        click.echo(f"❌ Alert '{alert_id}' not found")
+
+
+@alerts.command()
+@click.option("--daemon", is_flag=True, help="Run as background daemon (enterprise)")
+def watch(daemon: bool):
+    """Watch telemetry and trigger alerts"""
+    if daemon:
+        click.echo("🔄 Starting alert watcher as daemon...")
+        click.echo("⚠️  Note: Daemon mode is an enterprise feature for 24/7 monitoring")
+        click.echo("   For development, use VSCode extension polling instead.")
+        # TODO: Implement daemon mode
+    else:
+        click.echo("🔄 Starting alert watcher (Ctrl+C to stop)...")
+        click.echo("💡 Tip: Use VSCode extension for automatic monitoring")
+
+        try:
+            while True:
+                # TODO: Check telemetry and trigger alerts
+                __import__("time").sleep(60)
+        except KeyboardInterrupt:
+            click.echo("\n✓ Alert watcher stopped")
+
+
+if __name__ == "__main__":
+    alerts()

empathy_os/monitoring/multi_backend.py

@@ -0,0 +1,271 @@
+"""Multi-Backend Telemetry Support
+
+Enables simultaneous logging to multiple backends (JSONL + OTEL).
+
+**Features:**
+- Composite pattern for multiple backends
+- Parallel writes to all configured backends
+- Graceful handling of backend failures
+- Automatic backend selection based on configuration
+
+**Example:**
+```python
+from empathy_os.monitoring import TelemetryStore
+from empathy_os.monitoring.otel_backend import OTELBackend
+from empathy_os.monitoring.multi_backend import MultiBackend
+
+# Create composite backend
+backends = [
+    TelemetryStore(),           # JSONL (always enabled)
+    OTELBackend(),              # OTEL (if configured)
+]
+multi = MultiBackend(backends)
+
+# Logs to both backends
+multi.log_call(record)
+```
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from typing import Protocol, runtime_checkable
+
+from empathy_os.models.telemetry import LLMCallRecord, TelemetryStore, WorkflowRunRecord
+
+
+@runtime_checkable
+class TelemetryBackend(Protocol):
+    """Protocol for telemetry storage backends.
+
+    All backends must implement log_call() and log_workflow().
+    """
+
+    def log_call(self, record: LLMCallRecord) -> None:
+        """Log an LLM call record."""
+        ...
+
+    def log_workflow(self, record: WorkflowRunRecord) -> None:
+        """Log a workflow run record."""
+        ...
+
+
+class MultiBackend:
+    """Composite backend for simultaneous logging to multiple backends.
+
+    Implements the TelemetryBackend protocol and forwards calls to all
+    configured backends. Handles failures gracefully - if one backend
+    fails, others continue to work.
+
+    **Auto-Configuration:**
+    - JSONL backend is always enabled (default)
+    - OTEL backend is enabled if EMPATHY_OTEL_ENDPOINT is set
+
+    Example:
+        >>> backend = MultiBackend.from_config()
+        >>> backend.log_call(call_record)  # Logs to JSONL + OTEL
+        >>> backend.log_workflow(workflow_record)
+    """
+
+    def __init__(self, backends: list[TelemetryBackend] | None = None):
+        """Initialize multi-backend.
+
+        Args:
+            backends: List of backend instances (default: auto-detect)
+        """
+        self.backends = backends or []
+        self._failed_backends: set[int] = set()
+
+    @classmethod
+    def from_config(cls, storage_dir: str = ".empathy") -> "MultiBackend":
+        """Create multi-backend from configuration.
+
+        Auto-detects available backends:
+        1. JSONL backend (always enabled)
+        2. OTEL backend (if EMPATHY_OTEL_ENDPOINT is set or collector detected)
+
+        Args:
+            storage_dir: Directory for JSONL storage (default: .empathy)
+
+        Returns:
+            MultiBackend instance with all available backends
+        """
+        backends: list[TelemetryBackend] = []
+
+        # Always add JSONL backend
+        try:
+            jsonl_backend = TelemetryStore(storage_dir)
+            backends.append(jsonl_backend)
+        except Exception as e:
+            print(f"⚠️  Failed to initialize JSONL backend: {e}")
+
+        # Add OTEL backend if configured
+        try:
+            from empathy_os.monitoring.otel_backend import OTELBackend
+
+            otel_backend = OTELBackend()
+            if otel_backend.is_available():
+                backends.append(otel_backend)
+        except ImportError:
+            # OTEL dependencies not installed
+            pass
+        except Exception as e:
+            print(f"⚠️  Failed to initialize OTEL backend: {e}")
+
+        return cls(backends)
+
+    def add_backend(self, backend: TelemetryBackend) -> None:
+        """Add a backend to the multi-backend.
+
+        Args:
+            backend: Backend instance to add
+        """
+        if isinstance(backend, TelemetryBackend):
+            self.backends.append(backend)
+        else:
+            raise TypeError(
+                f"Backend must implement TelemetryBackend protocol, got {type(backend)}"
+            )
+
+    def remove_backend(self, backend: TelemetryBackend) -> None:
+        """Remove a backend from the multi-backend.
+
+        Args:
+            backend: Backend instance to remove
+        """
+        if backend in self.backends:
+            self.backends.remove(backend)
+
+    def log_call(self, record: LLMCallRecord) -> None:
+        """Log an LLM call record to all backends.
+
+        Failures in individual backends are logged but don't affect other backends.
+
+        Args:
+            record: LLM call record to log
+        """
+        for i, backend in enumerate(self.backends):
+            if i in self._failed_backends:
+                # Skip backends that have failed before
+                continue
+
+            try:
+                backend.log_call(record)
+            except Exception as e:
+                backend_name = type(backend).__name__
+                print(f"⚠️  Failed to log call to {backend_name}: {e}")
+                # Mark backend as failed to reduce log spam
+                self._failed_backends.add(i)
+
+    def log_workflow(self, record: WorkflowRunRecord) -> None:
+        """Log a workflow run record to all backends.
+
+        Failures in individual backends are logged but don't affect other backends.
+
+        Args:
+            record: Workflow run record to log
+        """
+        for i, backend in enumerate(self.backends):
+            if i in self._failed_backends:
+                # Skip backends that have failed before
+                continue
+
+            try:
+                backend.log_workflow(record)
+            except Exception as e:
+                backend_name = type(backend).__name__
+                print(f"⚠️  Failed to log workflow to {backend_name}: {e}")
+                # Mark backend as failed to reduce log spam
+                self._failed_backends.add(i)
+
+    def get_active_backends(self) -> list[str]:
+        """Get list of active backend names.
+
+        Returns:
+            List of backend class names that are active (not failed)
+        """
+        return [
+            type(backend).__name__
+            for i, backend in enumerate(self.backends)
+            if i not in self._failed_backends
+        ]
+
+    def get_failed_backends(self) -> list[str]:
+        """Get list of failed backend names.
+
+        Returns:
+            List of backend class names that have failed
+        """
+        return [
+            type(self.backends[i]).__name__ for i in self._failed_backends if i < len(self.backends)
+        ]
+
+    def reset_failures(self) -> None:
+        """Reset failed backend tracking.
+
+        Allows retry of previously failed backends.
+        """
+        self._failed_backends.clear()
+
+    def flush(self) -> None:
+        """Flush all backends.
+
+        Calls flush() on backends that support it (e.g., OTEL backend).
+        """
+        for backend in self.backends:
+            if hasattr(backend, "flush"):
+                try:
+                    backend.flush()
+                except Exception as e:
+                    backend_name = type(backend).__name__
+                    print(f"⚠️  Failed to flush {backend_name}: {e}")
+
+    def __len__(self) -> int:
+        """Return number of active backends."""
+        return len(self.backends) - len(self._failed_backends)
+
+    def __repr__(self) -> str:
+        """String representation."""
+        active = self.get_active_backends()
+        failed = self.get_failed_backends()
+        status = f"active={active}"
+        if failed:
+            status += f", failed={failed}"
+        return f"MultiBackend({status})"
+
+
+# Singleton instance for global access
+_global_backend: MultiBackend | None = None
+
+
+def get_multi_backend(storage_dir: str = ".empathy") -> MultiBackend:
+    """Get or create the global multi-backend instance.
+
+    This is the recommended way to get a multi-backend instance.
+    It ensures a single instance is shared across the application.
+
+    Args:
+        storage_dir: Directory for JSONL storage (default: .empathy)
+
+    Returns:
+        Global MultiBackend instance
+
+    Example:
+        >>> backend = get_multi_backend()
+        >>> backend.log_call(record)
+    """
+    global _global_backend
+    if _global_backend is None:
+        _global_backend = MultiBackend.from_config(storage_dir)
+    return _global_backend
+
+
+def reset_multi_backend() -> None:
+    """Reset the global multi-backend instance.
+
+    Useful for testing or reconfiguration.
+    """
+    global _global_backend
+    if _global_backend is not None:
+        _global_backend.flush()
+    _global_backend = None