alita-sdk 0.3.528__py3-none-any.whl → 0.3.554__py3-none-any.whl

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}})
+        )
+
+    @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} 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

alita_sdk/runtime/toolkits/tools.py

@@ -14,6 +14,7 @@ from .prompt import PromptToolkit
 from .subgraph import SubgraphToolkit
 from .vectorstore import VectorStoreToolkit
 from .mcp import McpToolkit
+from .skill_router import SkillRouterToolkit
 from ..tools.mcp_server_tool import McpServerTool
 from ..tools.sandbox import SandboxToolkit
 from ..tools.image_generation import ImageGenerationToolkit
@@ -35,19 +36,50 @@ def get_toolkits():
         VectorStoreToolkit.toolkit_config_schema(),
         SandboxToolkit.toolkit_config_schema(),
         ImageGenerationToolkit.toolkit_config_schema(),
-        McpToolkit.toolkit_config_schema()
+        McpToolkit.toolkit_config_schema(),
+        SkillRouterToolkit.toolkit_config_schema()
     ]
 
     return core_toolkits + community_toolkits() + alita_toolkits()
 
 
 def get_tools(tools_list: list, alita_client=None, llm=None, memory_store: BaseStore = None, debug_mode: Optional[bool] = False, mcp_tokens: Optional[dict] = None, conversation_id: Optional[str] = None, ignored_mcp_servers: Optional[list] = None) -> list:
+    # Sanitize tools_list to handle corrupted tool configurations
+    sanitized_tools = []
+    for tool in tools_list:
+        if isinstance(tool, dict):
+            # Check for corrupted structure where 'type' and 'name' contain the full tool config
+            if 'type' in tool and isinstance(tool['type'], dict):
+                # This is a corrupted tool - use the inner dict instead
+                logger.warning(f"Detected corrupted tool configuration (type=dict), fixing: {tool}")
+                actual_tool = tool['type']  # or tool['name'], they should be the same
+                sanitized_tools.append(actual_tool)
+            elif 'name' in tool and isinstance(tool['name'], dict):
+                # Another corruption pattern where name contains the full config
+                logger.warning(f"Detected corrupted tool configuration (name=dict), fixing: {tool}")
+                actual_tool = tool['name']
+                sanitized_tools.append(actual_tool)
+            elif 'type' in tool and isinstance(tool['type'], str):
+                # Valid tool configuration
+                sanitized_tools.append(tool)
+            else:
+                # Skip invalid/corrupted tools that can't be fixed
+                logger.warning(f"Skipping invalid tool configuration: {tool}")
+        else:
+            logger.warning(f"Skipping non-dict tool: {tool}")
+            # Skip non-dict tools
+
     prompts = []
     tools = []
+    unhandled_tools = []  # Track tools not handled by main processing
 
-    for tool in tools_list:
+    for tool in sanitized_tools:
+        # Flag to track if this tool was processed by the main loop
+        # Used to prevent double processing by fallback systems
+        tool_handled = False
         try:
             if tool['type'] == 'datasource':
