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

solace_agent_mesh/gateway/http_sse/alembic/versions/versions_llm.txt

@@ -0,0 +1,161 @@
+# DEVELOPER GUIDE: versions
+
+## Quick Summary
+This directory contains Alembic database migration files for the HTTP SSE gateway. These migrations handle the evolution of the database schema, including initial table creation, performance optimization through indexing, timestamp format standardization, and task management features.
+
+## Files Overview
+- `20250910_d5b3f8f2e9a0_create_initial_database.py` - Creates the initial database schema with sessions and chat_messages tables
+- `20250911_b1c2d3e4f5g6_add_database_indexes.py` - Adds performance indexes for common query patterns
+- `20250916_f6e7d8c9b0a1_convert_timestamps_to_epoch_and_align_columns.py` - Converts datetime columns to epoch milliseconds and standardizes column names
+- `20251006_98882922fa59_add_tasks_events_feedback_chat_tasks.py` - Adds task management tables and replaces chat_messages with chat_tasks
+- `20251015_add_session_performance_indexes.py` - Adds optimized composite indexes for better query performance
+- `versions_llm.txt` - LLM-generated documentation for the versions directory
+
+## Developer API Reference
+
+### 20250910_d5b3f8f2e9a0_create_initial_database.py
+**Purpose:** Initial database migration that creates the core tables for session and message management
+**Import:** This is an Alembic migration file - not directly imported
+
+**Functions:**
+- `upgrade() -> None` - Creates sessions and chat_messages tables with proper relationships and foreign key constraints
+- `downgrade() -> None` - Drops all created tables (chat_messages first, then sessions)
+
+**Constants/Variables:**
+- `revision: str` - Migration identifier "d5b3f8f2e9a0"
+- `down_revision: Union[str, None]` - Previous migration (None for initial migration)
+- `branch_labels: Union[str, Sequence[str], None]` - Branch labels (None)
+- `depends_on: Union[str, Sequence[str], None]` - Dependencies (None)
+
+**Usage Examples:**
+```bash
+# Run this migration
+alembic upgrade d5b3f8f2e9a0
+
+# Rollback this migration
+alembic downgrade base
+```
+
+### 20250911_b1c2d3e4f5g6_add_database_indexes.py
+**Purpose:** Performance optimization migration that adds indexes for efficient querying
+**Import:** This is an Alembic migration file - not directly imported
+
+**Functions:**
+- `upgrade() -> None` - Creates indexes on user_id, timestamps, agent_id, and composite fields for optimal query performance
+- `downgrade() -> None` - Removes all created indexes in reverse order
+
+**Constants/Variables:**
+- `revision: str` - Migration identifier "b1c2d3e4f5g6"
+- `down_revision: Union[str, None]` - Previous migration "d5b3f8f2e9a0"
+
+**Usage Examples:**
+```bash
+# Run this migration
+alembic upgrade b1c2d3e4f5g6
+
+# Rollback this migration
+alembic downgrade d5b3f8f2e9a0
+```
+
+### 20250916_f6e7d8c9b0a1_convert_timestamps_to_epoch_and_align_columns.py
+**Purpose:** Schema modernization migration that converts datetime columns to epoch milliseconds for cross-platform compatibility
+**Import:** This is an Alembic migration file - not directly imported
+
+**Functions:**
+- `upgrade() -> None` - Converts datetime columns to epoch milliseconds and renames columns (created_at → created_time, updated_at → updated_time)
+- `downgrade() -> None` - Reverts back to datetime columns with original names
+- `_upgrade_sqlite(current_time_ms: int) -> None` - SQLite-specific upgrade logic using table recreation
+- `_upgrade_standard_sql(current_time_ms: int) -> None` - PostgreSQL/MySQL upgrade logic using ALTER COLUMN
+- `_downgrade_sqlite() -> None` - SQLite-specific downgrade logic
+- `_downgrade_standard_sql() -> None` - PostgreSQL/MySQL downgrade logic
+- `_create_updated_indexes() -> None` - Creates indexes on new timestamp columns
+- `_create_indexes_safe(index_name: str, table_name: str, columns: list) -> None` - Safely creates indexes (ignores if exists)
+- `_drop_index_safe(index_name: str, table_name: str) -> None` - Safely drops indexes (ignores if not exists)
+
+**Constants/Variables:**
+- `revision: str` - Migration identifier "f6e7d8c9b0a1"
+- `down_revision: str | None` - Previous migration "b1c2d3e4f5g6"
+
+**Usage Examples:**
+```bash
+# Run this migration
+alembic upgrade f6e7d8c9b0a1
+
+# Rollback this migration
+alembic downgrade b1c2d3e4f5g6
+```
+
+### 20251006_98882922fa59_add_tasks_events_feedback_chat_tasks.py
+**Purpose:** Major schema update that adds task management functionality and replaces chat_messages with chat_tasks
+**Import:** This is an Alembic migration file - not directly imported
+
+**Functions:**
+- `upgrade() -> None` - Creates tasks, task_events, feedback, and chat_tasks tables; drops old chat_messages table and indexes
+- `downgrade() -> None` - Recreates chat_messages table and drops all task-related tables
+
+**Constants/Variables:**
+- `revision: str` - Migration identifier "98882922fa59"
+- `down_revision: Union[str, Sequence[str], None]` - Previous migration "f6e7d8c9b0a1"
+
+**Usage Examples:**
+```bash
+# Run this migration
+alembic upgrade 98882922fa59
+
+# Rollback this migration
+alembic downgrade f6e7d8c9b0a1
+```
+
+### 20251015_add_session_performance_indexes.py
+**Purpose:** Performance optimization migration that adds composite indexes for optimal query patterns
+**Import:** This is an Alembic migration file - not directly imported
+
+**Functions:**
+- `upgrade() -> None` - Creates optimized composite indexes for user sessions, chat tasks, and task events; removes unused text index
+- `downgrade() -> None` - Removes performance indexes and recreates the original text index
+
+**Constants/Variables:**
+- `revision: str` - Migration identifier "20251015_session_idx"
+- `down_revision: str | Sequence[str] | None` - Previous migration "98882922fa59"
+
+**Usage Examples:**
+```bash
+# Run this migration
+alembic upgrade 20251015_session_idx
+
+# Rollback this migration
+alembic downgrade 98882922fa59
+
+# Run all migrations to latest
+alembic upgrade head
+
+# Check current migration status
+alembic current
+
+# View migration history
+alembic history
+
+# Generate new migration
+alembic revision --autogenerate -m "description"
+```
+
+**Final Database Schema After All Migrations:**
+```sql
+-- Core tables with epoch millisecond timestamps:
+-- sessions: id, name, user_id, agent_id, created_time, updated_time
+-- chat_tasks: id, session_id, user_id, user_message, message_bubbles, task_metadata, created_time, updated_time
+
+-- Task management tables:
+-- tasks: id, user_id, start_time, end_time, status, initial_request_text,
+--        total_input_tokens, total_output_tokens, total_cached_input_tokens, token_usage_details
+-- task_events: id, task_id, user_id, created_time, topic, direction, payload
+-- feedback: id, session_id, task_id, user_id, rating, comment, created_time
+
+-- Performance indexes:
+-- ix_sessions_user_id, ix_sessions_user_updated
+-- ix_chat_tasks_session_user_created
+-- ix_tasks_user_start_time, ix_task_events_task_created
+-- ix_feedback_task_id, ix_feedback_user_id, ix_feedback_created_time
+```
+
+# content_hash: c1d3d7f6855eba76bdabdb5cc0c7253756faf1583ef349dc503418c611a23bd2

