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

solace_agent_mesh/common/services/identity_service.py

@@ -0,0 +1,134 @@
+"""
+Defines the abstract base class and factory for creating Identity 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
+from ..sac.sam_component_base import SamComponentBase
+
+log = logging.getLogger(__name__)
+
+class BaseIdentityService(ABC):
+    """Abstract base class for all Identity Service providers."""
+
+    def __init__(self, config: Dict[str, Any], component: Optional[SamComponentBase] = None):
+        """
+        Initializes the service with its specific configuration block.
+
+        Args:
+            config: The dictionary of configuration parameters for this provider.
+        """
+        self.config = config
+        self.component = component
+        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_user_profile(
+        self, auth_claims: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Fetches additional profile details for an already authenticated user.
+
+        Args:
+            auth_claims: A dictionary of claims from the primary authentication
+                         system (e.g., decoded JWT, session data). It's guaranteed
+                         to contain at least a primary user identifier.
+            kwargs: Optional additional parameters for provider-specific logic.
+
+        Returns:
+            A dictionary containing additional user details (e.g., title, manager)
+            or None if the user is not found in this identity system.
+        """
+        pass
+
+    @abstractmethod
+    async def search_users(self, query: str, limit: int = 10) -> List[Dict[str, Any]]:
+        """
+        Searches for users based on a query string for autocomplete.
+
+        Args:
+            query: The partial name or email to search for.
+            limit: The maximum number of results to return.
+
+        Returns:
+            A list of dictionaries, each containing basic user info
+            (e.g., id, name, email, title).
+        """
+        pass
+
+
+def create_identity_service(
+    config: Optional[Dict[str, Any]],
+    component: Optional[SamComponentBase] = None,
+) -> Optional[BaseIdentityService]:
+    """
+    Factory function to create an instance of an Identity Service provider
+    based on the provided configuration.
+    """
+    if not config:
+        log.info(
+            "[IdentityFactory] No 'identity_service' configuration found. Skipping creation."
+        )
+        return None
+
+    provider_type = config.get("type")
+    if not provider_type:
+        raise ValueError("Identity service config must contain a 'type' key.")
+
+    log.info(
+        f"[IdentityFactory] Attempting to create identity service of type: {provider_type}"
+    )
+
+    if provider_type == "local_file":
+        from .providers.local_file_identity_service import LocalFileIdentityService
+
+        return LocalFileIdentityService(config, component)
+
+    else:
+        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, BaseIdentityService):
+                raise TypeError(
+                    f"Provider class '{class_path}' does not inherit from BaseIdentityService."
+                )
+
+            log.info(f"Successfully loaded identity provider plugin: {provider_type}")
+            return provider_class(config, component)
+        except (ImportError, AttributeError, TypeError, ValueError) as e:
+            log.exception(
+                f"[IdentityFactory] Failed to load identity provider plugin '{provider_type}'. "
+                "Ensure the plugin is installed and the entry point is correct."
+            )
+            raise ValueError(f"Could not load identity provider plugin: {e}") from e

solace_agent_mesh/common/services/providers/__init__.py

@@ -0,0 +1,4 @@
+"""
+This package contains concrete implementations (providers) for the services
+defined in the parent 'services' package.
+"""

solace_agent_mesh/common/services/providers/local_file_identity_service.py

@@ -0,0 +1,151 @@
+"""
+A simple, file-based implementation of the BaseIdentityService.
+Useful for development, testing, or small-scale deployments.
+"""
+
+import logging
+import json
+from typing import Any, Dict, List, Optional
+
+from ..identity_service import BaseIdentityService
+from ...sac.sam_component_base import SamComponentBase
+
+
+log = logging.getLogger(__name__)
+
+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], component: Optional[SamComponentBase] = None):
+        super().__init__(config, component)
+        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,81 @@
+## 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