codeframe-ai 0.9.0__py3-none-any.whl

codeframe/ui/response_models.py

@@ -0,0 +1,201 @@
+"""Standardized API response models for CodeFRAME v2.
+
+This module provides consistent response and error formats for all v2 API endpoints.
+
+Standard Response Format:
+{
+    "success": true,
+    "data": { ... },
+    "message": "Optional human-readable message"
+}
+
+Standard Error Format:
+{
+    "error": "Error description",
+    "detail": "Additional context",
+    "code": "ERROR_CODE"
+}
+
+Usage:
+    from codeframe.ui.response_models import ApiResponse, api_response, ApiError
+
+    @router.get("/items")
+    async def list_items() -> ApiResponse[list[Item]]:
+        items = get_items()
+        return api_response(items, message="Retrieved 5 items")
+
+    # For errors, raise HTTPException with ApiError detail
+    raise HTTPException(status_code=404, detail=ApiError(
+        error="Item not found",
+        detail=f"No item with id {item_id}",
+        code="ITEM_NOT_FOUND"
+    ).model_dump())
+"""
+
+from typing import Any, Generic, Optional, TypeVar
+
+from pydantic import BaseModel, Field
+
+T = TypeVar("T")
+
+
+# ============================================================================
+# Standard Response Models
+# ============================================================================
+
+
+class ApiResponse(BaseModel, Generic[T]):
+    """Standard API response wrapper.
+
+    All successful responses should use this format for consistency.
+    """
+
+    success: bool = Field(default=True, description="Whether the request succeeded")
+    data: T = Field(..., description="Response payload")
+    message: Optional[str] = Field(default=None, description="Optional human-readable message")
+
+
+class ApiError(BaseModel):
+    """Standard API error format.
+
+    Use this for HTTPException details to ensure consistent error responses.
+    """
+
+    error: str = Field(..., description="Error description")
+    detail: Optional[str] = Field(default=None, description="Additional context")
+    code: str = Field(..., description="Machine-readable error code")
+
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    """Standard paginated response wrapper."""
+
+    success: bool = Field(default=True)
+    data: list[T] = Field(..., description="List of items")
+    total: int = Field(..., description="Total number of items")
+    page: int = Field(..., description="Current page number")
+    page_size: int = Field(..., description="Items per page")
+    message: Optional[str] = Field(default=None)
+
+
+# ============================================================================
+# Helper Functions
+# ============================================================================
+
+
+def api_response(
+    data: Any,
+    message: Optional[str] = None,
+) -> dict:
+    """Create a standard API response dict.
+
+    Args:
+        data: Response payload
+        message: Optional human-readable message
+
+    Returns:
+        Dict in standard response format
+
+    Example:
+        return api_response({"id": 1, "name": "test"}, message="Created successfully")
+    """
+    response = {
+        "success": True,
+        "data": data,
+    }
+    if message:
+        response["message"] = message
+    return response
+
+
+def api_error(
+    error: str,
+    code: str,
+    detail: Optional[str] = None,
+) -> dict:
+    """Create a standard API error dict for HTTPException detail.
+
+    Args:
+        error: Error description
+        code: Machine-readable error code
+        detail: Additional context
+
+    Returns:
+        Dict in standard error format
+
+    Example:
+        raise HTTPException(
+            status_code=404,
+            detail=api_error("Not found", "ITEM_NOT_FOUND", f"No item {id}")
+        )
+    """
+    result = {
+        "error": error,
+        "code": code,
+    }
+    if detail:
+        result["detail"] = detail
+    return result
+
+
+# ============================================================================
+# Common Error Codes
+# ============================================================================
+
+
+class ErrorCodes:
+    """Standard error codes for consistent error handling."""
+
+    # Resource errors (4xx)
+    NOT_FOUND = "NOT_FOUND"
+    ALREADY_EXISTS = "ALREADY_EXISTS"
+    INVALID_REQUEST = "INVALID_REQUEST"
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+
+    # Authorization errors
+    UNAUTHORIZED = "UNAUTHORIZED"
+    FORBIDDEN = "FORBIDDEN"
+
+    # State errors
+    INVALID_STATE = "INVALID_STATE"
+    CONFLICT = "CONFLICT"
+
+    # Execution errors
+    EXECUTION_FAILED = "EXECUTION_FAILED"
+    TIMEOUT = "TIMEOUT"
+
+    # Server errors (5xx)
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
+
+
+# ============================================================================
+# Common Success Messages
+# ============================================================================
+
+
+def created_message(resource: str, id: Any = None) -> str:
+    """Generate a standard created message."""
+    if id:
+        return f"{resource} created successfully (id: {id})"
+    return f"{resource} created successfully"
+
+
+def updated_message(resource: str, id: Any = None) -> str:
+    """Generate a standard updated message."""
+    if id:
+        return f"{resource} updated successfully (id: {id})"
+    return f"{resource} updated successfully"
+
+
+def deleted_message(resource: str, id: Any = None) -> str:
+    """Generate a standard deleted message."""
+    if id:
+        return f"{resource} deleted successfully (id: {id})"
+    return f"{resource} deleted successfully"
+
+
+def retrieved_message(resource: str, count: Optional[int] = None) -> str:
+    """Generate a standard retrieval message."""
+    if count is not None:
+        return f"Retrieved {count} {resource}(s)"
+    return f"{resource} retrieved successfully"