solace_agent_mesh/gateway/http_sse/alembic.ini

@@ -0,0 +1,109 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts.
+# this is typically a path given in POSIX (e.g. forward slashes)
+# format, relative to the token %(here)s which refers to the location of this
+# ini file
+script_location = %(here)s/alembic
+
+# Template used to generate migration file names
+# Format: YYYYMMDD_revision_description
+file_template = %%(year)d%%(month).2d%%(day).2d_%%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path if present.
+# defaults to the current working directory.  for multiple paths, the path separator
+# is defined by "path_separator" below.
+prepend_sys_path = .
+
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the python>=3.9 or backports.zoneinfo library and tzdata library.
+# Any required deps can installed by adding `alembic[tz]` to the pip requirements
+# string value is passed to ZoneInfo()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to <script_location>/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# The path separator used here should be the separator specified by "path_separator"
+# below.
+# version_locations = %(here)s/bar:%(here)s/bat:%(here)s/alembic/versions
+
+# path_separator; This indicates what character is used to split lists of file
+# paths, including version_locations and prepend_sys_path within configparser
+# files such as alembic.ini.
+# The default rendered in new alembic.ini files is "os", which uses os.pathsep
+# to provide os-dependent path splitting.
+#
+# Note that in order to support legacy alembic.ini files, this default does NOT
+# take place if path_separator is not present in alembic.ini.  If this
+# option is omitted entirely, fallback logic is as follows:
+#
+# 1. Parsing of the version_locations option falls back to using the legacy
+#    "version_path_separator" key, which if absent then falls back to the legacy
+#    behavior of splitting on spaces and/or commas.
+# 2. Parsing of the prepend_sys_path option falls back to the legacy
+#    behavior of splitting on spaces, commas, or colons.
+#
+# Valid values for path_separator are:
+#
+# path_separator = :
+# path_separator = ;
+# path_separator = space
+# path_separator = newline
+#
+# Use os.pathsep. Default configuration used for new projects.
+path_separator = os
+
+# set to 'true' to search source files recursively
+# in each "version_locations" directory
+# new in Alembic version 1.10
+# recursive_version_locations = false
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+# database URL.  This is consumed by the user-maintained env.py script only.
+# other means of configuring database URLs may be customized within the env.py
+# file.
+# sqlalchemy.url = sqlite:////Users/mradwan/solace_agent_mesh.db
+
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+# lint with attempts to fix using "ruff" - use the module runner, against the "ruff" module
+# hooks = ruff
+# ruff.type = module
+# ruff.module = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Alternatively, use the exec runner to execute a binary found on your PATH
+# hooks = ruff
+# ruff.type = exec
+# ruff.executable = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME

