aegis-stack 0.2.0rc2__py3-none-any.whl

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

@@ -0,0 +1,243 @@
+"""
+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.extend(self._flatten_component(name, component))
+
+        return all_components
+
+    def _flatten_component(
+        self, name: str, component: ComponentStatus
+    ) -> list[tuple[str, ComponentStatus]]:
+        """Recursively flatten a component and its sub-components into a list."""
+        result = [(name, component)]
+        # Recursively add sub-components with parent.child naming
+        for sub_name, sub_component in component.sub_components.items():
+            result.extend(self._flatten_component(f"{name}.{sub_name}", sub_component))
+        return result
+
+    @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]
+
+    @property
+    def services_status(self) -> ComponentStatus | None:
+        """Get the services component status if it exists."""
+        if "aegis" in self.components:
+            aegis_component = self.components["aegis"]
+            if (
+                hasattr(aegis_component, "sub_components")
+                and aegis_component.sub_components
+            ):
+                return aegis_component.sub_components.get("services")
+        return None
+
+    @property
+    def has_services(self) -> bool:
+        """Check if any services are registered in the system."""
+        return self.services_status is not None
+
+    @property
+    def service_names(self) -> list[str]:
+        """Get list of registered service names."""
+        services_component = self.services_status
+        if services_component and hasattr(services_component, "sub_components"):
+            return list(services_component.sub_components.keys())
+        return []
+
+    @property
+    def healthy_services(self) -> list[str]:
+        """List of healthy service names."""
+        services_component = self.services_status
+        if services_component and hasattr(services_component, "sub_components"):
+            return [
+                name
+                for name, service in services_component.sub_components.items()
+                if service.healthy
+            ]
+        return []
+
+    @property
+    def unhealthy_services(self) -> list[str]:
+        """List of unhealthy service names."""
+        services_component = self.services_status
+        if services_component and hasattr(services_component, "sub_components"):
+            return [
+                name
+                for name, service in services_component.sub_components.items()
+                if not service.healthy
+            ]
+        return []
+
+
+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"
+    )
+    # Service-specific fields (optional)
+    has_services: bool = Field(
+        default=False, description="Whether any services are registered"
+    )
+    service_names: list[str] = Field(
+        default_factory=list, description="List of registered service names"
+    )
+    healthy_services: list[str] = Field(
+        default_factory=list, description="List of healthy service names"
+    )
+    unhealthy_services: list[str] = Field(
+        default_factory=list, description="List of unhealthy service names"
+    )
+
+
+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/copier-aegis-project/{{ 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/copier-aegis-project/{{ project_slug }}/clean-validation/.env.example.jinja

@@ -0,0 +1,64 @@
+# Aegis Stack Environment Variables Example
+# Copy this file to .env and customize for your environment
+
+# =============================================================================
+# APPLICATION SETTINGS
+# =============================================================================
+
+# Environment: dev, qa, stg, prod
+APP_ENV=dev
+
+# Port to run the webserver on
+PORT=8000
+
+# Logging level: DEBUG, INFO, WARNING, ERROR
+LOG_LEVEL=INFO
+
+# Auto-reload server on code changes (development only)
+AUTO_RELOAD=true
+
+# =============================================================================
+# DOCKER SETTINGS
+# =============================================================================
+
+# Docker image tag (used by docker-compose)
+AEGIS_STACK_TAG=aegis-stack:latest
+
+# Version tag for builds
+AEGIS_STACK_VERSION=dev
+
+# Environment file to use (defaults to .env)
+# AEGIS_STACK_ENV_FILE=.env
+
+# =============================================================================
+# COMPONENT SETTINGS
+# =============================================================================
+
+
+# Database settings
+# DATABASE_URL=sqlite:///./data/app.db  # SQLite database (default)
+# DATABASE_ENGINE_ECHO=false  # Set to true to log all SQL queries (debugging)
+
+
+
+
+
+# Scheduler settings
+# SCHEDULER_TIMEZONE=UTC
+# SCHEDULER_MAX_WORKERS=10
+
+
+# API Keys and Secrets (add as needed)
+# SECRET_KEY=your-super-secret-key-here
+# API_KEY=your-api-key-here
+
+# =============================================================================
+# DEVELOPMENT OVERRIDES
+# =============================================================================
+
+# Worker auto-reload settings
+# WORKER_WATCH=false  # Disable worker auto-reload (useful for debugging)
+
+# Override for local development
+# Use this to point to local services instead of Docker services
+# DATABASE_HOST=host.docker.internal  # For connecting to host DB from container

aegis/templates/copier-aegis-project/{{ project_slug }}/clean-validation/README.md.jinja

@@ -0,0 +1,172 @@
+# clean-validation 🛡️
+
+A production-ready async Python application built with Aegis Stack
+
+## Components
+
+This Aegis Stack project includes the following components:
+
+- **✅ Backend**: FastAPI-based async web server
+- **✅ Frontend**: Flet-based Python UI framework
+- **✅ Scheduler**: APScheduler-based async task scheduling
+- **✅ Database**: SQLite database with SQLModel ORM
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+### Installation
+
+1. **Install dependencies:**
+   ```bash
+   uv sync                    # Core dependencies only
+   # Or for development: uv sync --all-extras  (includes testing, linting, docs)
+   ```
+
+2. **Activate virtual environment:**
+   ```bash
+   source .venv/bin/activate
+   ```
+
+3. **Set up environment:**
+   ```bash
+   cp .env.example .env
+   # Edit .env with your configuration
+   ```
+
+4. **Set up database:**
+   ```bash
+   # Create data directory for SQLite database
+   mkdir -p data
+
+   # Database will be created automatically on first run
+   # Default location: data/app.db
+   ```
+
+5. **Run the application:**
+   ```bash
+   make server
+   ```
+
+The application will be available at `http://127.0.0.1:8000`.
+
+## Development
+
+### Running Tests
+```bash
+make test
+```
+
+### Code Quality
+```bash
+make check  # Run linting, type checking, and tests
+```
+
+### CLI Commands
+
+Your project gets its own CLI command **automatically installed** when first used - no setup required! 🎉
+
+```bash
+# Health monitoring (auto-installs CLI if needed)
+make health                     # Basic health check
+make health-detailed            # Detailed component status
+make health-json               # JSON output for scripts
+make health-quick              # Quick healthy/unhealthy check
+
+# Direct CLI usage (after first make command)
+clean-validation health check              # Basic health check
+clean-validation health check --detailed   # Detailed component status
+clean-validation health check --json       # JSON output for scripts
+clean-validation health quick              # Quick healthy/unhealthy check
+
+# Explore all commands
+clean-validation --help                    # See all available commands
+clean-validation health --help             # See health subcommand options
+```
+
+**Environment Issues?** If CLI commands don't work:
+```bash
+# Ensure you're in the project's virtual environment
+unset VIRTUAL_ENV               # Clear Docker contamination
+source .venv/bin/activate       # Activate local venv
+make health                     # This will auto-install CLI
+# Or manually: make install-cli
+```
+
+### Documentation
+```bash
+make docs-serve  # Serve docs at http://localhost:8001/clean-validation/
+```
+
+## Docker
+
+### Development
+```bash
+docker compose --profile dev up
+```
+
+### Production
+```bash
+docker compose --profile prod up
+```
+
+## Configuration
+
+### Database Settings
+
+The database component uses SQLite with the following default configuration:
+
+```bash
+# Environment variables (add to .env file)
+DATABASE_URL=sqlite:///data/app.db          # Database file location
+DATABASE_ENGINE_ECHO=false                  # Enable SQL query logging
+```
+
+### Database Usage
+
+```python
+from app.core.db import db_session
+from sqlmodel import SQLModel, Field, select
+
+# Define a model
+class User(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str
+    email: str
+
+# Use the database
+with db_session() as session:
+    user = User(name="John Doe", email="john@example.com")
+    session.add(user)
+    # Auto-committed by context manager
+```
+
+## Project Structure
+
+```
+clean-validation/
+├── app/                    # Application code
+│   ├── components/         # Component implementations
+│   │   ├── backend/       # FastAPI backend
+│   │   └── frontend/      # Flet frontend
+│   │   └── scheduler/     # APScheduler background tasks
+│   ├── cli/               # CLI commands and health monitoring
+│   ├── core/              # Core utilities
+│   │   ├── config.py      # Environment-dependent configuration
+│   │   ├── constants.py   # Immutable constants (12-Factor App)
+│   │   ├── db.py          # Database connection and session management
+│   │   └── log.py         # Structured logging
+│   ├── entrypoints/       # Execution entry points
+│   ├── integrations/      # App composition layer
+├── tests/                 # Test suite
+├── docs/                  # Documentation
+├── docker-compose.yml     # Docker services
+└── pyproject.toml        # Project configuration
+```
+
+---
+
+Generated with [Aegis Stack](https://github.com/lbedner/aegis-stack) 🛡️

aegis/templates/copier-aegis-project/{{ project_slug }}/clean-validation/docker-compose.yml.jinja

@@ -0,0 +1,78 @@
+
+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}"
+    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
+  # Scheduler service (runs scheduler tasks independently)
+  scheduler:
+    <<: *app
+    command:
+      - scheduler
+    restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 256M
+          cpus: '0.25'
+        reservations:
+          memory: 128M
+          cpus: '0.1'
+    profiles:
+      - dev
+      - prod
+
+  # TEST PROFILE
+
+  test_runner:
+    <<: *app
+    command:
+      - test
+    env_file:
+      - ${AEGIS_STACK_ENV_FILE:-.env}
+    profiles:
+      - test
+
+volumes:
+  aegis-data: