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

control_plane_api/app/skills/__init__.py

@@ -0,0 +1,100 @@
+"""
+Skills Module
+
+This module manages all available skills (OS-level capabilities) that can be
+assigned to agents and teams. Each skill corresponds to a capability that agents
+can use during execution (file system, shell, Docker, Python, etc.).
+
+Skills are defined as Python classes that provide:
+- Metadata (name, description, icon)
+- Default configuration
+- Validation logic
+- Instantiation logic for the underlying framework
+
+Skills can be:
+1. Built-in (imported below)
+2. Dynamic (loaded from .kubiya/skills/ via loaders)
+"""
+
+from .base import SkillDefinition, SkillType, SkillCategory, SkillRequirements, SkillVariant
+from .registry import skill_registry, get_skill, get_all_skills, register_skill
+from .config import get_skill_template_paths, is_dynamic_skills_enabled
+from .loaders import FilesystemSkillTemplateLoader
+import logging
+
+# Import all built-in skill definitions to auto-register them
+from .builtin import (
+    FileSystemSkill,
+    ShellSkill,
+    DockerSkill,
+    PythonSkill,
+    FileGenerationSkill,
+    DataVisualizationSkill,
+    WorkflowExecutorSkill,
+    KnowledgeAPISkill,
+    AgentCommunicationSkill,
+)
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "SkillDefinition",
+    "SkillType",
+    "SkillCategory",
+    "SkillRequirements",
+    "SkillVariant",
+    "skill_registry",
+    "get_skill",
+    "get_all_skills",
+    "register_skill",
+    "FileSystemSkill",
+    "ShellSkill",
+    "DockerSkill",
+    "PythonSkill",
+    "FileGenerationSkill",
+    "DataVisualizationSkill",
+    "WorkflowExecutorSkill",
+    "KnowledgeAPISkill",
+    "AgentCommunicationSkill",
+    "initialize_dynamic_skills",
+]
+
+
+def initialize_dynamic_skills() -> int:
+    """
+    Initialize and load dynamic skills from configured sources.
+
+    This should be called during Control Plane startup, after built-in
+    skills have been registered.
+
+    Returns:
+        Number of dynamic skills loaded
+
+    Environment Variables:
+        KUBIYA_ENABLE_DYNAMIC_SKILLS: Enable/disable dynamic loading (default: true)
+        KUBIYA_SKILLS_TEMPLATES_PATH: Primary skills directory
+        KUBIYA_SKILLS_EXTRA_PATHS: Additional paths (colon-separated)
+    """
+    if not is_dynamic_skills_enabled():
+        logger.info("Dynamic skills loading is disabled")
+        return 0
+
+    logger.info("Initializing dynamic skills...")
+
+    # Get configured paths
+    paths = get_skill_template_paths()
+
+    if not paths:
+        logger.info("No skill template paths configured, skipping dynamic loading")
+        return 0
+
+    # Create filesystem loader
+    loaders = [
+        FilesystemSkillTemplateLoader(base_paths=paths, enabled=True)
+    ]
+
+    # Load from all loaders
+    loaded_count = skill_registry.load_from_loaders(loaders)
+
+    logger.info(f"Dynamic skills initialization complete: {loaded_count} skills loaded")
+    return loaded_count

control_plane_api/app/skills/base.py

