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

solace_agent_mesh/gateway/http_sse/shared/base_repository.py

@@ -0,0 +1,252 @@
+"""
+Base repository classes with proper transaction management.
+
+This module provides base classes for repositories that follow FastAPI best practices
+for database session management and transaction handling.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Generic, TypeVar
+
+from sqlalchemy.orm import Session
+
+from .exceptions import EntityNotFoundError
+
+T = TypeVar("T")
+ModelType = TypeVar("ModelType")
+EntityType = TypeVar("EntityType")
+
+
+class BaseRepository(ABC, Generic[ModelType, EntityType]):
+    """
+    Abstract base class for repositories with common database operations.
+
+    This base class provides common patterns for database operations
+    without manual transaction management, following the principle that
+    transactions should be handled at the service/API layer.
+    """
+
+    def __init__(self, model_class: type[ModelType], entity_class: type[EntityType]):
+        """
+        Initialize repository with model and entity classes.
+
+        Args:
+            model_class: SQLAlchemy model class
+            entity_class: Pydantic entity class
+        """
+        self.model_class = model_class
+        self.entity_class = entity_class
+
+    @property
+    @abstractmethod
+    def entity_name(self) -> str:
+        """Return the entity name for error messages."""
+        pass
+
+    def create(self, session: Session, create_data: dict[str, Any]) -> EntityType:
+        """
+        Create a new entity.
+
+        Args:
+            session: Database session (managed externally)
+            create_data: Data for creating the entity
+
+        Returns:
+            Created entity
+
+        Note:
+            This method does NOT commit the transaction.
+            Commit/rollback is handled by the service layer.
+        """
+        model_instance = self.model_class(**create_data)
+
+        session.add(model_instance)
+        session.flush()  # Flush to get generated IDs
+        session.refresh(model_instance)
+
+        entity = self.entity_class.model_validate(model_instance)
+
+        return entity
+
+    def get_by_id(self, session: Session, entity_id: Any) -> EntityType:
+        """
+        Get entity by ID.
+
+        Args:
+            session: Database session
+            entity_id: Entity identifier
+
+        Returns:
+            Entity instance
+
+        Raises:
+            EntityNotFoundError: If entity not found
+        """
+        model_instance = (
+            session.query(self.model_class)
+            .filter(self.model_class.id == str(entity_id))
+            .first()
+        )
+
+        if not model_instance:
+            raise EntityNotFoundError(self.entity_name, entity_id)
+
+        return self.entity_class.model_validate(model_instance)
+
+    def get_all(
+        self, session: Session, limit: int | None = None, offset: int | None = None
+    ) -> list[EntityType]:
+        """
+        Get all entities with optional pagination.
+
+        Args:
+            session: Database session
+            limit: Maximum number of results
+            offset: Number of results to skip
+
+        Returns:
+            List of entities
+        """
+        query = session.query(self.model_class)
+
+        if offset:
+            query = query.offset(offset)
+        if limit:
+            query = query.limit(limit)
+
+        model_instances = query.all()
+        return [
+            self.entity_class.model_validate(instance) for instance in model_instances
+        ]
+
+    def update(
+        self, session: Session, entity_id: Any, update_data: dict[str, Any]
+    ) -> EntityType:
+        """
+        Update an entity.
+
+        Args:
+            session: Database session
+            entity_id: Entity identifier
+            update_data: Data to update
+
+        Returns:
+            Updated entity
+
+        Raises:
+            EntityNotFoundError: If entity not found
+        """
+        model_instance = (
+            session.query(self.model_class)
+            .filter(self.model_class.id == str(entity_id))
+            .first()
+        )
+
+        if not model_instance:
+            raise EntityNotFoundError(self.entity_name, entity_id)
+
+        for key, value in update_data.items():
+            if value is not None and hasattr(model_instance, key):
+                setattr(model_instance, key, value)
+
+        session.flush()  # Flush to validate constraints
+        session.refresh(model_instance)
+
+        entity = self.entity_class.model_validate(model_instance)
+
+        return entity
+
+    def delete(self, session: Session, entity_id: Any) -> None:
+        """
+        Delete an entity.
+
+        Args:
+            session: Database session
+            entity_id: Entity identifier
+
+        Raises:
+            EntityNotFoundError: If entity not found
+        """
+        model_instance = (
+            session.query(self.model_class)
+            .filter(self.model_class.id == str(entity_id))
+            .first()
+        )
+
+        if not model_instance:
+            raise EntityNotFoundError(self.entity_name, entity_id)
+
+        session.delete(model_instance)
+        session.flush()  # Flush to validate constraints
+
+    def exists(self, session: Session, entity_id: Any) -> bool:
+        """
+        Check if an entity exists.
+
+        Args:
+            session: Database session
+            entity_id: Entity identifier
+
+        Returns:
+            True if entity exists, False otherwise
+        """
+        count = (
+            session.query(self.model_class)
+            .filter(self.model_class.id == str(entity_id))
+            .count()
+        )
+
+        return count > 0
+
+    def count(self, session: Session) -> int:
+        """
+        Get total count of entities.
+
+        Args:
+            session: Database session
+
+        Returns:
+            Total number of entities
+        """
+        return session.query(self.model_class).count()
+
+
+class PaginatedRepository(BaseRepository[ModelType, EntityType]):
+    """
+    Base repository with pagination support.
+
+    Concrete repositories should implement their own pagination methods
+    that apply specific filters and ordering before pagination.
+    """
+
+    pass
+
+
+class ValidationMixin:
+    """
+    Mixin for repositories that need validation logic.
+    """
+
+    def validate_create_data(self, create_data: dict[str, Any]) -> None:
+        """
+        Validate data before creation.
+
+        Args:
+            create_data: Data to validate
+
+        Raises:
+            ValidationError: If validation fails
+        """
+        pass
+
+    def validate_update_data(self, update_data: dict[str, Any]) -> None:
+        """
+        Validate data before update.
+
+        Args:
+            update_data: Data to validate
+
+        Raises:
+            ValidationError: If validation fails
+        """
+        pass

solace_agent_mesh/gateway/http_sse/shared/database_exceptions.py

@@ -0,0 +1,274 @@
+"""
+Database Exception Handling
+
+Provides centralized handling for converting SQLAlchemy exceptions to domain exceptions.
+This handler translates low-level database errors into meaningful business exceptions
+that can be properly handled by the API layer.
+"""
+
+from typing import Optional, Dict, List
+from sqlalchemy.exc import IntegrityError, SQLAlchemyError, OperationalError, DatabaseError
+from .exceptions import ValidationError, DataIntegrityError, EntityAlreadyExistsError
+
+
+class DatabaseExceptionHandler:
+    """
+    Centralized handler for converting SQLAlchemy exceptions to domain exceptions.
+
+    This handler translates low-level database errors into meaningful business exceptions
+    that can be properly handled by the API layer.
+    """
+
+    @staticmethod
+    def handle_integrity_error(e: IntegrityError, entity_type: str = "Resource") -> ValidationError:
+        """
+        Convert SQLAlchemy integrity constraint violations to domain exceptions.
+
+        Args:
+            e: The SQLAlchemy IntegrityError
+            entity_type: The type of entity being operated on
+
+        Returns:
+            ValidationError with appropriate message and validation details
+        """
+        # Try to get the most descriptive error message for constraint matching
+        full_message = str(e)
+        orig_message = str(e.orig) if hasattr(e, 'orig') and e.orig else ""
+
+        # Use the message that contains constraint information
+        if any(keyword in full_message for keyword in ['constraint', 'UNIQUE', 'NULL', 'CHECK', 'FOREIGN']):
+            # Extract the most specific constraint line from the full message
+            lines = full_message.split('\n')
+
+            # Prioritize SQL lines that contain actual constraint details
+            for line in lines:
+                if '[SQL:' in line and any(keyword in line for keyword in ['UNIQUE', 'NULL', 'CHECK', 'FOREIGN']):
+                    # Extract just the SQL part without the [SQL: ] wrapper
+                    if '[SQL:' in line and ']' in line:
+                        error_message = line.split('[SQL:')[1].split(']')[0].strip()
+                        break
+                    error_message = line.strip()
+                    break
+            else:
+                # Fallback to any line with constraint keywords
+                for line in lines:
+                    if any(keyword in line for keyword in ['constraint', 'UNIQUE', 'NULL', 'CHECK', 'FOREIGN']):
+                        error_message = line.strip()
+                        break
+                else:
+                    error_message = full_message
+        else:
+            # Fallback to orig if no constraint info in main message
+            error_message = orig_message or full_message
+
+        # Handle UNIQUE constraint violations and concurrent modifications
+        if ("UNIQUE constraint failed" in error_message or
+            "duplicate key value" in error_message.lower() or
+            "concurrent modification" in error_message.lower() or
+            "row was updated or deleted by another transaction" in error_message.lower()):
+            field_name = DatabaseExceptionHandler._extract_field_from_unique_error(error_message)
+            return EntityAlreadyExistsError(
+                entity_type=entity_type,
+                identifier=field_name,
+                value="provided value"
+            )
+
+        # Handle NOT NULL constraint violations
+        if "NOT NULL constraint failed" in error_message or "null value in column" in error_message.lower():
+            field_name = DatabaseExceptionHandler._extract_field_from_null_error(error_message)
+            return ValidationError(
+                message="Required field is missing",
+                validation_details={field_name: ["This field is required"]},
+                entity_type=entity_type
+            )
+
+        # Handle CHECK constraint violations
+        if "CHECK constraint failed" in error_message or "check constraint" in error_message.lower():
+            constraint_name = DatabaseExceptionHandler._extract_constraint_name(error_message)
+            field_name = DatabaseExceptionHandler._map_constraint_to_field(constraint_name)
+            return ValidationError(
+                message="Field validation failed",
+                validation_details={field_name: ["Value violates validation rules"]},
+                entity_type=entity_type
+            )
+
+        # Handle FOREIGN KEY constraint violations
+        if "FOREIGN KEY constraint failed" in error_message or "foreign key constraint" in error_message.lower():
+            return ValidationError(
+                message="Referenced resource does not exist",
+                validation_details={"reference": ["Invalid reference to related resource"]},
+                entity_type=entity_type
+            )
+
+        # Generic integrity error fallback
+        return DataIntegrityError(
+            constraint="integrity_violation",
+            message=f"Database constraint violation: {error_message}"
+        )
+
+    @staticmethod
+    def handle_operational_error(e: OperationalError, entity_type: str = "Resource") -> DataIntegrityError:
+        """
+        Handle SQLAlchemy operational errors (connection issues, timeouts, etc.).
+
+        Args:
+            e: The SQLAlchemy OperationalError
+            entity_type: The type of entity being operated on
+
+        Returns:
+            DataIntegrityError with appropriate message
+        """
+        error_message = str(e.orig) if hasattr(e, 'orig') else str(e)
+
+        if "timeout" in error_message.lower():
+            return DataIntegrityError(
+                constraint="timeout",
+                message="Database operation timed out. Please try again."
+            )
+
+        if "connection" in error_message.lower():
+            return DataIntegrityError(
+                constraint="connection_error",
+                message="Database connection failed. Please try again later."
+            )
+
+        return DataIntegrityError(
+            constraint="operational_error",
+            message="Database operation failed. Please contact support if this persists."
+        )
+
+    @staticmethod
+    def handle_database_error(e: DatabaseError, entity_type: str = "Resource") -> DataIntegrityError:
+        """
+        Handle general SQLAlchemy database errors.
+
+        Args:
+            e: The SQLAlchemy DatabaseError
+            entity_type: The type of entity being operated on
+
+        Returns:
+            DataIntegrityError with appropriate message
+        """
+        error_message = str(e.orig) if hasattr(e, 'orig') else str(e)
+
+        return DataIntegrityError(
+            constraint="database_error",
+            message="A database error occurred. Please contact support."
+        )
+
+    @staticmethod
+    def handle_sqlalchemy_error(e: SQLAlchemyError, entity_type: str = "Resource") -> DataIntegrityError:
+        """
+        Handle any other SQLAlchemy errors not caught by specific handlers.
+
+        Args:
+            e: The SQLAlchemy error
+            entity_type: The type of entity being operated on
+
+        Returns:
+            DataIntegrityError with generic message
+        """
+        error_message = str(e)
+
+        return DataIntegrityError(
+            constraint="sqlalchemy_error",
+            message="An unexpected database error occurred. Please contact support."
+        )
+
+    @staticmethod
+    def _extract_field_from_unique_error(error_message: str) -> str:
+        """Extract field name from UNIQUE constraint error message."""
+        # Try to extract field name from common formats
+        if "agents.name" in error_message:
+            return "name"
+        elif "agents.id" in error_message:
+            return "id"
+        elif "." in error_message:
+            # Extract field after table.field pattern
+            parts = error_message.split(".")
+            if len(parts) > 1:
+                field_part = parts[1].split()[0]  # Get first word after dot
+                return field_part.strip('()"\'')
+
+        return "field"  # Generic fallback
+
+    @staticmethod
+    def _extract_field_from_null_error(error_message: str) -> str:
+        """Extract field name from NOT NULL constraint error message."""
+        # Common patterns: "NOT NULL constraint failed: agents.name"
+        if ":" in error_message:
+            field_part = error_message.split(":")[-1].strip()
+            if "." in field_part:
+                return field_part.split(".")[-1]
+            return field_part
+
+        return "field"  # Generic fallback
+
+    @staticmethod
+    def _extract_constraint_name(error_message: str) -> str:
+        """Extract constraint name from CHECK constraint error message."""
+        # Common patterns: "CHECK constraint failed: check_name_length"
+        if ":" in error_message:
+            constraint_part = error_message.split(":")[-1].strip()
+            return constraint_part
+
+        return "unknown_constraint"
+
+    @staticmethod
+    def _map_constraint_to_field(constraint_name: str) -> str:
+        """Map database constraint names to user-friendly field names."""
+        constraint_field_map = {
+            "check_name_length": "name",
+            "check_description_length": "description",
+            "check_system_prompt_length": "systemPrompt",
+            "check_created_by_length": "createdBy",
+            "check_updated_by_length": "updatedBy",
+            "check_id_length": "id"
+        }
+
+        return constraint_field_map.get(constraint_name, "field")
+
+
+class DatabaseErrorDecorator:
+    """
+    Decorator class for wrapping repository methods with database exception handling.
+    """
+
+    def __init__(self, entity_type: str = "Resource"):
+        self.entity_type = entity_type
+
+    def __call__(self, func):
+        """
+        Decorator that wraps repository methods with database exception handling.
+
+        Args:
+            func: The repository method to wrap
+
+        Returns:
+            Wrapped function with exception handling
+        """
+        def wrapper(*args, **kwargs):
+            try:
+                return func(*args, **kwargs)
+            except IntegrityError as e:
+                raise DatabaseExceptionHandler.handle_integrity_error(e, self.entity_type)
+            except OperationalError as e:
+                raise DatabaseExceptionHandler.handle_operational_error(e, self.entity_type)
+            except DatabaseError as e:
+                raise DatabaseExceptionHandler.handle_database_error(e, self.entity_type)
+            except SQLAlchemyError as e:
+                raise DatabaseExceptionHandler.handle_sqlalchemy_error(e, self.entity_type)
+
+        return wrapper
+
+
+def handle_database_errors(entity_type: str = "Resource"):
+    """
+    Convenience decorator for database exception handling.
+
+    Usage:
+        @handle_database_errors("Agent")
+        def create_agent(self, ...):
+            # Repository method implementation
+    """
+    return DatabaseErrorDecorator(entity_type)

solace_agent_mesh/gateway/http_sse/shared/database_helpers.py

@@ -0,0 +1,43 @@
+"""
+Database Helper Functions
+
+Provides database utility functions and custom types.
+Separated from dependencies.py to avoid circular imports.
+"""
+
+import json
+from sqlalchemy import Text, TypeDecorator
+from .exceptions import DataIntegrityError
+
+
+class SimpleJSON(TypeDecorator):
+    """Simple JSON type using Text storage for all databases."""
+
+    impl = Text
+    cache_ok = True
+
+    def process_bind_param(self, value, dialect):
+        """Convert Python object to JSON string for storage."""
+        if value is not None:
+            return json.dumps(value, default=self._json_serializer, ensure_ascii=False)
+        return value
+
+    def process_result_value(self, value, dialect):
+        """Convert JSON string back to Python object."""
+        if value is not None and isinstance(value, str):
+            try:
+                return json.loads(value)
+            except (ValueError, TypeError, json.JSONDecodeError) as e:
+                raise DataIntegrityError("json_parsing", f"Invalid JSON data in database: {value}") from e
+        return value
+
+    @staticmethod
+    def _json_serializer(obj):
+        """Custom JSON serializer for complex objects."""
+        if model_dump := getattr(obj, 'model_dump', None):
+            return model_dump()
+        elif dict_method := getattr(obj, 'dict', None):
+            return dict_method()
+        elif obj_dict := getattr(obj, '__dict__', None):
+            return obj_dict
+        raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")

solace_agent_mesh/gateway/http_sse/shared/enums.py

@@ -0,0 +1,40 @@
+"""
+Enumerations used throughout the application.
+"""
+
+from enum import Enum
+
+
+class SenderType(str, Enum):
+    """Types of message senders."""
+    USER = "user"
+    AGENT = "agent"
+    SYSTEM = "system"
+
+
+class TaskStatus(str, Enum):
+    """Task execution status."""
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+
+
+class MessageType(str, Enum):
+    """Types of messages."""
+    TEXT = "text"
+    FILE = "file"
+    IMAGE = "image"
+    DOCUMENT = "document"
+
+
+class ValidationErrorType(str, Enum):
+    """Types of validation errors."""
+    REQUIRED_FIELD = "required_field"
+    INVALID_FORMAT = "invalid_format"
+    OUT_OF_RANGE = "out_of_range"
+    DUPLICATE_VALUE = "duplicate_value"
+    BUSINESS_RULE = "business_rule"