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

control_plane_api/app/middleware/request_id.py

@@ -0,0 +1,202 @@
+"""
+Request ID middleware for request tracking and correlation.
+
+Adds a unique request ID to each request for tracking through logs and services.
+"""
+
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.types import ASGIApp
+import structlog
+import logging
+import uuid
+import contextvars
+from typing import Optional
+
+logger = structlog.get_logger()
+
+# Context variable to store request ID
+request_id_context: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    "request_id", default=None
+)
+
+
+class RequestIDMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware to add request ID to all requests.
+    
+    - Checks for existing X-Request-ID header
+    - Generates new ID if not present
+    - Adds ID to response headers
+    - Makes ID available in context for logging
+    """
+    
+    REQUEST_ID_HEADER = "X-Request-ID"
+    
+    def __init__(self, app: ASGIApp, header_name: str = None):
+        super().__init__(app)
+        if header_name:
+            self.REQUEST_ID_HEADER = header_name
+    
+    async def dispatch(self, request: Request, call_next):
+        """Process the request and add request ID."""
+        
+        # Get or generate request ID
+        request_id = (
+            request.headers.get(self.REQUEST_ID_HEADER) or
+            request.headers.get(self.REQUEST_ID_HEADER.lower()) or
+            self._generate_request_id()
+        )
+        
+        # Validate request ID format (basic security check)
+        if not self._is_valid_request_id(request_id):
+            request_id = self._generate_request_id()
+        
+        # Store in request state for easy access
+        request.state.request_id = request_id
+        
+        # Set context variable for logging
+        token = request_id_context.set(request_id)
+        
+        try:
+            # Log request start
+            logger.info(
+                "request_started",
+                request_id=request_id,
+                method=request.method,
+                path=str(request.url.path),
+                query=str(request.url.query) if request.url.query else None,
+                client=request.client.host if request.client else None,
+            )
+            
+            # Process request
+            response = await call_next(request)
+            
+            # Add request ID to response headers
+            response.headers[self.REQUEST_ID_HEADER] = request_id
+            
+            # Log request completion
+            logger.info(
+                "request_completed",
+                request_id=request_id,
+                status_code=response.status_code,
+            )
+            
+            return response
+            
+        except Exception as e:
+            # Log request failure
+            logger.error(
+                "request_failed",
+                request_id=request_id,
+                error=str(e),
+                error_type=type(e).__name__,
+            )
+            raise
+            
+        finally:
+            # Reset context variable
+            request_id_context.reset(token)
+    
+    def _generate_request_id(self) -> str:
+        """Generate a new request ID."""
+        return str(uuid.uuid4())
+    
+    def _is_valid_request_id(self, request_id: str) -> bool:
+        """
+        Validate request ID format.
+        
+        Accepts UUIDs and alphanumeric strings up to 128 characters.
+        """
+        if not request_id or len(request_id) > 128:
+            return False
+        
+        # Allow UUIDs, alphanumeric, hyphens, and underscores
+        import re
+        return bool(re.match(r'^[a-zA-Z0-9\-_]+$', request_id))
+
+
+def get_request_id() -> Optional[str]:
+    """
+    Get the current request ID from context.
+    
+    This can be used anywhere in the application to get the current request ID.
+    
+    Returns:
+        Request ID if in request context, None otherwise
+    """
+    return request_id_context.get()
+
+
+def set_request_id(request_id: str) -> None:
+    """
+    Set the request ID in context.
+    
+    This is useful for background tasks or other contexts where you want
+    to maintain the request ID.
+    
+    Args:
+        request_id: Request ID to set
+    """
+    request_id_context.set(request_id)
+
+
+class RequestIDLogProcessor:
+    """
+    Structlog processor to add request ID to all log entries.
+    
+    Use this in your structlog configuration:
+    
+    structlog.configure(
+        processors=[
+            RequestIDLogProcessor(),
+            structlog.processors.add_log_level,
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.processors.JSONRenderer(),
+        ],
+        ...
+    )
+    """
+    
+    def __call__(self, logger, name, event_dict):
+        """Add request ID to log entry if available."""
+        request_id = get_request_id()
+        if request_id:
+            event_dict["request_id"] = request_id
+        return event_dict
+
+
+def setup_request_id_logging():
+    """
+    Configure structlog to include request ID in all logs.
+    
+    Call this in your app initialization.
+    """
+    import structlog
+    
+    structlog.configure(
+        processors=[
+            RequestIDLogProcessor(),  # Add request ID
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.add_log_level,
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.processors.JSONRenderer(),
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(
+            logging.INFO
+        ),
+        logger_factory=structlog.PrintLoggerFactory(),
+    )
+
+
+# For FastAPI dependency injection
+async def get_request_id_from_request(request: Request) -> str:
+    """
+    FastAPI dependency to get request ID.
+    
+    Usage:
+        @app.get("/example")
+        async def example(request_id: str = Depends(get_request_id_from_request)):
+            return {"request_id": request_id}
+    """
+    return getattr(request.state, "request_id", None) or str(uuid.uuid4())

control_plane_api/app/models/__init__.py

@@ -0,0 +1,27 @@
+# Database Models
+from control_plane_api.app.models.project import Project, ProjectStatus
+from control_plane_api.app.models.agent import Agent, AgentStatus
+from control_plane_api.app.models.team import Team, TeamStatus
+from control_plane_api.app.models.workflow import Workflow, WorkflowStatus
+from control_plane_api.app.models.session import Session
+from control_plane_api.app.models.execution import Execution, ExecutionStatus, ExecutionType, ExecutionTriggerSource
+from control_plane_api.app.models.presence import UserPresence
+from control_plane_api.app.models.environment import Environment, EnvironmentStatus
+from control_plane_api.app.models.associations import AgentEnvironment, TeamEnvironment, ExecutionParticipant, ParticipantRole
+from control_plane_api.app.models.job import Job, JobExecution, JobStatus, JobTriggerType, ExecutorType, PlanningMode
+from control_plane_api.app.models.llm_model import LLMModel
+
+__all__ = [
+    "Project", "ProjectStatus",
+    "Agent", "AgentStatus",
+    "Team", "TeamStatus",
+    "Workflow", "WorkflowStatus",
+    "Session",
+    "Execution", "ExecutionStatus", "ExecutionType", "ExecutionTriggerSource",
+    "UserPresence",
+    "Environment", "EnvironmentStatus",
+    "AgentEnvironment", "TeamEnvironment",
+    "ExecutionParticipant", "ParticipantRole",
+    "Job", "JobExecution", "JobStatus", "JobTriggerType", "ExecutorType", "PlanningMode",
+    "LLMModel"
+]

control_plane_api/app/models/agent.py

@@ -0,0 +1,79 @@
+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 AgentStatus(str, enum.Enum):
+    """Agent status enumeration"""
+
+    IDLE = "idle"
+    RUNNING = "running"
+    PAUSED = "paused"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    STOPPED = "stopped"
+
+
+class RuntimeType(str, enum.Enum):
+    """Agent runtime type enumeration"""
+
+    DEFAULT = "default"  # Agno-based runtime (current implementation)
+    CLAUDE_CODE = "claude_code"  # Claude Code SDK runtime
+
+
+class Agent(Base):
+    """Agent model for storing agent information"""
+
+    __tablename__ = "agents"
+
+    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(AgentStatus, values_callable=lambda x: [e.value for e in x]), default=AgentStatus.IDLE, nullable=False)
+    capabilities = Column(JSON, default=list, nullable=False)
+    configuration = Column(JSON, default=dict, nullable=False)
+
+    # LiteLLM configuration
+    model_id = Column(String, nullable=True)  # LiteLLM model identifier
+    model_config = Column(JSON, default=dict, nullable=False)  # Model-specific config (temperature, top_p, etc.)
+
+    # 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 agent execution (default: Agno, claude_code: Claude Code SDK)
+
+    # Foreign keys
+    organization_id = Column(String, nullable=False, index=True)
+    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)
+    last_active_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="agents")
+    sessions = relationship("Session", back_populates="agent", cascade="all, delete-orphan")
+
+    # Many-to-many relationship with environments
+    environment_associations = relationship(
+        "AgentEnvironment",
+        foreign_keys="AgentEnvironment.agent_id",
+        cascade="all, delete-orphan",
+        lazy="select"
+    )
+
+    def __repr__(self):
+        return f"<Agent(id={self.id}, name={self.name}, status={self.status})>"

control_plane_api/app/models/analytics.py

@@ -0,0 +1,206 @@
+"""
+Analytics models for comprehensive execution tracking and reporting.
+
+This module provides production-grade analytics tables to track:
+- Per-turn LLM metrics (tokens, duration, cost)
+- Tool execution details (success/failure, timing)
+- Task completion tracking
+- Organization-level reporting
+"""
+
+from sqlalchemy import Column, String, DateTime, Integer, Float, Boolean, Text, JSON, ForeignKey, Index
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.sql import func
+from sqlalchemy.orm import relationship
+from datetime import datetime
+import uuid
+import enum
+
+from control_plane_api.app.database import Base
+
+
+class ExecutionTurn(Base):
+    """
+    Tracks each LLM interaction turn within an execution.
+
+    This provides granular metrics for each agent reasoning step,
+    enabling detailed performance analysis and cost tracking.
+    """
+
+    __tablename__ = "execution_turns"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+
+    # Organization and execution context
+    organization_id = Column(String, nullable=False, index=True)
+    execution_id = Column(UUID(as_uuid=True), ForeignKey("executions.id", ondelete="CASCADE"), nullable=False, index=True)
+
+    # Turn identification
+    turn_number = Column(Integer, nullable=False)  # Sequential turn number in conversation
+    turn_id = Column(String, nullable=True)  # Runtime-specific turn identifier
+
+    # Model information
+    model = Column(String, nullable=False)  # e.g., "claude-sonnet-4", "gpt-4"
+    model_provider = Column(String, nullable=True)  # e.g., "anthropic", "openai"
+
+    # Timing metrics
+    started_at = Column(DateTime(timezone=True), nullable=False, default=func.now())
+    completed_at = Column(DateTime(timezone=True), nullable=True)
+    duration_ms = Column(Integer, nullable=True)  # Duration in milliseconds
+
+    # Token usage metrics
+    input_tokens = Column(Integer, nullable=True, default=0)
+    output_tokens = Column(Integer, nullable=True, default=0)
+    cache_read_tokens = Column(Integer, nullable=True, default=0)  # Cached tokens (Anthropic)
+    cache_creation_tokens = Column(Integer, nullable=True, default=0)  # Cache creation tokens
+    total_tokens = Column(Integer, nullable=True, default=0)
+
+    # Cost metrics (in USD)
+    input_cost = Column(Float, nullable=True, default=0.0)
+    output_cost = Column(Float, nullable=True, default=0.0)
+    cache_read_cost = Column(Float, nullable=True, default=0.0)
+    cache_creation_cost = Column(Float, nullable=True, default=0.0)
+    total_cost = Column(Float, nullable=True, default=0.0)
+
+    # Agentic Engineering Minutes (AEM) metrics
+    runtime_minutes = Column(Float, nullable=True, default=0.0)  # duration_ms / 60000
+    model_weight = Column(Float, nullable=True, default=1.0)  # Model family weight (opus=2.0, sonnet=1.0, haiku=0.5)
+    tool_calls_weight = Column(Float, nullable=True, default=1.0)  # Tool complexity weight
+    aem_value = Column(Float, nullable=True, default=0.0)  # Calculated: runtime_minutes × model_weight × tool_calls_weight
+    aem_cost = Column(Float, nullable=True, default=0.0)  # AEM × price per AEM ($0.15/min default)
+
+    # Turn result
+    finish_reason = Column(String, nullable=True)  # "stop", "length", "tool_use", "error"
+    response_preview = Column(Text, nullable=True)  # First 500 chars of response
+
+    # Tool usage in this turn
+    tools_called_count = Column(Integer, default=0)
+    tools_called_names = Column(JSON, default=list)  # List of tool names called
+
+    # Error tracking
+    error_message = Column(Text, nullable=True)
+
+    # Additional metrics (JSON for flexibility)
+    metrics = Column(JSON, default=dict)  # Custom metrics, latencies, etc.
+
+    # Timestamps
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+
+    # Indexes for fast querying
+    __table_args__ = (
+        Index('ix_execution_turns_org_execution', 'organization_id', 'execution_id'),
+        Index('ix_execution_turns_org_model', 'organization_id', 'model'),
+        Index('ix_execution_turns_org_created', 'organization_id', 'created_at'),
+        Index('ix_execution_turns_org_cost', 'organization_id', 'total_cost'),
+    )
+
+    def __repr__(self):
+        return f"<ExecutionTurn {self.id} turn={self.turn_number} model={self.model} tokens={self.total_tokens} cost=${self.total_cost}>"
+
+
+class ExecutionToolCall(Base):
+    """
+    Tracks individual tool/function calls within an execution.
+
+    This enables detailed tool usage analytics, error tracking,
+    and performance monitoring at the tool level.
+    """
+
+    __tablename__ = "execution_tool_calls"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+
+    # Organization and execution context
+    organization_id = Column(String, nullable=False, index=True)
+    execution_id = Column(UUID(as_uuid=True), ForeignKey("executions.id", ondelete="CASCADE"), nullable=False, index=True)
+    turn_id = Column(UUID(as_uuid=True), ForeignKey("execution_turns.id", ondelete="CASCADE"), nullable=True, index=True)
+
+    # Tool identification
+    tool_name = Column(String, nullable=False, index=True)  # e.g., "Read", "Bash", "WebFetch"
+    tool_use_id = Column(String, nullable=True)  # Runtime-specific tool call ID
+
+    # Timing
+    started_at = Column(DateTime(timezone=True), nullable=False, default=func.now())
+    completed_at = Column(DateTime(timezone=True), nullable=True)
+    duration_ms = Column(Integer, nullable=True)  # Duration in milliseconds
+
+    # Tool execution details
+    tool_input = Column(JSON, nullable=True)  # Tool parameters
+    tool_output = Column(Text, nullable=True)  # Tool result (truncated if large)
+    tool_output_size = Column(Integer, nullable=True)  # Size in bytes
+
+    # Status
+    success = Column(Boolean, nullable=False, default=True)
+    error_message = Column(Text, nullable=True)
+    error_type = Column(String, nullable=True)  # e.g., "TimeoutError", "PermissionError"
+
+    # Additional metadata
+    custom_metadata = Column(JSON, default=dict)  # Custom metrics, context, etc.
+
+    # Timestamps
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+
+    # Indexes for fast querying
+    __table_args__ = (
+        Index('ix_execution_tool_calls_org_execution', 'organization_id', 'execution_id'),
+        Index('ix_execution_tool_calls_org_tool', 'organization_id', 'tool_name'),
+        Index('ix_execution_tool_calls_org_success', 'organization_id', 'success'),
+        Index('ix_execution_tool_calls_org_created', 'organization_id', 'created_at'),
+    )
+
+    def __repr__(self):
+        status = "✓" if self.success else "✗"
+        return f"<ExecutionToolCall {status} {self.tool_name} duration={self.duration_ms}ms>"
+
+
+class ExecutionTask(Base):
+    """
+    Tracks high-level tasks/subtasks within an execution.
+
+    Some runtimes (like Claude Code) break work into tasks with status tracking.
+    This table captures that information for progress monitoring and analytics.
+    """
+
+    __tablename__ = "execution_tasks"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+
+    # Organization and execution context
+    organization_id = Column(String, nullable=False, index=True)
+    execution_id = Column(UUID(as_uuid=True), ForeignKey("executions.id", ondelete="CASCADE"), nullable=False, index=True)
+
+    # Task identification
+    task_number = Column(Integer, nullable=True)  # Sequential task number
+    task_id = Column(String, nullable=True)  # Runtime-specific task ID
+
+    # Task details
+    task_description = Column(Text, nullable=False)  # What is the task
+    task_type = Column(String, nullable=True)  # e.g., "coding", "analysis", "research"
+
+    # Status tracking
+    status = Column(String, nullable=False, default="pending")  # pending, in_progress, completed, failed
+
+    # Timing
+    started_at = Column(DateTime(timezone=True), nullable=True)
+    completed_at = Column(DateTime(timezone=True), nullable=True)
+    duration_ms = Column(Integer, nullable=True)
+
+    # Result
+    result = Column(Text, nullable=True)  # Task outcome/result
+    error_message = Column(Text, nullable=True)
+
+    # Additional metadata
+    custom_metadata = Column(JSON, default=dict)
+
+    # 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)
+
+    # Indexes
+    __table_args__ = (
+        Index('ix_execution_tasks_org_execution', 'organization_id', 'execution_id'),
+        Index('ix_execution_tasks_org_status', 'organization_id', 'status'),
+    )
+
+    def __repr__(self):
+        return f"<ExecutionTask {self.id} status={self.status} desc={self.task_description[:50]}>"

control_plane_api/app/models/associations.py

@@ -0,0 +1,81 @@
+"""Association tables for many-to-many relationships"""
+from sqlalchemy import Column, String, DateTime, ForeignKey, Enum as SQLEnum
+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 ParticipantRole(str, enum.Enum):
+    """Role of a participant in an execution"""
+    OWNER = "owner"  # User who created the execution
+    COLLABORATOR = "collaborator"  # User actively participating
+    VIEWER = "viewer"  # User with read-only access
+
+
+class AgentEnvironment(Base):
+    """Many-to-many association between agents and environments"""
+
+    __tablename__ = "agent_environments"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    agent_id = Column(String, ForeignKey("agents.id", ondelete="CASCADE"), nullable=False)
+    environment_id = Column(String, ForeignKey("environments.id", ondelete="CASCADE"), nullable=False)
+    organization_id = Column(String, nullable=False, index=True)
+
+    # Assignment metadata
+    assigned_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    assigned_by = Column(String, nullable=True)
+
+    def __repr__(self):
+        return f"<AgentEnvironment(agent_id={self.agent_id}, environment_id={self.environment_id})>"
+
+
+class TeamEnvironment(Base):
+    """Many-to-many association between teams and environments"""
+
+    __tablename__ = "team_environments"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    team_id = Column(String, ForeignKey("teams.id", ondelete="CASCADE"), nullable=False)
+    environment_id = Column(String, ForeignKey("environments.id", ondelete="CASCADE"), nullable=False)
+    organization_id = Column(String, nullable=False, index=True)
+
+    # Assignment metadata
+    assigned_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    assigned_by = Column(String, nullable=True)
+
+    def __repr__(self):
+        return f"<TeamEnvironment(team_id={self.team_id}, environment_id={self.environment_id})>"
+
+
+class ExecutionParticipant(Base):
+    """Many-to-many association between executions and users (multiplayer support)"""
+
+    __tablename__ = "execution_participants"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    execution_id = Column(String, ForeignKey("executions.id", ondelete="CASCADE"), nullable=False, index=True)
+    organization_id = Column(String, nullable=False, index=True)
+
+    # 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)
+
+    # Participant role and status
+    role = Column(SQLEnum(ParticipantRole, values_callable=lambda x: [e.value for e in x]), default=ParticipantRole.COLLABORATOR, nullable=False)
+
+    # Timestamps
+    joined_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)
+
+    # Relationships
+    execution = relationship("Execution", back_populates="participants")
+
+    def __repr__(self):
+        return f"<ExecutionParticipant(execution_id={self.execution_id}, user_id={self.user_id}, role={self.role})>"

control_plane_api/app/models/environment.py

@@ -0,0 +1,63 @@
+"""Environment model for execution environments"""
+from sqlalchemy import Column, String, DateTime, JSON, Enum as SQLEnum
+from datetime import datetime
+import uuid
+import enum
+
+from control_plane_api.app.database import Base
+
+
+class EnvironmentStatus(str, enum.Enum):
+    """Environment status"""
+    PENDING = "pending"
+    PROVISIONING = "provisioning"
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+    ERROR = "error"
+
+
+class Environment(Base):
+    """
+    Execution environment - represents a worker queue environment.
+    Maps to task queues in Temporal.
+    """
+
+    __tablename__ = "environments"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    organization_id = Column(String, nullable=False, index=True)
+    
+    # Basic info
+    name = Column(String, nullable=False, index=True)  # Environment name (e.g., "default", "production")
+    display_name = Column(String, nullable=True)  # User-friendly display name
+    description = Column(String, nullable=True)
+    
+    # Configuration
+    tags = Column(JSON, nullable=False, default=list)  # Tags for categorization
+    settings = Column(JSON, nullable=False, default=dict)  # Environment-specific settings
+    status = Column(
+        SQLEnum(EnvironmentStatus),
+        nullable=False,
+        default=EnvironmentStatus.PENDING,
+        index=True
+    )
+    
+    # Temporal Cloud provisioning
+    worker_token = Column(String, nullable=True)  # JWT token for worker registration
+    provisioning_workflow_id = Column(String, nullable=True)  # Temporal workflow ID for provisioning
+    provisioned_at = Column(DateTime, nullable=True)  # When namespace was provisioned
+    error_message = Column(String, nullable=True)  # Error message if provisioning failed
+    temporal_namespace_id = Column(String, nullable=True)  # Temporal Cloud namespace ID
+    
+    # Execution environment configuration (env vars, secrets, integrations)
+    execution_environment = Column(JSON, nullable=False, default=dict)
+    
+    # Timestamps and audit
+    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 email or ID who created
+    updated_by = Column(String, nullable=True)  # User email or ID who last updated
+
+    def __repr__(self):
+        return f"<Environment(id={self.id}, name={self.name}, organization_id={self.organization_id}, status={self.status})>"
+