aegis-stack 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,169 @@
+"""
+System domain Pydantic models.
+
+Type-safe data models for system health monitoring, alerts, and status reporting.
+All models provide runtime validation and automatic FastAPI integration.
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field, computed_field
+
+
+class ComponentStatusType(str, Enum):
+    """Component status levels."""
+    HEALTHY = "healthy"
+    INFO = "info" 
+    WARNING = "warning"
+    UNHEALTHY = "unhealthy"
+
+
+class ComponentStatus(BaseModel):
+    """Status of a single system component."""
+
+    name: str = Field(..., description="Component name")
+    status: ComponentStatusType = Field(
+        default=ComponentStatusType.HEALTHY, 
+        description="Detailed status level (healthy/info/warning/unhealthy)"
+    )
+    message: str = Field(..., description="Status message or error description")
+    response_time_ms: float | None = Field(
+        None, description="Response time in milliseconds"
+    )
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Additional component metadata"
+    )
+    sub_components: dict[str, "ComponentStatus"] = Field(
+        default_factory=dict, 
+        description="Sub-components (e.g., system metrics under backend)"
+    )
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def healthy(self) -> bool:
+        """
+        Component is healthy if status is not UNHEALTHY.
+
+        WARNING and INFO statuses are considered healthy (functional but with concerns),
+        only UNHEALTHY is considered not healthy (non-functional).
+        """
+        return self.status != ComponentStatusType.UNHEALTHY
+
+
+class SystemStatus(BaseModel):
+    """Overall system status with component details."""
+
+    components: dict[str, ComponentStatus] = Field(
+        ..., description="Component status by name"
+    )
+    overall_healthy: bool = Field(..., description="Whether all components are healthy")
+    timestamp: datetime = Field(..., description="When status was generated")
+    system_info: dict[str, Any] = Field(
+        default_factory=dict, description="System information"
+    )
+
+    def _get_all_components_flat(self) -> list[tuple[str, ComponentStatus]]:
+        """Get all components including sub-components as a flat list."""
+        all_components = []
+        for name, component in self.components.items():
+            all_components.append((name, component))
+            # Add sub-components with parent.child naming
+            for sub_name, sub_component in component.sub_components.items():
+                all_components.append((f"{name}.{sub_name}", sub_component))
+        return all_components
+
+    @property
+    def healthy_components(self) -> list[str]:
+        """List of healthy component names (including sub-components)."""
+        return [
+            name for name, component in self._get_all_components_flat() 
+            if component.healthy
+        ]
+
+    @property
+    def unhealthy_components(self) -> list[str]:
+        """List of unhealthy component names (including sub-components)."""
+        return [
+            name for name, component in self._get_all_components_flat() 
+            if not component.healthy
+        ]
+
+    @property
+    def health_percentage(self) -> float:
+        """Percentage of healthy components (including sub-components)."""
+        all_components = self._get_all_components_flat()
+        if not all_components:
+            return 100.0
+        healthy_count = len([c for _, c in all_components if c.healthy])
+        return (healthy_count / len(all_components)) * 100
+
+    @property
+    def total_components(self) -> int:
+        """Total number of top-level components."""
+        return len(self.components)
+
+    @property
+    def healthy_top_level_components(self) -> list[str]:
+        """List of healthy top-level component names."""
+        return [name for name, comp in self.components.items() if comp.healthy]
+
+
+class HealthResponse(BaseModel):
+    """Basic health check API response."""
+
+    healthy: bool = Field(..., description="Whether system is healthy")
+    status: str = Field(..., description="Overall status text")
+    components: dict[str, ComponentStatus] = Field(
+        default_factory=dict, description="Component statuses"
+    )
+    timestamp: str = Field(..., description="ISO timestamp when checked")
+
+
+class DetailedHealthResponse(BaseModel):
+    """Detailed health check API response with system information."""
+
+    healthy: bool = Field(..., description="Whether system is healthy")
+    status: str = Field(..., description="Overall status text")
+    service: str = Field(..., description="Service name")
+    version: str = Field(..., description="Service version")
+    components: dict[str, ComponentStatus] = Field(
+        ..., description="Component statuses"
+    )
+    system_info: dict[str, Any] = Field(..., description="System information")
+    timestamp: str = Field(..., description="ISO timestamp when checked")
+    healthy_components: list[str] = Field(
+        ..., description="List of healthy component names"
+    )
+    unhealthy_components: list[str] = Field(
+        ..., description="List of unhealthy component names"
+    )
+    health_percentage: float = Field(
+        ..., description="Percentage of healthy components"
+    )
+
+
+class AlertSeverity(BaseModel):
+    """Alert severity levels as constants."""
+
+    INFO: str = Field(default="info", description="Informational alert")
+    WARNING: str = Field(default="warning", description="Warning alert")
+    ERROR: str = Field(default="error", description="Error alert")
+    CRITICAL: str = Field(default="critical", description="Critical alert")
+
+
+class Alert(BaseModel):
+    """System alert model."""
+
+    severity: str = Field(..., description="Alert severity level")
+    title: str = Field(..., min_length=1, description="Alert title")
+    message: str = Field(..., min_length=1, description="Alert message")
+    timestamp: datetime = Field(..., description="When alert was created")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Additional alert data"
+    )
+
+
+# Singleton for alert severity constants
+alert_severity = AlertSeverity()

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

@@ -0,0 +1,52 @@
+"""
+Shared UI helpers for status presentation across CLI and frontend.
+
+Provides a single source of truth for mapping ComponentStatusType to
+icons and semantic colors, so CLI and dashboard remain consistent.
+"""
+
+from .models import ComponentStatusType
+
+
+def get_status_icon(status: ComponentStatusType) -> str:
+    """Return the display icon for a given status.
+
+    Note: INFO icon intentionally includes a trailing space for terminal alignment.
+    """
+    if status == ComponentStatusType.HEALTHY:
+        return "✅"
+    if status == ComponentStatusType.INFO:
+        return "ℹ️ "
+    if status == ComponentStatusType.WARNING:
+        return "⚠️"
+    if status == ComponentStatusType.UNHEALTHY:
+        return "❌"
+    return "❓"
+
+
+def get_status_color_name(status: ComponentStatusType) -> str:
+    """Return a semantic color name for a given status (CLI friendly).
+
+    Frontend can adapt these semantic names to theme-specific colors.
+    """
+    if status == ComponentStatusType.HEALTHY:
+        return "green"
+    if status == ComponentStatusType.INFO:
+        return "blue"
+    if status == ComponentStatusType.WARNING:
+        return "yellow"
+    if status == ComponentStatusType.UNHEALTHY:
+        return "red"
+    return "white"
+
+
+def get_component_label(component_name: str) -> str:
+    """Map component keys to user-facing labels (brand or friendly name)."""
+    mapping = {
+        "backend": "FastAPI",
+        "frontend": "Flet",
+        "cache": "Redis",
+        "worker": "arq",
+        "scheduler": "APScheduler",
+    }
+    return mapping.get(component_name, component_name.title())

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/docker-compose.yml.j2

@@ -0,0 +1,195 @@
+
+x-app: &app
+  image: ${AEGIS_STACK_TAG:-aegis-stack:latest}
+  build:
+    context: .
+    args:
+      - AEGIS_STACK_VERSION=${AEGIS_STACK_VERSION:-dev}
+      - PORT=${PORT:-8000}
+  env_file:
+    - ${AEGIS_STACK_ENV_FILE:-.env}
+  volumes:
+    - .:/code
+    # Exclude .venv to prevent host/container virtual environment conflicts
+    - /code/.venv
+  environment:
+    # Docker container marker for entrypoint script
+    - DOCKER_CONTAINER=1
+    - PORT=${PORT:-8000}
+  labels:
+    logging: "aegis-stack"
+
+services:
+  # DEVELOPMENT PROFILE
+
+  webserver:
+    <<: *app
+    command:
+      - webserver
+    ports:
+      - "${PORT:-8000}:${PORT:-8000}"
+{%- if cookiecutter.include_redis == "yes" %}
+    depends_on:
+      redis:
+        condition: service_healthy
+    environment:
+      # Redis connection for health checks and task enqueueing
+      - REDIS_URL=${REDIS_URL:-redis://redis:6379}
+{%- endif %}
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:${PORT:-8000}/health/"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+    restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: '0.5'
+        reservations:
+          memory: 256M
+          cpus: '0.25'
+    profiles:
+      - dev
+
+
+{%- if cookiecutter.include_scheduler == "yes" %}
+  # Scheduler service (runs scheduler tasks independently)
+  scheduler:
+    <<: *app
+    command:
+      - scheduler
+{%- if cookiecutter.include_redis == "yes" %}
+    depends_on:
+      redis:
+        condition: service_healthy
+    environment:
+      # Redis connection for future scheduler integration
+      - REDIS_URL=${REDIS_URL:-redis://redis:6379}
+{%- endif %}
+    restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 256M
+          cpus: '0.25'
+        reservations:
+          memory: 128M
+          cpus: '0.1'
+    profiles:
+      - dev
+      - prod
+{%- endif %}
+
+{%- if cookiecutter.include_worker == "yes" %}
+  # Load Test Worker (high-performance load testing tasks)
+  worker-load-test:
+    <<: *app
+    command:
+      - worker
+      - load_test
+    depends_on:
+      redis:
+        condition: service_healthy
+    restart: unless-stopped
+    tty: true
+    environment:
+      # Load test worker configuration (high concurrency)
+      - WORKER_QUEUE_TYPE=load_test
+      - WORKER_CONCURRENCY=${LOAD_TEST_WORKER_CONCURRENCY:-20}
+      - WORKER_TIMEOUT_SECONDS=${LOAD_TEST_WORKER_TIMEOUT:-60}
+      - WORKER_MAX_TRIES=${LOAD_TEST_WORKER_MAX_TRIES:-1}
+      - REDIS_URL=${REDIS_URL:-redis://redis:6379}
+      # Docker file watching fix - force polling for volume mounts
+      - WATCHFILES_FORCE_POLLING=true
+      - WATCHFILES_POLL_DELAY_MS=800
+    deploy:
+      resources:
+        limits:
+          memory: 1G
+          cpus: '1.0'
+        reservations:
+          memory: 512M
+          cpus: '0.5'
+    profiles:
+      - dev
+      - prod
+
+
+  # System Worker (maintenance and administrative tasks)
+  worker-system:
+    <<: *app
+    command:
+      - worker
+      - system
+    depends_on:
+      redis:
+        condition: service_healthy
+    restart: unless-stopped
+    tty: true
+    environment:
+      # System worker configuration (low concurrency, high reliability)
+      - WORKER_QUEUE_TYPE=system
+      - WORKER_CONCURRENCY=${SYSTEM_WORKER_CONCURRENCY:-2}
+      - WORKER_TIMEOUT_SECONDS=${SYSTEM_WORKER_TIMEOUT:-1800}
+      - WORKER_MAX_TRIES=${SYSTEM_WORKER_MAX_TRIES:-5}
+      - REDIS_URL=${REDIS_URL:-redis://redis:6379}
+      # Docker file watching fix - force polling for volume mounts
+      - WATCHFILES_FORCE_POLLING=true
+      - WATCHFILES_POLL_DELAY_MS=800
+    deploy:
+      resources:
+        limits:
+          memory: 256M
+          cpus: '0.25'
+        reservations:
+          memory: 128M
+          cpus: '0.1'
+    profiles:
+      - dev
+      - prod
+{%- endif %}
+
+
+{%- if cookiecutter.include_redis == "yes" %}
+  # REDIS SERVICE
+  
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    command: redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+    restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: '0.25'
+        reservations:
+          memory: 256M
+          cpus: '0.1'
+    profiles:
+      - dev
+{%- endif %}
+
+  # TEST PROFILE
+
+  test_runner:
+    <<: *app
+    command:
+      - test
+    env_file:
+      - ${AEGIS_STACK_ENV_FILE:-.env}
+    profiles:
+      - test
+
+volumes:
+  aegis-data:

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/docs/api.md

@@ -0,0 +1,191 @@
+# API Reference
+
+{{ cookiecutter.project_name }} provides a FastAPI-based REST API with automatic documentation.
+
+## Interactive Documentation
+
+When running the application, interactive API documentation is available at:
+
+- **Swagger UI**: [http://localhost:8000/docs](http://localhost:8000/docs)
+- **ReDoc**: [http://localhost:8000/redoc](http://localhost:8000/redoc)
+- **OpenAPI Schema**: [http://localhost:8000/openapi.json](http://localhost:8000/openapi.json)
+
+## Health Endpoints
+
+### Basic Health Check
+
+**GET** `/health/`
+
+Returns basic health status of the application.
+
+```bash
+curl http://localhost:8000/health/
+```
+
+**Response:**
+```json
+{
+  "healthy": true,
+  "status": "healthy",
+  "components": {},
+  "timestamp": "2024-01-01T00:00:00Z"
+}
+```
+
+### Detailed Health Check
+
+**GET** `/health/detailed`
+
+Returns comprehensive health information including system metrics.
+
+```bash
+curl http://localhost:8000/health/detailed
+```
+
+**Response:**
+```json
+{
+  "healthy": true,
+  "status": "healthy", 
+  "components": {
+    "system": {
+      "status": "healthy",
+      "cpu_percent": 15.2,
+      "memory_percent": 45.8,
+      "disk_percent": 32.1,
+      "response_time_ms": 2.1
+    }{% if cookiecutter.include_scheduler == "yes" %},
+    "scheduler": {
+      "status": "healthy",
+      "active_jobs": 2,
+      "next_run": "2024-01-01T02:00:00Z",
+      "response_time_ms": 1.5
+    }{% endif %}
+  },
+  "timestamp": "2024-01-01T00:00:00Z",
+  "uptime_seconds": 3600
+}
+```
+
+## Authentication
+
+Currently, {{ cookiecutter.project_name }} does not implement authentication. 
+
+To add authentication:
+
+1. **Install dependencies:**
+   ```bash
+   uv add python-jose[cryptography] passlib[bcrypt]
+   ```
+
+2. **Add authentication routes:**
+   ```python
+   # app/components/backend/api/auth.py
+   from fastapi import APIRouter, Depends, HTTPException, status
+   from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
+   
+   router = APIRouter()
+   oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
+   
+   @router.post("/token")
+   async def login(form_data: OAuth2PasswordRequestForm = Depends()):
+       # Implement login logic
+       pass
+   ```
+
+3. **Register in routing:**
+   ```python
+   # app/components/backend/api/routing.py
+   from app.components.backend.api import auth
+   
+   def include_routers(app: FastAPI) -> None:
+       app.include_router(auth.router, prefix="/auth", tags=["authentication"])
+   ```
+
+## CORS Configuration
+
+CORS is pre-configured to allow all origins in development. For production, update the CORS middleware in `app/components/backend/middleware/cors.py`:
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["https://yourdomain.com"],  # Update for production
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+## Error Handling
+
+The API includes standard HTTP error responses:
+
+- **400 Bad Request**: Invalid request data
+- **404 Not Found**: Resource not found  
+- **422 Unprocessable Entity**: Validation errors
+- **500 Internal Server Error**: Server errors
+
+Custom error handlers can be added in `app/components/backend/main.py`:
+
+```python
+from fastapi import HTTPException, Request
+from fastapi.responses import JSONResponse
+
+@app.exception_handler(404)
+async def not_found_handler(request: Request, exc: HTTPException):
+    return JSONResponse(
+        status_code=404,
+        content={"message": "Resource not found"}
+    )
+```
+
+## Adding Custom Endpoints
+
+### 1. Create Router Module
+
+```python
+# app/components/backend/api/my_api.py
+from fastapi import APIRouter, HTTPException
+from app.services.my_service import get_data, create_item
+
+router = APIRouter()
+
+@router.get("/items")
+async def list_items():
+    """Get all items."""
+    items = await get_data()
+    return {"items": items}
+
+@router.post("/items")
+async def create_item_endpoint(name: str):
+    """Create a new item."""
+    try:
+        item = await create_item(name)
+        return {"item": item}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+```
+
+### 2. Register Router
+
+```python
+# app/components/backend/api/routing.py
+from app.components.backend.api import my_api
+
+def include_routers(app: FastAPI) -> None:
+    app.include_router(my_api.router, prefix="/api", tags=["items"])
+```
+
+### 3. Add Tests
+
+```python
+# tests/api/test_my_api.py
+def test_list_items(client):
+    response = client.get("/api/items")
+    assert response.status_code == 200
+    assert "items" in response.json()
+```
+
+The API will automatically include your endpoints in the interactive documentation at `/docs`.