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

solace_agent_mesh/common/sam_events/sam_events_llm_detail.txt

@@ -1,115 +0,0 @@
-# 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/providers/providers_llm.txt

@@ -1,81 +0,0 @@
-## Quick Summary
-This directory contains concrete implementations (providers) for the abstract services defined in the parent `services` package. These providers offer specific ways to fulfill service contracts, such as sourcing user identity information from a local file.
-
-## Files Overview
-- `__init__.py` - Package initialization file marking the directory as a Python package
-- `local_file_identity_service.py` - File-based identity service implementation that reads user data from local JSON files
-
-## Developer API Reference
-
-### __init__.py
-**Purpose:** Initializes the providers package
-**Import:** `from solace_agent_mesh.common.services import providers`
-
-This file contains no public classes or functions - it serves only as package documentation.
-
-### local_file_identity_service.py
-**Purpose:** Provides a file-based identity service that reads user profiles from a local JSON file, ideal for development, testing, or small-scale deployments
-**Import:** `from solace_agent_mesh.common.services.providers.local_file_identity_service import LocalFileIdentityService`
-
-**Classes:**
-- `LocalFileIdentityService(config: Dict[str, Any], component: Optional[SamComponentBase] = None)` - Identity service that sources user data from a local JSON file
-  - `async get_user_profile(auth_claims: Dict[str, Any]) -> Optional[Dict[str, Any]]` - Looks up a user profile using the lookup key from auth claims
-  - `async search_users(query: str, limit: int = 10) -> List[Dict[str, Any]]` - Performs case-insensitive search on user names and emails
-  - `file_path: str` - Path to the JSON file containing user data
-  - `lookup_key: str` - Key used to identify users (defaults to "id")
-  - `all_users: List[Dict[str, Any]]` - Complete list of user profiles loaded from file
-  - `user_index: Dict[str, Dict[str, Any]]` - In-memory index mapping lookup keys to user profiles
-
-**Usage Examples:**
-```python
-import asyncio
-import json
-from typing import Dict, Any
-from solace_agent_mesh.common.services.providers.local_file_identity_service import LocalFileIdentityService
-
-# Create sample users.json file
-users_data = [
-    {
-        "id": "jdoe",
-        "email": "jane.doe@example.com", 
-        "name": "Jane Doe",
-        "title": "Senior Engineer",
-        "manager_id": "ssmith"
-    },
-    {
-        "id": "ssmith",
-        "email": "sam.smith@example.com",
-        "name": "Sam Smith", 
-        "title": "Engineering Manager"
-    }
-]
-
-with open("users.json", "w") as f:
-    json.dump(users_data, f)
-
-async def main():
-    # Initialize the service
-    config = {
-        "file_path": "users.json",
-        "lookup_key": "id"  # Optional, defaults to "id"
-    }
-    
-    identity_service = LocalFileIdentityService(config)
-    
-    # Get user profile by ID
-    auth_claims = {"id": "jdoe"}
-    profile = await identity_service.get_user_profile(auth_claims)
-    print(f"User profile: {profile}")
-    
-    # Search for users
-    results = await identity_service.search_users("jane", limit=5)
-    print(f"Search results: {results}")
-    
-    # Handle missing user
-    missing = await identity_service.get_user_profile({"id": "nonexistent"})
-    print(f"Missing user: {missing}")  # Returns None
-
-asyncio.run(main())
-```
-
-# content_hash: 26b677e947bf60f1e211b6e119bf6382f0a269d46c0f102751bae9faab3c8435

solace_agent_mesh/common/services/services_llm.txt

