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

alita_sdk/runtime/toolkits/planning.py

@@ -0,0 +1,178 @@
+"""
+PlanningToolkit - Runtime toolkit for agent plan management.
+
+Provides tools for creating, tracking, and completing multi-step execution plans.
+Supports two storage backends:
+1. PostgreSQL - when pgvector_configuration with connection_string is provided
+2. Filesystem - when no connection string (local CLI usage)
+"""
+
+from typing import ClassVar, List, Any, Literal, Optional, Callable
+
+from langchain_community.agent_toolkits.base import BaseToolkit
+from langchain_core.tools import BaseTool
+from pydantic import create_model, BaseModel, ConfigDict, Field
+from pydantic.fields import FieldInfo
+
+from ..tools.planning import PlanningWrapper
+from ...tools.base.tool import BaseAction
+from ...tools.utils import clean_string, get_max_toolkit_length
+
+
+class PlanningToolkit(BaseToolkit):
+    """
+    Toolkit for agent plan management.
+    
+    Provides tools for creating, updating, and tracking execution plans.
+    Supports PostgreSQL (production) and filesystem (local) storage backends.
+    Plans are scoped by conversation_id.
+    """
+    tools: List[BaseTool] = []
+    _toolkit_max_length: ClassVar[int] = 50  # Use ClassVar to avoid Pydantic treating it as field
+    
+    @staticmethod
+    def toolkit_config_schema() -> BaseModel:
+        """
+        Returns the configuration schema for the Planning toolkit.
+        
+        Used by the UI to generate the toolkit configuration form.
+        """
+        # Define available tools
+        selected_tools = {
+            'update_plan': {
+                'title': 'UpdatePlanInput',
+                'type': 'object',
+                'properties': {
+                    'title': {'type': 'string', 'description': "Title for the plan"},
+                    'steps': {'type': 'array', 'items': {'type': 'string'}, 'description': "List of step descriptions"},
+                    'conversation_id': {'type': 'string', 'description': "Conversation ID (auto-injected)"}
+                },
+                'required': ['title', 'steps', 'conversation_id']
+            },
+            'complete_step': {
+                'title': 'CompleteStepInput', 
+                'type': 'object',
+                'properties': {
+                    'step_number': {'type': 'integer', 'description': "Step number to complete (1-indexed)"},
+                    'conversation_id': {'type': 'string', 'description': "Conversation ID (auto-injected)"}
+                },
+                'required': ['step_number', 'conversation_id']
+            },
+            'get_plan_status': {
+                'title': 'GetPlanStatusInput',
+                'type': 'object', 
+                'properties': {
+                    'conversation_id': {'type': 'string', 'description': "Conversation ID (auto-injected)"}
+                },
+                'required': ['conversation_id']
+            },
+            'delete_plan': {
+                'title': 'DeletePlanInput',
+                'type': 'object',
+                'properties': {
+                    'conversation_id': {'type': 'string', 'description': "Conversation ID (auto-injected)"}
+                },
+                'required': ['conversation_id']
+            }
+        }
+        
+        PlanningToolkit._toolkit_max_length = get_max_toolkit_length(selected_tools)
+        
+        return create_model(
+            "planning",
+            # Tool selection
+            selected_tools=(
+                List[Literal[tuple(selected_tools)]], 
+                Field(
+                    default=list(selected_tools.keys()),
+                    json_schema_extra={'args_schemas': selected_tools}
+                )
+            ),
+            __config__=ConfigDict(
+                json_schema_extra={
+                    'metadata': {
+                        "label": "Planning",
+                        "description": "Tools for managing multi-step execution plans with progress tracking. Uses PostgreSQL when configured, filesystem otherwise.",
+                        "icon_url": None,
+                        "max_length": PlanningToolkit._toolkit_max_length,
+                        "categories": ["planning", "internal_tool"],
+                        "extra_categories": ["task management", "todo", "progress tracking"]
+                    }
+                }
+            )
+        )
+    
+    @classmethod
+    def get_toolkit(
+        cls,
+        toolkit_name: Optional[str] = None,
+        selected_tools: Optional[List[str]] = None,
+        pgvector_configuration: Optional[dict] = None,
+        storage_dir: Optional[str] = None,
+        plan_callback: Optional[Any] = None,
+        conversation_id: Optional[str] = None,
+        **kwargs
+    ):
+        """
+        Create a PlanningToolkit instance with configured tools.
+        
+        Args:
+            toolkit_name: Optional name prefix for tools
+            selected_tools: List of tool names to include (default: all)
+            pgvector_configuration: PostgreSQL configuration dict with connection_string.
+                                   If not provided, uses filesystem storage.
+            storage_dir: Directory for filesystem storage (when no pgvector_configuration)
+            plan_callback: Optional callback function called when plan changes (for CLI UI)
+            conversation_id: Conversation ID for scoping plans.
+                            For server: from elitea_core payload. For CLI: session_id.
+            **kwargs: Additional configuration options
+            
+        Returns:
+            PlanningToolkit instance with configured tools
+        """
+        if selected_tools is None:
+            selected_tools = ['update_plan', 'complete_step', 'get_plan_status', 'delete_plan']
+        
+        tools = []
+        
+        # Extract connection string from pgvector configuration (if provided)
+        connection_string = None
+        if pgvector_configuration:
+            connection_string = pgvector_configuration.get('connection_string', '')
+            if hasattr(connection_string, 'get_secret_value'):
+                connection_string = connection_string.get_secret_value()
+        
+        # Create wrapper - it will auto-select storage backend
+        wrapper = PlanningWrapper(
+            connection_string=connection_string if connection_string else None,
+            conversation_id=conversation_id,
+            storage_dir=storage_dir,
+            plan_callback=plan_callback,
+        )
+        
+        # Use clean toolkit name for context (max 1000 chars in description)
+        toolkit_context = f" [Toolkit: {clean_string(toolkit_name, 0)}]" if toolkit_name else ''
+        
+        # Create tools from wrapper
+        available_tools = wrapper.get_available_tools()
+        for tool in available_tools:
+            if tool["name"] not in selected_tools:
+                continue
+            
+            # Add toolkit context to description with character limit
+            description = tool["description"]
+            if toolkit_context and len(description + toolkit_context) <= 1000:
+                description = description + toolkit_context
+            
+            tools.append(BaseAction(
+                api_wrapper=wrapper,
+                name=tool["name"],
+                description=description,
+                args_schema=tool["args_schema"]
+            ))
+        
+        return cls(tools=tools)
+    
+    def get_tools(self) -> List[BaseTool]:
+        """Return the list of configured tools."""
+        return self.tools

