solace-agent-mesh 1.0.9__py3-none-any.whl → 1.3.0__py3-none-any.whl

solace_agent_mesh/gateway/http_sse/services/services_llm.txt

@@ -1,179 +1,133 @@
-Here is the developer guide for the `services` directory.
+# DEVELOPER GUIDE: services
 
 ## Quick Summary
-The `services` directory contains the business logic layer for the HTTP SSE Gateway. It encapsulates core functionalities by providing high-level services for agent management, user identity searches, and A2A (Agent-to-Agent) task operations. These services abstract the complexities of interacting with the agent registry, external identity providers, and the underlying A2A messaging protocol.
+The `services` directory contains the business logic layer for the HTTP SSE Gateway. It provides high-level services for agent management (discovering and retrieving A2A agents), user identity operations (searching for users), and task management (cancelling A2A tasks). These services abstract the complexities of interacting with agent registries, identity providers, and A2A messaging protocols.
 
 ## Files Overview
-- `__init__.py` - Marks the directory as a Python package.
-- `agent_service.py` - Service for retrieving information about discovered A2A agents.
-- `people_service.py` - Service for searching for users via a configured identity service.
-- `task_service.py` - Service for handling the cancellation of tasks with A2A agents.
+- `__init__.py` - Package initialization file marking the directory as a Python package
+- `agent_service.py` - Service for retrieving information about discovered A2A agents from the registry
+- `people_service.py` - Service for searching users via configured identity services
+- `task_service.py` - Service for handling A2A task cancellation operations
 
 ## Developer API Reference
 
 ### __init__.py
-**Purpose:** This file marks the `services` directory as a Python package, allowing its modules to be imported.
-**Import:** N/A - No public interfaces.
-
----
+**Purpose:** Marks the services directory as a Python package
+**Import:** N/A - No public interfaces
 
 ### agent_service.py
-**Purpose:** Provides high-level methods for accessing information about discovered A2A agents from the shared `AgentRegistry`.
-**Import:** `from src.solace_agent_mesh.gateway.http_sse.services.agent_service import AgentService`
+**Purpose:** Provides methods for accessing information about discovered A2A agents from the shared AgentRegistry
+**Import:** `from solace_agent_mesh.gateway.http_sse.services.agent_service import AgentService`
 
 **Classes:**
-- `AgentService(agent_registry: AgentRegistry)` - A service that provides methods for accessing information about discovered A2A agents.
-  - `get_all_agents() -> List[AgentCard]` - Retrieves all currently discovered and registered agent cards from the registry.
-  - `get_agent_by_name(agent_name: str) -> Optional[AgentCard]` - Retrieves a specific agent card by its unique name. Returns `None` if the agent is not found.
+- `AgentService(agent_registry: AgentRegistry)` - Service for accessing discovered A2A agent information
+  - `get_all_agents() -> List[AgentCard]` - Retrieves all currently discovered and registered agent cards
+  - `get_agent_by_name(agent_name: str) -> Optional[AgentCard]` - Retrieves a specific agent card by name, returns None if not found
 
 **Usage Examples:**
 ```python
-from typing import List, Optional
-from src.solace_agent_mesh.gateway.http_sse.services.agent_service import AgentService
-from src.solace_agent_mesh.common.agent_registry import AgentRegistry
-from src.solace_agent_mesh.common.types import AgentCard
-
-# In a real application, AgentRegistry would be a shared instance.
-# For this example, we'll create a new one and populate it.
-agent_registry = AgentRegistry()
-my_agent_card = AgentCard(name="data-analyzer", description="Analyzes data files.")
-agent_registry.register_agent(my_agent_card)
-
-# 1. Initialize the service with the agent registry
+from solace_agent_mesh.gateway.http_sse.services.agent_service import AgentService
+from solace_agent_mesh.common.agent_registry import AgentRegistry
+
+# Initialize with shared agent registry
+agent_registry = AgentRegistry()  # Usually injected as shared instance
 agent_service = AgentService(agent_registry=agent_registry)
 
-# 2. Get all available agents
+# Get all available agents
 all_agents = agent_service.get_all_agents()
-print(f"Found {len(all_agents)} agent(s).")
-for agent in all_agents:
-    print(f"- Agent: {agent.name}, Description: {agent.description}")
-
-# 3. Get a specific agent by name
-found_agent = agent_service.get_agent_by_name("data-analyzer")
-if found_agent:
-    print(f"\nSuccessfully retrieved agent: {found_agent.name}")
-else:
-    print("\nCould not find agent 'data-analyzer'.")
+print(f"Found {len(all_agents)} agents")
 
-# 4. Try to get a non-existent agent
-missing_agent = agent_service.get_agent_by_name("non-existent-agent")
-print(f"Result for 'non-existent-agent': {missing_agent}")
+# Get specific agent by name
+agent = agent_service.get_agent_by_name("data-processor")
+if agent:
+    print(f"Found agent: {agent.name}")
+else:
+    print("Agent not found")
 ```
 
