kubiya-control-plane-api 0.1.0__py3-none-any.whl → 0.3.4__py3-none-any.whl

control_plane_api/app/config.py

@@ -0,0 +1,95 @@
+from pydantic_settings import BaseSettings
+from pydantic import model_validator
+from typing import Optional
+import os
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables"""
+
+    # API Settings
+    API_HOST: str = "0.0.0.0"
+    API_PORT: int = 7777
+    API_TITLE: str = "Agent Control Plane"
+    API_VERSION: str = "0.1.0"
+    API_DESCRIPTION: str = "Multi-tenant agent orchestration with Temporal workflows"
+
+    # Supabase Settings (replaces DATABASE_URL for serverless)
+    SUPABASE_URL: str = ""  # Required: Set via environment variable
+    SUPABASE_ANON_KEY: Optional[str] = None
+    SUPABASE_SERVICE_KEY: str = ""  # Required: Set via environment variable for admin operations
+
+    # Legacy Database URL (kept for backward compatibility)
+    DATABASE_URL: Optional[str] = None
+
+    @model_validator(mode='after')
+    def set_database_url_fallback(self):
+        """Set DATABASE_URL from SUPABASE_POSTGRES_URL if not already set (for Vercel compatibility)"""
+        if not self.DATABASE_URL:
+            # Check for Vercel's SUPABASE_POSTGRES_URL or other variants
+            supabase_db_url = (
+                os.environ.get("SUPABASE_POSTGRES_URL") or
+                os.environ.get("SUPABASE_POSTGRES_PRISMA_URL") or
+                os.environ.get("SUPABASE_DB_URL")
+            )
+            if supabase_db_url:
+                # Fix URL format for SQLAlchemy 2.0+ (postgres:// -> postgresql://)
+                if supabase_db_url.startswith("postgres://"):
+                    supabase_db_url = supabase_db_url.replace("postgres://", "postgresql://", 1)
+                # Remove invalid Supabase pooler parameters that SQLAlchemy doesn't understand
+                supabase_db_url = supabase_db_url.replace("&supa=base-pooler.x", "")
+                self.DATABASE_URL = supabase_db_url
+        
+        # Also fix DATABASE_URL if it was already set with old postgres:// scheme
+        if self.DATABASE_URL and self.DATABASE_URL.startswith("postgres://"):
+            self.DATABASE_URL = self.DATABASE_URL.replace("postgres://", "postgresql://", 1)
+        
+        # Remove invalid Supabase pooler parameters from DATABASE_URL
+        if self.DATABASE_URL:
+            self.DATABASE_URL = self.DATABASE_URL.replace("&supa=base-pooler.x", "")
+        
+        return self
+
+    # Redis Settings (from Composer)
+    REDIS_URL: str = "redis://localhost:6379/0"
+    REDIS_HOST: Optional[str] = None
+    REDIS_PORT: int = 6379
+    REDIS_PASSWORD: Optional[str] = None
+    REDIS_DB: int = 0
+
+    # Temporal Settings
+    TEMPORAL_HOST: str = "localhost:7233"
+    TEMPORAL_NAMESPACE: str = "default"
+    TEMPORAL_CLIENT_CERT_PATH: Optional[str] = None
+    TEMPORAL_CLIENT_KEY_PATH: Optional[str] = None
+
+    # Security Settings
+    SECRET_KEY: str = "change-this-secret-key-in-production"
+    ALGORITHM: str = "HS256"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
+
+    # Logging
+    LOG_LEVEL: str = "info"
+
+    # CORS
+    CORS_ORIGINS: list[str] = ["*"]
+
+    # LiteLLM Settings
+    LITELLM_API_BASE: str = "https://llm-proxy.kubiya.ai"
+    LITELLM_API_KEY: str = ""  # Required: Set via environment variable
+    LITELLM_DEFAULT_MODEL: str = "kubiya/claude-sonnet-4"
+    LITELLM_TIMEOUT: int = 300
+
+    # Kubiya API Settings
+    KUBIYA_API_BASE: str = "https://api.kubiya.ai"
+
+    # Environment
+    ENVIRONMENT: str = "development"  # development, staging, production
+
+    class Config:
+        env_file = ".env"
+        case_sensitive = True
+        extra = "ignore"  # Allow extra environment variables (for worker-specific vars)
+
+
+settings = Settings()

control_plane_api/app/database.py

@@ -0,0 +1,135 @@
+from sqlalchemy import create_engine, event, text
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.pool import NullPool
+from control_plane_api.app.config import settings
+import structlog
+import os
+
+logger = structlog.get_logger()
+
+# Lazy-load engine and session to avoid crashing on import if DATABASE_URL not set
+_engine = None
+_SessionLocal = None
+
+# Create base class for models
+Base = declarative_base()
+
+# Detect if running in serverless environment
+# Only enable serverless mode in actual Vercel/Lambda, not in local development
+IS_SERVERLESS = bool(os.getenv("VERCEL") or os.getenv("AWS_LAMBDA_FUNCTION_NAME"))
+
+
+def get_engine():
+    """Get or create the database engine optimized for serverless"""
+    global _engine
+    if _engine is None:
+        if not settings.database_url:
+            raise RuntimeError(
+                "DATABASE_URL not configured. SQLAlchemy-based endpoints are not available. "
+                "Please use Supabase-based endpoints instead."
+            )
+
+        # Serverless-optimized configuration
+        if IS_SERVERLESS:
+            logger.info("creating_serverless_database_engine")
+            _engine = create_engine(
+                settings.database_url,
+                # Use NullPool for serverless - no connection pooling, create fresh connections
+                poolclass=NullPool,
+                # Verify connections are alive before using them
+                pool_pre_ping=True,
+                # Short connection timeout for serverless
+                connect_args={
+                    "connect_timeout": 5,
+                    "options": "-c statement_timeout=30000",  # 30s query timeout
+                    "keepalives": 1,
+                    "keepalives_idle": 30,
+                    "keepalives_interval": 10,
+                    "keepalives_count": 5,
+                }
+            )
+        else:
+            # Traditional server configuration with connection pooling
+            logger.info("creating_traditional_database_engine")
+            _engine = create_engine(
+                settings.database_url,
+                pool_pre_ping=True,
+                pool_size=2,  # Reduced for better resource management
+                max_overflow=3,  # Reduced overflow
+                pool_recycle=300,  # Recycle connections after 5 minutes
+                pool_timeout=10,  # Reduced timeout
+                connect_args={
+                    "connect_timeout": 10,
+                    "options": "-c statement_timeout=30000"
+                }
+            )
+
+        # Add connection event listeners for better debugging
+        @event.listens_for(_engine, "connect")
+        def receive_connect(dbapi_conn, connection_record):
+            logger.debug("database_connection_established")
+
+        @event.listens_for(_engine, "close")
+        def receive_close(dbapi_conn, connection_record):
+            logger.debug("database_connection_closed")
+
+        logger.info("database_engine_created", serverless=IS_SERVERLESS)
+    return _engine
+
+
+def get_session_local():
+    """Get or create the session factory"""
+    global _SessionLocal
+    if _SessionLocal is None:
+        _SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=get_engine())
+    return _SessionLocal
+
+
+def get_db():
+    """Dependency for getting database sessions"""
+    SessionLocal = get_session_local()
+    db = SessionLocal()
+    try:
+        yield db
+    except Exception:
+        # Rollback on any error during request processing
+        db.rollback()
+        raise
+    finally:
+        db.close()
+
+
+def dispose_engine():
+    """
+    Dispose of the database engine to release all connections.
+    Should be called at the end of serverless function invocations.
+    """
+    global _engine
+    if _engine is not None:
+        logger.info("disposing_database_engine")
+        _engine.dispose()
+        _engine = None
+
+
+def init_db():
+    """Initialize database tables"""
+    Base.metadata.create_all(bind=get_engine())
+
+
+def health_check_db():
+    """
+    Health check for database connectivity.
+    Returns True if database is accessible, False otherwise.
+    """
+    from sqlalchemy.exc import OperationalError, DisconnectionError
+
+    try:
+        engine = get_engine()
+        with engine.connect() as conn:
+            conn.execute(text("SELECT 1"))
+        logger.info("database_health_check_passed")
+        return True
+    except (OperationalError, DisconnectionError) as e:
+        logger.error("database_health_check_failed", error=str(e))
+        return False

control_plane_api/app/exceptions.py

@@ -0,0 +1,408 @@
+"""
+Centralized exception hierarchy for Control Plane API.
+
+Provides standardized exceptions with consistent error codes and status codes.
+"""
+
+from typing import Optional, Dict, Any
+from enum import Enum
+
+
+class ErrorCode(str, Enum):
+    """Standard error codes for API responses."""
+    
+    # Validation errors (400)
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+    INVALID_INPUT = "INVALID_INPUT"
+    MISSING_PARAMETER = "MISSING_PARAMETER"
+    INVALID_FORMAT = "INVALID_FORMAT"
+    
+    # Authentication/Authorization (401/403)
+    AUTHENTICATION_ERROR = "AUTHENTICATION_ERROR"
+    INVALID_CREDENTIALS = "INVALID_CREDENTIALS"
+    TOKEN_EXPIRED = "TOKEN_EXPIRED"
+    AUTHORIZATION_ERROR = "AUTHORIZATION_ERROR"
+    INSUFFICIENT_PERMISSIONS = "INSUFFICIENT_PERMISSIONS"
+    
+    # Resource errors (404/409)
+    RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND"
+    RESOURCE_ALREADY_EXISTS = "RESOURCE_ALREADY_EXISTS"
+    RESOURCE_CONFLICT = "RESOURCE_CONFLICT"
+    
+    # Rate limiting (429)
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"
+    
+    # External service errors (502/503)
+    EXTERNAL_SERVICE_ERROR = "EXTERNAL_SERVICE_ERROR"
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
+    TIMEOUT_ERROR = "TIMEOUT_ERROR"
+    
+    # Internal errors (500)
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+    DATABASE_ERROR = "DATABASE_ERROR"
+    WORKFLOW_ERROR = "WORKFLOW_ERROR"
+    CONFIGURATION_ERROR = "CONFIGURATION_ERROR"
+
+
+class ControlPlaneException(Exception):
+    """
+    Base exception for all Control Plane errors.
+    
+    Attributes:
+        message: Human-readable error message
+        error_code: Machine-readable error code
+        status_code: HTTP status code
+        details: Additional error details
+    """
+    
+    def __init__(
+        self,
+        message: str,
+        error_code: Optional[ErrorCode] = None,
+        status_code: int = 500,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.error_code = error_code or ErrorCode.INTERNAL_ERROR
+        self.status_code = status_code
+        self.details = details or {}
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert exception to dictionary for API response."""
+        return {
+            "code": self.error_code,
+            "message": self.message,
+            "details": self.details,
+        }
+
+
+# 400 - Bad Request Errors
+
+class ValidationError(ControlPlaneException):
+    """Raised when input validation fails."""
+    
+    def __init__(
+        self,
+        message: str,
+        field: Optional[str] = None,
+        value: Optional[Any] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        if field:
+            details = details or {}
+            details["field"] = field
+            if value is not None:
+                details["value"] = str(value)
+        
+        super().__init__(
+            message=message,
+            error_code=ErrorCode.VALIDATION_ERROR,
+            status_code=400,
+            details=details,
+        )
+
+
+class InvalidInputError(ControlPlaneException):
+    """Raised when input is invalid but passes basic validation."""
+    
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__(
+            message=message,
+            error_code=ErrorCode.INVALID_INPUT,
+            status_code=400,
+            details=details,
+        )
+
+
+# 401 - Authentication Errors
+
+class AuthenticationError(ControlPlaneException):
+    """Raised when authentication fails."""
+    
+    def __init__(self, message: str = "Authentication required"):
+        super().__init__(
+            message=message,
+            error_code=ErrorCode.AUTHENTICATION_ERROR,
+            status_code=401,
+        )
+
+
+class InvalidCredentialsError(ControlPlaneException):
+    """Raised when credentials are invalid."""
+    
+    def __init__(self, message: str = "Invalid credentials"):
+        super().__init__(
+            message=message,
+            error_code=ErrorCode.INVALID_CREDENTIALS,
+            status_code=401,
+        )
+
+
+class TokenExpiredError(ControlPlaneException):
+    """Raised when authentication token has expired."""
+    
+    def __init__(self, message: str = "Token has expired"):
+        super().__init__(
+            message=message,
+            error_code=ErrorCode.TOKEN_EXPIRED,
+            status_code=401,
+        )
+
+
+# 403 - Authorization Errors
+
+class AuthorizationError(ControlPlaneException):
+    """Raised when user lacks required permissions."""
+    
+    def __init__(
+        self,
+        message: str = "Insufficient permissions",
+        required_permission: Optional[str] = None,
+    ):
+        details = {}
+        if required_permission:
+            details["required_permission"] = required_permission
+        
+        super().__init__(
+            message=message,
+            error_code=ErrorCode.AUTHORIZATION_ERROR,
+            status_code=403,
+            details=details,
+        )
+
+
+# 404 - Not Found Errors
+
+class ResourceNotFoundError(ControlPlaneException):
+    """Raised when a requested resource doesn't exist."""
+    
+    def __init__(
+        self,
+        resource_type: str,
+        resource_id: str,
+        message: Optional[str] = None,
+    ):
+        if not message:
+            message = f"{resource_type} with ID '{resource_id}' not found"
+        
+        super().__init__(
+            message=message,
+            error_code=ErrorCode.RESOURCE_NOT_FOUND,
+            status_code=404,
+            details={
+                "resource_type": resource_type,
+                "resource_id": resource_id,
+            },
+        )
+
+
+# 409 - Conflict Errors
+
+class ResourceAlreadyExistsError(ControlPlaneException):
+    """Raised when attempting to create a resource that already exists."""
+    
+    def __init__(
+        self,
+        resource_type: str,
+        identifier: str,
+        message: Optional[str] = None,
+    ):
+        if not message:
+            message = f"{resource_type} already exists: {identifier}"
+        
+        super().__init__(
+            message=message,
+            error_code=ErrorCode.RESOURCE_ALREADY_EXISTS,
+            status_code=409,
+            details={
+                "resource_type": resource_type,
+                "identifier": identifier,
+            },
+        )
+
+
+class ResourceConflictError(ControlPlaneException):
+    """Raised when a resource operation conflicts with current state."""
+    
+    def __init__(
+        self,
+        message: str,
+        resource_type: Optional[str] = None,
+        resource_id: Optional[str] = None,
+    ):
+        details = {}
+        if resource_type:
+            details["resource_type"] = resource_type
+        if resource_id:
+            details["resource_id"] = resource_id
+        
+        super().__init__(
+            message=message,
+            error_code=ErrorCode.RESOURCE_CONFLICT,
+            status_code=409,
+            details=details,
+        )
+
+
+# 429 - Rate Limit Errors
+
+class RateLimitError(ControlPlaneException):
+    """Raised when rate limit is exceeded."""
+    
+    def __init__(
+        self,
+        limit: int,
+        window: str,
+        retry_after: Optional[int] = None,
+    ):
+        details = {
+            "limit": limit,
+            "window": window,
+        }
+        if retry_after:
+            details["retry_after_seconds"] = retry_after
+        
+        super().__init__(
+            message=f"Rate limit exceeded: {limit} requests per {window}",
+            error_code=ErrorCode.RATE_LIMIT_EXCEEDED,
+            status_code=429,
+            details=details,
+        )
+
+
+# 502/503 - Service Errors
+
+class ExternalServiceError(ControlPlaneException):
+    """Raised when an external service call fails."""
+    
+    def __init__(
+        self,
+        service: str,
+        message: str,
+        status_code: int = 502,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        full_details = {"service": service}
+        if details:
+            full_details.update(details)
+        
+        super().__init__(
+            message=f"{service}: {message}",
+            error_code=ErrorCode.EXTERNAL_SERVICE_ERROR,
+            status_code=status_code,
+            details=full_details,
+        )
+
+
+class ServiceUnavailableError(ControlPlaneException):
+    """Raised when a service is temporarily unavailable."""
+    
+    def __init__(
+        self,
+        service: str,
+        message: Optional[str] = None,
+        retry_after: Optional[int] = None,
+    ):
+        if not message:
+            message = f"{service} is temporarily unavailable"
+        
+        details = {"service": service}
+        if retry_after:
+            details["retry_after_seconds"] = retry_after
+        
+        super().__init__(
+            message=message,
+            error_code=ErrorCode.SERVICE_UNAVAILABLE,
+            status_code=503,
+            details=details,
+        )
+
+
+class TimeoutError(ControlPlaneException):
+    """Raised when an operation times out."""
+    
+    def __init__(
+        self,
+        operation: str,
+        timeout_seconds: Optional[float] = None,
+    ):
+        details = {"operation": operation}
+        if timeout_seconds:
+            details["timeout_seconds"] = timeout_seconds
+        
+        super().__init__(
+            message=f"Operation '{operation}' timed out",
+            error_code=ErrorCode.TIMEOUT_ERROR,
+            status_code=504,
+            details=details,
+        )
+
+
+# 500 - Internal Errors
+
+class DatabaseError(ControlPlaneException):
+    """Raised when a database operation fails."""
+    
+    def __init__(
+        self,
+        message: str,
+        operation: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        full_details = details or {}
+        if operation:
+            full_details["operation"] = operation
+        
+        super().__init__(
+            message=message,
+            error_code=ErrorCode.DATABASE_ERROR,
+            status_code=500,
+            details=full_details,
+        )
+
+
+class WorkflowExecutionError(ControlPlaneException):
+    """Raised when a Temporal workflow execution fails."""
+    
+    def __init__(
+        self,
+        workflow_id: str,
+        message: str,
+        workflow_type: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        full_details = {
+            "workflow_id": workflow_id,
+        }
+        if workflow_type:
+            full_details["workflow_type"] = workflow_type
+        if details:
+            full_details.update(details)
+        
+        super().__init__(
+            message=f"Workflow {workflow_id}: {message}",
+            error_code=ErrorCode.WORKFLOW_ERROR,
+            status_code=500,
+            details=full_details,
+        )
+
+
+class ConfigurationError(ControlPlaneException):
+    """Raised when configuration is invalid or missing."""
+    
+    def __init__(
+        self,
+        message: str,
+        config_key: Optional[str] = None,
+    ):
+        details = {}
+        if config_key:
+            details["config_key"] = config_key
+        
+        super().__init__(
+            message=message,
+            error_code=ErrorCode.CONFIGURATION_ERROR,
+            status_code=500,
+            details=details,
+        )

control_plane_api/app/lib/__init__.py

@@ -0,0 +1,11 @@
+"""Shared library modules"""
+
+from control_plane_api.app.lib.supabase import get_supabase, execute_with_org_context
+from control_plane_api.app.lib.temporal_client import get_temporal_client, close_temporal_client
+
+__all__ = [
+    "get_supabase",
+    "execute_with_org_context",
+    "get_temporal_client",
+    "close_temporal_client",
+]