solace-agent-mesh 1.4.12__py3-none-any.whl → 1.5.1__py3-none-any.whl

solace_agent_mesh/gateway/http_sse/services/feedback_service.py

@@ -0,0 +1,242 @@
+"""
+Service layer for handling user feedback on chat messages.
+"""
+
+import json
+import logging
+import uuid
+from typing import TYPE_CHECKING, Callable
+
+from sqlalchemy.orm import Session as DBSession
+
+from ..repository.entities import Feedback
+from ..repository.feedback_repository import FeedbackRepository
+from ..shared import now_epoch_ms
+from ..utils.stim_utils import create_stim_from_task_data
+
+# The FeedbackPayload is defined in the router, this creates a forward reference
+# which is resolved at runtime.
+if TYPE_CHECKING:
+    from ..routers.feedback import FeedbackPayload
+    from ..component import WebUIBackendComponent
+    from ..repository.interfaces import ITaskRepository
+
+log = logging.getLogger(__name__)
+
+class FeedbackService:
+    """Handles the business logic for processing user feedback."""
+
+    def __init__(
+        self,
+        session_factory: Callable[[], DBSession] | None,
+        component: "WebUIBackendComponent",
+        task_repo: "ITaskRepository",
+    ):
+        """Initializes the FeedbackService."""
+        self.session_factory = session_factory
+        self.component = component
+        self.task_repo = task_repo
+        if self.session_factory:
+            log.info("FeedbackService initialized with database persistence.")
+        else:
+            log.info(
+                "FeedbackService initialized without database persistence (logging only)."
+            )
+
+    async def process_feedback(self, payload: "FeedbackPayload", user_id: str):
+        """
+        Processes and stores the feedback. If a repository is configured,
+        it saves to the database. Otherwise, it logs the feedback.
+        Also publishes feedback to a Solace topic if configured.
+        Additionally updates the corresponding task's metadata with the feedback.
+        """
+        if self.session_factory:
+            task_id = getattr(payload, "task_id", None)
+            if not task_id:
+                log.error(
+                    "Feedback payload is missing 'task_id'. Cannot save to database. Payload: %s",
+                    payload.model_dump_json(by_alias=True),
+                )
+                # We can still try to publish the event without saving to DB
+            else:
+                feedback_entity = Feedback(
+                    id=str(uuid.uuid4()),
+                    session_id=payload.session_id,
+                    task_id=task_id,
+                    user_id=user_id,
+                    rating=payload.feedback_type,
+                    comment=payload.feedback_text,
+                    created_time=now_epoch_ms(),
+                )
+
+                db = self.session_factory()
+                try:
+                    repo = FeedbackRepository(db)
+                    repo.save(feedback_entity)
+                    db.commit()
+                    log.info(
+                        "Feedback from user '%s' for task '%s' saved to database.",
+                        user_id,
+                        task_id,
+                    )
+                except Exception as e:
+                    log.exception(
+                        "Failed to save feedback for user '%s' to database: %s",
+                        user_id,
+                        e,
+                    )
+                    db.rollback()
+                finally:
+                    db.close()
+
+                # Update task metadata with feedback
+                self._update_task_metadata_with_feedback(
+                    task_id, user_id, payload.feedback_type, payload.feedback_text
+                )
+        else:
+            log.warning(
+                "Feedback received but no database repository is configured. "
+                "Logging feedback only. Payload: %s",
+                payload.model_dump_json(by_alias=True),
+            )
+
+        # --- New event publishing logic ---
+        try:
+            await self._publish_feedback_event(payload, user_id)
+        except Exception as e:
+            log.error(
+                "Failed to publish feedback event for user '%s': %s", user_id, e
+            )
+            # Do not re-raise, as the primary operation (DB save) may have succeeded.
+
+    def _update_task_metadata_with_feedback(
+        self, task_id: str, user_id: str, feedback_type: str, feedback_text: str | None
+    ):
+        """
+        Update the task's metadata with feedback information.
+        
+        Args:
+            task_id: The task ID to update
+            user_id: The user ID who submitted feedback
+            feedback_type: Type of feedback ("up" or "down")
+            feedback_text: Optional feedback text
+        """
+        if not self.session_factory:
+            log.debug(
+                "No session factory available, skipping task metadata update for task %s",
+                task_id
+            )
+            return
+
+        db = self.session_factory()
+        try:
+            from ..repository.chat_task_repository import ChatTaskRepository
+            
+            task_repo = ChatTaskRepository(db)
+            task = task_repo.find_by_id(task_id, user_id)
+            
+            if task:
+                # Update feedback in task metadata
+                task.add_feedback(feedback_type, feedback_text)
+                task_repo.save(task)
+                db.commit()
+                log.info(
+                    "Updated task metadata with feedback for task '%s' by user '%s'",
+                    task_id,
+                    user_id
+                )
+            else:
+                log.warning(
+                    "Task '%s' not found for user '%s', cannot update task metadata with feedback",
+                    task_id,
+                    user_id
+                )
+        except Exception as e:
+            log.warning(
+                "Failed to update task metadata with feedback for task '%s': %s",
+                task_id,
+                e
+            )
+            db.rollback()
+            # Don't re-raise - feedback was already saved to feedback table
+        finally:
+            db.close()
+
+    async def _publish_feedback_event(self, payload: "FeedbackPayload", user_id: str):
+        """Publishes the feedback as an event to the message broker if configured."""
+        log_id = f"[FeedbackPublisher:{payload.task_id}]"
+        config = self.component.get_config("feedback_publishing", {})
+
+        if not config.get("enabled", False):
+            log.debug("%s Feedback publishing is disabled. Skipping.", log_id)
+            return
+
+        # Construct base payload
+        event_payload = {
+            "feedback": {
+                "task_id": payload.task_id,
+                "session_id": payload.session_id,
+                "feedback_type": payload.feedback_type,
+                "feedback_text": payload.feedback_text,
+                "user_id": user_id,
+            }
+        }
+
+        include_task_info = config.get("include_task_info", "none")
+        task_summary_data = None
+
+        if include_task_info == "summary":
+            log.debug("%s Including task summary.", log_id)
+            task_summary_data = self.task_repo.find_by_id(payload.task_id)
+            if task_summary_data:
+                event_payload["task_summary"] = task_summary_data.model_dump()
+
+        elif include_task_info == "stim":
+            log.debug("%s Including task stim data.", log_id)
+            task_with_events = self.task_repo.find_by_id_with_events(payload.task_id)
+            if task_with_events:
+                task, events = task_with_events
+                stim_data = create_stim_from_task_data(task, events)
+                event_payload["task_stim_data"] = stim_data
+
+                # Check payload size
+                max_size = config.get("max_payload_size_bytes", 9000000)
+                try:
+                    payload_bytes = json.dumps(event_payload).encode("utf-8")
+                    if len(payload_bytes) > max_size:
+                        log.warning(
+                            "%s Stim payload size (%d bytes) exceeds limit (%d bytes). Falling back to summary.",
+                            log_id,
+                            len(payload_bytes),
+                            max_size,
+                        )
+                        # Fallback to summary
+                        del event_payload["task_stim_data"]
+                        task_summary_data = self.task_repo.find_by_id(payload.task_id)
+                        if task_summary_data:
+                            event_payload[
+                                "task_summary"
+                            ] = task_summary_data.model_dump()
+                        event_payload["truncation_details"] = {
+                            "strategy": "fallback_to_summary",
+                            "reason": "payload_too_large",
+                        }
+                except Exception as e:
+                    log.error("%s Error checking payload size: %s", log_id, e)
+                    # If we can't check size, better to not send a potentially huge message
+                    if "task_stim_data" in event_payload:
+                        del event_payload["task_stim_data"]
+
+        # Publish the event
+        topic = config.get("topic", "sam/feedback/v1")
+        try:
+            log.info("%s Publishing feedback event to topic '%s'", log_id, topic)
+            self.component.publish_a2a(topic, event_payload)
+        except Exception as e:
+            log.error(
+                "%s Failed to publish feedback event to topic '%s': %s",
+                log_id,
+                topic,
+                e,
+            )
+            # Don't re-raise, this is a non-critical operation.

