devloop 0.2.0__py3-none-any.whl

devloop/core/debug_trace.py

@@ -0,0 +1,289 @@
+"""Debug tracing utilities for agent execution flow.
+
+Provides decorators and utilities for tracing agent execution,
+detecting failures, and diagnosing issues.
+"""
+
+import asyncio
+import functools
+import logging
+import time
+from datetime import datetime, UTC
+from typing import Any, Callable, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class ExecutionTrace:
+    """Records execution details for debugging"""
+
+    def __init__(self, name: str, args: tuple = None, kwargs: dict = None):
+        self.name = name
+        self.args = args or ()
+        self.kwargs = kwargs or {}
+        self.start_time: Optional[float] = None
+        self.end_time: Optional[float] = None
+        self.duration: Optional[float] = None
+        self.result: Any = None
+        self.exception: Optional[Exception] = None
+        self.success = False
+
+    @property
+    def is_running(self) -> bool:
+        return self.start_time is not None and self.end_time is None
+
+    @property
+    def is_complete(self) -> bool:
+        return self.end_time is not None
+
+    def start(self):
+        """Mark start of execution"""
+        self.start_time = time.time()
+        logger.debug(f"[TRACE] {self.name} START")
+
+    def end(self, result: Any = None, exception: Exception = None):
+        """Mark end of execution"""
+        self.end_time = time.time()
+        self.duration = (
+            self.end_time - self.start_time if self.start_time is not None else None
+        )
+        self.result = result
+        self.exception = exception
+        self.success = exception is None
+
+        if exception:
+            logger.error(
+                f"[TRACE] {self.name} END (failed after {self.duration:.3f}s): {exception}"
+            )
+        else:
+            logger.debug(f"[TRACE] {self.name} END ({self.duration:.3f}s)")
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert trace to dictionary"""
+        return {
+            "name": self.name,
+            "start_time": self.start_time,
+            "end_time": self.end_time,
+            "duration": self.duration,
+            "success": self.success,
+            "error": str(self.exception) if self.exception else None,
+        }
+
+
+# Global trace history (in-memory for now)
+_trace_history: list[ExecutionTrace] = []
+
+
+def get_trace_history(limit: int = 100) -> list[ExecutionTrace]:
+    """Get recent execution traces"""
+    return _trace_history[-limit:]
+
+
+def clear_trace_history():
+    """Clear trace history"""
+    global _trace_history
+    _trace_history = []
+
+
+def trace_execution(name: str = None):
+    """Decorator for tracing function execution
+
+    Usage:
+        @trace_execution("my_function")
+        async def my_func():
+            pass
+    """
+
+    def decorator(func: Callable) -> Callable:
+        trace_name = name or f"{func.__module__}.{func.__name__}"
+
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            trace = ExecutionTrace(trace_name, args, kwargs)
+            trace.start()
+            _trace_history.append(trace)
+
+            try:
+                result = await func(*args, **kwargs)
+                trace.end(result=result)
+                return result
+            except Exception as e:
+                trace.end(exception=e)
+                raise
+
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            trace = ExecutionTrace(trace_name, args, kwargs)
+            trace.start()
+            _trace_history.append(trace)
+
+            try:
+                result = func(*args, **kwargs)
+                trace.end(result=result)
+                return result
+            except Exception as e:
+                trace.end(exception=e)
+                raise
+
+        # Use appropriate wrapper based on function type
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper
+        else:
+            return sync_wrapper
+
+    return decorator
+
+
+def trace_agent_execution(agent_name: str):
+    """Specialized decorator for agent handle() execution"""
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        async def wrapper(self, event, *args, **kwargs):
+            trace_name = f"agent.{agent_name}.handle"
+            trace = ExecutionTrace(
+                trace_name,
+                (event.type, event.source),
+                {"event_id": event.id},
+            )
+            trace.start()
+            _trace_history.append(trace)
+
+            try:
+                logger.debug(
+                    f"[AGENT] {agent_name} processing event: {event.type} from {event.source}"
+                )
+
+                result = await func(self, event, *args, **kwargs)
+
+                if hasattr(result, "findings") and result.findings:
+                    logger.debug(
+                        f"[AGENT] {agent_name} found {len(result.findings)} issues"
+                    )
+
+                trace.end(result=result)
+                return result
+
+            except Exception as e:
+                logger.error(f"[AGENT] {agent_name} failed: {e}")
+                trace.end(exception=e)
+                raise
+
+        return wrapper
+
+    return decorator
+
+
+def trace_context_store(operation: str):
+    """Trace context store operations"""
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        async def async_wrapper(self, *args, **kwargs):
+            trace_name = f"context_store.{operation}"
+            trace = ExecutionTrace(trace_name)
+            trace.start()
+            _trace_history.append(trace)
+
+            try:
+                logger.debug(f"[CONTEXT] {operation} starting...")
+                result = await func(self, *args, **kwargs)
+                logger.debug(f"[CONTEXT] {operation} completed successfully")
+                trace.end(result=result)
+                return result
+            except Exception as e:
+                logger.error(f"[CONTEXT] {operation} failed: {e}")
+                trace.end(exception=e)
+                raise
+
+        @functools.wraps(func)
+        def sync_wrapper(self, *args, **kwargs):
+            trace_name = f"context_store.{operation}"
+            trace = ExecutionTrace(trace_name)
+            trace.start()
+            _trace_history.append(trace)
+
+            try:
+                logger.debug(f"[CONTEXT] {operation} starting...")
+                result = func(self, *args, **kwargs)
+                logger.debug(f"[CONTEXT] {operation} completed successfully")
+                trace.end(result=result)
+                return result
+            except Exception as e:
+                logger.error(f"[CONTEXT] {operation} failed: {e}")
+                trace.end(exception=e)
+                raise
+
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper
+        else:
+            return sync_wrapper
+
+    return decorator
+
+
+class FailureDetector:
+    """Detects and reports agent failures"""
+
+    def __init__(self, alert_threshold: int = 5):
+        """
+        Initialize failure detector
+
+        Args:
+            alert_threshold: Number of consecutive failures before alerting
+        """
+        self.alert_threshold = alert_threshold
+        self.agent_failures: Dict[str, int] = {}
+        self.agent_last_success: Dict[str, datetime] = {}
+
+    def record_failure(self, agent_name: str):
+        """Record a failure for an agent"""
+        self.agent_failures[agent_name] = self.agent_failures.get(agent_name, 0) + 1
+
+        failure_count = self.agent_failures[agent_name]
+
+        if failure_count >= self.alert_threshold:
+            logger.error(
+                f"[FAILURE] Agent '{agent_name}' failed {failure_count} times. "
+                f"Agent may be broken and needs investigation."
+            )
+
+    def record_success(self, agent_name: str):
+        """Record a successful execution"""
+        self.agent_failures[agent_name] = 0
+        self.agent_last_success[agent_name] = datetime.now(UTC)
+        logger.debug(f"[SUCCESS] Agent '{agent_name}' executed successfully")
+
+    def get_status(self) -> Dict[str, Any]:
+        """Get overall failure status"""
+        failing_agents = {
+            name: count for name, count in self.agent_failures.items() if count > 0
+        }
+
+        return {
+            "failing_agents": failing_agents,
+            "has_failures": len(failing_agents) > 0,
+            "critical_failures": {
+                name: count
+                for name, count in failing_agents.items()
+                if count >= self.alert_threshold
+            },
+        }
+
+
+# Global failure detector
+_failure_detector = FailureDetector()
+
+
+def get_failure_detector() -> FailureDetector:
+    """Get the global failure detector"""
+    return _failure_detector
+
+
+def report_diagnostics() -> Dict[str, Any]:
+    """Generate diagnostic report"""
+    return {
+        "timestamp": datetime.now(UTC).isoformat(),
+        "traces": [t.to_dict() for t in get_trace_history()],
+        "failures": _failure_detector.get_status(),
+    }

devloop/core/event.py

@@ -0,0 +1,105 @@
+"""Event system core - simplified for prototype."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+import uuid
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, Set
+
+
+class Priority(Enum):
+    """Event priority levels."""
+
+    LOW = 0
+    NORMAL = 1
+    HIGH = 2
+    CRITICAL = 3
+
+
+@dataclass
+class Event:
+    """Base event class."""
+
+    type: str
+    payload: Dict[str, Any]
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    timestamp: float = field(default_factory=time.time)
+    source: str = "unknown"
+    priority: Priority = Priority.NORMAL
+
+    def __lt__(self, other: Event) -> bool:
+        """Compare events by priority for priority queue."""
+        return self.priority.value > other.priority.value
+
+
+class EventBus:
+    """Central event bus for publishing and subscribing to events."""
+
+    def __init__(self):
+        self._subscribers: Dict[str, Set[asyncio.Queue]] = {}
+        self._event_log: list[Event] = []  # For debugging
+
+    async def subscribe(self, event_type: str, queue: asyncio.Queue) -> None:
+        """Subscribe to events of a specific type."""
+        if event_type not in self._subscribers:
+            self._subscribers[event_type] = set()
+        self._subscribers[event_type].add(queue)
+
+    async def unsubscribe(self, event_type: str, queue: asyncio.Queue) -> None:
+        """Unsubscribe from events."""
+        if event_type in self._subscribers:
+            self._subscribers[event_type].discard(queue)
+
+    async def emit(self, event: Event) -> None:
+        """Emit an event to all subscribers."""
+        # Log event for debugging
+        self._event_log.append(event)
+        if len(self._event_log) > 100:  # Keep last 100 events
+            self._event_log.pop(0)
+
+        # Store event in event store (async, non-blocking)
+        from .event_store import event_store
+
+        # Don't await - fire and forget for performance
+        asyncio.create_task(event_store.store_event(event))
+
+        # Emit to matching subscribers (supporting patterns)
+        notified_queues = set()
+
+        for pattern, queues in self._subscribers.items():
+            if self._matches_pattern(event.type, pattern):
+                for queue in list(queues):
+                    if queue not in notified_queues:  # Avoid duplicate notifications
+                        try:
+                            await queue.put(event)
+                            notified_queues.add(queue)
+                        except (
+                            asyncio.QueueFull,
+                            asyncio.CancelledError,
+                            RuntimeError,
+                        ):
+                            pass  # Queue might be closed or in a bad state
+
+    def _matches_pattern(self, event_type: str, pattern: str) -> bool:
+        """Check if event type matches a subscription pattern."""
+        # Exact match
+        if event_type == pattern:
+            return True
+
+        # Global wildcard
+        if pattern == "*":
+            return True
+
+        # Pattern matching (e.g., "file:*" matches "file:created")
+        if pattern.endswith("*"):
+            prefix = pattern[:-1]  # Remove the *
+            return event_type.startswith(prefix)
+
+        return False
+
+    def get_recent_events(self, count: int = 10) -> list[Event]:
+        """Get recent events for debugging."""
+        return self._event_log[-count:]

