solace-agent-mesh 1.0.8__py3-none-any.whl → 1.1.0__py3-none-any.whl

solace_agent_mesh/common/services/providers/providers_llm.txt

@@ -2,112 +2,79 @@
 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`: Marks the directory as a Python package.
-- `local_file_identity_service.py`: An identity service implementation that reads user data from a local JSON file.
+- `__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_ai_connector.common.services import providers`
+**Purpose:** Initializes the providers package
+**Import:** `from solace_agent_mesh.common.services import providers`
 
-This file contains no public classes or functions.
-
----
+This file contains no public classes or functions - it serves only as package documentation.
 
 ### local_file_identity_service.py
-**Purpose:** Provides a simple, file-based identity service that reads user profiles from a local JSON file. It's ideal for development, testing, or small-scale deployments where a full-fledged identity provider is not available.
-**Import:** `from solace_ai_connector.common.services.providers.local_file_identity_service import LocalFileIdentityService`
+**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])` - An identity service that sources user data from a local JSON file. The `config` dictionary must contain a `file_path` key.
-  - `async get_user_profile(auth_claims: Dict[str, Any]) -> Optional[Dict[str, Any]]` - Looks up a user profile from the in-memory index. The lookup is performed using the `lookup_key` (configured during initialization) present in the `auth_claims` dictionary.
-  - `async search_users(query: str, limit: int = 10) -> List[Dict[str, Any]]` - Performs a simple, case-insensitive search across user names and emails. Returns a list of matching user profiles.
-  - `file_path: str` - The path to the JSON file containing the user data.
-  - `lookup_key: str` - The key within the user profile objects and `auth_claims` used to identify a user. Defaults to `"id"`.
-  - `all_users: List[Dict[str, Any]]` - The complete list of all user profiles loaded from the file.
-  - `user_index: Dict[str, Dict[str, Any]]` - An in-memory dictionary mapping the `lookup_key` value to the corresponding user profile for fast lookups.
+- `LocalFileIdentityService(config: Dict[str, Any])` - 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
-import os
-from typing import Dict, Any, Optional, List
-
-# Assume this is the identity service class from the file
-from solace_ai_connector.common.services.providers.local_file_identity_service import LocalFileIdentityService
+from solace_agent_mesh.common.services.providers.local_file_identity_service import LocalFileIdentityService
 
-# --- Setup: Create a dummy users.json for the example ---
+# 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",
-    "manager_id": None
-  }
+    {
+        "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"
+    }
 ]
-file_path = "users.json"
-with open(file_path, "w") as f:
-    json.dump(users_data, f)
-# --- End Setup ---
 
+with open("users.json", "w") as f:
+    json.dump(users_data, f)
 
 async def main():
-    # 1. Configure the service
-    # The 'file_path' is required. 'lookup_key' is optional (defaults to 'id').
+    # Initialize the service
     config = {
-        "file_path": file_path,
-        "lookup_key": "id"
+        "file_path": "users.json",
+        "lookup_key": "id"  # Optional, defaults to "id"
     }
-
-    # 2. Initialize the service
+    
     identity_service = LocalFileIdentityService(config)
-    print(f"Service initialized. Loaded {len(identity_service.all_users)} users.")
-
-    # 3. Get a specific user profile
-    print("\n--- Getting user profile for id 'jdoe' ---")
+    
+    # Get user profile by ID
     auth_claims = {"id": "jdoe"}
     profile = await identity_service.get_user_profile(auth_claims)
-    if profile:
-        print(f"Found profile: {profile}")
-    else:
-        print("Profile not found.")
-
-    # 4. Search for users by name
-    print("\n--- Searching for users with 'sam' in their name ---")
-    search_results = await identity_service.search_users(query="sam", limit=5)
-    print(f"Found {len(search_results)} user(s): {search_results}")
-
-    # 5. Handle a case where the user is not found
-    print("\n--- Getting user profile for non-existent id 'nobody' ---")
-    not_found_profile = await identity_service.get_user_profile({"id": "nobody"})
-    print(f"Profile for 'nobody': {not_found_profile}")
-
-
-if __name__ == "__main__":
-    asyncio.run(main())
-    # Clean up the dummy file
-    os.remove(file_path)
-
-# Expected output:
-#
-# Service initialized. Loaded 2 users.
-#
-# --- Getting user profile for id 'jdoe' ---
-# Found profile: {'id': 'jdoe', 'email': 'jane.doe@example.com', 'name': 'Jane Doe', 'title': 'Senior Engineer', 'manager_id': 'ssmith'}
-#
-# --- Searching for users with 'sam' in their name ---
-# Found 1 user(s): [{'id': 'ssmith', 'name': 'Sam Smith', 'email': 'sam.smith@example.com', 'title': 'Engineering Manager'}]
-#
-# --- Getting user profile for non-existent id 'nobody' ---
-# Profile for 'nobody': None
-```
+    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: 3661ffe07466b1391797c2feb90e2c97544b1a9c6c8cd15fc448cf95f4be6015

solace_agent_mesh/common/services/services_llm.txt

@@ -1,3 +1,5 @@
+# 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.
 
@@ -5,11 +7,11 @@ The core architecture revolves around factory functions (`create_identity_servic
 
 ## Files and Subdirectories Overview
 - **Direct files:**