@@ -0,0 +1,239 @@
+"""
+Base classes for skill definitions
+"""
+from typing import Dict, Any, List, Optional, Set
+from enum import Enum
+from pydantic import BaseModel, Field
+from abc import ABC, abstractmethod
+import platform
+
+
+class SkillType(str, Enum):
+    """Supported skill types"""
+    FILE_SYSTEM = "file_system"
+    SHELL = "shell"
+    DOCKER = "docker"
+    PYTHON = "python"
+    FILE_GENERATION = "file_generation"
+    DATA_VISUALIZATION = "data_visualization"
+    SLEEP = "sleep"
+    WORKFLOW_EXECUTOR = "workflow_executor"
+    CONTEXTUAL_AWARENESS = "contextual_awareness"
+    KNOWLEDGE_API = "knowledge_api"
+    COGNITIVE_MEMORY = "cognitive_memory"  # Context graph + semantic memory operations
+    CODE_INGESTION = "code_ingestion"  # Code repository ingestion and analysis
+    AGENT_COMMUNICATION = "agent_communication"
+    REMOTE_FILESYSTEM = "remote_filesystem"
+    SLACK = "slack"
+    CUSTOM = "custom"
+
+
+class SkillCategory(str, Enum):
+    """Skill categories for organization"""
+    COMMON = "common"          # Frequently used, safe defaults
+    ADVANCED = "advanced"       # Advanced features, require more privileges
+    SECURITY = "security"       # Security-focused, restricted access
+    CUSTOM = "custom"           # User-defined custom skills
+
+
+class SkillRequirements(BaseModel):
+    """Runtime requirements for a skill"""
+    # Python packages required (will be checked/installed by worker)
+    python_packages: List[str] = Field(default_factory=list)
+
+    # System packages required (informational, worker should validate)
+    system_packages: List[str] = Field(default_factory=list)
+
+    # Supported operating systems (e.g., ["linux", "darwin", "windows"])
+    supported_os: Optional[List[str]] = None
+
+    # Minimum Python version (e.g., "3.10")
+    min_python_version: Optional[str] = None
+
+    # Environment variables required
+    required_env_vars: List[str] = Field(default_factory=list)
+
+    # External services/APIs required (informational)
+    external_dependencies: List[str] = Field(default_factory=list)
+
+    # Additional notes about requirements
+    notes: Optional[str] = None
+
+
+class SkillVariant(BaseModel):
+    """A specific variant/preset of a skill"""
+    id: str
+    name: str
+    description: str
+    category: SkillCategory
+    configuration: Dict[str, Any]
+    badge: Optional[str] = None  # e.g., "Safe", "Recommended", "Advanced"
+    icon: Optional[str] = None
+    is_default: bool = False
+
+
+class SkillDefinition(ABC):
+    """
+    Base class for all skill definitions.
+
+    Each skill type should subclass this and implement the required methods.
+    This provides a clean interface for defining new skills.
+    """
+
+    @property
+    @abstractmethod
+    def type(self) -> SkillType:
+        """The type identifier for this skill"""
+        pass
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Human-readable name"""
+        pass
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Description of what this skill does"""
+        pass
+
+    @property
+    @abstractmethod
+    def icon(self) -> str:
+        """Icon name (Lucide or React Icons)"""
+        pass
+
+    @property
+    def icon_type(self) -> str:
+        """Icon type: 'lucide' or 'react-icon'"""
+        return "lucide"
+
+    @abstractmethod
+    def get_variants(self) -> List[SkillVariant]:
+        """
+        Get all predefined variants/presets for this skill.
+
+        Returns a list of variants with different configurations
+        (e.g., "Read Only", "Full Access", "Sandboxed")
+        """
+        pass
+
+    @abstractmethod
+    def validate_configuration(self, config: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Validate and normalize configuration.
+
+        Args:
+            config: Raw configuration dict
+
+        Returns:
+            Validated and normalized configuration
+
+        Raises:
+            ValueError: If configuration is invalid
+        """
+        pass
+
+    @abstractmethod
+    def get_default_configuration(self) -> Dict[str, Any]:
+        """Get the default configuration for this skill"""
+        pass
+
+    def get_framework_class_name(self) -> str:
+        """
+        Get the underlying framework tool class name.
+        This is used for instantiation during agent execution.
+
+        Returns:
+            Class name (e.g., "FileTools", "ShellTools")
+        """
+        # Default mapping based on type
+        mapping = {
+            SkillType.FILE_SYSTEM: "FileTools",
+            SkillType.SHELL: "ShellTools",
+            SkillType.DOCKER: "DockerTools",
+            SkillType.PYTHON: "PythonTools",
+            SkillType.FILE_GENERATION: "FileGenerationTools",
+            SkillType.DATA_VISUALIZATION: "DataVisualizationTools",
+            SkillType.SLEEP: "SleepTools",
+            SkillType.CONTEXTUAL_AWARENESS: "ContextualAwarenessTools",
+            SkillType.AGENT_COMMUNICATION: "AgentCommunicationTools",
+            SkillType.REMOTE_FILESYSTEM: "RemoteFilesystemTools",
+        }
+        return mapping.get(self.type, "BaseTool")
+
+    def get_requirements(self) -> SkillRequirements:
+        """
+        Get runtime requirements for this skill.
+
+        Override this method to specify requirements like:
+        - Python packages
+        - System packages
+        - OS requirements
+        - Environment variables
+
+        Returns:
+            SkillRequirements instance
+        """
+        # Default: no special requirements
+        return SkillRequirements()
+
+    def check_requirements(self) -> tuple[bool, List[str]]:
+        """
+        Check if requirements are met in current environment.
+
+        Returns:
+            Tuple of (is_satisfied, missing_requirements)
+        """
+        requirements = self.get_requirements()
+        missing = []
+
+        # Check OS
+        if requirements.supported_os:
+            current_os = platform.system().lower()
+            if current_os not in requirements.supported_os:
+                missing.append(f"OS '{current_os}' not supported (requires: {', '.join(requirements.supported_os)})")
+
+        # Check Python version
+        if requirements.min_python_version:
+            import sys
+            from packaging import version
+            current_version = f"{sys.version_info.major}.{sys.version_info.minor}"
+            if version.parse(current_version) < version.parse(requirements.min_python_version):
+                missing.append(f"Python {requirements.min_python_version}+ required (current: {current_version})")
+
+        # Check environment variables
+        import os
+        for env_var in requirements.required_env_vars:
+            if not os.getenv(env_var):
+                missing.append(f"Environment variable '{env_var}' not set")
+
+        # Check Python packages (basic import check)
+        for package in requirements.python_packages:
+            package_name = package.split('[')[0].split('>=')[0].split('==')[0].strip()
+            try:
+                __import__(package_name)
+            except ImportError:
+                missing.append(f"Python package '{package}' not installed")
+
+        return len(missing) == 0, missing
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary representation"""
+        requirements = self.get_requirements()
+        is_satisfied, missing = self.check_requirements()
+
+        return {
+            "type": self.type.value,
+            "name": self.name,
+            "description": self.description,
+            "icon": self.icon,
+            "icon_type": self.icon_type,
+            "default_configuration": self.get_default_configuration(),
+            "variants": [v.model_dump() for v in self.get_variants()],
+            "framework_class": self.get_framework_class_name(),
+            "requirements": requirements.model_dump(),
+            "requirements_satisfied": is_satisfied,
+            "missing_requirements": missing,
+        }

control_plane_api/app/skills/builtin/__init__.py

@@ -0,0 +1,37 @@
+"""
+Built-in Skills Module
+
+Contains all built-in skill definitions that are part of the Control Plane.
+Each skill is in its own dedicated folder with proper structure.
+"""
+from .file_system import FileSystemSkill
+from .shell import ShellSkill
+from .python import PythonSkill
+from .docker import DockerSkill
+from .workflow_executor import WorkflowExecutorSkill
+from .file_generation import FileGenerationSkill
+from .data_visualization import DataVisualizationSkill
+from .contextual_awareness import ContextualAwarenessSkill
+from .knowledge_api import KnowledgeAPISkill
+from .cognitive_memory import CognitiveMemorySkill
+from .code_ingestion import CodeIngestionSkill
+from .agent_communication import AgentCommunicationSkill
+from .remote_filesystem import RemoteFilesystemSkill
+from .slack import SlackSkill
+
+__all__ = [
+    "FileSystemSkill",
+    "ShellSkill",
+    "PythonSkill",
+    "DockerSkill",
+    "WorkflowExecutorSkill",
+    "FileGenerationSkill",
+    "DataVisualizationSkill",
+    "ContextualAwarenessSkill",
+    "KnowledgeAPISkill",
+    "CognitiveMemorySkill",
+    "CodeIngestionSkill",
+    "AgentCommunicationSkill",
+    "RemoteFilesystemSkill",
+    "SlackSkill",
+]

control_plane_api/app/skills/builtin/agent_communication/__init__.py

@@ -0,0 +1,8 @@
+"""
+Agent Communication Skill
+
+Enables agents to call other agents or agent teams through tool calling.
+"""
+from .skill import AgentCommunicationSkill
+
+__all__ = ["AgentCommunicationSkill"]

control_plane_api/app/skills/builtin/agent_communication/skill.py

@@ -0,0 +1,246 @@
+"""
+Agent Communication Skill
+
+Provides agent-to-agent and agent-to-team communication capabilities.
+"""
+from typing import Dict, Any, List, Union, Literal, Optional
+from pydantic import BaseModel, Field, validator
+from control_plane_api.app.skills.base import SkillDefinition, SkillType, SkillCategory, SkillVariant
+from control_plane_api.app.skills.registry import register_skill
+
+
+class AgentCommunicationConfiguration(BaseModel):
+    """Configuration for Agent Communication Skill"""
+
+    allowed_operations: List[Literal[
+        "execute_agent",
+        "execute_team",
+        "followup_execution",
+        "get_execution_status"
+    ]] = Field(
+        default=["get_execution_status"],
+        description="List of allowed tool operations"
+    )
+
+    allowed_agents: Union[List[str], Literal["*"]] = Field(
+        default=[],
+        description="List of agent IDs that can be called, or '*' for all"
+    )
+
+    allowed_teams: Union[List[str], Literal["*"]] = Field(
+        default=[],
+        description="List of team IDs that can be called, or '*' for all"
+    )
+
+    max_execution_depth: int = Field(
+        default=2,
+        ge=0,
+        le=10,
+        description="Maximum nesting depth for child executions (0 = monitoring only)"
+    )
+
+    timeout: int = Field(
+        default=300,
+        ge=30,
+        le=3600,
+        description="Maximum wait time for child execution in seconds"
+    )
+
+    wait_for_completion: bool = Field(
+        default=True,
+        description="Whether to wait for child execution to complete (sync vs async)"
+    )
+
+    inherit_context: bool = Field(
+        default=True,
+        description="Whether to pass parent execution context to child"
+    )
+
+    max_concurrent_calls: int = Field(
+        default=3,
+        ge=1,
+        le=20,
+        description="Maximum number of concurrent child executions"
+    )
+
+    allow_session_continuation: bool = Field(
+        default=True,
+        description="Allow following up on existing sessions"
+    )
+
+    streaming_enabled: bool = Field(
+        default=True,
+        description="Stream child execution events to parent"
+    )
+
+    @validator('allowed_agents', 'allowed_teams')
+    def validate_allowed_entities(cls, v):
+        """Validate allowed entities format"""
+        if v == "*":
+            return v
+        if not isinstance(v, list):
+            raise ValueError("Must be a list of IDs or '*'")
+        return v
+
+
+class AgentCommunicationSkill(SkillDefinition):
+    """Agent communication skill - orchestrate hierarchical agent execution"""
+
+    @property
+    def type(self) -> SkillType:
+        return SkillType.AGENT_COMMUNICATION
+
+    @property
+    def name(self) -> str:
+        return "Agent Communication"
+
+    @property
+    def description(self) -> str:
+        return "Enable agents to call other agents or teams, creating hierarchical execution workflows"
+
+    @property
+    def icon(self) -> str:
+        return "Network"
+
+    def get_variants(self) -> List[SkillVariant]:
+        return [
+            SkillVariant(
+                id="agent_communication_read_only",
+                name="Agent Communication - Read Only",
+                description="Monitor execution status only. Cannot initiate agent calls. Safe for observability.",
+                category=SkillCategory.COMMON,
+                badge="Safe",
+                icon="Eye",
+                configuration={
+                    "allowed_operations": ["get_execution_status"],
+                    "allowed_agents": [],
+                    "allowed_teams": [],
+                    "max_execution_depth": 0,
+                    "timeout": 30,
+                    "wait_for_completion": False,
+                    "inherit_context": True,
+                    "max_concurrent_calls": 1,
+                    "allow_session_continuation": False,
+                    "streaming_enabled": True,
+                },
+                is_default=False,
+            ),
+            SkillVariant(
+                id="agent_communication_limited",
+                name="Agent Communication - Limited",
+                description="Call specific approved agents and teams with safeguards. Recommended for most use cases.",
+                category=SkillCategory.COMMON,
+                badge="Recommended",
+                icon="Network",
+                configuration={
+                    "allowed_operations": ["execute_agent", "execute_team", "followup_execution", "get_execution_status"],
+                    "allowed_agents": [],  # Must be explicitly configured
+                    "allowed_teams": [],   # Must be explicitly configured
+                    "max_execution_depth": 2,
+                    "timeout": 300,
+                    "wait_for_completion": True,
+                    "inherit_context": True,
+                    "max_concurrent_calls": 3,
+                    "allow_session_continuation": True,
+                    "streaming_enabled": True,
+                },
+                is_default=True,
+            ),
+            SkillVariant(
+                id="agent_communication_full",
+                name="Agent Communication - Full Orchestration",
+                description="Unrestricted agent orchestration for complex workflows. Advanced use cases only.",
+                category=SkillCategory.ADVANCED,
+                badge="Advanced",
+                icon="Workflow",
+                configuration={
+                    "allowed_operations": ["execute_agent", "execute_team", "followup_execution", "get_execution_status"],
+                    "allowed_agents": "*",
+                    "allowed_teams": "*",
+                    "max_execution_depth": 5,
+                    "timeout": 600,
+                    "wait_for_completion": True,
+                    "inherit_context": True,
+                    "max_concurrent_calls": 10,
+                    "allow_session_continuation": True,
+                    "streaming_enabled": True,
+                },
+                is_default=False,
+            ),
+        ]
+
+    def validate_configuration(self, config: Dict[str, Any]) -> Dict[str, Any]:
+        """Validate agent communication configuration"""
+        try:
+            # Validate using Pydantic model
+            validated_config = AgentCommunicationConfiguration(**config)
+            return validated_config.dict()
+        except Exception as e:
+            # Fallback to manual validation
+            validated = {}
+
+            # allowed_operations
+            allowed_ops = config.get("allowed_operations", ["get_execution_status"])
+            if not isinstance(allowed_ops, list):
+                allowed_ops = ["get_execution_status"]
+            validated["allowed_operations"] = allowed_ops
+
+            # allowed_agents
+            allowed_agents = config.get("allowed_agents", [])
+            if allowed_agents == "*":
+                validated["allowed_agents"] = "*"
+            elif isinstance(allowed_agents, list):
+                validated["allowed_agents"] = allowed_agents
+            else:
+                validated["allowed_agents"] = []
+
+            # allowed_teams
+            allowed_teams = config.get("allowed_teams", [])
+            if allowed_teams == "*":
+                validated["allowed_teams"] = "*"
+            elif isinstance(allowed_teams, list):
+                validated["allowed_teams"] = allowed_teams
+            else:
+                validated["allowed_teams"] = []
+
+            # max_execution_depth
+            validated["max_execution_depth"] = max(0, min(10, config.get("max_execution_depth", 2)))
+
+            # timeout
+            validated["timeout"] = max(30, min(3600, config.get("timeout", 300)))
+
+            # wait_for_completion
+            validated["wait_for_completion"] = bool(config.get("wait_for_completion", True))
+
+            # inherit_context
+            validated["inherit_context"] = bool(config.get("inherit_context", True))
+
+            # max_concurrent_calls
+            validated["max_concurrent_calls"] = max(1, min(20, config.get("max_concurrent_calls", 3)))
+
+            # allow_session_continuation
+            validated["allow_session_continuation"] = bool(config.get("allow_session_continuation", True))
+
+            # streaming_enabled
+            validated["streaming_enabled"] = bool(config.get("streaming_enabled", True))
+
+            return validated
+
+    def get_default_configuration(self) -> Dict[str, Any]:
+        """Default: limited agent calling with safeguards"""
+        return {
+            "allowed_operations": ["execute_agent", "execute_team", "followup_execution", "get_execution_status"],
+            "allowed_agents": [],
+            "allowed_teams": [],
+            "max_execution_depth": 2,
+            "timeout": 300,
+            "wait_for_completion": True,
+            "inherit_context": True,
+            "max_concurrent_calls": 3,
+            "allow_session_continuation": True,
+            "streaming_enabled": True,
+        }
+
+
+# Auto-register this skill
+register_skill(AgentCommunicationSkill())

control_plane_api/app/skills/builtin/code_ingestion/__init__.py

@@ -0,0 +1,4 @@
+"""Code Ingestion skill module"""
+from control_plane_api.app.skills.builtin.code_ingestion.skill import CodeIngestionSkill
+
+__all__ = ["CodeIngestionSkill"]