aegis-stack 0.1.0__py3-none-any.whl

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/components/backend/api/health.py

@@ -0,0 +1,134 @@
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from starlette import status
+
+from app.services.system import (
+    DetailedHealthResponse,
+    HealthResponse,
+    get_system_status,
+)
+
+router = APIRouter()
+
+
+@router.get("/", response_model=HealthResponse)
+async def health_check() -> HealthResponse:
+    """
+    Quick health check endpoint.
+
+    Returns basic healthy/unhealthy status for load balancers and monitoring.
+    """
+    try:
+        system_status = await get_system_status()
+        return HealthResponse(
+            healthy=system_status.overall_healthy,
+            status="healthy" if system_status.overall_healthy else "unhealthy",
+            components=system_status.components,
+            timestamp=system_status.timestamp.isoformat(),
+        )
+    except Exception:
+        # If health checks fail completely, consider unhealthy
+        return HealthResponse(
+            healthy=False,
+            status="unhealthy",
+            components={},
+            timestamp="",
+        )
+
+
+@router.get("/detailed", response_model=DetailedHealthResponse)
+async def detailed_health() -> DetailedHealthResponse:
+    """
+    Detailed health check with component information.
+
+    Returns comprehensive system status including individual component health,
+    system metrics, and diagnostic information.
+    """
+    try:
+        system_status = await get_system_status()
+
+        # Always return 200 OK - service is available even if components are unhealthy
+        return DetailedHealthResponse(
+            healthy=system_status.overall_healthy,
+            status="healthy" if system_status.overall_healthy else "unhealthy",
+            service="{{ cookiecutter.project_name }}",
+            version="0.1.0",
+            components=system_status.components,
+            system_info=system_status.system_info,
+            timestamp=system_status.timestamp.isoformat(),
+            healthy_components=system_status.healthy_components,
+            unhealthy_components=system_status.unhealthy_components,
+            health_percentage=system_status.health_percentage,
+        )
+
+    except HTTPException:
+        # Re-raise HTTP exceptions from unexpected errors
+        raise
+    except Exception as e:
+        # Handle unexpected errors
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail={
+                "message": "Health check failed",
+                "error": str(e),
+                "status": "unhealthy",
+            },
+        )
+
+
+@router.get("/dashboard")
+async def system_dashboard() -> dict[str, Any]:
+    """
+    System dashboard endpoint optimized for frontend consumption.
+
+    Returns system status with additional dashboard metadata like
+    alert counts, trend data, and formatted display information.
+    """
+    try:
+        system_status = await get_system_status()
+
+        # TODO: Implement alert tracking when alert management is enhanced
+        recent_alerts = 0
+
+        return {
+            "status": "healthy" if system_status.overall_healthy else "unhealthy",
+            "service": "{{ cookiecutter.project_name }}",
+            "version": "0.1.0",
+            "dashboard_data": {
+                "overall_status": {
+                    "healthy": system_status.overall_healthy,
+                    "percentage": system_status.health_percentage,
+                    "status_text": (
+                        "System Healthy"
+                        if system_status.overall_healthy
+                        else "Issues Detected"
+                    ),
+                },
+                "components": {
+                    name: {
+                        "name": name,
+                        "healthy": component.healthy,
+                        "message": component.message,
+                        "response_time_ms": component.response_time_ms,
+                        "metadata": component.metadata,
+                    }
+                    for name, component in system_status.components.items()
+                },
+                "summary": {
+                    "total_components": len(system_status.components),
+                    "healthy_components": len(system_status.healthy_components),
+                    "unhealthy_components": len(system_status.unhealthy_components),
+                    "recent_alerts": recent_alerts,
+                },
+                "system_info": system_status.system_info,
+                "timestamp": system_status.timestamp.isoformat(),
+                "last_updated": system_status.timestamp.strftime("%H:%M:%S"),
+            },
+        }
+
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail={"message": "Dashboard data unavailable", "error": str(e)},
+        )

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/components/backend/api/models.py.j2

