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

solace_agent_mesh/gateway/http_sse/components/components_llm.txt

@@ -1,65 +1,65 @@
+# DEVELOPER GUIDE: components
+
 ## Quick Summary
 This directory contains components for the HTTP SSE (Server-Sent Events) gateway, designed to work within the Solace AI Connector (SAC) framework. The primary component forwards messages received from the Solace broker to an internal queue, enabling real-time visualization in a web-based user interface.
 
 ## Files Overview
-- `__init__.py`: Makes the `VisualizationForwarderComponent` class directly importable from the `components` package.
-- `visualization_forwarder_component.py`: Defines a component that forwards messages from a broker input to a Python `queue.Queue` for visualization.
+- `__init__.py` - Makes the `VisualizationForwarderComponent` class directly importable from the `components` package
+- `visualization_forwarder_component.py` - Defines a SAC component that forwards messages from a broker input to a Python `queue.Queue` for visualization
 
 ## Developer API Reference
 
 ### __init__.py
-**Purpose:** Exposes the public components of this directory for easy importing.
-**Import:** `from gateway.http_sse.components import VisualizationForwarderComponent`
+**Purpose:** Exposes the public components of this directory for easy importing
+**Import:** `from solace_agent_mesh.gateway.http_sse.components import VisualizationForwarderComponent`
 
 **Exports:**
-- `VisualizationForwarderComponent`: The main component class for forwarding messages to a visualization queue.
-
----
+- `VisualizationForwarderComponent` - The main component class for forwarding messages to a visualization queue
 
 ### visualization_forwarder_component.py
-**Purpose:** A Solace AI Connector (SAC) component that listens for messages from a `BrokerInput` and forwards them to a specified Python `queue.Queue`. This is primarily used to send data to the Web UI for real-time display.
-**Import:** `from gateway.http_sse.components.visualization_forwarder_component import VisualizationForwarderComponent`
+**Purpose:** A Solace AI Connector (SAC) component that listens for messages from a `BrokerInput` and forwards them to a specified Python `queue.Queue` for real-time visualization
+**Import:** `from solace_agent_mesh.gateway.http_sse.components.visualization_forwarder_component import VisualizationForwarderComponent`
 
 **Classes:**
-- `VisualizationForwarderComponent(**kwargs: Any)` - A component that forwards messages to a target queue. It is initialized with configuration parameters, most importantly `target_queue_ref`.
-  - `invoke(self, message: SolaceMessage, data: Dict[str, Any]) -> None` - The core method called by the SAC framework for each incoming message. It formats the data and places it onto the target queue. This method should not be called directly by developers; the framework handles its execution.
+- `VisualizationForwarderComponent(**kwargs: Any)` - A component that forwards messages to a target queue, initialized with configuration parameters including `target_queue_ref`
+  - `invoke(message: SolaceMessage, data: Dict[str, Any]) -> None` - Core method called by SAC framework for each incoming message; formats data and places it onto the target queue
+  - `target_queue: queue.Queue` - The queue instance where messages are forwarded
 
 **Constants/Variables:**
-- `info: Dict` - A metadata dictionary required by the SAC framework. It describes the component's configuration parameters, input schema, and purpose. This is for framework use and not for direct interaction.
+- `info: Dict` - Metadata dictionary required by SAC framework describing component configuration, input schema, and purpose
 
 **Usage Examples:**
 ```python
 import queue
-from gateway.http_sse.components import VisualizationForwarderComponent
+from solace_agent_mesh.gateway.http_sse.components import VisualizationForwarderComponent
 from solace_ai_connector.common.message import Message as SolaceMessage
 
-# 1. Create a target queue that will receive the forwarded messages.
-#    This queue is typically managed by another component, like a Web UI backend.
+# 1. Create a target queue that will receive the forwarded messages
 visualization_queue = queue.Queue()
 
-# 2. Instantiate the component, providing a reference to the target queue.
-#    This is usually done within a SAC flow configuration file.
+# 2. Instantiate the component with target queue reference
 forwarder = VisualizationForwarderComponent(
     name="my_forwarder",
     target_queue_ref=visualization_queue
 )
 
-# 3. The `invoke` method is called automatically by the SAC framework when a message
-#    arrives from a connected BrokerInput component.
+# 3. The invoke method is called automatically by SAC framework
+# when messages arrive from connected BrokerInput component
 
-# Example of what the consuming component would get from the queue:
-# A dictionary containing the message topic, payload, and other details.
-#
-# if not visualization_queue.empty():
-#     forwarded_data = visualization_queue.get()
-#     print(f"Received topic: {forwarded_data['topic']}")
-#     print(f"Received payload: {forwarded_data['payload']}")
-#
-# Expected structure of `forwarded_data`:
+# 4. Consume forwarded messages from the queue
+if not visualization_queue.empty():
+    forwarded_data = visualization_queue.get()
+    print(f"Topic: {forwarded_data['topic']}")
+    print(f"Payload: {forwarded_data['payload']}")
+    print(f"User Properties: {forwarded_data['user_properties']}")
+    
+# Expected structure of forwarded_data:
 # {
 #     "topic": "some/broker/topic",
 #     "payload": {"key": "value"},
 #     "user_properties": {"prop1": "value1"},
 #     "_original_broker_message": <SolaceMessage object>
 # }
-```
+```
+
+# content_hash: cee7f7b4ea7e87ab3f94f7e24d463f22fa045e50d54991c61b84fe95e8a7f77d

solace_agent_mesh/gateway/http_sse/dependencies.py

@@ -3,39 +3,40 @@ Defines FastAPI dependency injectors to access shared resources
 managed by the WebUIBackendComponent.
 """
 
-from fastapi import Depends, HTTPException, status, Request
-from typing import (
-    TYPE_CHECKING,
-    Callable,
-    Dict,
-    Optional,
-    Any,
-)
-import os
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
 
+from fastapi import Depends, HTTPException, Request, status
 from solace_ai_connector.common.log import log
-from ...gateway.http_sse.sse_manager import SSEManager
-from ...gateway.http_sse.session_manager import SessionManager
-from ...common.agent_registry import AgentRegistry
 
+from ...common.agent_registry import AgentRegistry
+from ...common.middleware.config_resolver import ConfigResolver
+from ...common.services.identity_service import BaseIdentityService
+from ...core_a2a.service import CoreA2AService
+from ...gateway.base.task_context import TaskContextManager
 from ...gateway.http_sse.services.agent_service import AgentService
-from ...gateway.http_sse.services.task_service import TaskService
 from ...gateway.http_sse.services.people_service import PeopleService
-from ...gateway.base.task_context import TaskContextManager
-
-from ...core_a2a.service import CoreA2AService
-from ...common.services.identity_service import BaseIdentityService
-from ...common.middleware.config_resolver import ConfigResolver
+from ...gateway.http_sse.services.task_service import TaskService
+from ...gateway.http_sse.session_manager import SessionManager
+from ...gateway.http_sse.sse_manager import SSEManager
+from .application.services.session_service import SessionService
+from .infrastructure.persistence_service import PersistenceService
 
-from google.adk.artifacts import BaseArtifactService
+try:
+    from google.adk.artifacts import BaseArtifactService
+except ImportError:
+    # Mock BaseArtifactService for environments without Google ADK
+    class BaseArtifactService:
+        pass
 
 
 if TYPE_CHECKING:
     from gateway.http_sse.component import WebUIBackendComponent
 
 sac_component_instance: "WebUIBackendComponent" = None
+persistence_service_instance: "PersistenceService" = None
 
-api_config: Optional[Dict[str, Any]] = None
+api_config: dict[str, Any] | None = None
 
 
 def set_component_instance(component: "WebUIBackendComponent"):
@@ -48,7 +49,30 @@ def set_component_instance(component: "WebUIBackendComponent"):
         log.warning("[Dependencies] SAC Component instance already set.")
 
 
-def set_api_config(config: Dict[str, Any]):
+def set_persistence_service(persistence_service: "PersistenceService"):
+    """Called by the component during its startup to provide its instance."""
+    global persistence_service_instance
+    if persistence_service_instance is None:
+        persistence_service_instance = persistence_service
+        log.info("[Dependencies] Persistence Service instance provided.")
+    else:
+        log.warning("[Dependencies] Persistence Service instance already set.")
+
+
+def get_persistence_service() -> "PersistenceService":
+    """FastAPI dependency to get the PersistenceService instance."""
+    if persistence_service_instance is None:
+        log.warning(
+            "[Dependencies] PersistenceService not available - running in compatibility mode"
+        )
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Persistence service not available in compatibility mode.",
+        )
+    return persistence_service_instance
+
+
+def set_api_config(config: dict[str, Any]):
     """Called during startup to provide API configuration."""
     global api_config
     if api_config is None:
@@ -71,7 +95,7 @@ def get_sac_component() -> "WebUIBackendComponent":
     return sac_component_instance
 
 
-def get_api_config() -> Dict[str, Any]:
+def get_api_config() -> dict[str, Any]:
     """FastAPI dependency to get the API configuration."""
     if api_config is None:
         log.critical("[Dependencies] API configuration accessed before it was set!")
@@ -128,26 +152,43 @@ def get_user_id(
 ) -> str:
     """
     FastAPI dependency that returns the user's identity.
-    It prioritizes the authenticated user from `request.state.user` (set by AuthMiddleware)
-    and falls back to the SessionManager for non-authenticated or legacy scenarios.
+    When FRONTEND_USE_AUTHORIZATION is true: Fully relies on OAuth - user must be authenticated by AuthMiddleware.
+    When FRONTEND_USE_AUTHORIZATION is false: Uses development fallback user.
     """
     log.debug("[Dependencies] Resolving user_id string")
 
+    # AuthMiddleware should always set user state for both auth enabled/disabled cases
     if hasattr(request.state, "user") and request.state.user:
         user_id = request.state.user.get("id")
         if user_id:
             log.debug(f"[Dependencies] Using user ID from AuthMiddleware: {user_id}")
             return user_id
         else:
-            log.warning(
-                "[Dependencies] request.state.user exists but has no 'id' field. Falling back."
+            log.error(
+                "[Dependencies] request.state.user exists but has no 'id' field: %s. This indicates a bug in AuthMiddleware.",
+                request.state.user,
             )
 
-    log.debug("[Dependencies] Falling back to SessionManager for user_id")
-    try:
-        return session_manager.get_a2a_client_id(request)
-    except AssertionError:
-        return f"anonymous_user:{os.urandom(8).hex()}"
+    # If we reach here, AuthMiddleware didn't set user state properly
+    use_authorization = session_manager.use_authorization
+
+    if use_authorization:
+        # When OAuth is enabled, we should never reach here - AuthMiddleware should have handled authentication
+        log.error(
+            "[Dependencies] OAuth is enabled but no authenticated user found. This indicates an authentication failure or middleware bug."
+        )
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication required but user not found",
+        )
+    else:
+        # When auth is disabled, use development fallback user
+        fallback_id = "sam_dev_user"
+        log.info(
+            "[Dependencies] Authorization disabled and no user in request state, using fallback user: %s",
+            fallback_id,
+        )
+        return fallback_id
 
 
 def ensure_session_id(
@@ -161,21 +202,21 @@ def ensure_session_id(
 
 def get_identity_service(
     component: "WebUIBackendComponent" = Depends(get_sac_component),
-) -> Optional[BaseIdentityService]:
+) -> BaseIdentityService | None:
     """FastAPI dependency to get the configured IdentityService instance."""
     log.debug("[Dependencies] get_identity_service called")
     return component.identity_service
 
 
 def get_people_service(
-    identity_service: Optional[BaseIdentityService] = Depends(get_identity_service),
+    identity_service: BaseIdentityService | None = Depends(get_identity_service),
 ) -> PeopleService:
     """FastAPI dependency to get an instance of PeopleService."""
     log.debug("[Dependencies] get_people_service called")
     return PeopleService(identity_service=identity_service)
 
 
-PublishFunc = Callable[[str, Dict, Optional[Dict]], None]
+PublishFunc = Callable[[str, dict, dict | None], None]
 
 
 def get_publish_a2a_func(
@@ -212,7 +253,7 @@ def get_config_resolver(
 
 def get_app_config(
     component: "WebUIBackendComponent" = Depends(get_sac_component),
-) -> Dict[str, Any]:
+) -> dict[str, Any]:
     """
     FastAPI dependency to safely get the application configuration dictionary.
     """
@@ -225,8 +266,8 @@ async def get_user_config(
     user_id: str = Depends(get_user_id),
     config_resolver: ConfigResolver = Depends(get_config_resolver),
     component: "WebUIBackendComponent" = Depends(get_sac_component),
-    app_config: Dict[str, Any] = Depends(get_app_config),
-) -> Dict[str, Any]:
+    app_config: dict[str, Any] = Depends(get_app_config),
+) -> dict[str, Any]:
     """
     FastAPI dependency to get the user-specific configuration.
     """
@@ -243,7 +284,7 @@ async def get_user_config(
 
 def get_shared_artifact_service(
     component: "WebUIBackendComponent" = Depends(get_sac_component),
-) -> Optional[BaseArtifactService]:
+) -> BaseArtifactService | None:
     """FastAPI dependency to get the shared ArtifactService."""
     log.debug("[Dependencies] get_shared_artifact_service called")
     return component.get_shared_artifact_service()
@@ -251,7 +292,7 @@ def get_shared_artifact_service(
 
 def get_embed_config(
     component: "WebUIBackendComponent" = Depends(get_sac_component),
-) -> Dict[str, Any]:
+) -> dict[str, Any]:
     """FastAPI dependency to get embed-related configuration."""
     log.debug("[Dependencies] get_embed_config called")
     return component.get_embed_config()
@@ -314,3 +355,65 @@ def get_task_service(
         task_context_lock=task_context_manager._lock,
         app_name=app_name,
     )
+
+
+def get_session_service(
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+) -> SessionService:
+    log.debug("[Dependencies] get_session_service called")
+
+    if (
+        hasattr(component, "persistence_service")
+        and component.persistence_service is not None
+    ):
+        log.debug("Using database-backed session service")
+        container = component.persistence_service.container
+        return container.get_session_service()
+    else:
+        log.debug("No database configured - session persistence not available")
+        raise HTTPException(
+            status_code=status.HTTP_501_NOT_IMPLEMENTED,
+            detail="Session management requires database configuration. Configure 'database_url' in your gateway configuration.",
+        )
+
+
+def get_session_validator(
+    component: "WebUIBackendComponent" = Depends(get_sac_component),
+) -> Callable[[str, str], bool]:
+    """
+    FastAPI dependency that returns a session validator function.
+
+    With database: Validates sessions against database
+    Without database: Validates sessions using basic checks (session exists in recent activity)
+    """
+    log.debug("[Dependencies] get_session_validator called")
+
+    # Check if component has a persistence service (database-backed)
+    if (
+        hasattr(component, "persistence_service")
+        and component.persistence_service is not None
+    ):
+        log.debug("Using database-backed session validation")
+
+        def validate_with_database(session_id: str, user_id: str) -> bool:
+            container = component.persistence_service.container
+            session_service = container.get_session_service()
+            session_domain = session_service.get_session(
+                session_id=session_id, user_id=user_id
+            )
+            return session_domain is not None
+
+        return validate_with_database
+    else:
+        log.debug("No database configured - using basic session validation")
+
+        def validate_without_database(session_id: str, user_id: str) -> bool:
+            """Basic validation: check session ID format and user authentication"""
+            # Validate session ID format (should be web-session-* format from SessionManager)
+            if not session_id or not session_id.startswith("web-session-"):
+                return False
+            # If user_id is provided (authenticated), allow access
+            # This provides basic security while allowing filesystem-based artifacts
+            return bool(user_id)
+
+        return validate_without_database

solace_agent_mesh/gateway/http_sse/domain/entities/__init__.py

@@ -0,0 +1,3 @@
+from .session import Message, Session, SessionHistory
+
+__all__ = ["Session", "Message", "SessionHistory"]

solace_agent_mesh/gateway/http_sse/domain/entities/session.py

@@ -0,0 +1,90 @@
+from datetime import datetime, timezone
+
+from pydantic import BaseModel
+
+from ...shared.enums import MessageType, SenderType, SessionStatus
+from ...shared.types import AgentId, MessageId, SessionId, UserId
+
+
+class Session(BaseModel):
+    id: SessionId
+    user_id: UserId
+    name: str | None = None
+    agent_id: AgentId | None = None
+    status: SessionStatus = SessionStatus.ACTIVE
+    created_at: datetime
+    updated_at: datetime | None = None
+    last_activity: datetime | None = None
+
+    def update_name(self, new_name: str) -> None:
+        if not new_name or len(new_name.strip()) == 0:
+            raise ValueError("Session name cannot be empty")
+        if len(new_name) > 255:
+            raise ValueError("Session name cannot exceed 255 characters")
+
+        self.name = new_name.strip()
+        self.updated_at = datetime.now(timezone.utc)
+
+    def mark_activity(self) -> None:
+        self.last_activity = datetime.now(timezone.utc)
+        self.updated_at = datetime.now(timezone.utc)
+
+    def archive(self) -> None:
+        self.status = SessionStatus.ARCHIVED
+        self.updated_at = datetime.now(timezone.utc)
+
+    def activate(self) -> None:
+        self.status = SessionStatus.ACTIVE
+        self.updated_at = datetime.now(timezone.utc)
+
+    def can_be_deleted_by_user(self, user_id: UserId) -> bool:
+        return self.user_id == user_id
+
+    def can_be_accessed_by_user(self, user_id: UserId) -> bool:
+        return self.user_id == user_id
+
+
+class Message(BaseModel):
+    id: MessageId
+    session_id: SessionId
+    message: str
+    sender_type: SenderType
+    sender_name: str
+    message_type: MessageType = MessageType.TEXT
+    created_at: datetime
+
+    def validate_message_content(self) -> None:
+        if not self.message or len(self.message.strip()) == 0:
+            raise ValueError("Message content cannot be empty")
+        if len(self.message) > 10_000_000:
+            raise ValueError("Message content exceeds maximum length (10MB)")
+
+    def is_from_user(self) -> bool:
+        return self.sender_type == SenderType.USER
+
+    def is_from_agent(self) -> bool:
+        return self.sender_type == SenderType.AGENT
+
+    def is_system_message(self) -> bool:
+        return self.sender_type == SenderType.SYSTEM
+
+
+class SessionHistory(BaseModel):
+    session: Session
+    messages: list[Message] = []
+    total_message_count: int = 0
+
+    def add_message(self, message: Message) -> None:
+        if message.session_id != self.session.id:
+            raise ValueError("Message does not belong to this session")
+
+        message.validate_message_content()
+        self.messages.append(message)
+        self.total_message_count += 1
+        self.session.mark_activity()
+
+    def get_messages_by_sender_type(self, sender_type: SenderType) -> list[Message]:
+        return [msg for msg in self.messages if msg.sender_type == sender_type]
+
+    def get_latest_messages(self, count: int = 10) -> list[Message]:
+        return sorted(self.messages, key=lambda x: x.created_at, reverse=True)[:count]

solace_agent_mesh/gateway/http_sse/domain/repositories/__init__.py

@@ -0,0 +1,3 @@
+from .session_repository import IMessageRepository, ISessionRepository
+
+__all__ = ["ISessionRepository", "IMessageRepository"]

solace_agent_mesh/gateway/http_sse/domain/repositories/session_repository.py

@@ -0,0 +1,54 @@
+from abc import ABC, abstractmethod
+
+from ...shared.types import PaginationInfo, SessionId, UserId
+from ..entities.session import Message, Session
+
+
+class ISessionRepository(ABC):
+    @abstractmethod
+    def get_by_id(self, session_id: SessionId) -> Session | None:
+        pass
+
+    @abstractmethod
+    def get_by_user_id(
+        self, user_id: UserId, pagination: PaginationInfo | None = None
+    ) -> list[Session]:
+        pass
+
+    @abstractmethod
+    def get_user_session(
+        self, session_id: SessionId, user_id: UserId
+    ) -> Session | None:
+        pass
+
+    @abstractmethod
+    def create(self, session: Session) -> Session:
+        pass
+
+    @abstractmethod
+    def update(self, session: Session) -> Session | None:
+        pass
+
+    @abstractmethod
+    def delete(self, session_id: SessionId, user_id: UserId) -> bool:
+        pass
+
+    @abstractmethod
+    def exists(self, session_id: SessionId) -> bool:
+        pass
+
+
+class IMessageRepository(ABC):
+    @abstractmethod
+    def get_by_session_id(
+        self, session_id: SessionId, pagination: PaginationInfo | None = None
+    ) -> list[Message]:
+        pass
+
+    @abstractmethod
+    def create(self, message: Message) -> Message:
+        pass
+
+    @abstractmethod
+    def delete_by_session_id(self, session_id: SessionId) -> bool:
+        pass