devloop/core/event_store.py

@@ -0,0 +1,316 @@
+"""Event store for persistent event logging using SQLite."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import sqlite3
+from datetime import datetime, UTC
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .event import Event
+
+logger = logging.getLogger(__name__)
+
+
+class EventStore:
+    """SQLite-based event store for persistent event logging."""
+
+    def __init__(self, db_path: Path):
+        self.db_path = db_path
+        self._lock = asyncio.Lock()
+        self._connection: Optional[sqlite3.Connection] = None
+
+    @property
+    def connection(self) -> sqlite3.Connection:
+        """Get the database connection, raising an exception if not initialized."""
+        if self._connection is None:
+            raise RuntimeError(
+                "Database connection not initialized. Call initialize() first."
+            )
+        return self._connection
+
+    async def initialize(self) -> None:
+        """Initialize the event store database."""
+        async with self._lock:
+            self.db_path.parent.mkdir(parents=True, exist_ok=True)
+
+            # Use thread pool for SQLite operations since it's not async
+            loop = asyncio.get_event_loop()
+            await loop.run_in_executor(None, self._init_db)
+
+    def _init_db(self) -> None:
+        """Initialize database schema (runs in thread pool)."""
+        self._connection = sqlite3.connect(str(self.db_path), check_same_thread=False)
+        self.connection.execute(
+            """
+        CREATE TABLE IF NOT EXISTS events (
+        id TEXT PRIMARY KEY,
+        type TEXT NOT NULL,
+        timestamp REAL NOT NULL,
+        source TEXT NOT NULL,
+        payload TEXT NOT NULL,
+        priority INTEGER NOT NULL,
+        created_at REAL NOT NULL
+        )
+        """
+        )
+
+        # Create indexes for efficient queries
+        self.connection.execute(
+            """
+            CREATE INDEX IF NOT EXISTS idx_events_type ON events(type)
+        """
+        )
+        self.connection.execute(
+            """
+            CREATE INDEX IF NOT EXISTS idx_events_timestamp ON events(timestamp)
+        """
+        )
+        self.connection.execute(
+            """
+            CREATE INDEX IF NOT EXISTS idx_events_source ON events(source)
+        """
+        )
+
+        self.connection.commit()
+        logger.info(f"Event store initialized at {self.db_path}")
+
+    async def store_event(self, event: Event) -> None:
+        """Store an event in the database."""
+        async with self._lock:
+            if not self._connection:
+                logger.warning("Event store not initialized, skipping event storage")
+                return
+
+            loop = asyncio.get_event_loop()
+            await loop.run_in_executor(None, self._store_event_sync, event)
+
+    def _store_event_sync(self, event: Event) -> None:
+        """Store event synchronously (runs in thread pool)."""
+        try:
+            # Convert event to dict for JSON storage
+            event_dict = {
+                "id": event.id,
+                "type": event.type,
+                "timestamp": event.timestamp,
+                "source": event.source,
+                "payload": event.payload,
+                "priority": (
+                    event.priority.value
+                    if hasattr(event.priority, "value")
+                    else event.priority
+                ),
+                "created_at": datetime.now(UTC).timestamp(),
+            }
+
+            self.connection.execute(
+                """
+                INSERT OR REPLACE INTO events
+                (id, type, timestamp, source, payload, priority, created_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+            """,
+                (
+                    event_dict["id"],
+                    event_dict["type"],
+                    event_dict["timestamp"],
+                    event_dict["source"],
+                    json.dumps(event_dict["payload"]),
+                    event_dict["priority"],
+                    event_dict["created_at"],
+                ),
+            )
+
+            self.connection.commit()
+
+        except Exception as e:
+            logger.error(f"Failed to store event {event.id}: {e}")
+
+    async def get_events(
+        self,
+        event_type: Optional[str] = None,
+        source: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+        since: Optional[float] = None,
+    ) -> List[Event]:
+        """Retrieve events from the database."""
+        async with self._lock:
+            if not self._connection:
+                return []
+
+            loop = asyncio.get_event_loop()
+            return await loop.run_in_executor(
+                None, self._get_events_sync, event_type, source, limit, offset, since
+            )
+
+    def _get_events_sync(
+        self,
+        event_type: Optional[str],
+        source: Optional[str],
+        limit: int,
+        offset: int,
+        since: Optional[float],
+    ) -> List[Event]:
+        """Retrieve events synchronously."""
+        try:
+            query = "SELECT id, type, timestamp, source, payload, priority FROM events WHERE 1=1"
+            params: List[Any] = []
+
+            if event_type:
+                query += " AND type = ?"
+                params.append(event_type)
+
+            if source:
+                query += " AND source = ?"
+                params.append(source)
+
+            if since:
+                query += " AND timestamp >= ?"
+                params.append(since)
+
+            query += " ORDER BY timestamp DESC LIMIT ? OFFSET ?"
+            params.extend([limit, offset])
+
+            cursor = self.connection.execute(query, params)
+            rows = cursor.fetchall()
+
+            events = []
+            for row in rows:
+                event_id, event_type, timestamp, source, payload_json, priority = row
+
+                # Parse JSON
+                payload = json.loads(payload_json)
+
+                # Reconstruct event
+                event = Event(
+                    type=event_type,
+                    payload=payload,
+                    id=event_id,
+                    timestamp=timestamp,
+                    source=source,
+                    priority=priority,
+                )
+
+                events.append(event)
+
+            return events
+
+        except Exception as e:
+            logger.error(f"Failed to retrieve events: {e}")
+            return []
+
+    async def get_event_stats(self) -> Dict[str, Any]:
+        """Get statistics about stored events."""
+        async with self._lock:
+            if not self._connection:
+                return {}
+
+            loop = asyncio.get_event_loop()
+            return await loop.run_in_executor(None, self._get_event_stats_sync)
+
+    def _get_event_stats_sync(self) -> Dict[str, Any]:
+        """Get event statistics synchronously."""
+        try:
+            # Total events
+            cursor = self.connection.execute("SELECT COUNT(*) FROM events")
+            total_events = cursor.fetchone()[0]
+
+            # Events by type
+            cursor = self.connection.execute(
+                """
+                SELECT type, COUNT(*) as count
+                FROM events
+                GROUP BY type
+                ORDER BY count DESC
+            """
+            )
+            events_by_type = {row[0]: row[1] for row in cursor.fetchall()}
+
+            # Events by source
+            cursor = self.connection.execute(
+                """
+                SELECT source, COUNT(*) as count
+                FROM events
+                GROUP BY source
+                ORDER BY count DESC
+            """
+            )
+            events_by_source = {row[0]: row[1] for row in cursor.fetchall()}
+
+            # Time range
+            cursor = self.connection.execute(
+                """
+                SELECT MIN(timestamp), MAX(timestamp) FROM events
+            """
+            )
+            time_range = cursor.fetchone()
+            oldest_timestamp = time_range[0] if time_range[0] else None
+            newest_timestamp = time_range[1] if time_range[1] else None
+
+            return {
+                "total_events": total_events,
+                "events_by_type": events_by_type,
+                "events_by_source": events_by_source,
+                "oldest_timestamp": oldest_timestamp,
+                "newest_timestamp": newest_timestamp,
+                "database_size": (
+                    self.db_path.stat().st_size if self.db_path.exists() else 0
+                ),
+            }
+
+        except Exception as e:
+            logger.error(f"Failed to get event stats: {e}")
+            return {}
+
+    async def cleanup_old_events(self, days_to_keep: int = 30) -> int:
+        """Clean up events older than specified days."""
+        async with self._lock:
+            if not self._connection:
+                return 0
+
+            cutoff_timestamp = datetime.now(UTC).timestamp() - (
+                days_to_keep * 24 * 60 * 60
+            )
+
+            loop = asyncio.get_event_loop()
+            return await loop.run_in_executor(
+                None,
+                lambda: self._cleanup_old_events_sync(cutoff_timestamp, days_to_keep),
+            )
+
+    def _cleanup_old_events_sync(
+        self, cutoff_timestamp: float, days_to_keep: int
+    ) -> int:
+        """Clean up old events synchronously."""
+        try:
+            cursor = self.connection.execute(
+                "DELETE FROM events WHERE timestamp < ?", (cutoff_timestamp,)
+            )
+            deleted_count = cursor.rowcount
+            self.connection.commit()
+
+            if deleted_count > 0:
+                logger.info(
+                    f"Cleaned up {deleted_count} events older than {days_to_keep} days"
+                )
+
+            return deleted_count
+
+        except Exception as e:
+            logger.error(f"Failed to cleanup old events: {e}")
+            return 0
+
+    async def close(self) -> None:
+        """Close the database connection."""
+        async with self._lock:
+            if self._connection:
+                self._connection.close()
+                self._connection = None
+                logger.info("Event store closed")
+
+
+# Global instance
+event_store = EventStore(Path(".devloop/events.db"))