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

control_plane_api/app/models/execution.py

@@ -0,0 +1,93 @@
+from sqlalchemy import Column, String, DateTime, Text, JSON, Enum as SQLEnum, ForeignKey
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+from datetime import datetime
+import uuid
+import enum
+
+from control_plane_api.app.database import Base
+
+
+class ExecutionStatus(str, enum.Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    WAITING_FOR_INPUT = "waiting_for_input"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class ExecutionType(str, enum.Enum):
+    AGENT = "agent"
+    TEAM = "team"
+    WORKFLOW = "workflow"
+
+
+class ExecutionTriggerSource(str, enum.Enum):
+    """How the execution was triggered"""
+    USER = "user"  # Triggered by a user directly via UI/API
+    JOB_CRON = "job_cron"  # Triggered by a scheduled job (cron)
+    JOB_WEBHOOK = "job_webhook"  # Triggered by a webhook job
+    JOB_MANUAL = "job_manual"  # Triggered manually through job trigger API
+    SYSTEM = "system"  # Triggered by system/automation
+    API = "api"  # Triggered directly via API
+    CHAT = "chat"  # Triggered from chat interface
+
+
+class Execution(Base):
+    """Model for tracking agent/team/workflow executions with user attribution"""
+
+    __tablename__ = "executions"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+
+    # Organization
+    organization_id = Column(String, nullable=False, index=True)
+
+    # What is being executed
+    execution_type = Column(SQLEnum(ExecutionType, values_callable=lambda x: [e.value for e in x]), nullable=False)
+    entity_id = Column(String, nullable=False)  # agent_id, team_id, or workflow_id
+    entity_name = Column(String)  # Cached name for display
+    runner_name = Column(String, nullable=True)  # Cached runner name for filtering
+
+    # User attribution - who initiated this execution
+    user_id = Column(String, nullable=True, index=True)
+    user_email = Column(String, nullable=True)
+    user_name = Column(String, nullable=True)
+    user_avatar = Column(String, nullable=True)
+
+    # Trigger source - how this execution was initiated
+    trigger_source = Column(
+        SQLEnum(ExecutionTriggerSource, values_callable=lambda x: [e.value for e in x]),
+        default=ExecutionTriggerSource.USER,
+        nullable=False,
+        index=True
+    )
+    trigger_metadata = Column(JSON, default={})  # Additional context about the trigger (job_id, webhook payload, etc.)
+
+    # Execution details
+    prompt = Column(Text, nullable=False)
+    system_prompt = Column(Text, nullable=True)
+    config = Column(JSON, default={})
+
+    # Status and results
+    status = Column(SQLEnum(ExecutionStatus, values_callable=lambda x: [e.value for e in x]), default=ExecutionStatus.PENDING, nullable=False)
+    response = Column(Text, nullable=True)
+    error_message = Column(Text, nullable=True)
+
+    # Metadata
+    usage = Column(JSON, default={})  # Token usage, cost, etc.
+    execution_metadata = Column(JSON, default={})  # Additional metadata
+
+    # Timestamps
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    started_at = Column(DateTime(timezone=True), nullable=True)
+    completed_at = Column(DateTime(timezone=True), nullable=True)
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False)
+
+    # Relationships
+    participants = relationship("ExecutionParticipant", back_populates="execution", cascade="all, delete-orphan", lazy="selectin")
+
+    def __repr__(self):
+        return f"<Execution {self.id} ({self.execution_type}:{self.entity_id}) - {self.status} by {self.user_email}>"

control_plane_api/app/models/job.py

