solace-agent-mesh 1.4.11__py3-none-any.whl → 1.5.0__py3-none-any.whl

solace_agent_mesh/gateway/http_sse/shared/shared_llm.txt

@@ -0,0 +1,285 @@
+# DEVELOPER GUIDE: shared
+
+## Quick Summary
+The `shared` directory contains common utilities, constants, enums, types, and exception handling used across all layers of the HTTP SSE gateway. It provides authentication helpers, timestamp utilities, standardized exception handling, database utilities, pagination support, and response formatting for consistent API behavior.
+
+## Files Overview
+- `__init__.py` - Central exports for all shared utilities and components
+- `auth_utils.py` - Authentication utilities for FastAPI applications
+- `timestamp_utils.py` - Epoch timestamp utilities matching Java backend patterns
+- `exceptions.py` - Generic web exceptions for HTTP/REST APIs
+- `error_dto.py` - Standardized error response DTOs
+- `exception_handlers.py` - FastAPI exception handlers for consistent HTTP error responses
+- `base_repository.py` - Base repository classes with proper transaction management
+- `pagination.py` - Pagination utilities for API responses
+- `database_exceptions.py` - Database exception handling and conversion
+- `database_helpers.py` - Database utility functions and custom types
+- `response_utils.py` - Standardized response formatting utilities
+- `enums.py` - Enumerations for message types, task status, and validation errors
+- `types.py` - Custom types and type aliases for better type safety
+- `utils.py` - Generic utility functions
+
+## Developer API Reference
+
+### auth_utils.py
+**Purpose:** Provides authentication utilities for FastAPI controllers
+**Import:** `from solace_agent_mesh.gateway.http_sse.shared import get_current_user`
+
+**Functions:**
+- `get_current_user(request: FastAPIRequest) -> dict` - Extracts authenticated user from request state, returns user info or anonymous default
+
+**Usage Examples:**
+```python
+from fastapi import Depends
+from solace_agent_mesh.gateway.http_sse.shared import get_current_user
+
+@app.get("/protected")
+async def protected_endpoint(user: dict = Depends(get_current_user)):
+    return {"user_id": user["id"], "name": user["name"]}
+```
+
+### timestamp_utils.py
+**Purpose:** Provides epoch timestamp utilities for database portability and timezone handling
+**Import:** `from solace_agent_mesh.gateway.http_sse.shared import now_epoch_ms, epoch_ms_to_iso8601, iso8601_to_epoch_ms`
+
+**Functions:**
+- `now_epoch_ms() -> int` - Get current time as milliseconds since epoch
+- `epoch_ms_to_iso8601(epoch_ms: int) -> str` - Convert epoch milliseconds to ISO 8601 string
+- `iso8601_to_epoch_ms(iso8601_string: str) -> int` - Convert ISO 8601 string to epoch milliseconds
+- `datetime_to_epoch_ms(dt: datetime) -> int` - Convert datetime object to epoch milliseconds
+- `epoch_ms_to_datetime(epoch_ms: int) -> datetime` - Convert epoch milliseconds to datetime object
+- `validate_epoch_ms(epoch_ms: int | None) -> bool` - Validate that an epoch milliseconds value is reasonable
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.shared import (
+    now_epoch_ms, epoch_ms_to_iso8601, iso8601_to_epoch_ms
+)
+
+# Get current timestamp for database storage
+created_time = now_epoch_ms()
+
+# Convert for API response
+iso_string = epoch_ms_to_iso8601(created_time)
+
+# Parse from API request
+timestamp = iso8601_to_epoch_ms("2024-01-01T00:00:00Z")
+```
+
+### exceptions.py
+**Purpose:** Generic web exceptions for HTTP/REST APIs
+**Import:** `from solace_agent_mesh.gateway.http_sse.shared import ValidationError, EntityNotFoundError, EntityAlreadyExistsError`
+
+**Classes:**
+- `WebUIBackendException(message: str, details: Optional[Dict[str, Any]] = None)` - Base exception for all web UI backend errors
+- `ValidationError(message: str, validation_details: Optional[Dict[str, List[str]]] = None, entity_type: Optional[str] = None, entity_identifier: Optional[str] = None)` - Exception for validation errors with field-level details
+- `EntityNotFoundError(entity_type: str, entity_id: str)` - Generic exception for when an entity is not found
+- `EntityAlreadyExistsError(entity_type: str, identifier: str, value: Any = None)` - Exception for when an entity already exists
+- `BusinessRuleViolationError(rule: str, message: str)` - Exception for business rule violations
+- `ConfigurationError(component: str, message: str)` - Exception for configuration-related errors
+- `DataIntegrityError(constraint: str, message: str)` - Exception for data integrity violations
+- `ExternalServiceError(service: str, message: str, status_code: Optional[int] = None)` - Exception for external service communication errors
+- `ValidationErrorBuilder()` - Builder for constructing ValidationError instances with fluent API
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.shared import (
+    ValidationError, EntityNotFoundError, ValidationErrorBuilder
+)
+
+# Simple validation error
+raise ValidationError("Invalid input data")
+
+# Entity not found
+raise EntityNotFoundError("User", "123")
+
+# Complex validation with builder
+error = ValidationError.builder() \
+    .message("Invalid user data") \
+    .validation_detail("email", ["Invalid email format"]) \
+    .entity_type("User") \
+    .build()
+```
+
+### error_dto.py
+**Purpose:** Standardized error response DTOs for HTTP APIs
+**Import:** `from solace_agent_mesh.gateway.http_sse.shared import EventErrorDTO`
+
+**Classes:**
+- `EventErrorDTO(message: str, validationDetails: Optional[Dict[str, List[str]]] = None)` - Simplified and standardized error response format
+  - `create(message: str, validation_details: Optional[Dict[str, List[str]]] = None) -> EventErrorDTO` - Create a new EventErrorDTO
+  - `not_found(entity_type: str, entity_id: str) -> EventErrorDTO` - Create a 404 Not Found error
+  - `validation_error(message: str, validation_details: Dict[str, List[str]]) -> EventErrorDTO` - Create a validation error
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.shared import EventErrorDTO
+
+# Simple error
+error = EventErrorDTO.create("Something went wrong")
+
+# Not found error
+error = EventErrorDTO.not_found("User", "123")
+
+# Validation error
+error = EventErrorDTO.validation_error(
+    "Invalid data",
+    {"email": ["Invalid format"], "age": ["Must be positive"]}
+)
+```
+
+### exception_handlers.py
+**Purpose:** FastAPI exception handlers for consistent HTTP error responses
+**Import:** `from solace_agent_mesh.gateway.http_sse.shared import register_exception_handlers`
+
+**Functions:**
+- `register_exception_handlers(app)` - Register all exception handlers with a FastAPI app
+- `create_error_response(status_code: int, message: str, validation_details: dict = None) -> JSONResponse` - Create standardized error response
+
+**Usage Examples:**
+```python
+from fastapi import FastAPI
+from solace_agent_mesh.gateway.http_sse.shared import register_exception_handlers
+
+app = FastAPI()
+register_exception_handlers(app)
+```
+
+### base_repository.py
+**Purpose:** Base repository classes with proper transaction management
+**Import:** `from solace_agent_mesh.gateway.http_sse.shared import BaseRepository, PaginatedRepository, ValidationMixin`
+
+**Classes:**
+- `BaseRepository(model_class: Type[ModelType], entity_class: Type[EntityType])` - Abstract base class for repositories
+  - `create(session: Session, create_data: Dict[str, Any]) -> EntityType` - Create a new entity
+  - `get_by_id(session: Session, entity_id: Any) -> EntityType` - Get entity by ID
+  - `get_all(session: Session, limit: Optional[int] = None, offset: Optional[int] = None) -> List[EntityType]` - Get all entities
+  - `update(session: Session, entity_id: Any, update_data: Dict[str, Any]) -> EntityType` - Update an entity
+  - `delete(session: Session, entity_id: Any) -> None` - Delete an entity
+- `PaginatedRepository(model_class: Type[ModelType], entity_class: Type[EntityType])` - Base repository with enhanced pagination support
+  - `get_paginated(session: Session, page_number: int, page_size: int) -> tuple[List[EntityType], int]` - Get paginated results
+- `ValidationMixin` - Mixin for repositories that need validation logic
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.shared import BaseRepository
+from sqlalchemy.orm import Session
+
+class UserRepository(BaseRepository[UserModel, UserEntity]):
+    @property
+    def entity_name(self) -> str:
+        return "User"
+
+# Usage
+repo = UserRepository(UserModel, UserEntity)
+user = repo.create(session, {"name": "John", "email": "john@example.com"})
+```
+
+### pagination.py
+**Purpose:** Pagination utilities for API responses
+**Import:** `from solace_agent_mesh.gateway.http_sse.shared import PaginationParams, PaginatedResponse, DataResponse`
+
+**Classes:**
+- `PaginationParams(page_number: int = 1, page_size: int = 20)` - Request parameters for pagination
+  - `offset: int` - Calculate the offset for database queries
+- `PaginatedResponse[T](data: list[T], meta: Meta)` - Generic paginated response with data and metadata
+  - `create(data: list[T], total_count: int, pagination: PaginationParams) -> PaginatedResponse[T]` - Create paginated response
+- `DataResponse[T](data: T)` - Simple data response wrapper
+  - `create(data: T) -> DataResponse[T]` - Create data response
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.shared import PaginationParams, PaginatedResponse
+
+# Create pagination params
+pagination = PaginationParams(page_number=1, page_size=20)
+
+# Create paginated response
+response = PaginatedResponse.create(users, total_count=100, pagination=pagination)
+```
+
+### response_utils.py
+**Purpose:** Standardized response formatting utilities
+**Import:** `from solace_agent_mesh.gateway.http_sse.shared import create_data_response, create_paginated_response, StandardResponseMixin`
+
+**Functions:**
+- `create_data_response(data: T) -> DataResponse[T]` - Create a standardized data response
+- `create_paginated_response(data: List[T], total_count: int, pagination_params: PaginationParams) -> PaginatedResponse[T]` - Create a standardized paginated response
+- `create_success_response(message: str = "Success") -> DataResponse[Dict[str, str]]` - Create a standardized success response
+- `create_list_response(items: List[T]) -> DataResponse[List[T]]` - Create a standardized list response
+
+**Classes:**
+- `StandardResponseMixin` - Mixin class to add standard response methods to services or controllers
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.shared import create_data_response, create_paginated_response
+
+# Simple data response
+response = create_data_response({"id": 1, "name": "test"})
+
+# Paginated response
+response = create_paginated_response(users, 100, pagination_params)
+```
+
+### database_exceptions.py
+**Purpose:** Database exception handling and conversion
+**Import:** `from solace_agent_mesh.gateway.http_sse.shared import DatabaseExceptionHandler, handle_database_errors`
+
+**Classes:**
+- `DatabaseExceptionHandler` - Centralized handler for converting SQLAlchemy exceptions to domain exceptions
+  - `handle_integrity_error(e: IntegrityError, entity_type: str = "Resource") -> ValidationError` - Convert integrity constraint violations
+  - `handle_operational_error(e: OperationalError, entity_type: str = "Resource") -> DataIntegrityError` - Handle operational errors
+
+**Functions:**
+- `handle_database_errors(entity_type: str = "Resource")` - Convenience decorator for database exception handling
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.shared import handle_database_errors
+
+class UserRepository:
+    @handle_database_errors("User")
+    def create_user(self, session, data):
+        # Repository method implementation
+        pass
+```
+
+### database_helpers.py
+**Purpose:** Database utility functions and custom types
+**Import:** `from solace_agent_mesh.gateway.http_sse.shared import SimpleJSON`
+
+**Classes:**
+- `SimpleJSON(TypeDecorator)` - Simple JSON type using Text storage for all databases
+
+**Usage Examples:**
+```python
+from sqlalchemy import Column, String
+from solace_agent_mesh.gateway.http_sse.shared import SimpleJSON
+
+class MyModel(Base):
+    id = Column(String, primary_key=True)
+    metadata = Column(SimpleJSON)  # Stores JSON as text
+```
+
+### utils.py
+**Purpose:** Generic utility functions
+**Import:** `from solace_agent_mesh.gateway.http_sse.shared import generate_uuid, to_snake_case, to_pascal_case`
+
+**Functions:**
+- `generate_uuid() -> str` - Generate a UUID string for database storage
+- `to_snake_case(name: str) -> str` - Convert a string to snake_case
+- `to_pascal_case(name: str) -> str` - Convert a string to PascalCase
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.shared import generate_uuid, to_snake_case
+
+# Generate unique ID
+user_id = generate_uuid()
+
+# Convert naming
+snake_name = to_snake_case("User Name")  # "user_name"
+```
+
+# content_hash: 0e33735691fb4637243f4fe61acbba78a388e654834903e34be22e3ce6f3c3bc

