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

solace_agent_mesh/gateway/http_sse/alembic/alembic_llm.txt

@@ -1,345 +0,0 @@
-# DEVELOPER GUIDE: alembic
-
-## Quick Summary
-This directory contains Alembic database migration configuration and version files for the HTTP SSE gateway. It provides database schema management capabilities, including initial table creation, performance optimization through indexing, timestamp format standardization, and task management features with token usage tracking. The directory consists of the main Alembic environment configuration (`env.py`) and a versions subdirectory containing sequential migration files that handle schema evolution over time.
-
-## Files and Subdirectories Overview
-- **Direct files:**
-  - `env.py` - Alembic environment configuration for running migrations in offline/online modes
-
-- **Subdirectories:**
-  - `versions/` - Contains sequential database migration files for schema evolution and task management
-
-## Developer API Reference
-
-### Direct Files
-
-#### env.py
-**Purpose:** Alembic environment configuration that handles migration execution in both offline and online modes with proper model registration
-**Import:** This is an Alembic configuration file - not directly imported by application code
-
-**Functions:**
-- `run_migrations_offline() -> None` - Executes migrations without database connection (generates SQL scripts)
-- `run_migrations_online() -> None` - Executes migrations with live database connection and proper URL handling
-
-**Constants/Variables:**
-- `config` - Alembic Config object providing access to .ini file values
-- `target_metadata` - SQLAlchemy metadata from repository Base class for autogenerate support
-
-### Subdirectory APIs
-
-#### versions/
-**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
-# These are migration files executed by Alembic CLI, not directly imported
-# Access via Alembic commands:
-# alembic upgrade head
-# alembic downgrade base
-```
-
-**Available Migrations:**
-- `d5b3f8f2e9a0` - Initial database schema (sessions and chat_messages tables)
-- `b1c2d3e4f5g6` - Performance indexes for query optimization
-- `f6e7d8c9b0a1` - Timestamp conversion to epoch milliseconds
-- `98882922fa59` - Task management tables (tasks, task_events, feedback, chat_tasks)
-- `20251015_session_idx` - Optimized composite indexes for better query performance
-
-## Complete Usage Guide
-
-### 1. Setting Up Alembic Environment
-
-```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.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
-
-target_metadata = Base.metadata
-```
-
-### 2. Running Migrations
-
-```bash
-# Check current migration status
-alembic current
-
-# Run all pending migrations to latest
-alembic upgrade head
-
-# Run specific migration
-alembic upgrade d5b3f8f2e9a0
-
-# Rollback to previous migration
-alembic downgrade -1
-
-# Rollback to specific migration
-alembic downgrade b1c2d3e4f5g6
-
-# Rollback all migrations
-alembic downgrade base
-
-# View migration history
-alembic history
-```
-
-### 3. Complete Migration Sequence and Schema Evolution
-
-```bash
-# Step 1: Create initial database schema
-alembic upgrade d5b3f8f2e9a0
-# Creates: sessions table, chat_messages table with relationships
-
-# Step 2: Add performance indexes
-alembic upgrade b1c2d3e4f5g6
-# Adds: indexes on user_id, timestamps, composite fields
-
-# Step 3: Modernize timestamp format
-alembic upgrade f6e7d8c9b0a1
-# Converts: datetime columns to epoch milliseconds
-# Renames: columns for consistency (created_at → created_time)
-
-# Step 4: Add task management features
-alembic upgrade 98882922fa59
-# Creates: tasks, task_events, feedback, chat_tasks tables
-# Replaces: chat_messages with chat_tasks for better task tracking
-
-# Step 5: Add optimized performance indexes
-alembic upgrade 20251015_session_idx
-# Adds: composite indexes for optimal query patterns
-```
-
-### 4. Working with Different Database Engines
-
-```python
-# The env.py handles multiple database types automatically
-# Configure database URL in alembic.ini or environment:
-
-# PostgreSQL
-# sqlalchemy.url = postgresql://user:pass@localhost/dbname
-
-# SQLite
-# sqlalchemy.url = sqlite:///./database.db
-
-# MySQL
-# sqlalchemy.url = mysql://user:pass@localhost/dbname
-```
-
-### 5. Integration with Repository Layer
-
-```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.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
-
-# After running all migrations, your models will have the updated schema:
-# - All timestamp fields use epoch milliseconds
-# - Proper indexes for performance
-# - Standardized column names
-# - Complete task management functionality
-# - Optimized composite indexes for query performance
-```
-
-### 6. Offline Migration Generation
-
-```bash
-# Generate SQL scripts without executing (useful for production deployments)
-# This uses run_migrations_offline() function from env.py
-
-# Generate SQL for specific migration
-alembic upgrade d5b3f8f2e9a0 --sql
-
-# Generate SQL for all pending migrations
-alembic upgrade head --sql
-
-# Generate SQL for performance optimization
-alembic upgrade 20251015_session_idx --sql
-```
-
-### 7. Common Development Patterns
-
-```bash
-# Development workflow:
-# 1. Make model changes in repository
-# 2. Generate new migration
-alembic revision --autogenerate -m "description of changes"
-
-# 3. Review generated migration file
-# 4. Test migration
-alembic upgrade head
-
-# 5. Test rollback
-alembic downgrade -1
-
-# Production deployment:
-# 1. Generate SQL scripts
-alembic upgrade head --sql > migration.sql
-
-# 2. Review and execute SQL manually in production
-```
-
-### 8. Database Schema After All Migrations
-
-```sql
--- Final schema structure after all migrations:
-
--- Core tables with epoch millisecond timestamps:
--- sessions table:
---   id (String, Primary Key)
---   name (String)
---   user_id (String, Indexed)
---   agent_id (String)
---   created_time (BigInteger, epoch ms)
---   updated_time (BigInteger, epoch ms)
-
--- chat_tasks table (replaces chat_messages):
---   id (String, Primary Key)
---   session_id (String, Foreign Key to sessions.id)
---   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:
---   id (String, Primary Key)
---   user_id (String, Indexed)
---   start_time (BigInteger, epoch ms)
---   end_time (BigInteger, epoch ms)
---   status (String)
---   initial_request_text (Text)
---   total_input_tokens (Integer)
---   total_output_tokens (Integer)
---   total_cached_input_tokens (Integer)
---   token_usage_details (Text, JSON)
-
--- task_events table:
---   id (String, Primary Key)
---   task_id (String, Foreign Key to tasks.id)
---   user_id (String)
---   created_time (BigInteger, epoch ms)
---   topic (String)
---   direction (String)
---   payload (Text)
-
--- feedback table:
---   id (String, Primary Key)
---   session_id (String, Foreign Key to sessions.id)
---   task_id (String, Foreign Key to tasks.id)
---   user_id (String)
---   rating (Integer)
---   comment (Text)
---   created_time (BigInteger, epoch ms)
-
--- 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
-
-```python
-# The f6e7d8c9b0a1 migration handles database-specific timestamp conversion:
-
-# SQLite: Uses table recreation approach
-# - Creates new tables with epoch millisecond columns
-# - Migrates data with timestamp conversion
-# - Drops old tables and renames new ones
-
-# PostgreSQL/MySQL: Uses ALTER COLUMN approach
-# - Directly modifies column types
-# - Converts existing data in place
-# - More efficient for large datasets
-```
-
-### 10. Performance Optimization Features
-
-```python
-# 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
-
-# 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 all migrations:
-from solace_agent_mesh.gateway.http_sse.repository.models.task_model import TaskModel
-
-# 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 optimized query patterns for the HTTP SSE gateway component.
-
-# content_hash: 1211a2aee2a0eb3361ee0f61e504f720c4cf454569a46c5f3991507db9a0cab9

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

@@ -1,161 +0,0 @@
-# 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/components/components_llm.txt

@@ -1,105 +0,0 @@
-# DEVELOPER GUIDE: components
-
-## Quick Summary
-This directory contains SAC (Solace AI Connector) components for the HTTP SSE (Server-Sent Events) gateway. These components forward messages from Solace broker inputs to internal Python queues, enabling real-time visualization and task logging in web-based user interfaces.
-
-## Files Overview
-- `__init__.py` - Makes the `VisualizationForwarderComponent` class directly importable from the components package
-- `components_llm.txt` - Developer guide documentation for this directory
-- `task_logger_forwarder.py` - SAC component that forwards messages to a task logging queue
-- `visualization_forwarder_component.py` - SAC component that forwards messages to a visualization queue
-
-## Developer API Reference
-
-### __init__.py
-**Purpose:** Exposes the public components of this directory for easy importing
-**Import:** `from solace_agent_mesh.gateway.http_sse.components import VisualizationForwarderComponent`
-
-**Exports:**
-- `VisualizationForwarderComponent` - The main component class for forwarding messages to a visualization queue
-
-### task_logger_forwarder.py
-**Purpose:** A SAC component that forwards messages from a BrokerInput to a target queue for task logging
-**Import:** `from solace_agent_mesh.gateway.http_sse.components.task_logger_forwarder import TaskLoggerForwarderComponent`
-
-**Classes:**
-- `TaskLoggerForwarderComponent(**kwargs: Any)` - A component that forwards messages to a task logging queue, initialized with configuration parameters including `target_queue_ref`
-  - `invoke(message: SolaceMessage, data: Dict[str, Any]) -> None` - Core method called by SAC framework for each incoming message; formats data and places it onto the target queue
-  - `target_queue: queue.Queue` - The queue instance where messages are forwarded
-
-**Constants/Variables:**
-- `info: Dict` - Metadata dictionary required by SAC framework describing component configuration, input schema, and purpose
-
-**Usage Examples:**
-```python
-import queue
-from solace_agent_mesh.gateway.http_sse.components.task_logger_forwarder import TaskLoggerForwarderComponent
-from solace_ai_connector.common.message import Message as SolaceMessage
-
-# 1. Create a target queue for task logging
-task_logging_queue = queue.Queue()
-
-# 2. Instantiate the component with target queue reference
-task_forwarder = TaskLoggerForwarderComponent(
-    name="task_logger",
-    target_queue_ref=task_logging_queue
-)
-
-# 3. The invoke method is called automatically by SAC framework
-# when messages arrive from connected BrokerInput component
-
-# 4. Consume forwarded messages from the queue
-if not task_logging_queue.empty():
-    forwarded_data = task_logging_queue.get()
-    print(f"Task Topic: {forwarded_data['topic']}")
-    print(f"Task Payload: {forwarded_data['payload']}")
-    print(f"User Properties: {forwarded_data['user_properties']}")
-```
-
-### visualization_forwarder_component.py
-**Purpose:** A SAC component that forwards messages from a BrokerInput to a target queue for visualization
-**Import:** `from solace_agent_mesh.gateway.http_sse.components.visualization_forwarder_component import VisualizationForwarderComponent`
-
-**Classes:**
-- `VisualizationForwarderComponent(**kwargs: Any)` - A component that forwards messages to a visualization queue, initialized with configuration parameters including `target_queue_ref`
-  - `invoke(message: SolaceMessage, data: Dict[str, Any]) -> None` - Core method called by SAC framework for each incoming message; formats data and places it onto the target queue
-  - `target_queue: queue.Queue` - The queue instance where messages are forwarded
-
-**Constants/Variables:**
-- `info: Dict` - Metadata dictionary required by SAC framework describing component configuration, input schema, and purpose
-
-**Usage Examples:**
-```python
-import queue
-from solace_agent_mesh.gateway.http_sse.components import VisualizationForwarderComponent
-from solace_ai_connector.common.message import Message as SolaceMessage
-
-# 1. Create a target queue that will receive the forwarded messages
-visualization_queue = queue.Queue()
-
-# 2. Instantiate the component with target queue reference
-forwarder = VisualizationForwarderComponent(
-    name="my_forwarder",
-    target_queue_ref=visualization_queue
-)
-
-# 3. The invoke method is called automatically by SAC framework
-# when messages arrive from connected BrokerInput component
-
-# 4. Consume forwarded messages from the queue
-if not visualization_queue.empty():
-    forwarded_data = visualization_queue.get()
-    print(f"Topic: {forwarded_data['topic']}")
-    print(f"Payload: {forwarded_data['payload']}")
-    print(f"User Properties: {forwarded_data['user_properties']}")
-    
-# Expected structure of forwarded_data:
-# {
-#     "topic": "some/broker/topic",
-#     "payload": {"key": "value"},
-#     "user_properties": {"prop1": "value1"},
-#     "_original_broker_message": <SolaceMessage object>
-# }
-```
-
-# content_hash: bb6b96e24d423d56a25e3c84eb411d061ad160ea98fc2ff83da46e3f317d34fb