alita-sdk 0.3.379__py3-none-any.whl → 0.3.627__py3-none-any.whl

alita_sdk/runtime/skills/input_builder.py

@@ -0,0 +1,371 @@
+"""
+Input preparation for different skill types.
+
+This module handles the preparation of input data for skill execution,
+ensuring that inputs are properly formatted for agent vs graph skill types.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from .models import SkillMetadata, SkillType, SkillValidationError
+
+logger = logging.getLogger(__name__)
+
+
+class SkillInputBuilder:
+    """
+    Service for building properly formatted inputs for different skill types.
+
+    This class handles the different input requirements for:
+    - Agent skills: variables, chat_history, and user input
+    - Graph skills: state variables with input field
+    """
+
+    @staticmethod
+    def prepare_input(
+        skill_metadata: SkillMetadata,
+        task: str,
+        context: Optional[Dict[str, Any]] = None,
+        chat_history: Optional[List[Dict[str, str]]] = None
+    ) -> Dict[str, Any]:
+        """
+        Prepare input data based on skill type.
+
+        Args:
+            skill_metadata: Metadata for the skill being executed.
+            task: The main task or user input for the skill.
+            context: Additional context data (variables for agents, state for graphs).
+            chat_history: Chat conversation history (for agents only).
+
+        Returns:
+            Properly formatted input dictionary for the skill type.
+
+        Raises:
+            SkillValidationError: If input preparation fails validation.
+        """
+        if skill_metadata.skill_type == SkillType.AGENT:
+            return SkillInputBuilder.prepare_agent_input(
+                skill_metadata, task, context, chat_history
+            )
+        else:  # SkillType.GRAPH
+            return SkillInputBuilder.prepare_graph_input(
+                skill_metadata, task, context
+            )
+
+    @staticmethod
+    def prepare_agent_input(
+        skill_metadata: SkillMetadata,
+        task: str,
+        context: Optional[Dict[str, Any]] = None,
+        chat_history: Optional[List[Dict[str, str]]] = None
+    ) -> Dict[str, Any]:
+        """
+        Prepare input for agent-type skills.
+
+        Agent skills expect:
+        - variables: Skill-specific variables from context
+        - chat_history: Previous conversation messages
+        - input: Current user request/task
+
+        Args:
+            skill_metadata: Metadata for the agent skill.
+            task: User input/task for the agent.
+            context: Variables to pass to the agent.
+            chat_history: Conversation history.
+
+        Returns:
+            Agent input dictionary.
+
+        Raises:
+            SkillValidationError: If required inputs are missing or invalid.
+        """
+        logger.debug(f"Preparing agent input for skill: {skill_metadata.name}")
+
+        if not task:
+            raise SkillValidationError("Task is required for agent skills")
+
+        # Validate chat_history format if provided
+        if chat_history:
+            SkillInputBuilder._validate_chat_history(chat_history)
+
+        # Validate context variables against schema if defined
+        variables = context or {}
+        if skill_metadata.inputs.variables:
+            variables = SkillInputBuilder._validate_agent_variables(
+                variables, skill_metadata.inputs.variables
+            )
+
+        agent_input = {
+            'variables': variables,
+            'chat_history': chat_history or [],
+            'input': task
+        }
+
+        logger.debug(f"Prepared agent input: variables={len(variables)}, "
+                    f"chat_history={len(chat_history or [])}, task_length={len(task)}")
+
+        return agent_input
+
+    @staticmethod
+    def prepare_graph_input(
+        skill_metadata: SkillMetadata,
+        task: str,
+        context: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        Prepare input for graph-type skills.
+
+        Graph skills expect state variables with the task merged in
+        as the 'input' field.
+
+        Args:
+            skill_metadata: Metadata for the graph skill.
+            task: Task description to be included as 'input'.
+            context: State variables for the graph.
+
+        Returns:
+            Graph state input dictionary.
+
+        Raises:
+            SkillValidationError: If required inputs are missing or invalid.
+        """
+        logger.debug(f"Preparing graph input for skill: {skill_metadata.name}")
+
+        # Start with context (state variables)
+        state_vars = context.copy() if context else {}
+
+        # Add task as 'input' field (standard for graphs)
+        state_vars['input'] = task
+
+        # Validate state variables against schema if defined
+        if skill_metadata.inputs.state_variables:
+            state_vars = SkillInputBuilder._validate_graph_state_variables(
+                state_vars, skill_metadata.inputs.state_variables
+            )
+
+        logger.debug(f"Prepared graph input: {len(state_vars)} state variables")
+
+        return state_vars
+
+    @staticmethod
+    def _validate_chat_history(chat_history: List[Dict[str, str]]) -> None:
+        """
+        Validate chat history format.
+
+        Args:
+            chat_history: List of message dictionaries.
+
+        Raises:
+            SkillValidationError: If format is invalid.
+        """
+        if not isinstance(chat_history, list):
+            raise SkillValidationError("chat_history must be a list")
+
+        for i, message in enumerate(chat_history):
+            if not isinstance(message, dict):
+                raise SkillValidationError(f"chat_history[{i}] must be a dictionary")
+
+            if 'role' not in message:
+                raise SkillValidationError(f"chat_history[{i}] missing 'role' field")
+
+            if 'content' not in message:
+                raise SkillValidationError(f"chat_history[{i}] missing 'content' field")
+
+            if message['role'] not in ['user', 'assistant', 'system']:
+                logger.warning(f"Unusual role in chat_history[{i}]: {message['role']}")
+
+    @staticmethod
+    def _validate_agent_variables(
+        variables: Dict[str, Any],
+        variable_schema: Dict[str, Dict[str, Any]]
+    ) -> Dict[str, Any]:
+        """
+        Validate agent variables against schema.
+
+        Args:
+            variables: Variables to validate.
+            variable_schema: Schema definition for variables.
+
+        Returns:
+            Validated variables with defaults applied.
+
+        Raises:
+            SkillValidationError: If validation fails.
+        """
+        validated_vars = variables.copy()
+
+        # Check for required variables and apply defaults
+        for var_name, var_def in variable_schema.items():
+            if var_name not in validated_vars:
+                if 'default' in var_def:
+                    validated_vars[var_name] = var_def['default']
+                    logger.debug(f"Applied default for variable '{var_name}': {var_def['default']}")
+                elif var_def.get('required', False):
+                    raise SkillValidationError(f"Required variable '{var_name}' not provided")
+
+            # Basic type validation (could be expanded)
+            if var_name in validated_vars:
+                expected_type = var_def.get('type')
+                if expected_type:
+                    SkillInputBuilder._validate_variable_type(
+                        var_name, validated_vars[var_name], expected_type
+                    )
+
+        return validated_vars
+
+    @staticmethod
+    def _validate_graph_state_variables(
+        state_vars: Dict[str, Any],
+        state_schema: Dict[str, Dict[str, Any]]
+    ) -> Dict[str, Any]:
+        """
+        Validate graph state variables against schema.
+
+        Args:
+            state_vars: State variables to validate.
+            state_schema: Schema definition for state variables.
+
+        Returns:
+            Validated state variables with defaults applied.
+
+        Raises:
+            SkillValidationError: If validation fails.
+        """
+        validated_vars = state_vars.copy()
+
+        # Check for required state variables and apply defaults
+        for var_name, var_def in state_schema.items():
+            if var_name not in validated_vars:
+                if 'default' in var_def:
+                    validated_vars[var_name] = var_def['default']
+                    logger.debug(f"Applied default for state variable '{var_name}': {var_def['default']}")
+                elif var_def.get('required', False):
+                    raise SkillValidationError(f"Required state variable '{var_name}' not provided")
+
+            # Basic type validation
+            if var_name in validated_vars:
+                expected_type = var_def.get('type')
+                if expected_type:
+                    SkillInputBuilder._validate_variable_type(
+                        var_name, validated_vars[var_name], expected_type
+                    )
+
+        return validated_vars
+
+    @staticmethod
+    def _validate_variable_type(var_name: str, value: Any, expected_type: str) -> None:
+        """
+        Validate a variable against its expected type.
+
+        Args:
+            var_name: Name of the variable (for error messages).
+            value: Value to validate.
+            expected_type: Expected type string.
+
+        Raises:
+            SkillValidationError: If type validation fails.
+        """
+        # Simple type checking - could be made more sophisticated
+        type_map = {
+            'str': str,
+            'string': str,
+            'int': int,
+            'integer': int,
+            'float': float,
+            'number': (int, float),
+            'bool': bool,
+            'boolean': bool,
+            'dict': dict,
+            'list': list
+        }
+
+        expected_python_type = type_map.get(expected_type.lower())
+        if expected_python_type and not isinstance(value, expected_python_type):
+            raise SkillValidationError(
+                f"Variable '{var_name}' expected type {expected_type}, "
+                f"got {type(value).__name__}"
+            )
+
+    @staticmethod
+    def validate_skill_inputs(
+        skill_metadata: SkillMetadata,
+        task: str,
+        context: Optional[Dict[str, Any]] = None,
+        chat_history: Optional[List[Dict[str, str]]] = None
+    ) -> List[str]:
+        """
+        Validate inputs for a skill without preparing them.
+
+        This can be used to check if inputs are valid before execution.
+
+        Args:
+            skill_metadata: Metadata for the skill.
+            task: Task to validate.
+            context: Context data to validate.
+            chat_history: Chat history to validate (for agents).
+
+        Returns:
+            List of validation error messages (empty if all valid).
+        """
+        errors = []
+
+        try:
+            SkillInputBuilder.prepare_input(
+                skill_metadata, task, context, chat_history
+            )
+        except SkillValidationError as e:
+            errors.append(str(e))
+        except Exception as e:
+            errors.append(f"Unexpected validation error: {e}")
+
+        return errors
+
+    @staticmethod
+    def get_input_schema_summary(skill_metadata: SkillMetadata) -> Dict[str, Any]:
+        """
+        Get a human-readable summary of the skill's input schema.
+
+        Args:
+            skill_metadata: Metadata for the skill.
+
+        Returns:
+            Dictionary summarizing the input requirements.
+        """
+        summary = {
+            'skill_name': skill_metadata.name,
+            'skill_type': skill_metadata.skill_type.value,
+            'requires_task': True  # All skills require a task
+        }
+
+        if skill_metadata.skill_type == SkillType.AGENT:
+            summary.update({
+                'supports_chat_history': True,
+                'variables': {}
+            })
+
+            if skill_metadata.inputs.variables:
+                for var_name, var_def in skill_metadata.inputs.variables.items():
+                    summary['variables'][var_name] = {
+                        'type': var_def.get('type', 'any'),
+                        'required': var_def.get('required', False),
+                        'description': var_def.get('description', ''),
+                        'default': var_def.get('default')
+                    }
+
+        else:  # GRAPH
+            summary.update({
+                'supports_chat_history': False,
+                'state_variables': {}
+            })
+
+            if skill_metadata.inputs.state_variables:
+                for var_name, var_def in skill_metadata.inputs.state_variables.items():
+                    summary['state_variables'][var_name] = {
+                        'type': var_def.get('type', 'any'),
+                        'required': var_def.get('required', False),
+                        'description': var_def.get('description', ''),
+                        'default': var_def.get('default')
+                    }
+
+        return summary

