solace-agent-mesh 1.6.2__py3-none-any.whl → 1.7.0__py3-none-any.whl

solace_agent_mesh/gateway/http_sse/alembic/alembic_llm.txt

@@ -29,7 +29,7 @@ This directory contains Alembic database migration configuration and version fil
 ### Subdirectory APIs
 
 #### versions/
-**Purpose:** Contains sequential Alembic migration files that define database schema changes including core tables, indexes, timestamp modernization, task management, and token usage tracking
+**Purpose:** Contains sequential Alembic migration files that define database schema changes including core tables, indexes, timestamp modernization, task management, and performance optimization
 **Key Exports:** Migration functions for complete schema evolution (upgrade/downgrade operations)
 **Import Examples:**
 ```python
@@ -43,8 +43,8 @@ This directory contains Alembic database migration configuration and version fil
 - `d5b3f8f2e9a0` - Initial database schema (sessions and chat_messages tables)
 - `b1c2d3e4f5g6` - Performance indexes for query optimization
 - `f6e7d8c9b0a1` - Timestamp conversion to epoch milliseconds
-- `079e06e9b448` - Task management tables (tasks, task_events, feedback)
-- `20250930_token_usage` - Token usage tracking columns for AI model consumption monitoring
+- `98882922fa59` - Task management tables (tasks, task_events, feedback, chat_tasks)
+- `20251015_session_idx` - Optimized composite indexes for better query performance
 
 ## Complete Usage Guide
 
@@ -53,8 +53,6 @@ This directory contains Alembic database migration configuration and version fil
 ```python
 # The env.py automatically imports all repository models for metadata
 from solace_agent_mesh.gateway.http_sse.repository.models.base import Base
-from solace_agent_mesh.gateway.http_sse.repository.models.session_model import SessionModel
-from solace_agent_mesh.gateway.http_sse.repository.models.message_model import MessageModel
 from solace_agent_mesh.gateway.http_sse.repository.models.task_model import TaskModel
 from solace_agent_mesh.gateway.http_sse.repository.models.task_event_model import TaskEventModel
 from solace_agent_mesh.gateway.http_sse.repository.models.feedback_model import FeedbackModel
@@ -104,12 +102,13 @@ alembic upgrade f6e7d8c9b0a1
 # Renames: columns for consistency (created_at → created_time)
 
 # Step 4: Add task management features
-alembic upgrade 079e06e9b448
-# Creates: tasks, task_events, feedback tables with proper relationships
+alembic upgrade 98882922fa59
+# Creates: tasks, task_events, feedback, chat_tasks tables
+# Replaces: chat_messages with chat_tasks for better task tracking
 
-# Step 5: Add token usage tracking
-alembic upgrade 20250930_token_usage
-# Adds: token usage columns for AI model consumption monitoring
+# Step 5: Add optimized performance indexes
+alembic upgrade 20251015_session_idx
+# Adds: composite indexes for optimal query patterns
 ```
 
 ### 4. Working with Different Database Engines
@@ -133,8 +132,6 @@ alembic upgrade 20250930_token_usage
 ```python
 # The migrations work with the repository models
 from solace_agent_mesh.gateway.http_sse.repository.models.base import Base
-from solace_agent_mesh.gateway.http_sse.repository.models.session_model import SessionModel
-from solace_agent_mesh.gateway.http_sse.repository.models.message_model import MessageModel
 from solace_agent_mesh.gateway.http_sse.repository.models.task_model import TaskModel
 from solace_agent_mesh.gateway.http_sse.repository.models.task_event_model import TaskEventModel
 from solace_agent_mesh.gateway.http_sse.repository.models.feedback_model import FeedbackModel
@@ -144,7 +141,7 @@ from solace_agent_mesh.gateway.http_sse.repository.models.feedback_model import
 # - Proper indexes for performance
 # - Standardized column names
 # - Complete task management functionality
-# - Token usage tracking for AI model consumption
+# - Optimized composite indexes for query performance
 ```
 
 ### 6. Offline Migration Generation
@@ -159,8 +156,8 @@ alembic upgrade d5b3f8f2e9a0 --sql
 # Generate SQL for all pending migrations
 alembic upgrade head --sql
 
-# Generate SQL for token usage migration
-alembic upgrade 20250930_token_usage --sql
+# Generate SQL for performance optimization
+alembic upgrade 20251015_session_idx --sql
 ```
 
 ### 7. Common Development Patterns