----
-
 ### people_service.py
-**Purpose:** Acts as a layer on top of a configured `IdentityService` to provide user search functionality. If no identity service is configured, it gracefully returns empty results.
-**Import:** `from src.solace_agent_mesh.gateway.http_sse.services.people_service import PeopleService`
+**Purpose:** Provides user search functionality via configured identity services
+**Import:** `from solace_agent_mesh.gateway.http_sse.services.people_service import PeopleService`
 
 **Classes:**
-- `PeopleService(identity_service: Optional[BaseIdentityService])` - A service for searching and retrieving user information.
-  - `search_for_users(query: str, limit: int = 10) -> List[Dict[str, Any]]` - Asynchronously searches for users via the identity service. Returns an empty list if the query is too short, no identity service is configured, or an error occurs.
+- `PeopleService(identity_service: Optional[BaseIdentityService])` - Service for searching and retrieving user information
+  - `search_for_users(query: str, limit: int = 10) -> List[Dict[str, Any]]` - Asynchronously searches for users, returns empty list if no identity service configured or query too short
 
 **Usage Examples:**
 ```python
 import asyncio
-from typing import Any, Dict, List, Optional
-from src.solace_agent_mesh.gateway.http_sse.services.people_service import PeopleService
-from src.solace_agent_mesh.common.services.identity_service import BaseIdentityService
-
-# Define a mock identity service for the example
-class MockIdentityService(BaseIdentityService):
-    async def search_users(self, query: str, limit: int) -> List[Dict[str, Any]]:
-        print(f"MockIdentityService: Searching for '{query}' with limit {limit}")
-        all_users = [
-            {"id": "jdoe", "name": "John Doe", "email": "j.doe@example.com"},
-            {"id": "jsmith", "name": "Jane Smith", "email": "j.smith@example.com"},
-        ]
-        return [user for user in all_users if query.lower() in user["name"].lower()][:limit]
-
-async def main():
-    # 1. Initialize with a configured identity service
-    identity_service = MockIdentityService()
-    people_service = PeopleService(identity_service=identity_service)
-
-    # 2. Search for users
+from solace_agent_mesh.gateway.http_sse.services.people_service import PeopleService
+from solace_agent_mesh.common.services.identity_service import BaseIdentityService
+
+# Initialize with identity service
+identity_service = SomeIdentityService()  # Your identity service implementation
+people_service = PeopleService(identity_service=identity_service)
+
+async def search_users():
+    # Search for users
     users = await people_service.search_for_users("john", limit=5)
-    print(f"Found {len(users)} user(s): {users}")
+    for user in users:
+        print(f"User: {user.get('name')} - {user.get('email')}")
 
-    # 3. Initialize without an identity service
-    people_service_no_id = PeopleService(identity_service=None)
-    
-    # 4. Search will return an empty list
-    empty_results = await people_service_no_id.search_for_users("jane")
-    print(f"Results with no identity service: {empty_results}")
+# Initialize without identity service (graceful degradation)
+people_service_no_id = PeopleService(identity_service=None)
+# search_for_users will return empty list
 
-if __name__ == "__main__":
-    asyncio.run(main())
+asyncio.run(search_users())
 ```
 
----
-
 ### task_service.py