alita_sdk/runtime/skills/models.py

@@ -0,0 +1,330 @@
+"""
+Core data models for the Skills Registry system.
+
+This module defines the data structures used throughout the skills system,
+including skill metadata, execution configuration, and result formats.
+"""
+
+import logging
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+
+class SkillType(str, Enum):
+    """Skill execution architecture type."""
+    GRAPH = "graph"
+    AGENT = "agent"
+    PIPELINE = "pipeline"
+
+
+class SkillSource(str, Enum):
+    """Source type for skill definitions."""
+    FILESYSTEM = "filesystem"  # Local agent.md files
+    PLATFORM = "platform"     # Platform-hosted agents/pipelines
+
+
+class ExecutionMode(str, Enum):
+    """Skill execution isolation mode."""
+    SUBPROCESS = "subprocess"
+    REMOTE = "remote"
+
+
+class SkillStatus(str, Enum):
+    """Skill execution status."""
+    SUCCESS = "success"
+    ERROR = "error"
+    TIMEOUT = "timeout"
+    RUNNING = "running"
+    PENDING = "pending"
+
+
+class SkillEventType(str, Enum):
+    """Callback event types for skill execution."""
+    SKILL_START = "skill_start"
+    SKILL_END = "skill_end"
+    NODE_START = "node_start"
+    NODE_END = "node_end"
+    TOOL_START = "tool_start"
+    TOOL_END = "tool_end"
+    LLM_START = "llm_start"
+    LLM_END = "llm_end"
+    ERROR = "error"
+    PROGRESS = "progress"
+    CUSTOM_EVENT = "custom_event"
+
+
+class ExecutionConfig(BaseModel):
+    """Configuration for skill execution."""
+
+    mode: ExecutionMode = ExecutionMode.SUBPROCESS
+    timeout: int = Field(default=300, description="Execution timeout in seconds")
+    working_directory: Optional[str] = Field(
+        default=None,
+        description="Working directory for skill execution"
+    )
+    environment: Dict[str, str] = Field(
+        default_factory=dict,
+        description="Environment variables for skill execution"
+    )
+    max_retries: int = Field(default=0, description="Maximum retry attempts")
+
+    class Config:
+        use_enum_values = True
+
+
+class ResultsConfig(BaseModel):
+    """Configuration for skill result handling."""
+
+    format: Literal["text_with_links"] = "text_with_links"
+    output_files: List[str] = Field(
+        default_factory=list,
+        description="Expected output file patterns"
+    )
+    cleanup_policy: Literal["preserve", "cleanup"] = Field(
+        default="preserve",
+        description="Policy for cleaning up working directory"
+    )
+
+    class Config:
+        use_enum_values = True
+
+
+class SkillInputSchema(BaseModel):
+    """Schema definition for skill inputs."""
+
+    # Common fields
+    description: Optional[str] = None
+
+    # Agent-specific inputs
+    variables: Optional[Dict[str, Dict[str, Any]]] = Field(
+        default=None,
+        description="Variable definitions for agent skills"
+    )
+    chat_history: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Chat history schema for agent skills"
+    )
+    user_input: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="User input schema for agent skills"
+    )
+
+    # Graph-specific inputs
+    state_variables: Optional[Dict[str, Dict[str, Any]]] = Field(
+        default=None,
+        description="State variable definitions for graph skills"
+    )
+
+
+class SkillOutputSchema(BaseModel):
+    """Schema definition for skill outputs."""
+
+    primary_output: Dict[str, Any] = Field(
+        default={"type": "text", "description": "Main result text"},
+        description="Primary text output schema"
+    )
+    generated_files: Dict[str, Any] = Field(
+        default={"type": "list[file_reference]", "description": "Created files"},
+        description="File references schema"
+    )
+    additional_outputs: Optional[Dict[str, Dict[str, Any]]] = Field(
+        default=None,
+        description="Additional skill-specific outputs"
+    )
+
+
+class SkillMetadata(BaseModel):
+    """Complete metadata for a skill definition."""
+
+    # Core identification
+    name: str = Field(description="Unique skill identifier")
+    skill_type: SkillType = Field(description="Skill architecture type")
+    source: SkillSource = Field(description="Source type for skill definition")
+
+    # Filesystem-based skill fields
+    path: Optional[str] = Field(
+        default=None,
+        description="Directory path containing agent.md (for filesystem skills)"
+    )
+
+    # Platform-based skill fields
+    id: Optional[int] = Field(
+        default=None,
+        description="Platform ID (for platform-hosted skills)"
+    )
+    version_id: Optional[int] = Field(
+        default=None,
+        description="Platform version ID (for platform-hosted skills)"
+    )
+
+    # Descriptive metadata
+    description: str = Field(description="Human-readable skill description")
+    capabilities: List[str] = Field(
+        default_factory=list,
+        description="List of capabilities this skill provides"
+    )
+    tags: List[str] = Field(
+        default_factory=list,
+        description="Tags for categorization and filtering"
+    )
+    version: str = Field(default="1.0.0", description="Skill version")
+
+    # Configuration
+    execution: ExecutionConfig = Field(description="Execution configuration")
+    results: ResultsConfig = Field(description="Result handling configuration")
+
+    # Input/Output schemas
+    inputs: SkillInputSchema = Field(description="Input schema definition")
+    outputs: SkillOutputSchema = Field(description="Output schema definition")
+
+    # Type-specific configurations
+    # Graph-specific fields
+    state_schema: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="State schema for graph skills"
+    )
+    nodes: Optional[List[Dict[str, Any]]] = Field(
+        default=None,
+        description="Node definitions for graph skills"
+    )
+    graph_yaml: Optional[str] = Field(
+        default=None,
+        description="Complete YAML definition for graph skills"
+    )
+
+    # Agent-specific fields
+    system_prompt: Optional[str] = Field(
+        default=None,
+        description="System prompt for agent skills"
+    )
+    agent_type: Optional[str] = Field(
+        default=None,
+        description="Agent architecture type (react, xml, etc.)"
+    )
+    toolkits: Optional[List[Dict[str, Any]]] = Field(
+        default=None,
+        description="Toolkit configurations for agent skills"
+    )
+
+    # LLM configuration
+    model: Optional[str] = Field(default=None, description="Default LLM model")
+    temperature: Optional[float] = Field(default=None, description="LLM temperature")
+    max_tokens: Optional[int] = Field(default=None, description="Max tokens")
+
+    class Config:
+        use_enum_values = True
+
+
+class SkillOutputFile(BaseModel):
+    """Reference to a file generated by skill execution."""
+
+    path: Path = Field(description="Path to the generated file")
+    description: str = Field(description="Human-readable file description")
+    file_type: str = Field(description="File type (json, markdown, csv, etc.)")
+    size_bytes: int = Field(description="File size in bytes")
+
+    def __str__(self) -> str:
+        """Format for LLM consumption."""
+        size_kb = self.size_bytes / 1024
+        if size_kb < 1:
+            size_str = f"{self.size_bytes} bytes"
+        else:
+            size_str = f"{size_kb:.1f}KB"
+
+        return f"[{self.description}]({self.path}) ({self.file_type}, {size_str})"
+
+
+class SkillExecutionResult(BaseModel):
+    """Result of skill execution with text output and file references."""
+
+    # Execution metadata
+    skill_name: str = Field(description="Name of executed skill")
+    skill_type: SkillType = Field(description="Type of skill executed")
+    status: SkillStatus = Field(description="Execution status")
+    execution_mode: ExecutionMode = Field(description="Execution mode used")
+    execution_id: str = Field(description="Unique execution identifier")
+
+    # Results
+    output_text: str = Field(description="Primary text output for LLM consumption")
+    output_files: List[SkillOutputFile] = Field(
+        default_factory=list,
+        description="Generated files with descriptions"
+    )
+
+    # Execution details
+    duration: float = Field(description="Execution duration in seconds")
+    working_directory: Optional[Path] = Field(
+        default=None,
+        description="Working directory used for execution"
+    )
+
+    # Error information
+    error_details: Optional[str] = Field(
+        default=None,
+        description="Error details if status is ERROR"
+    )
+
+    # Additional metadata
+    metadata: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional execution metadata"
+    )
+
+    class Config:
+        use_enum_values = True
+
+    def format_for_llm(self) -> str:
+        """Format result as text suitable for LLM consumption."""
+        result = self.output_text
+
+        if self.output_files:
+            result += "\n\n**Generated Files:**\n"
+            for file in self.output_files:
+                result += f"- {file}\n"
+
+        if self.status == SkillStatus.ERROR and self.error_details:
+            result += f"\n\n**Error:** {self.error_details}"
+
+        return result
+
+
+@dataclass
+class SkillEvent:
+    """Event emitted during skill execution."""
+
+    event_type: SkillEventType
+    data: Dict[str, Any]
+    skill_name: str
+    execution_id: str
+    timestamp: float
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "event_type": self.event_type.value,
+            "data": self.data,
+            "skill_name": self.skill_name,
+            "execution_id": self.execution_id,
+            "timestamp": self.timestamp
+        }
+
+
+class SkillDiscoveryError(Exception):
+    """Exception raised during skill discovery."""
+    pass
+
+
+class SkillValidationError(Exception):
+    """Exception raised during skill validation."""
+    pass
+
+
+class SkillExecutionError(Exception):
+    """Exception raised during skill execution."""
+    pass