solace_agent_mesh/gateway/http_sse/services/people_service.py

@@ -2,92 +2,12 @@
 Service layer for handling people-related operations, such as searching for users.
 """
 
+import logging
 from typing import Any, Dict, List, Optional
 
-from solace_ai_connector.common.log import log
-
-from ....common.services.identity_service import BaseIdentityService
-
-
-class PeopleService:
-    """
-    Provides methods for searching and retrieving user information,
-    acting as a layer on top of the configured IdentityService.
-    """
-
-    def __init__(self, identity_service: Optional[BaseIdentityService]):
-        """
-        Initializes the PeopleService.
-
-        Args:
-            identity_service: An instance of a configured BaseIdentityService, or None.
-        """
-        self._identity_service = identity_service
-        self.log_identifier = "[PeopleService]"
-        log.info(
-            "%s Initialized with Identity Service: %s",
-            self.log_identifier,
-            identity_service is not None,
-        )
-
-    async def search_for_users(
-        self, query: str, limit: int = 10
-    ) -> List[Dict[str, Any]]:
-        """
-        Searches for users via the identity service.
-
-        Args:
-            query: The search query string.
-            limit: The maximum number of results to return.
-
-        Returns:
-            A list of user profile dictionaries.
-        """
-        if not self._identity_service:
-            log.warning(
-                "%s Search requested but no identity service is configured.",
-                self.log_identifier,
-            )
-            return []
-
-        if not query or len(query) < 2:
-            return []
-
-        try:
-            log.debug(
-                "%s Searching for users with query: '%s', limit: %d",
-                self.log_identifier,
-                query,
-                limit,
-            )
-            results = await self._identity_service.search_users(query, limit)
-            log.info(
-                "%s Found %d users for query: '%s'",
-                self.log_identifier,
-                len(results),
-                query,
-            )
-            return results
-        except Exception as e:
-            log.exception(
-                "%s Error during user search for query '%s': %s",
-                self.log_identifier,
-                query,
-                e,
-            )
-            return []
-
-
-"""
-Service layer for handling people-related operations, such as searching for users.
-"""
-
-from typing import Any, Dict, List, Optional
-
-from solace_ai_connector.common.log import log
-
 from ....common.services.identity_service import BaseIdentityService
 
+log = logging.getLogger(__name__)
 
 class PeopleService:
     """

