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

solace_agent_mesh/gateway/http_sse/services/prompt_builder_assistant.py

@@ -0,0 +1,303 @@
+"""
+AI Assistant for Prompt Template Builder.
+Manages conversational prompt template creation through natural language.
+"""
+
+import json
+import logging
+import os
+import re
+from typing import Dict, Any, List, Optional
+from pydantic import BaseModel, Field
+from litellm import acompletion
+from sqlalchemy.orm import Session
+
+logger = logging.getLogger(__name__)
+
+
+class PromptBuilderResponse(BaseModel):
+    """Response from the prompt builder assistant."""
+    message: str
+    template_updates: Dict[str, Any] = Field(default_factory=dict)
+    confidence: float = Field(ge=0.0, le=1.0)
+    ready_to_save: bool = False
+
+
+class PromptBuilderAssistant:
+    """
+    AI assistant for prompt template creation.
+    Manages conversation flow and template generation.
+    """
+    
+    SYSTEM_PROMPT = """You are an AI assistant helping users create reusable prompt templates.
+
+CRITICAL RULES:
+1. You MUST respond with valid JSON in this exact format - NO EXCEPTIONS
+2. You MUST always include a "message" field with a helpful, conversational response
+3. NEVER respond with just "I understand" - always provide actionable guidance
+4. ONLY create placeholders for DATA that changes (names, paths, dates, numbers, specific values)
+5. Keep instructions, steps, requirements, and process descriptions as FIXED TEXT
+6. Use descriptive variable names in Title Case (e.g., {{File Path}}, {{Module Name}})
+7. Suggest appropriate categories (Development, Analysis, Documentation, Communication, Testing, etc.)
+8. Generate short command names (lowercase, hyphens only)
+
+RESPONSE FORMAT (REQUIRED):
+{{
+  "message": "your conversational response here - MUST be helpful and specific",
+  "template_updates": {{
+    "name": "Name",
+    "category": "Category",
+    "command": "command-name",
+    "promptText": "Template with {{placeholders}} for variable data only",
+    "description": "Brief description"
+  }},
+  "confidence": 0.0-1.0,
+  "ready_to_save": false
+}}
+
+VARIABLE PLACEHOLDER RULES:
+- Use {{Variable Name}} format for placeholders (Title Case with spaces)
+- ONLY for data that changes: file paths, names, dates, numbers, specific values
+- NOT for instructions, steps, or requirements
+- Use descriptive names: {{File Path}}, {{Module Name}}, {{Task Description}}
+
+EXAMPLES:
+
+Example 1: Code Review Template
+User: "I need a template for code reviews"
+{{
+  "message": "Great! I'll create a code review template. What information changes each time you do a code review? For example: file path, module name, specific concerns?",
+  "template_updates": {{
+    "name": "Code Review Template",
+    "category": "Development"
+  }},
+  "confidence": 0.6,
+  "ready_to_save": false
+}}
+
+User: "The file path, module name, and specific security concerns"
+{{
+  "message": "Perfect! I've created a code review template with placeholders for file path, module name, and security concerns. Check the preview on the left!",
+  "template_updates": {{
+    "name": "Code Review Template",
+    "category": "Development",
+    "command": "code-review",
+    "promptText": "Review the {{Module Name}} module located at {{File Path}}.\\n\\nPlease perform a comprehensive code review focusing on:\\n1. Security vulnerabilities\\n2. Error handling\\n3. Code quality and best practices\\n4. Specific attention to: {{Security Concerns}}\\n\\nProvide a detailed report with:\\n- List of issues with severity levels\\n- Specific code snippets that need attention\\n- Recommendations for improvements",
+    "description": "Template for code review with security focus"
+  }},
+  "confidence": 0.9,
+  "ready_to_save": true
+}}
+
+Example 2: Bug Report Template
+User: "Create a bug report template"
+{{
+  "message": "I'll create a bug report template! What details vary for each bug report? For example: bug description, steps to reproduce, expected vs actual behavior?",
+  "template_updates": {{
+    "name": "Bug Report Template",
+    "category": "Testing"
+  }},
+  "confidence": 0.6,
+  "ready_to_save": false
+}}
+
+User: "Bug description, steps to reproduce, and environment details"
+{{
+  "message": "Excellent! I've created a bug report template with those placeholders. You can see it in the preview!",
+  "template_updates": {{
+    "name": "Bug Report Template",
+    "category": "Testing",
+    "command": "bug-report",
+    "promptText": "# Bug Report\\n\\n## Description\\n{{Bug Description}}\\n\\n## Steps to Reproduce\\n{{Steps To Reproduce}}\\n\\n## Environment\\n{{Environment Details}}\\n\\n## Expected Behavior\\nDescribe what should happen\\n\\n## Actual Behavior\\nDescribe what actually happens\\n\\n## Additional Context\\nAny other relevant information",
+    "description": "Template for reporting bugs with structured format"
+  }},
+  "confidence": 0.9,
+  "ready_to_save": true
+}}
+
+REMEMBER:
+- Ask clarifying questions to understand what data changes
+- Create detailed, useful templates
+- Only use placeholders for variable data
+- Keep instructions and structure as fixed text
+- Set ready_to_save to true when template is complete
+"""
+    
+    def __init__(self, db: Optional[Session] = None, model_config: Optional[Dict[str, Any]] = None):
+        """Initialize the assistant with model configuration from component config."""
+        self.system_prompt = self.SYSTEM_PROMPT
+        self.db = db
+        
+        # Get LLM configuration from provided config
+        if not model_config or not isinstance(model_config, dict):
+            raise ValueError("model_config is required and must be a dictionary")
+        
+        if not model_config.get("model"):
+            raise ValueError("model_config must contain 'model' key")
+        
+        self.model = model_config.get("model")
+        self.api_base = model_config.get("api_base")
+        self.api_key = model_config.get("api_key", "dummy")
+    
+    def _get_existing_commands(self, user_id: str) -> List[str]:
+        """Get list of existing command shortcuts to avoid conflicts."""
+        if not self.db:
+            return []
+        
+        try:
+            from ..repository.models import PromptGroupModel
+            
+            groups = self.db.query(PromptGroupModel).filter(
+                PromptGroupModel.user_id == user_id,
+                PromptGroupModel.command.isnot(None)
+            ).all()
+            
+            return [group.command for group in groups if group.command]
+        except Exception as e:
+            logger.error(f"Error fetching existing commands: {e}")
+            return []
+    
+    async def process_message(
+        self,
+        user_message: str,
+        conversation_history: List[Dict[str, str]],
+        current_template: Dict[str, Any],
+        user_id: Optional[str] = None
+    ) -> PromptBuilderResponse:
+        """
+        Process user message and update template using LLM.
+        
+        Args:
+            user_message: The user's message
+            conversation_history: Previous conversation messages
+            current_template: Current template configuration
+            
+        Returns:
+            PromptBuilderResponse with updates
+        """
+        try:
+            return await self._llm_response(
+                user_message,
+                conversation_history,
+                current_template,
+                user_id
+            )
+        except Exception as e:
+            logger.error(f"Error processing message: {e}", exc_info=True)
+            return PromptBuilderResponse(
+                message="I encountered an error. Could you please rephrase that?",
+                confidence=0.0,
+                ready_to_save=False
+            )
+    
+    async def _llm_response(
+        self,
+        user_message: str,
+        conversation_history: List[Dict[str, str]],
+        current_template: Dict[str, Any],
+        user_id: Optional[str] = None
+    ) -> PromptBuilderResponse:
+        """Use LLM to generate response and template updates."""
+        
+        # Get existing commands to avoid conflicts
+        existing_commands = []
+        if user_id and self.db:
+            existing_commands = self._get_existing_commands(user_id)
+        
+        # Build messages for LLM
+        messages = [
+            {"role": "system", "content": self.system_prompt}
+        ]
+        
+        # Add conversation history
+        messages.extend(conversation_history)
+        
+        # Add current message with template context and existing commands
+        template_context = f"\n\nCurrent Template:\n{json.dumps(current_template, indent=2)}"
+        
+        commands_context = ""
+        if existing_commands:
+            commands_context = f"\n\nEXISTING COMMANDS (avoid these):\n{', '.join(['/' + cmd for cmd in existing_commands])}"
+        
+        messages.append({
+            "role": "user",
+            "content": user_message + template_context + commands_context
+        })
+        
+        # Call LLM with JSON mode
+        try:
+            completion_args = {
+                "model": self.model,
+                "messages": messages,
+                "response_format": {"type": "json_object"},
+                "temperature": 0.1,  # Low temperature for consistency
+            }
+            
+            if self.api_base:
+                completion_args["api_base"] = self.api_base
+            if self.api_key:
+                completion_args["api_key"] = self.api_key
+            
+            response = await acompletion(**completion_args)
+            
+            # Parse response
+            content = response.choices[0].message.content
+            logger.info(f"LLM Response: {content}")
+            
+            try:
+                parsed = json.loads(content)
+            except json.JSONDecodeError as e:
+                logger.error(f"Failed to parse LLM response as JSON: {e}")
+                logger.error(f"Response content: {content}")
+                # Try to extract JSON from response
+                json_match = re.search(r'\{.*\}', content, re.DOTALL)
+                if json_match:
+                    parsed = json.loads(json_match.group())
+                else:
+                    raise
+            
+            # Handle nested response structure (some LLMs wrap in various keys)
+            if "response" in parsed and isinstance(parsed["response"], dict):
+                logger.info("Unwrapping nested 'response' structure from LLM")
+                parsed = parsed["response"]
+            
+            # Handle case where LLM wraps response in an arbitrary key (e.g., "{}", "result", etc.)
+            # If we don't have a "message" key but have exactly one key with a dict value containing "message"
+            if "message" not in parsed and len(parsed) == 1:
+                single_key = list(parsed.keys())[0]
+                if isinstance(parsed[single_key], dict) and "message" in parsed[single_key]:
+                    logger.info(f"Unwrapping nested structure from key '{single_key}'")
+                    parsed = parsed[single_key]
+            
+            # Validate that we have a proper message
+            message = parsed.get("message", "")
+            if not message or message.strip().lower() in ["i understand", "i understand.", "ok", "okay"]:
+                logger.warning(f"LLM returned generic/empty message: '{message}'")
+                message = "I'll help you create that template. Could you provide more details about what information changes each time you use this prompt?"
+            
+            return PromptBuilderResponse(
+                message=message,
+                template_updates=parsed.get("template_updates", {}),
+                confidence=parsed.get("confidence", 0.5),
+                ready_to_save=parsed.get("ready_to_save", False)
+            )
+            
+        except Exception as e:
+            logger.error(f"LLM call failed: {e}", exc_info=True)
+            # Fallback response with helpful guidance
+            return PromptBuilderResponse(
+                message="I'm having trouble processing that. Could you describe what you'd like this template to do? For example, what task are you trying to automate or what information changes each time?",
+                confidence=0.3,
+                ready_to_save=False
+            )
+    
+    def get_initial_greeting(self) -> PromptBuilderResponse:
+        """Get the initial greeting message."""
+        return PromptBuilderResponse(
+            message="Hi! I'll help you create a prompt template. You can either:\n\n"
+                   "1. Describe a recurring task you'd like to template\n"
+                   "2. Paste an example transcript of the task\n\n"
+                   "What would you like to create a template for?",
+            confidence=1.0,
+            ready_to_save=False
+        )