alita_sdk/runtime/toolkits/skill_router.py

@@ -0,0 +1,238 @@
+"""
+SkillRouter Toolkit for configuring and accessing specialized skills.
+
+This toolkit provides a configurable way to set up the skill router with
+specific skills from filesystem or platform-hosted agents/pipelines.
+"""
+
+from typing import List, Optional, TYPE_CHECKING
+from pydantic import create_model, BaseModel, Field, ConfigDict
+from langchain_community.agent_toolkits.base import BaseToolkit
+from langchain_core.tools import BaseTool
+
+if TYPE_CHECKING:
+    from alita_sdk.clients import AlitaClient
+
+from alita_sdk.tools.base.tool import BaseAction
+from alita_sdk.tools.utils import clean_string
+from ..skills import SkillsRegistry, SkillMetadata, SkillType, SkillSource
+from ..tools.skill_router import SkillRouterWrapper
+
+
+class SkillConfig(BaseModel):
+    """Configuration for a single skill."""
+
+    # Platform skill fields (type is implicit from parent field: agents or pipelines)
+    id: int = Field(description="Platform ID (for agent/pipeline skills)")
+    version_id: int = Field(description="Platform version ID (for agent/pipeline skills)")
+    name: Optional[str] = Field(default=None, description="Skill name (optional override)")
+
+
+class SkillRouterToolkit(BaseToolkit):
+    """Toolkit for configuring skill router with specific skills."""
+
+    tools: List[BaseTool] = []
+
+    @staticmethod
+    def toolkit_config_schema() -> BaseModel:
+        """Define the configuration schema for the skill router toolkit."""
+        # Get available tools for selected_tools field
+        selected_tools_options = {x['name']: x['args_schema'].schema() for x in SkillRouterWrapper.model_construct().get_available_tools()}
+        
+        return create_model(
+            "skill_router",
+            # Separate fields for agents and pipelines - optional but default to empty lists
+            agents=(Optional[List[SkillConfig]], Field(
+                description="List of agents to make available as skills",
+                default=[],
+                json_schema_extra={
+                    "agent_tags": ["skill"]
+                }
+            )),
+            pipelines=(Optional[List[SkillConfig]], Field(
+                description="List of pipelines to make available as skills",
+                default=[],
+                json_schema_extra={
+                    "pipeline_tags": ["skill"]
+                }
+            )),
+            prompt=(Optional[str], Field(
+                description="Custom system prompt for skill routing",
+                default="",
+                json_schema_extra={"lines": 4}
+            )),
+            timeout=(Optional[int], Field(description="Default timeout in seconds for skill execution", default=300)),
+            execution_mode=(Optional[str], Field(
+                description="Default execution mode for skills",
+                default=None,
+                json_schema_extra={"enum": ["subprocess", "remote"]}
+            )),
+            selected_tools=(List[str], Field(
+                description="List of tools to enable",
+                default=list(selected_tools_options.keys()),
+                json_schema_extra={'args_schemas': selected_tools_options}
+            )),
+            __config__=ConfigDict(json_schema_extra={'metadata': {"label": "Skill Router", "icon_url": None, "hidden": True}})
+        )
+
+    @classmethod
+    def get_toolkit(
+        cls,
+        client: 'AlitaClient',
+        llm = None,
+        toolkit_name: Optional[str] = None,
+        selected_tools: List[str] = None,
+        agents: List[SkillConfig] = None,
+        pipelines: List[SkillConfig] = None,
+        prompt: Optional[str] = None,
+        timeout: Optional[int] = None,
+        execution_mode: Optional[str] = None
+    ):
+        """Create a skill router toolkit with configured skills."""
+        
+        if selected_tools is None:
+            selected_tools = []
+
+        # Create a custom registry for this toolkit
+        registry = SkillsRegistry(search_paths=[])
+
+        # Helper function to process skill configs
+        def add_skills_to_registry(skill_configs, skill_type):
+            if skill_configs:
+                for skill_config_dict in skill_configs:
+                    # Convert dict to SkillConfig object
+                    skill_config = SkillConfig(**skill_config_dict)
+                    skill_metadata = cls._create_skill_from_config(skill_config, client, skill_type)
+                    if skill_metadata:
+                        # Add skill to registry manually
+                        registry.discovery.cache[skill_metadata.name] = skill_metadata
+
+        # Add configured agents (if provided)
+        add_skills_to_registry(agents or [], "agent")
+
+        # Add configured pipelines (if provided)
+        add_skills_to_registry(pipelines or [], "pipeline")
+
+        # Create skill router wrapper with custom configuration
+        wrapper = SkillRouterWrapper(
+            registry=registry,
+            alita_client=client,
+            llm=llm,
+            enable_callbacks=True,
+            default_timeout=timeout,
+            default_execution_mode=execution_mode,
+            custom_prompt=prompt
+        )
+        
+        # Get available tools from wrapper
+        available_tools = wrapper.get_available_tools()
+        
+        # Filter by selected_tools if provided
+        tools = []
+        toolkit_context = f" [Toolkit: {clean_string(toolkit_name, 0)}]" if toolkit_name else ''
+        
+        for tool in available_tools:
+            if selected_tools:
+                if tool["name"] not in selected_tools:
+                    continue
+            
+            # Add toolkit context to description with character limit
+            description = tool["description"]
+            if toolkit_context and len(description + toolkit_context) <= 1000:
+                description = description + toolkit_context
+            
+            # Wrap in BaseAction
+            tools.append(BaseAction(
+                api_wrapper=wrapper,
+                name=tool["name"],
+                description=description,
+                args_schema=tool["args_schema"],
+                metadata={"toolkit_name": toolkit_name, "toolkit_type": "skill_router"} if toolkit_name else {}
+            ))
+
+        return cls(tools=tools)
+
+    @classmethod
+    def _create_skill_from_config(cls, config: SkillConfig, client: 'AlitaClient', skill_type: str) -> Optional[SkillMetadata]:
+        """Create SkillMetadata from SkillConfig.
+        
+        Args:
+            config: SkillConfig with id, version_id, and optional name
+            client: AlitaClient for fetching skill details
+            skill_type: Either "agent" or "pipeline" (from parent field)
+        """
+        try:
+            # Get skill details from platform
+            if skill_type == "agent":
+                skill_details = cls._get_agent_details(client, config.id, config.version_id)
+                metadata_type = SkillType.AGENT
+            else:  # pipeline
+                skill_details = cls._get_pipeline_details(client, config.id, config.version_id)
+                metadata_type = SkillType.PIPELINE
+
+            # Create SkillMetadata for platform skill
+            return SkillMetadata(
+                name=config.name or skill_details.get('name', f"{skill_type}_{config.id}"),
+                skill_type=metadata_type,
+                source=SkillSource.PLATFORM,
+                id=config.id,
+                version_id=config.version_id,
+                description=skill_details.get('description', ''),
+                capabilities=skill_details.get('capabilities', []),
+                tags=skill_details.get('tags', []),
+                version=skill_details.get('version', '1.0.0'),
+                # Set default execution config - platform skills run remotely
+                execution={"mode": "remote", "timeout": 300},
+                results={"format": "text_with_links"},
+                inputs={},
+                outputs={}
+            )
+
+        except Exception as e:
+            import logging
+            logging.getLogger(__name__).error(f"Failed to create skill from config {config}: {e}")
+            return None
+
+    @classmethod
+    def _get_agent_details(cls, client: 'AlitaClient', agent_id: int, version_id: int) -> dict:
+        """Get agent details from platform."""
+        try:
+            app_details = client.get_app_details(agent_id)
+            version_details = client.get_app_version_details(agent_id, version_id)
+
+            return {
+                'name': app_details.get('name', f'agent_{agent_id}'),
+                'description': app_details.get('description', ''),
+                'capabilities': [], # Could be extracted from app metadata
+                'tags': [], # Could be extracted from app metadata
+                'version': version_details.get('version', '1.0.0')
+            }
+        except Exception as e:
+            import logging
+            logging.getLogger(__name__).error(f"Failed to get agent details for {agent_id}/{version_id}: {e}")
+            return {'name': f'agent_{agent_id}', 'description': 'Platform-hosted agent'}
+
+    @classmethod
+    def _get_pipeline_details(cls, client: 'AlitaClient', pipeline_id: int, version_id: int) -> dict:
+        """Get pipeline details from platform."""
+        try:
+            # For now, use the same method as agents since they use the same API
+            # In the future, this might use a different endpoint for pipelines
+            app_details = client.get_app_details(pipeline_id)
+            version_details = client.get_app_version_details(pipeline_id, version_id)
+
+            return {
+                'name': app_details.get('name', f'pipeline_{pipeline_id}'),
+                'description': app_details.get('description', ''),
+                'capabilities': [], # Could be extracted from pipeline metadata
+                'tags': [], # Could be extracted from pipeline metadata
+                'version': version_details.get('version', '1.0.0')
+            }
+        except Exception as e:
+            import logging
+            logging.getLogger(__name__).error(f"Failed to get pipeline details for {pipeline_id}/{version_id}: {e}")
+            return {'name': f'pipeline_{pipeline_id}', 'description': 'Platform-hosted pipeline'}
+
+    def get_tools(self):
+        """Get the configured tools."""
+        return self.tools