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

alita_sdk/tools/github/graphql_client_wrapper.py

@@ -1326,6 +1326,74 @@ class GraphQLClientWrapper(BaseModel):
         except Exception as e:
             raise ValueError(f"'{repo}' repo format is invalid. It should be like 'org-name/repo-name'. Error: {str(e)}")
 
+    def _format_project_error(self, error_message: str) -> str:
+        """
+        Format project access errors with user-friendly guidance.
+
+        Detects permission-related errors and provides actionable guidance for users
+        to fix token permission issues.
+
+        Args:
+            error_message: The original error message from get_project() or get_issue_repo()
+
+        Returns:
+            str: A user-friendly error message with guidance on how to fix the issue
+        """
+        # Detect permission-related errors
+        permission_indicators = [
+            "Resource not accessible",
+            "INSUFFICIENT_SCOPES",
+            "not accessible by personal access token",
+            "requires authentication",
+            "Bad credentials",
+            "401",
+            "403"
+        ]
+
+        is_permission_error = any(
+            indicator.lower() in error_message.lower()
+            for indicator in permission_indicators
+        )
+
+        if is_permission_error:
+            return (
+                "GitHub Token Permission Error\n\n"
+                "Your GitHub token does not have the required 'project' permission "
+                "to access GitHub Projects (ProjectsV2).\n\n"
+                "To fix this:\n"
+                "1. Go to GitHub Settings > Developer settings > Personal access tokens\n"
+                "2. Edit your token and enable the 'project' scope (read/write access to projects)\n"
+                "3. Update your toolkit configuration with the new token\n\n"
+                f"Technical details: {error_message}"
+            )
+
+        # For other errors (not found, network issues, etc.), return with clearer context
+        if "not found" in error_message.lower():
+            return f"Project not found. Please verify the project title exists and is accessible. {error_message}"
+
+        if "No repository data found" in error_message:
+            return (
+                "Repository not found or not accessible. Please verify:\n"
+                "1. The repository name is correct (format: owner/repo-name)\n"
+                "2. Your token has access to this repository\n\n"
+                f"Technical details: {error_message}"
+            )
+
+        return f"Failed to access GitHub project. {error_message}"
+
+    def _format_repo_error(self, error_message: str) -> str:
+        """
+        Format repository access errors with user-friendly guidance.
+
+        Args:
+            error_message: The original error message from get_issue_repo()
+
+        Returns:
+            str: A user-friendly error message with guidance
+        """
+        # Reuse the project error formatting logic as the errors are similar
+        return self._format_project_error(error_message)
+
     def _get_repo_extra_info(self, repository: Dict[str, Any]) -> Tuple[str, List[Dict[str, Any]], List[Dict[str, Any]]]:
         """Helper to extract repository ID, labels and assignable users of the repository."""
         repository_id = repository.get("repositoryId")
@@ -1356,22 +1424,31 @@ class GraphQLClientWrapper(BaseModel):
         except ValueError as e:
             return str(e)
 
-        try:
-            result = self.get_project(owner=owner_name, repo_name=repo_name, project_title=project_title)
-            project = result.get("project")
-            project_id = result.get("projectId")
-            if issue_repo:
-                try:
-                    issue_owner_name, issue_repo_name = self._parse_repo(issue_repo)
-                except ValueError as e:
-                    return str(e)
-
-                issue_repo_result = self.get_issue_repo(owner=issue_owner_name, repo_name=issue_repo_name)
-                repository_id, labels, assignable_users = self._get_repo_extra_info(issue_repo_result)
-            else:
-                repository_id, labels, assignable_users = self._get_repo_extra_info(result)
-        except Exception as e:
-            return f"Project has not been found. Error: {str(e)}"
+        # Get project data with type safety check
+        result = self.get_project(owner=owner_name, repo_name=repo_name, project_title=project_title)
+
+        # Type check: get_project() returns str on error, dict on success
+        if isinstance(result, str):
+            return self._format_project_error(result)
+
+        project = result.get("project")
+        project_id = result.get("projectId")
+
+        if issue_repo:
+            try:
+                issue_owner_name, issue_repo_name = self._parse_repo(issue_repo)
+            except ValueError as e:
+                return str(e)
+
+            issue_repo_result = self.get_issue_repo(owner=issue_owner_name, repo_name=issue_repo_name)
+
+            # Type check: get_issue_repo() returns str on error, dict on success
+            if isinstance(issue_repo_result, str):
+                return self._format_repo_error(issue_repo_result)
+
+            repository_id, labels, assignable_users = self._get_repo_extra_info(issue_repo_result)
+        else:
+            repository_id, labels, assignable_users = self._get_repo_extra_info(result)
 
         missing_fields = []
         updated_fields = []
