aegis-stack 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,240 @@
+# Health Monitoring
+
+{{ cookiecutter.project_name }} includes comprehensive health monitoring capabilities through both API endpoints and CLI commands.
+
+## Health Check Endpoints
+
+### Basic Health Check
+- **URL**: `GET /health/`
+- **Purpose**: Quick health status check
+- **Response Time**: < 100ms
+
+### Detailed Health Check  
+- **URL**: `GET /health/detailed`
+- **Purpose**: Comprehensive system health with metrics
+- **Response Time**: < 500ms
+
+## CLI Health Commands
+
+{{ cookiecutter.project_name }} provides a built-in CLI for health monitoring:
+
+### Basic Health Check
+```bash
+{{ cookiecutter.project_slug }} health status
+```
+
+**Output:**
+```
+✅ {{ cookiecutter.project_name }} - System Status: HEALTHY
+
+🖥️  System Health:
+   • CPU Usage: 15.2%
+   • Memory Usage: 45.8%  
+   • Disk Usage: 32.1%
+   • Response Time: 2.1ms{% if cookiecutter.include_scheduler == "yes" %}
+
+⏰ Scheduler Health:
+   • Status: HEALTHY
+   • Active Jobs: 2
+   • Next Run: 2024-01-01 02:00:00
+   • Response Time: 1.5ms{% endif %}
+
+🔍 Overall Health: 98.5%
+```
+
+### Detailed Health Check
+```bash
+{{ cookiecutter.project_slug }} health status --detailed
+```
+
+Shows comprehensive system information including:
+- Component-level health status
+- System resource utilization
+- Response time metrics
+- Uptime information
+
+### JSON Output
+```bash
+{{ cookiecutter.project_slug }} health status --json
+```
+
+Returns structured JSON for integration with monitoring systems:
+
+```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,
+  "health_percentage": 98.5
+}
+```
+
+### Health Probe
+```bash
+{{ cookiecutter.project_slug }} health probe
+```
+
+Returns simple healthy/unhealthy status for use in scripts and monitoring.
+
+## Using Health Checks in Development
+
+### Make Commands
+Convenient make targets are available:
+
+```bash
+make health         # Basic health check
+make health-detailed # Detailed health information  
+make health-json    # JSON health output
+make health-probe   # Health probe for monitoring
+```
+
+## Health Check Components
+
+### System Health
+Monitors core system resources:
+
+- **CPU Usage**: Current CPU utilization percentage
+- **Memory Usage**: RAM utilization percentage  
+- **Disk Usage**: Disk space utilization percentage
+- **Response Time**: Health check response time{% if cookiecutter.include_scheduler == "yes" %}
+
+### Scheduler Health  
+Monitors the background task scheduler:
+
+- **Scheduler Status**: Running/stopped status
+- **Active Jobs**: Number of currently scheduled jobs
+- **Next Run**: When the next job will execute
+- **Job History**: Recent job execution status{% endif %}
+
+## Integration with Monitoring Systems
+
+### Prometheus Metrics
+To add Prometheus metrics:
+
+```python
+# app/components/backend/middleware/prometheus.py
+from prometheus_client import Counter, Histogram, generate_latest
+from fastapi import Request, Response
+
+REQUEST_COUNT = Counter('http_requests_total', 'Total HTTP requests', ['method', 'endpoint'])
+REQUEST_DURATION = Histogram('http_request_duration_seconds', 'HTTP request duration')
+
+@app.middleware("http")
+async def prometheus_middleware(request: Request, call_next):
+    start_time = time.time()
+    response = await call_next(request)
+    
+    REQUEST_COUNT.labels(method=request.method, endpoint=request.url.path).inc()
+    REQUEST_DURATION.observe(time.time() - start_time)
+    
+    return response
+
+@app.get("/metrics")
+async def metrics():
+    return Response(generate_latest(), media_type="text/plain")
+```
+
+### External Health Checks
+The health endpoints can be monitored by external systems:
+
+- **Uptime monitoring**: Ping `/health/` endpoint
+- **Performance monitoring**: Track `/health/detailed` response times
+- **Alerting**: Monitor health percentage thresholds
+
+### Docker Health Checks
+The Docker container includes built-in health checks:
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+```
+
+## Troubleshooting Health Issues
+
+### Common Issues
+
+**Health check timeouts:**
+- Check if application is running on expected port
+- Verify no firewall blocking connections
+- Check application logs for startup errors
+
+**High resource usage:**
+- Monitor CPU/memory usage over time
+- Check for memory leaks in long-running processes
+- Review recent code changes{% if cookiecutter.include_scheduler == "yes" %}
+
+**Scheduler issues:**
+- Check scheduler logs for job failures
+- Verify scheduled job configurations
+- Monitor job execution times{% endif %}
+
+### Debug Commands
+```bash
+# Check if service is running
+curl http://localhost:8000/health/
+
+# Check application logs  
+docker compose logs -f
+
+# Monitor resource usage
+docker stats
+
+# Test CLI connectivity
+{{ cookiecutter.project_slug }} health check --debug
+```
+
+## Health Check Best Practices
+
+1. **Regular Monitoring**: Set up automated health checks every 30-60 seconds
+2. **Alerting Thresholds**: Alert when health percentage drops below 95%
+3. **Response Time Monitoring**: Alert on health check response times > 1 second
+4. **Component-Level Monitoring**: Monitor individual components, not just overall health
+5. **Historical Tracking**: Store health metrics for trend analysis
+
+## Customizing Health Checks
+
+To add custom health checks, extend the system service:
+
+```python
+# app/services/system_service.py
+async def check_database_health() -> ComponentHealth:
+    """Check database connectivity."""
+    try:
+        # Perform database ping
+        start_time = datetime.utcnow()
+        # ... database check logic ...
+        end_time = datetime.utcnow()
+        
+        return ComponentHealth(
+            status="healthy",
+            details={
+                "connection_pool": "active",
+                "query_response_ms": (end_time - start_time).total_seconds() * 1000
+            },
+            response_time_ms=(end_time - start_time).total_seconds() * 1000
+        )
+    except Exception as e:
+        return ComponentHealth(
+            status="unhealthy", 
+            details={"error": str(e)},
+            response_time_ms=0
+        )
+```
+
+Then register it in the health check system to have it included in all health reports.

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/docs/javascripts/mermaid-config.js

@@ -0,0 +1,62 @@
+// Mermaid configuration for dark/light mode support
+document.addEventListener("DOMContentLoaded", function() {
+    // Function to get current theme
+    function getCurrentTheme() {
+        return document.querySelector('[data-md-color-scheme]').getAttribute('data-md-color-scheme');
+    }
+    
+    // Function to configure Mermaid theme
+    function configureMermaid() {
+        const theme = getCurrentTheme();
+        const mermaidTheme = theme === 'slate' ? 'dark' : 'default';
+        
+        mermaid.initialize({
+            startOnLoad: true,
+            theme: mermaidTheme,
+            themeVariables: {
+                // Light mode colors
+                primaryColor: theme === 'default' ? '#1976d2' : '#64b5f6',
+                primaryTextColor: theme === 'default' ? '#000000' : '#ffffff',
+                primaryBorderColor: theme === 'default' ? '#1976d2' : '#64b5f6',
+                lineColor: theme === 'default' ? '#333333' : '#ffffff',
+                secondaryColor: theme === 'default' ? '#e3f2fd' : '#1e1e1e',
+                tertiaryColor: theme === 'default' ? '#f5f5f5' : '#2d2d2d',
+                background: theme === 'default' ? '#ffffff' : '#1e1e1e',
+                mainBkg: theme === 'default' ? '#ffffff' : '#1e1e1e',
+                secondBkg: theme === 'default' ? '#f8f9fa' : '#2d2d2d',
+                tertiaryBkg: theme === 'default' ? '#e9ecef' : '#404040'
+            }
+        });
+        
+        // Re-render all mermaid diagrams
+        if (typeof mermaid !== 'undefined') {
+            const mermaidElements = document.querySelectorAll('.mermaid');
+            mermaidElements.forEach((element, index) => {
+                element.removeAttribute('data-processed');
+                element.innerHTML = element.getAttribute('data-original') || element.innerHTML;
+                if (!element.getAttribute('data-original')) {
+                    element.setAttribute('data-original', element.innerHTML);
+                }
+            });
+            mermaid.init();
+        }
+    }
+    
+    // Initial configuration
+    configureMermaid();
+    
+    // Listen for theme changes
+    const observer = new MutationObserver(function(mutations) {
+        mutations.forEach(function(mutation) {
+            if (mutation.type === 'attributes' && mutation.attributeName === 'data-md-color-scheme') {
+                setTimeout(configureMermaid, 100); // Small delay to ensure theme is applied
+            }
+        });
+    });
+    
+    // Start observing theme changes
+    const target = document.querySelector('[data-md-color-scheme]');
+    if (target) {
+        observer.observe(target, { attributes: true });
+    }
+});

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/docs/stylesheets/mermaid.css

@@ -0,0 +1,95 @@
+/* Mermaid diagram styling for light and dark modes */
+
+/* Base mermaid diagram styling */
+.mermaid {
+    text-align: center;
+    margin: 1em 0;
+}
+
+/* Light mode styling */
+[data-md-color-scheme="default"] .mermaid {
+    --mermaid-primary-color: #1976d2;
+    --mermaid-primary-text-color: #000000;
+    --mermaid-primary-border-color: #1976d2;
+    --mermaid-line-color: #333333;
+    --mermaid-secondary-color: #e3f2fd;
+    --mermaid-tertiary-color: #f5f5f5;
+    --mermaid-background: #ffffff;
+    --mermaid-main-bkg: #ffffff;
+    --mermaid-second-bkg: #f8f9fa;
+    --mermaid-tertiary-bkg: #e9ecef;
+}
+
+/* Dark mode styling */
+[data-md-color-scheme="slate"] .mermaid {
+    --mermaid-primary-color: #64b5f6;
+    --mermaid-primary-text-color: #ffffff;
+    --mermaid-primary-border-color: #64b5f6;
+    --mermaid-line-color: #ffffff;
+    --mermaid-secondary-color: #1e1e1e;
+    --mermaid-tertiary-color: #2d2d2d;
+    --mermaid-background: #1e1e1e;
+    --mermaid-main-bkg: #1e1e1e;
+    --mermaid-second-bkg: #2d2d2d;
+    --mermaid-tertiary-bkg: #404040;
+}
+
+/* Ensure mermaid diagrams are visible in dark mode */
+[data-md-color-scheme="slate"] .mermaid svg {
+    background: transparent !important;
+}
+
+[data-md-color-scheme="slate"] .mermaid .node rect,
+[data-md-color-scheme="slate"] .mermaid .node circle,
+[data-md-color-scheme="slate"] .mermaid .node ellipse,
+[data-md-color-scheme="slate"] .mermaid .node polygon {
+    fill: var(--mermaid-main-bkg) !important;
+    stroke: var(--mermaid-primary-border-color) !important;
+}
+
+[data-md-color-scheme="slate"] .mermaid .node .label {
+    color: var(--mermaid-primary-text-color) !important;
+}
+
+[data-md-color-scheme="slate"] .mermaid .edgePath .path {
+    stroke: var(--mermaid-line-color) !important;
+}
+
+[data-md-color-scheme="slate"] .mermaid .edgeLabel {
+    background-color: var(--mermaid-background) !important;
+    color: var(--mermaid-primary-text-color) !important;
+}
+
+/* Flowchart specific styling */
+[data-md-color-scheme="slate"] .mermaid .cluster rect {
+    fill: var(--mermaid-second-bkg) !important;
+    stroke: var(--mermaid-primary-border-color) !important;
+}
+
+[data-md-color-scheme="slate"] .mermaid .cluster .label {
+    color: var(--mermaid-primary-text-color) !important;
+}
+
+/* Sequence diagram specific styling */
+[data-md-color-scheme="slate"] .mermaid .actor {
+    fill: var(--mermaid-main-bkg) !important;
+    stroke: var(--mermaid-primary-border-color) !important;
+}
+
+[data-md-color-scheme="slate"] .mermaid .actor-line {
+    stroke: var(--mermaid-line-color) !important;
+}
+
+[data-md-color-scheme="slate"] .mermaid .messageLine0,
+[data-md-color-scheme="slate"] .mermaid .messageLine1 {
+    stroke: var(--mermaid-line-color) !important;
+}
+
+[data-md-color-scheme="slate"] .mermaid .messageText {
+    fill: var(--mermaid-primary-text-color) !important;
+}
+
+[data-md-color-scheme="slate"] .mermaid .note {
+    fill: var(--mermaid-tertiary-bkg) !important;
+    stroke: var(--mermaid-primary-border-color) !important;
+}

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

@@ -0,0 +1,62 @@
+# mkdocs.yml
+site_name: {{ cookiecutter.project_name }}
+site_description: {{ cookiecutter.project_description }}
+site_author: {{ cookiecutter.author_name }}
+site_url: https://{{ cookiecutter.github_username }}.github.io/{{ cookiecutter.project_slug }}/
+
+theme:
+  name: material
+  palette:
+    # Palette toggle for light vs dark mode
+    - scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.tabs
+    - navigation.top
+    - search.highlight
+    - search.suggest
+    - content.code.copy
+
+# Navigation structure
+nav:
+  - Home: index.md
+  - Development: development.md
+  - API Reference: api.md
+  - Health Monitoring: health.md{% if cookiecutter.include_scheduler == "yes" %}
+  - Components:
+    - Scheduler: components/scheduler.md{% endif %}
+
+# Plugins
+plugins:
+  - gen-files:
+      scripts:
+        - scripts/gen_docs.py
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            show_root_heading: true
+            show_source: true
+
+# Markdown extensions
+markdown_extensions:
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+
+# Additional configuration for Mermaid dark mode support
+extra_javascript:
+  - https://unpkg.com/mermaid@10.6.0/dist/mermaid.min.js
+  - javascripts/mermaid-config.js
+
+extra_css:
+  - stylesheets/mermaid.css

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/pyproject.toml.j2

@@ -0,0 +1,156 @@
+[project]
+name = "{{ cookiecutter.project_slug }}"
+version = "{{ cookiecutter.version }}"
+description = "{{ cookiecutter.project_description }}"
+readme = "README.md"
+requires-python = ">={{ cookiecutter.python_version }}"
+authors = [
+    {name = "{{ cookiecutter.author_name }}", email = "{{ cookiecutter.author_email }}"}
+]
+
+dependencies = [
+    "fastapi==0.116.1",
+    "flet[all]==0.28.3",
+    "uvicorn==0.35.0",
+    "structlog==25.4.0",
+    "pydantic-settings==2.10.1",
+    "typer==0.16.0",
+    # Pin click to avoid yanked versions (typer dependency)
+    "click==8.2.1",
+    # Rich CLI formatting
+    "rich==14.1.0",
+    # HTTP client for CLI API calls
+    "httpx==0.28.1",
+    # System monitoring
+    "psutil==7.0.0",
+{%- if cookiecutter.include_scheduler == "yes" %}
+    "apscheduler==3.10.4",
+{%- endif %}
+{%- if cookiecutter.include_redis == "yes" %}
+    "redis==5.0.8",
+{%- endif %}
+{%- if cookiecutter.include_worker == "yes" %}
+    "arq==0.25.0",
+{%- endif %}
+{%- if cookiecutter.include_database == "yes" %}
+    "sqlmodel>=0.0.14",
+    "sqlalchemy>=2.0.0",
+    "aiosqlite>=0.19.0",
+{%- endif %}
+{%- if cookiecutter.include_cache == "yes" %}
+    "redis[hiredis]==5.0.8",
+{%- endif %}
+]
+
+[project.scripts]
+{{cookiecutter.project_slug}} = "app.cli.main:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest==8.4.1",
+    "pytest-asyncio==1.1.0", 
+    "ruff==0.12.7",
+    "mypy==1.17.1",
+    "types-psutil==7.0.0.20250801",
+    "pre-commit==4.2.0",
+    "pip-audit==2.9.0",
+{%- if cookiecutter.include_worker == "yes" %}
+    # Development auto-reload for workers
+    "watchdog==4.0.2",
+{%- endif %}
+]
+docs = [
+    "mkdocs==1.6.1",
+    "mkdocs-material==9.6.16",
+    "mkdocstrings[python]==0.30.0",
+    "mkdocs-gen-files==0.5.0",
+    "pymdown-extensions==10.16.1",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["app"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py{{ cookiecutter.python_version.replace('.', '') }}"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]  # Added UP for pyupgrade (modern Python syntax)
+ignore = []
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.ruff.lint.isort]
+force-single-line = false
+force-sort-within-sections = true
+known-first-party = ["app"]
+
+[tool.mypy]
+python_version = "{{ cookiecutter.python_version }}"
+strict = true
+plugins = ["pydantic.mypy"]
+
+[[tool.mypy.overrides]]
+module = "flet.*"
+ignore_missing_imports = true
+
+{%- if cookiecutter.include_scheduler == "yes" %}
+
+[[tool.mypy.overrides]]
+module = "apscheduler.*"
+ignore_missing_imports = true
+{%- endif %}
+
+{%- if cookiecutter.include_redis == "yes" %}
+
+[[tool.mypy.overrides]]
+module = "redis.*"
+ignore_missing_imports = true
+{%- endif %}
+
+{%- if cookiecutter.include_worker == "yes" %}
+
+[[tool.mypy.overrides]]
+module = "arq.*"
+ignore_missing_imports = true
+{%- endif %}
+
+{%- if cookiecutter.include_database == "yes" %}
+
+[[tool.mypy.overrides]]
+module = "sqlmodel.*"
+ignore_missing_imports = true
+{%- endif %}
+
+# Ignore imports for future components that may not exist yet
+[[tool.mypy.overrides]]
+module = "app.components.database.main"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "app.components.cache.main"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "app.components.worker.*"
+ignore_missing_imports = true
+
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "httpx>=0.28.1",
+]

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/scripts/entrypoint.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+
+set -e
+
+# More comprehensive venv cleanup to prevent Docker container conflicts
+if [ -d ".venv" ]; then
+    echo "🧹 Found existing .venv directory, checking compatibility..."
+    
+    # Check if .venv has issues (broken symlinks, wrong Python version, etc.)
+    if [ -L ".venv/bin/python3" ] && [ ! -e ".venv/bin/python3" ]; then
+        echo "🧹 Cleaning up broken venv symlinks..."
+        rm -rf .venv
+    elif [ -f ".venv/bin/python3" ]; then
+        # Check if the Python executable is compatible and accessible
+        if ! .venv/bin/python3 --version > /dev/null 2>&1; then
+            echo "🧹 Cleaning up incompatible venv..."
+            rm -rf .venv
+        fi
+    elif [ ! -w ".venv" ] || [ ! -x ".venv" ]; then
+        # Check for permission issues in Docker containers
+        echo "🧹 Cleaning up venv with permission issues..."
+        rm -rf .venv
+    else
+        # If directory exists but has no python executable, clean it up
+        if [ ! -f ".venv/bin/python3" ] && [ ! -f ".venv/bin/python" ]; then
+            echo "🧹 Cleaning up incomplete venv..."
+            rm -rf .venv
+        fi
+    fi
+fi
+
+# Configure UV environment based on execution context
+if [ -n "$DOCKER_CONTAINER" ] || [ "$USER" = "root" ]; then
+    echo "🐳 Running in Docker container, configuring UV for containerized environment..."
+    
+    # Set Docker-specific UV configuration
+    export UV_PROJECT_ENVIRONMENT=/code/.venv
+    export UV_LINK_MODE=copy
+    export VIRTUAL_ENV=/code/.venv
+    
+    # Ensure .venv path is in PATH for CLI commands
+    export PATH="/code/.venv/bin:$PATH"
+    
+    echo "✅ UV configured for Docker: UV_PROJECT_ENVIRONMENT=/code/.venv"
+else
+    echo "🖥️  Running in local environment, UV will use project defaults"
+    
+    # Ensure we don't inherit Docker environment variables
+    unset UV_PROJECT_ENVIRONMENT
+    unset UV_SYSTEM_PYTHON
+    
+    # Let UV auto-detect local .venv
+    echo "✅ UV configured for local development"
+fi
+
+# Pop run_command from arguments
+run_command="$1"
+shift
+
+if [ "$run_command" = "webserver" ]; then
+    # Web server (FastAPI + Flet)
+    uv run python -m app.entrypoints.webserver
+elif [ "$run_command" = "scheduler" ]; then
+    # Scheduler component
+    uv run python -m app.entrypoints.scheduler
+elif [ "$run_command" = "lint" ]; then
+    uv run ruff check .
+elif [ "$run_command" = "typecheck" ]; then
+    uv run mypy .
+elif [ "$run_command" = "test" ]; then
+    uv run pytest "$@"
+elif [ "$run_command" = "health" ]; then
+    uv run python -m app.cli.health check "$@"
+elif [ "$run_command" = "help" ]; then
+    echo "Available commands:"
+    echo "  webserver   - Run FastAPI + Flet web server"
+    echo "  scheduler   - Run scheduler component"
+    echo "  health      - Check system health status"
+    echo "  lint        - Run ruff linting"
+    echo "  typecheck   - Run mypy type checking"
+    echo "  test        - Run pytest test suite"
+    echo "  help        - Show this help message"
+else
+    echo "Unknown command: $run_command"
+    echo "Available commands: webserver, scheduler, health, lint, typecheck, test, help"
+    exit 1
+fi