solace_agent_mesh/gateway/http_sse/services/services_llm.txt

@@ -1,13 +1,17 @@
 # DEVELOPER GUIDE: services
 
 ## Quick Summary
-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.
+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 feedback processing with database persistence and event publishing, user search via identity services, session management with database persistence, task logging to database, data retention/cleanup, and A2A task operations like cancellation.
 
 ## Files Overview
 - `__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
+- `agent_card_service.py` - Service for retrieving information about discovered A2A agents from the registry
+- `data_retention_service.py` - Service for automatic cleanup of old tasks and feedback based on retention policies
+- `feedback_service.py` - Service for processing and storing user feedback on chat messages with database and event publishing
 - `people_service.py` - Service for searching users via configured identity services
-- `task_service.py` - Service for handling A2A task cancellation operations
+- `session_service.py` - Service for managing chat sessions and messages with database persistence
+- `task_logger_service.py` - Service for logging A2A tasks and events to the database
+- `task_service.py` - Service for handling A2A task operations like cancellation
 
 ## Developer API Reference
 
@@ -15,36 +19,107 @@ The `services` directory contains the business logic layer for the HTTP SSE Gate
 **Purpose:** Marks the services directory as a Python package
 **Import:** N/A - No public interfaces
 
-### agent_service.py
+### agent_card_service.py
 **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`
+**Import:** `from solace_agent_mesh.gateway.http_sse.services.agent_card_service import AgentCardService`
 
 **Classes:**
-- `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
+- `AgentCardService(agent_registry: AgentRegistry)` - Service for accessing discovered A2A agent information
+  - `get_all_agent_cards() -> List[AgentCard]` - Retrieves all currently discovered and registered agent cards
+  - `get_agent_card_by_name(agent_name: str) -> Optional[AgentCard]` - Retrieves a specific agent card by name, returns None if not found
 
 **Usage Examples:**
 ```python
