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

control_plane_api/app/models/agent.py

@@ -0,0 +1,90 @@
+from sqlalchemy import Column, String, DateTime, Text, JSON, ForeignKey, Enum, UniqueConstraint, Index, CheckConstraint, \
+    text, func
+from sqlalchemy.dialects.postgresql import UUID, ARRAY as PG_ARRAY, JSONB
+import enum
+
+from sqlalchemy.orm import relationship
+
+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(UUID(as_uuid=True), primary_key=True, server_default=text("gen_random_uuid()"), nullable=False)
+    organization_id = Column(String(255), nullable=False)
+    name = Column(String(255), nullable=False)
+    description = Column(Text, nullable=True)
+    status = Column(String(50), server_default='idle', nullable=True)
+    capabilities = Column(JSONB, server_default=text("'[]'::jsonb"), nullable=True)
+    configuration = Column(JSONB, server_default=text("'{}'::jsonb"), nullable=True)
+    model_id = Column(String(100), nullable=True)
+    model_config = Column(JSONB, server_default=text("'{}'::jsonb"), nullable=True)
+    team_id = Column(UUID(as_uuid=True), ForeignKey("teams.id", ondelete="SET NULL"), nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=True)
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=True)
+    last_active_at = Column(DateTime(timezone=True), nullable=True)
+    state = Column(JSONB, server_default=text("'{}'::jsonb"), nullable=True)
+    error_message = Column(Text, nullable=True)
+    runner_name = Column(String(100), nullable=True)
+    visibility = Column(String(20), server_default='private', nullable=True)
+    project_id = Column(UUID(as_uuid=True), ForeignKey("projects.id", ondelete="SET NULL"), nullable=True)
+    environment_id = Column(UUID(as_uuid=True), ForeignKey("environments.id", ondelete="SET NULL"), nullable=True)
+    toolset_ids = Column(PG_ARRAY(UUID(as_uuid=True)), server_default=text("'{}'::uuid[]"), nullable=True)
+    runtime = Column(String(50), server_default='default', nullable=False)
+    execution_environment = Column(JSONB, server_default=text("'{}'::jsonb"), nullable=False)
+    policy_ids = Column(PG_ARRAY(String(255)), server_default=text("'{}'::character varying[]"), nullable=True)
+
+    # Relationships
+    team = relationship("Team", back_populates="agents")
+    project = relationship("Project", foreign_keys=[project_id])
+    environment = relationship("Environment", foreign_keys=[environment_id])
+
+    # Many-to-many relationship with environments
+    environment_associations = relationship(
+        "AgentEnvironment",
+        foreign_keys="AgentEnvironment.agent_id",
+        cascade="all, delete-orphan",
+        lazy="select"
+    )
+
+    __table_args__ = (
+        UniqueConstraint('organization_id', 'name', name='agents_organization_id_name_key'),
+        CheckConstraint("visibility IN ('private', 'org')", name='agents_visibility_check'),
+        CheckConstraint("runtime IN ('default', 'claude_code')", name='chk_agents_runtime'),
+        Index('idx_agents_status', 'status'),
+        Index('idx_agents_team', 'team_id'),
+        Index('idx_agents_org', 'organization_id'),
+        Index('idx_agents_visibility', 'organization_id', 'visibility'),
+        Index('idx_agents_team_id', 'team_id'),
+        Index('idx_agents_project_id', 'project_id'),
+        Index('idx_agents_environment_id', 'environment_id'),
+        Index('idx_agents_toolset_ids', 'toolset_ids', postgresql_using='gin'),
+        Index('idx_agents_runtime', 'runtime'),
+        Index('idx_agents_org_runtime', 'organization_id', 'runtime'),
+        Index('idx_agents_execution_environment', 'execution_environment', postgresql_using='gin'),
+        Index('idx_agents_policy_ids', 'policy_ids', postgresql_using='gin'),
+    )
+
+    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, text
+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, nullable=False)
+
+    # 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, server_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, server_default=text('0'))
+    output_tokens = Column(Integer, nullable=True, server_default=text('0'))
+    cache_read_tokens = Column(Integer, nullable=True, server_default=text('0'))  # Cached tokens (Anthropic)
+    cache_creation_tokens = Column(Integer, nullable=True, server_default=text('0'))  # Cache creation tokens
+    total_tokens = Column(Integer, nullable=True, server_default=text('0'))
+
+    # Cost metrics (in USD)
+    input_cost = Column(Float, nullable=True, server_default=text('0'))
+    output_cost = Column(Float, nullable=True, server_default=text('0'))
+    cache_read_cost = Column(Float, nullable=True, server_default=text('0'))
+    cache_creation_cost = Column(Float, nullable=True, server_default=text('0'))
+    total_cost = Column(Float, nullable=True, server_default=text('0'))
+
+    # Agentic Engineering Minutes (AEM) metrics
+    runtime_minutes = Column(Float, nullable=True, server_default=text('0'))  # duration_ms / 60000
+    model_weight = Column(Float, nullable=True, server_default=text('1'))  # Model family weight (opus=2.0, sonnet=1.0, haiku=0.5)
+    tool_calls_weight = Column(Float, nullable=True, server_default=text('1'))  # Tool complexity weight
+    aem_value = Column(Float, nullable=True, server_default=text('0'))  # Calculated: runtime_minutes × model_weight × tool_calls_weight
+    aem_cost = Column(Float, nullable=True, server_default=text('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, server_default=text('0'), nullable=False)
+    tools_called_names = Column(JSON, server_default=text("'[]'::json"), nullable=False)  # List of tool names called
+
+    # Error tracking
+    error_message = Column(Text, nullable=True)
+
+    # Additional metrics (JSON for flexibility)
+    metrics = Column(JSON, server_default=text("'{}'::json"), nullable=False)  # 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, nullable=False)
+
+    # 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, server_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, server_default=text('true'))
+    error_message = Column(Text, nullable=True)
+    error_type = Column(String, nullable=True)  # e.g., "TimeoutError", "PermissionError"
+
+    # Additional metadata
+    metadata_ = Column("metadata", JSON, server_default=text("'{}'::json"), nullable=False)  # 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, nullable=False)
+
+    # 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, server_default=text("'pending'::character varying"))  # 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, server_default=text("'{}'::json"), nullable=False)
+
+    # 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,107 @@
+"""Association tables for many-to-many relationships"""
+from sqlalchemy import Column, String, DateTime, ForeignKey, Enum as SQLEnum, Index, UniqueConstraint
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+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(UUID(as_uuid=True), primary_key=True, server_default=func.gen_random_uuid(), nullable=False)
+    agent_id = Column(UUID(as_uuid=True), ForeignKey("agents.id", ondelete="CASCADE"), nullable=False)
+    environment_id = Column(UUID(as_uuid=True), ForeignKey("environments.id", ondelete="CASCADE"), nullable=False)
+    organization_id = Column(String, nullable=False)
+
+    # Assignment metadata
+    assigned_at = Column(DateTime(timezone=False), server_default=func.now(), nullable=False)
+    assigned_by = Column(String, nullable=True)
+
+    __table_args__ = (
+        UniqueConstraint('agent_id', 'environment_id', name='uq_agent_environment'),
+        Index('idx_agent_environments_agent_id', 'agent_id'),
+        Index('idx_agent_environments_environment_id', 'environment_id'),
+        Index('idx_agent_environments_org_id', 'organization_id'),
+        Index('idx_agent_environments_org_env', 'organization_id', 'environment_id'),
+    )
+
+    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(UUID(as_uuid=True), primary_key=True, server_default=func.gen_random_uuid(), nullable=False)
+    team_id = Column(UUID(as_uuid=True), ForeignKey("teams.id", ondelete="CASCADE"), nullable=False)
+    environment_id = Column(UUID(as_uuid=True), ForeignKey("environments.id", ondelete="CASCADE"), nullable=False)
+    organization_id = Column(String, nullable=False)
+
+    # Assignment metadata
+    assigned_at = Column(DateTime(timezone=False), server_default=func.now(), nullable=False)
+    assigned_by = Column(String, nullable=True)
+
+    __table_args__ = (
+        UniqueConstraint('team_id', 'environment_id', name='uq_team_environment'),
+        Index('idx_team_environments_team_id', 'team_id'),
+        Index('idx_team_environments_environment_id', 'environment_id'),
+        Index('idx_team_environments_org_id', 'organization_id'),
+        Index('idx_team_environments_org_env', 'organization_id', 'environment_id'),
+    )
+
+    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(UUID(as_uuid=True), primary_key=True, server_default=func.gen_random_uuid(), nullable=False)
+    execution_id = Column(UUID(as_uuid=True), ForeignKey("executions.id", ondelete="CASCADE"), nullable=False)
+    organization_id = Column(String, nullable=False)
+
+    # User information
+    user_id = Column(String, nullable=False)
+    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, name="participant_role", values_callable=lambda x: [e.value for e in x]),
+        server_default=ParticipantRole.COLLABORATOR.value,
+        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(), nullable=False)
+
+    # Relationships
+    execution = relationship("Execution", back_populates="participants")
+
+    __table_args__ = (
+        UniqueConstraint('execution_id', 'user_id', name='unique_execution_user'),
+        Index('idx_execution_participants_execution', 'execution_id'),
+        Index('idx_execution_participants_user', 'user_id'),
+        Index('idx_execution_participants_org', 'organization_id'),
+    )
+
+    def __repr__(self):
+        return f"<ExecutionParticipant(execution_id={self.execution_id}, user_id={self.user_id}, role={self.role})>"