@@ -1,368 +0,0 @@
-# DEVELOPER GUIDE: services
-
-## Quick Summary
-The `services` directory provides a modular and extensible framework for integrating external data sources related to identity and employee information into the Solace AI Connector. It is built on a provider pattern, defining abstract base classes (`BaseIdentityService`, `BaseEmployeeService`) that establish a clear contract for what data and functionality a service must provide.
-
-The core architecture revolves around factory functions (`create_identity_service`, `create_employee_service`) that instantiate specific service providers based on a configuration dictionary. This allows the application to remain decoupled from the concrete implementations. The `providers/` subdirectory contains concrete implementations, including a built-in file-based identity service, while external providers can be dynamically loaded as plugins through Python's entry points system.
-
-## Files and Subdirectories Overview
-- **Direct files:**
-  - `__init__.py`: Marks the directory as a Python package with shared, reusable services
-  - `employee_service.py`: Defines the abstract contract and factory for employee data services
-  - `identity_service.py`: Defines the abstract contract and factory for user identity services
-- **Subdirectories:**
-  - `providers/`: Contains concrete implementations of the service contracts, including a file-based identity provider
-
-## Developer API Reference
-
-### Direct Files
-
-#### employee_service.py
-**Purpose:** Defines the abstract base class (`BaseEmployeeService`) that all employee service providers must implement, and a factory function (`create_employee_service`) to instantiate them. It enforces a canonical schema for employee data to ensure consistency across different providers.
-**Import:** `from solace_agent_mesh.common.services.employee_service import BaseEmployeeService, create_employee_service`
-
-**Classes/Functions/Constants:**
-- **`class BaseEmployeeService(ABC)`**: The abstract base class for employee service providers.
-    - **`__init__(self, config: Dict[str, Any])`**: Initializes the service, setting up configuration and an optional in-memory cache.
-    - **`async def get_employee_dataframe(self) -> pd.DataFrame`**: (Abstract) Returns the entire employee directory as a pandas DataFrame.
-    - **`async def get_employee_profile(self, employee_id: str) -> Optional[Dict[str, Any]]`**: (Abstract) Fetches the profile for a single employee, conforming to the canonical schema.
-    - **`async def get_time_off_data(self, employee_id: str) -> List[Dict[str, Any]]`**: (Abstract) Retrieves a list of time-off entries for an employee.
-    - **`async def get_employee_profile_picture(self, employee_id: str) -> Optional[str]`**: (Abstract) Fetches an employee's profile picture as a data URI string.
-- **`def create_employee_service(config: Optional[Dict[str, Any]]) -> Optional[BaseEmployeeService]`**: A factory function that dynamically loads and instantiates an employee service provider based on the `type` specified in the configuration. It primarily uses Python's entry points to find and load external plugins.
-
-#### identity_service.py
-**Purpose:** Defines the abstract base class (`BaseIdentityService`) for identity providers and a factory function (`create_identity_service`) to create instances of them. This service is used for user lookups and profile enrichment.
-**Import:** `from solace_agent_mesh.common.services.identity_service import BaseIdentityService, create_identity_service`
-
-**Classes/Functions/Constants:**
-- **`class BaseIdentityService(ABC)`**: The abstract base class for identity service providers.
-    - **`__init__(self, config: Dict[str, Any], component: Optional[SamComponentBase] = None)`**: Initializes the service, setting up configuration and an optional in-memory cache.
-    - **`async def get_user_profile(self, auth_claims: Dict[str, Any]) -> Optional[Dict[str, Any]]`**: (Abstract) Fetches additional profile details for an authenticated user based on claims.
-    - **`async def search_users(self, query: str, limit: int = 10) -> List[Dict[str, Any]]`**: (Abstract) Searches for users based on a query string (e.g., for autocomplete).
-- **`def create_identity_service(config: Optional[Dict[str, Any]], component: Optional[SamComponentBase] = None) -> Optional[BaseIdentityService]`**: A factory function that instantiates an identity service provider. It has special handling for the built-in `local_file` provider and uses Python entry points for all other provider types.
-
-### Subdirectory APIs
-
-#### providers/
-**Purpose:** Contains concrete implementations of the abstract service classes, providing specific ways to fulfill service contracts such as sourcing user identity information from local files
-**Key Exports:** `LocalFileIdentityService`
-**Import Examples:**
-```python
-from solace_agent_mesh.common.services.providers.local_file_identity_service import LocalFileIdentityService
-```
-
-## Complete Usage Guide
-
-### 1. Using Service Factories (Recommended Approach)
-The factories are the primary way to create and use services. They abstract away the specific implementation details and handle plugin loading.
-
-**Example: Creating Identity and Employee Services**
-
-```python
-import asyncio
-from solace_agent_mesh.common.services.identity_service import create_identity_service
-from solace_agent_mesh.common.services.employee_service import create_employee_service
-
-async def main():
-    # --- Identity Service Example (using built-in provider) ---
-    identity_config = {
-        "type": "local_file",
-        "file_path": "path/to/your/users.json",
-        "lookup_key": "email",  # Key to use for lookups from auth_claims
-        "cache_ttl_seconds": 3600
-    }
-    identity_service = create_identity_service(identity_config)
-
-    if identity_service:
-        print("Identity Service created.")
-        # Fetch a user profile
-        auth_claims = {"email": "jane.doe@example.com"}
-        user_profile = await identity_service.get_user_profile(auth_claims)
-        print(f"User Profile: {user_profile}")
-
-        # Search for users
-        search_results = await identity_service.search_users("Jane")
-        print(f"Search Results: {search_results}")
-
-    # --- Employee Service Example (using external plugin) ---
-    # The 'type' must match the name of a registered plugin entry point
-    employee_config = {
-        "type": "bamboohr_plugin",
-        "api_key": "your-secret-api-key",
-        "subdomain": "your-company",
-        "cache_ttl_seconds": 7200
-    }
-    employee_service = create_employee_service(employee_config)
-
-    if employee_service:
-        print("\nEmployee Service created.")
-        # Get a detailed employee profile
-        employee_profile = await employee_service.get_employee_profile("jane.doe@example.com")
-        print(f"Employee Profile: {employee_profile}")
-
-        # Get time off data
-        time_off = await employee_service.get_time_off_data("jane.doe@example.com")
-        print(f"Time Off Data: {time_off}")
-
-        # Get employee directory as DataFrame
-        df = await employee_service.get_employee_dataframe()
-        print(f"Employee Directory Shape: {df.shape}")
-
-# Run the example
-asyncio.run(main())
-```
-
-### 2. Direct Provider Instantiation
-While factories are preferred, you can instantiate providers from the `providers/` directory directly. This is useful for testing or when you know you will always use a specific built-in provider.
-
-**Example: Direct Use of LocalFileIdentityService**
-
-```python
-import asyncio
-import json
-from solace_agent_mesh.common.services.providers.local_file_identity_service import LocalFileIdentityService
-
-async def main():
-    # First, create a sample users.json file
-    users_data = [
-        {
-            "id": "jdoe",
-            "email": "jane.doe@example.com", 
-            "name": "Jane Doe",
-            "title": "Senior Engineer",
-            "manager_id": "ssmith"
-        },
-        {
-            "id": "ssmith",
-            "email": "sam.smith@example.com",
-            "name": "Sam Smith", 
-            "title": "Engineering Manager"
-        }
-    ]
-
-    with open("users.json", "w") as f:
-        json.dump(users_data, f)
-
-    # Configuration does not need a 'type' key for direct instantiation
-    config = {
-        "file_path": "users.json",
-        "lookup_key": "id",
-        "cache_ttl_seconds": 1800
-    }
-
-    # Instantiate the class directly
-    local_service = LocalFileIdentityService(config)
-    print("LocalFileIdentityService created directly")
-
-    # Get user profile by ID
-    auth_claims = {"id": "jdoe"}
-    profile = await local_service.get_user_profile(auth_claims)
-    print(f"User profile: {profile}")
-    
-    # Search for users
-    results = await local_service.search_users("jane", limit=5)
-    print(f"Search results: {results}")
-
-asyncio.run(main())
-```
-
-### 3. Creating Custom Service Providers
-To create your own service provider, inherit from the appropriate base class and implement all abstract methods.
-
-**Example: Custom Employee Service Provider**
-
-```python
-import pandas as pd
-from typing import Any, Dict, List, Optional
-from solace_agent_mesh.common.services.employee_service import BaseEmployeeService
-
-class CustomEmployeeService(BaseEmployeeService):
-    """Custom employee service that connects to your HR system."""
-    
-    def __init__(self, config: Dict[str, Any]):
-        super().__init__(config)
-        self.api_endpoint = config.get("api_endpoint")
-        self.api_key = config.get("api_key")
-    
-    async def get_employee_dataframe(self) -> pd.DataFrame:
-        """Fetch all employees and return as DataFrame."""
-        # Your implementation here
-        # This should return a DataFrame with canonical schema columns:
-        # id, displayName, workEmail, jobTitle, department, location, supervisorId, hireDate, mobilePhone
-        employees_data = [
-            {
-                "id": "jdoe@company.com",
-                "displayName": "Jane Doe",
-                "workEmail": "jdoe@company.com",
-                "jobTitle": "Software Engineer",
-                "department": "Engineering",
-                "location": "San Francisco",
-                "supervisorId": "manager@company.com",
-                "hireDate": "2023-01-15",
-                "mobilePhone": "+1-555-0123"
-            }
-        ]
-        return pd.DataFrame(employees_data)
-    
-    async def get_employee_profile(self, employee_id: str) -> Optional[Dict[str, Any]]:
-        """Get single employee profile."""
-        # Your implementation here
-        return {
-            "id": employee_id,
-            "displayName": "Jane Doe",
-            "workEmail": employee_id,
-            "jobTitle": "Software Engineer"
-        }
-    
-    async def get_time_off_data(self, employee_id: str) -> List[Dict[str, Any]]:
-        """Get employee time off data."""
-        # Your implementation here
-        return [
-            {
-                'start': '2025-07-04',
-                'end': '2025-07-04',
-                'type': 'Holiday',
-                'amount': 'full_day'
-            }
-        ]
-    
-    async def get_employee_profile_picture(self, employee_id: str) -> Optional[str]:
-        """Get employee profile picture as data URI."""
-        # Your implementation here
-        return None  # or return "data:image/jpeg;base64,..."
-
-# Usage
-async def use_custom_service():
-    config = {
-        "api_endpoint": "https://your-hr-api.com",
-        "api_key": "your-api-key",
-        "cache_ttl_seconds": 3600
-    }
-    
-    service = CustomEmployeeService(config)
-    profile = await service.get_employee_profile("jdoe@company.com")
-    print(f"Custom service profile: {profile}")
-```
-
-### 4. Working with Both Services Together
-Often you'll want to use both identity and employee services together for comprehensive user information.
-
-**Example: Combined Service Usage**
-
-```python
-import asyncio
-from solace_agent_mesh.common.services.identity_service import create_identity_service
-from solace_agent_mesh.common.services.employee_service import create_employee_service
-
-async def get_complete_user_info(user_email: str):
-    """Get comprehensive user information from both services."""
-    
-    # Configure services
-    identity_config = {
-        "type": "local_file",
-        "file_path": "users.json",
-        "lookup_key": "email"
-    }
-    
-    employee_config = {
-        "type": "your_hr_plugin",
-        "api_key": "your-key"
-    }
-    
-    # Create services
-    identity_service = create_identity_service(identity_config)
-    employee_service = create_employee_service(employee_config)
-    
-    # Gather information
-    user_info = {}
-    
-    if identity_service:
-        auth_claims = {"email": user_email}
-        identity_profile = await identity_service.get_user_profile(auth_claims)
-        if identity_profile:
-            user_info.update(identity_profile)
-    
-    if employee_service:
-        employee_profile = await employee_service.get_employee_profile(user_email)
-        if employee_profile:
-            user_info.update(employee_profile)
-            
-        # Get additional employee data
-        time_off = await employee_service.get_time_off_data(user_email)
-        user_info["time_off"] = time_off
-        
-        profile_pic = await employee_service.get_employee_profile_picture(user_email)
-        if profile_pic:
-            user_info["profile_picture"] = profile_pic
-    
-    return user_info
-
-# Usage
-async def main():
-    complete_info = await get_complete_user_info("jane.doe@example.com")
-    print(f"Complete user information: {complete_info}")
-
-asyncio.run(main())
-```
-
-### 5. Using the Built-in LocalFileIdentityService
-The `providers/` subdirectory includes a ready-to-use file-based identity service that's perfect for development and testing.
-
-**Example: Setting up LocalFileIdentityService with Factory**
-
-```python
-import asyncio
-import json
-from solace_agent_mesh.common.services.identity_service import create_identity_service
-
-async def setup_file_based_identity():
-    # Create sample users.json file
-    users_data = [
-        {
-            "id": "jdoe",
-            "email": "jane.doe@example.com", 
-            "name": "Jane Doe",
-            "title": "Senior Engineer",
-            "manager_id": "ssmith"
-        },
-        {
-            "id": "ssmith",
-            "email": "sam.smith@example.com",
-            "name": "Sam Smith", 
-            "title": "Engineering Manager"
-        }
-    ]
-
-    with open("users.json", "w") as f:
-        json.dump(users_data, f)
-
-    # Use factory to create the service
-    config = {
-        "type": "local_file",  # This triggers the built-in provider
-        "file_path": "users.json",
-        "lookup_key": "email",  # Use email for lookups
-        "cache_ttl_seconds": 3600
-    }
-    
-    identity_service = create_identity_service(config)
-    
-    # Test the service
-    auth_claims = {"email": "jane.doe@example.com"}
-    profile = await identity_service.get_user_profile(auth_claims)
-    print(f"Profile found: {profile}")
-    
-    # Search functionality
-    search_results = await identity_service.search_users("jane")
-    print(f"Search results: {search_results}")
-
-asyncio.run(setup_file_based_identity())
-```
-
-### 6. Advanced Usage: Custom Identity Service with Component Integration
-
-```python
-import asyncio
-from typing import Any, Dict, List, Optional
-from solace_agent
-
-# content_hash: 4532aa73f5067694fc253bc1875f79148f7b8778d1d46680c423d2b3da8456e6