aegis-stack 0.2.0rc2__py3-none-any.whl

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

@@ -0,0 +1,215 @@
+# Development Guide
+
+This guide covers how to develop and maintain {{ cookiecutter.project_name }}.
+
+## Getting Started
+
+### Prerequisites
+- Python 3.11+
+- UV package manager
+
+### Setup
+```bash
+# Clone and enter the project
+cd {{ cookiecutter.project_slug }}
+
+# Install dependencies
+uv sync
+
+# Copy environment template
+cp .env.example .env
+
+# Start development server
+make run
+```
+
+## Development Commands
+
+### Running the Application
+```bash
+make run          # Start with Docker
+```
+
+### Health Monitoring
+```bash
+make health         # Check system health
+make health-detailed # Detailed health information
+make health-json    # JSON health output
+```
+
+### Code Quality
+```bash
+make test           # Run test suite
+make lint           # Check code style
+make typecheck      # Run type checking
+make check          # Run all checks
+make fix            # Auto-fix code issues
+```
+
+### Documentation
+```bash
+make docs-serve     # Serve documentation locally (http://localhost:8001)
+make docs-build     # Build static documentation
+```
+
+## Project Structure
+
+```
+{{ cookiecutter.project_slug }}/
+├── app/
+│   ├── components/     # Application components{% if cookiecutter.include_scheduler == "yes" %}
+│   │   ├── scheduler/  # Background task scheduling{% endif %}
+│   │   ├── backend/    # FastAPI web server
+│   │   ├── frontend/   # Flet user interface
+│   │   └── worker/     # Background task workers (arq)
+│   ├── core/          # Core utilities and configuration
+│   ├── services/      # Business logic services
+│   └── cli/           # Command-line interface
+├── tests/             # Test suite
+├── docs/              # Project documentation
+└── docker-compose.yml # Container orchestration
+```
+
+## Adding New Features
+
+### 1. Create Business Logic
+Add pure business logic functions to `app/services/`:
+
+```python
+# app/services/my_service.py
+async def process_data(data: str) -> str:
+    """Process data and return result."""
+    return f"Processed: {data}"
+```
+
+### 2. Add API Endpoints
+Create routes in `app/components/backend/api/`:
+
+```python
+# app/components/backend/api/my_endpoints.py
+from fastapi import APIRouter
+from app.services.my_service import process_data
+
+router = APIRouter()
+
+@router.post("/process")
+async def process_endpoint(data: str):
+    result = await process_data(data)
+    return {"result": result}
+```
+
+Register in `app/components/backend/api/routing.py`:
+
+```python
+from app.components.backend.api import my_endpoints
+
+def include_routers(app: FastAPI) -> None:
+    app.include_router(my_endpoints.router, prefix="/api", tags=["processing"])
+```
+
+### 3. Add Background Tasks
+Create worker tasks in `app/components/worker/tasks/`:
+
+```python
+# app/components/worker/tasks/my_tasks.py
+async def background_process_data(data: str) -> dict[str, str]:
+    """Process data in background."""
+    logger.info(f"Processing {data} in background")
+    
+    # Your processing logic here
+    result = f"Processed: {data}"
+    
+    return {
+        "status": "completed",
+        "result": result,
+        "timestamp": datetime.now(UTC).isoformat()
+    }
+```
+
+Register in worker queue (`app/components/worker/queues/system.py`):
+
+```python
+from app.components.worker.tasks.my_tasks import background_process_data
+
+class WorkerSettings:
+    functions = [
+        system_health_check,
+        background_process_data,  # Add your task here
+    ]
+```{% if cookiecutter.include_scheduler == "yes" %}
+
+### 4. Add Scheduled Tasks
+Add jobs to the scheduler component:
+
+```python
+# In app/components/scheduler/main.py
+from app.services.my_service import process_data
+
+# Add to create_scheduler function
+scheduler.add_job(
+    func=lambda: process_data("scheduled"),
+    trigger="cron",
+    hour=2,  # Run at 2 AM daily
+    id="daily_processing",
+    name="Daily Data Processing"
+)
+```{% endif %}
+
+## Testing
+
+### Running Tests
+```bash
+make test           # All tests
+make test-verbose   # Verbose output
+```
+
+### Writing Tests
+Create tests in the `tests/` directory:
+
+```python
+# tests/services/test_my_service.py
+import pytest
+from app.services.my_service import process_data
+
+@pytest.mark.asyncio
+async def test_process_data():
+    result = await process_data("test")
+    assert result == "Processed: test"
+```
+
+## Deployment
+
+### Docker Deployment
+```bash
+# Build and run
+make docker-build
+make docker-up
+
+# Or use profiles for specific components
+docker compose --profile dev up
+```
+
+### Environment Configuration
+Configure `.env` file for your environment:
+
+```env
+# API Configuration
+API_HOST=0.0.0.0
+API_PORT=8000
+
+# Logging
+LOG_LEVEL=INFO{% if cookiecutter.include_scheduler == "yes" %}
+
+# Scheduler Configuration  
+SCHEDULER_TIMEZONE=UTC{% endif %}
+```
+
+## Monitoring and Health Checks
+
+{{ cookiecutter.project_name }} includes comprehensive health monitoring:
+
+- **Health Endpoints**: `/health/` and `/health/detailed`
+- **CLI Commands**: `{{ cookiecutter.project_slug }} health check`
+- **Component Monitoring**: Automatic health checks for all components
+
+See [Health Monitoring](health.md) for complete details.

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.now(UTC)
+        # ... database check logic ...
+        end_time = datetime.now(UTC)
+        
+        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