@@ -1444,26 +1521,35 @@ class GraphQLClientWrapper(BaseModel):
         except Exception as e:
             return str(e)
 
-        try:
-            result = self.get_project(owner=owner_name, repo_name=repo_name, project_title=project_title)
-            project = result.get("project")
-            project_id = result.get("projectId")
-
-            if issue_repo:
-                try:
-                    issue_owner_name, issue_repo_name = self._parse_repo(issue_repo)
-                except ValueError as e:
-                    return str(e)
-
-                issue_repo_result = self.get_issue_repo(owner=issue_owner_name, repo_name=issue_repo_name)
-                repository_id, labels, assignable_users = self._get_repo_extra_info(issue_repo_result)
-            else:
-                repository_id, labels, assignable_users = self._get_repo_extra_info(result)
-        except Exception as e:
-            return f"Project has not been found. Error: {str(e)}"
+        # Get project data with type safety check
+        result = self.get_project(owner=owner_name, repo_name=repo_name, project_title=project_title)
+
+        # Type check: get_project() returns str on error, dict on success
+        if isinstance(result, str):
+            return self._format_project_error(result)
+
+        project = result.get("project")
+        project_id = result.get("projectId")
+
+        if issue_repo:
+            try:
+                issue_owner_name, issue_repo_name = self._parse_repo(issue_repo)
+            except ValueError as e:
+                return str(e)
+
+            issue_repo_result = self.get_issue_repo(owner=issue_owner_name, repo_name=issue_repo_name)
+
+            # Type check: get_issue_repo() returns str on error, dict on success
+            if isinstance(issue_repo_result, str):
+                return self._format_repo_error(issue_repo_result)
+
+            repository_id, labels, assignable_users = self._get_repo_extra_info(issue_repo_result)
+        else:
+            repository_id, labels, assignable_users = self._get_repo_extra_info(result)
 
         missing_fields = []
         fields_to_update = []
+        updated_fields = []
 
         if fields:
             try:

alita_sdk/tools/github/schemas.py

@@ -1,6 +1,9 @@
 from typing import Dict, List, Optional, Any
 from pydantic import BaseModel, Field, SecretStr, create_model
 
+from alita_sdk.tools.utils.tool_prompts import UPDATE_FILE_PROMPT_WITH_PATH
+
+
 # Base schemas for GitHub API wrapper
 class GitHubAuthConfig(BaseModel):
     github_access_token: Optional[SecretStr] = None
@@ -28,6 +31,12 @@ CreateBranchName = create_model(
     proposed_branch_name=(str, Field(description="The name of the new branch to create, e.g. `feature-branch`"))
 )
 
