solace-agent-mesh 1.6.1__py3-none-any.whl → 1.13.2__py3-none-any.whl

solace_agent_mesh/gateway/http_sse/alembic/alembic_llm.txt

@@ -1,295 +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 token usage tracking
-**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
-- `079e06e9b448` - Task management tables (tasks, task_events, feedback)
-- `20250930_token_usage` - Token usage tracking columns for AI model consumption monitoring
-
-## 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.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
-
-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 079e06e9b448
-# Creates: tasks, task_events, feedback tables with proper relationships
-
-# Step 5: Add token usage tracking
-alembic upgrade 20250930_token_usage
-# Adds: token usage columns for AI model consumption monitoring
-```
-
-### 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.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
-
-# 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
-# - Token usage tracking for AI model consumption
-```
-
-### 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 token usage migration
-alembic upgrade 20250930_token_usage --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:
--- 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_messages table:
---   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)
-
--- 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)
-
--- 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
-```
-
-### 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. Token Usage Tracking
-
-```python
-# The 20250930_token_usage migration adds AI model consumption tracking:
-
-# 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
-
-# Usage example after migration:
-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}")
-```
-
-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.
-
-# content_hash: 2904df085decd08d4411ff2583b376a04fc56ba1eae82ba45f4a91e1a930b710

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

@@ -1,155 +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 with token usage tracking.
-
-## 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
-- `20250928_079e06e9b448_add_tasks_task_events_and_feedback_.py` - Adds task management tables (tasks, task_events, feedback)
-- `20250930_add_token_usage_to_tasks.py` - Adds token usage tracking columns to tasks table
-- `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
-```
-
-### 20250928_079e06e9b448_add_tasks_task_events_and_feedback_.py
-**Purpose:** Adds task management functionality with tables for tracking tasks, events, and user feedback
-**Import:** This is an Alembic migration file - not directly imported
-
-**Functions:**
-- `upgrade() -> None` - Creates tasks, task_events, and feedback tables with appropriate indexes and foreign key relationships
-- `downgrade() -> None` - Drops all task-related tables and recreates original session/message indexes
-
-**Constants/Variables:**
-- `revision: str` - Migration identifier "079e06e9b448"
-- `down_revision: Union[str, Sequence[str], None]` - Previous migration "f6e7d8c9b0a1"
-
-**Usage Examples:**
-```bash
-# Run this migration
-alembic upgrade 079e06e9b448
-
-# Rollback this migration
-alembic downgrade f6e7d8c9b0a1
-```
-
-### 20250930_add_token_usage_to_tasks.py
-**Purpose:** Adds token usage tracking columns to the tasks table for monitoring AI model consumption
-**Import:** This is an Alembic migration file - not directly imported
-
-**Functions:**
-- `upgrade() -> None` - Adds token usage columns (total_input_tokens, total_output_tokens, total_cached_input_tokens, token_usage_details) to tasks table
-- `downgrade() -> None` - Removes all token usage columns from tasks table
-
-**Constants/Variables:**
-- `revision: str` - Migration identifier "20250930_token_usage"
-- `down_revision: Union[str, None]` - Previous migration "079e06e9b448"
-
-**Usage Examples:**
-```bash
-# Run this migration
-alembic upgrade 20250930_token_usage
-
-# Rollback this migration
-alembic downgrade 079e06e9b448
-
-# 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"
-```
-
-**Database Schema After All Migrations:**
-```sql
--- Core tables with epoch millisecond timestamps:
--- sessions: id, name, user_id, agent_id, created_time, updated_time
--- chat_messages: id, session_id, message, sender_type, sender_name, created_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
-```
-
-# content_hash: 93bf894b6e5451feedc0b65a723765d7e6798c6912fb3fc34eaf9548d27e4195

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: 6add2167cb9fdee9ed3e46635d6b4e9391cf062dde9e14dba250a3f33c6c4f73