solace_agent_mesh/gateway/http_sse/shared/types.py

@@ -35,6 +35,13 @@ class LegacyTimestamp(BaseModel):
     updated_at: datetime | None = None
 
 
+class PaginationParams(BaseModel):
+    """Pagination parameters for list requests."""
+
+    page: int
+    page_size: int
+
+
 class PaginationInfo(BaseModel):
     """Pagination information for list responses."""
 

solace_agent_mesh/gateway/http_sse/utils/__init__.py

@@ -0,0 +1 @@
+"""Utilities for the HTTP SSE Gateway."""

solace_agent_mesh/gateway/http_sse/utils/stim_utils.py

@@ -0,0 +1,32 @@
+"""
+Utility functions for creating .stim file structures.
+"""
+
+from typing import List
+
+from ..repository.entities import Task, TaskEvent
+
+
+def create_stim_from_task_data(task: Task, events: List[TaskEvent]) -> dict:
+    """
+    Formats a task and its events into the .stim file structure.
+
+    Args:
+        task: The task entity.
+        events: A list of task event entities.
+
+    Returns:
+        A dictionary representing the .stim file content.
+    """
+    return {
+        "invocation_details": {
+            "log_file_version": "2.0",  # New version for gateway-generated logs
+            "task_id": task.id,
+            "user_id": task.user_id,
+            "start_time": task.start_time,
+            "end_time": task.end_time,
+            "status": task.status,
+            "initial_request_text": task.initial_request_text,
+        },
+        "invocation_flow": [event.model_dump() for event in events],
+    }