@@ -0,0 +1,247 @@
+{%- if cookiecutter.include_worker == "yes" %}
+"""
+API models for background tasks and responses.
+
+This module contains all Pydantic models used by the API layer for
+task management, status tracking, and response formatting.
+"""
+
+from datetime import datetime
+from typing import Dict, Any, Optional
+
+from pydantic import BaseModel, Field
+
+from app.components.worker.constants import LoadTestTypes
+
+
+class TaskRequest(BaseModel):
+    """Request model for enqueueing a background task."""
+
+    task_name: str = Field(..., description="Name of the task function to execute")
+    queue_type: str = Field(
+        "system", description="Functional queue type: media or system"
+    )
+    args: list[Any] = Field(
+        default_factory=list, description="Positional arguments for the task"
+    )
+    kwargs: Dict[str, Any] = Field(
+        default_factory=dict, description="Keyword arguments for the task"
+    )
+    delay_seconds: Optional[int] = Field(
+        None, description="Delay task execution by this many seconds"
+    )
+
+
+class TaskResponse(BaseModel):
+    """Response model for task enqueue operations."""
+
+    task_id: str
+    task_name: str
+    queue_type: str
+    queued_at: datetime
+    estimated_start: Optional[datetime] = None
+    message: str
+
+
+class TaskListResponse(BaseModel):
+    """Response model for listing available tasks."""
+
+    available_tasks: list[str]
+    total_count: int
+    queues: Dict[str, list[str]]
+
+
+class TaskStatusResponse(BaseModel):
+    """Response model for task status checks."""
+    
+    task_id: str
+    status: str = Field(
+        ...,
+        description="Task status: queued, in_progress, complete, failed, unknown",
+    )
+    enqueue_time: Optional[datetime] = Field(
+        None, description="When the task was enqueued"
+    )
+    start_time: Optional[datetime] = Field(
+        None, description="When the task started processing"
+    )
+    finish_time: Optional[datetime] = Field(None, description="When the task completed")
+    result_available: bool = Field(
+        False, description="Whether task result is available"
+    )
+    error: Optional[str] = Field(None, description="Error message if task failed")
+
+
+class TaskResultResponse(BaseModel):
+    """Response model for completed task results."""
+    
+    task_id: str
+    status: str = Field(..., description="Task completion status")
+    result: Any = Field(..., description="The actual task result data")
+    enqueue_time: Optional[datetime] = Field(
+        None, description="When the task was enqueued"
+    )
+    start_time: Optional[datetime] = Field(
+        None, description="When the task started processing"
+    )
+    finish_time: Optional[datetime] = Field(None, description="When the task completed")
+
+
+class LoadTestRequest(BaseModel):
+    """Request model for orchestrating load tests that measure queue throughput."""
+    
+    num_tasks: int = Field(
+        100, 
+        description="Number of tasks to spawn for the load test",
+        ge=10,
+        le=10000
+    )
+    task_type: LoadTestTypes = Field(
+        LoadTestTypes.CPU_INTENSIVE,
+        description="Type of worker task to spawn for load testing",
+    )
+    batch_size: int = Field(
+        10, 
+        description="How many tasks to send concurrently per batch",
+        ge=1,
+        le=100
+    )
+    delay_ms: int = Field(
+        0, 
+        description="Delay between batches in milliseconds",
+        ge=0,
+        le=5000
+    )
+    target_queue: str = Field(
+        "load_test", 
+        description="Which queue to test (system, media, or load_test)",
+        pattern="^(system|media|load_test)$"
+    )
+
+    class Config:
+        schema_extra = {
+            "examples": [
+                {
+                    "description": (
+                        "Quick CPU load test - fibonacci calculations and operations"
+                    ),
+                    "num_tasks": 50,
+                    "task_type": "cpu_intensive", 
+                    "batch_size": 10,
+                    "delay_ms": 0,
+                    "target_queue": "system",
+                    "expected_work": (
+                        "Computational: fibonacci, prime checking, math operations"
+                    ),
+                    "expected_metrics": [
+                        "fibonacci_result",
+                        "math_operations_sum",
+                        "operations_per_ms",
+                    ]
+                },
+                {
+                    "description": (
+                        "I/O stress test - async operations and concurrent handling"
+                    ),
+                    "num_tasks": 200,
+                    "task_type": "io_simulation",
+                    "batch_size": 20,
+                    "delay_ms": 50,
+                    "target_queue": "system",
+                    "expected_work": (
+                        "Async I/O: network delays, concurrent operations, files"
+                    ),
+                    "expected_metrics": [
+                        "concurrent_operations",
+                        "io_efficiency_percent",
+                        "concurrency_benefit",
+                    ]
+                },
+                {
+                    "description": (
+                        "Memory allocation test - data structures and GC pressure"
+                    ),
+                    "num_tasks": 500,
+                    "task_type": "memory_operations",
+                    "batch_size": 25,
+                    "delay_ms": 0,
+                    "target_queue": "media",
+                    "expected_work": (
+                        "Memory: allocation patterns, data manipulation, cleanup"
+                    ),
+                    "expected_metrics": [
+                        "estimated_peak_memory_mb",
+                        "memory_throughput_mb_per_sec",
+                        "memory_operations_count",
+                    ]
+                },
+                {
+                    "description": (
+                        "Failure resilience test - ~20% random failures for errors"
+                    ),
+                    "num_tasks": 100,
+                    "task_type": "test_task_failure",
+                    "batch_size": 15,
+                    "delay_ms": 0,
+                    "target_queue": "system",
+                    "expected_work": (
+                        "Failure testing: random errors, recovery patterns, resilience"
+                    ),
+                    "expected_metrics": [
+                        "failure_roll",
+                        "failure_threshold",
+                        "would_have_failed",
+                    ]
+                }
+            ]
+        }
+
+
+class LoadTestStatus(BaseModel):
+    """Status model for monitoring active load tests."""
+    
+    test_id: str = Field(..., description="Unique load test identifier")
+    status: str = Field(..., description="Test status: running, completed, failed")
+    tasks_sent: int = Field(..., description="Number of tasks sent to queue")
+    tasks_completed: int = Field(..., description="Number of tasks completed")
+    tasks_failed: int = Field(0, description="Number of tasks that failed") 
+    elapsed_seconds: float = Field(..., description="Time elapsed since test start")
+    current_throughput: float = Field(..., description="Current tasks per second")
+    estimated_completion: Optional[datetime] = Field(
+        None, description="Estimated completion time"
+    )
+    queue_depth: int = Field(0, description="Current queue depth")
+
+
+class LoadTestResults(BaseModel):
+    """Final results model for completed load tests."""
+    
+    test_id: str = Field(..., description="Unique load test identifier")
+    status: str = Field(..., description="Final test status")
+    configuration: LoadTestRequest = Field(..., description="Test configuration used")
+    
+    # Task metrics
+    tasks_sent: int = Field(..., description="Total tasks sent")
+    tasks_completed: int = Field(..., description="Total tasks completed")
+    tasks_failed: int = Field(..., description="Total tasks failed")
+    
+    # Timing metrics
+    start_time: datetime = Field(..., description="Test start time")
+    end_time: Optional[datetime] = Field(None, description="Test end time")
+    total_duration_seconds: float = Field(..., description="Total test duration")
+    
+    # Performance metrics
+    overall_throughput: float = Field(..., description="Overall tasks per second")
+    peak_throughput: float = Field(..., description="Peak throughput achieved")
+    failure_rate: float = Field(..., description="Percentage of tasks that failed")
+    
+    # Queue metrics
+    final_queue_metrics: Dict[str, Any] = Field(
+        ..., description="Final arq queue health data"
+    )
+    
+    # Summary
+    performance_summary: str = Field(
+        ..., description="Human readable performance summary"
+    )
+{%- endif %}

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/components/backend/api/routing.py.j2

@@ -0,0 +1,14 @@
+from fastapi import FastAPI
+
+from app.components.backend.api import health
+{%- if cookiecutter.include_worker == "yes" %}
+from app.components.backend.api import tasks
+{%- endif %}
+
+
+def include_routers(app: FastAPI) -> None:
+    """Include all API routers in the FastAPI app"""
+    app.include_router(health.router, prefix="/health", tags=["health"])
+    {%- if cookiecutter.include_worker == "yes" %}
+    app.include_router(tasks.router, prefix="/api/v1", tags=["tasks"])
+    {%- endif %}