@@ -0,0 +1,179 @@
+from sqlalchemy import Column, String, DateTime, Text, JSON, Enum as SQLEnum, Boolean, ForeignKey, Integer
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+from datetime import datetime
+import uuid
+import enum
+
+from control_plane_api.app.database import Base
+
+
+class JobStatus(str, enum.Enum):
+    """Job status enumeration"""
+    ACTIVE = "active"
+    PAUSED = "paused"
+    FAILED = "failed"
+    DISABLED = "disabled"
+
+
+class JobTriggerType(str, enum.Enum):
+    """Job trigger type enumeration"""
+    CRON = "cron"
+    WEBHOOK = "webhook"
+    MANUAL = "manual"
+
+
+class ExecutorType(str, enum.Enum):
+    """Job executor routing type"""
+    AUTO = "auto"  # First available worker queue with active workers
+    SPECIFIC_QUEUE = "specific_queue"  # Explicit worker queue selection
+    ENVIRONMENT = "environment"  # Route to specific environment
+
+
+class PlanningMode(str, enum.Enum):
+    """Planning mode for job execution"""
+    ON_THE_FLY = "on_the_fly"  # Use planner to determine execution
+    PREDEFINED_AGENT = "predefined_agent"  # Execute specific agent
+    PREDEFINED_TEAM = "predefined_team"  # Execute specific team
+    PREDEFINED_WORKFLOW = "predefined_workflow"  # Execute specific workflow
+
+
+class Job(Base):
+    """
+    Model for scheduled and webhook-triggered jobs.
+
+    Jobs can be triggered via:
+    - Cron schedule (using Temporal Schedules)
+    - Webhook URL (with HMAC signature verification)
+    - Manual API trigger
+
+    Jobs execute agents, teams, or workflows with configurable routing.
+    """
+
+    __tablename__ = "jobs"
+
+    id = Column(String, primary_key=True, default=lambda: f"job_{uuid.uuid4()}")
+
+    # Organization (multi-tenant isolation)
+    organization_id = Column(String, nullable=False, index=True)
+
+    # Job metadata
+    name = Column(String, nullable=False, index=True)
+    description = Column(Text, nullable=True)
+    enabled = Column(Boolean, default=True, nullable=False, index=True)
+    status = Column(
+        SQLEnum(JobStatus, values_callable=lambda x: [e.value for e in x]),
+        default=JobStatus.ACTIVE,
+        nullable=False,
+        index=True
+    )
+
+    # Trigger configuration
+    trigger_type = Column(
+        SQLEnum(JobTriggerType, values_callable=lambda x: [e.value for e in x]),
+        nullable=False,
+        index=True
+    )
+
+    # Cron configuration (for CRON trigger type)
+    cron_schedule = Column(String, nullable=True)  # e.g., "0 17 * * *" (daily at 5pm)
+    cron_timezone = Column(String, default="UTC", nullable=True)  # e.g., "America/New_York"
+
+    # Webhook configuration (for WEBHOOK trigger type)
+    webhook_url_path = Column(String, nullable=True, unique=True, index=True)  # e.g., "/api/v1/jobs/webhook/abc123"
+    webhook_secret = Column(String, nullable=True)  # HMAC secret for signature verification
+
+    # Temporal Schedule ID (managed by system)
+    temporal_schedule_id = Column(String, nullable=True, unique=True, index=True)
+
+    # Planning and execution configuration
+    planning_mode = Column(
+        SQLEnum(PlanningMode, values_callable=lambda x: [e.value for e in x]),
+        default=PlanningMode.PREDEFINED_AGENT,
+        nullable=False
+    )
+
+    # Entity to execute (based on planning_mode)
+    entity_type = Column(String, nullable=True)  # "agent", "team", "workflow" (for predefined modes)
+    entity_id = Column(String, nullable=True)  # agent_id, team_id, or workflow_id
+    entity_name = Column(String, nullable=True)  # Cached name for display
+
+    # Prompt configuration
+    prompt_template = Column(Text, nullable=False)  # Can include {{variables}} for dynamic params
+    system_prompt = Column(Text, nullable=True)
+
+    # Executor routing configuration
+    executor_type = Column(
+        SQLEnum(ExecutorType, values_callable=lambda x: [e.value for e in x]),
+        default=ExecutorType.AUTO,
+        nullable=False
+    )
+    worker_queue_name = Column(String, nullable=True)  # For SPECIFIC_QUEUE executor type
+    environment_name = Column(String, nullable=True)  # For ENVIRONMENT executor type
+
+    # Execution configuration
+    config = Column(JSON, default={})  # Additional execution config (timeout, retry, etc.)
+    execution_environment = Column(JSON, default={})  # Environment variables, secrets, etc.
+
+    # Execution tracking
+    last_execution_id = Column(UUID(as_uuid=True), ForeignKey("executions.id", ondelete="SET NULL"), nullable=True)
+    last_execution_at = Column(DateTime(timezone=True), nullable=True)
+    next_execution_at = Column(DateTime(timezone=True), nullable=True)  # For cron jobs
+    total_executions = Column(Integer, default=0, nullable=False)  # Total number of executions
+    successful_executions = Column(Integer, default=0, nullable=False)  # Number of successful executions
+    failed_executions = Column(Integer, default=0, nullable=False)  # Number of failed executions
+
+    # Execution history (last N runs)
+    execution_history = Column(JSON, default=list)  # List of recent execution summaries
+
+    # Audit fields
+    created_by = Column(String, nullable=True)  # User ID who created the job
+    updated_by = Column(String, nullable=True)  # User ID who last updated the job
+
+    # Timestamps
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False)
+    last_triggered_at = Column(DateTime(timezone=True), nullable=True)  # Last time job was triggered (manual or scheduled)
+
+    # Relationships
+    last_execution = relationship("Execution", foreign_keys=[last_execution_id], lazy="select")
+
+    def __repr__(self):
+        return f"<Job {self.id} ({self.name}) - {self.trigger_type}:{self.status}>"
+
+
+class JobExecution(Base):
+    """
+    Junction table linking Jobs to Executions.
+    Tracks which executions were triggered by which jobs.
+    """
+
+    __tablename__ = "job_executions"
+
+    id = Column(String, primary_key=True, default=lambda: f"jobexec_{uuid.uuid4()}")
+
+    # Foreign keys
+    job_id = Column(String, ForeignKey("jobs.id", ondelete="CASCADE"), nullable=False, index=True)
+    execution_id = Column(UUID(as_uuid=True), ForeignKey("executions.id", ondelete="CASCADE"), nullable=False, index=True)
+
+    # Organization (for efficient querying)
+    organization_id = Column(String, nullable=False, index=True)
+
+    # Trigger context
+    trigger_type = Column(String, nullable=False)  # "cron", "webhook", "manual"
+    trigger_metadata = Column(JSON, default={})  # Additional context (webhook payload, manual trigger user, etc.)
+
+    # Execution outcome (denormalized for quick queries)
+    execution_status = Column(String, nullable=True)  # Cached from execution.status
+    execution_duration_ms = Column(Integer, nullable=True)  # Duration in milliseconds
+
+    # Timestamps
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+
+    # Relationships
+    job = relationship("Job", foreign_keys=[job_id], lazy="select")
+    execution = relationship("Execution", foreign_keys=[execution_id], lazy="select")
+
+    def __repr__(self):
+        return f"<JobExecution job={self.job_id} execution={self.execution_id}>"