-  - `__init__.py`: Marks the directory as a Python package.
-  - `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.
+  - `__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, such as a file-based identity provider.
+  - `providers/`: Contains concrete implementations of the service contracts, including a file-based identity provider
 
 ## Developer API Reference
 
@@ -17,7 +19,7 @@ The core architecture revolves around factory functions (`create_identity_servic
 
 #### 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_ai_connector.common.services import BaseEmployeeService, create_employee_service`
+**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.
@@ -30,7 +32,7 @@ The core architecture revolves around factory functions (`create_identity_servic
 
 #### 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_ai_connector.common.services import BaseIdentityService, create_identity_service`
+**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.
@@ -48,26 +50,23 @@ The core architecture revolves around factory functions (`create_identity_servic
 ```python
 # Typically, you would use the factory function.
 # But for direct instantiation (e.g., in tests), you can do this:
-from solace_ai_connector.common.services.providers import LocalFileIdentityService
+from solace_agent_mesh.common.services.providers.local_file_identity_service import LocalFileIdentityService
 ```
 
 ## Complete Usage Guide
-The following examples demonstrate how to use the services framework, from basic instantiation using factories to creating custom providers.
 
-### 1. How to Use the Service Factories (Recommended)
-The factories are the primary way to create and use services. They abstract away the specific implementation details.
+### 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 a File-Based Identity Service and a Plugin-Based Employee Service**
+**Example: Creating Identity and Employee Services**
 
 ```python
 import asyncio
-from solace_ai_connector.common.services import create_identity_service, create_employee_service
-
-# Assume you have a users.json file for the identity service
-# and a plugin installed for the employee service.
+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 a built-in provider) ---
+    # --- Identity Service Example (using built-in provider) ---
     identity_config = {
         "type": "local_file",
         "file_path": "path/to/your/users.json",
@@ -87,8 +86,8 @@ async def main():
         search_results = await identity_service.search_users("Jane")
         print(f"Search Results: {search_results}")
 
-    # --- Employee Service Example (using an external plugin) ---
-    # The 'type' must match the name of a registered plugin entry point.
+    # --- 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",
@@ -107,26 +106,207 @@ async def main():
         time_off = await employee_service.get_time_off_data("jane.doe@example.com")
         print(f"Time Off Data: {time_off}")
 
-# To run this example:
-# asyncio.run(main())
+        # 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. How to Use Functionality from Subdirectories
+### 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 Instantiation of `LocalFileIdentityService`**
+**Example: Direct Use of LocalFileIdentityService**
 
 ```python
 import asyncio
-from solace_ai_connector.common.services.providers import LocalFileIdentityService
+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": "path/to/your/users.json",
-        "lookup_key": "id"
+        "file_path": "users.json",
+        "lookup_key": "id",
+        "cache_ttl_seconds": 1800
     }
 
     # Instantiate the class directly
     local_service = LocalFileIdentityService(config)
-    print("LocalFileIdentityService
+    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())
+```
+
+This comprehensive guide shows how the services framework provides a clean, extensible way to integrate various data sources while maintaining consistent interfaces and supporting both built-in providers and external plugins.
+
+# content_hash: 63457e2c72256810f713e62325c1601a675951fe47c1121a647c404690179206

solace_agent_mesh/common/utils/artifact_utils.py

@@ -0,0 +1,29 @@
+"""
+Common utility functions for working with ADK artifacts.
+"""
+
+from typing import Optional
+from google.adk.artifacts import BaseArtifactService
+from solace_ai_connector.common.log import log
+
+
+async def get_latest_artifact_version(
+    artifact_service: BaseArtifactService,
+    app_name: str,
+    user_id: str,
+    session_id: str,
+    filename: str,
+) -> Optional[int]:
+    """Resolves the latest version number for a given artifact."""
+    try:
+        versions = await artifact_service.list_artifact_versions(
+            app_name=app_name,
+            user_id=user_id,
+            session_id=session_id,
+            filename=filename,
+        )
+        if versions:
+            return max(versions)
+    except Exception as e:
+        log.error(f"Error listing versions for artifact '{filename}': {e}")
+    return None