solace-agent-mesh 0.0.1__py3-none-any.whl → 0.1.1__py3-none-any.whl

solace_agent_mesh/common/mysql_database.py

@@ -0,0 +1,40 @@
+"""Manage a MySQL database connection."""
+
+import mysql.connector
+
+class MySQLDatabase:
+    def __init__(self, host: str, user: str, password: str, database: str):
+        self.host = host
+        self.user = user
+        self.password = password
+        self.database = database
+        self.connection = None
+
+        if ":" in self.host:
+            self.host, self.port = self.host.split(":")
+        else:
+            self.port = 3306
+
+    def cursor(self, **kwargs):
+        if self.connection is None:
+            self.connect()
+        try:
+            return self.connection.cursor(**kwargs)
+        except mysql.connector.errors.OperationalError:
+            self.connect()
+            return self.connection.cursor(**kwargs)
+
+    def connect(self):
+        return mysql.connector.connect(
+            host=self.host,
+            port=self.port,
+            user=self.user,
+            password=self.password,
+            database=self.database,
+            raise_on_warnings=False,
+            connection_timeout=60,
+            autocommit=True,
+        )
+
+    def close(self):
+        self.connection.close()

solace_agent_mesh/common/postgres_database.py

@@ -0,0 +1,79 @@
+"""Manage a PostgreSQL database connection."""
+
+import psycopg2
+import psycopg2.extras
+from solace_ai_connector.common.log import log
+
+
+class PostgreSQLDatabase:
+    def __init__(self, host: str, user: str, password: str, database: str):
+        self.host = host
+        self.user = user
+        self.password = password
+        self.database = database
+        self.connection = None
+
+        if ":" in self.host:
+            self.host, self.port = self.host.split(":")
+        else:
+            self.port = 5432
+
+    def cursor(self, **kwargs):
+        if self.connection is None or self.connection.closed:
+            self.connect()
+        try:
+            return self.connection.cursor(**kwargs)
+        except Exception:  # pylint: disable=broad-except
+            self.connect()
+            return self.connection.cursor(**kwargs)
+
+    def connect(self, auto_commit=True):
+        self.connection = psycopg2.connect(
+            host=self.host,
+            port=self.port,
+            user=self.user,
+            password=self.password,
+            database=self.database,
+            connect_timeout=10,
+        )
+        self.connection.autocommit = auto_commit
+
+    def close(self):
+        self.connection.close()
+
+    def execute(self, query, params=None):
+        sanity = 3
+        while True:
+            try:
+                cursor = self.cursor(cursor_factory=psycopg2.extras.RealDictCursor)
+                cursor.execute(query, params)
+                break
+            except Exception as e:
+                log.error("Database error: %s", e)
+                sanity -= 1
+                if sanity == 0:
+                    raise e
+
+        return cursor
+
+def get_db_for_action(action_obj):
+    sql_host = action_obj.get_config("sql_host")
+    sql_user = action_obj.get_config("sql_user")
+    sql_password = action_obj.get_config("sql_password")
+    sql_database = action_obj.get_config("sql_database")
+    sql_db = None
+
+    if sql_host and sql_user and sql_password and sql_database:
+        sql_db = PostgreSQLDatabase(
+            host=sql_host,
+            user=sql_user,
+            password=sql_password,
+            database=sql_database,
+        )
+
+    if sql_db is None:
+        raise ValueError(
+            f"SQL database expected but not configured on {action_obj.__class__.__name__}"
+        )
+
+    return sql_db

solace_agent_mesh/common/prompt_templates.py

@@ -0,0 +1,30 @@
+from typing import List
+from langchain_core.messages import HumanMessage
+
+import yaml
+
+
+def FilterLocationsSystemPrompt(locations: List[str]) -> str:
+    return f"""
+You will use your geographical knowledge to filter the following list of locations
+into a list of locations that fall within the user's request. Those locations
+must be returned in a yaml array of the following schema:
+
+<response-schema-yaml>
+matching_locations:
+  - <location1>
+  - <location2>
+  ...
+</response-schema-yaml>
+
+<locations>
+{yaml.dump(locations)}
+"""
+
+
+def FilterLocationsUserPrompt(location_filter: str) -> HumanMessage:
+    return f"""
+<user-location-filter>
+{location_filter}
+</user-location-filter>
+"""

