alita-sdk 0.3.205__py3-none-any.whl → 0.3.207__py3-none-any.whl

alita_sdk/runtime/utils/toolkit_runtime.py

@@ -0,0 +1,147 @@
+"""
+Toolkit runtime utilities for event dispatching and execution context.
+This module provides tools with the ability to dispatch custom events during execution.
+"""
+
+import sys
+import logging
+from typing import Dict, Any, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def dispatch_custom_event(event_type: str, data: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """
+    Dispatch a custom event from within a toolkit tool execution.
+    
+    This function can be called by toolkit tools to send events back to the runtime
+    for monitoring, logging, or other purposes.
+    
+    Args:
+        event_type: Type of the event (e.g., "progress", "warning", "info")
+        data: Event data dictionary
+        
+    Returns:
+        Event dictionary if successful, None if no executor context available
+        
+    Example:
+        ```python
+        from alita_sdk.runtime.utils.toolkit_runtime import dispatch_custom_event
+        
+        def my_tool_function(param1, param2):
+            # Dispatch a progress event
+            dispatch_custom_event("progress", {
+                "message": "Processing started",
+                "step": 1,
+                "total_steps": 3
+            })
+            
+            # Do some work
+            result = process_data(param1, param2)
+            
+            # Dispatch completion event
+            dispatch_custom_event("completion", {
+                "message": "Processing completed",
+                "result_size": len(result)
+            })
+            
+            return result
+        ```
+    """
+    try:
+        # Try to get the current executor context
+        if hasattr(sys.modules[__name__], 'toolkit_dispatch_context'):
+            context = sys.modules[__name__].toolkit_dispatch_context
+            return context.dispatch_custom_event(event_type, data)
+        else:
+            # No executor context available - this is normal when not in test mode
+            logger.debug(f"No toolkit executor context available for event: {event_type}")
+            return None
+    except Exception as e:
+        logger.warning(f"Error dispatching custom event {event_type}: {e}")
+        return None
+
+
+def get_executor_context():
+    """
+    Get the current toolkit executor context if available.
+    
+    Returns:
+        ToolkitExecutor context or None if not in execution context
+    """
+    try:
+        if hasattr(sys.modules[__name__], 'toolkit_dispatch_context'):
+            return sys.modules[__name__].toolkit_dispatch_context.executor
+        return None
+    except Exception:
+        return None
+
+
+def is_in_test_mode() -> bool:
+    """
+    Check if the toolkit is currently running in test mode.
+    
+    Returns:
+        True if running in test mode with executor context, False otherwise
+    """
+    return get_executor_context() is not None
+
+
+class ToolkitRuntimeContext:
+    """
+    Context manager for toolkit runtime execution.
+    
+    This can be used by tools that need to perform setup/cleanup operations
+    when running in test mode vs normal execution.
+    """
+    
+    def __init__(self, tool_name: str):
+        self.tool_name = tool_name
+        self.executor = get_executor_context()
+        
+    def __enter__(self):
+        if self.executor:
+            dispatch_custom_event("tool_start", {
+                "tool_name": self.tool_name,
+                "message": f"Starting execution of {self.tool_name}"
+            })
+        return self
+        
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self.executor:
+            if exc_type is None:
+                dispatch_custom_event("tool_end", {
+                    "tool_name": self.tool_name,
+                    "message": f"Completed execution of {self.tool_name}",
+                    "success": True
+                })
+            else:
+                dispatch_custom_event("tool_error", {
+                    "tool_name": self.tool_name,
+                    "message": f"Error in {self.tool_name}: {exc_val}",
+                    "success": False,
+                    "error_type": exc_type.__name__ if exc_type else "Unknown"
+                })
+        return False  # Don't suppress exceptions
+    
+    def dispatch_progress(self, message: str, step: int = None, total_steps: int = None, **kwargs):
+        """Convenience method for dispatching progress events."""
+        data = {"message": message, "tool_name": self.tool_name}
+        if step is not None:
+            data["step"] = step
+        if total_steps is not None:
+            data["total_steps"] = total_steps
+        data.update(kwargs)
+        dispatch_custom_event("progress", data)
+    
+    def dispatch_info(self, message: str, **kwargs):
+        """Convenience method for dispatching info events."""
+        data = {"message": message, "tool_name": self.tool_name}
+        data.update(kwargs)
+        dispatch_custom_event("info", data)
+    
+    def dispatch_warning(self, message: str, **kwargs):
+        """Convenience method for dispatching warning events."""
+        data = {"message": message, "tool_name": self.tool_name}
+        data.update(kwargs)
+        dispatch_custom_event("warning", data)

alita_sdk/runtime/utils/toolkit_utils.py

@@ -0,0 +1,157 @@
+"""
+Toolkit utilities for instantiating and managing toolkits.
+This module provides toolkit management functions that are not tied to any specific interface.
+"""
+
+import logging
+import random
+from typing import Dict, Any, Optional, List
+
+logger = logging.getLogger(__name__)
+
+
+def instantiate_toolkit_with_client(toolkit_config: Dict[str, Any], 
+                                   llm_client: Any, 
+                                   alita_client: Optional[Any] = None) -> List[Any]:
+    """
+    Instantiate a toolkit with LLM client support.
+    
+    This is a variant of instantiate_toolkit that includes LLM client support
+    for toolkits that require LLM capabilities.
+    
+    Args:
+        toolkit_config: Configuration dictionary for the toolkit
+        llm_client: LLM client instance for tools that need LLM capabilities
+        client: Optional additional client instance
+    
+    Returns:
+        List of instantiated tools from the toolkit
+        
+    Raises:
+        ValueError: If required configuration or client is missing
+        Exception: If toolkit instantiation fails
+    """
+    try:
+        from ..toolkits.tools import get_tools
+        
+        toolkit_name = toolkit_config.get('toolkit_name')
+        if not toolkit_name:
+            raise ValueError("toolkit_name is required in configuration")
+        
+        if not llm_client:
+            raise ValueError("LLM client is required but not provided")
+        
+        settings = toolkit_config.get('settings', {})
+        
+        # Log the configuration being used
+        logger.info(f"Instantiating toolkit {toolkit_name} with LLM client")
+        logger.debug(f"Toolkit {toolkit_name} configuration: {toolkit_config}")
+        
+        # Create a tool configuration dict with required fields
+        tool_config = {
+            'id': toolkit_config.get('id', random.randint(1, 1000000)),
+            'type': toolkit_config.get('type', toolkit_name.lower()),
+            'settings': settings,
+            'toolkit_name': toolkit_name
+        }
+        
+        # Get tools using the toolkit configuration with clients
+        # Parameter order: get_tools(tools_list, alita_client, llm, memory_store)
+        tools = get_tools([tool_config], alita_client, llm_client)
+        
+        if not tools:
+            logger.warning(f"No tools returned for toolkit {toolkit_name}")
+            return []
+        
+        logger.info(f"Successfully instantiated toolkit {toolkit_name} with {len(tools)} tools")
+        return tools
+            
+    except Exception as e:
+        logger.error(f"Error instantiating toolkit {toolkit_name} with client: {str(e)}")
+        raise
+
+
+def get_toolkit_tools(toolkit_instance: Any) -> List[Any]:
+    """
+    Extract tools from an instantiated toolkit instance.
+    
+    This function provides a standardized way to get tools from various
+    toolkit implementations that might have different interfaces.
+    
+    Args:
+        toolkit_instance: An instantiated toolkit object
+        
+    Returns:
+        List of tools from the toolkit
+        
+    Raises:
+        ValueError: If no tools can be extracted from the toolkit
+    """
+    try:
+        # Try different methods to get tools from the toolkit
+        if hasattr(toolkit_instance, 'get_tools'):
+            tools = toolkit_instance.get_tools()
+        elif hasattr(toolkit_instance, 'tools'):
+            tools = toolkit_instance.tools
+        elif hasattr(toolkit_instance, '_tools'):
+            tools = toolkit_instance._tools
+        else:
+            raise ValueError("Could not find tools in the toolkit instance")
+        
+        if not tools:
+            logger.warning("Toolkit instance returned empty tools list")
+            return []
+        
+        logger.info(f"Extracted {len(tools)} tools from toolkit instance")
+        return tools
+        
+    except Exception as e:
+        logger.error(f"Error extracting tools from toolkit: {str(e)}")
+        raise
+
+
+def find_tool_by_name(tools: List[Any], tool_name: str) -> Optional[Any]:
+    """
+    Find a specific tool by name from a list of tools.
+    
+    Args:
+        tools: List of tool instances
+        tool_name: Name of the tool to find
+        
+    Returns:
+        The tool instance if found, None otherwise
+    """
+    for tool in tools:
+        # Check various attributes that might contain the tool name
+        if hasattr(tool, 'name') and tool.name == tool_name:
+            return tool
+        elif hasattr(tool, 'func') and hasattr(tool.func, '__name__') and tool.func.__name__ == tool_name:
+            return tool
+        elif hasattr(tool, '__name__') and tool.__name__ == tool_name:
+            return tool
+    
+    return None
+
+
+def get_tool_names(tools: List[Any]) -> List[str]:
+    """
+    Extract tool names from a list of tools.
+    
+    Args:
+        tools: List of tool instances
+        
+    Returns:
+        List of tool names
+    """
+    tool_names = []
+    for tool in tools:
+        if hasattr(tool, 'name'):
+            tool_names.append(tool.name)
+        elif hasattr(tool, 'func') and hasattr(tool.func, '__name__'):
+            tool_names.append(tool.func.__name__)
+        elif hasattr(tool, '__name__'):
+            tool_names.append(tool.__name__)
+        else:
+            tool_names.append(str(tool))
+    
+    return tool_names

alita_sdk/runtime/utils/utils.py

@@ -1,7 +1,12 @@
 import re
+from enum import Enum
 
 TOOLKIT_SPLITTER = "___"
 
+class IndexerKeywords(Enum):
+    DEPENDENT_DOCS = 'dependent_docs'
+    PARENT = 'parent_id'
+
 # This pattern matches characters that are NOT alphanumeric, underscores, or hyphens
 clean_string_pattern = re.compile(r'[^a-zA-Z0-9_.-]')
 

alita_sdk/tools/__init__.py

@@ -2,6 +2,7 @@ import logging
 from importlib import import_module
 from typing import Optional
 
+from langchain_core.tools import ToolException
 from langgraph.store.base import BaseStore
 
 logger = logging.getLogger(__name__)
@@ -113,6 +114,7 @@ def get_tools(tools_list, alita, llm, store: Optional[BaseStore] = None, *args,
 
             except Exception as e:
                 logger.error(f"Error getting tools for {tool_type}: {e}")
+                raise ToolException(f"Error getting tools for {tool_type}: {e}")
 
         # Handle ADO repos special case (it might be requested as azure_devops_repos)
         elif tool_type in ['ado_repos', 'azure_devops_repos'] and 'ado_repos' in AVAILABLE_TOOLS:

alita_sdk/tools/ado/repos/repos_wrapper.py

@@ -250,6 +250,7 @@ class ReposApiWrapper(BaseCodeToolApiWrapper):
     token: Optional[SecretStr]
     _client: Optional[GitClient] = PrivateAttr()
 
+    llm: Optional[Any] = None
     # Vector store configuration
     connection_string: Optional[SecretStr] = None
     collection_name: Optional[str] = None
@@ -303,24 +304,30 @@ class ReposApiWrapper(BaseCodeToolApiWrapper):
 
     def _get_files(
             self,
-            directory_path: str = "",
-            branch_name: str = None,
+            path: str = "",
+            branch: str = None,
             recursion_level: str = "Full",
     ) -> str:
+        """Get list of files from a repository path and branch.
+
+        Args:
+            path (str): Path within the repository to list files from
+            branch (str): Branch to get files from. Defaults to base_branch if None.
+            recursion_level (str): OneLevel - includes immediate children, Full - includes all items, None - no recursion
+
+        Returns:
+            List[str]: List of file paths
         """
-        Params:
-            recursion_level: OneLevel - includes immediate children, Full - includes all items, None - no recursion
-        """
-        branch_name = branch_name if branch_name else self.base_branch
+        branch = branch if branch else self.base_branch
         files: List[str] = []
         try:
             version_descriptor = GitVersionDescriptor(
-                version=branch_name, version_type="branch"
+                version=branch, version_type="branch"
             )
             items = self._client.get_items(
                 repository_id=self.repository_id,
                 project=self.project,
-                scope_path=directory_path,
+                scope_path=path,
                 recursion_level=recursion_level,
                 version_descriptor=version_descriptor,
                 include_content_metadata=True,
@@ -334,7 +341,7 @@ class ReposApiWrapper(BaseCodeToolApiWrapper):
             item = items.pop(0)
             if item.git_object_type == "blob":
                 files.append(item.path)
-        return str(files)
+        return files # Changed to return list directly instead of str
 
     def set_active_branch(self, branch_name: str) -> str:
         """
@@ -389,7 +396,7 @@ class ReposApiWrapper(BaseCodeToolApiWrapper):
             logger.error(msg)
             return ToolException(msg)
 
-    def list_files(self, directory_path: str = "", branch_name: str = None) -> str:
+    def list_files(self, directory_path: str = "", branch_name: str = None) -> List[str]:
         """
         Recursively fetches files from a directory in the repo.
 
@@ -398,12 +405,12 @@ class ReposApiWrapper(BaseCodeToolApiWrapper):
             branch_name (str): The name of the branch where the files to be received.
 
         Returns:
-            str: List of file paths, or an error message.
+            List[str]: List of file paths, or an error message.
         """
         self.active_branch = branch_name if branch_name else self.active_branch
         return self._get_files(
-            directory_path=directory_path,
-            branch_name=self.active_branch if self.active_branch else self.base_branch,
+            path=directory_path,
+            branch=self.active_branch if self.active_branch else self.base_branch,
         )
 
     def parse_pull_request_comments(

alita_sdk/tools/bitbucket/api_wrapper.py

@@ -5,7 +5,7 @@ import logging
 from typing import TYPE_CHECKING, Any, Dict, List, Optional
 
 from langchain_core.tools import ToolException
-from pydantic import BaseModel, model_validator, SecretStr
+from pydantic import model_validator, SecretStr
 from .bitbucket_constants import create_pr_data
 from .cloud_api_wrapper import BitbucketCloudApi, BitbucketServerApi
 from pydantic.fields import PrivateAttr
@@ -172,26 +172,26 @@ class BitbucketAPIWrapper(BaseCodeToolApiWrapper):
         """
         return self._bitbucket.get_pull_requests()
     
-    def get_pull_request(self, pr_id: str) -> Any:
+    def get_pull_request(self, pr_id: str) -> Dict[str, Any]:
         """
         Get details of a pull request
         Parameters:
             pr_id(str): the pull request ID
         Returns:
-            Any: Details of the pull request
+            dict: Details of the pull request as a dictionary
         """
         try:
             return self._bitbucket.get_pull_request(pr_id=pr_id)
         except Exception as e:
             return ToolException(f"Can't get pull request `{pr_id}` due to error:\n{str(e)}")
         
-    def get_pull_requests_changes(self, pr_id: str) -> Any:
+    def get_pull_requests_changes(self, pr_id: str) -> Dict[str, Any]:
         """
         Get changes of a pull request
         Parameters:
             pr_id(str): the pull request ID
         Returns:
-            Any: Changes of the pull request
+            dict: Changes of the pull request as a dictionary
         """
         try:
             return self._bitbucket.get_pull_requests_changes(pr_id=pr_id)

alita_sdk/tools/bitbucket/cloud_api_wrapper.py

@@ -17,6 +17,21 @@ if TYPE_CHECKING:
     pass
 
 
+def normalize_response(response) -> Dict[str, Any]:
+    """
+    Normalize API response to dictionary format.
+    Handles different response types from Bitbucket APIs.
+    """
+    if isinstance(response, dict):
+        return response
+    if hasattr(response, 'to_dict'):
+        return response.to_dict()
+    if hasattr(response, '__dict__'):
+        return {k: v for k, v in response.__dict__.items()
+                if isinstance(v, (str, int, float, bool, list, dict, type(None)))}
+    return {"raw_response": str(response)}
+
+
 class BitbucketApiAbstract(ABC):
 
     @abstractmethod
@@ -48,11 +63,11 @@ class BitbucketApiAbstract(ABC):
         pass
 
     @abstractmethod
-    def get_pull_request(self, pr_id: str) -> Any:
+    def get_pull_request(self, pr_id: str) -> Dict[str, Any]:
         pass
 
     @abstractmethod
-    def get_pull_requests_changes(self, pr_id: str) -> Any:
+    def get_pull_requests_changes(self, pr_id: str) -> Dict[str, Any]:
         pass
 
     @abstractmethod
@@ -95,7 +110,7 @@ class BitbucketServerApi(BitbucketApiAbstract):
 
     def get_files_list(self, file_path: str, branch: str) -> list:
         files = self.api_client.get_file_list(project_key=self.project, repository_slug=self.repository, query=branch,
-                                      sub_folder=file_path)
+                                              sub_folder=file_path)
         files_list = []
         for file in files:
             files_list.append(file['path'])
@@ -112,7 +127,7 @@ class BitbucketServerApi(BitbucketApiAbstract):
         )
 
     def update_file(self, file_path: str, update_query: str, branch: str) -> str:
-        file_content = self.get_file(file_path = file_path, branch=branch)
+        file_content = self.get_file(file_path=file_path, branch=branch)
         updated_file_content = file_content
         for old, new in extract_old_new_pairs(update_query):
             if not old.strip():
@@ -126,8 +141,8 @@ class BitbucketServerApi(BitbucketApiAbstract):
                 "the current file contents."
             )
 
-
-        source_commit_generator = self.api_client.get_commits(project_key=self.project, repository_slug=self.repository, hash_newest=branch, limit=1)
+        source_commit_generator = self.api_client.get_commits(project_key=self.project, repository_slug=self.repository,
+                                                              hash_newest=branch, limit=1)
         source_commit = next(source_commit_generator)
         return self.api_client.update_file(
             project_key=self.project,
@@ -138,7 +153,7 @@ class BitbucketServerApi(BitbucketApiAbstract):
             filename=file_path,
             source_commit_id=source_commit['id']
         )
-    
+
     def get_pull_request_commits(self, pr_id: str) -> List[Dict[str, Any]]:
         """
         Get commits from a pull request
@@ -147,27 +162,32 @@ class BitbucketServerApi(BitbucketApiAbstract):
         Returns:
             List[Dict[str, Any]]: List of commits in the pull request
         """
-        return self.api_client.get_pull_requests_commits(project_key=self.project, repository_slug=self.repository, pull_request_id=pr_id)
-    
+        return self.api_client.get_pull_requests_commits(project_key=self.project, repository_slug=self.repository,
+                                                         pull_request_id=pr_id)
+
     def get_pull_request(self, pr_id):
         """ Get details of a pull request
         Parameters:
             pr_id(str): the pull request ID
         Returns:
-            Any: Details of the pull request
+            Dict[str, Any]: Details of the pull request
         """
-        return self.api_client.get_pull_request(project_key=self.project, repository_slug=self.repository, pull_request_id=pr_id)
-    
-    def get_pull_requests_changes(self, pr_id: str) -> Any:
+        response = self.api_client.get_pull_request(project_key=self.project, repository_slug=self.repository,
+                                                    pull_request_id=pr_id)
+        return normalize_response(response)
+
+    def get_pull_requests_changes(self, pr_id: str) -> Dict[str, Any]:
         """
         Get changes of a pull request
         Parameters:
             pr_id(str): the pull request ID
         Returns:
-            Any: Changes of the pull request
+            Dict[str, Any]: Changes of the pull request
         """
-        return self.api_client.get_pull_requests_changes(project_key=self.project, repository_slug=self.repository, pull_request_id=pr_id)
-    
+        response = self.api_client.get_pull_requests_changes(project_key=self.project, repository_slug=self.repository,
+                                                             pull_request_id=pr_id)
+        return normalize_response(response)
+
     def add_pull_request_comment(self, pr_id, content, inline=None):
         """
         Add a comment to a pull request. Supports multiple content types and inline comments.
@@ -204,6 +224,7 @@ class BitbucketServerApi(BitbucketApiAbstract):
             **comment_data
         )
 
+
 class BitbucketCloudApi(BitbucketApiAbstract):
     api_client: Cloud
 
@@ -249,8 +270,9 @@ class BitbucketCloudApi(BitbucketApiAbstract):
         index = 0
         # TODO: add pagination
         for item in \
-        self.repository.get(path=f'src/{branch}/{file_path}?max_depth=100&pagelen=100&fields=values.path&q=type="commit_file"')[
-            'values']:
+                self.repository.get(
+                    path=f'src/{branch}/{file_path}?max_depth=100&pagelen=100&fields=values.path&q=type="commit_file"')[
+                    'values']:
             files_list.append(item['path'])
         return files_list
 
@@ -259,7 +281,8 @@ class BitbucketCloudApi(BitbucketApiAbstract):
             'branch': f'{branch}',
             f'{file_path}': f'{file_contents}',
         }
-        return self.repository.post(path='src', data=form_data, files={}, headers={'Content-Type': 'application/x-www-form-urlencoded'})
+        return self.repository.post(path='src', data=form_data, files={},
+                                    headers={'Content-Type': 'application/x-www-form-urlencoded'})
 
     def update_file(self, file_path: str, update_query: str, branch: str) -> ToolException | str:
 
@@ -277,7 +300,7 @@ class BitbucketCloudApi(BitbucketApiAbstract):
                 "the current file contents."
             )
         return self.create_file(file_path, updated_file_content, branch)