solace_agent_mesh/gateway/http_sse/app.py

@@ -0,0 +1,351 @@
+"""
+Custom Solace AI Connector App class for the Web UI Backend.
+Defines configuration schema and programmatically creates the WebUIBackendComponent.
+"""
+
+import logging
+from typing import Any, Dict, List
+
+from ...gateway.http_sse.component import WebUIBackendComponent
+
+from ...gateway.base.app import BaseGatewayApp
+from ...gateway.base.component import BaseGatewayComponent
+
+log = logging.getLogger(__name__)
+
+info = {
+    "class_name": "WebUIBackendApp",
+    "description": "Custom App class for the A2A Web UI Backend with automatic subscription generation.",
+}
+
+
+class WebUIBackendApp(BaseGatewayApp):
+    """
+    Custom App class for the A2A Web UI Backend.
+    - Extends BaseGatewayApp for common gateway functionalities.
+    - Defines WebUI-specific configuration parameters.
+    """
+
+    SPECIFIC_APP_SCHEMA_PARAMS: List[Dict[str, Any]] = [
+        {
+            "name": "session_secret_key",
+            "required": True,
+            "type": "string",
+            "description": "Secret key for signing web user sessions.",
+        },
+        {
+            "name": "fastapi_host",
+            "required": False,
+            "type": "string",
+            "default": "127.0.0.1",
+            "description": "Host address for the embedded FastAPI server.",
+        },
+        {
+            "name": "fastapi_port",
+            "required": False,
+            "type": "integer",
+            "default": 8000,
+            "description": "Port for the embedded FastAPI server.",
+        },
+        {
+            "name": "fastapi_https_port",
+            "required": False,
+            "type": "integer",
+            "default": 8443,
+            "description": "Port for the embedded FastAPI server when SSL is enabled.",
+        },
+        {
+            "name": "cors_allowed_origins",
+            "required": False,
+            "type": "list",
+            "default": ["*"],
+            "description": "List of allowed origins for CORS requests.",
+        },
+        {
+            "name": "sse_max_queue_size",
+            "required": False,
+            "type": "integer",
+            "default": 200,
+            "description": "Maximum size of the SSE connection queues. Adjust based on expected load.",
+        },
+        {
+            "name": "resolve_artifact_uris_in_gateway",
+            "required": False,
+            "type": "boolean",
+            "default": True,
+            "description": "If true, the gateway will resolve artifact:// URIs found in A2A messages and embed the content as bytes before sending to the UI. If false, URIs are passed through.",
+        },
+        {
+            "name": "model",
+            "required": False,
+            "type": "dict",
+            "default": None,
+            "description": "The model to use for the WebUI gateway.",
+        },
+        {
+            "name": "frontend_welcome_message",
+            "required": False,
+            "type": "string",
+            "default": "Hi! How can I help?",
+            "description": "Initial welcome message displayed in the chat.",
+        },
+        {
+            "name": "frontend_bot_name",
+            "required": False,
+            "type": "string",
+            "default": "A2A Agent",
+            "description": "Name displayed for the bot/agent in the UI.",
+        },
+        {
+            "name": "frontend_collect_feedback",
+            "required": False,
+            "type": "boolean",
+            "default": False,
+            "description": "Enable/disable the feedback buttons in the UI.",
+        },
+        {
+            "name": "frontend_auth_login_url",
+            "required": False,
+            "type": "string",
+            "default": "",
+            "description": "URL for the external login page (if auth is enabled).",
+        },
+        {
+            "name": "frontend_use_authorization",
+            "required": False,
+            "type": "boolean",
+            "default": False,
+            "description": "Tell frontend whether backend expects authorization.",
+        },
+        {
+            "name": "frontend_redirect_url",
+            "required": False,
+            "type": "string",
+            "default": "",
+            "description": "Redirect URL for OAuth flows (if auth is enabled).",
+        },
+        {
+            "name": "external_auth_callback_uri",
+            "required": False,
+            "type": "string",
+            "default": "",
+            "description": "Redirect URI for the OIDC application.",
+        },
+        {
+            "name": "external_auth_service_url",
+            "required": False,
+            "type": "string",
+            "default": "http://localhost:8080",
+            "description": "External authorization service URL for login initiation.",
+        },
+        {
+            "name": "external_auth_provider",
+            "required": False,
+            "type": "string",
+            "default": "",
+            "description": "The external authentication provider.",
+        },
+        {
+            "name": "ssl_keyfile",
+            "required": False,
+            "type": "string",
+            "default": "",
+            "description": "The file path to the SSL private key.",
+        },
+        {
+            "name": "ssl_certfile",
+            "required": False,
+            "type": "string",
+            "default": "",
+            "description": "The file path to the SSL certificate.",
+        },
+        {
+            "name": "ssl_keyfile_password",
+            "required": False,
+            "type": "string",
+            "default": "",
+            "description": "The passphrase for the SSL private key.",
+        },
+        {
+            "name": "session_service",
+            "required": False,
+            "type": "dict",
+            "default": {"type": "memory"},
+            "description": "Configuration for the Session Service.",
+            "dict_schema": {
+                "type": {
+                    "type": "string",
+                    "required": True,
+                    "default": "memory",
+                    "allowed": ["memory", "sql"],
+                    "description": "The type of session service to use ('memory' or 'sql').",
+                },
+                "database_url": {
+                    "type": "string",
+                    "required": False,
+                    "default": None,
+                    "description": "Database URL for SQL session service. Required if type is 'sql'.",
+                },
+            },
+        },
+        {
+            "name": "platform_service",
+            "required": False,
+            "type": "dict",
+            "default": {},
+            "description": "Configuration for the Platform Service (enterprise features: agents, connectors, deployments).",
+            "dict_schema": {
+                "database_url": {
+                    "type": "string",
+                    "required": False,
+                    "default": None,
+                    "description": (
+                        "Database URL for platform data (agents, connectors, deployments). "
+                        "REQUIRED for platform features to be available. "
+                        "Example: postgresql://user:pass@host:5432/platform_db"
+                    ),
+                },
+            },
+        },
+        {
+            "name": "task_logging",
+            "required": False,
+            "type": "dict",
+            "description": "Configuration for the A2A task logging service.",
+            "dict_schema": {
+                "enabled": {
+                    "type": "boolean",
+                    "required": False,
+                    "default": False,
+                    "description": "Enable/disable the task logging service.",
+                },
+                "log_status_updates": {
+                    "type": "boolean",
+                    "required": False,
+                    "default": True,
+                    "description": "Log intermediate TaskStatusUpdate events.",
+                },
+                "log_artifact_events": {
+                    "type": "boolean",
+                    "required": False,
+                    "default": True,
+                    "description": "Log TaskArtifactUpdate events.",
+                },
+                "log_file_parts": {
+                    "type": "boolean",
+                    "required": False,
+                    "default": True,
+                    "description": "Log FilePart content within events.",
+                },
+                "max_file_part_size_bytes": {
+                    "type": "integer",
+                    "required": False,
+                    "default": 102400,  # 100KB
+                    "description": "Maximum size of a FilePart's content to store in the database. Larger files will have their content stripped.",
+                },
+            },
+        },
+        {
+            "name": "feedback_publishing",
+            "required": False,
+            "type": "dict",
+            "description": "Configuration for publishing user feedback to the message broker.",
+            "dict_schema": {
+                "enabled": {
+                    "type": "boolean",
+                    "required": False,
+                    "default": False,
+                    "description": "Enable/disable feedback publishing.",
+                },
+                "topic": {
+                    "type": "string",
+                    "required": False,
+                    "default": "sam/feedback/v1",
+                    "description": "The Solace topic to publish feedback events to.",
+                },
+                "include_task_info": {
+                    "type": "string",
+                    "required": False,
+                    "default": "none",
+                    "enum": ["none", "summary", "stim"],
+                    "description": "Level of task detail to include in the feedback event.",
+                },
+                "max_payload_size_bytes": {
+                    "type": "integer",
+                    "required": False,
+                    "default": 9000000,
+                    "description": "Max payload size in bytes before 'stim' falls back to 'summary'.",
+                },
+            },
+        },
+        {
+            "name": "data_retention",
+            "required": False,
+            "type": "dict",
+            "description": "Configuration for automatic cleanup of old data.",
+            "dict_schema": {
+                "enabled": {
+                    "type": "boolean",
+                    "required": False,
+                    "default": True,
+                    "description": "Enable/disable automatic data cleanup.",
+                },
+                "task_retention_days": {
+                    "type": "integer",
+                    "required": False,
+                    "default": 90,
+                    "description": "Number of days to retain task and task_event records. Minimum: 1 day.",
+                },
+                "feedback_retention_days": {
+                    "type": "integer",
+                    "required": False,
+                    "default": 90,
+                    "description": "Number of days to retain feedback records. Minimum: 1 day.",
+                },
+                "cleanup_interval_hours": {
+                    "type": "integer",
+                    "required": False,
+                    "default": 24,
+                    "description": "How often to run the cleanup job (in hours). Minimum: 1 hour.",
+                },
+                "batch_size": {
+                    "type": "integer",
+                    "required": False,
+                    "default": 1000,
+                    "description": "Number of records to delete per batch to avoid long-running transactions. Range: 1-10000.",
+                },
+            },
+        },
+    ]
+
+    def __init__(self, app_info: Dict[str, Any], **kwargs):
+        """
+        Initializes the WebUIBackendApp.
+        Most setup is handled by BaseGatewayApp.
+        """
+        log.debug(
+            "%s Initializing WebUIBackendApp...",
+            app_info.get("name", "WebUIBackendApp"),
+        )
+        super().__init__(app_info, **kwargs)
+
+        log.debug("%s WebUIBackendApp initialization complete.", self.name)
+
+    def _get_gateway_component_class(self) -> type[BaseGatewayComponent]:
+        return WebUIBackendComponent
+
+    def get_component(self) -> WebUIBackendComponent | None:
+        """
+        Retrieves the running WebUIBackendComponent instance from the app's flow.
+        """
+        if self.flows and self.flows[0].component_groups:
+            for group in self.flows[0].component_groups:
+                for component_wrapper in group:
+                    component = (
+                        component_wrapper.component
+                        if hasattr(component_wrapper, "component")
+                        else component_wrapper
+                    )
+                    if isinstance(component, WebUIBackendComponent):
+                        return component
+        return None