control_plane_api/app/models/auth_user.py

@@ -0,0 +1,73 @@
+"""Auth user model - external table managed by Supabase"""
+from sqlalchemy import Column, String, DateTime, Text, Boolean, SmallInteger, CheckConstraint
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+
+from control_plane_api.app.database import Base
+
+
+class AuthUser(Base):
+    """Model for auth.users table (managed by Supabase, read-only)"""
+
+    __tablename__ = "users"
+    __table_args__ = (
+        {'schema': 'auth', 'extend_existing': True, 'info': {'skip_autogenerate': True}},
+    )
+
+    # Primary columns
+    id = Column(UUID(as_uuid=True), primary_key=True, nullable=False)
+    instance_id = Column(UUID(as_uuid=True), nullable=True)
+
+    # Authentication fields
+    aud = Column(String(255), nullable=True)
+    role = Column(String(255), nullable=True)
+    email = Column(String(255), nullable=True)
+    encrypted_password = Column(String(255), nullable=True)
+
+    # Email confirmation
+    email_confirmed_at = Column(DateTime(timezone=True), nullable=True)
+    confirmation_token = Column(String(255), nullable=True)
+    confirmation_sent_at = Column(DateTime(timezone=True), nullable=True)
+
+    # Recovery
+    recovery_token = Column(String(255), nullable=True)
+    recovery_sent_at = Column(DateTime(timezone=True), nullable=True)
+
+    # Email change
+    email_change_token_new = Column(String(255), nullable=True)
+    email_change = Column(String(255), nullable=True)
+    email_change_sent_at = Column(DateTime(timezone=True), nullable=True)
+    email_change_token_current = Column(String(255), nullable=True)
+    email_change_confirm_status = Column(SmallInteger, nullable=True, server_default='0')
+
+    # Sign in tracking
+    last_sign_in_at = Column(DateTime(timezone=True), nullable=True)
+    invited_at = Column(DateTime(timezone=True), nullable=True)
+
+    # Metadata
+    raw_app_meta_data = Column(JSONB, nullable=True)
+    raw_user_meta_data = Column(JSONB, nullable=True)
+
+    # Flags
+    is_super_admin = Column(Boolean, nullable=True)
+    is_sso_user = Column(Boolean, nullable=False, server_default='false')
+    is_anonymous = Column(Boolean, nullable=False, server_default='false')
+
+    # Timestamps
+    created_at = Column(DateTime(timezone=True), nullable=True)
+    updated_at = Column(DateTime(timezone=True), nullable=True)
+    deleted_at = Column(DateTime(timezone=True), nullable=True)
+
+    # Phone fields
+    phone = Column(Text, nullable=True)
+    phone_confirmed_at = Column(DateTime(timezone=True), nullable=True)
+    phone_change = Column(Text, nullable=True)
+    phone_change_token = Column(String(255), nullable=True)
+    phone_change_sent_at = Column(DateTime(timezone=True), nullable=True)
+
+    # Reauthentication
+    banned_until = Column(DateTime(timezone=True), nullable=True)
+    reauthentication_token = Column(String(255), nullable=True)
+    reauthentication_sent_at = Column(DateTime(timezone=True), nullable=True)
+
+    def __repr__(self):
+        return f"<AuthUser(id={self.id}, email={self.email})>"