solace_agent_mesh/gateway/http_sse/utils/utils_llm.txt

@@ -0,0 +1,47 @@
+## Quick Summary
+The `utils` directory provides utility functions for the HTTP SSE Gateway, specifically for creating .stim file structures from task and event data.
+
+## Files Overview
+- `__init__.py` - Package initialization file for HTTP SSE Gateway utilities
+- `stim_utils.py` - Utility functions for formatting task data into .stim file structures
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** Package initialization for HTTP SSE Gateway utilities
+**Import:** `from solace_agent_mesh.gateway.http_sse.utils import *`
+
+This file serves as the package entry point and contains no public interfaces.
+
+### stim_utils.py
+**Purpose:** Provides utility functions for creating .stim file structures from task and event data
+**Import:** `from solace_agent_mesh.gateway.http_sse.utils.stim_utils import create_stim_from_task_data`
+
+**Functions:**
+- `create_stim_from_task_data(task: Task, events: List[TaskEvent]) -> dict` - Formats a task and its events into the .stim file structure with version 2.0 format for gateway-generated logs
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.gateway.http_sse.utils.stim_utils import create_stim_from_task_data
+from solace_agent_mesh.gateway.http_sse.repository.entities import Task, TaskEvent
+
+# Create a .stim file structure from task and events
+task = Task(
+    id="task_123",
+    user_id="user_456", 
+    start_time="2024-01-01T10:00:00Z",
+    end_time="2024-01-01T10:05:00Z",
+    status="completed",
+    initial_request_text="Process this data"
+)
+
+events = [
+    TaskEvent(event_type="start", timestamp="2024-01-01T10:00:00Z"),
+    TaskEvent(event_type="complete", timestamp="2024-01-01T10:05:00Z")
+]
+
+stim_data = create_stim_from_task_data(task, events)
+# Returns a dictionary with 'invocation_details' and 'invocation_flow' keys
+```
+
+# content_hash: 7fdc4ad8bbcefb07ee40f84c438f988cda4fdfb812dab55c6a064d1b38b0c83f

solace_agent_mesh/solace_agent_mesh_llm.txt

@@ -359,4 +359,4 @@ async def client_integration_example():
         if hasattr(response.result, 'text_delta'):
             print(response.result.text_delta,
 
-# content_hash: 59d897c57c8a54f55bda0548509f1b6bc7af3a1afde93f59a8525c0eb98659e1
+# content_hash: ce6554bc70f746507a86e0faa0836fe1b338161b5f72a7923df30de5f23ac84e