-from solace_agent_mesh.gateway.http_sse.services.agent_service import AgentService
+from solace_agent_mesh.gateway.http_sse.services.agent_card_service import AgentCardService
 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)
+agent_service = AgentCardService(agent_registry=agent_registry)
 
 # Get all available agents
-all_agents = agent_service.get_all_agents()
+all_agents = agent_service.get_all_agent_cards()
 print(f"Found {len(all_agents)} agents")
 
 # Get specific agent by name
-agent = agent_service.get_agent_by_name("data-processor")
+agent = agent_service.get_agent_card_by_name("data-processor")
 if agent:
     print(f"Found agent: {agent.name}")
 else:
     print("Agent not found")
 ```
 
+### data_retention_service.py
+**Purpose:** Service for automatically cleaning up old tasks, task events, and feedback based on configurable retention policies
+**Import:** `from solace_agent_mesh.gateway.http_sse.services.data_retention_service import DataRetentionService`
+
+**Classes:**
+- `DataRetentionService(session_factory: Callable[[], DBSession] | None, config: Dict[str, Any])` - Service for automatic data cleanup based on retention policies
+  - `cleanup_old_data() -> None` - Main orchestration method for cleaning up old data, calls cleanup methods for tasks and feedback
+
+**Constants/Variables:**
+- `MIN_RETENTION_DAYS: int` - Minimum retention period (7 days)
+- `MIN_CLEANUP_INTERVAL_HOURS: int` - Minimum cleanup interval (1 hour)
+- `MIN_BATCH_SIZE: int` - Minimum batch size for deletion (1)
+- `MAX_BATCH_SIZE: int` - Maximum batch size for deletion (10000)
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.services.data_retention_service import DataRetentionService
+from sqlalchemy.orm import sessionmaker
+
+# Initialize with database session factory and config
+session_factory = sessionmaker(bind=your_engine)
+config = {
+    "enabled": True,
+    "task_retention_days": 90,
+    "feedback_retention_days": 90,
+    "cleanup_interval_hours": 24,
+    "batch_size": 1000
+}
+
+retention_service = DataRetentionService(
+    session_factory=session_factory,
+    config=config
+)
+
+# Run cleanup (typically called by scheduler)
+retention_service.cleanup_old_data()
+```
+
+### feedback_service.py
+**Purpose:** Handles the business logic for processing and storing user feedback with database persistence and event publishing
+**Import:** `from solace_agent_mesh.gateway.http_sse.services.feedback_service import FeedbackService`
+
+**Classes:**
+- `FeedbackService(session_factory: Callable[[], DBSession] | None, component: WebUIBackendComponent, task_repo: ITaskRepository)` - Service for processing user feedback with database persistence and event publishing
+  - `process_feedback(payload: FeedbackPayload, user_id: str) -> None` - Asynchronously processes and stores feedback, publishes events if configured
+
+**Usage Examples:**
+```python
+import asyncio
+from solace_agent_mesh.gateway.http_sse.services.feedback_service import FeedbackService
+from sqlalchemy.orm import sessionmaker
+
+# Initialize with database session factory
+session_factory = sessionmaker(bind=your_engine)
+component = YourWebUIBackendComponent()  # Your component instance
+task_repo = YourTaskRepository()  # Your task repository
+
+feedback_service = FeedbackService(
+    session_factory=session_factory,
+    component=component,
+    task_repo=task_repo
+)
+
+# Process feedback (requires FeedbackPayload from router)
+async def process_user_feedback():
+    # payload would be a FeedbackPayload instance from the router
+    await feedback_service.process_feedback(payload, user_id="user123")
+
+asyncio.run(process_user_feedback())
+```
+
 ### people_service.py
 **Purpose:** Provides user search functionality via configured identity services
 **Import:** `from solace_agent_mesh.gateway.http_sse.services.people_service import PeopleService`
