alita-sdk 0.3.465__py3-none-any.whl → 0.3.497__py3-none-any.whl

alita_sdk/runtime/toolkits/planning.py

@@ -0,0 +1,173 @@
+"""
+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, TOOLKIT_SPLITTER, 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,
+        )
+        
+        # Build tool name prefix
+        prefix = clean_string(toolkit_name, cls._toolkit_max_length) + TOOLKIT_SPLITTER 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
+            
+            tools.append(BaseAction(
+                api_wrapper=wrapper,
+                name=prefix + tool["name"],
+                description=tool["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/tools.py

@@ -9,6 +9,7 @@ from alita_sdk.tools import get_tools as alita_tools
 from .application import ApplicationToolkit
 from .artifact import ArtifactToolkit
 from .datasource import DatasourcesToolkit
+from .planning import PlanningToolkit
 from .prompt import PromptToolkit
 from .subgraph import SubgraphToolkit
 from .vectorstore import VectorStoreToolkit
@@ -21,6 +22,7 @@ from ...community import get_toolkits as community_toolkits, get_tools as commun
 from ...tools.memory import MemoryToolkit
 from ..utils.mcp_oauth import canonical_resource, McpAuthorizationRequired
 from ...tools.utils import TOOLKIT_SPLITTER
+from alita_sdk.tools import _inject_toolkit_id
 
 logger = logging.getLogger(__name__)
 
@@ -29,6 +31,7 @@ def get_toolkits():
     core_toolkits = [
         ArtifactToolkit.toolkit_config_schema(),
         MemoryToolkit.toolkit_config_schema(),
+        PlanningToolkit.toolkit_config_schema(),
         VectorStoreToolkit.toolkit_config_schema(),
         SandboxToolkit.toolkit_config_schema(),
         ImageGenerationToolkit.toolkit_config_schema(),
@@ -38,7 +41,7 @@ def get_toolkits():
     return core_toolkits + community_toolkits() + alita_toolkits()
 
 
-def get_tools(tools_list: list, alita_client, llm, memory_store: BaseStore = None, debug_mode: Optional[bool] = False, mcp_tokens: Optional[dict] = None) -> list:
+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) -> list:
     prompts = []
     tools = []
 
@@ -91,8 +94,13 @@ def get_tools(tools_list: list, alita_client, llm, memory_store: BaseStore = Non
                     else:
                         logger.warning("Image generation internal tool requested "
                                        "but no image generation model configured")
+                elif tool['name'] == 'planner':
+                    tools += PlanningToolkit.get_toolkit(
+                        pgvector_configuration=tool.get('settings', {}).get('pgvector_configuration'),
+                        conversation_id=conversation_id,
+                    ).get_tools()
             elif tool['type'] == 'artifact':
-                tools.extend(ArtifactToolkit.get_toolkit(
+                toolkit_tools = ArtifactToolkit.get_toolkit(
                     client=alita_client,
                     bucket=tool['settings']['bucket'],
                     toolkit_name=tool.get('toolkit_name', ''),
@@ -102,13 +110,56 @@ def get_tools(tools_list: list, alita_client, llm, memory_store: BaseStore = Non
                     pgvector_configuration=tool['settings'].get('pgvector_configuration', {}),
                     embedding_model=tool['settings'].get('embedding_model'),
                     collection_name=f"{tool.get('toolkit_name')}",
-                    collection_schema = str(tool['id'])
-                ).get_tools())
+                    collection_schema=str(tool['id']),
+                ).get_tools()
+                # Inject toolkit_id for artifact tools as well
+                _inject_toolkit_id(tool, toolkit_tools)
+                tools.extend(toolkit_tools)
+
             elif tool['type'] == 'vectorstore':
                 tools.extend(VectorStoreToolkit.get_toolkit(
                     llm=llm,
                     toolkit_name=tool.get('toolkit_name', ''),
                     **tool['settings']).get_tools())
+            elif tool['type'] == 'planning':
+                # Planning toolkit for multi-step task tracking
+                settings = tool.get('settings', {})
+                
+                # Check if local mode is enabled (uses filesystem storage, ignores pgvector)
+                use_local = settings.get('local', False)
+                
+                if use_local:
+                    # Local mode - use filesystem storage
+                    logger.info("Planning toolkit using local filesystem storage (local=true)")
+                    pgvector_config = {}
+                else:
+                    # Check if explicit connection_string is provided in pgvector_configuration
+                    explicit_pgvector_config = settings.get('pgvector_configuration', {})
+                    explicit_connstr = explicit_pgvector_config.get('connection_string') if explicit_pgvector_config else None
+                    
+                    if explicit_connstr:
+                        # Use explicitly provided connection string (overrides project secrets)
+                        logger.info("Using explicit connection_string for planning toolkit")
+                        pgvector_config = explicit_pgvector_config
+                    else:
+                        # Try to fetch pgvector_project_connstr from project secrets
+                        pgvector_connstr = None
+                        if alita_client:
+                            try:
+                                pgvector_connstr = alita_client.unsecret('pgvector_project_connstr')
+                                if pgvector_connstr:
+                                    logger.info("Using pgvector_project_connstr for planning toolkit")
+                            except Exception as e:
+                                logger.debug(f"pgvector_project_connstr not available: {e}")
+                        
+                        pgvector_config = {'connection_string': pgvector_connstr} if pgvector_connstr else {}
+                
+                tools.extend(PlanningToolkit.get_toolkit(
+                    toolkit_name=tool.get('toolkit_name', ''),
+                    selected_tools=settings.get('selected_tools', []),
+                    pgvector_configuration=pgvector_config,
+                    conversation_id=conversation_id or settings.get('conversation_id'),
+                ).get_tools())
             elif tool['type'] == 'mcp':
                 # remote mcp tool initialization with token injection
                 settings = dict(tool['settings'])
@@ -153,9 +204,10 @@ def get_tools(tools_list: list, alita_client, llm, memory_store: BaseStore = Non
                     toolkit_name=tool.get('toolkit_name', ''),
                     client=alita_client,
                     **settings).get_tools())
+        except McpAuthorizationRequired:
+            # Re-raise auth required exceptions directly
+            raise
         except Exception as e:
-            if isinstance(e, McpAuthorizationRequired):
-                raise
             logger.error(f"Error initializing toolkit for tool '{tool.get('name', 'unknown')}': {e}", exc_info=True)
             if debug_mode:
                 logger.info("Skipping tool initialization error due to debug mode.")
@@ -271,7 +323,7 @@ def _init_single_mcp_tool(server_toolkit_name, toolkit_name, available_tool, ali
         tool_name = f'{toolkit_name}{TOOLKIT_SPLITTER}{available_tool["name"]}'
         return McpServerTool(
             name=tool_name,
-            description=f"MCP for a tool '{tool_name}': {available_tool.get("description", "")}",
+            description=f"MCP for a tool '{tool_name}': {available_tool.get('description', '')}",
             args_schema=McpServerTool.create_pydantic_model_from_schema(
                 available_tool.get("inputSchema", {})
             ),

alita_sdk/runtime/tools/artifact.py

@@ -34,28 +34,57 @@ class ArtifactWrapper(NonCodeIndexerToolkit):
         return self.artifact.list(bucket_name, return_as_string)
 
     def create_file(self, filename: str, filedata: str, bucket_name = None):
-        if filename.endswith(".xlsx"):
+        # Sanitize filename to prevent regex errors during indexing
+        sanitized_filename, was_modified = self._sanitize_filename(filename)
+        if was_modified:
+            logging.warning(f"Filename sanitized: '{filename}' -> '{sanitized_filename}'")
+        
+        if sanitized_filename.endswith(".xlsx"):
             data = json.loads(filedata)
             filedata = self.create_xlsx_filedata(data)
 
-        result = self.artifact.create(filename, filedata, bucket_name)
+        result = self.artifact.create(sanitized_filename, filedata, bucket_name)
         
         # Dispatch custom event for file creation
-        self._log_tool_event(
-            tool_name="file_modified",
-            message="""
-            {
-                "message": f"File '{filename}' created successfully",
-                "filename": filename,
-                "tool_name": "createFile",
-                "toolkit": "artifact",
-                "operation_type": "create",
-                "meta": {
-                    "bucket": bucket_name or self.bucket
-                }
-            }""")
+        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
+    
+    @staticmethod
+    def _sanitize_filename(filename: str) -> tuple:
+        """Sanitize filename for safe storage and regex pattern matching."""
+        from pathlib import Path
+        
+        if not filename or not filename.strip():
+            return "unnamed_file", True
+        
+        original = filename
+        path_obj = Path(filename)
+        name = path_obj.stem
+        extension = path_obj.suffix
+        
+        # Whitelist: alphanumeric, underscore, hyphen, space, Unicode letters/digits
+        sanitized_name = re.sub(r'[^\w\s-]', '', name, flags=re.UNICODE)
+        sanitized_name = re.sub(r'[-\s]+', '-', sanitized_name)
+        sanitized_name = sanitized_name.strip('-').strip()
+        
+        if not sanitized_name:
+            sanitized_name = "file"
+        
+        if extension:
+            extension = re.sub(r'[^\w.-]', '', extension, flags=re.UNICODE)
+        
+        sanitized = sanitized_name + extension
+        return sanitized, (sanitized != original)
 
     def create_xlsx_filedata(self, data: dict[str, list[list]]) -> bytes:
         try:
@@ -173,13 +202,13 @@ class ArtifactWrapper(NonCodeIndexerToolkit):
             file_name = file['name']
 
             # Check if file should be skipped based on skip_extensions
-            if any(re.match(pattern.replace('*', '.*') + '$', file_name, re.IGNORECASE)
+            if any(re.match(re.escape(pattern).replace(r'\*', '.*') + '$', file_name, re.IGNORECASE)
                    for pattern in skip_extensions):
                 continue
 
             # Check if file should be included based on include_extensions
             # If include_extensions is empty, process all files (that weren't skipped)
-            if include_extensions and not (any(re.match(pattern.replace('*', '.*') + '$', file_name, re.IGNORECASE)
+            if include_extensions and not (any(re.match(re.escape(pattern).replace(r'\*', '.*') + '$', file_name, re.IGNORECASE)
                                                for pattern in include_extensions)):
                 continue
 

alita_sdk/runtime/tools/function.py

@@ -107,7 +107,8 @@ class FunctionTool(BaseTool):
 
         # special handler for PyodideSandboxTool
         if self._is_pyodide_tool():
-            code = func_args['code']
+            # replace new lines in strings in code block
+            code = func_args['code'].replace('\\n', '\\\\n')
             func_args['code'] = f"{self._prepare_pyodide_input(state)}\n{code}"
         try:
             tool_result = self.tool.invoke(func_args, config, **kwargs)