-**Purpose:** Handles the business logic for cancelling A2A tasks. It uses `CoreA2AService` to construct the cancellation message and a provided publisher function to send it over the messaging fabric.
-**Import:** `from src.solace_agent_mesh.gateway.http_sse.services.task_service import TaskService, PublishFunc`
-
-**Classes:**
-- `TaskService(core_a2a_service: CoreA2AService, publish_func: PublishFunc, namespace: str, gateway_id: str, sse_manager: SSEManager, task_context_map: Dict[str, Dict], task_context_lock: threading.Lock, app_name: str)` - A service for managing A2A task operations.
-  - `cancel_task(agent_name: str, task_id: str, client_id: str, user_id: str = "web_user") -> None` - Asynchronously constructs and publishes an A2A `CancelTaskRequest` message for a specific task.
+**Purpose:** Handles A2A task operations, specifically task cancellation using CoreA2AService and message publishing
+**Import:** `from solace_agent_mesh.gateway.http_sse.services.task_service import TaskService, PublishFunc`
 
 **Type Aliases:**
-- `PublishFunc: Callable[[str, Dict, Optional[Dict]], None]` - A callable that sends a message. It takes a topic, a payload dictionary, and optional user properties.
+- `PublishFunc: Callable[[str, Dict, Optional[Dict]], None]` - Function type for publishing messages (topic, payload, user_properties)
+
+**Classes:**
+- `TaskService(core_a2a_service: CoreA2AService, publish_func: PublishFunc, namespace: str, gateway_id: str, sse_manager: SSEManager, task_context_map: Dict[str, Dict], task_context_lock: threading.Lock, app_name: str)` - Service for managing A2A task operations
+  - `cancel_task(agent_name: str, task_id: str, client_id: str, user_id: str = "web_user") -> None` - Asynchronously cancels a task by publishing A2A CancelTaskRequest message
 
 **Usage Examples:**
 ```python
 import asyncio
 import threading
-from typing import Callable, Dict, Optional
-
-from src.solace_agent_mesh.gateway.http_sse.services.task_service import TaskService, PublishFunc
-from src.solace_agent_mesh.core_a2a.service import CoreA2AService
-from src.solace_agent_mesh.gateway.http_sse.sse_manager import SSEManager
-
-# Mock dependencies for the example
-class MockCoreA2AService(CoreA2AService):
-    def cancel_task(self, agent_name, task_id, client_id, user_id):
-        topic = f"a2a/request/{agent_name}/cancelTask"
-        payload = {"taskId": task_id}
-        user_props = {"clientId": client_id, "userId": user_id}
-        return topic, payload, user_props
-
-def my_publish_func(topic: str, payload: Dict, user_properties: Optional[Dict]):
-    print("\n--- Publishing Message ---")
-    print(f"Topic: {topic}")
-    print(f"Payload: {payload}")
-    print(f"User Properties: {user_properties}")
-    print("------------------------")
-
-async def main():
-    # 1. Set up dependencies
-    core_a2a_service = MockCoreA2AService()
-    sse_manager = SSEManager()
-    task_context_map = {}
-    task_context_lock = threading.Lock()
-
-    # 2. Initialize TaskService
-    task_service = TaskService(
-        core_a2a_service=core_a2a_service,
-        publish_func=my_publish_func,
-        namespace="my-namespace",
-        gateway_id="gateway-01",
-        sse_manager=sse_manager,
-        task_context_map=task_context_map,
-        task_context_lock=task_context_lock,
-        app_name="my-app"
-    )
-
-    # 3. Call the cancel_task method
-    print("Requesting task cancellation...")
+from solace_agent_mesh.gateway.http_sse.services.task_service import TaskService, PublishFunc
+from solace_agent_mesh.core_a2a.service import CoreA2AService
+from solace_agent_mesh.gateway.http_sse.sse_manager import SSEManager
+
+# Define publish function
+def my_publish_func(topic: str, payload: dict, user_properties: dict = None):
+    print(f"Publishing to {topic}: {payload}")
+    # Your actual message publishing logic here
+
+# Initialize dependencies
+core_a2a_service = CoreA2AService()  # Your core A2A service
+sse_manager = SSEManager()
+task_context_map = {}
+task_context_lock = threading.Lock()
+
+# Create task service
+task_service = TaskService(
+    core_a2a_service=core_a2a_service,
+    publish_func=my_publish_func,
+    namespace="my-namespace",
+    gateway_id="gateway-01",
+    sse_manager=sse_manager,
+    task_context_map=task_context_map,
+    task_context_lock=task_context_lock,
+    app_name="my-app"
+)
+
+async def cancel_task_example():
+    # Cancel a task
     await task_service.cancel_task(
-        agent_name="report-generator",
-        task_id="task-12345",
-        client_id="client-abcde",
-        user_id="test.user"
+        agent_name="data-processor",
+        task_id="task-123",
+        client_id="client-456",
+        user_id="user@example.com"
     )
-    print("Task cancellation request sent.")
 
-if __name__ == "__main__":
-    asyncio.run(main())
-```
+asyncio.run(cancel_task_example())
+```
+
+# content_hash: 83ddf6b403dc50598ed550e4b3a5445f832b3956dad75f7a3fbbb7e6e5c6c115

solace_agent_mesh/gateway/http_sse/services/task_service.py

@@ -8,10 +8,7 @@ from typing import Callable, Dict, Optional
 
 from solace_ai_connector.common.log import log
 
-from ....common.types import (
-    InternalError,
-)
-
+from ....common import a2a
 from ....gateway.http_sse.sse_manager import SSEManager
 from ....core_a2a.service import CoreA2AService
 
@@ -116,6 +113,6 @@ class TaskService:
 
         except Exception as e:
             log.exception("%sFailed to publish cancellation request: %s", log_prefix, e)
-            raise InternalError(
+            raise a2a.create_internal_error(
                 message="Failed to publish cancellation request: %s" % e
             ) from e

solace_agent_mesh/gateway/http_sse/session_manager.py

@@ -3,10 +3,13 @@ Manages web user sessions and mapping to A2A Client IDs.
 """
 
 import uuid
-from starlette.requests import Request
-from typing import Optional, Callable, Dict, Any
+from collections.abc import Callable
+from typing import Any
 
 from solace_ai_connector.common.log import log
+from starlette.requests import Request
+
+from .infrastructure.persistence_service import PersistenceService
 
 SESSION_KEY_CLIENT_ID = "a2a_client_id"
 SESSION_KEY_SESSION_ID = "a2a_session_id"
@@ -21,12 +24,18 @@ class SessionManager:
     Generates and stores unique A2A Client IDs and manages the current A2A Session ID per web session.
     """
 
-    def __init__(self, secret_key: str, app_config: Dict[str, Any]):
+    def __init__(
+        self,
+        secret_key: str,
+        app_config: dict[str, Any],
+        persistence_service: "PersistenceService",
+    ):
         if not secret_key:
             raise ValueError("Session secret key cannot be empty.")
         self.secret_key = secret_key
         self.force_user_identity = app_config.get("force_user_identity")
-        self.default_user_identity = app_config.get("default_user_identity")
+        self.use_authorization = app_config.get("frontend_use_authorization", False)
+        self.persistence_service = persistence_service
         self._temp_code_cache = {}
         log.info("[SessionManager] Initialized.")
         if self.force_user_identity:
@@ -34,10 +43,11 @@ class SessionManager:
                 f"[SessionManager] Forcing user identity to: {self.force_user_identity}"
             )
 
-    def _get_or_create_client_id(self, request: Request) -> str:
+    def _get_or_create_client_id(self, request: Request) -> str | None:
         """
         Retrieves the A2A Client ID. It prioritizes the authenticated user from
         `request.state.user` and falls back to session-based or generated IDs.
+        If authorization is enabled, it returns None if no user can be identified.
         """
         if self.force_user_identity:
             return self.force_user_identity
@@ -64,35 +74,35 @@ class SessionManager:
             return user_id
 
         client_id = request.session.get(SESSION_KEY_CLIENT_ID)
-        if not client_id:
-            if self.default_user_identity:
-                log.info(
-                    "[SessionManager] Using default_user_identity as A2A Client ID: %s",
-                    self.default_user_identity,
-                )
-                client_id = self.default_user_identity
-            else:
-                client_id = f"web-client-{uuid.uuid4().hex}"
-                log.info(
-                    "[SessionManager] Created new A2A Client ID: %s for web session.",
-                    client_id,
-                )
-            request.session[SESSION_KEY_CLIENT_ID] = client_id
-        else:
+        if client_id:
             log.debug(
                 "[SessionManager] Using existing A2A Client ID: %s for web session.",
                 client_id,
             )
-        return client_id
+            return client_id
+
+        if not self.use_authorization:
+            client_id = "sam_dev_user"
+            log.info(
+                "[SessionManager] No authenticated user and auth is disabled, using client ID: %s for web session.",
+                client_id,
+            )
+            request.session[SESSION_KEY_CLIENT_ID] = client_id
+            return client_id
+
+        log.warning(
+            "[SessionManager] Could not determine client ID and authorization is enabled."
+        )
+        return None
 
-    def get_a2a_client_id(self, request: Request) -> str:
+    def get_a2a_client_id(self, request: Request) -> str | None:
         """
         FastAPI dependency callable to get the A2A Client ID for the current request.
-        Ensures a client ID exists in the session.
+        Ensures a client ID exists in the session if auth is disabled.
         """
         return self._get_or_create_client_id(request)
 
-    def get_a2a_session_id(self, request: Request) -> Optional[str]:
+    def get_a2a_session_id(self, request: Request) -> str | None:
         """
         FastAPI dependency callable to get the current A2A Session ID for the current request.
         Returns None if no session has been started for the current agent in this web session.
@@ -107,6 +117,11 @@ class SessionManager:
         This should be called when the user explicitly starts a new chat or switches agents.
         """
         client_id = self._get_or_create_client_id(request)
+        if not client_id:
+            # This case should ideally be prevented by middleware raising 401
+            raise RuntimeError(
+                "Cannot start a new A2A session without a client ID when authorization is enabled."
+            )
         new_session_id = f"web-session-{uuid.uuid4().hex}"
         request.session[SESSION_KEY_SESSION_ID] = new_session_id
         log.info(
@@ -116,6 +131,25 @@ class SessionManager:
         )
         return new_session_id
 
+    def create_new_session_id(self, request: Request) -> str:
+        """
+        Generates a new A2A Session ID without storing it in cookies.
+        This should be used when the frontend manages session state.
+        """
+        client_id = self._get_or_create_client_id(request)
+        if not client_id:
+            # This case should ideally be prevented by middleware raising 401
+            raise RuntimeError(
+                "Cannot start a new A2A session without a client ID when authorization is enabled."
+            )
+        new_session_id = f"web-session-{uuid.uuid4().hex}"
+        log.info(
+            "[SessionManager] Generated new A2A Session ID: %s for Client ID: %s (not stored in cookies)",
+            new_session_id,
+            client_id,
+        )
+        return new_session_id
+
     def ensure_a2a_session(self, request: Request) -> str:
         """
         Ensures an A2A session ID exists, creating one if necessary.
@@ -131,7 +165,7 @@ class SessionManager:
         return session_id
 
     def store_auth_tokens(
-        self, request: Request, access_token: str, refresh_token: Optional[str] = None
+        self, request: Request, access_token: str, refresh_token: str | None = None
     ):
         """
         Stores authentication tokens directly in the user's session.
@@ -141,13 +175,13 @@ class SessionManager:
             request.session[SESSION_KEY_REFRESH_TOKEN] = refresh_token
         log.info("[SessionManager] Stored auth tokens directly in session.")
 
-    def get_access_token(self, request: Request) -> Optional[str]:
+    def get_access_token(self, request: Request) -> str | None:
         """
         Retrieves the access token from the web session.
         """
         return request.session.get(SESSION_KEY_ACCESS_TOKEN)
 
-    def get_refresh_token(self, request: Request) -> Optional[str]:
+    def get_refresh_token(self, request: Request) -> str | None:
         """
         Retrieves the refresh token from the web session.
         """
@@ -168,17 +202,17 @@ class SessionManager:
         request.session[SESSION_KEY_USER_ID] = user_id
         log.info("[SessionManager] Stored user ID in session: %s", user_id)
 
-    def get_user_id(self, request: Request) -> Optional[str]:
+    def get_user_id(self, request: Request) -> str | None:
         """
         Retrieves the user ID from the web session.
         """
         return request.session.get(SESSION_KEY_USER_ID)
 
-    def dep_get_client_id(self) -> Callable[[Request], str]:
+    def dep_get_client_id(self) -> Callable[[Request], str | None]:
         """Returns a callable suitable for FastAPI Depends to get the client ID."""
         return self.get_a2a_client_id
 
-    def dep_get_session_id(self) -> Callable[[Request], Optional[str]]:
+    def dep_get_session_id(self) -> Callable[[Request], str | None]:
         """Returns a callable suitable for FastAPI Depends to get the current session ID."""
         return self.get_a2a_session_id
 

solace_agent_mesh/gateway/http_sse/shared/__init__.py

@@ -0,0 +1,9 @@
+"""
+Shared Utilities and Constants
+
+Contains common utilities, constants, enums, and types used across layers.
+"""
+
+from .auth_utils import get_current_user
+
+__all__ = ["get_current_user"]

solace_agent_mesh/gateway/http_sse/shared/auth_utils.py

@@ -0,0 +1,29 @@
+"""
+Authentication utilities for the FastAPI application.
+
+This module provides common authentication functions used across controllers.
+"""
+
+from fastapi import Depends, Request as FastAPIRequest
+
+
+async def get_current_user(request: FastAPIRequest) -> dict:
+    """
+    Extracts the current user from the request state.
+    
+    This function is used as a FastAPI dependency to get the authenticated user
+    information that was set by the AuthMiddleware.
+    
+    Args:
+        request: The FastAPI request object with user state
+        
+    Returns:
+        dict: User information dictionary containing id, name, email, etc.
+    """
+    return getattr(request.state, "user", {
+        "id": "anonymous",
+        "name": "Anonymous User",
+        "email": "anonymous@localhost",
+        "authenticated": False,
+        "auth_method": "none"
+    })

solace_agent_mesh/gateway/http_sse/shared/enums.py

@@ -0,0 +1,45 @@
+"""
+Enumerations used throughout the application.
+"""
+
+from enum import Enum
+
+
+class SenderType(str, Enum):
+    """Types of message senders."""
+    USER = "user"
+    AGENT = "agent"
+    SYSTEM = "system"
+
+
+class TaskStatus(str, Enum):
+    """Task execution status."""
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class SessionStatus(str, Enum):
+    """Session status."""
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+    ARCHIVED = "archived"
+
+
+class MessageType(str, Enum):
+    """Types of messages."""
+    TEXT = "text"
+    FILE = "file"
+    IMAGE = "image"
+    DOCUMENT = "document"
+
+
+class ValidationErrorType(str, Enum):
+    """Types of validation errors."""
+    REQUIRED_FIELD = "required_field"
+    INVALID_FORMAT = "invalid_format"
+    OUT_OF_RANGE = "out_of_range"
+    DUPLICATE_VALUE = "duplicate_value"
+    BUSINESS_RULE = "business_rule"

solace_agent_mesh/gateway/http_sse/shared/types.py

@@ -0,0 +1,45 @@
+"""
+Custom types and type aliases used throughout the application.
+"""
+
+from typing import Dict, Any, List, Optional, Union
+from datetime import datetime
+from pydantic import BaseModel
+
+# Basic type aliases
+UserId = str
+SessionId = str
+MessageId = str
+TaskId = str
+AgentId = str
+
+# Dictionary types
+JsonDict = Dict[str, Any]
+Headers = Dict[str, str]
+QueryParams = Dict[str, Union[str, List[str]]]
+
+# Common data structures
+class Timestamp(BaseModel):
+    """Standardized timestamp representation."""
+    created_at: datetime
+    updated_at: Optional[datetime] = None
+
+class PaginationInfo(BaseModel):
+    """Pagination information for list responses."""
+    page: int
+    page_size: int
+    total_items: int
+    total_pages: int
+    has_next: bool
+    has_previous: bool
+
+class SortInfo(BaseModel):
+    """Sorting information for list requests."""
+    field: str
+    direction: str = "asc"  # asc or desc
+
+class FilterInfo(BaseModel):
+    """Filtering information for list requests."""
+    field: str
+    operator: str  # eq, ne, gt, lt, gte, lte, contains, in
+    value: Any