smartify-ai 0.1.0__py3-none-any.whl

smartify/engine/approval.py

@@ -0,0 +1,479 @@
+"""Approval flow for human-in-the-loop nodes.
+
+Approval nodes pause grid execution and wait for human approval
+before continuing. They can send notifications via multiple channels
+(Slack, webhook, email) and track approval state.
+"""
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from enum import Enum
+from typing import Any, Callable, Dict, List, Optional, Protocol
+from uuid import uuid4
+import json
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class ApprovalStatus(str, Enum):
+    """Status of an approval request."""
+    PENDING = "pending"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+    EXPIRED = "expired"
+    CANCELLED = "cancelled"
+
+
+@dataclass
+class ApprovalRequest:
+    """An approval request awaiting human decision."""
+    id: str
+    grid_id: str
+    node_id: str
+    prompt: str
+    context: Dict[str, Any]
+    
+    # Configuration
+    timeout_seconds: int = 86400  # 24 hours default
+    required_approvers: int = 1
+    allowed_approvers: List[str] = field(default_factory=list)
+    
+    # State
+    status: ApprovalStatus = ApprovalStatus.PENDING
+    created_at: datetime = field(default_factory=datetime.now)
+    resolved_at: Optional[datetime] = None
+    approvers: List[str] = field(default_factory=list)
+    rejection_reason: Optional[str] = None
+    
+    # Outputs from preceding nodes to show
+    show_outputs: Dict[str, Any] = field(default_factory=dict)
+    
+    @property
+    def expires_at(self) -> datetime:
+        return self.created_at + timedelta(seconds=self.timeout_seconds)
+    
+    @property
+    def is_expired(self) -> bool:
+        return datetime.now() > self.expires_at and self.status == ApprovalStatus.PENDING
+    
+    def approve(self, approver: str) -> bool:
+        """Record an approval. Returns True if fully approved."""
+        if self.status != ApprovalStatus.PENDING:
+            return False
+        
+        if self.allowed_approvers and approver not in self.allowed_approvers:
+            logger.warning(f"Approver {approver} not in allowed list")
+            return False
+        
+        if approver not in self.approvers:
+            self.approvers.append(approver)
+        
+        if len(self.approvers) >= self.required_approvers:
+            self.status = ApprovalStatus.APPROVED
+            self.resolved_at = datetime.now()
+            return True
+        
+        return False
+    
+    def reject(self, approver: str, reason: Optional[str] = None) -> None:
+        """Reject the approval request."""
+        if self.status != ApprovalStatus.PENDING:
+            return
+        
+        self.status = ApprovalStatus.REJECTED
+        self.resolved_at = datetime.now()
+        self.rejection_reason = reason
+        self.approvers.append(approver)
+
+
+class NotificationChannel(ABC):
+    """Abstract base for notification channels."""
+    
+    @abstractmethod
+    async def send(self, request: ApprovalRequest, callback_url: str) -> bool:
+        """Send approval notification. Returns True if sent successfully."""
+        pass
+
+
+class SlackNotificationChannel(NotificationChannel):
+    """Send approval requests to Slack."""
+    
+    def __init__(
+        self,
+        webhook_url: Optional[str] = None,
+        bot_token: Optional[str] = None,
+        channel: Optional[str] = None,
+    ):
+        self.webhook_url = webhook_url
+        self.bot_token = bot_token
+        self.channel = channel
+    
+    async def send(self, request: ApprovalRequest, callback_url: str) -> bool:
+        """Send Slack notification with approval buttons."""
+        if not (self.webhook_url or self.bot_token):
+            logger.warning("Slack not configured - skipping notification")
+            return False
+        
+        # Build message blocks
+        blocks = [
+            {
+                "type": "header",
+                "text": {
+                    "type": "plain_text",
+                    "text": "🔔 Approval Required",
+                }
+            },
+            {
+                "type": "section",
+                "text": {
+                    "type": "mrkdwn",
+                    "text": f"*Grid:* {request.grid_id}\n*Node:* {request.node_id}",
+                }
+            },
+            {
+                "type": "section",
+                "text": {
+                    "type": "mrkdwn",
+                    "text": request.prompt,
+                }
+            },
+        ]
+        
+        # Add context from previous nodes if available
+        if request.show_outputs:
+            context_text = "```\n" + json.dumps(request.show_outputs, indent=2)[:2000] + "\n```"
+            blocks.append({
+                "type": "section",
+                "text": {
+                    "type": "mrkdwn",
+                    "text": f"*Context:*\n{context_text}",
+                }
+            })
+        
+        # Add approval buttons
+        blocks.append({
+            "type": "actions",
+            "elements": [
+                {
+                    "type": "button",
+                    "text": {"type": "plain_text", "text": "✅ Approve"},
+                    "style": "primary",
+                    "action_id": f"approve_{request.id}",
+                    "value": request.id,
+                },
+                {
+                    "type": "button",
+                    "text": {"type": "plain_text", "text": "❌ Reject"},
+                    "style": "danger",
+                    "action_id": f"reject_{request.id}",
+                    "value": request.id,
+                },
+            ]
+        })
+        
+        # Add expiration notice
+        blocks.append({
+            "type": "context",
+            "elements": [{
+                "type": "mrkdwn",
+                "text": f"⏰ Expires: {request.expires_at.strftime('%Y-%m-%d %H:%M:%S')} | Request ID: `{request.id}`"
+            }]
+        })
+        
+        payload = {"blocks": blocks}
+        
+        try:
+            async with httpx.AsyncClient() as client:
+                if self.webhook_url:
+                    response = await client.post(
+                        self.webhook_url,
+                        json=payload,
+                        timeout=10.0,
+                    )
+                elif self.bot_token and self.channel:
+                    payload["channel"] = self.channel
+                    response = await client.post(
+                        "https://slack.com/api/chat.postMessage",
+                        json=payload,
+                        headers={"Authorization": f"Bearer {self.bot_token}"},
+                        timeout=10.0,
+                    )
+                else:
+                    return False
+                
+                if response.status_code == 200:
+                    logger.info(f"Slack notification sent for approval {request.id}")
+                    return True
+                else:
+                    logger.error(f"Slack notification failed: {response.text}")
+                    return False
+                    
+        except Exception as e:
+            logger.error(f"Failed to send Slack notification: {e}")
+            return False
+
+
+class WebhookNotificationChannel(NotificationChannel):
+    """Send approval requests to a webhook URL."""
+    
+    def __init__(self, url: str, headers: Optional[Dict[str, str]] = None):
+        self.url = url
+        self.headers = headers or {}
+    
+    async def send(self, request: ApprovalRequest, callback_url: str) -> bool:
+        """POST approval request to webhook."""
+        payload = {
+            "type": "approval_request",
+            "request_id": request.id,
+            "grid_id": request.grid_id,
+            "node_id": request.node_id,
+            "prompt": request.prompt,
+            "context": request.show_outputs,
+            "callback_url": callback_url,
+            "expires_at": request.expires_at.isoformat(),
+        }
+        
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.post(
+                    self.url,
+                    json=payload,
+                    headers=self.headers,
+                    timeout=10.0,
+                )
+                
+                if response.status_code in (200, 201, 202):
+                    logger.info(f"Webhook notification sent for approval {request.id}")
+                    return True
+                else:
+                    logger.error(f"Webhook notification failed: {response.status_code}")
+                    return False
+                    
+        except Exception as e:
+            logger.error(f"Failed to send webhook notification: {e}")
+            return False
+
+
+class ApprovalManager:
+    """Manages approval requests and notifications.
+    
+    Usage:
+        manager = ApprovalManager()
+        manager.add_channel(SlackNotificationChannel(webhook_url="..."))
+        
+        # Create approval request
+        request = await manager.create_request(
+            grid_id="grid-1",
+            node_id="approval-node-1",
+            prompt="Review this deployment",
+            context={"changes": [...]},
+        )
+        
+        # Wait for approval (with timeout)
+        result = await manager.wait_for_approval(request.id, timeout=3600)
+    """
+    
+    def __init__(self, callback_base_url: Optional[str] = None):
+        self.requests: Dict[str, ApprovalRequest] = {}
+        self.channels: List[NotificationChannel] = []
+        self.callback_base_url = callback_base_url or "http://localhost:8000"
+        
+        # Event tracking for async waiting
+        self._events: Dict[str, asyncio.Event] = {}
+    
+    def add_channel(self, channel: NotificationChannel) -> None:
+        """Add a notification channel."""
+        self.channels.append(channel)
+    
+    async def create_request(
+        self,
+        grid_id: str,
+        node_id: str,
+        prompt: str,
+        context: Optional[Dict[str, Any]] = None,
+        timeout_seconds: int = 86400,
+        required_approvers: int = 1,
+        allowed_approvers: Optional[List[str]] = None,
+        show_outputs: Optional[Dict[str, Any]] = None,
+    ) -> ApprovalRequest:
+        """Create a new approval request and send notifications."""
+        request_id = f"apr-{uuid4().hex[:12]}"
+        
+        request = ApprovalRequest(
+            id=request_id,
+            grid_id=grid_id,
+            node_id=node_id,
+            prompt=prompt,
+            context=context or {},
+            timeout_seconds=timeout_seconds,
+            required_approvers=required_approvers,
+            allowed_approvers=allowed_approvers or [],
+            show_outputs=show_outputs or {},
+        )
+        
+        self.requests[request_id] = request
+        self._events[request_id] = asyncio.Event()
+        
+        # Send notifications
+        callback_url = f"{self.callback_base_url}/approvals/{request_id}"
+        
+        for channel in self.channels:
+            try:
+                await channel.send(request, callback_url)
+            except Exception as e:
+                logger.error(f"Notification channel failed: {e}")
+        
+        logger.info(f"Created approval request {request_id} for {grid_id}/{node_id}")
+        
+        return request
+    
+    def get_request(self, request_id: str) -> Optional[ApprovalRequest]:
+        """Get an approval request by ID."""
+        return self.requests.get(request_id)
+    
+    def process_approval(self, request_id: str, approver: str) -> bool:
+        """Process an approval action. Returns True if fully approved."""
+        request = self.requests.get(request_id)
+        if not request:
+            logger.warning(f"Approval request {request_id} not found")
+            return False
+        
+        if request.is_expired:
+            request.status = ApprovalStatus.EXPIRED
+            self._signal_complete(request_id)
+            return False
+        
+        result = request.approve(approver)
+        
+        if request.status == ApprovalStatus.APPROVED:
+            self._signal_complete(request_id)
+        
+        return result
+    
+    def process_rejection(
+        self,
+        request_id: str,
+        approver: str,
+        reason: Optional[str] = None,
+    ) -> None:
+        """Process a rejection action."""
+        request = self.requests.get(request_id)
+        if not request:
+            logger.warning(f"Approval request {request_id} not found")
+            return
+        
+        request.reject(approver, reason)
+        self._signal_complete(request_id)
+    
+    def _signal_complete(self, request_id: str) -> None:
+        """Signal that a request has been resolved."""
+        if request_id in self._events:
+            self._events[request_id].set()
+    
+    async def wait_for_approval(
+        self,
+        request_id: str,
+        timeout: Optional[int] = None,
+    ) -> ApprovalRequest:
+        """Wait for an approval request to be resolved.
+        
+        Args:
+            request_id: The approval request ID
+            timeout: Override timeout in seconds (defaults to request's timeout)
+            
+        Returns:
+            The resolved ApprovalRequest
+            
+        Raises:
+            TimeoutError: If timeout is reached
+        """
+        request = self.requests.get(request_id)
+        if not request:
+            raise ValueError(f"Approval request {request_id} not found")
+        
+        if request.status != ApprovalStatus.PENDING:
+            return request
+        
+        event = self._events.get(request_id)
+        if not event:
+            event = asyncio.Event()
+            self._events[request_id] = event
+        
+        wait_timeout = timeout or request.timeout_seconds
+        
+        try:
+            await asyncio.wait_for(event.wait(), timeout=wait_timeout)
+        except asyncio.TimeoutError:
+            request.status = ApprovalStatus.EXPIRED
+            raise TimeoutError(f"Approval request {request_id} expired")
+        
+        return request
+    
+    def get_pending_requests(self, grid_id: Optional[str] = None) -> List[ApprovalRequest]:
+        """Get all pending approval requests, optionally filtered by grid."""
+        pending = []
+        for request in self.requests.values():
+            if request.status == ApprovalStatus.PENDING:
+                # Check for expiration
+                if request.is_expired:
+                    request.status = ApprovalStatus.EXPIRED
+                    continue
+                    
+                if grid_id is None or request.grid_id == grid_id:
+                    pending.append(request)
+        return pending
+    
+    def cleanup_expired(self) -> int:
+        """Mark expired requests and return count."""
+        count = 0
+        for request in self.requests.values():
+            if request.status == ApprovalStatus.PENDING and request.is_expired:
+                request.status = ApprovalStatus.EXPIRED
+                self._signal_complete(request.id)
+                count += 1
+        return count
+
+
+# Singleton for global access
+_approval_manager: Optional[ApprovalManager] = None
+
+
+def get_approval_manager() -> ApprovalManager:
+    """Get the global approval manager instance."""
+    global _approval_manager
+    if _approval_manager is None:
+        _approval_manager = ApprovalManager()
+    return _approval_manager
+
+
+def configure_approval_manager(
+    callback_base_url: Optional[str] = None,
+    slack_webhook: Optional[str] = None,
+    slack_bot_token: Optional[str] = None,
+    slack_channel: Optional[str] = None,
+    webhooks: Optional[List[str]] = None,
+) -> ApprovalManager:
+    """Configure the global approval manager with notification channels."""
+    global _approval_manager
+    
+    _approval_manager = ApprovalManager(callback_base_url=callback_base_url)
+    
+    # Add Slack if configured
+    if slack_webhook or slack_bot_token:
+        _approval_manager.add_channel(SlackNotificationChannel(
+            webhook_url=slack_webhook,
+            bot_token=slack_bot_token,
+            channel=slack_channel,
+        ))
+    
+    # Add webhooks
+    if webhooks:
+        for url in webhooks:
+            _approval_manager.add_channel(WebhookNotificationChannel(url))
+    
+    return _approval_manager