control_plane_api/app/models/context.py

@@ -0,0 +1,161 @@
+"""Context models for managing knowledge, resources, and policies"""
+from sqlalchemy import Column, String, DateTime, Text, UUID, ARRAY, CheckConstraint, ForeignKey, Index, \
+    UniqueConstraint, text, desc
+from sqlalchemy.sql import func
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import relationship
+
+from control_plane_api.app.database import Base
+
+
+class AgentContext(Base):
+    """Model for contextual settings (knowledge, resources, policies) for agents"""
+
+    __tablename__ = "agent_contexts"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, server_default=text("gen_random_uuid()"), nullable=False)
+    agent_id = Column(UUID(as_uuid=True), ForeignKey('agents.id', ondelete='CASCADE'), nullable=False)
+    entity_type = Column(String(50), server_default=text("'agent'::character varying"), nullable=True)
+    organization_id = Column(UUID(as_uuid=True), nullable=False)
+    knowledge_uuids = Column(ARRAY(Text), server_default=text("'{}'::text[]"), nullable=True)  # Array of knowledge base UUIDs
+    resource_ids = Column(ARRAY(Text), server_default=text("'{}'::text[]"), nullable=True)  # Array of resource IDs from Meilisearch
+    policy_ids = Column(ARRAY(Text), server_default=text("'{}'::text[]"), nullable=True)  # Array of OPA policy IDs
+
+    # Metadata
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=True)
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=True)
+
+    # Relationships
+    agent = relationship("Agent", foreign_keys=[agent_id], viewonly=True)
+
+    __table_args__ = (
+        UniqueConstraint('agent_id', 'organization_id', name='agent_contexts_agent_id_organization_id_key'),
+        Index('idx_agent_contexts_agent_id', 'agent_id'),
+        Index('idx_agent_contexts_org_id', 'organization_id'),
+    )
+
+    def __repr__(self):
+        return f"<AgentContext(agent_id={self.agent_id}, org_id={self.organization_id})>"
+
+
+class EnvironmentContext(Base):
+    """Model for contextual settings (knowledge, resources, policies) for environments"""
+
+    __tablename__ = "environment_contexts"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, server_default=text("gen_random_uuid()"), nullable=False)
+    environment_id = Column(UUID(as_uuid=True), ForeignKey('environments.id', ondelete='CASCADE'), nullable=False)
+    entity_type = Column(String(50), server_default=text("'environment'::character varying"), nullable=True)
+    organization_id = Column(UUID(as_uuid=True), nullable=False)
+    knowledge_uuids = Column(ARRAY(Text), server_default=text("'{}'::text[]"), nullable=True)
+    resource_ids = Column(ARRAY(Text), server_default=text("'{}'::text[]"), nullable=True)
+    policy_ids = Column(ARRAY(Text), server_default=text("'{}'::text[]"), nullable=True)
+
+    # Metadata
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=True)
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=True)
+
+    # Relationships
+    environment = relationship("Environment", foreign_keys=[environment_id], viewonly=True)
+
+    __table_args__ = (
+        UniqueConstraint('environment_id', 'organization_id', name='environment_contexts_environment_id_organization_id_key'),
+        Index('idx_environment_contexts_environment_id', 'environment_id'),
+        Index('idx_environment_contexts_org_id', 'organization_id'),
+    )
+
+    def __repr__(self):
+        return f"<EnvironmentContext(env_id={self.environment_id}, org_id={self.organization_id})>"
+
+
+class ProjectContext(Base):
+    """Model for contextual settings (knowledge, resources, policies) for projects"""
+
+    __tablename__ = "project_contexts"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, server_default=text("gen_random_uuid()"), nullable=False)
+    project_id = Column(UUID(as_uuid=True), ForeignKey('projects.id', ondelete='CASCADE'), nullable=False)
+    entity_type = Column(String(50), server_default=text("'project'::character varying"), nullable=True)
+    organization_id = Column(UUID(as_uuid=True), nullable=False)
+    knowledge_uuids = Column(ARRAY(Text), server_default=text("'{}'::text[]"), nullable=True)
+    resource_ids = Column(ARRAY(Text), server_default=text("'{}'::text[]"), nullable=True)
+    policy_ids = Column(ARRAY(Text), server_default=text("'{}'::text[]"), nullable=True)
+
+    # Metadata
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=True)
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=True)
+
+    # Relationships
+    project = relationship("Project", foreign_keys=[project_id], viewonly=True)
+
+    __table_args__ = (
+        UniqueConstraint('project_id', 'organization_id', name='project_contexts_project_id_organization_id_key'),
+        Index('idx_project_contexts_project_id', 'project_id'),
+        Index('idx_project_contexts_org_id', 'organization_id'),
+    )
+
+    def __repr__(self):
+        return f"<ProjectContext(project_id={self.project_id}, org_id={self.organization_id})>"
+
+
+class TeamContext(Base):
+    """Model for contextual settings (knowledge, resources, policies) for teams"""
+
+    __tablename__ = "team_contexts"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, server_default=text("gen_random_uuid()"), nullable=False)
+    team_id = Column(UUID(as_uuid=True), ForeignKey('teams.id', ondelete='CASCADE'), nullable=False)
+    entity_type = Column(String(50), server_default=text("'team'::character varying"), nullable=True)
+    organization_id = Column(UUID(as_uuid=True), nullable=False)
+    knowledge_uuids = Column(ARRAY(Text), server_default=text("'{}'::text[]"), nullable=True)
+    resource_ids = Column(ARRAY(Text), server_default=text("'{}'::text[]"), nullable=True)
+    policy_ids = Column(ARRAY(Text), server_default=text("'{}'::text[]"), nullable=True)
+
+    # Metadata
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=True)
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=True)
+
+    # Relationships
+    team = relationship("Team", foreign_keys=[team_id], viewonly=True)
+
+    __table_args__ = (
+        UniqueConstraint('team_id', 'organization_id', name='team_contexts_team_id_organization_id_key'),
+        Index('idx_team_contexts_team_id', 'team_id'),
+        Index('idx_team_contexts_org_id', 'organization_id'),
+    )
+
+    def __repr__(self):
+        return f"<TeamContext(team_id={self.team_id}, org_id={self.organization_id})>"
+
+
+class ContextResource(Base):
+    """Model for context resources from various platforms (read-only, synced by external processes)"""
+
+    __tablename__ = "context_resources"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, server_default=text("gen_random_uuid()"), nullable=False)
+    name = Column(Text, nullable=False)  # Resource name following MindsDB convention
+    platform = Column(Text, nullable=False)  # Source platform (github, slack, discord, notion, etc.)
+    organization = Column(Text, nullable=False)  # Organization identifier for data isolation
+    type = Column(Text, server_default=text("'integration'::text"), nullable=True)  # Type of resource
+    status = Column(Text, server_default=text("'active'::text"), nullable=True)  # active, inactive, pending, error
+    description = Column(Text, nullable=True)
+    metadata_ = Column("metadata", JSONB, server_default=text("'{}'::jsonb"), nullable=True)  # Maps to 'metadata' column in DB
+
+    # Metadata
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=True)
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=True)
+
+    __table_args__ = (
+        UniqueConstraint('name', name='context_resources_name_key'),
+        CheckConstraint("status = ANY (ARRAY['active'::text, 'inactive'::text, 'pending'::text, 'error'::text])", name='valid_status'),
+        Index('idx_context_resources_name', 'name'),
+        Index('idx_context_resources_org_platform', 'organization', 'platform'),
+        Index('idx_context_resources_organization', 'organization'),
+        Index('idx_context_resources_platform', 'platform'),
+        Index('idx_context_resources_status', 'status'),
+        Index('idx_context_resources_updated_at', desc('updated_at')),
+    )
+
+    def __repr__(self):
+        return f"<ContextResource(name={self.name}, platform={self.platform}, org={self.organization})>"