control_plane_api/app/models/llm_model.py

@@ -0,0 +1,75 @@
+"""LLM Model database model"""
+from sqlalchemy import Column, String, Boolean, Text, JSON, Integer
+from datetime import datetime
+from sqlalchemy import DateTime
+import uuid as uuid_module
+
+from control_plane_api.app.database import Base
+
+
+class LLMModel(Base):
+    """
+    LLM Model configuration for agent execution.
+
+    Stores available LLM models that can be used by agents and teams,
+    including provider information, compatibility, and UI metadata.
+    """
+
+    __tablename__ = "llm_models"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid_module.uuid4()))
+
+    # Model identification
+    value = Column(String, unique=True, nullable=False, index=True)
+    label = Column(String, nullable=False)
+    provider = Column(String, nullable=False, index=True)
+
+    # UI metadata
+    logo = Column(String, nullable=True)
+    description = Column(Text, nullable=True)
+
+    # Status and flags
+    enabled = Column(Boolean, default=True, nullable=False, index=True)
+    recommended = Column(Boolean, default=False, nullable=False)
+
+    # Runtime compatibility
+    # Store list of compatible runtime types (e.g., ["default", "claude_code"])
+    compatible_runtimes = Column(JSON, default=list, nullable=False)
+
+    # Model capabilities and metadata
+    capabilities = Column(JSON, default=dict, nullable=False)
+    # Example: {"vision": true, "function_calling": true, "max_tokens": 4096}
+
+    # Pricing information (optional)
+    pricing = Column(JSON, default=dict, nullable=True)
+    # Example: {"input_cost_per_1k": 0.01, "output_cost_per_1k": 0.03}
+
+    # Display order (lower = shown first)
+    display_order = Column(Integer, default=1000, nullable=False)
+
+    # Metadata
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+    created_by = Column(String, nullable=True)  # User ID who created this model entry
+
+    def __repr__(self):
+        return f"<LLMModel(id={self.id}, value={self.value}, provider={self.provider})>"
+
+    def to_dict(self):
+        """Convert to dictionary for API responses"""
+        return {
+            "id": self.id,
+            "value": self.value,
+            "label": self.label,
+            "provider": self.provider,
+            "logo": self.logo,
+            "description": self.description,
+            "enabled": self.enabled,
+            "recommended": self.recommended,
+            "compatible_runtimes": self.compatible_runtimes,
+            "capabilities": self.capabilities,
+            "pricing": self.pricing,
+            "display_order": self.display_order,
+            "created_at": self.created_at.isoformat() if self.created_at else None,
+            "updated_at": self.updated_at.isoformat() if self.updated_at else None,
+        }

control_plane_api/app/models/presence.py

@@ -0,0 +1,49 @@
+from sqlalchemy import Column, String, DateTime, Boolean, Index
+from sqlalchemy.sql import func
+from datetime import datetime
+import uuid
+
+from control_plane_api.app.database import Base
+
+
+class UserPresence(Base):
+    """Model for tracking user presence on agents/tasks for real-time collaboration"""
+
+    __tablename__ = "user_presence"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+
+    # User information
+    user_id = Column(String, nullable=False, index=True)
+    user_email = Column(String, nullable=True)
+    user_name = Column(String, nullable=True)
+    user_avatar = Column(String, nullable=True)
+
+    # What the user is viewing/interacting with
+    agent_id = Column(String, nullable=True, index=True)
+    session_id = Column(String, nullable=True, index=True)
+    execution_id = Column(String, nullable=True, index=True)
+
+    # Presence state
+    is_active = Column(Boolean, default=True, nullable=False)
+    is_typing = Column(Boolean, default=False, nullable=False)
+
+    # Timestamps
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    last_active_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False)
+
+    # Create composite index for efficient queries
+    __table_args__ = (
+        Index('idx_presence_lookup', 'agent_id', 'is_active', 'last_active_at'),
+        Index('idx_presence_user', 'user_id', 'is_active'),
+    )
+
+    def __repr__(self):
+        return f"<UserPresence(user_id={self.user_id}, agent_id={self.agent_id}, is_active={self.is_active})>"
+
+    @property
+    def is_stale(self) -> bool:
+        """Check if presence is stale (no activity in last 5 minutes)"""
+        if not self.last_active_at:
+            return True
+        return (datetime.utcnow() - self.last_active_at).total_seconds() > 300  # 5 minutes

control_plane_api/app/models/project.py

@@ -0,0 +1,47 @@
+from sqlalchemy import Column, String, DateTime, Text, JSON, Enum, Boolean
+from sqlalchemy.orm import relationship
+from datetime import datetime
+import enum
+import uuid
+
+from control_plane_api.app.database import Base
+
+
+class ProjectStatus(str, enum.Enum):
+    """Project status enumeration"""
+
+    ACTIVE = "active"
+    ARCHIVED = "archived"
+    PAUSED = "paused"
+
+
+class Project(Base):
+    """Project model for organizing agents, teams, and tasks"""
+
+    __tablename__ = "projects"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    organization_id = Column(String, nullable=False, index=True)
+    name = Column(String, nullable=False, index=True)
+    description = Column(Text, nullable=True)
+    goals = Column(Text, nullable=True)
+    status = Column(Enum(ProjectStatus, values_callable=lambda x: [e.value for e in x]), default=ProjectStatus.ACTIVE, nullable=False)
+
+    # Environment and runner configuration
+    restrict_to_environment = Column(Boolean, default=False, nullable=False)
+    # Note: policy_ids are stored in settings JSON field, not as separate column
+
+    # Default settings for project
+    default_model = Column(String, nullable=True)  # Default LLM model for this project
+    default_settings = Column(JSON, default=dict, nullable=False)  # Additional project-wide settings
+
+    # Metadata
+    is_default = Column(Boolean, default=False, nullable=False)  # Flag for the default project
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+
+    # Note: Project associations are managed through junction tables (project_agents, project_teams)
+    # in Supabase, not through direct foreign keys in the SQLAlchemy models
+
+    def __repr__(self):
+        return f"<Project(id={self.id}, name={self.name}, status={self.status})>"

control_plane_api/app/models/session.py

@@ -0,0 +1,38 @@
+from sqlalchemy import Column, String, DateTime, Text, JSON, ForeignKey
+from sqlalchemy.orm import relationship
+from datetime import datetime
+import uuid
+
+from control_plane_api.app.database import Base
+
+
+class Session(Base):
+    """Session model for storing agent session information with multi-user support"""
+
+    __tablename__ = "sessions"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    agent_id = Column(String, ForeignKey("agents.id"), nullable=False)
+
+    # Multi-user support - inspired by Agno's multi-user pattern
+    user_id = Column(String, nullable=True, index=True)  # User who owns this session
+    user_email = Column(String, nullable=True)
+    user_name = Column(String, nullable=True)
+    user_avatar = Column(String, nullable=True)
+
+    # Session data
+    messages = Column(JSON, default=list, nullable=False)
+    context = Column(JSON, default=dict, nullable=False)
+    session_metadata = Column(JSON, default=dict, nullable=False)
+
+    # Timestamps
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+    expires_at = Column(DateTime, nullable=True)
+    last_active_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+
+    # Relationships
+    agent = relationship("Agent", back_populates="sessions")
+
+    def __repr__(self):
+        return f"<Session(id={self.id}, agent_id={self.agent_id}, user_id={self.user_id})>"

