kubiya-control-plane-api 0.9.15__py3-none-any.whl

control_plane_api/app/schemas/job_schemas.py

@@ -0,0 +1,302 @@
+"""
+Pydantic schemas for Jobs API.
+
+This module defines request/response schemas for the Jobs CRUD API.
+"""
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+from typing import Optional, Dict, List, Any
+from datetime import datetime
+from croniter import croniter
+
+
+class ExecutionEnvironment(BaseModel):
+    """Execution environment configuration for jobs"""
+    env_vars: Dict[str, str] = Field(default_factory=dict, description="Environment variables (key-value pairs)")
+    secrets: List[str] = Field(default_factory=list, description="Secret names from Kubiya vault")
+    integration_ids: List[str] = Field(default_factory=list, description="Integration UUIDs for delegated credentials")
+    mcp_servers: Dict[str, Dict] = Field(
+        default_factory=dict,
+        description="MCP (Model Context Protocol) server configurations. Supports stdio, HTTP, and SSE transports."
+    )
+
+
+class JobCreate(BaseModel):
+    """Schema for creating a new job"""
+    name: str = Field(..., description="Job name", min_length=1, max_length=255)
+    description: Optional[str] = Field(None, description="Job description")
+    enabled: bool = Field(True, description="Whether the job is enabled")
+
+    # Trigger configuration
+    trigger_type: str = Field(..., description="Trigger type: 'cron', 'webhook', or 'manual'")
+
+    # Cron configuration (required if trigger_type is 'cron')
+    cron_schedule: Optional[str] = Field(None, description="Cron expression (e.g., '0 17 * * *' for daily at 5pm)")
+    cron_timezone: Optional[str] = Field("UTC", description="Timezone for cron schedule (e.g., 'America/New_York')")
+
+    # Planning and execution configuration
+    planning_mode: str = Field(
+        default="predefined_agent",
+        description="Planning mode: 'on_the_fly', 'predefined_agent', 'predefined_team', or 'predefined_workflow'"
+    )
+
+    # Entity to execute (required for predefined modes)
+    entity_type: Optional[str] = Field(None, description="Entity type: 'agent', 'team', or 'workflow'")
+    entity_id: Optional[str] = Field(None, description="Entity ID (agent_id, team_id, or workflow_id)")
+
+    # Prompt configuration
+    prompt_template: str = Field(..., description="Prompt template (can include {{variables}} for dynamic params)")
+    system_prompt: Optional[str] = Field(None, description="Optional system prompt")
+
+    # Executor routing configuration
+    executor_type: str = Field(
+        default="auto",
+        description="Executor routing: 'auto', 'specific_queue', or 'environment'"
+    )
+    worker_queue_name: Optional[str] = Field(None, description="Worker queue name for 'specific_queue' executor type")
+    environment_name: Optional[str] = Field(None, description="Environment name for 'environment' executor type")
+
+    # Execution configuration
+    config: Dict[str, Any] = Field(default_factory=dict, description="Additional execution config (timeout, retry, etc.)")
+    execution_environment: Optional[ExecutionEnvironment] = Field(
+        None,
+        description="Execution environment: env vars, secrets, integrations"
+    )
+
+    @field_validator("trigger_type")
+    @classmethod
+    def validate_trigger_type(cls, v):
+        valid_types = ["cron", "webhook", "manual"]
+        if v not in valid_types:
+            raise ValueError(f"trigger_type must be one of {valid_types}")
+        return v
+
+    @field_validator("planning_mode")
+    @classmethod
+    def validate_planning_mode(cls, v):
+        valid_modes = ["on_the_fly", "predefined_agent", "predefined_team", "predefined_workflow"]
+        if v not in valid_modes:
+            raise ValueError(f"planning_mode must be one of {valid_modes}")
+        return v
+
+    @field_validator("executor_type")
+    @classmethod
+    def validate_executor_type(cls, v):
+        valid_types = ["auto", "specific_queue", "environment"]
+        if v not in valid_types:
+            raise ValueError(f"executor_type must be one of {valid_types}")
+        return v
+
+    @field_validator("cron_schedule")
+    @classmethod
+    def validate_cron_schedule(cls, v):
+        if v is not None:
+            # Validate cron expression
+            try:
+                croniter(v)
+            except Exception as e:
+                raise ValueError(f"Invalid cron expression: {str(e)}")
+        return v
+
+    @model_validator(mode='after')
+    def validate_cross_field_dependencies(self):
+        # Validate cron_schedule required for cron trigger
+        if self.trigger_type == "cron" and not self.cron_schedule:
+            raise ValueError("cron_schedule is required when trigger_type is 'cron'")
+
+        # Validate entity_id required for predefined modes
+        if self.planning_mode in ["predefined_agent", "predefined_team", "predefined_workflow"] and not self.entity_id:
+            raise ValueError(f"entity_id is required when planning_mode is '{self.planning_mode}'")
+
+        # Validate worker_queue_name for specific_queue executor
+        if self.executor_type == "specific_queue" and not self.worker_queue_name:
+            raise ValueError("worker_queue_name is required when executor_type is 'specific_queue'")
+
+        # Validate environment_name for environment executor
+        if self.executor_type == "environment" and not self.environment_name:
+            raise ValueError("environment_name is required when executor_type is 'environment'")
+
+        return self
+
+
+class JobUpdate(BaseModel):
+    """Schema for updating an existing job"""
+    name: Optional[str] = Field(None, min_length=1, max_length=255)
+    description: Optional[str] = None
+    enabled: Optional[bool] = None
+
+    # Trigger configuration
+    trigger_type: Optional[str] = None
+    cron_schedule: Optional[str] = None
+    cron_timezone: Optional[str] = None
+
+    # Planning and execution configuration
+    planning_mode: Optional[str] = None
+    entity_type: Optional[str] = None
+    entity_id: Optional[str] = None
+
+    # Prompt configuration
+    prompt_template: Optional[str] = None
+    system_prompt: Optional[str] = None
+
+    # Executor routing configuration
+    executor_type: Optional[str] = None
+    worker_queue_name: Optional[str] = None
+    environment_name: Optional[str] = None
+
+    # Execution configuration
+    config: Optional[Dict[str, Any]] = None
+    execution_environment: Optional[ExecutionEnvironment] = None
+
+    @field_validator("trigger_type")
+    @classmethod
+    def validate_trigger_type(cls, v):
+        if v is not None:
+            valid_types = ["cron", "webhook", "manual"]
+            if v not in valid_types:
+                raise ValueError(f"trigger_type must be one of {valid_types}")
+        return v
+
+    @field_validator("planning_mode")
+    @classmethod
+    def validate_planning_mode(cls, v):
+        if v is not None:
+            valid_modes = ["on_the_fly", "predefined_agent", "predefined_team", "predefined_workflow"]
+            if v not in valid_modes:
+                raise ValueError(f"planning_mode must be one of {valid_modes}")
+        return v
+
+    @field_validator("executor_type")
+    @classmethod
+    def validate_executor_type(cls, v):
+        if v is not None:
+            valid_types = ["auto", "specific_queue", "environment"]
+            if v not in valid_types:
+                raise ValueError(f"executor_type must be one of {valid_types}")
+        return v
+
+    @field_validator("cron_schedule")
+    @classmethod
+    def validate_cron_schedule(cls, v):
+        if v is not None:
+            try:
+                croniter(v)
+            except Exception as e:
+                raise ValueError(f"Invalid cron expression: {str(e)}")
+        return v
+
+
+class JobResponse(BaseModel):
+    """Schema for job response"""
+    id: str
+    organization_id: str
+    name: str
+    description: Optional[str]
+    enabled: bool
+    status: str
+
+    # Trigger configuration
+    trigger_type: str
+    cron_schedule: Optional[str]
+    cron_timezone: Optional[str]
+    webhook_url: Optional[str] = Field(None, description="Full webhook URL (generated from webhook_url_path)")
+    webhook_secret: Optional[str] = Field(None, description="Webhook HMAC secret for signature verification")
+    temporal_schedule_id: Optional[str]
+
+    # Planning and execution configuration
+    planning_mode: str
+    entity_type: Optional[str]
+    entity_id: Optional[str]
+    entity_name: Optional[str]
+
+    # Prompt configuration
+    prompt_template: str
+    system_prompt: Optional[str]
+
+    # Executor routing configuration
+    executor_type: str
+    worker_queue_name: Optional[str]
+    environment_name: Optional[str]
+
+    # Execution configuration
+    config: Dict[str, Any]
+    execution_environment: Optional[ExecutionEnvironment]
+
+    # Execution tracking
+    last_execution_id: Optional[str]
+    last_execution_at: Optional[datetime]
+    next_execution_at: Optional[datetime]
+    total_executions: int
+    successful_executions: int
+    failed_executions: int
+    execution_history: List[Dict[str, Any]]
+
+    # Audit fields
+    created_by: Optional[str]
+    updated_by: Optional[str]
+    created_by_email: Optional[str] = Field(None, description="Email of the user who created the job (enriched)")
+    updated_by_email: Optional[str] = Field(None, description="Email of the user who last updated the job (enriched)")
+
+    # Timestamps
+    created_at: datetime
+    updated_at: datetime
+    last_triggered_at: Optional[datetime]
+
+    class Config:
+        from_attributes = True
+
+
+class JobTriggerRequest(BaseModel):
+    """Schema for manually triggering a job"""
+    parameters: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Parameters to substitute in prompt template (e.g., {{param_name}})"
+    )
+    config_override: Optional[Dict[str, Any]] = Field(
+        None,
+        description="Optional config overrides for this execution"
+    )
+
+
+class JobTriggerResponse(BaseModel):
+    """Schema for job trigger response"""
+    job_id: str
+    execution_id: str
+    workflow_id: str
+    status: str
+    message: str
+
+
+class JobExecutionHistoryItem(BaseModel):
+    """Schema for a single job execution history item"""
+    execution_id: str
+    trigger_type: str
+    status: str
+    started_at: Optional[datetime]
+    completed_at: Optional[datetime]
+    duration_ms: Optional[int]
+    error_message: Optional[str]
+    trigger_metadata: Optional[Dict[str, Any]] = None
+
+
+class JobExecutionHistoryResponse(BaseModel):
+    """Schema for job execution history response"""
+    job_id: str
+    total_count: int
+    executions: List[JobExecutionHistoryItem]
+
+
+class WebhookPayload(BaseModel):
+    """Schema for webhook trigger payload"""
+    parameters: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Parameters to substitute in prompt template"
+    )
+    config_override: Optional[Dict[str, Any]] = Field(
+        None,
+        description="Optional config overrides for this execution"
+    )
+    metadata: Optional[Dict[str, Any]] = Field(
+        None,
+        description="Additional metadata for this webhook trigger"
+    )