solace_agent_mesh/gateway/http_sse/services/services_llm.txt

@@ -0,0 +1,303 @@
+# 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 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_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
+- `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
+
+### __init__.py
+**Purpose:** Marks the services directory as a Python package
+**Import:** N/A - No public interfaces
+
+### 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_card_service import AgentCardService`
+
+**Classes:**
+- `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_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 = AgentCardService(agent_registry=agent_registry)
+
+# Get all available 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_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 (1 day)
+- `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`
+
+**Classes:**
+- `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 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)
+    for user in users:
+        print(f"User: {user.get('name')} - {user.get('email')}")
+
+# Initialize without identity service (graceful degradation)
+people_service_no_id = PeopleService(identity_service=None)
+# search_for_users will return empty list
+
+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
+  - `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
+  - `save_task(db: DbSession, task_id: str, session_id: str, user_id: str, user_message: Optional[str], message_bubbles: str, task_metadata: Optional[str] = None) -> ChatTask` - Saves a complete task interaction
+  - `get_session_tasks(db: DbSession, session_id: str, user_id: str) -> List[ChatTask]` - Gets all tasks for a session
+  - `get_session_messages_from_tasks(db: DbSession, session_id: str, user_id: str) -> List[Dict[str, Any]]` - Gets session messages by flattening task message_bubbles for backward compatibility
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.services.session_service import SessionService
+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"
+    )
+
+    # Save a task with message bubbles
+    import json
+    message_bubbles = json.dumps([
+        {"type": "user", "text": "Hello", "id": "msg1"},
+        {"type": "agent", "text": "Hi there!", "id": "msg2"}
+    ])
+    
+    task = session_service.save_task(
+        db=db,
+        task_id="task-123",
+        session_id=session.id,
+        user_id="user123",
+        user_message="Hello",
+        message_bubbles=message_bubbles
+    )
+
+    # 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`
+
+**Type Aliases:**
+- `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 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="data-processor",
+        task_id="task-123",
+        client_id="client-456",
+        user_id="user@example.com"
+    )
+
+asyncio.run(cancel_task_example())
+```
+
+# content_hash: 09bc3008d9a6c148b0b9d7477d20b26514f7fc4ee72f36eda5348f8f7d51f2ea