@@ -190,7 +187,7 @@ alembic upgrade head --sql > migration.sql
 ```sql
 -- Final schema structure after all migrations:
 
--- Core tables:
+-- Core tables with epoch millisecond timestamps:
 -- sessions table:
 --   id (String, Primary Key)
 --   name (String)
@@ -199,13 +196,15 @@ alembic upgrade head --sql > migration.sql
 --   created_time (BigInteger, epoch ms)
 --   updated_time (BigInteger, epoch ms)
 
--- chat_messages table:
+-- chat_tasks table (replaces chat_messages):
 --   id (String, Primary Key)
 --   session_id (String, Foreign Key to sessions.id)
---   message (Text)
---   sender_type (String)
---   sender_name (String)
---   created_time (BigInteger, epoch ms, Indexed)
+--   user_id (String)
+--   user_message (Text)
+--   message_bubbles (Text, JSON)
+--   task_metadata (Text, JSON)
+--   created_time (BigInteger, epoch ms)
+--   updated_time (BigInteger, epoch ms)
 
 -- Task management tables:
 -- tasks table:
@@ -238,18 +237,15 @@ alembic upgrade head --sql > migration.sql
 --   comment (Text)
 --   created_time (BigInteger, epoch ms)
 
--- Performance indexes:
---   idx_sessions_user_id
---   idx_sessions_created_time
---   idx_sessions_updated_time
---   idx_chat_messages_session_id
---   idx_chat_messages_created_time
---   idx_chat_messages_session_created (composite)
---   idx_tasks_user_id
---   idx_task_events_task_id
---   idx_task_events_created_time
---   idx_feedback_session_id
---   idx_feedback_task_id
+-- Optimized performance indexes:
+--   ix_sessions_user_id
+--   ix_sessions_user_updated (composite: user_id, updated_time)
+--   ix_chat_tasks_session_user_created (composite: session_id, user_id, created_time)
+--   ix_tasks_user_start_time (composite: user_id, start_time)
+--   ix_task_events_task_created (composite: task_id, created_time)
+--   ix_feedback_task_id
+--   ix_feedback_user_id
+--   ix_feedback_created_time
 ```
 
 ### 9. Cross-Platform Timestamp Handling
@@ -268,28 +264,82 @@ alembic upgrade head --sql > migration.sql
 # - More efficient for large datasets
 ```
 
-### 10. Token Usage Tracking
+### 10. Performance Optimization Features
 
 ```python
-# The 20250930_token_usage migration adds AI model consumption tracking:
+# The migrations include comprehensive performance optimizations:
+
+# Single-column indexes for basic filtering:
+# - user_id columns for user-specific queries
+# - timestamp columns for time-based filtering
 
-# Token usage columns added to tasks table:
-# - total_input_tokens: Total input tokens consumed
-# - total_output_tokens: Total output tokens generated
-# - total_cached_input_tokens: Cached input tokens used
-# - token_usage_details: JSON field for detailed token usage breakdown
+# Composite indexes for complex queries:
+# - (user_id, updated_time) for recent user sessions
+# - (session_id, user_id, created_time) for session chat history
+# - (task_id, created_time) for task event chronology
+# - (user_id, start_time) for user task history
 
-# Usage example after migration:
+# Usage example after all migrations:
 from solace_agent_mesh.gateway.http_sse.repository.models.task_model import TaskModel
 