solace_agent_mesh/common/prompt_templates_unused_delete.py

@@ -0,0 +1,161 @@
+from langchain_core.messages import HumanMessage
+import yaml
+
+
+def RagWithBundleSummarySystemPrompt() -> str:
+    return """
+    You are the first stage in providing a great answer to a user's question
+    about Solace products. To get a great answer, you must work with the
+    user to ensure that their question is sufficiently unambiguous and
+    detailed. Specifically, with Solace products it is important to ensure that
+    the correct operational context is provided when necessary, since Solace brokers
+    can be appliances, self-managed software instances (VMs, containers, ...) or they 
+    could be using Solace Cloud. Each of these operational contexts can have different
+    configurations and requirements. However, if the question is about a feature that
+    is common to all Solace products, then that context is not necessary. Make sure that
+    the question is clear and detailed enough to provide a good answer.
+    
+    Along with their query, you are provided with summaries of all the bundles of documentation
+    available to retrieve answers to the user's question. If the question is sufficiently
+    detailed, then for each bundle summary, you must give it a relevance score from 0 to 5, where 5 is
+    indicates that the bundle will very likely answer the question, and 0 indicates that
+    the bundle is not relevant to the question. If the question is not detailed enough,
+    then you must ask the user for more information to clarify the question. For questions
+    relating to the Software broker, make user you include the Software Broker bundle. Similarly,
+    for Appliances, include the Appliance bundle and for Solace Cloud, include the Solace Cloud bundle.
+    
+    When selecting bundles, you must return an object with the bundle indexes as keys and
+    the relevance scores as values. List the bundles in the order that they are provided to
+    you and give each one a score.
+    
+    Some things that you should consider when scoring the bundles are:
+     - The term 'services' refers to all the protocols and input/outputs of the brokers. All information
+       about ports, protocols, and services should be in the 'services' bundle.
+     - When dealing specifically with default port values, it is necessary to go to the platform-specific
+       bundle. For example, the default port for the Software broker is different from the default port for
+       the appliance or Solace Cloud instance. The general services page has default port info but it might be wrong.
+     - 'gather-diagnostics' is a highly used term relating to debugging and troubleshooting of the brokers. Getting these
+       diagnostics varies greatly between the different types of brokers.
+      
+    
+    The answer must follow this YAML format:
+    
+    Either: (for when the question does not need further clarification)
+    <response>
+        bundles: 
+          0: <score0>
+          1: <score1>
+          ...
+        query: <clarified-question>
+    </response>
+    
+    or: (for when the question needs further clarification)
+    <response>
+        question: <clarification-question>
+    </response>
+    
+  <example-request-1>  
+      query: How do I get 'gather diagnostics' on a Solace broker?
+  </example-request-1>
+  <example-response-1>
+    <response>
+        question: Are you asking about a Solace appliance, a software broker or a Solace Cloud instance?
+    </response>
+  </example-response-1>
+  <example-response-2>
+    <response>
+        bundles: 
+          0: 5
+          1: 2
+          2: 0
+          3: 3
+        query: How do I configure a Solace broker to use TLS?
+    </response>
+  </example-response-2>
+  <example-response-3>
+    <response>
+        question: Are you running the software broker yourself or through Solace Cloud?
+    </response>
+  </example-response-3>
+  <example-response-4>
+    <response>
+        bundles: 
+          0: 0
+          1: 5
+          2: 3
+        query: How do I get 'gather diagnostics' on a Solace broker?
+    </response>
+  </example-response-4>
+        """
+
+
+def RagWithBundleSummaryUserPrompt(query: str, bundle_content: str):
+    return f"""
+    <user-query>\n{query}</user-query>\n\n<bundles>\n{bundle_content}\n</bundles>\n
+    
+    Reminder, use the context above to answer this query:
+    <user-query-reminder>\n{query}</user-query-reminder>\n
+    """
+
+
+def RagWithBundleSummarySystemPromptPart2() -> str:
+    return """
+    You are the second stage in providing a great answer to a user's question
+    about Solace products. Your task is to take the user's question and the
+    context provided below and use that context to provide a well-thoughtout and
+    professional answer in markdown. The answer should be detailed enough to
+    provide the user with the information they need, but it should not be overly
+    verbose. The answer should be written in a professional tone and should be
+    free of spelling and grammatical errors. Always provide links to the source
+    of the information, which is given above the context starting with 'Page: ...'.
+
+    If you can't find the answer in the provided context, you must state that the
+    information that you have is insufficient to answer the question.
+    
+    No not add any information that is not in the context provided. Don't trust the
+    general services page (Managing-Services) for default port information. The default
+    port for the Software broker is different from the default port for the appliance or
+    Solace Cloud instance. Look deeper for that information. 
+    
+    Solace CLI commands are immediately persisted. It is not necessary to 'write memory' or 
+    'commit' the configuration. The user knows this, so there is no need to
+    mention it in the answer.
+
+    When providing an answer it is essential to provide links to the source of the
+    data as shown in the context below (Page: ...)
+  """
+
+
+def RagWithBundleSummaryUserPromptPart2(query: str, context: str):
+    return f"""
+    <user-query>\n{query}</user-query>\n\n<answer-context>\n{context}\n</answer-context>\n
+    
+    Reminder, use the context above to answer this query: (and keep answers to only the context provided)
+    <user-query-reminder>\n{query}</user-query-reminder>
+    <rule>Add links to the source of the information in the context - important</rule>
+    """
+
+
+def RagWithBundleSummaryUserPromptClarificationQuestion(question: str):
+    return f"To clarify the customer documentation query, you must ask the user the following question: {question} and then perform the customer documentation query again."
+
+
+def ChannelHistoryQueryPrompt(query: str, history_messages: list) -> HumanMessage:
+    return HumanMessage(
+        content=f"""
+You (orchestrator) are being asked to query the channel history with the following query:
+<channel_history_query>
+{query}
+</channel_history_query>
+
+The messages in the channel history are shown below with the most recent first. You should use this information to answer the query.
+You should return a send_message action with the answer to the query.
+<channel_history_messages>
+{yaml.dump(history_messages)}
+</channel_history_messages>
+"""
+    )
+
+
+def BasicStatementPrompt(statement: str) -> HumanMessage:
+    return HumanMessage(content=statement)