+                tool_handled = True
                 tools.extend(DatasourcesToolkit.get_toolkit(
                     alita_client,
                     datasource_ids=[int(tool['settings']['datasource_id'])],
@@ -55,6 +87,7 @@ def get_tools(tools_list: list, alita_client=None, llm=None, memory_store: BaseS
                     toolkit_name=tool.get('toolkit_name', '') or tool.get('name', '')
                 ).get_tools())
             elif tool['type'] == 'application':
+                tool_handled = True
                 tools.extend(ApplicationToolkit.get_toolkit(
                     alita_client,
                     application_id=int(tool['settings']['application_id']),
@@ -74,6 +107,7 @@ def get_tools(tools_list: list, alita_client=None, llm=None, memory_store: BaseS
                         llm=llm
                     ))
             elif tool['type'] == 'memory':
+                tool_handled = True
                 tools += MemoryToolkit.get_toolkit(
                     namespace=tool['settings'].get('namespace', str(tool['id'])),
                     pgvector_configuration=tool['settings'].get('pgvector_configuration', {}),
@@ -81,6 +115,7 @@ def get_tools(tools_list: list, alita_client=None, llm=None, memory_store: BaseS
                 ).get_tools()
             # TODO: update configuration of internal tools
             elif tool['type'] == 'internal_tool':
+                tool_handled = True
                 if tool['name'] == 'pyodide':
                     tools += SandboxToolkit.get_toolkit(
                         stateful=False,
@@ -101,6 +136,7 @@ def get_tools(tools_list: list, alita_client=None, llm=None, memory_store: BaseS
                         conversation_id=conversation_id,
                     ).get_tools()
             elif tool['type'] == 'artifact':
+                tool_handled = True
                 toolkit_tools = ArtifactToolkit.get_toolkit(
                     client=alita_client,
                     bucket=tool['settings']['bucket'],
@@ -119,11 +155,13 @@ def get_tools(tools_list: list, alita_client=None, llm=None, memory_store: BaseS
                 tools.extend(toolkit_tools)
 
             elif tool['type'] == 'vectorstore':
+                tool_handled = True
                 tools.extend(VectorStoreToolkit.get_toolkit(
                     llm=llm,
                     toolkit_name=tool.get('toolkit_name', ''),
                     **tool['settings']).get_tools())
             elif tool['type'] == 'planning':
+                tool_handled = True
                 # Planning toolkit for multi-step task tracking
                 settings = tool.get('settings', {})
                 
@@ -163,6 +201,7 @@ def get_tools(tools_list: list, alita_client=None, llm=None, memory_store: BaseS
                     conversation_id=conversation_id or settings.get('conversation_id'),
                 ).get_tools())
             elif tool['type'] == 'mcp':
+                tool_handled = True
                 # remote mcp tool initialization with token injection
                 settings = dict(tool['settings'])
                 url = settings.get('url')
@@ -214,6 +253,28 @@ def get_tools(tools_list: list, alita_client=None, llm=None, memory_store: BaseS
                     toolkit_name=tool.get('toolkit_name', ''),
                     client=alita_client,
                     **settings).get_tools())
+            elif tool['type'] == 'skill_router':
+                tool_handled = True
+                # Skills Registry Router Toolkit
+                logger.info(f"Processing skill_router toolkit: {tool}")
+                try:
+                    settings = tool.get('settings', {})
+                    toolkit_name = tool.get('toolkit_name', '')
+                    selected_tools = settings.get('selected_tools', [])
+                    
+                    toolkit_tools = SkillRouterToolkit.get_toolkit(
+                        client=alita_client,
+                        llm=llm,
+                        toolkit_name=toolkit_name,
+                        selected_tools=selected_tools,
+                        **settings
+                    ).get_tools()
+
+                    tools.extend(toolkit_tools)
+                    logger.info(f"✅ Successfully added {len(toolkit_tools)} tools from SkillRouterToolkit")
+                except Exception as e:
+                    logger.error(f"❌ Failed to initialize SkillRouterToolkit: {e}")
+                    raise
         except McpAuthorizationRequired:
             # Re-raise auth required exceptions directly
             raise
@@ -224,17 +285,23 @@ def get_tools(tools_list: list, alita_client=None, llm=None, memory_store: BaseS
                 continue
             else:
                 raise ToolException(f"Error initializing toolkit for tool '{tool.get('name', 'unknown')}': {e}")
-    
+
+        # Track unhandled tools (make a copy to avoid reference issues)
+        if not tool_handled:
+            # Ensure we only add valid tool configurations to unhandled_tools
+            if isinstance(tool, dict) and 'type' in tool and isinstance(tool['type'], str):
+                unhandled_tools.append(dict(tool))
+
     if len(prompts) > 0:
         tools += PromptToolkit.get_toolkit(alita_client, prompts).get_tools()
-    
-    # Add community tools
-    tools += community_tools(tools_list, alita_client, llm)
-    # Add alita tools
-    tools += alita_tools(tools_list, alita_client, llm, memory_store)
+
+    # Add community tools (only for unhandled tools)
+    tools += community_tools(unhandled_tools, alita_client, llm)
+    # Add alita tools (only for unhandled tools)
+    tools += alita_tools(unhandled_tools, alita_client, llm, memory_store)
     # Add MCP tools registered via alita-mcp CLI (static registry)
     # Note: Tools with type='mcp' are already handled in main loop above
-    tools += _mcp_tools(tools_list, alita_client)
+    tools += _mcp_tools(unhandled_tools, alita_client)
     
     # Sanitize tool names to meet OpenAI's function naming requirements
     # tools = _sanitize_tool_names(tools)

alita_sdk/runtime/tools/__init__.py

@@ -10,6 +10,7 @@ from .image_generation import (
     create_image_generation_tool,
     ImageGenerationToolkit
 )
+from .skill_router import SkillRouterWrapper
 
 __all__ = [
     "PyodideSandboxTool",
@@ -18,5 +19,6 @@ __all__ = [
     "EchoTool",
     "ImageGenerationTool",
     "ImageGenerationToolkit",
-    "create_image_generation_tool"
+    "create_image_generation_tool",
+    "SkillRouterWrapper"
 ]

alita_sdk/runtime/tools/artifact.py

@@ -1,3 +1,4 @@
+import base64
 import hashlib
 import io
 import json
@@ -14,7 +15,7 @@ from pydantic import create_model, Field, model_validator
 from ...tools.non_code_indexer_toolkit import NonCodeIndexerToolkit
 from ...tools.utils.available_tools_decorator import extend_with_parent_available_tools
 from ...tools.elitea_base import extend_with_file_operations, BaseCodeToolApiWrapper
-from ...runtime.utils.utils import IndexerKeywords
+from ...runtime.utils.utils import IndexerKeywords, resolve_image_from_cache
 
 
 class ArtifactWrapper(NonCodeIndexerToolkit):
@@ -63,23 +64,30 @@ class ArtifactWrapper(NonCodeIndexerToolkit):
         if was_modified:
             logging.warning(f"Filename sanitized: '{filename}' -> '{sanitized_filename}'")
         
+        # Auto-detect and extract base64 from image_url structures (from image_generation tool)
+        # Returns tuple: (processed_data, is_from_image_generation)
+        filedata, is_from_image_generation = self._extract_base64_if_needed(filedata)
+        
         if sanitized_filename.endswith(".xlsx"):
             data = json.loads(filedata)
             filedata = self.create_xlsx_filedata(data)
 
         result = self.artifact.create(sanitized_filename, filedata, bucket_name)
         
-        # Dispatch custom event for file creation
-        dispatch_custom_event("file_modified", {
-            "message": f"File '{filename}' created successfully",
-            "filename": filename,
-            "tool_name": "createFile",
-            "toolkit": "artifact",
-            "operation_type": "create",
-            "meta": {
-                "bucket": bucket_name or self.bucket
-            }
-        })
+        # Skip file_modified event for images from image_generation tool
+        # These are already tracked in the tool output and don't need duplicate events
+        if not is_from_image_generation:
+            # Dispatch custom event for file creation
+            dispatch_custom_event("file_modified", {
+                "message": f"File '{filename}' created successfully",
+                "filename": filename,
+                "tool_name": "createFile",
+                "toolkit": "artifact",
+                "operation_type": "create",
+                "meta": {
+                    "bucket": bucket_name or self.bucket
+                }
+            })
 
         return result
     
@@ -109,6 +117,43 @@ class ArtifactWrapper(NonCodeIndexerToolkit):
         
         sanitized = sanitized_name + extension
         return sanitized, (sanitized != original)
+    
+    def _extract_base64_if_needed(self, filedata: str) -> tuple[str | bytes, bool]:
+        """
+        Resolve cached_image_id references from cache and decode to binary data.
+        
+        Requires JSON format with cached_image_id field: {"cached_image_id": "img_xxx"}
+        LLM must extract specific cached_image_id from generate_image response.
+        
+        Returns:
+            tuple: (processed_data, is_from_image_generation)
+                - processed_data: Original filedata or resolved binary image data
+                - is_from_image_generation: True if data came from image_generation cache
+        """
+        if not filedata or not isinstance(filedata, str):
+            return filedata, False
+        
+        # Require JSON format - fail fast if not JSON
+        if '{' not in filedata:
+            return filedata, False
+        
+        try:
+            data = json.loads(filedata)
+        except json.JSONDecodeError:
+            # Not valid JSON, return as-is (regular file content)
+            return filedata, False
+        
+        if not isinstance(data, dict):
+            return filedata, False
+        
+        # Only accept direct cached_image_id format: {"cached_image_id": "img_xxx"}
+        # LLM must parse generate_image response and extract specific cached_image_id
+        if 'cached_image_id' in data:
+            binary_data = resolve_image_from_cache(self.alita, data['cached_image_id'])
+            return binary_data, True  # Mark as from image_generation
+        
+        # If JSON doesn't have cached_image_id, treat as regular file content
+        return filedata, False
 
     def create_xlsx_filedata(self, data: dict[str, list[list]]) -> bytes:
         try:
@@ -377,15 +422,19 @@ class ArtifactWrapper(NonCodeIndexerToolkit):
                     "createFile", 
                     filename=(str, Field(description="Filename")),
                     filedata=(str, Field(description="""Stringified content of the file.
-                    Example for .xlsx filedata format:
-                    {
-                        "Sheet1":[
-                            ["Name", "Age", "City"],
-                            ["Alice", 25, "New York"],
-                            ["Bob", 30, "San Francisco"],
-                            ["Charlie", 35, "Los Angeles"]
-                        ]
-                    }
+                    
+                    Supports three input formats:
+                    
+                    1. CACHED IMAGE REFERENCE (for generated/cached images):
+                       Pass JSON with cached_image_id field: {"cached_image_id": "img_xxx"}
+                       The tool will automatically resolve and decode the image from cache.
+                       This is typically used when another tool returns an image reference.
+                    
+                    2. EXCEL FILES (.xlsx extension):
+                       Pass JSON with sheet structure: {"Sheet1": [["Name", "Age"], ["Alice", 25], ["Bob", 30]]}
+                    
+                    3. TEXT/OTHER FILES:
+                       Pass the plain text string directly.
                     """)),
                     bucket_name=bucket_name
                 )