codeframe/ui/routers/__init__.py

@@ -0,0 +1,5 @@
+"""FastAPI router modules.
+
+This package contains all API router modules, organized by domain.
+Each router handles a specific set of related endpoints.
+"""

codeframe/ui/routers/_helpers.py

@@ -0,0 +1,29 @@
+"""Shared helpers for v2 routers."""
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+
+def atomic_write_json(path: Path, payload: dict) -> None:
+    """Write JSON via per-call unique temp-file + os.replace.
+
+    A unique temp name is required so concurrent writers to the same target
+    do not collide on a shared `.tmp` suffix.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=f".{path.name}.", suffix=".tmp", dir=path.parent
+    )
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(json.dumps(payload, indent=2))
+        os.replace(tmp_name, path)
+    except Exception:
+        # Clean up the temp file on failure so we don't leak it.
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise

codeframe/ui/routers/batches_v2.py

@@ -0,0 +1,315 @@
+"""V2 Batches router - delegates to core/conductor module.
+
+This module provides v2-style API endpoints for batch execution management.
+Batches represent coordinated execution of multiple tasks.
+
+Routes:
+    GET  /api/v2/batches             - List batches
+    GET  /api/v2/batches/{id}        - Get batch status
+    POST /api/v2/batches/{id}/stop   - Stop a running batch
+    POST /api/v2/batches/{id}/resume - Resume a batch
+"""
+
+import logging
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from pydantic import BaseModel, Field
+
+from codeframe.core.workspace import Workspace
+from codeframe.lib.rate_limiter import rate_limit_standard
+from codeframe.core import conductor
+from codeframe.core.conductor import BatchStatus
+from codeframe.ui.dependencies import get_v2_workspace
+from codeframe.ui.response_models import api_error, ErrorCodes
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/v2/batches", tags=["batches-v2"])
+
+
+# ============================================================================
+# Request/Response Models
+# ============================================================================
+
+
+class BatchResponse(BaseModel):
+    """Response for a single batch."""
+
+    id: str
+    workspace_id: str
+    task_ids: list[str]
+    status: str
+    strategy: str
+    max_parallel: int
+    on_failure: str
+    started_at: Optional[str]
+    completed_at: Optional[str]
+    results: dict[str, str]  # task_id -> RunStatus value
+
+
+class BatchListResponse(BaseModel):
+    """Response for batch list."""
+
+    batches: list[BatchResponse]
+    total: int
+    by_status: dict[str, int]
+
+
+class StopBatchRequest(BaseModel):
+    """Request for stopping a batch."""
+
+    force: bool = Field(False, description="Force stop by terminating running processes")
+
+
+class ResumeBatchRequest(BaseModel):
+    """Request for resuming a batch."""
+
+    force: bool = Field(False, description="Re-run all tasks including completed ones")
+
+
+# ============================================================================
+# Helper Functions
+# ============================================================================
+
+
+def _batch_to_response(batch: conductor.BatchRun) -> BatchResponse:
+    """Convert a BatchRun to a BatchResponse."""
+    return BatchResponse(
+        id=batch.id,
+        workspace_id=batch.workspace_id,
+        task_ids=batch.task_ids,
+        status=batch.status.value,
+        strategy=batch.strategy,
+        max_parallel=batch.max_parallel,
+        on_failure=batch.on_failure.value,
+        started_at=batch.started_at.isoformat() if batch.started_at else None,
+        completed_at=batch.completed_at.isoformat() if batch.completed_at else None,
+        results={k: v.value if hasattr(v, 'value') else str(v) for k, v in batch.results.items()},
+    )
+
+
+# ============================================================================
+# Endpoints
+# ============================================================================
+
+
+@router.get("", response_model=BatchListResponse)
+@rate_limit_standard()
+async def list_batches(
+    request: Request,
+    status: Optional[str] = Query(None, description="Filter by status (PENDING, RUNNING, COMPLETED, PARTIAL, FAILED, CANCELLED)"),
+    limit: int = Query(20, ge=1, le=100),
+    workspace: Workspace = Depends(get_v2_workspace),
+) -> BatchListResponse:
+    """List batches in the workspace.
+
+    Args:
+        status: Optional status filter
+        limit: Maximum batches to return
+        workspace: v2 Workspace
+
+    Returns:
+        List of batches with counts by status
+    """
+    # Parse status filter
+    status_filter = None
+    if status:
+        try:
+            status_filter = BatchStatus(status.upper())
+        except ValueError:
+            raise HTTPException(
+                status_code=400,
+                detail=api_error(
+                    f"Invalid status: {status}",
+                    ErrorCodes.VALIDATION_ERROR,
+                    f"Valid values: {[s.value for s in BatchStatus]}",
+                ),
+            )
+
+    # Get batches
+    batch_list = conductor.list_batches(workspace, status=status_filter, limit=limit)
+
+    # Calculate counts by status
+    all_batches = conductor.list_batches(workspace, limit=1000)
+    status_counts: dict[str, int] = {}
+    for batch in all_batches:
+        status_val = batch.status.value
+        status_counts[status_val] = status_counts.get(status_val, 0) + 1
+
+    return BatchListResponse(
+        batches=[_batch_to_response(b) for b in batch_list],
+        total=len(batch_list),
+        by_status=status_counts,
+    )
+
+
+@router.get("/{batch_id}", response_model=BatchResponse)
+@rate_limit_standard()
+async def get_batch(
+    request: Request,
+    batch_id: str,
+    workspace: Workspace = Depends(get_v2_workspace),
+) -> BatchResponse:
+    """Get a specific batch by ID.
+
+    Args:
+        batch_id: Batch identifier
+        workspace: v2 Workspace
+
+    Returns:
+        Batch details
+
+    Raises:
+        HTTPException: 404 if batch not found
+    """
+    batch = conductor.get_batch(workspace, batch_id)
+
+    if not batch:
+        raise HTTPException(
+            status_code=404,
+            detail=api_error("Batch not found", ErrorCodes.NOT_FOUND, f"No batch with id {batch_id}"),
+        )
+
+    return _batch_to_response(batch)
+
+
+@router.post("/{batch_id}/stop", response_model=BatchResponse)
+@rate_limit_standard()
+async def stop_batch(
+    request: Request,
+    batch_id: str,
+    body: StopBatchRequest = None,
+    workspace: Workspace = Depends(get_v2_workspace),
+) -> BatchResponse:
+    """Stop a running batch.
+
+    Graceful stop (force=False):
+        - Marks batch as CANCELLED
+        - Running tasks finish naturally
+
+    Force stop (force=True):
+        - Sends SIGTERM to running processes
+        - Immediate termination
+
+    Args:
+        request: HTTP request for rate limiting
+        batch_id: Batch to stop
+        body: Stop options
+        workspace: v2 Workspace
+
+    Returns:
+        Updated batch
+
+    Raises:
+        HTTPException:
+            - 404: Batch not found
+            - 400: Batch not in stoppable state
+    """
+    force = body.force if body else False
+
+    try:
+        batch = conductor.stop_batch(workspace, batch_id, force=force)
+        return _batch_to_response(batch)
+
+    except ValueError as e:
+        error_msg = str(e)
+        if "not found" in error_msg.lower():
+            raise HTTPException(
+                status_code=404,
+                detail=api_error("Batch not found", ErrorCodes.NOT_FOUND, error_msg),
+            )
+        raise HTTPException(
+            status_code=400,
+            detail=api_error("Cannot stop batch", ErrorCodes.INVALID_STATE, error_msg),
+        )
+
+
+@router.post("/{batch_id}/resume", response_model=BatchResponse)
+@rate_limit_standard()
+async def resume_batch(
+    request: Request,
+    batch_id: str,
+    body: ResumeBatchRequest = None,
+    workspace: Workspace = Depends(get_v2_workspace),
+) -> BatchResponse:
+    """Resume a batch by re-running failed/blocked tasks.
+
+    Args:
+        request: HTTP request for rate limiting
+        batch_id: Batch to resume
+        body: Resume options
+        workspace: v2 Workspace
+
+    Returns:
+        Updated batch
+
+    Raises:
+        HTTPException:
+            - 404: Batch not found
+            - 400: Batch not in resumable state
+    """
+    force = body.force if body else False
+
+    try:
+        batch = conductor.resume_batch(workspace, batch_id, force=force)
+        return _batch_to_response(batch)
+
+    except ValueError as e:
+        error_msg = str(e)
+        if "not found" in error_msg.lower():
+            raise HTTPException(
+                status_code=404,
+                detail=api_error("Batch not found", ErrorCodes.NOT_FOUND, error_msg),
+            )
+        raise HTTPException(
+            status_code=400,
+            detail=api_error("Cannot resume batch", ErrorCodes.INVALID_STATE, error_msg),
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to resume batch {batch_id}: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=500,
+            detail=api_error("Resume failed", ErrorCodes.EXECUTION_FAILED, str(e)),
+        )
+
+
+@router.post("/{batch_id}/cancel", response_model=BatchResponse)
+@rate_limit_standard()
+async def cancel_batch(
+    request: Request,
+    batch_id: str,
+    workspace: Workspace = Depends(get_v2_workspace),
+) -> BatchResponse:
+    """Cancel a running batch.
+
+    Similar to stop but with explicit cancel semantics.
+
+    Args:
+        batch_id: Batch to cancel
+        workspace: v2 Workspace
+
+    Returns:
+        Updated batch
+
+    Raises:
+        HTTPException:
+            - 404: Batch not found
+            - 400: Batch not in cancellable state
+    """
+    try:
+        batch = conductor.cancel_batch(workspace, batch_id)
+        return _batch_to_response(batch)
+
+    except ValueError as e:
+        error_msg = str(e)
+        if "not found" in error_msg.lower():
+            raise HTTPException(
+                status_code=404,
+                detail=api_error("Batch not found", ErrorCodes.NOT_FOUND, error_msg),
+            )
+        raise HTTPException(
+            status_code=400,
+            detail=api_error("Cannot cancel batch", ErrorCodes.INVALID_STATE, error_msg),
+        )