solace_agent_mesh/common/stimulus_utils.py

@@ -0,0 +1,152 @@
+"""Utilities for describing stimulus state and events.
+
+This module provides functions for generating human-readable descriptions
+of stimulus state, including events, errors and completion status.
+"""
+
+from typing import Dict, List
+import time
+import json
+
+from solace_ai_connector.common.log import log
+from ..services.file_service import FileService
+
+
+def _format_timestamp(timestamp: float) -> str:
+    """Formats a Unix timestamp into a human readable string.
+
+    Args:
+        timestamp: Unix timestamp to format
+
+    Returns:
+        Formatted timestamp string in YYYY-MM-DD HH:MM:SS format
+    """
+    return time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(timestamp))
+
+
+def _format_event(event: Dict) -> str:
+    """Formats a single stimulus event into markdown.
+
+    Args:
+        event: Dictionary containing event details including topic, payload,
+            user properties and timestamp
+
+    Returns:
+        Markdown formatted string describing the event
+    """
+    timestamp = _format_timestamp(event.get("timestamp", 0))
+    topic = event.get("topic", "")
+    payload = event.get("payload", {})
+    user_props = event.get("user_properties", {})
+
+    # Format based on topic pattern, similar to ConversationFormatter
+    if "/stimulus/" in topic:
+        stimulus_text = payload.get("text", "")
+        identity = user_props.get("identity", "unknown")
+        if "/reinvoke" in topic:
+            return f"### {timestamp} - Reinvoke Request\nFrom: {identity}\n```\n{stimulus_text}\n```\n"
+        return f"### {timestamp} - Initial Request\nFrom: {identity}\n```\n{stimulus_text}\n```\n"
+
+    if "/response/" in topic or "/streamingResponse/" in topic:
+        if isinstance(payload, dict) and payload.get("last_chunk") is True:
+            response_text = payload.get("text", "")
+            return f"### {timestamp} - Response:\n{response_text}\n\n"
+        return ""
+
+    if "/responseComplete/" in topic:
+        return f"### {timestamp} - Response Complete\n"
+
+    if "/actionRequest/" in topic:
+        action_name = payload.get("action_name", "")
+        action_params = payload.get("action_params", {})
+        params_text = "\n".join(f"- {k}: {v}" for k, v in action_params.items())
+        return f"### {timestamp} - Action Request: {action_name}\n{params_text}\n"
+
+    if "/actionResponse/" in topic:
+        topic_parts = topic.split("/agent/")[1].split("/")
+        agent_name = topic_parts[0]
+        action_name = topic_parts[1]
+        response_text = "\n".join(f"- {k}: {v}" for k, v in payload.items())
+        return f"### {timestamp} - Action Response: {agent_name}.{action_name}\n{response_text}\n"
+
+    return f"### {timestamp} - Other Event\nTopic: {topic}\n"
+
+
+def _format_error(error: Dict) -> str:
+    """Formats a single stimulus error into markdown.
+
+    Args:
+        error: Dictionary containing error details including message,
+            timestamp and user properties
+
+    Returns:
+        Markdown formatted string describing the error
+    """
+    timestamp = _format_timestamp(error.get("timestamp", 0))
+    message = error.get("message", "Unknown error")
+    source = error.get("source", "Unknown source")
+    return f"### {timestamp} - Error\nSource: {source}\nDetails: {message}\n"
+
+
+def describe_stimulus(stimulus_uuid: str, state: Dict, is_timeout: bool = False) -> str:
+    """Generates a markdown description of a stimulus's complete state.
+
+    Takes a stimulus state dictionary and generates a human-readable markdown
+    description including all events, errors and completion status.
+
+    Args:
+        stimulus_uuid: UUID of the stimulus
+        state: Dictionary containing complete stimulus state including events,
+            errors and metadata
+        is_timeout: Whether this stimulus timed out
+
+    Returns:
+        Markdown formatted string describing the complete stimulus journey
+    """
+    events: List[Dict] = state.get("events", [])
+    errors: List[Dict] = state.get("errors", [])
+    completion_status = state.get("completion_status", "unknown")
+
+    # Start with header
+    description = f"# Stimulus {stimulus_uuid}\n\n"
+
+    # Add completion status with timeout indicator if applicable
+    status_str = completion_status.upper()
+    if is_timeout:
+        status_str += " (TIMED OUT)"
+    description += f"**Status:** {status_str}\n\n"
+
+    # Add events section
+    if events:
+        description += "## Events\n\n"
+        for event in events:
+            description += _format_event(event)
+
+    # Add errors section
+    if errors:
+        description += "\n## Errors\n\n"
+        for error in errors:
+            description += _format_error(error)
+
+    # Add any available files
+    available_files_json = (
+        events[-1].get("user_properties", {}).get("available_files", None)
+    )
+    available_files = []
+    if available_files_json:
+        try:
+            available_files_user_prop = json.loads(available_files_json)
+            if available_files_user_prop:
+                file_service = FileService()
+                available_files = [
+                    file_service.get_file_block_by_metadata(file)
+                    for file in available_files_user_prop
+                ]
+        except Exception as e:
+            log.error("Failed to get available files: %s", str(e))
+
+        if available_files:
+            description += "\n## Available Files\n\n"
+            description += "\n\n".join(available_files)
+
+    return description

solace_agent_mesh/common/time.py

@@ -0,0 +1,24 @@
+ONE_DAY = 86400
+"""
+Number of seconds in a day.
+"""
+
+ONE_HOUR = 3600
+"""
+Number of seconds in an hour.
+"""
+
+THIRTY_MINUTES = 1800
+"""
+Number of seconds in thirty minutes.
+"""
+
+TEN_MINUTES = 600
+"""
+Number of seconds in ten minutes.
+"""
+
+FIVE_MINUTES = 300
+"""
+Number of seconds in five minutes.
+"""