aegis-stack 0.1.0__py3-none-any.whl

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/services/load_test_models.py

@@ -0,0 +1,269 @@
+"""
+Pydantic models for load test data structures.
+
+Provides type safety and validation for load test configurations,
+results, and analysis data.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field, ValidationInfo, field_validator, model_validator
+
+from app.components.worker.constants import LoadTestTypes
+from app.core.config import get_load_test_queue
+
+
+class LoadTestError(Exception):
+    """Custom exception for load test operations."""
+    pass
+
+
+class LoadTestConfiguration(BaseModel):
+    """Load test configuration with validation and defaults."""
+
+    num_tasks: int = Field(
+        default=100, ge=10, le=10000, description="Number of tasks to spawn"
+    )
+    task_type: LoadTestTypes = Field(
+        default=LoadTestTypes.CPU_INTENSIVE, description="Type of load test to run"
+    )
+    batch_size: int = Field(default=10, ge=1, le=100, description="Tasks per batch")
+    delay_ms: int = Field(
+        default=0, ge=0, le=5000, description="Delay between batches (ms)"
+    )
+    target_queue: str | None = Field(
+        default=None, description="Target queue for testing"
+    )
+
+    @field_validator('target_queue')
+    @classmethod
+    def set_default_queue(cls, v: str | None) -> str:
+        """Set default queue if not specified."""
+        return v if v is not None else get_load_test_queue()
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        """Convert configuration to dictionary for task enqueueing."""
+        data = super().model_dump(**kwargs)
+        # Convert enum to string value for task enqueueing
+        data["task_type"] = self.task_type.value
+        return data
+
+
+class LoadTestMetrics(BaseModel):
+    """Metrics from load test execution."""
+
+    tasks_sent: int = Field(..., ge=0, description="Total tasks enqueued")
+    tasks_completed: int = Field(..., ge=0, description="Successfully completed tasks")
+    tasks_failed: int = Field(0, ge=0, description="Failed tasks")
+    total_duration_seconds: float = Field(..., ge=0, description="Total test duration")
+    overall_throughput: float = Field(
+        0, ge=0, description="Overall throughput (tasks/sec)"
+    )
+    failure_rate_percent: float = Field(
+        0, ge=0, le=100, description="Failure rate percentage"
+    )
+    completion_percentage: float = Field(
+        0, ge=0, le=100, description="Completion percentage"
+    )
+    average_throughput_per_second: float = Field(
+        0, ge=0, description="Average throughput"
+    )
+    monitor_duration_seconds: float = Field(0, ge=0, description="Monitoring duration")
+
+    @field_validator("tasks_completed")
+    @classmethod
+    def completed_not_exceed_sent(cls, v: int, info: ValidationInfo) -> int:
+        """Ensure completed tasks don't exceed sent tasks."""
+        if info.data and "tasks_sent" in info.data and v > info.data["tasks_sent"]:
+            raise ValueError(
+                f"Completed tasks ({v}) cannot exceed sent tasks "
+                f"({info.data['tasks_sent']})"
+            )
+        return v
+
+    @field_validator("tasks_failed")
+    @classmethod
+    def failed_not_exceed_sent(cls, v: int, info: ValidationInfo) -> int:
+        """Ensure failed tasks don't exceed sent tasks."""
+        if info.data and "tasks_sent" in info.data and v > info.data["tasks_sent"]:
+            raise ValueError(
+                f"Failed tasks ({v}) cannot exceed sent tasks "
+                f"({info.data['tasks_sent']})"
+            )
+        return v
+
+    @field_validator("failure_rate_percent")
+    @classmethod
+    def validate_failure_rate_consistency(cls, v: float, info: ValidationInfo) -> float:
+        """Ensure failure rate percentage matches task counts."""
+        if info.data and "tasks_sent" in info.data and "tasks_failed" in info.data:
+            tasks_sent = info.data["tasks_sent"]
+            tasks_failed = info.data["tasks_failed"]
+            if tasks_sent > 0:
+                calculated_rate = (tasks_failed / tasks_sent) * 100
+                # Allow small floating point differences (within 0.1%)
+                if abs(v - calculated_rate) > 0.1:
+                    raise ValueError(
+                        f"Failure rate {v}% doesn't match task counts "
+                        f"({tasks_failed}/{tasks_sent} = {calculated_rate:.1f}%)"
+                    )
+        return v
+
+
+class PerformanceAnalysis(BaseModel):
+    """Performance analysis results."""
+
+    throughput_rating: str = Field(
+        ...,
+        pattern=r"^(unknown|poor|fair|good|excellent)$",
+        description="Throughput performance rating"
+    )
+    efficiency_rating: str = Field(
+        ...,
+        pattern=r"^(unknown|poor|fair|good|excellent)$",
+        description="Task completion efficiency"
+    )
+    queue_pressure: str = Field(
+        ...,
+        pattern=r"^(unknown|low|moderate|high)$",
+        description="Queue saturation level"
+    )
+
+
+class ValidationStatus(BaseModel):
+    """Test execution validation status."""
+
+    test_type_verified: bool = Field(
+        default=False, description="Test type executed correctly"
+    )
+    expected_metrics_present: bool = Field(
+        default=False, description="Expected metrics are present"
+    )
+    performance_signature_match: str = Field(
+        default="unknown",
+        pattern=r"^(unknown|verified|partial|failed)$",
+        description="Performance matches expected patterns"
+    )
+    issues: list[str] = Field(default_factory=list, description="Validation issues")
+
+
+class TestTypeInfo(BaseModel):
+    """Information about a specific test type."""
+
+    name: str = Field(..., description="Human-readable test name")
+    description: str = Field(..., description="Test description")
+    expected_metrics: list[str] = Field(..., description="Expected result metrics")
+    performance_signature: str = Field(..., description="Expected performance pattern")
+    typical_duration_ms: str = Field(..., description="Typical execution time")
+    concurrency_impact: str = Field(..., description="Concurrency characteristics")
+    validation_keys: list[str] = Field(..., description="Keys for result validation")
+
+
+class LoadTestAnalysis(BaseModel):
+    """Complete load test analysis."""
+
+    test_type_info: TestTypeInfo = Field(..., description="Test type information")
+    performance_analysis: PerformanceAnalysis = Field(
+        ..., description="Performance analysis"
+    )
+    validation_status: ValidationStatus = Field(..., description="Validation results")
+    recommendations: list[str] = Field(..., description="Improvement recommendations")
+
+
+class LoadTestResult(BaseModel):
+    """Complete load test result with analysis."""
+
+    task: str = Field(default="load_test_orchestrator", description="Task name")
+    status: str = Field(
+        ...,
+        pattern=r"^(completed|failed|timed_out)$",
+        description="Test execution status"
+    )
+    test_id: str = Field(..., description="Unique test identifier")
+    configuration: LoadTestConfiguration = Field(..., description="Test configuration")
+    metrics: LoadTestMetrics = Field(..., description="Execution metrics")
+    start_time: str | None = Field(None, description="Test start time")
+    end_time: str | None = Field(None, description="Test end time")
+    task_ids: list[str] = Field(default_factory=list, description="Individual task IDs")
+    error: str | None = Field(None, description="Error message if failed")
+    analysis: LoadTestAnalysis | None = Field(
+        None, description="Performance analysis"
+    )
+
+    @model_validator(mode='after')
+    def validate_status_consistency(self) -> 'LoadTestResult':
+        """Validate status consistency with error field."""
+        if self.status == 'failed' and not self.error:
+            raise ValueError("Failed status requires error message")
+        return self
+
+
+class OrchestratorRawResult(BaseModel):
+    """Raw orchestrator result format for transformation."""
+
+    test_id: str = Field(..., description="Test identifier")
+    task_type: str = Field(..., description="Task type executed")
+    tasks_sent: int = Field(..., description="Tasks enqueued")
+    tasks_completed: int = Field(0, description="Successfully completed")
+    tasks_failed: int = Field(0, description="Failed tasks")
+    total_duration_seconds: float = Field(..., description="Total duration")
+    overall_throughput_per_second: float = Field(0, description="Overall throughput")
+    failure_rate_percent: float = Field(0, description="Failure rate")
+    completion_percentage: float = Field(0, description="Completion rate")
+    average_throughput_per_second: float = Field(0, description="Average throughput")
+    monitor_duration_seconds: float = Field(0, description="Monitor duration")
+    batch_size: int = Field(1, description="Batch size used")
+    delay_ms: int = Field(0, description="Delay between batches")
+    target_queue: str = Field(..., description="Target queue")
+    start_time: str | None = Field(None, description="Start time")
+    end_time: str | None = Field(None, description="End time")
+    task_ids: list[str] = Field(default_factory=list, description="Task IDs")
+
+    def to_load_test_result(self) -> LoadTestResult:
+        """Transform to standard LoadTestResult format."""
+        configuration = LoadTestConfiguration(
+            task_type=LoadTestTypes(self.task_type),
+            num_tasks=self.tasks_sent,
+            batch_size=self.batch_size,
+            delay_ms=self.delay_ms,
+            target_queue=self.target_queue,
+        )
+
+        metrics = LoadTestMetrics(
+            tasks_sent=self.tasks_sent,
+            tasks_completed=self.tasks_completed,
+            tasks_failed=self.tasks_failed,
+            total_duration_seconds=self.total_duration_seconds,
+            overall_throughput=self.overall_throughput_per_second,
+            failure_rate_percent=self.failure_rate_percent,
+            completion_percentage=self.completion_percentage,
+            average_throughput_per_second=self.average_throughput_per_second,
+            monitor_duration_seconds=self.monitor_duration_seconds,
+        )
+
+        return LoadTestResult(
+            status="completed",
+            test_id=self.test_id,
+            configuration=configuration,
+            metrics=metrics,
+            start_time=self.start_time,
+            end_time=self.end_time,
+            task_ids=self.task_ids,
+            error=None,
+            analysis=None,
+        )
+
+
+class LoadTestErrorModel(BaseModel):
+    """Load test error result with partial information."""
+
+    task: str = Field(default="load_test_orchestrator", description="Task name")
+    status: str = Field(
+        ...,
+        pattern=r"^(failed|timed_out)$",
+        description="Error status"
+    )
+    test_id: str = Field(..., description="Unique test identifier")
+    error: str = Field(..., description="Error message")
+    partial_info: str | None = Field(None, description="Partial completion info")
+    tasks_sent: int | None = Field(None, ge=0, description="Tasks that were sent")

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/services/shared/__init__.py