control_plane_api/app/models/team.py

@@ -0,0 +1,66 @@
+from sqlalchemy import Column, String, DateTime, Text, JSON, Enum, ForeignKey, UniqueConstraint, ARRAY
+from sqlalchemy.dialects.postgresql import UUID as PG_UUID
+from sqlalchemy.orm import relationship
+from datetime import datetime
+import enum
+import uuid as uuid_module
+
+from control_plane_api.app.database import Base
+from control_plane_api.app.models.agent import RuntimeType
+
+
+class TeamStatus(str, enum.Enum):
+    """Team status enumeration"""
+
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+    ARCHIVED = "archived"
+
+
+class Team(Base):
+    """Team model for storing team information"""
+
+    __tablename__ = "teams"
+    __table_args__ = (
+        UniqueConstraint('organization_id', 'name', name='uq_team_org_name'),
+    )
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid_module.uuid4()))
+    organization_id = Column(String, nullable=False, index=True)
+    name = Column(String, nullable=False, index=True)
+    description = Column(Text, nullable=True)
+    status = Column(Enum(TeamStatus, values_callable=lambda x: [e.value for e in x]), default=TeamStatus.ACTIVE, nullable=False)
+
+    # Configuration
+    configuration = Column(JSON, default=dict, nullable=False)
+    # Use PostgreSQL UUID array - SQLAlchemy will handle the conversion
+    skill_ids = Column(ARRAY(PG_UUID(as_uuid=False)), default=list, nullable=False)
+    execution_environment = Column(JSON, default=dict, nullable=False)
+
+    # Runtime configuration
+    runtime = Column(
+        Enum(RuntimeType, values_callable=lambda x: [e.value for e in x]),
+        default=RuntimeType.DEFAULT,
+        server_default="default",
+        nullable=False,
+        index=True
+    )  # Runtime type for team execution (default: Agno, claude_code: Claude Code SDK)
+
+    # Metadata
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+
+    # Relationships
+    agents = relationship("Agent", back_populates="team")
+    workflows = relationship("Workflow", back_populates="team", cascade="all, delete-orphan")
+
+    # Many-to-many relationship with environments
+    environment_associations = relationship(
+        "TeamEnvironment",
+        foreign_keys="TeamEnvironment.team_id",
+        cascade="all, delete-orphan",
+        lazy="select"
+    )
+
+    def __repr__(self):
+        return f"<Team(id={self.id}, name={self.name}, status={self.status})>"

control_plane_api/app/models/workflow.py

@@ -0,0 +1,55 @@
+from sqlalchemy import Column, String, DateTime, Text, JSON, ForeignKey, Enum
+from sqlalchemy.orm import relationship
+from datetime import datetime
+import enum
+import uuid
+
+from control_plane_api.app.database import Base
+
+
+class WorkflowStatus(str, enum.Enum):
+    """Workflow status enumeration"""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    PAUSED = "paused"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class Workflow(Base):
+    """Workflow model for storing workflow information"""
+
+    __tablename__ = "workflows"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    name = Column(String, nullable=False, index=True)
+    description = Column(Text, nullable=True)
+    status = Column(Enum(WorkflowStatus, values_callable=lambda x: [e.value for e in x]), default=WorkflowStatus.PENDING, nullable=False)
+
+    # Workflow definition
+    steps = Column(JSON, default=list, nullable=False)
+    current_step = Column(String, nullable=True)
+
+    # Configuration
+    configuration = Column(JSON, default=dict, nullable=False)
+
+    # Relationships
+    team_id = Column(String, ForeignKey("teams.id"), nullable=True)
+
+    # Metadata
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+    started_at = Column(DateTime, nullable=True)
+    completed_at = Column(DateTime, nullable=True)
+
+    # State management
+    state = Column(JSON, default=dict, nullable=False)
+    error_message = Column(Text, nullable=True)
+
+    # Relationships
+    team = relationship("Team", back_populates="workflows")
+
+    def __repr__(self):
+        return f"<Workflow(id={self.id}, name={self.name}, status={self.status})>"