solace-agent-mesh 0.2.4__py3-none-any.whl → 1.0.1__py3-none-any.whl

solace_agent_mesh/common/services/providers/local_file_identity_service.py

@@ -0,0 +1,148 @@
+"""
+A simple, file-based implementation of the BaseIdentityService.
+Useful for development, testing, or small-scale deployments.
+"""
+
+import json
+from typing import Any, Dict, List, Optional
+
+from solace_ai_connector.common.log import log
+from ..identity_service import BaseIdentityService
+
+
+class LocalFileIdentityService(BaseIdentityService):
+    """
+    Identity service that sources user data from a local JSON file.
+
+    The JSON file should be a list of user profile objects.
+    Example:
+    [
+      {
+        "id": "jdoe",
+        "email": "jane.doe@example.com",
+        "name": "Jane Doe",
+        "title": "Senior Engineer",
+        "manager_id": "ssmith"
+      },
+      ...
+    ]
+    """
+
+    def __init__(self, config: Dict[str, Any]):
+        super().__init__(config)
+        self.file_path = self.config.get("file_path")
+        if not self.file_path:
+            raise ValueError("LocalFileIdentityService config requires 'file_path'.")
+        self.lookup_key = self.config.get("lookup_key", "id")
+        self._load_data()
+
+    def _load_data(self):
+        """Loads and indexes the data from the JSON file."""
+        try:
+            with open(self.file_path, "r", encoding="utf-8") as f:
+                self.all_users: List[Dict[str, Any]] = json.load(f)
+            self.user_index: Dict[str, Dict[str, Any]] = {
+                user.get(self.lookup_key): user
+                for user in self.all_users
+                if user.get(self.lookup_key)
+            }
+            log.info(
+                "%s Loaded and indexed %d users from %s using key '%s'.",
+                self.log_identifier,
+                len(self.user_index),
+                self.file_path,
+                self.lookup_key,
+            )
+        except FileNotFoundError:
+            log.error(
+                "%s Identity file not found at: %s", self.log_identifier, self.file_path
+            )
+            raise
+        except json.JSONDecodeError:
+            log.error(
+                "%s Failed to decode JSON from: %s", self.log_identifier, self.file_path
+            )
+            raise
+        except Exception as e:
+            log.exception("%s Error loading identity file: %s", self.log_identifier, e)
+            raise
+
+    async def get_user_profile(
+        self, auth_claims: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """Looks up a user profile from the in-memory index."""
+        lookup_value = auth_claims.get(self.lookup_key)
+        if not lookup_value:
+            log.warning(
+                "%s Cannot find lookup_key '%s' in auth_claims.",
+                self.log_identifier,
+                self.lookup_key,
+            )
+            return None
+
+        if self.cache:
+            cache_key = f"profile:{lookup_value}"
+            cached_profile = self.cache.get(cache_key)
+            if cached_profile:
+                log.debug(
+                    "%s Returning cached profile for '%s'.",
+                    self.log_identifier,
+                    lookup_value,
+                )
+                return cached_profile
+
+        profile = self.user_index.get(lookup_value)
+
+        if profile and self.cache:
+            self.cache.set(cache_key, profile, ttl=self.cache_ttl)
+            log.debug(
+                "%s Stored profile for '%s' in cache.",
+                self.log_identifier,
+                lookup_value,
+            )
+
+        return profile
+
+    async def search_users(self, query: str, limit: int = 10) -> List[Dict[str, Any]]:
+        """Performs a simple, case-insensitive search on user names and emails."""
+        if not query:
+            return []
+
+        if self.cache:
+            cache_key = f"search:{query}:{limit}"
+            cached_results = self.cache.get(cache_key)
+            if cached_results is not None:
+                log.debug(
+                    "%s Returning cached search results for '%s'.",
+                    self.log_identifier,
+                    query,
+                )
+                return cached_results
+
+        lower_query = query.lower()
+        results = []
+        for user in self.all_users:
+            if len(results) >= limit:
+                break
+            if (
+                lower_query in str(user.get("name", "")).lower()
+                or lower_query in str(user.get("email", "")).lower()
+            ):
+                results.append(
+                    {
+                        "id": user.get("id"),
+                        "name": user.get("name"),
+                        "email": user.get("email"),
+                        "title": user.get("title"),
+                    }
+                )
+
+        if self.cache:
+            self.cache.set(cache_key, results, ttl=min(self.cache_ttl, 60))
+            log.debug(
+                "%s Stored search results for '%s' in cache.",
+                self.log_identifier,
+                query,
+            )
+
+        return results

solace_agent_mesh/common/services/providers/providers_llm.txt

@@ -0,0 +1,113 @@
+## 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`: 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.
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** Initializes the `providers` package.
+**Import:** `from solace_ai_connector.common.services import providers`
+
+This file contains no public classes or functions.
+
+---
+
+### 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`
+
+**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.
+
+**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
+
+# --- Setup: Create a dummy users.json for the example ---
+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
+  }
+]
+file_path = "users.json"
+with open(file_path, "w") as f:
+    json.dump(users_data, f)
+# --- End Setup ---
+
+
+async def main():
+    # 1. Configure the service
+    # The 'file_path' is required. 'lookup_key' is optional (defaults to 'id').
+    config = {
+        "file_path": file_path,
+        "lookup_key": "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' ---")
+    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
+```

solace_agent_mesh/common/services/services_llm.txt

@@ -0,0 +1,132 @@
+## 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. Providers can be either built-in (like the file-based identity service located in the `providers/` subdirectory) or dynamically loaded as external plugins, making the system highly flexible and easy to extend.
+
+## 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.
+- **Subdirectories:**
+  - `providers/`: Contains concrete implementations of the service contracts, such as 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_ai_connector.common.services 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_ai_connector.common.services 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])`**: 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]]) -> 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:** This subdirectory contains concrete implementations of the abstract service classes. It ships with a built-in provider for the `IdentityService` that is useful for development and testing.
+**Key Exports:** `LocalFileIdentityService`
+**Import Examples:**
+```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
+```
+
+## 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.
+
+**Example: Creating a File-Based Identity Service and a Plugin-Based Employee Service**
+
+```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.
+
+async def main():
+    # --- Identity Service Example (using a 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 an 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}")
+
+# To run this example:
+# asyncio.run(main())
+```
+
+### 2. How to Use Functionality from Subdirectories
+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`**
+
+```python
+import asyncio
+from solace_ai_connector.common.services.providers import LocalFileIdentityService
+
+async def main():
+    # Configuration does not need a 'type' key for direct instantiation
+    config = {
+        "file_path": "path/to/your/users.json",
+        "lookup_key": "id"
+    }
+
+    # Instantiate the class directly
+    local_service = LocalFileIdentityService(config)
+    print("LocalFileIdentityService