-# Query tasks with token usage
-task = session.query(TaskModel).filter_by(id="task_id").first()
-print(f"Input tokens: {task.total_input_tokens}")
-print(f"Output tokens: {task.total_output_tokens}")
-print(f"Cached tokens: {task.total_cached_input_tokens}")
-print(f"Details: {task.token_usage_details}")
+# Efficient queries using optimized indexes:
+# Get recent user sessions (uses ix_sessions_user_updated)
+recent_sessions = session.query(SessionModel)\
+    .filter_by(user_id="user123")\
+    .order_by(SessionModel.updated_time.desc())\
+    .limit(10)
+
+# Get task events chronologically (uses ix_task_events_task_created)
+task_events = session.query(TaskEventModel)\
+    .filter_by(task_id="task456")\
+    .order_by(TaskEventModel.created_time)\
+    .all()
+```
+
+### 11. Task Management Integration
+
+```python
+# After running all migrations, the complete task management system is available:
+
+from solace_agent_mesh.gateway.http_sse.repository.models.task_model import TaskModel
+from solace_agent_mesh.gateway.http_sse.repository.models.task_event_model import TaskEventModel
+from solace_agent_mesh.gateway.http_sse.repository.models.feedback_model import FeedbackModel
+
+# Create a new task with token tracking
+task = TaskModel(
+    id="task_123",
+    user_id="user_456",
+    start_time=1634567890000,  # epoch milliseconds
+    status="in_progress",
+    initial_request_text="User's initial request",
+    total_input_tokens=150,
+    total_output_tokens=300,
+    total_cached_input_tokens=50,
+    token_usage_details='{"model": "gpt-4", "breakdown": {...}}'
+)
+
+# Add task events for tracking
+event = TaskEventModel(
+    id="event_789",
+    task_id="task_123",
+    user_id="user_456",
+    created_time=1634567891000,
+    topic="ai_response",
+    direction="outbound",
+    payload='{"response": "AI generated response"}'
+)
+
+# Collect user feedback
+feedback = FeedbackModel(
+    id="feedback_101",
+    task_id="task_123",
+    user_id="user_456",
+    rating=5,
+    comment="Excellent response quality",
+    created_time=1634567892000
+)
 ```
 
-This Alembic configuration provides a comprehensive database migration system that handles schema evolution, performance optimization, cross-database compatibility, complete task management functionality, and AI model token usage tracking for the HTTP SSE gateway component.
+This Alembic configuration provides a comprehensive database migration system that handles schema evolution, performance optimization, cross-database compatibility, complete task management functionality, and optimized query patterns for the HTTP SSE gateway component.
 
-# content_hash: 2904df085decd08d4411ff2583b376a04fc56ba1eae82ba45f4a91e1a930b710
+# content_hash: 1211a2aee2a0eb3361ee0f61e504f720c4cf454569a46c5f3991507db9a0cab9

solace_agent_mesh/gateway/http_sse/alembic/versions/20251023_add_fulltext_search_indexes.py

@@ -0,0 +1,92 @@
+"""Add full-text search indexes for chat search optimization (PostgreSQL only)
+
+Revision ID: fts_indexes_001
+Revises: soft_del_search_001
+Create Date: 2025-10-23
+
+This migration adds PostgreSQL full-text search (FTS) indexes to optimize
+chat search performance. It creates GIN indexes on the user_message and
+message_bubbles columns of the chat_tasks table.
+
+Database Compatibility:
+- PostgreSQL: Creates GIN indexes for full-text search (10-100x faster)
+- SQLite: Skips index creation (uses ILIKE fallback in repository)
+
+Performance Impact (PostgreSQL only):
+- Search queries will be 10-100x faster
+- Supports stemming (e.g., "running" matches "run", "ran")
+- Enables relevance ranking
+- Scales efficiently to millions of records
+
+Index Details:
+- Uses 'english' text search configuration
+- GIN (Generalized Inverted Index) for fast lookups
+- Automatically maintained by PostgreSQL
+"""
+
+from alembic import op
+from sqlalchemy import inspect
+
+
+# revision identifiers, used by Alembic.
+revision = 'fts_indexes_001'
+down_revision = 'soft_del_search_001'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """
+    Add GIN indexes for full-text search on chat_tasks table (PostgreSQL only).
+    
+    Creates three indexes:
+    1. idx_chat_tasks_user_message_fts - For searching user messages
+    2. idx_chat_tasks_message_bubbles_fts - For searching full conversation content
+    3. idx_sessions_name_fts - For searching session names
+    
+    Note: Silently skips index creation for non-PostgreSQL databases (e.g., SQLite).
+    """
+    # Get database connection and check dialect
+    conn = op.get_bind()
+    dialect_name = conn.dialect.name
+    
+    # Only create FTS indexes for PostgreSQL
+    if dialect_name == 'postgresql':
+        # Create GIN index for user_message full-text search
+        op.execute("""
+            CREATE INDEX IF NOT EXISTS idx_chat_tasks_user_message_fts
+            ON chat_tasks
+            USING gin(to_tsvector('english', COALESCE(user_message, '')))
+        """)
+        
+        # Create GIN index for message_bubbles full-text search
+        op.execute("""
+            CREATE INDEX IF NOT EXISTS idx_chat_tasks_message_bubbles_fts
+            ON chat_tasks
+            USING gin(to_tsvector('english', message_bubbles))
+        """)
+        
+        # Create GIN index for session name full-text search
+        op.execute("""
+            CREATE INDEX IF NOT EXISTS idx_sessions_name_fts
+            ON sessions
+            USING gin(to_tsvector('english', COALESCE(name, '')))
+        """)
+    # For SQLite and other databases, skip FTS index creation
+    # The repository will automatically use ILIKE-based search instead
+
+
+def downgrade() -> None:
+    """
+    Remove full-text search indexes (PostgreSQL only).
+    
+    Note: Downgrading will revert to slower ILIKE-based search.
+    Silently skips for non-PostgreSQL databases.
+    """
+    conn = op.get_bind()
+    dialect_name = conn.dialect.name
+    
+    if dialect_name == 'postgresql':
+        op.execute("DROP INDEX IF EXISTS idx_chat_tasks_user_message_fts")
+        op.execute("DROP INDEX IF EXISTS idx_chat_tasks_message_bubbles_fts")
+        op.execute("DROP INDEX IF EXISTS idx_sessions_name_fts")

solace_agent_mesh/gateway/http_sse/alembic/versions/20251023_add_project_users_table.py

@@ -0,0 +1,72 @@
+"""Add project_users table for multi-user project access
+
+Revision ID: 20251023_add_project_users
+Revises: 20251023_remove_created_by_user_id
+Create Date: 2025-10-23
+
+"""
+from typing import Sequence, Union
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'add_project_users_001'
+down_revision: Union[str, None] = 'add_projects_table_001'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """
+    Create project_users table to enable multi-user access to projects.
+    
+    This table tracks which users have access to which projects and their roles.
+    It supports future features for collaborative project management.
+    """
+    # Create project_users table
+    op.create_table(
+        'project_users',
+        sa.Column('id', sa.String(), nullable=False),
+        sa.Column('project_id', sa.String(), nullable=False),
+        sa.Column('user_id', sa.String(), nullable=False),
+        sa.Column('role', sa.String(), nullable=False),
+        sa.Column('added_at', sa.BigInteger(), nullable=False),
+        sa.Column('added_by_user_id', sa.String(), nullable=False),
+        sa.PrimaryKeyConstraint('id'),
+        sa.ForeignKeyConstraint(['project_id'], ['projects.id'], ondelete='CASCADE'),
+        sa.UniqueConstraint('project_id', 'user_id', name='uq_project_user')
+    )
+    
+    # Create indexes for efficient queries
+    op.create_index(
+        'ix_project_users_project_id',
+        'project_users',
+        ['project_id']
+    )
+    
+    op.create_index(
+        'ix_project_users_user_id',
+        'project_users',
+        ['user_id']
+    )
+    
+    # Create composite index for common query pattern (user accessing specific project)
+    op.create_index(
+        'ix_project_users_user_project',
+        'project_users',
+        ['user_id', 'project_id']
+    )
+
+
+def downgrade() -> None:
+    """
+    Remove project_users table and related indexes.
+    """
+    # Drop indexes first
+    op.drop_index('ix_project_users_user_project', table_name='project_users')
+    op.drop_index('ix_project_users_user_id', table_name='project_users')
+    op.drop_index('ix_project_users_project_id', table_name='project_users')
+    
+    # Drop the table
+    op.drop_table('project_users')

solace_agent_mesh/gateway/http_sse/alembic/versions/20251023_add_soft_delete_and_search.py

@@ -0,0 +1,150 @@
+"""Add soft delete and search support for sessions and projects
+
+Revision ID: add_soft_delete_search_001
+Revises: remove_is_global_001
+Create Date: 2025-10-23 16:20:00.000000
+
+"""
+from typing import Sequence, Union
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy import inspect
+
+# revision identifiers, used by Alembic.
+revision: str = 'soft_del_search_001'
+down_revision: Union[str, Sequence[str], None] = 'add_project_users_001'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add soft delete columns and search indexes."""
+    bind = op.get_bind()
+    inspector = inspect(bind)
+    
+    # Add soft delete columns to sessions table
+    if 'sessions' in inspector.get_table_names():
+        sessions_columns = [col['name'] for col in inspector.get_columns('sessions')]
+        
+        if 'deleted_at' not in sessions_columns:
+            op.add_column('sessions', sa.Column('deleted_at', sa.BigInteger(), nullable=True))
+        
+        if 'deleted_by' not in sessions_columns:
+            op.add_column('sessions', sa.Column('deleted_by', sa.String(), nullable=True))
+        
+        # Create index on deleted_at for efficient filtering
+        try:
+            op.create_index('ix_sessions_deleted_at', 'sessions', ['deleted_at'])
+        except Exception:
+            pass  # Index might already exist
+        
+        # Create composite index for user queries with soft delete
+        try:
+            op.create_index('ix_sessions_user_deleted', 'sessions', ['user_id', 'deleted_at'])
+        except Exception:
+            pass
+    
+    # Add soft delete columns to projects table
+    if 'projects' in inspector.get_table_names():
+        projects_columns = [col['name'] for col in inspector.get_columns('projects')]
+        
+        if 'deleted_at' not in projects_columns:
+            op.add_column('projects', sa.Column('deleted_at', sa.BigInteger(), nullable=True))
+        
+        if 'deleted_by' not in projects_columns:
+            op.add_column('projects', sa.Column('deleted_by', sa.String(), nullable=True))
+        
+        # Create index on deleted_at for efficient filtering
+        try:
+            op.create_index('ix_projects_deleted_at', 'projects', ['deleted_at'])
+        except Exception:
+            pass
+        
+        # Create composite index for user queries with soft delete
+        try:
+            op.create_index('ix_projects_user_deleted', 'projects', ['user_id', 'deleted_at'])
+        except Exception:
+            pass
+    
+    # Enable pg_trgm extension for fuzzy text search (PostgreSQL only)
+    try:
+        op.execute('CREATE EXTENSION IF NOT EXISTS pg_trgm')
+    except Exception:
+        # Not PostgreSQL or extension already exists
+        pass
+    
+    # Create GIN indexes for text search on sessions
+    if 'sessions' in inspector.get_table_names():
+        try:
+            # Index on session name for fuzzy search
+            op.execute(
+                'CREATE INDEX IF NOT EXISTS ix_sessions_name_trgm ON sessions '
+                'USING gin (name gin_trgm_ops)'
+            )
+        except Exception:
+            pass
+    
+    # Create GIN indexes for text search on chat_tasks
+    if 'chat_tasks' in inspector.get_table_names():
+        try:
+            # Index on user_message for content search
+            op.execute(
+                'CREATE INDEX IF NOT EXISTS ix_chat_tasks_user_message_trgm ON chat_tasks '
+                'USING gin (user_message gin_trgm_ops)'
+            )
+        except Exception:
+            pass
+
+
+def downgrade() -> None:
+    """Remove soft delete columns and search indexes."""
+    bind = op.get_bind()
+    inspector = inspect(bind)
+    
+    # Drop search indexes from chat_tasks
+    if 'chat_tasks' in inspector.get_table_names():
+        try:
+            op.execute('DROP INDEX IF EXISTS ix_chat_tasks_user_message_trgm')
+        except Exception:
+            pass
+    
+    # Drop search indexes from sessions
+    if 'sessions' in inspector.get_table_names():
+        try:
+            op.execute('DROP INDEX IF EXISTS ix_sessions_name_trgm')
+        except Exception:
+            pass
+        
+        try:
+            op.drop_index('ix_sessions_user_deleted', table_name='sessions')
+        except Exception:
+            pass
+        
+        try:
+            op.drop_index('ix_sessions_deleted_at', table_name='sessions')
+        except Exception:
+            pass
+        
+        sessions_columns = [col['name'] for col in inspector.get_columns('sessions')]
+        if 'deleted_by' in sessions_columns:
+            op.drop_column('sessions', 'deleted_by')
+        if 'deleted_at' in sessions_columns:
+            op.drop_column('sessions', 'deleted_at')
+    
+    # Drop indexes and columns from projects
+    if 'projects' in inspector.get_table_names():
+        try:
+            op.drop_index('ix_projects_user_deleted', table_name='projects')
+        except Exception:
+            pass
+        
+        try:
+            op.drop_index('ix_projects_deleted_at', table_name='projects')
+        except Exception:
+            pass
+        
+        projects_columns = [col['name'] for col in inspector.get_columns('projects')]
+        if 'deleted_by' in projects_columns:
+            op.drop_column('projects', 'deleted_by')
+        if 'deleted_at' in projects_columns:
+            op.drop_column('projects', 'deleted_at')

solace_agent_mesh/gateway/http_sse/alembic/versions/20251024_add_default_agent_to_projects.py

@@ -0,0 +1,26 @@
+"""add default agent to projects
+
+Revision ID: default_agent_001
+Revises: fts_indexes_001
+Create Date: 2025-01-24 01:13:00.000000
+
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = 'default_agent_001'
+down_revision = 'fts_indexes_001'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    """Add default_agent_id column to projects table."""
+    op.add_column('projects', sa.Column('default_agent_id', sa.String(), nullable=True))
+
+
+def downgrade():
+    """Remove default_agent_id column from projects table."""
+    op.drop_column('projects', 'default_agent_id')