solace-agent-mesh 1.11.2__py3-none-any.whl

solace_agent_mesh/common/sam_events/__init__.py

@@ -0,0 +1,9 @@
+"""
+SAM Events - System-level event messaging for Solace Agent Mesh.
+
+Provides clean separation between A2A task communication and system events.
+"""
+
+from .event_service import SamEventService, SamEvent, SessionDeletedEvent
+
+__all__ = ["SamEventService", "SamEvent", "SessionDeletedEvent"]

solace_agent_mesh/common/sam_events/event_service.py

@@ -0,0 +1,208 @@
+"""
+SAM Events Service - Clean system-level event messaging.
+
+Provides event publishing and subscription for system events like session lifecycle,
+agent health, configuration changes, etc.
+"""
+
+import logging
+import uuid
+from datetime import datetime, timezone
+from dataclasses import dataclass, asdict
+from typing import Any, Dict, Optional, Callable, List
+
+from ..a2a.protocol import get_sam_events_topic
+
+log = logging.getLogger(__name__)
+
+@dataclass
+class SamEvent:
+    """Base class for all SAM system events."""
+    event_type: str
+    event_id: str
+    timestamp: str
+    source_component: str
+    namespace: str
+    data: Dict[str, Any]
+
+    @classmethod
+    def create(cls, event_type: str, source_component: str, namespace: str, data: Dict[str, Any]) -> "SamEvent":
+        """Create a new SAM event with auto-generated ID and timestamp."""
+        return cls(
+            event_type=event_type,
+            event_id=uuid.uuid4().hex,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            source_component=source_component,
+            namespace=namespace,
+            data=data
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert event to dictionary for messaging."""
+        return asdict(self)
+
+
+@dataclass
+class SessionDeletedEvent(SamEvent):
+    """System event for session deletion."""
+    
+    @classmethod
+    def create(cls, namespace: str, source_component: str, session_id: str, 
+               user_id: str, agent_id: str, gateway_id: str) -> "SessionDeletedEvent":
+        """Create a session deleted event."""
+        data = {
+            "session_id": session_id,
+            "user_id": user_id,
+            "agent_id": agent_id,
+            "gateway_id": gateway_id
+        }
+        return super().create("session.deleted", source_component, namespace, data)
+
+
+class SamEventService:
+    """Service for publishing and subscribing to SAM system events."""
+    
+    def __init__(self, namespace: str, component_name: str, publish_func: Callable[[str, Dict, Optional[Dict]], None]):
+        """
+        Initialize the SAM event service.
+        
+        Args:
+            namespace: The SAM namespace
+            component_name: Name of the component using this service
+            publish_func: Function to publish messages (from WebUIBackendComponent.publish_a2a)
+        """
+        self.namespace = namespace
+        self.component_name = component_name
+        self.publish_func = publish_func
+        self._subscribers: Dict[str, List[Callable]] = {}
+        
+        log.info(f"[SamEventService] Initialized for component {component_name} in namespace {namespace}")
+
+    def publish_event(self, event: SamEvent) -> bool:
+        """
+        Publish a SAM system event.
+        
+        Args:
+            event: The system event to publish
+            
+        Returns:
+            bool: True if published successfully, False otherwise
+        """
+        try:
+            # Extract category and action from event_type (e.g., "session.deleted" -> "session", "deleted")
+            parts = event.event_type.split(".", 1)
+            if len(parts) != 2:
+                raise ValueError(f"Invalid event_type format: {event.event_type}. Expected 'category.action'")
+                
+            category, action = parts
+            topic = get_sam_events_topic(self.namespace, category, action)
+            payload = event.to_dict()
+            
+            log.info(f"[SamEventService] Publishing {event.event_type} event (ID: {event.event_id}) to topic {topic}")
+            
+            # Use the component's publish function (which goes through proper A2A infrastructure)
+            self.publish_func(topic, payload, {"eventType": event.event_type, "eventId": event.event_id})
+            
+            log.info(f"[SamEventService] Successfully published event {event.event_id}")
+            return True
+            
+        except Exception as e:
+            log.error(f"[SamEventService] Failed to publish event {event.event_id}: {e}")
+            return False
+
+    def publish_session_deleted(self, session_id: str, user_id: str, agent_id: str, gateway_id: str) -> bool:
+        """
+        Convenience method to publish session deleted event.
+        
+        Args:
+            session_id: The deleted session ID
+            user_id: The user who owned the session
+            agent_id: The agent that was handling the session
+            gateway_id: The gateway that deleted the session
+            
+        Returns:
+            bool: True if published successfully
+        """
+        event = SessionDeletedEvent.create(
+            namespace=self.namespace,
+            source_component=self.component_name,
+            session_id=session_id,
+            user_id=user_id,
+            agent_id=agent_id,
+            gateway_id=gateway_id
+        )
+        return self.publish_event(event)
+
+    def subscribe_to_events(self, event_type: str, handler: Callable[[SamEvent], None]) -> bool:
+        """
+        Subscribe to system events of a specific type.
+        
+        Args:
+            event_type: The type of events to subscribe to (e.g., "session.deleted")
+            handler: Function to call when event is received
+            
+        Returns:
+            bool: True if subscription was successful
+        """
+        try:
+            if event_type not in self._subscribers:
+                self._subscribers[event_type] = []
+                
+            self._subscribers[event_type].append(handler)
+            
+            log.info(f"[SamEventService] Subscribed to {event_type} events")
+            return True
+            
+        except Exception as e:
+            log.error(f"[SamEventService] Failed to subscribe to {event_type} events: {e}")
+            return False
+
+    def handle_incoming_event(self, topic: str, payload: Dict[str, Any]) -> None:
+        """
+        Handle incoming SAM event from messaging system.
+        
+        Args:
+            topic: The topic the event was received on
+            payload: Event payload
+        """
+        try:
+            event_type = payload.get("event_type")
+            
+            if not event_type:
+                log.warning(f"[SamEventService] Received event without event_type on topic {topic}")
+                return
+                
+            # Create event object
+            event = SamEvent(**payload)
+            
+            # Call registered handlers
+            handlers = self._subscribers.get(event_type, [])
+            for handler in handlers:
+                try:
+                    handler(event)
+                except Exception as e:
+                    log.error(f"[SamEventService] Error in event handler for {event_type}: {e}")
+                    
+            log.debug(f"[SamEventService] Processed event {event.event_id} with {len(handlers)} handlers")
+            
+        except Exception as e:
+            log.error(f"[SamEventService] Error handling event from topic {topic}: {e}")
+
+    @staticmethod
+    def get_event_topic(namespace: str, event_type: str) -> str:
+        """
+        Get the topic for a specific event type.
+        
+        Args:
+            namespace: The SAM namespace  
+            event_type: Event type in format "category.action"
+            
+        Returns:
+            str: The topic for the event
+        """
+        parts = event_type.split(".", 1)
+        if len(parts) != 2:
+            raise ValueError(f"Invalid event_type format: {event_type}. Expected 'category.action'")
+            
+        category, action = parts
+        return get_sam_events_topic(namespace, category, action)

solace_agent_mesh/common/sam_events/sam_events_llm.txt

@@ -0,0 +1,104 @@
+# DEVELOPER GUIDE: sam_events
+
+## Quick Summary
+The `sam_events` directory provides system-level event messaging for Solace Agent Mesh (SAM). It enables clean separation between agent-to-agent (A2A) task communication and system events like session lifecycle, agent health, and configuration changes.
+
+## Files Overview
+- `__init__.py` - Package initialization and public API exports
+- `event_service.py` - Core event service implementation with publishing/subscription capabilities
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** Package entry point that exports the main classes for SAM event handling
+**Import:** `from solace_agent_mesh.common.sam_events import SamEventService, SamEvent, SessionDeletedEvent`
+
+### event_service.py
+**Purpose:** Implements the core event messaging service for system-level events in SAM
+**Import:** `from solace_agent_mesh.common.sam_events.event_service import SamEventService, SamEvent, SessionDeletedEvent`
+
+**Classes:**
+
+- `SamEvent(event_type: str, event_id: str, timestamp: str, source_component: str, namespace: str, data: Dict[str, Any])` - Base class for all SAM system events
+  - `create(event_type: str, source_component: str, namespace: str, data: Dict[str, Any]) -> SamEvent` - Create a new event with auto-generated ID and timestamp
+  - `to_dict() -> Dict[str, Any]` - Convert event to dictionary for messaging
+  - `event_type: str` - Type of event (e.g., "session.deleted")
+  - `event_id: str` - Unique identifier for the event
+  - `timestamp: str` - ISO format timestamp when event was created
+  - `source_component: str` - Component that generated the event
+  - `namespace: str` - SAM namespace
+  - `data: Dict[str, Any]` - Event-specific data payload
+
+- `SessionDeletedEvent(SamEvent)` - Specialized event for session deletion notifications
+  - `create(namespace: str, source_component: str, session_id: str, user_id: str, agent_id: str, gateway_id: str) -> SessionDeletedEvent` - Create a session deleted event
+
+- `SamEventService(namespace: str, component_name: str, publish_func: Callable[[str, Dict, Optional[Dict]], None])` - Service for publishing and subscribing to SAM system events
+  - `publish_event(event: SamEvent) -> bool` - Publish a system event
+  - `publish_session_deleted(session_id: str, user_id: str, agent_id: str, gateway_id: str) -> bool` - Convenience method to publish session deleted event
+  - `subscribe_to_events(event_type: str, handler: Callable[[SamEvent], None]) -> bool` - Subscribe to events of a specific type
+  - `handle_incoming_event(topic: str, payload: Dict[str, Any]) -> None` - Handle incoming events from messaging system
+  - `namespace: str` - The SAM namespace
+  - `component_name: str` - Name of the component using this service
+
+**Functions:**
+
+- `SamEventService.get_event_topic(namespace: str, event_type: str) -> str` - Get the topic for a specific event type
+
+**Usage Examples:**
+
+```python
+# Basic event service setup
+from solace_agent_mesh.common.sam_events import SamEventService, SamEvent, SessionDeletedEvent
+
+# Initialize the event service
+def my_publish_func(topic: str, payload: dict, headers: dict = None):
+    # Your A2A publishing implementation
+    pass
+
+event_service = SamEventService(
+    namespace="my_namespace",
+    component_name="my_component", 
+    publish_func=my_publish_func
+)
+
+# Create and publish a custom event
+custom_event = SamEvent.create(
+    event_type="agent.health_check",
+    source_component="health_monitor",
+    namespace="my_namespace",
+    data={"status": "healthy", "cpu_usage": 45.2}
+)
+success = event_service.publish_event(custom_event)
+
+# Publish a session deleted event (convenience method)
+success = event_service.publish_session_deleted(
+    session_id="sess_123",
+    user_id="user_456", 
+    agent_id="agent_789",
+    gateway_id="gateway_001"
+)
+
+# Subscribe to events
+def handle_session_deleted(event: SamEvent):
+    session_id = event.data["session_id"]
+    print(f"Session {session_id} was deleted")
+
+event_service.subscribe_to_events("session.deleted", handle_session_deleted)
+
+# Handle incoming events (typically called by your messaging infrastructure)
+incoming_payload = {
+    "event_type": "session.deleted",
+    "event_id": "evt_123",
+    "timestamp": "2024-01-01T12:00:00Z",
+    "source_component": "gateway",
+    "namespace": "my_namespace",
+    "data": {"session_id": "sess_123", "user_id": "user_456"}
+}
+event_service.handle_incoming_event("sam/events/session/deleted", incoming_payload)
+
+# Get topic for an event type
+topic = SamEventService.get_event_topic("my_namespace", "session.deleted")
+print(topic)  # Returns the proper SAM events topic
+```
+
+# content_hash: 2a249adbac594bbf8a551a6b4f606218b7b8fce41753efe31954b8acc50cc126

solace_agent_mesh/common/sam_events/sam_events_llm_detail.txt

@@ -0,0 +1,115 @@
+# LLM Summary Detail File
+
+This file is a concatenation of all individual *llm.txt files found in the 'sam_events' directory tree. Each section below corresponds to a specific directory's summary file.
+
+================================================================================
+
+## Section 1: solace_agent_mesh/common/sam_events/sam_events_llm.txt
+
+**Source file:** `solace_agent_mesh/common/sam_events/sam_events_llm.txt`
+
+# DEVELOPER GUIDE: sam_events
+
+## Quick Summary
+The `sam_events` directory provides system-level event messaging for Solace Agent Mesh (SAM). It enables clean separation between agent-to-agent (A2A) task communication and system events like session lifecycle, agent health, and configuration changes.
+
+## Files Overview
+- `__init__.py` - Package initialization and public API exports
+- `event_service.py` - Core event service implementation with publishing/subscription capabilities
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** Package entry point that exports the main classes for SAM event handling
+**Import:** `from solace_agent_mesh.common.sam_events import SamEventService, SamEvent, SessionDeletedEvent`
+
+### event_service.py
+**Purpose:** Implements the core event messaging service for system-level events in SAM
+**Import:** `from solace_agent_mesh.common.sam_events.event_service import SamEventService, SamEvent, SessionDeletedEvent`
+
+**Classes:**
+
+- `SamEvent(event_type: str, event_id: str, timestamp: str, source_component: str, namespace: str, data: Dict[str, Any])` - Base class for all SAM system events
+  - `create(event_type: str, source_component: str, namespace: str, data: Dict[str, Any]) -> SamEvent` - Create a new event with auto-generated ID and timestamp
+  - `to_dict() -> Dict[str, Any]` - Convert event to dictionary for messaging
+  - `event_type: str` - Type of event (e.g., "session.deleted")
+  - `event_id: str` - Unique identifier for the event
+  - `timestamp: str` - ISO format timestamp when event was created
+  - `source_component: str` - Component that generated the event
+  - `namespace: str` - SAM namespace
+  - `data: Dict[str, Any]` - Event-specific data payload
+
+- `SessionDeletedEvent(SamEvent)` - Specialized event for session deletion notifications
+  - `create(namespace: str, source_component: str, session_id: str, user_id: str, agent_id: str, gateway_id: str) -> SessionDeletedEvent` - Create a session deleted event
+
+- `SamEventService(namespace: str, component_name: str, publish_func: Callable[[str, Dict, Optional[Dict]], None])` - Service for publishing and subscribing to SAM system events
+  - `publish_event(event: SamEvent) -> bool` - Publish a system event
+  - `publish_session_deleted(session_id: str, user_id: str, agent_id: str, gateway_id: str) -> bool` - Convenience method to publish session deleted event
+  - `subscribe_to_events(event_type: str, handler: Callable[[SamEvent], None]) -> bool` - Subscribe to events of a specific type
+  - `handle_incoming_event(topic: str, payload: Dict[str, Any]) -> None` - Handle incoming events from messaging system
+  - `namespace: str` - The SAM namespace
+  - `component_name: str` - Name of the component using this service
+
+**Functions:**
+
+- `SamEventService.get_event_topic(namespace: str, event_type: str) -> str` - Get the topic for a specific event type
+
+**Usage Examples:**
+
+```python
+# Basic event service setup
+from solace_agent_mesh.common.sam_events import SamEventService, SamEvent, SessionDeletedEvent
+
+# Initialize the event service
+def my_publish_func(topic: str, payload: dict, headers: dict = None):
+    # Your A2A publishing implementation
+    pass
+
+event_service = SamEventService(
+    namespace="my_namespace",
+    component_name="my_component", 
+    publish_func=my_publish_func
+)
+
+# Create and publish a custom event
+custom_event = SamEvent.create(
+    event_type="agent.health_check",
+    source_component="health_monitor",
+    namespace="my_namespace",
+    data={"status": "healthy", "cpu_usage": 45.2}
+)
+success = event_service.publish_event(custom_event)
+
+# Publish a session deleted event (convenience method)
+success = event_service.publish_session_deleted(
+    session_id="sess_123",
+    user_id="user_456", 
+    agent_id="agent_789",
+    gateway_id="gateway_001"
+)
+
+# Subscribe to events
+def handle_session_deleted(event: SamEvent):
+    session_id = event.data["session_id"]
+    print(f"Session {session_id} was deleted")
+
+event_service.subscribe_to_events("session.deleted", handle_session_deleted)
+
+# Handle incoming events (typically called by your messaging infrastructure)
+incoming_payload = {
+    "event_type": "session.deleted",
+    "event_id": "evt_123",
+    "timestamp": "2024-01-01T12:00:00Z",
+    "source_component": "gateway",
+    "namespace": "my_namespace",
+    "data": {"session_id": "sess_123", "user_id": "user_456"}
+}
+event_service.handle_incoming_event("sam/events/session/deleted", incoming_payload)
+
+# Get topic for an event type
+topic = SamEventService.get_event_topic("my_namespace", "session.deleted")
+print(topic)  # Returns the proper SAM events topic
+```
+
+================================================================================
+

solace_agent_mesh/common/services/__init__.py

@@ -0,0 +1,4 @@
+"""
+This package contains shared, reusable services for the Solace AI Connector,
+such as the IdentityService.
+"""

solace_agent_mesh/common/services/employee_service.py

@@ -0,0 +1,164 @@
+"""
+Defines the abstract base class and factory for creating Employee Service providers.
+"""
+
+import logging
+import importlib
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+import importlib.metadata as metadata
+
+
+from ..utils.in_memory_cache import InMemoryCache
+import pandas as pd
+
+log = logging.getLogger(__name__)
+
+class BaseEmployeeService(ABC):
+    """
+    Abstract base class for Employee Service providers.
+
+    This class defines a "thin provider" contract. Implementations should focus
+    solely on fetching data from a source system (like an HR platform) and
+    mapping it to the canonical format. All complex business logic, such as
+    building organizational charts or calculating availability schedules, should
+    be handled by the tools that consume this service.
+
+    Canonical Employee Schema
+    This schema defines the standard fields that all EmployeeService providers should aim to return.
+    - id (string): A unique, stable, and lowercase identifier for the employee (e.g., email, GUID).
+    - displayName (string): The employee's full name for display purposes.
+    - workEmail (string): The employee's primary work email address.
+    - jobTitle (string): The employee's official job title.
+    - department (string): The department the employee belongs to.
+    - location (string): The physical or regional location of the employee.
+    - supervisorId (string): The unique id of the employee's direct manager.
+    - hireDate (string): The date the employee was hired (ISO 8601: YYYY-MM-DD).
+    - mobilePhone (string): The employee's mobile phone number (optional).
+
+    """
+
+    def __init__(self, config: Dict[str, Any]):
+        """
+        Initializes the service with its specific configuration block.
+
+        Args:
+            config: The dictionary of configuration parameters for this provider.
+        """
+        self.config = config
+        self.log_identifier = f"[{self.__class__.__name__}]"
+        self.cache_ttl = config.get("cache_ttl_seconds", 3600)
+        self.cache = InMemoryCache() if self.cache_ttl > 0 else None
+        log.info(
+            "%s Initialized. Cache TTL: %d seconds.",
+            self.log_identifier,
+            self.cache_ttl,
+        )
+
+    @abstractmethod
+    async def get_employee_dataframe(self) -> pd.DataFrame:
+        """Returns the entire employee directory as a pandas DataFrame."""
+        pass
+
+    @abstractmethod
+    async def get_employee_profile(self, employee_id: str) -> Optional[Dict[str, Any]]:
+        """Fetches the profile for a single employee."""
+        pass
+
+    @abstractmethod
+    async def get_time_off_data(self, employee_id: str, start_date: Optional[str] = None, end_date: Optional[str] = None) -> List[Dict[str, Any]]:
+        """
+        Retrieves a list of raw time-off entries for an employee.
+
+        The tool consuming this data is responsible for interpreting it.
+        Each dictionary in the list MUST contain the following keys:
+        - 'start' (str): The start date of the leave (YYYY-MM-DD).
+        - 'end' (str): The end date of the leave (YYYY-MM-DD).
+        - 'type' (str): The category of leave (e.g., 'Vacation', 'Sick', 'Holiday').
+        - 'amount' (str): The amount of time taken, must be one of 'full_day' or 'half_day'.
+
+        Example:
+        [
+            {'start': '2025-07-04', 'end': '2025-07-04', 'type': 'Holiday', 'amount': 'full_day'},
+            {'start': '2025-08-15', 'end': '2025-08-15', 'type': 'Vacation', 'amount': 'full_day'}
+        ]
+
+        Args:
+            employee_id: The unique identifier for the employee.
+
+        Returns:
+            A list of dictionaries, each representing a time-off entry.
+        """
+        pass
+
+    @abstractmethod
+    async def get_employee_profile_picture(self, employee_id: str) -> Optional[str]:
+        """
+        Fetches an employee's profile picture and returns it as a data URI.
+
+        Args:
+            employee_id: The unique identifier for the employee.
+
+        Returns:
+            A string containing the data URI (e.g., 'data:image/jpeg;base64,...')
+            or None if not available.
+        """
+        pass
+
+
+def create_employee_service(
+    config: Optional[Dict[str, Any]],
+) -> Optional[BaseEmployeeService]:
+    """
+    Factory function to create an instance of an Employee Service provider
+    based on the provided configuration.
+    """
+    if not config:
+        log.info(
+            "[EmployeeFactory] No 'employee_service' configuration found. Skipping creation."
+        )
+        return None
+
+    provider_type = config.get("type")
+    if not provider_type:
+        raise ValueError("Employee service config must contain a 'type' key.")
+
+    log.info(
+        f"[EmployeeFactory] Attempting to create employee service of type: {provider_type}"
+    )
+
+    try:
+        entry_points = metadata.entry_points(group="solace_agent_mesh.plugins")
+        provider_info_entry = next(
+            (ep for ep in entry_points if ep.name == provider_type), None
+        )
+
+        if not provider_info_entry:
+            raise ValueError(
+                f"No plugin provider found for type '{provider_type}' under the 'solace_agent_mesh.plugins' entry point."
+            )
+
+        provider_info = provider_info_entry.load()
+        class_path = provider_info.get("class_path")
+        if not class_path:
+            raise ValueError(
+                f"Plugin '{provider_type}' is missing 'class_path' in its info dictionary."
+            )
+
+        module_path, class_name = class_path.rsplit(".", 1)
+        module = importlib.import_module(module_path)
+        provider_class = getattr(module, class_name)
+
+        if not issubclass(provider_class, BaseEmployeeService):
+            raise TypeError(
+                f"Provider class '{class_path}' does not inherit from BaseEmployeeService."
+            )
+
+        log.info(f"Successfully loaded employee provider plugin: {provider_type}")
+        return provider_class(config)
+    except (ImportError, AttributeError, TypeError, ValueError) as e:
+        log.exception(
+            f"[EmployeeFactory] Failed to load employee provider plugin '{provider_type}'. "
+            "Ensure the plugin is installed and the entry point is correct."
+        )
+        raise ValueError(f"Could not load employee provider plugin: {e}") from e