aegis-stack 0.2.0rc2__py3-none-any.whl

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

@@ -0,0 +1,280 @@
+"""
+API models for{%- if cookiecutter.include_worker == "yes" %} background tasks{%- endif %}{%- if cookiecutter.include_worker == "yes" and cookiecutter.scheduler_backend != "memory" %} and{%- endif %}{%- if cookiecutter.scheduler_backend != "memory" %} scheduled tasks{%- endif %} and responses.
+
+This module contains all Pydantic models used by the API layer for
+task management, status tracking, and response formatting.
+"""
+
+{%- if cookiecutter.include_worker == "yes" or cookiecutter.scheduler_backend != "memory" %}
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+{%- endif %}
+
+{%- if cookiecutter.include_worker == "yes" %}
+from app.components.worker.constants import LoadTestTypes
+{%- endif %}
+
+{%- if cookiecutter.scheduler_backend != "memory" %}
+from app.services.scheduler.models import ScheduledTask, TaskStatistics
+{%- endif %}
+
+{%- if cookiecutter.include_worker == "yes" %}
+
+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"
+    )
+    task_kwargs: dict[str, Any] = Field(
+        default_factory=dict, description="Keyword arguments for the task"
+    )
+    delay_seconds: int | None = 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: datetime | None = 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: datetime | None = Field(
+        None, description="When the task was enqueued"
+    )
+    start_time: datetime | None = Field(
+        None, description="When the task started processing"
+    )
+    finish_time: datetime | None = Field(None, description="When the task completed")
+    result_available: bool = Field(
+        False, description="Whether task result is available"
+    )
+    error: str | None = 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: datetime | None = Field(
+        None, description="When the task was enqueued"
+    )
+    start_time: datetime | None = Field(
+        None, description="When the task started processing"
+    )
+    finish_time: datetime | None = 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: datetime | None = 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: datetime | None = 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 %}
+
+{%- if cookiecutter.scheduler_backend != "memory" %}
+
+# ============================================================================
+# SCHEDULED TASK API MODELS
+# ============================================================================
+
+class ScheduledTaskListResponse(BaseModel):
+    """Response model for listing scheduled tasks."""
+
+    tasks: list[ScheduledTask] = Field(..., description="List of scheduled tasks")
+    total_count: int = Field(..., description="Total number of scheduled tasks")
+
+
+class ScheduledTaskDetailResponse(BaseModel):
+    """Response model for scheduled task details."""
+
+    task: ScheduledTask = Field(..., description="Detailed scheduled task information")
+
+
+class ScheduledTaskStatisticsResponse(BaseModel):
+    """Response model for scheduled task statistics."""
+
+    statistics: TaskStatistics = Field(..., description="Task statistics summary")
+{%- endif %}

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

@@ -0,0 +1,32 @@
+from fastapi import FastAPI
+
+from app.components.backend.api import health
+{%- if cookiecutter.include_worker == "yes" %}
+from app.components.backend.api import worker
+{%- endif %}
+{%- if cookiecutter.scheduler_backend != "memory" %}
+from app.components.backend.api import scheduler
+{%- endif %}
+{%- if cookiecutter.include_auth == "yes" %}
+from app.components.backend.api.auth.router import router as auth_router
+{%- endif %}
+{%- if cookiecutter.include_ai == "yes" %}
+from app.components.backend.api.ai.router import router as ai_router
+{%- 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(worker.router, prefix="/api/v1", tags=["worker"])
+    {%- endif %}
+    {%- if cookiecutter.scheduler_backend != "memory" %}
+    app.include_router(scheduler.router, prefix="/api/v1", tags=["scheduler"])
+    {%- endif %}
+    {%- if cookiecutter.include_auth == "yes" %}
+    app.include_router(auth_router, prefix="/api/v1")
+    {%- endif %}
+    {%- if cookiecutter.include_ai == "yes" %}
+    app.include_router(ai_router)
+    {%- endif %}

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

@@ -0,0 +1,121 @@
+{%- if cookiecutter.scheduler_backend != "memory" %}
+"""Scheduled job API endpoints."""
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from app.components.backend.api.models import (
+    ScheduledTaskDetailResponse,
+    ScheduledTaskListResponse,
+    ScheduledTaskStatisticsResponse,
+)
+from app.core.log import logger
+from app.services.scheduler import ScheduledTaskManager
+
+router = APIRouter(prefix="/scheduler", tags=["scheduler"])
+
+
+async def get_task_manager() -> ScheduledTaskManager:
+    """Dependency to provide ScheduledTaskManager instance."""
+    return ScheduledTaskManager()
+
+
+@router.get("/jobs", response_model=ScheduledTaskListResponse)
+async def list_scheduled_jobs(
+    manager: ScheduledTaskManager = Depends(get_task_manager)
+) -> ScheduledTaskListResponse:
+    """Get list of all scheduled jobs."""
+    try:
+        tasks = await manager.list_tasks()
+
+        return ScheduledTaskListResponse(
+            tasks=tasks,
+            total_count=len(tasks)
+        )
+
+    except RuntimeError as e:
+        raise HTTPException(
+            status_code=503,
+            detail={
+                "error": "scheduler_unavailable",
+                "message": str(e)
+            }
+        )
+    except Exception as e:
+        logger.error(f"Failed to list scheduled jobs: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail={
+                "error": "internal_error",
+                "message": f"Failed to retrieve scheduled jobs: {str(e)}"
+            }
+        )
+
+
+@router.get("/jobs/{job_id}", response_model=ScheduledTaskDetailResponse)
+async def get_scheduled_job(
+    job_id: str, manager: ScheduledTaskManager = Depends(get_task_manager)
+) -> ScheduledTaskDetailResponse:
+    """Get specific scheduled job details."""
+    try:
+        task = await manager.get_task(job_id)
+
+        if not task:
+            raise HTTPException(
+                status_code=404,
+                detail={
+                    "error": "job_not_found",
+                    "message": f"Scheduled job '{job_id}' not found"
+                }
+            )
+
+        return ScheduledTaskDetailResponse(task=task)
+
+    except HTTPException:
+        raise
+    except RuntimeError as e:
+        raise HTTPException(
+            status_code=503,
+            detail={
+                "error": "scheduler_unavailable",
+                "message": str(e)
+            }
+        )
+    except Exception as e:
+        logger.error(f"Failed to get scheduled job {job_id}: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail={
+                "error": "internal_error",
+                "message": f"Failed to retrieve job details: {str(e)}"
+            }
+        )
+
+
+@router.get("/statistics", response_model=ScheduledTaskStatisticsResponse)
+async def get_scheduler_statistics(
+    manager: ScheduledTaskManager = Depends(get_task_manager)
+) -> ScheduledTaskStatisticsResponse:
+    """Get scheduler statistics."""
+    try:
+        statistics = await manager.get_statistics()
+
+        return ScheduledTaskStatisticsResponse(statistics=statistics)
+
+    except RuntimeError as e:
+        raise HTTPException(
+            status_code=503,
+            detail={
+                "error": "scheduler_unavailable",
+                "message": str(e)
+            }
+        )
+    except Exception as e:
+        logger.error(f"Failed to get scheduler statistics: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail={
+                "error": "internal_error",
+                "message": f"Failed to retrieve statistics: {str(e)}"
+            }
+        )
+{%- endif %}