control_plane_api/app/schemas/mcp_schemas.py

@@ -0,0 +1,311 @@
+"""
+Pydantic schemas for MCP (Model Context Protocol) server configurations.
+
+Supports multiple transport types:
+- stdio: External process communication via stdin/stdout
+- http: HTTP-based communication
+- sse: Server-Sent Events communication
+
+All string fields support template syntax for dynamic value resolution.
+"""
+
+from pydantic import BaseModel, Field, field_validator, model_validator, ConfigDict
+from typing import Dict, List, Literal, Optional, Union, Any
+from enum import Enum
+
+
+class MCPTransportType(str, Enum):
+    """MCP server transport types."""
+    STDIO = "stdio"
+    HTTP = "http"
+    SSE = "sse"
+
+
+class MCPServerStdioConfig(BaseModel):
+    """
+    Configuration for stdio-based MCP servers.
+
+    Stdio servers run as external processes and communicate via stdin/stdout.
+    Commonly used for local tools and CLI-based MCP servers.
+
+    All string fields support template syntax:
+    - {{variable}} - Simple variables
+    - {{.secret.name}} - Secrets from vault
+    - {{.env.VAR}} - Environment variables
+
+    Example:
+        {
+            "command": "python",
+            "args": ["-m", "mcp_server_filesystem"],
+            "env": {
+                "ALLOWED_PATHS": "{{.env.PROJECT_ROOT}}",
+                "API_KEY": "{{.secret.filesystem_key}}"
+            }
+        }
+    """
+    command: str = Field(
+        ...,
+        description="Command to execute (supports templates)",
+        min_length=1,
+        examples=["python", "node", "npx", "/usr/local/bin/mcp-server"]
+    )
+    args: List[str] = Field(
+        default_factory=list,
+        description="Command arguments (each arg supports templates)",
+        examples=[
+            ["-m", "mcp_server_filesystem"],
+            ["@modelcontextprotocol/server-filesystem", "{{.env.ROOT_PATH}}"]
+        ]
+    )
+    env: Dict[str, str] = Field(
+        default_factory=dict,
+        description="Environment variables (values support templates)",
+        examples=[
+            {"ALLOWED_PATHS": "/home/user/projects", "DEBUG": "{{.env.DEBUG_MODE}}"}
+        ]
+    )
+
+    @field_validator('command')
+    @classmethod
+    def validate_command(cls, v: str) -> str:
+        """Validate command is not empty after stripping."""
+        if not v.strip():
+            raise ValueError("Command cannot be empty or whitespace only")
+        return v.strip()
+
+    @field_validator('args')
+    @classmethod
+    def validate_args(cls, v: List[str]) -> List[str]:
+        """Validate args list doesn't contain empty strings."""
+        if any(not arg.strip() for arg in v):
+            raise ValueError("Arguments cannot contain empty or whitespace-only strings")
+        return [arg.strip() for arg in v]
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "command": "python",
+                "args": ["-m", "mcp_server_filesystem"],
+                "env": {
+                    "ALLOWED_PATHS": "{{.env.PROJECT_ROOT}}",
+                    "LOG_LEVEL": "info"
+                }
+            }
+        }
+    )
+
+
+class MCPServerHTTPConfig(BaseModel):
+    """
+    Configuration for HTTP/SSE-based MCP servers.
+
+    HTTP servers communicate over network using HTTP protocol or Server-Sent Events.
+    Useful for remote MCP servers and cloud-hosted tools.
+
+    All string fields support template syntax:
+    - {{variable}} - Simple variables
+    - {{.secret.name}} - Secrets from vault
+    - {{.env.VAR}} - Environment variables
+
+    Example:
+        {
+            "type": "sse",
+            "url": "https://{{.env.API_HOST}}/mcp/sse",
+            "headers": {
+                "Authorization": "Bearer {{.secret.api_token}}",
+                "X-API-Key": "{{.secret.api_key}}"
+            }
+        }
+    """
+    type: Literal["http", "sse"] = Field(
+        ...,
+        description="Transport type: 'http' for HTTP or 'sse' for Server-Sent Events"
+    )
+    url: str = Field(
+        ...,
+        description="Server URL (supports templates)",
+        min_length=1,
+        examples=[
+            "https://api.example.com/mcp",
+            "https://{{.env.MCP_HOST}}/sse",
+            "http://localhost:{{.env.MCP_PORT}}/mcp"
+        ]
+    )
+    headers: Dict[str, str] = Field(
+        default_factory=dict,
+        description="HTTP headers (values support templates)",
+        examples=[
+            {
+                "Authorization": "Bearer {{.secret.mcp_token}}",
+                "X-API-Key": "{{.secret.api_key}}",
+                "Content-Type": "application/json"
+            }
+        ]
+    )
+
+    @field_validator('url')
+    @classmethod
+    def validate_url(cls, v: str) -> str:
+        """Validate URL format (basic check, templates make full validation impossible)."""
+        v = v.strip()
+        if not v:
+            raise ValueError("URL cannot be empty")
+
+        # Basic sanity check - should start with http:// or https:// or contain template
+        if not (v.startswith(('http://', 'https://')) or '{{' in v):
+            raise ValueError("URL must start with http:// or https://, or contain templates")
+
+        return v
+
+    @field_validator('headers')
+    @classmethod
+    def validate_headers(cls, v: Dict[str, str]) -> Dict[str, str]:
+        """Validate headers don't have empty keys or values."""
+        for key, value in v.items():
+            if not key.strip():
+                raise ValueError("Header keys cannot be empty")
+            if not value.strip():
+                raise ValueError(f"Header value for '{key}' cannot be empty")
+        return v
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "type": "sse",
+                "url": "https://api.example.com/mcp/sse",
+                "headers": {
+                    "Authorization": "Bearer {{.secret.mcp_token}}",
+                    "X-Organization": "{{.env.ORG_ID}}"
+                }
+            }
+        }
+    )
+
+
+class MCPServerConfig(BaseModel):
+    """
+    Unified MCP server configuration supporting multiple transport types.
+
+    This schema uses discriminated union based on the presence of 'command' or 'type' field:
+    - If 'command' is present: stdio transport
+    - If 'type' is present: HTTP/SSE transport
+
+    The configuration is validated to ensure only one transport type is specified.
+    """
+    # Fields from stdio config
+    command: Optional[str] = Field(
+        None,
+        description="Command for stdio transport (mutually exclusive with url/type)"
+    )
+    args: Optional[List[str]] = Field(
+        None,
+        description="Arguments for stdio transport"
+    )
+    env: Optional[Dict[str, str]] = Field(
+        None,
+        description="Environment variables (used by both stdio and HTTP transports)"
+    )
+
+    # Fields from HTTP/SSE config
+    type: Optional[Literal["http", "sse"]] = Field(
+        None,
+        description="Transport type for HTTP/SSE (mutually exclusive with command)",
+        alias="transport_type"  # Support both 'type' and 'transport_type' for backward compatibility
+    )
+    url: Optional[str] = Field(
+        None,
+        description="URL for HTTP/SSE transport (mutually exclusive with command)"
+    )
+    headers: Optional[Dict[str, str]] = Field(
+        None,
+        description="HTTP headers for HTTP/SSE transport"
+    )
+
+    @model_validator(mode='after')
+    def validate_transport_type(self):
+        """Validate that exactly one transport type is configured."""
+        has_stdio = self.command is not None
+        has_http = self.type is not None or self.url is not None
+
+        if not has_stdio and not has_http:
+            raise ValueError(
+                "MCP server config must specify either 'command' (stdio) or 'type'/'url' (HTTP/SSE)"
+            )
+
+        if has_stdio and has_http:
+            raise ValueError(
+                "MCP server config cannot specify both stdio (command) and HTTP/SSE (type/url) transport"
+            )
+
+        # Validate stdio config
+        if has_stdio:
+            if not self.command.strip():
+                raise ValueError("Command cannot be empty for stdio transport")
+
+        # Validate HTTP/SSE config
+        if has_http:
+            if not self.type:
+                raise ValueError("'type' field is required for HTTP/SSE transport")
+            if not self.url:
+                raise ValueError("'url' field is required for HTTP/SSE transport")
+            if not self.url.strip():
+                raise ValueError("URL cannot be empty for HTTP/SSE transport")
+
+        return self
+
+    def get_transport_type(self) -> MCPTransportType:
+        """Get the transport type of this configuration."""
+        if self.command:
+            return MCPTransportType.STDIO
+        elif self.type == "sse":
+            return MCPTransportType.SSE
+        elif self.type == "http":
+            return MCPTransportType.HTTP
+        else:
+            raise ValueError("Invalid MCP server configuration")
+
+    def to_stdio_config(self) -> Optional[MCPServerStdioConfig]:
+        """Convert to stdio config if applicable."""
+        if self.command:
+            return MCPServerStdioConfig(
+                command=self.command,
+                args=self.args or [],
+                env=self.env or {}
+            )
+        return None
+
+    def to_http_config(self) -> Optional[MCPServerHTTPConfig]:
+        """Convert to HTTP/SSE config if applicable."""
+        if self.type and self.url:
+            return MCPServerHTTPConfig(
+                type=self.type,
+                url=self.url,
+                headers=self.headers or {}
+            )
+        return None
+
+    model_config = ConfigDict(
+        populate_by_name=True,  # Allow populating by both field name and alias
+        json_schema_extra={
+            "examples": [
+                {
+                    "command": "python",
+                    "args": ["-m", "mcp_server_filesystem"],
+                    "env": {"ALLOWED_PATHS": "{{.env.PROJECT_ROOT}}"}
+                },
+                {
+                    "type": "sse",
+                    "url": "https://api.example.com/mcp",
+                    "headers": {"Authorization": "Bearer {{.secret.token}}"}
+                },
+                {
+                    "transport_type": "sse",  # Also supports 'transport_type'
+                    "url": "https://api.example.com/mcp",
+                    "headers": {"Authorization": "Bearer {{.secret.token}}"}
+                }
+            ]
+        }
+    )
+
+# NOTE: MCPServersConfig was removed as it's not used anywhere and had Pydantic v2 compatibility issues.
+# MCP servers are stored as Dict[str, Any] in execution_environment.mcp_servers