-    
+
     def get_pull_request_commits(self, pr_id: str) -> List[Dict[str, Any]]:
         """
         Get commits from a pull request
@@ -287,26 +310,28 @@ class BitbucketCloudApi(BitbucketApiAbstract):
             List[Dict[str, Any]]: List of commits in the pull request
         """
         return self.repository.pullrequests.get(pr_id).get('commits', {}).get('values', [])
-    
-    def get_pull_request(self, pr_id: str) -> Any:
+
+    def get_pull_request(self, pr_id: str) -> Dict[str, Any]:
         """ Get details of a pull request
         Parameters:
             pr_id(str): the pull request ID
         Returns:
-            Any: Details of the pull request
+            Dict[str, Any]: Details of the pull request
         """
-        return self.repository.pullrequests.get(pr_id)
-    
-    def get_pull_requests_changes(self, pr_id: str) -> Any:
+        response = self.repository.pullrequests.get(pr_id)
+        return normalize_response(response)
+
+    def get_pull_requests_changes(self, pr_id: str) -> Dict[str, Any]:
         """
         Get changes of a pull request
         Parameters:
             pr_id(str): the pull request ID
         Returns:
-            Any: Changes of the pull request
+            Dict[str, Any]: Changes of the pull request
         """
-        return self.repository.pullrequests.get(pr_id).get('diff', {})
-    
+        response = self.repository.pullrequests.get(pr_id).get('diff', {})
+        return normalize_response(response)
+
     def add_pull_request_comment(self, pr_id: str, content, inline=None) -> str:
         """
         Add a comment to a pull request. Supports multiple content types and inline comments.

alita_sdk/tools/elitea_base.py

@@ -2,7 +2,7 @@ import ast
 import fnmatch
 import logging
 import traceback
-from typing import Any, Optional, List, Dict
+from typing import Any, Optional, List, Dict, Generator
 
 from langchain_core.documents import Document
 from langchain_core.tools import ToolException
@@ -208,7 +208,7 @@ class BaseVectorStoreToolApiWrapper(BaseToolApiWrapper):
             Document: The processed document with metadata."""
         pass
 
-    def _process_documents(self, documents: List[Document]) -> List[Document]:
+    def _process_documents(self, documents: List[Document]) -> Generator[Document, None, None]:
         """
         Process a list of base documents to extract relevant metadata for full document preparation.
         Used for late processing of documents after we ensure that the documents have to be indexed to avoid
@@ -219,9 +219,14 @@ class BaseVectorStoreToolApiWrapper(BaseToolApiWrapper):
             documents (List[Document]): The base documents to process.
 
         Returns:
-            List[Document]: The processed documents with metadata.
+            Generator[Document, None, None]: A generator yielding processed documents with metadata.
         """
-        return [self._process_document(doc) for doc in documents]
+        for doc in documents:
+            processed_docs = self._process_document(doc)
+            if processed_docs:  # Only proceed if the list is not empty
+                for processed_doc in processed_docs:
+                    yield processed_doc
+
 
     def _init_vector_store(self, collection_suffix: str = "", embeddings: Optional[Any] = None):
         """ Initializes the vector store wrapper with the provided parameters."""