@@ -0,0 +1,15 @@
+"""
+Shared domain models and utilities.
+
+Common types and models used across multiple domains.
+"""
+
+from .models import (
+    BaseResponse,
+    ErrorResponse,
+)
+
+__all__ = [
+    "BaseResponse",
+    "ErrorResponse",
+]

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/services/shared/models.py

@@ -0,0 +1,26 @@
+"""
+Shared domain models.
+
+Common Pydantic models used across multiple domains and services.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class BaseResponse(BaseModel):
+    """Base API response model."""
+
+    success: bool = Field(..., description="Whether operation was successful")
+    message: str = Field(..., description="Response message")
+    data: dict[str, Any] | list[Any] | None = Field(None, description="Response data")
+
+
+class ErrorResponse(BaseModel):
+    """Standard error response model."""
+
+    error: str = Field(..., description="Error message")
+    status: str = Field(default="error", description="Status indicator")
+    details: dict[str, Any] | None = Field(None, description="Additional error details")
+    timestamp: str | None = Field(None, description="ISO timestamp when error occurred")

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/services/system/__init__.py

@@ -0,0 +1,52 @@
+"""
+System domain - health monitoring, alerts, and system management.
+
+This domain provides functions for:
+- System health checking and monitoring
+- Component status validation
+- Alert management and notifications
+- System resource monitoring
+
+All functions use Pydantic models for type safety and validation.
+"""
+
+from .alerts import (
+    send_alert,
+    send_critical_alert,
+    send_health_alert,
+)
+from .health import (
+    check_system_status,
+    get_system_status,
+    is_system_healthy,
+    register_health_check,
+)
+from .models import (
+    Alert,
+    AlertSeverity,
+    ComponentStatus,
+    ComponentStatusType,
+    DetailedHealthResponse,
+    HealthResponse,
+    SystemStatus,
+)
+
+__all__ = [
+    # Health functions
+    "check_system_status",
+    "get_system_status",
+    "is_system_healthy",
+    "register_health_check",
+    # Alert functions
+    "send_alert",
+    "send_critical_alert",
+    "send_health_alert",
+    # Models
+    "Alert",
+    "AlertSeverity",
+    "ComponentStatus",
+    "ComponentStatusType",
+    "SystemStatus",
+    "HealthResponse",
+    "DetailedHealthResponse",
+]

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/services/system/alerts.py

@@ -0,0 +1,94 @@
+"""
+System alert management functions.
+
+Pure functions for sending alerts, managing notifications, and rate limiting.
+All functions use Pydantic models for type safety and validation.
+"""
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from app.core.log import logger
+
+from .models import Alert, SystemStatus, alert_severity
+
+if TYPE_CHECKING:
+    pass
+
+
+# Global state for alert rate limiting
+_last_alerts: dict[str, datetime] = {}
+_rate_limit_seconds = 300  # 5 minutes between similar alerts
+
+
+def _should_send_alert(alert_key: str) -> bool:
+    """Check if we should send this alert based on rate limiting."""
+    if alert_key not in _last_alerts:
+        return True
+
+    time_since_last = datetime.utcnow() - _last_alerts[alert_key]
+    return time_since_last.total_seconds() > _rate_limit_seconds
+
+
+async def send_alert(alert: Alert) -> None:
+    """Send an alert through configured channels."""
+    alert_key = f"{alert.severity}:{alert.title}"
+
+    if not _should_send_alert(alert_key):
+        logger.debug(f"Rate limiting alert: {alert_key}")
+        return
+
+    _last_alerts[alert_key] = datetime.utcnow()
+
+    # Log-based alerting (always available)
+    log_level = {
+        alert_severity.INFO: logger.info,
+        alert_severity.WARNING: logger.warning,
+        alert_severity.ERROR: logger.error,
+        alert_severity.CRITICAL: logger.critical,
+    }.get(alert.severity, logger.info)
+
+    log_level(
+        f"🚨 ALERT [{alert.severity.upper()}]: {alert.title}",
+        extra={
+            "alert_message": alert.message,
+            "alert_metadata": alert.metadata,
+            "alert_timestamp": alert.timestamp.isoformat(),
+        },
+    )
+
+    # TODO: Add integrations for:
+    # - Slack/Discord webhooks
+    # - Email notifications
+    # - PagerDuty/Opsgenie
+    # - Custom webhook endpoints
+
+
+async def send_health_alert(status: SystemStatus) -> None:
+    """Send health-related alerts."""
+    if not status.overall_healthy:
+        alert = Alert(
+            severity=alert_severity.WARNING,
+            title="System Health Issues Detected",
+            message=(
+                f"{len(status.unhealthy_components)} components unhealthy: "
+                f"{', '.join(status.unhealthy_components)}"
+            ),
+            timestamp=status.timestamp,
+            metadata={
+                "unhealthy_components": status.unhealthy_components,
+                "health_percentage": status.health_percentage,
+            },
+        )
+        await send_alert(alert)
+
+
+async def send_critical_alert(title: str, message: str) -> None:
+    """Send a critical system alert."""
+    alert = Alert(
+        severity=alert_severity.CRITICAL,
+        title=title,
+        message=message,
+        timestamp=datetime.utcnow(),
+    )
+    await send_alert(alert)