solace-agent-mesh 0.2.4__py3-none-any.whl → 1.0.1__py3-none-any.whl

solace_agent_mesh/common/utils/embeds/types.py

@@ -0,0 +1,14 @@
+"""
+Defines types used within the embed processing system, like DataFormat.
+"""
+
+from enum import Enum, auto
+
+
+class DataFormat(Enum):
+    """Represents internal data formats during modifier chain execution."""
+
+    BYTES = auto()
+    STRING = auto()
+    JSON_OBJECT = auto()
+    LIST_OF_DICTS = auto()

solace_agent_mesh/common/utils/in_memory_cache.py

@@ -0,0 +1,108 @@
+"""In Memory Cache utility."""
+
+import threading
+import time
+from typing import Any, Dict, Optional
+
+
+class InMemoryCache:
+    """A thread-safe Singleton class to manage cache data.
+
+    Ensures only one instance of the cache exists across the application.
+    """
+
+    _instance: Optional["InMemoryCache"] = None
+    _lock: threading.Lock = threading.Lock()
+    _initialized: bool = False
+
+    def __new__(cls):
+        """Override __new__ to control instance creation (Singleton pattern).
+
+        Uses a lock to ensure thread safety during the first instantiation.
+
+        Returns:
+            The singleton instance of InMemoryCache.
+        """
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        """Initialize the cache storage.
+
+        Uses a flag (_initialized) to ensure this logic runs only on the very first
+        creation of the singleton instance.
+        """
+        if not self._initialized:
+            with self._lock:
+                if not self._initialized:
+                    self._cache_data: Dict[str, Dict[str, Any]] = {}
+                    self._ttl: Dict[str, float] = {}
+                    self._data_lock: threading.Lock = threading.Lock()
+                    self._initialized = True
+
+    def set(self, key: str, value: Any, ttl: Optional[int] = None) -> None:
+        """Set a key-value pair.
+
+        Args:
+            key: The key for the data.
+            value: The data to store.
+            ttl: Time to live in seconds. If None, data will not expire.
+        """
+        with self._data_lock:
+            self._cache_data[key] = value
+
+            if ttl is not None:
+                self._ttl[key] = time.time() + ttl
+            else:
+                if key in self._ttl:
+                    del self._ttl[key]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get the value associated with a key.
+
+        Args:
+            key: The key for the data within the session.
+            default: The value to return if the session or key is not found.
+
+        Returns:
+            The cached value, or the default value if not found.
+        """
+        with self._data_lock:
+            if key in self._ttl and time.time() > self._ttl[key]:
+                del self._cache_data[key]
+                del self._ttl[key]
+                return default
+            return self._cache_data.get(key, default)
+
+    def delete(self, key: str) -> None:
+        """Delete a specific key-value pair from a cache.
+
+        Args:
+            key: The key to delete.
+
+        Returns:
+            True if the key was found and deleted, False otherwise.
+        """
+
+        with self._data_lock:
+            if key in self._cache_data:
+                del self._cache_data[key]
+                if key in self._ttl:
+                    del self._ttl[key]
+                return True
+            return False
+
+    def clear(self) -> bool:
+        """Remove all data.
+
+        Returns:
+            True if the data was cleared, False otherwise.
+        """
+        with self._data_lock:
+            self._cache_data.clear()
+            self._ttl.clear()
+            return True
+        return False

solace_agent_mesh/common/utils/log_formatters.py

@@ -0,0 +1,44 @@
+import logging
+import json
+import os
+from datetime import datetime, timezone
+import traceback
+
+
+class DatadogJsonFormatter(logging.Formatter):
+    """
+    Custom formatter to output logs in Datadog-compatible JSON format.
+    """
+
+    def format(self, record):
+        log_entry = {
+            "timestamp": datetime.fromtimestamp(
+                record.created, tz=timezone.utc
+            ).isoformat(),
+            "level": record.levelname,
+            "message": record.getMessage(),
+            "logger.name": record.name,
+            "logger.thread_name": record.threadName,
+            "service": os.getenv("SERVICE_NAME", "solace_agent_mesh"),
+            "code.filepath": record.pathname,
+            "code.lineno": record.lineno,
+            "code.module": record.module,
+            "code.funcName": record.funcName,
+        }
+
+        dd_trace_id = getattr(record, "dd.trace_id", None)
+        if dd_trace_id:
+            log_entry["dd.trace_id"] = dd_trace_id
+
+        dd_span_id = getattr(record, "dd.span_id", None)
+        if dd_span_id:
+            log_entry["dd.span_id"] = dd_span_id
+
+        if record.exc_info:
+            log_entry["exception.type"] = record.exc_info[0].__name__
+            log_entry["exception.message"] = str(record.exc_info[1])
+            log_entry["exception.stacktrace"] = "".join(
+                traceback.format_exception(*record.exc_info)
+            )
+
+        return json.dumps(log_entry)

solace_agent_mesh/common/utils/mime_helpers.py

@@ -0,0 +1,106 @@
+"""
+Utility functions for handling MIME types.
+"""
+
+from typing import Optional, Set
+
+TEXT_CONTAINER_MIME_TYPES: Set[str] = {
+    "text/plain",
+    "text/markdown",
+    "text/html",
+    "application/json",
+    "application/yaml",
+    "text/yaml",
+    "application/x-yaml",
+    "text/x-yaml",
+    "application/xml",
+    "text/xml",
+    "text/csv",
+}
+
+_TEXT_BASED_PRIMARY_TYPES = {"text"}
+_TEXT_BASED_SUBTYPE_WHOLE = {
+    "json",
+    "xml",
+    "yaml",
+    "csv",
+    "javascript",
+    "ecmascript",
+    "xhtml+xml",
+    "svg+xml",
+    "atom+xml",
+    "rss+xml",
+    "sparql-query",
+    "sparql-update",
+    "sql",
+    "graphql",
+    "markdown",
+    "html",
+    "rtf",
+    "sgml",
+}
+_TEXT_BASED_SUBTYPE_SUFFIXES_AFTER_PLUS = {
+    "json",
+    "xml",
+    "yaml",
+    "csv",
+    "svg",
+    "xhtml",
+}
+
+def is_text_based_mime_type(mime_type: Optional[str]) -> bool:
+    """
+    Checks if a given MIME type is considered text-based.
+
+    Args:
+        mime_type: The MIME type string (e.g., "text/plain", "application/json").
+
+    Returns:
+        True if the MIME type is text-based, False otherwise.
+    """
+    if not mime_type:
+        return False
+
+    normalized_mime_type = mime_type.lower().strip()
+
+    if normalized_mime_type.startswith("text/"):
+        return True
+
+    if normalized_mime_type in TEXT_CONTAINER_MIME_TYPES:
+        return True
+
+    return False
+
+
+def is_text_based_file(mime_type: Optional[str], content_bytes: Optional[bytes] = None) -> bool:
+    """
+    Determines if a file is text-based based on its MIME type and content.
+    Args:
+        mime_type: The MIME type of the file.
+        content_bytes: The content of the file as bytes.
+    Returns:
+        True if the file is text-based, False otherwise.
+    """
+    if not mime_type:
+        return False
+        
+    normalized_mime_type = mime_type.lower().strip()
+    primary_type, _, subtype = normalized_mime_type.partition("/")
+    
+    if primary_type in _TEXT_BASED_PRIMARY_TYPES:
+        return True
+    elif subtype in _TEXT_BASED_SUBTYPE_WHOLE:
+        return True
+    elif "+" in subtype:
+        specific_format = subtype.split("+")[-1]
+        if specific_format in _TEXT_BASED_SUBTYPE_SUFFIXES_AFTER_PLUS:
+            return True
+    elif normalized_mime_type == "application/octet-stream" and content_bytes is not None:
+        try:
+            sample_size = min(1024, len(content_bytes))
+            content_bytes[:sample_size].decode("utf-8")
+            return True
+        except UnicodeDecodeError:
+            return False
+        
+    return False

solace_agent_mesh/common/utils/push_notification_auth.py

@@ -0,0 +1,134 @@
+from jwcrypto import jwk
+import uuid
+from starlette.responses import JSONResponse
+from starlette.requests import Request
+from typing import Any
+
+import jwt
+import time
+import json
+import hashlib
+import httpx
+
+from solace_ai_connector.common.log import log
+
+from jwt import PyJWK, PyJWKClient
+
+AUTH_HEADER_PREFIX = "Bearer "
+
+
+class PushNotificationAuth:
+    def _calculate_request_body_sha256(self, data: dict[str, Any]):
+        """Calculates the SHA256 hash of a request body.
+
+        This logic needs to be same for both the agent who signs the payload and the client verifier.
+        """
+        body_str = json.dumps(
+            data,
+            ensure_ascii=False,
+            allow_nan=False,
+            indent=None,
+            separators=(",", ":"),
+        )
+        return hashlib.sha256(body_str.encode()).hexdigest()
+
+
+class PushNotificationSenderAuth(PushNotificationAuth):
+    def __init__(self):
+        self.public_keys = []
+        self.private_key_jwk: PyJWK = None
+
+    @staticmethod
+    async def verify_push_notification_url(url: str) -> bool:
+        async with httpx.AsyncClient(timeout=10) as client:
+            try:
+                validation_token = str(uuid.uuid4())
+                response = await client.get(
+                    url, params={"validationToken": validation_token}
+                )
+                response.raise_for_status()
+                is_verified = response.text == validation_token
+
+                log.info("Verified push-notification URL: %s => %s", url, is_verified)
+                return is_verified
+            except Exception as e:
+                log.warning(
+                    "Error during sending push-notification for URL %s: %s", url, e
+                )
+
+        return False
+
+    def generate_jwk(self):
+        key = jwk.JWK.generate(kty="RSA", size=2048, kid=str(uuid.uuid4()), use="sig")
+        self.public_keys.append(key.export_public(as_dict=True))
+        self.private_key_jwk = PyJWK.from_json(key.export_private())
+
+    def handle_jwks_endpoint(self, _request: Request):
+        """Allow clients to fetch public keys."""
+        return JSONResponse({"keys": self.public_keys})
+
+    def _generate_jwt(self, data: dict[str, Any]):
+        """JWT is generated by signing both the request payload SHA digest and time of token generation.
+
+        Payload is signed with private key and it ensures the integrity of payload for client.
+        Including iat prevents from replay attack.
+        """
+
+        iat = int(time.time())
+
+        return jwt.encode(
+            {
+                "iat": iat,
+                "request_body_sha256": self._calculate_request_body_sha256(data),
+            },
+            key=self.private_key_jwk,
+            headers={"kid": self.private_key_jwk.key_id},
+            algorithm="RS256",
+        )
+
+    async def send_push_notification(self, url: str, data: dict[str, Any]):
+        jwt_token = self._generate_jwt(data)
+        headers = {"Authorization": f"Bearer {jwt_token}"}
+        async with httpx.AsyncClient(timeout=10) as client:
+            try:
+                response = await client.post(url, json=data, headers=headers)
+                response.raise_for_status()
+                log.info("Push-notification sent for URL: %s", url)
+            except Exception as e:
+                log.warning(
+                    "Error during sending push-notification for URL %s: %s", url, e
+                )
+
+
+class PushNotificationReceiverAuth(PushNotificationAuth):
+    def __init__(self):
+        self.public_keys_jwks = []
+        self.jwks_client = None
+
+    async def load_jwks(self, jwks_url: str):
+        self.jwks_client = PyJWKClient(jwks_url)
+
+    async def verify_push_notification(self, request: Request) -> bool:
+        auth_header = request.headers.get("Authorization")
+        if not auth_header or not auth_header.startswith(AUTH_HEADER_PREFIX):
+            log.warning("Invalid authorization header")
+            return False
+
+        token = auth_header[len(AUTH_HEADER_PREFIX) :]
+        signing_key = self.jwks_client.get_signing_key_from_jwt(token)
+
+        decode_token = jwt.decode(
+            token,
+            signing_key,
+            options={"require": ["iat", "request_body_sha256"]},
+            algorithms=["RS256"],
+        )
+
+        actual_body_sha256 = self._calculate_request_body_sha256(await request.json())
+        if actual_body_sha256 != decode_token["request_body_sha256"]:
+            raise ValueError("Invalid request body")
+
+        if time.time() - decode_token["iat"] > 60 * 5:
+            raise ValueError("Token is expired")
+
+        return True

solace_agent_mesh/common/utils/utils_llm.txt

@@ -0,0 +1,67 @@
+Here is the comprehensive developer guide for the `utils` directory.
+
+## Quick Summary
+The `utils` directory provides a collection of essential, cross-cutting utilities for the Solace AI Connector. Its purpose is to offer robust, reusable solutions for common application needs, including caching, platform compatibility, secure communication, logging, and dynamic content generation.
+
+The architecture consists of standalone utility files for specific tasks and a more complex, self-contained subdirectory for advanced functionality. Direct files provide services like a thread-safe in-memory cache (`in_memory_cache.py`), JWT-based authentication for push notifications (`push_notification_auth.py`), custom logging formatters (`log_formatters.py`), and a critical patch for asyncio on macOS (`asyncio_macos_fix.py`).
+
+The `embeds` subdirectory provides a powerful system for finding, parsing, and resolving dynamic expressions embedded within strings. These utilities are designed to work together. For instance, a request handler might use `mime_helpers` to validate content type, use the `embeds` system to process the content, and then store the result in the `InMemoryCache` to optimize future requests.
+
+## Files and Subdirectories Overview
+- **Direct files:**
+    - `__init__.py`: Exposes key utility functions from the package for convenient access.
+    - `asyncio_macos_fix.py`: Automatically applies a patch to fix asyncio subprocess issues on macOS.
+    - `in_memory_cache.py`: Implements a thread-safe, singleton in-memory cache with TTL support.
+    - `log_formatters.py`: Provides custom logging formatters, such as a Datadog-compatible JSON formatter.
+    - `mime_helpers.py`: Contains helper functions to classify and identify text-based MIME types.
+    - `push_notification_auth.py`: Implements JWT-based authentication for sending and receiving push notifications.
+
+- **Subdirectories:**
+    - `embeds/`: Provides a comprehensive system for processing embedded dynamic expressions (e.g., math, datetimes, artifact content).
+
+## Developer API Reference
+
+### Direct Files
+
+#### __init__.py
+**Purpose:** Serves as the main entry point for the `utils` package, exporting the most common utility functions for easy importing.
+**Import:** `from solace_ai_connector.common.utils import is_text_based_mime_type`
+
+**Classes/Functions/Constants:**
+*   `is_text_based_mime_type(mime_type: Optional[str]) -> bool`: Checks if a given MIME type is considered text-based.
+
+#### asyncio_macos_fix.py
+**Purpose:** Provides a targeted, automatic fix for a `NotImplementedError` that occurs when creating subprocesses with asyncio on macOS. This module is imported for its side effects and should be loaded early in the application's lifecycle.
+**Import:** `from solace_ai_connector.common.utils import asyncio_macos_fix` (Importing the module is sufficient to apply the patch).
+
+**Classes/Functions/Constants:**
+*   `ensure_asyncio_compatibility() -> bool`: The core function that applies the patch. It is called automatically when the module is first imported.
+
+#### in_memory_cache.py
+**Purpose:** Provides a simple, thread-safe, in-memory cache implemented as a singleton. It's useful for storing frequently accessed data with an optional time-to-live (TTL).
+**Import:** `from solace_ai_connector.common.utils.in_memory_cache import InMemoryCache`
+
+**Classes/Functions/Constants:**
+*   **`InMemoryCache`**: A singleton class for caching.
+    *   `set(self, key: str, value: Any, ttl: Optional[int] = None) -> None`: Sets a key-value pair with an optional TTL in seconds.
+    *   `get(self, key: str, default: Any = None) -> Any`: Retrieves a value by its key, returning a default if the key is not found or has expired.
+    *   `delete(self, key: str) -> bool`: Deletes a key-value pair from the cache.
+    *   `clear(self) -> bool`: Removes all items from the cache.
+
+#### log_formatters.py
+**Purpose:** Contains custom logging formatters to structure log output for specific platforms, such as Datadog.
+**Import:** `from solace_ai_connector.common.utils.log_formatters import DatadogJsonFormatter`
+
+**Classes/Functions/Constants:**
+*   **`DatadogJsonFormatter(logging.Formatter)`**: A formatter that outputs log records as a JSON string, compatible with Datadog's standard log attributes. It automatically includes tracing information (`dd.trace_id`, `dd.span_id`) if available.
+
+#### mime_helpers.py
+**Purpose:** Provides utilities for handling and classifying MIME types, with a focus on identifying which types represent text-based content.
+**Import:** `from solace_ai_connector.common.utils.mime_helpers import is_text_based_mime_type, TEXT_CONTAINER_MIME_TYPES`
+
+**Classes/Functions/Constants:**
+*   `is_text_based_mime_type(mime_type: Optional[str]) -> bool`: Returns `True` if the MIME type starts with `text/` or is in the list of known text-based application types (like `application/json`).
+*   `TEXT_CONTAINER_MIME_TYPES: Set[str]`: A set of non-`text/*` MIME types that are considered to contain text (e.g., `application/json`, `application/yaml`).
+
+#### push_notification_auth.py
+**Purpose:**

solace_agent_mesh/config_portal/backend/common.py

@@ -1,9 +1,7 @@
-default_options = {
-    "namespace": "",
-    "config_dir": "configs",
-    "module_dir": "modules",
-    "env_file": ".env",
-    "build_dir": "build",
+import sys
+
+INIT_DEFAULT = {
+    "namespace": "default_namespace",
     "broker_type": "solace",
     "broker_url": "ws://localhost:8008",
     "broker_vpn": "default",
@@ -13,23 +11,67 @@ default_options = {
     "llm_model_name": "openai/gpt-4o",
     "llm_endpoint_url": "https://api.openai.com/v1",
     "llm_api_key": "",
-    "embedding_model_name": "openai/text-embedding-ada-002",
-    "embedding_endpoint_url": "https://api.openai.com/v1",
-    "embedding_api_key": "",
-    "embedding_service_enabled": False,
-    "built_in_agent": ["web_request"],
-    "file_service_provider": "volume",
-    "file_service_config": ["directory=/tmp/solace-agent-mesh"],
-    "env_var": [],
-    "rest_api_enabled": True,
-    "rest_api_server_input_port": "5050",
-    "rest_api_server_host": "127.0.0.1",
-    "rest_api_server_input_endpoint": "/api/v1/request",
-    "rest_api_gateway_name": "rest-api",
-    "webui_enabled": True,
-    "webui_listen_port": "5001",
-    "webui_host": "localhost",
-    "dev_mode": True,
+    "dev_mode": False,
+    "add_webui_gateway": True,
+    "webui_frontend_welcome_message": "",
+    "webui_frontend_bot_name": "Solace Agent Mesh",
+    "webui_frontend_collect_feedback": False,
+    "webui_fastapi_host": "127.0.0.1",
+    "webui_fastapi_port": 8000,
+    "webui_enable_embed_resolution": True,
+}
+
+USE_DEFAULT_SHARED_SESSION = "use_default_shared_session"
+USE_DEFAULT_SHARED_ARTIFACT = "use_default_shared_artifact"
+
+DEFAULT_COMMUNICATION_TIMEOUT = 600  # 10 minutes
+
+AGENT_DEFAULTS = {
+    "supports_streaming": True,
+    "model_type": "general",
+    "instruction": "You are a helpful AI assistant named __AGENT_NAME__.",
+    "artifact_handling_mode": "embed",
+    "enable_embed_resolution": True,
+    "enable_artifact_content_instruction": True,
+    "tools": "[]",
+    "session_service_type": USE_DEFAULT_SHARED_SESSION,
+    "session_service_behavior": "PERSISTENT",
+    "artifact_service_type": USE_DEFAULT_SHARED_ARTIFACT,
+    "artifact_service_base_path": "/tmp/samv2",
+    "artifact_service_scope": "namespace",
+    "agent_card_description": "A helpful AI assistant.",
+    "agent_card_default_input_modes": ["text"],
+    "agent_card_default_output_modes": ["text", "file"],
+    "agent_card_skills_str": "[]",
+    "agent_card_publishing_interval": 10,
+    "agent_discovery_enabled": True,
+    "inter_agent_communication_allow_list": ["*"],
+    "inter_agent_communication_deny_list": [],
+    "inter_agent_communication_timeout": DEFAULT_COMMUNICATION_TIMEOUT,
+    "namespace": "${NAMESPACE}",
 }
 
-CONTAINER_RUN_COMMAND = " run -d -p 8080:8080 -p 55554:55555 -p 8008:8008 -p 1883:1883 -p 8000:8000 -p 5672:5672 -p 9000:9000 -p 2222:2222 --shm-size=2g --env username_admin_globalaccesslevel=admin --env username_admin_password=admin --name=solace solace/solace-pubsub-standard"
+GATEWAY_DEFAULTS = {
+    "namespace": "${NAMESPACE}",
+    "gateway_id_suffix": "-gw-01",
+    "artifact_service_type": USE_DEFAULT_SHARED_ARTIFACT,
+    "artifact_service_scope": "namespace",
+    "artifact_service_base_path": "/tmp/samv2",
+    "system_purpose": (
+        "The system is an AI Chatbot with agentic capabilities.\n"
+        "It will use the agents available to provide information,\n"
+        "reasoning and general assistance for the users in this system.\n"
+        "**Always return useful artifacts and files that you create to the user.**\n"
+        "Provide a status update before each tool call.\n"
+        "Your external name is Agent Mesh."
+    ),
+    "response_format": (
+        "Responses should be clear, concise, and professionally toned.\n"
+        "Format responses to the user in Markdown using appropriate formatting."
+    ),
+}
+
+
+port_55555 = "-p 55554:55555" if sys.platform == "darwin" else "-p 55555:55555"
+
+CONTAINER_RUN_COMMAND = f" run -d --rm -p 8080:8080 {port_55555} -p 8008:8008 -u 1004 --shm-size=2g --env username_admin_globalaccesslevel=admin --env username_admin_password=admin --name=solace-broker solace/solace-pubsub-standard"

solace_agent_mesh/config_portal/backend/plugin_catalog/constants.py

@@ -0,0 +1,23 @@
+import os
+from pathlib import Path
+
+try:
+    from cli.utils import get_sam_cli_home_dir
+    SAM_HOME = get_sam_cli_home_dir()
+except ImportError:
+    print(
+        "WARNING: Could not import 'get_sam_cli_home_dir' from 'cli.utils'. "
+        "Falling back to legacy ~/.sam paths for Plugin Catalog. "
+        "SAM_CLI_HOME environment variable will not be respected in this mode."
+    )
+    SAM_HOME = Path(os.path.expanduser("~/.sam"))
+    SAM_HOME.mkdir(parents=True, exist_ok=True)
+
+DEFAULT_OFFICIAL_REGISTRY_URL = (
+        "https://github.com/SolaceLabs/solace-agent-mesh-core-plugins"
+)
+OFFICIAL_REGISTRY_GIT_BRANCH = "main"
+IGNORE_OFFICIAL_FLAG_REPOS = []
+
+USER_REGISTRIES_PATH = SAM_HOME / "plugin_catalog_registries.json"
+PLUGIN_CATALOG_TEMP_DIR = SAM_HOME / "plugin_catalog_tmp"

solace_agent_mesh/config_portal/backend/plugin_catalog/models.py

@@ -0,0 +1,49 @@
+from typing import List, Optional, Dict, Any
+from pydantic import BaseModel
+
+
+class PyProjectAuthor(BaseModel):
+    name: Optional[str] = None
+    email: Optional[str] = None
+
+
+class PyProjectDetails(BaseModel):
+    name: str
+    version: str
+    description: Optional[str] = None
+    authors: Optional[List[PyProjectAuthor]] = None
+    plugin_type: Optional[str] = "custom"
+    custom_metadata: Optional[Dict[str, Any]] = None
+
+
+class AgentCardSkill(BaseModel):
+    name: str
+    description: Optional[str] = None
+
+
+class AgentCard(BaseModel):
+    displayName: Optional[str] = None
+    shortDescription: Optional[str] = None
+    Skill: Optional[List[AgentCardSkill]] = None
+
+
+class PluginScrapedInfo(BaseModel):
+    id: str
+    pyproject: PyProjectDetails
+    readme_content: Optional[str] = None
+    agent_card: Optional[AgentCard] = None
+    source_registry_name: Optional[str] = None
+    source_registry_location: str
+    source_type: str
+    plugin_subpath: str
+    is_official: bool
+
+
+class Registry(BaseModel):
+    id: str
+    path_or_url: str
+    name: Optional[str] = None
+    type: str
+    is_default: bool = False
+    is_official_source: bool = False
+    git_branch: Optional[str] = None