@@ -76,6 +151,95 @@ people_service_no_id = PeopleService(identity_service=None)
 asyncio.run(search_users())
 ```
 
+### session_service.py
+**Purpose:** Manages chat sessions and messages with database persistence support
+**Import:** `from solace_agent_mesh.gateway.http_sse.services.session_service import SessionService`
+
+**Classes:**
+- `SessionService(component: WebUIBackendComponent = None)` - Service for managing chat sessions and messages
+  - `is_persistence_enabled() -> bool` - Checks if the service is configured with a persistent backend
+  - `get_user_sessions(db: DbSession, user_id: UserId, pagination: PaginationParams | None = None) -> PaginatedResponse[Session]` - Retrieves paginated sessions for a user
+  - `get_session_details(db: DbSession, session_id: SessionId, user_id: UserId) -> Session | None` - Gets session details for a specific session
+  - `get_session_history(db: DbSession, session_id: SessionId, user_id: UserId, pagination: PaginationInfo | None = None) -> SessionHistory | None` - Gets session with messages
+  - `create_session(db: DbSession, user_id: UserId, name: str | None = None, agent_id: str | None = None, session_id: str | None = None) -> Optional[Session]` - Creates a new session
+  - `update_session_name(db: DbSession, session_id: SessionId, user_id: UserId, name: str) -> Session | None` - Updates session name
+  - `delete_session_with_notifications(db: DbSession, session_id: SessionId, user_id: UserId) -> bool` - Deletes session and notifies agents
+  - `add_message_to_session(db: DbSession, session_id: SessionId, user_id: UserId, message: str, sender_type: SenderType, sender_name: str, agent_id: str | None = None, message_type: MessageType = MessageType.TEXT) -> Message` - Adds a message to a session
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.services.session_service import SessionService
+from solace_agent_mesh.gateway.http_sse.shared.enums import SenderType, MessageType
+from sqlalchemy.orm import Session as DbSession
+
+# Initialize with component
+component = YourWebUIBackendComponent()  # Your component
+session_service = SessionService(component=component)
+
+# Use with database session
+with your_session_factory() as db:
+    # Create a new session
+    session = session_service.create_session(
+        db=db,
+        user_id="user123",
+        name="My Chat Session",
+        agent_id="assistant-agent"
+    )
+
+    # Add a message to the session
+    message = session_service.add_message_to_session(
+        db=db,
+        session_id=session.id,
+        user_id="user123",
+        message="Hello, how can you help me?",
+        sender_type=SenderType.USER,
+        sender_name="John Doe"
+    )
+
+    # Get user's sessions with pagination
+    paginated_sessions = session_service.get_user_sessions(db, "user123")
+    
+    db.commit()
+```
+
+### task_logger_service.py
+**Purpose:** Service for logging A2A tasks and events to the database with configurable filtering and sanitization
+**Import:** `from solace_agent_mesh.gateway.http_sse.services.task_logger_service import TaskLoggerService`
+
+**Classes:**
+- `TaskLoggerService(session_factory: Callable[[], DBSession] | None, config: Dict[str, Any])` - Service for logging A2A tasks and events to database
+  - `log_event(event_data: Dict[str, Any]) -> None` - Parses a raw A2A message and logs it as a task event, creates or updates master task record
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.services.task_logger_service import TaskLoggerService
+from sqlalchemy.orm import sessionmaker
+
+# Initialize with database session factory and config
+session_factory = sessionmaker(bind=your_engine)
+config = {
+    "enabled": True,
+    "log_status_updates": True,
+    "log_artifact_events": False,
+    "log_file_parts": True,
+    "max_file_part_size_bytes": 102400
+}
+
+task_logger = TaskLoggerService(
+    session_factory=session_factory,
+    config=config
+)
+
+# Log an A2A event
+event_data = {
+    "topic": "sam/agents/my-agent/request",
+    "payload": {"id": "task-123", "method": "sendMessage"},
+    "user_properties": {"userId": "user@example.com"}
+}
+
+task_logger.log_event(event_data)
+```
+
 ### task_service.py
 **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`
@@ -130,4 +294,4 @@ async def cancel_task_example():
 asyncio.run(cancel_task_example())
 ```
 
-# content_hash: 83ddf6b403dc50598ed550e4b3a5445f832b3956dad75f7a3fbbb7e6e5c6c115
+# content_hash: 12385f5117d2f5c30f0e44a0913ea91d62722aa82eb55268ae6bd317311ec5eb