smartify-ai 0.1.0__py3-none-any.whl

smartify/api/events.py

@@ -0,0 +1,345 @@
+"""Grid execution events for async operation tracking.
+
+Provides:
+- Event storage and retrieval
+- Polling endpoint for execution progress
+- WebSocket endpoint for real-time streaming (optional)
+"""
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from collections import deque
+from dataclasses import dataclass, field
+import asyncio
+import logging
+
+from pydantic import BaseModel, Field
+
+
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# Event Types
+# ============================================================================
+
+class EventType(str, Enum):
+    """Types of events that can occur during grid execution."""
+    
+    # Grid lifecycle events
+    GRID_LOADED = "grid.loaded"
+    GRID_ENERGIZED = "grid.energized"
+    GRID_STARTED = "grid.started"
+    GRID_PAUSED = "grid.paused"
+    GRID_RESUMED = "grid.resumed"
+    GRID_STOPPED = "grid.stopped"
+    GRID_COMPLETED = "grid.completed"
+    GRID_FAILED = "grid.failed"
+    
+    # Node events
+    NODE_STARTED = "node.started"
+    NODE_COMPLETED = "node.completed"
+    NODE_FAILED = "node.failed"
+    NODE_SKIPPED = "node.skipped"
+    NODE_RETRYING = "node.retrying"
+    
+    # Spark events
+    SPARK_SPAWNED = "spark.spawned"
+    SPARK_COMPLETED = "spark.completed"
+    SPARK_FAILED = "spark.failed"
+    
+    # Breaker events
+    BREAKER_WARNING = "breaker.warning"
+    BREAKER_TRIPPED = "breaker.tripped"
+    
+    # Approval events
+    APPROVAL_REQUESTED = "approval.requested"
+    APPROVAL_GRANTED = "approval.granted"
+    APPROVAL_DENIED = "approval.denied"
+    APPROVAL_EXPIRED = "approval.expired"
+    
+    # Tool events
+    TOOL_CALLED = "tool.called"
+    TOOL_RESULT = "tool.result"
+
+
+# ============================================================================
+# Event Models
+# ============================================================================
+
+class GridEvent(BaseModel):
+    """A single event from grid execution."""
+    
+    id: str = Field(..., description="Unique event ID")
+    type: EventType = Field(..., description="Event type")
+    grid_id: str = Field(..., description="Grid this event belongs to")
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    
+    # Optional context
+    node_id: Optional[str] = Field(None, description="Node ID if node-specific event")
+    
+    # Event payload
+    data: Dict[str, Any] = Field(default_factory=dict, description="Event-specific data")
+    
+    # For progress tracking
+    progress: Optional[float] = Field(None, ge=0.0, le=1.0, description="Execution progress (0-1)")
+
+
+class EventsResponse(BaseModel):
+    """Response for events polling endpoint."""
+    
+    grid_id: str
+    events: List[GridEvent]
+    total: int = Field(..., description="Total events for this grid")
+    has_more: bool = Field(..., description="Whether more events exist after these")
+    
+    # Cursor for pagination
+    next_cursor: Optional[str] = Field(None, description="Cursor for next page")
+    
+    # Current grid state summary
+    state: str
+    progress: float = Field(ge=0.0, le=1.0)
+    completed_nodes: int
+    total_nodes: int
+
+
+class EventFilter(BaseModel):
+    """Filter for events query."""
+    
+    types: Optional[List[EventType]] = Field(None, description="Filter by event types")
+    node_id: Optional[str] = Field(None, description="Filter by node ID")
+    after: Optional[str] = Field(None, description="Cursor: return events after this ID")
+    limit: int = Field(default=50, ge=1, le=200, description="Maximum events to return")
+
+
+# ============================================================================
+# Event Store
+# ============================================================================
+
+@dataclass
+class EventStore:
+    """In-memory event storage per grid.
+    
+    Uses a bounded deque to limit memory usage.
+    For production, consider Redis Streams or similar.
+    """
+    
+    grid_id: str
+    max_events: int = 1000
+    _events: deque = field(default_factory=lambda: deque(maxlen=1000))
+    _event_counter: int = 0
+    _lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+    
+    def __post_init__(self):
+        self._events = deque(maxlen=self.max_events)
+    
+    async def append(self, event: GridEvent) -> None:
+        """Add an event to the store."""
+        async with self._lock:
+            self._event_counter += 1
+            self._events.append(event)
+    
+    async def get_events(
+        self,
+        after: Optional[str] = None,
+        types: Optional[List[EventType]] = None,
+        node_id: Optional[str] = None,
+        limit: int = 50,
+    ) -> tuple[List[GridEvent], bool, Optional[str]]:
+        """Get events with filtering and pagination.
+        
+        Returns (events, has_more, next_cursor)
+        """
+        async with self._lock:
+            events = list(self._events)
+        
+        # Apply cursor filter (after)
+        if after:
+            found_idx = None
+            for i, e in enumerate(events):
+                if e.id == after:
+                    found_idx = i
+                    break
+            if found_idx is not None:
+                events = events[found_idx + 1:]
+        
+        # Apply type filter
+        if types:
+            events = [e for e in events if e.type in types]
+        
+        # Apply node filter
+        if node_id:
+            events = [e for e in events if e.node_id == node_id]
+        
+        # Pagination
+        has_more = len(events) > limit
+        events = events[:limit]
+        
+        next_cursor = events[-1].id if events and has_more else None
+        
+        return events, has_more, next_cursor
+    
+    async def count(self) -> int:
+        """Get total event count."""
+        async with self._lock:
+            return len(self._events)
+    
+    async def clear(self) -> None:
+        """Clear all events."""
+        async with self._lock:
+            self._events.clear()
+
+
+# ============================================================================
+# Event Manager
+# ============================================================================
+
+class EventManager:
+    """Manages event stores for all grids.
+    
+    Thread-safe and async-compatible.
+    """
+    
+    def __init__(self, max_events_per_grid: int = 1000):
+        self.max_events = max_events_per_grid
+        self._stores: Dict[str, EventStore] = {}
+        self._lock = asyncio.Lock()
+        
+        # WebSocket subscribers (grid_id -> set of queues)
+        self._subscribers: Dict[str, set] = {}
+    
+    async def get_store(self, grid_id: str) -> EventStore:
+        """Get or create event store for a grid."""
+        async with self._lock:
+            if grid_id not in self._stores:
+                self._stores[grid_id] = EventStore(
+                    grid_id=grid_id,
+                    max_events=self.max_events,
+                )
+            return self._stores[grid_id]
+    
+    async def emit(
+        self,
+        grid_id: str,
+        event_type: EventType,
+        node_id: Optional[str] = None,
+        data: Optional[Dict[str, Any]] = None,
+        progress: Optional[float] = None,
+    ) -> GridEvent:
+        """Emit an event for a grid.
+        
+        Args:
+            grid_id: Grid identifier
+            event_type: Type of event
+            node_id: Optional node ID for node-specific events
+            data: Optional event payload
+            progress: Optional execution progress (0-1)
+        
+        Returns:
+            The created event
+        """
+        store = await self.get_store(grid_id)
+        
+        event = GridEvent(
+            id=f"evt_{grid_id}_{store._event_counter + 1}",
+            type=event_type,
+            grid_id=grid_id,
+            node_id=node_id,
+            data=data or {},
+            progress=progress,
+        )
+        
+        await store.append(event)
+        
+        # Notify WebSocket subscribers
+        await self._notify_subscribers(grid_id, event)
+        
+        logger.debug(f"Event emitted: {event_type.value} for grid {grid_id}")
+        return event
+    
+    async def get_events(
+        self,
+        grid_id: str,
+        filter: Optional[EventFilter] = None,
+    ) -> tuple[List[GridEvent], bool, Optional[str]]:
+        """Get events for a grid with optional filtering."""
+        store = await self.get_store(grid_id)
+        
+        if filter:
+            return await store.get_events(
+                after=filter.after,
+                types=filter.types,
+                node_id=filter.node_id,
+                limit=filter.limit,
+            )
+        else:
+            return await store.get_events()
+    
+    async def subscribe(self, grid_id: str) -> asyncio.Queue:
+        """Subscribe to real-time events for a grid.
+        
+        Returns a queue that will receive events.
+        """
+        async with self._lock:
+            if grid_id not in self._subscribers:
+                self._subscribers[grid_id] = set()
+            
+            queue: asyncio.Queue = asyncio.Queue()
+            self._subscribers[grid_id].add(queue)
+            return queue
+    
+    async def unsubscribe(self, grid_id: str, queue: asyncio.Queue) -> None:
+        """Unsubscribe from real-time events."""
+        async with self._lock:
+            if grid_id in self._subscribers:
+                self._subscribers[grid_id].discard(queue)
+                if not self._subscribers[grid_id]:
+                    del self._subscribers[grid_id]
+    
+    async def _notify_subscribers(self, grid_id: str, event: GridEvent) -> None:
+        """Notify all subscribers of a new event."""
+        async with self._lock:
+            subscribers = self._subscribers.get(grid_id, set()).copy()
+        
+        for queue in subscribers:
+            try:
+                queue.put_nowait(event)
+            except asyncio.QueueFull:
+                logger.warning(f"Event queue full for grid {grid_id}, dropping event")
+    
+    async def cleanup_grid(self, grid_id: str) -> None:
+        """Clean up event store for a deleted grid."""
+        async with self._lock:
+            if grid_id in self._stores:
+                del self._stores[grid_id]
+            if grid_id in self._subscribers:
+                # Close all subscriber queues
+                for queue in self._subscribers[grid_id]:
+                    queue.put_nowait(None)  # Signal end
+                del self._subscribers[grid_id]
+
+
+# Global event manager instance
+event_manager = EventManager()
+
+
+# ============================================================================
+# Helper Functions
+# ============================================================================
+
+def create_grid_event(
+    grid_id: str,
+    event_type: EventType,
+    node_id: Optional[str] = None,
+    **data,
+) -> GridEvent:
+    """Create an event (for use when not async)."""
+    import uuid
+    return GridEvent(
+        id=f"evt_{uuid.uuid4().hex[:8]}",
+        type=event_type,
+        grid_id=grid_id,
+        node_id=node_id,
+        data=data,
+    )