+DeleteBranchName = create_model(
+    "DeleteBranchName",
+    branch_name=(str, Field(description="The name of the branch to delete, e.g. `feature-branch`")),
+    force=(Optional[bool], Field(default=False, description="Force deletion even if branch is the current active branch"))
+)
+
 DirectoryPath = create_model(
     "DirectoryPath",
     directory_path=(str, Field(description="The path of the directory, e.g. `src/my_dir`"))
@@ -42,7 +51,7 @@ ReadFile = create_model(
 
 UpdateFile = create_model(
     "UpdateFile",
-    file_query=(str, Field(description="File path and content to update with OLD and NEW markers")),
+    file_query=(str, Field(description=UPDATE_FILE_PROMPT_WITH_PATH)),
     repo_name=(Optional[str], Field(default=None, description="Name of the repository (e.g., 'owner/repo'). If None, uses the default repository.")),
     commit_message=(Optional[str], Field(default=None, description="Commit message for the update operation")),
 )
@@ -92,7 +101,7 @@ SearchIssues = create_model(
     "SearchIssues",
     search_query=(str, Field(description="Keywords or query for searching issues and PRs in Github")),
     repo_name=(Optional[str], Field(description="Name of the repository to search issues in", default=None)),
-    max_count=(Optional[int], Field(description="Maximum number of issues to return", default=30))
+    max_count=(Optional[int], Field(description="Maximum number of issues to return", default=30, gt=0))
 )
 
 CreateIssue = create_model(
@@ -152,7 +161,7 @@ GetCommits = create_model(
     since=(Optional[str], Field(description="Only commits after this date will be returned (ISO format)", default=None)),
     until=(Optional[str], Field(description="Only commits before this date will be returned (ISO format)", default=None)),
     author=(Optional[str], Field(description="The author of the commits", default=None)),
-    max_count=(Optional[int], Field(description="Maximum number of commits to return (default: 30)", default=30))
+    max_count=(Optional[int], Field(description="Maximum number of commits to return (default: 30)", default=30, gt=0))
 )
 
 GetCommitChanges = create_model(
@@ -213,7 +222,7 @@ ListProjectIssues = create_model(
     "ListProjectIssues",
     board_repo=(str, Field(description="The organization and repository for the board (project). Example: 'org-name/repo-name'")),
     project_number=(int, Field(description="The project number as shown in the project URL")),
-    items_count=(Optional[int], Field(description="Maximum number of items to retrieve", default=100))
+    items_count=(Optional[int], Field(description="Maximum number of items to retrieve", default=100, gt=0))
 )
 
 SearchProjectIssues = create_model(
@@ -221,7 +230,7 @@ SearchProjectIssues = create_model(
     board_repo=(str, Field(description="The organization and repository for the board (project). Example: 'org-name/repo-name'")),
     project_number=(int, Field(description="The project number as shown in the project URL")),
     search_query=(str, Field(description="Search query for filtering issues. Examples: 'status:In Progress', 'release:v1.0'")),
-    items_count=(Optional[int], Field(description="Maximum number of items to retrieve", default=100))
+    items_count=(Optional[int], Field(description="Maximum number of items to retrieve", default=100, gt=0))
 )
 
 ListProjectViews = create_model(

alita_sdk/tools/github/tool.py

@@ -29,6 +29,10 @@ class GitHubAction(BaseTool):
     ) -> str:
         """Use the GitHub API to run an operation."""
         try:
-            return self.api_wrapper.run(self.mode, *args, **kwargs)
+            # Strip numeric suffix added for deduplication (_2, _3, etc.)
+            # to get the original tool name that exists in the wrapper
+            import re
+            mode = re.sub(r'_\d+$', '', self.mode) if self.mode else self.mode
+            return self.api_wrapper.run(mode, *args, **kwargs)
         except Exception as e:
             return f"Error: {format_exc()}"

alita_sdk/tools/github/tool_prompts.py

@@ -1,31 +1,18 @@
 CREATE_FILE_PROMPT = """Create new file in your github repository."""
 
-UPDATE_FILE_PROMPT = """Updates the contents of a file in repository. Input MUST strictly follow these rules:
-Specify the file to modify by passing a full file path (the path must not start with a slash); Specify at lest 2 lines of the old contents which you would like to replace wrapped in OLD <<<< and >>>> OLD; Specify the new contents which you would like to replace the old contents with wrapped in NEW <<<< and >>>> NEW; NEW content may contain lines from OLD content in case you want to add content without removing the old content
 
-Example 1: Replace "old contents" to "new contents" in the file /test/test.txt from , pass in the following string:
+DELETE_BRANCH_PROMPT = """Delete a branch from the GitHub repository.
 
-test/test.txt
+IMPORTANT: This tool will NOT delete protected branches:
+- 'main' and 'master' branches are always protected
+- The configured base branch is protected
+- The currently active branch is protected (unless force=True)
 
-This is text that will not be changed
-OLD <<<<
-old contents
->>>> OLD
-NEW <<<<
-new contents
->>>> NEW
+Parameters:
+- branch_name: The name of the branch to delete (e.g., 'feature-branch')
+- force: Set to True to delete even if it's the current active branch (default: False)
 
-Example 2: Extend "existing contents" with new contents" in the file /test/test.txt, pass in the following string:
-
-test/test.txt
-
-OLD <<<<
-existing contents
->>>> OLD
-NEW <<<<
-existing contents
-new contents
->>>> NEW"""
+Returns a success or error message."""
 
 CREATE_ISSUE_PROMPT = """
 Tool allows to create a new issue in a GitHub repository.

alita_sdk/tools/gitlab/__init__.py

@@ -8,14 +8,15 @@ from pydantic.fields import Field
 
 from .api_wrapper import GitLabAPIWrapper
 from ..elitea_base import filter_missconfigured_index_tools
-from ..utils import clean_string, TOOLKIT_SPLITTER, get_max_toolkit_length
+from ..utils import clean_string, get_max_toolkit_length
 from ...configurations.gitlab import GitlabConfiguration
 from ...configurations.pgvector import PgVectorConfiguration
+from ...runtime.utils.constants import TOOLKIT_NAME_META, TOOL_NAME_META, TOOLKIT_TYPE_META
 
 name = "gitlab"
 
 
-def get_tools(tool):
+def get_toolkit(tool):
     return AlitaGitlabToolkit().get_toolkit(
         selected_tools=tool['settings'].get('selected_tools', []),
         repository=tool['settings']['repository'],
@@ -30,20 +31,21 @@ def get_tools(tool):
         embedding_model=tool['settings'].get('embedding_model'),
         vectorstore_type="PGVector",
         toolkit_name=tool.get('toolkit_name')
-    ).get_tools()
+    )
+
+def get_tools(tool):
+    return get_toolkit(tool).get_tools()
 
 class AlitaGitlabToolkit(BaseToolkit):
     tools: List[BaseTool] = []
-    toolkit_max_length: int = 0
 
     @staticmethod
     def toolkit_config_schema() -> BaseModel:
         selected_tools = {x['name']: x['args_schema'].schema() for x in
                           GitLabAPIWrapper.model_construct().get_available_tools()}
-        AlitaGitlabToolkit.toolkit_max_length = get_max_toolkit_length(selected_tools)
         return create_model(
             name,
-            repository=(str, Field(description="GitLab repository", json_schema_extra={'toolkit_name': True, 'max_toolkit_length': AlitaGitlabToolkit.toolkit_max_length})),
+            repository=(str, Field(description="GitLab repository")),
             gitlab_configuration=(GitlabConfiguration, Field(description="GitLab configuration", json_schema_extra={'configuration_types': ['gitlab']})),
             branch=(str, Field(description="Main branch", default="main")),
             # indexer settings
@@ -76,19 +78,22 @@ class AlitaGitlabToolkit(BaseToolkit):
             **(kwargs.get('embedding_configuration') or {}),
         }
         gitlab_api_wrapper = GitLabAPIWrapper(**wrapper_payload)
-        prefix = clean_string(toolkit_name, cls.toolkit_max_length) + TOOLKIT_SPLITTER if toolkit_name else ''
         available_tools: List[Dict] = gitlab_api_wrapper.get_available_tools()
         tools = []
         for tool in available_tools:
             if selected_tools:
                 if tool["name"] not in selected_tools:
                     continue
-
+            description = tool["description"] +  f"\nrepo: {gitlab_api_wrapper.repository}"
+            if toolkit_name:
+                description = f"{description}\nToolkit: {toolkit_name}"
+            description = description[:1000]
             tools.append(BaseAction(
                 api_wrapper=gitlab_api_wrapper,
-                name=prefix + tool["name"],
-                description=tool["description"] +  f"\nrepo: {gitlab_api_wrapper.repository}",
-                args_schema=tool["args_schema"]
+                name=tool["name"],
+                description=description,
+                args_schema=tool["args_schema"],
+                metadata={TOOLKIT_NAME_META: toolkit_name, TOOLKIT_TYPE_META: name, TOOL_NAME_META: tool["name"]} if toolkit_name else {TOOL_NAME_META: tool["name"]}
             ))
         return cls(tools=tools)