empathy-framework 4.9.1__py3-none-any.whl → 5.0.1__py3-none-any.whl

empathy_os/telemetry/agent_coordination.py

@@ -0,0 +1,478 @@
+"""Agent Coordination via TTL Signals.
+
+Pattern 2 from Agent Coordination Architecture - TTL-based inter-agent
+communication for orchestration, synchronization, and coordination.
+
+Usage:
+    # Agent A signals completion
+    coordinator = CoordinationSignals()
+    coordinator.signal(
+        signal_type="task_complete",
+        source_agent="agent-a",
+        target_agent="agent-b",
+        payload={"result": "success", "data": {...}}
+    )
+
+    # Agent B waits for signal
+    signal = coordinator.wait_for_signal(
+        signal_type="task_complete",
+        source_agent="agent-a",
+        timeout=30.0
+    )
+    if signal:
+        process(signal.payload)
+
+    # Orchestrator broadcasts to all agents
+    coordinator.broadcast(
+        signal_type="abort",
+        source_agent="orchestrator",
+        payload={"reason": "user_cancelled"}
+    )
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, TYPE_CHECKING
+from uuid import uuid4
+
+if TYPE_CHECKING:
+    from empathy_os.memory.types import AgentCredentials
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class CoordinationSignal:
+    """Coordination signal between agents.
+
+    Ephemeral message with TTL, used for agent-to-agent communication.
+    """
+
+    signal_id: str
+    signal_type: str  # "task_complete", "abort", "ready", "checkpoint", etc.
+    source_agent: str
+    target_agent: str | None  # None for broadcast
+    payload: dict[str, Any]
+    timestamp: datetime
+    ttl_seconds: int = 60
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "signal_id": self.signal_id,
+            "signal_type": self.signal_type,
+            "source_agent": self.source_agent,
+            "target_agent": self.target_agent,
+            "payload": self.payload,
+            "timestamp": self.timestamp.isoformat() if isinstance(self.timestamp, datetime) else self.timestamp,
+            "ttl_seconds": self.ttl_seconds,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CoordinationSignal:
+        """Create from dictionary."""
+        timestamp = data.get("timestamp")
+        if isinstance(timestamp, str):
+            timestamp = datetime.fromisoformat(timestamp)
+        elif not isinstance(timestamp, datetime):
+            timestamp = datetime.utcnow()
+
+        return cls(
+            signal_id=data["signal_id"],
+            signal_type=data["signal_type"],
+            source_agent=data["source_agent"],
+            target_agent=data.get("target_agent"),
+            payload=data.get("payload", {}),
+            timestamp=timestamp,
+            ttl_seconds=data.get("ttl_seconds", 60),
+        )
+
+
+class CoordinationSignals:
+    """TTL-based inter-agent coordination signals.
+
+    Agents can:
+    - Send signals to specific agents
+    - Broadcast signals to all agents
+    - Wait for specific signals with timeout
+    - Check for pending signals without blocking
+
+    Signals expire automatically via TTL, preventing stale coordination.
+    """
+
+    DEFAULT_TTL = 60  # Default signal TTL: 60 seconds
+    BROADCAST_TARGET = "*"  # Special target for broadcast signals
+    KEY_PREFIX = "empathy:signal:"  # Redis key prefix (consistent with framework)
+
+    def __init__(self, memory=None, agent_id: str | None = None, enable_streaming: bool = False):
+        """Initialize coordination signals.
+
+        Args:
+            memory: Memory instance for storing signals
+            agent_id: This agent's ID (for receiving targeted signals)
+            enable_streaming: If True, publish signal events to Redis Streams
+                            for real-time monitoring (Pattern 4).
+        """
+        self.memory = memory
+        self.agent_id = agent_id
+        self._enable_streaming = enable_streaming
+        self._event_streamer = None
+
+        if self.memory is None:
+            try:
+                from empathy_os.telemetry import UsageTracker
+
+                tracker = UsageTracker.get_instance()
+                if hasattr(tracker, "_memory"):
+                    self.memory = tracker._memory
+            except (ImportError, AttributeError):
+                pass
+
+        if self.memory is None:
+            logger.warning("No memory backend available for coordination signals")
+
+    def _get_event_streamer(self):
+        """Get or create EventStreamer instance (lazy initialization)."""
+        if not self._enable_streaming:
+            return None
+
+        if self._event_streamer is None:
+            try:
+                from empathy_os.telemetry.event_streaming import EventStreamer
+
+                self._event_streamer = EventStreamer(memory=self.memory)
+            except Exception as e:
+                logger.warning(f"Failed to initialize EventStreamer: {e}")
+                self._enable_streaming = False
+
+        return self._event_streamer
+
+    def signal(
+        self,
+        signal_type: str,
+        source_agent: str | None = None,
+        target_agent: str | None = None,
+        payload: dict[str, Any] | None = None,
+        ttl_seconds: int | None = None,
+        credentials: AgentCredentials | None = None,
+    ) -> str:
+        """Send a coordination signal.
+
+        Args:
+            signal_type: Type of signal (e.g., "task_complete", "abort", "ready")
+            source_agent: Source agent ID (defaults to self.agent_id)
+            target_agent: Target agent ID (None for broadcast)
+            payload: Signal payload data
+            ttl_seconds: TTL for this signal (defaults to DEFAULT_TTL)
+            credentials: Agent credentials for permission check (optional but recommended)
+
+        Returns:
+            Signal ID
+
+        Raises:
+            PermissionError: If credentials provided but agent lacks CONTRIBUTOR tier
+
+        Security:
+            Coordination signals require CONTRIBUTOR tier or higher. If credentials
+            are not provided, a warning is logged but the signal is still sent
+            (backward compatibility). For production use, always provide credentials.
+        """
+        if not self.memory:
+            logger.warning("Cannot send signal: no memory backend")
+            return ""
+
+        # Permission check for coordination signals (requires CONTRIBUTOR tier)
+        if credentials is not None:
+            if not credentials.can_stage():
+                raise PermissionError(
+                    f"Agent {credentials.agent_id} (Tier {credentials.tier.name}) "
+                    "cannot send coordination signals. Requires CONTRIBUTOR tier or higher."
+                )
+        else:
+            # Log warning if no credentials provided (security best practice)
+            logger.warning(
+                "Sending coordination signal without credentials - "
+                "permission check bypassed. Provide credentials for secure coordination."
+            )
+
+        source = source_agent or self.agent_id or "unknown"
+        signal_id = f"signal_{uuid4().hex[:8]}"
+        ttl = ttl_seconds or self.DEFAULT_TTL
+
+        signal = CoordinationSignal(
+            signal_id=signal_id,
+            signal_type=signal_type,
+            source_agent=source,
+            target_agent=target_agent,
+            payload=payload or {},
+            timestamp=datetime.utcnow(),
+            ttl_seconds=ttl,
+        )
+
+        # Store signal with TTL (Pattern 2)
+        # Key format: empathy:signal:{target}:{type}:{id}
+        target_key = target_agent or self.BROADCAST_TARGET
+        key = f"{self.KEY_PREFIX}{target_key}:{signal_type}:{signal_id}"
+
+        try:
+            if hasattr(self.memory, "stash"):
+                # Pass credentials through to memory backend for permission enforcement
+                self.memory.stash(key=key, data=signal.to_dict(), credentials=credentials, ttl_seconds=ttl)
+            elif hasattr(self.memory, "_redis"):
+                import json
+
+                self.memory._redis.setex(key, ttl, json.dumps(signal.to_dict()))
+            else:
+                logger.warning(f"Cannot send signal: unsupported memory type {type(self.memory)}")
+        except Exception as e:
+            logger.error(f"Failed to send signal {signal_id}: {e}")
+
+        # Publish to event stream (Pattern 4 - optional)
+        streamer = self._get_event_streamer()
+        if streamer:
+            try:
+                streamer.publish_event(
+                    event_type="coordination_signal",
+                    data=signal.to_dict(),
+                    source="empathy_os",
+                )
+            except Exception as e:
+                logger.debug(f"Failed to publish coordination signal event to stream: {e}")
+
+        return signal_id
+
+    def broadcast(
+        self,
+        signal_type: str,
+        source_agent: str | None = None,
+        payload: dict[str, Any] | None = None,
+        ttl_seconds: int | None = None,
+        credentials: AgentCredentials | None = None,
+    ) -> str:
+        """Broadcast signal to all agents.
+
+        Args:
+            signal_type: Type of signal
+            source_agent: Source agent ID
+            payload: Signal payload
+            ttl_seconds: TTL for signal
+            credentials: Agent credentials for permission check
+
+        Returns:
+            Signal ID
+
+        Raises:
+            PermissionError: If credentials provided but agent lacks CONTRIBUTOR tier
+        """
+        return self.signal(
+            signal_type=signal_type,
+            source_agent=source_agent,
+            target_agent=None,  # Broadcast
+            payload=payload,
+            ttl_seconds=ttl_seconds,
+            credentials=credentials,
+        )
+
+    def wait_for_signal(
+        self,
+        signal_type: str,
+        source_agent: str | None = None,
+        timeout: float = 30.0,
+        poll_interval: float = 0.5,
+    ) -> CoordinationSignal | None:
+        """Wait for a specific signal (blocking with timeout).
+
+        Args:
+            signal_type: Type of signal to wait for
+            source_agent: Optional source agent filter
+            timeout: Maximum wait time in seconds
+            poll_interval: Poll interval in seconds
+
+        Returns:
+            CoordinationSignal if received, None if timeout
+        """
+        if not self.memory or not self.agent_id:
+            return None
+
+        start_time = time.time()
+
+        while time.time() - start_time < timeout:
+            # Check for signal
+            signal = self.check_signal(signal_type=signal_type, source_agent=source_agent, consume=True)
+
+            if signal:
+                return signal
+
+            # Sleep before next poll
+            time.sleep(poll_interval)
+
+        return None
+
+    def check_signal(
+        self, signal_type: str, source_agent: str | None = None, consume: bool = True
+    ) -> CoordinationSignal | None:
+        """Check for a signal without blocking.
+
+        Args:
+            signal_type: Type of signal to check
+            source_agent: Optional source agent filter
+            consume: If True, remove signal after reading
+
+        Returns:
+            CoordinationSignal if available, None otherwise
+        """
+        if not self.memory or not self.agent_id:
+            return None
+
+        try:
+            # Scan for matching signals
+            # Check targeted signals: empathy:signal:{agent_id}:{type}:*
+            # Check broadcast signals: empathy:signal:*:{type}:*
+            patterns = [
+                f"{self.KEY_PREFIX}{self.agent_id}:{signal_type}:*",
+                f"{self.KEY_PREFIX}{self.BROADCAST_TARGET}:{signal_type}:*"
+            ]
+
+            for pattern in patterns:
+                if hasattr(self.memory, "_redis"):
+                    keys = self.memory._redis.keys(pattern)
+                else:
+                    continue
+
+                for key in keys:
+                    if isinstance(key, bytes):
+                        key = key.decode("utf-8")
+
+                    # Retrieve signal
+                    data = self._retrieve_signal(key)
+                    if not data:
+                        continue
+
+                    signal = CoordinationSignal.from_dict(data)
+
+                    # Filter by source if specified
+                    if source_agent and signal.source_agent != source_agent:
+                        continue
+
+                    # Consume signal if requested
+                    if consume:
+                        self._delete_signal(key)
+
+                    return signal
+
+            return None
+        except Exception as e:
+            logger.error(f"Failed to check signal: {e}")
+            return None
+
+    def get_pending_signals(self, signal_type: str | None = None) -> list[CoordinationSignal]:
+        """Get all pending signals for this agent.
+
+        Args:
+            signal_type: Optional filter by signal type
+
+        Returns:
+            List of pending signals
+        """
+        if not self.memory or not self.agent_id:
+            return []
+
+        try:
+            # Scan for all signals for this agent
+            patterns = [
+                f"{self.KEY_PREFIX}{self.agent_id}:*",
+                f"{self.KEY_PREFIX}{self.BROADCAST_TARGET}:*",
+            ]
+
+            signals = []
+            for pattern in patterns:
+                if hasattr(self.memory, "_redis"):
+                    keys = self.memory._redis.keys(pattern)
+                else:
+                    continue
+
+                for key in keys:
+                    if isinstance(key, bytes):
+                        key = key.decode("utf-8")
+
+                    data = self._retrieve_signal(key)
+                    if not data:
+                        continue
+
+                    signal = CoordinationSignal.from_dict(data)
+
+                    # Filter by type if specified
+                    if signal_type and signal.signal_type != signal_type:
+                        continue
+
+                    signals.append(signal)
+
+            return signals
+        except Exception as e:
+            logger.error(f"Failed to get pending signals: {e}")
+            return []
+
+    def clear_signals(self, signal_type: str | None = None) -> int:
+        """Clear all signals for this agent.
+
+        Args:
+            signal_type: Optional filter by signal type
+
+        Returns:
+            Number of signals cleared
+        """
+        if not self.memory or not self.agent_id:
+            return 0
+
+        signals = self.get_pending_signals(signal_type=signal_type)
+        count = 0
+
+        for signal in signals:
+            # Reconstruct key
+            target_key = signal.target_agent or self.BROADCAST_TARGET
+            key = f"{self.KEY_PREFIX}{target_key}:{signal.signal_type}:{signal.signal_id}"
+            if self._delete_signal(key):
+                count += 1
+
+        return count
+
+    def _retrieve_signal(self, key: str) -> dict[str, Any] | None:
+        """Retrieve signal data from memory."""
+        if not self.memory:
+            return None
+
+        try:
+            if hasattr(self.memory, "retrieve"):
+                return self.memory.retrieve(key, credentials=None)
+            elif hasattr(self.memory, "_redis"):
+                import json
+
+                data = self.memory._redis.get(key)
+                if data:
+                    if isinstance(data, bytes):
+                        data = data.decode("utf-8")
+                    return json.loads(data)
+            return None
+        except Exception as e:
+            logger.debug(f"Failed to retrieve signal {key}: {e}")
+            return None
+
+    def _delete_signal(self, key: str) -> bool:
+        """Delete signal from memory."""
+        if not self.memory:
+            return False
+
+        try:
+            if hasattr(self.memory, "_redis"):
+                return self.memory._redis.delete(key) > 0
+            return False
+        except Exception as e:
+            logger.debug(f"Failed to delete signal {key}: {e}")
+            return False