alita-sdk 0.3.276__tar.gz → 0.3.432__tar.gz

{alita_sdk-0.3.276 → alita_sdk-0.3.432}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: alita_sdk
-Version: 0.3.276
+Version: 0.3.432
 Summary: SDK for building langchain agents using resources from Alita
-Author-email: Artem Rozumenko <artyom.rozumenko@gmail.com>, Mikalai Biazruchka <mikalai_biazruchka@epam.com>, Roman Mitusov <roman_mitusov@epam.com>, Ivan Krakhmaliuk <lifedjik@gmail.com>, Artem Dubrovskiy <ad13box@gmail.com>
+Author-email: Artem Rozumenko <artyom.rozumenko@gmail.com>, Mikalai Biazruchka <mikalai_biazruchka@epam.com>, Roman Mitusov <roman_mitusov@epam.com>, Ivan Krakhmaliuk <lifedj27@gmail.com>, Artem Dubrovskiy <ad13box@gmail.com>
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://projectalita.ai
 Project-URL: Issues, https://github.com/ProjectAlita/alita-sdk/issues
@@ -25,60 +25,64 @@ Requires-Dist: httpcore==1.0.7
 Requires-Dist: urllib3>=2
 Requires-Dist: certifi==2024.8.30
 Provides-Extra: runtime
-Requires-Dist: langchain_core==0.3.49; extra == "runtime"
-Requires-Dist: langchain<=0.3.22; extra == "runtime"
-Requires-Dist: langchain_community~=0.3.7; extra == "runtime"
-Requires-Dist: langchain-openai~=0.3.0; extra == "runtime"
+Requires-Dist: streamlit>=1.28.0; extra == "runtime"
+Requires-Dist: langchain_core<0.4.0,>=0.3.76; extra == "runtime"
+Requires-Dist: langchain<0.4.0,>=0.3.22; extra == "runtime"
+Requires-Dist: langchain_community<0.4.0,>=0.3.7; extra == "runtime"
+Requires-Dist: langchain-openai<0.4.0,>=0.3.0; extra == "runtime"
+Requires-Dist: langchain-anthropic<0.4.0,>=0.3.10; extra == "runtime"
+Requires-Dist: anthropic>=0.57.0; extra == "runtime"
+Requires-Dist: langgraph<0.5,>=0.4.8; extra == "runtime"
+Requires-Dist: langgraph-prebuilt==0.5.2; extra == "runtime"
 Requires-Dist: langgraph-checkpoint-sqlite~=2.0.0; extra == "runtime"
 Requires-Dist: langgraph-checkpoint-postgres==2.0.21; extra == "runtime"
 Requires-Dist: langsmith>=0.3.45; extra == "runtime"
-Requires-Dist: langgraph<0.5,>=0.4.8; extra == "runtime"
-Requires-Dist: langchain_chroma~=0.2.2; extra == "runtime"
+Requires-Dist: langchain_chroma<0.3.0,>=0.2.2; extra == "runtime"
+Requires-Dist: chromadb==0.5.20; extra == "runtime"
+Requires-Dist: pgvector==0.2.5; extra == "runtime"
 Requires-Dist: langchain-unstructured~=0.1.6; extra == "runtime"
 Requires-Dist: langchain-postgres~=0.0.13; extra == "runtime"
-Requires-Dist: keybert==0.8.3; extra == "runtime"
-Requires-Dist: charset_normalizer==3.3.2; extra == "runtime"
 Requires-Dist: unstructured[local-inference]==0.16.23; extra == "runtime"
 Requires-Dist: unstructured_pytesseract==0.3.13; extra == "runtime"
 Requires-Dist: unstructured_inference==0.8.7; extra == "runtime"
 Requires-Dist: python-pptx==1.0.2; extra == "runtime"
-Requires-Dist: pdf2image==1.16.3; extra == "runtime"
-Requires-Dist: pikepdf==8.7.1; extra == "runtime"
-Requires-Dist: pypdf==4.3.1; extra == "runtime"
-Requires-Dist: pdfminer.six==20240706; extra == "runtime"
-Requires-Dist: opencv-python==4.11.0.86; extra == "runtime"
 Requires-Dist: python-docx==1.1.2; extra == "runtime"
 Requires-Dist: openpyxl==3.1.2; extra == "runtime"
-Requires-Dist: markdown==3.5.1; extra == "runtime"
-Requires-Dist: beautifulsoup4==4.12.2; extra == "runtime"
-Requires-Dist: gensim==4.3.3; extra == "runtime"
-Requires-Dist: chromadb==0.5.20; extra == "runtime"
-Requires-Dist: pgvector==0.2.5; extra == "runtime"
-Requires-Dist: scipy==1.13.1; extra == "runtime"
-Requires-Dist: pytesseract==0.3.13; extra == "runtime"
+Requires-Dist: pypdf==4.3.1; extra == "runtime"
+Requires-Dist: pdfminer.six==20240706; extra == "runtime"
+Requires-Dist: pdf2image==1.16.3; extra == "runtime"
+Requires-Dist: pikepdf==8.7.1; extra == "runtime"
+Requires-Dist: docx2txt==0.8; extra == "runtime"
+Requires-Dist: mammoth==1.9.0; extra == "runtime"
 Requires-Dist: reportlab==4.2.5; extra == "runtime"
 Requires-Dist: svglib==1.5.1; extra == "runtime"
-Requires-Dist: rlpycairo==0.3.0; extra == "runtime"
 Requires-Dist: cairocffi==1.7.1; extra == "runtime"
-Requires-Dist: docx2txt==0.8; extra == "runtime"
-Requires-Dist: mammoth==1.9.0; extra == "runtime"
+Requires-Dist: rlpycairo==0.3.0; extra == "runtime"
+Requires-Dist: keybert==0.8.3; extra == "runtime"
+Requires-Dist: sentence-transformers==2.7.0; extra == "runtime"
+Requires-Dist: gensim==4.3.3; extra == "runtime"
+Requires-Dist: scipy==1.13.1; extra == "runtime"
+Requires-Dist: opencv-python==4.11.0.86; extra == "runtime"
+Requires-Dist: pytesseract==0.3.13; extra == "runtime"
+Requires-Dist: markdown==3.5.1; extra == "runtime"
+Requires-Dist: beautifulsoup4==4.12.2; extra == "runtime"
+Requires-Dist: charset_normalizer==3.3.2; extra == "runtime"
 Requires-Dist: opentelemetry-exporter-otlp-proto-grpc==1.25.0; extra == "runtime"
 Requires-Dist: opentelemetry_api==1.25.0; extra == "runtime"
 Requires-Dist: opentelemetry_instrumentation==0.46b0; extra == "runtime"
 Requires-Dist: grpcio_status==1.63.0rc1; extra == "runtime"
 Requires-Dist: protobuf==4.25.7; extra == "runtime"
-Requires-Dist: sentence-transformers==2.7.0; extra == "runtime"
+Requires-Dist: langchain-sandbox>=0.0.6; extra == "runtime"
 Provides-Extra: tools
 Requires-Dist: dulwich==0.21.6; extra == "tools"
 Requires-Dist: paramiko==3.3.1; extra == "tools"
 Requires-Dist: pygithub==2.3.0; extra == "tools"
 Requires-Dist: python-gitlab==4.5.0; extra == "tools"
 Requires-Dist: gitpython==3.1.43; extra == "tools"
-Requires-Dist: atlassian-python-api~=3.41; extra == "tools"
-Requires-Dist: atlassian_python_api==3.41.16; extra == "tools"
+Requires-Dist: atlassian-python-api~=4.0.7; extra == "tools"
 Requires-Dist: jira==3.8.0; extra == "tools"
 Requires-Dist: qtest-swagger-client==0.0.3; extra == "tools"
-Requires-Dist: testrail-api==1.13.2; extra == "tools"
+Requires-Dist: testrail-api==1.13.4; extra == "tools"
 Requires-Dist: azure-devops==7.1.0b4; extra == "tools"
 Requires-Dist: msrest==0.7.1; extra == "tools"
 Requires-Dist: python-graphql-client~=0.4.3; extra == "tools"
@@ -97,8 +101,6 @@ Requires-Dist: azure-search-documents==11.5.2; extra == "tools"
 Requires-Dist: PyMySQL==1.1.1; extra == "tools"
 Requires-Dist: psycopg2-binary==2.9.10; extra == "tools"
 Requires-Dist: Office365-REST-Python-Client==2.5.14; extra == "tools"
-Requires-Dist: python-docx==1.1.2; extra == "tools"
-Requires-Dist: python-pptx==1.0.2; extra == "tools"
 Requires-Dist: pypdf2~=3.0.1; extra == "tools"
 Requires-Dist: FigmaPy==2018.1.0; extra == "tools"
 Requires-Dist: pandas==2.2.3; extra == "tools"
@@ -115,7 +117,6 @@ Requires-Dist: playwright>=1.52.0; extra == "tools"
 Requires-Dist: google-api-python-client==2.154.0; extra == "tools"
 Requires-Dist: wikipedia==1.4.0; extra == "tools"
 Requires-Dist: lxml==5.2.2; extra == "tools"
-Requires-Dist: beautifulsoup4; extra == "tools"
 Requires-Dist: pymupdf==1.24.9; extra == "tools"
 Requires-Dist: googlemaps==4.10.0; extra == "tools"
 Requires-Dist: yagmail==0.15.293; extra == "tools"
@@ -127,6 +128,7 @@ Requires-Dist: textract-py3==2.1.1; extra == "tools"
 Requires-Dist: slack_sdk==3.35.0; extra == "tools"
 Requires-Dist: deltalake==1.0.2; extra == "tools"
 Requires-Dist: google_cloud_bigquery==3.34.0; extra == "tools"
+Requires-Dist: python-calamine==0.5.3; extra == "tools"
 Provides-Extra: community
 Requires-Dist: retry-extended==0.2.3; extra == "community"
 Requires-Dist: pyobjtojson==0.3; extra == "community"

alita_sdk-0.3.432/alita_sdk/configurations/bitbucket.py

@@ -0,0 +1,127 @@
+from typing import Optional
+
+from atlassian import Bitbucket
+from pydantic import BaseModel, ConfigDict, Field, SecretStr
+
+
+class BitbucketConfiguration(BaseModel):
+    model_config = ConfigDict(
+        json_schema_extra={
+            "metadata": {
+                "label": "Bitbucket",
+                "icon_url": "bitbucket-icon.svg",
+                "sections": {
+                    "auth": {
+                        "required": True,
+                        "subsections": [
+                            {
+                                "name": "Username & Password",
+                                "fields": ["username", "password"]
+                            }
+                        ]
+                    },
+                },
+                "section": "credentials",
+                "type": "bitbucket",
+                "categories": ["code repositories"],
+                "extra_categories": ["bitbucket", "git", "repository", "code", "version control"],
+            }
+        }
+    )
+    url: str = Field(description="Bitbucket URL")
+    username: str = Field(description="Bitbucket Username")
+    password: SecretStr = Field(description="Bitbucket Password/App Password")
+
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """
+        Check the connection to Bitbucket.
+        
+        Args:
+            settings: Dictionary containing Bitbucket configuration
+                - url: Bitbucket instance URL (required)
+                - username: Bitbucket username (required)
+                - password: Password or App Password (required)
+        
+        Returns:
+            None if connection successful, error message string if failed
+        """
+        import requests
+        from requests.auth import HTTPBasicAuth
+        
+        # Validate url
+        url = settings.get("url", "").strip()
+        if not url:
+            return "Bitbucket URL is required"
+        
+        # Normalize URL - remove trailing slashes
+        url = url.rstrip("/")
+        
+        # Basic URL validation
+        if not url.startswith(("http://", "https://")):
+            return "Bitbucket URL must start with http:// or https://"
+        
+        # Validate username
+        username = settings.get("username", "").strip()
+        if not username:
+            return "Bitbucket username is required"
+        
+        # Validate password
+        password = settings.get("password")
+        if not password:
+            return "Bitbucket password is required"
+        
+        # Extract password value if it's a SecretStr
+        password_value = password.get_secret_value() if hasattr(password, 'get_secret_value') else password
+        
+        if not password_value or not str(password_value).strip():
+            return "Bitbucket password cannot be empty"
+        
+        # Detect if this is Bitbucket Cloud or Server/Data Center
+        is_cloud = "bitbucket.org" in url.lower() or "api.bitbucket.org" in url.lower()
+        is_correct_bitbucket_domain = "bitbucket" in url.lower()
+        
+        if is_cloud:
+            # Bitbucket Cloud: Use API v2.0
+            # Endpoint: /2.0/user - returns current authenticated user
+            test_url = f"{url}/2.0/user"
+        else:
+            # Bitbucket Server/Data Center: Use API v1.0
+            # Endpoint: /rest/api/1.0/users/{username}
+            test_url = f"{url}/rest/api/1.0/users/{username}"
+        
+        try:
+            response = requests.get(
+                test_url,
+                auth=HTTPBasicAuth(username, str(password_value).strip()),
+                timeout=10
+            )
+            
+            # Check response status
+            if response.status_code == 200:
+                # Successfully connected and authenticated
+                return None
+            elif response.status_code == 401:
+                return "Authentication failed: invalid username or password"
+            elif response.status_code == 403:
+                return "Access forbidden: check user permissions"
+            elif response.status_code == 404:
+                if not is_correct_bitbucket_domain:
+                    return f"Url you provided is incorrect. Please provide correct server or cloud bitbucket url."
+                if is_cloud:
+                    return "Bitbucket API endpoint not found: please provide the correct bitbucket cloud URL"
+                else:
+                    return "Bitbucket API endpoint not found: please provide the correct bitbucket server URL"
+            else:
+                return f"Bitbucket API returned status code {response.status_code}"
+
+        except requests.exceptions.SSLError as e:
+            return f"SSL certificate verification failed: {str(e)}"
+        except requests.exceptions.ConnectionError:
+            return f"Cannot connect to Bitbucket at {url if not is_cloud else 'api.bitbucket.org'}: connection refused"
+        except requests.exceptions.Timeout:
+            return f"Connection to Bitbucket at {url if not is_cloud else 'api.bitbucket.org'} timed out"
+        except requests.exceptions.RequestException as e:
+            return f"Error connecting to Bitbucket: {str(e)}"
+        except Exception as e:
+            return f"Unexpected error: {str(e)}"

{alita_sdk-0.3.276 → alita_sdk-0.3.432}/alita_sdk/configurations/browser.py

@@ -15,4 +15,4 @@ class BrowserConfiguration(BaseModel):
         }
     )
     google_cse_id: str = Field(description="Google CSE id", default=None)
-    google_api_key: SecretStr = Field(description="Google API key", default=None, json_schema_extra={'secret': True})
+    google_api_key: SecretStr = Field(description="Google API key", json_schema_extra={'secret': True})

alita_sdk-0.3.432/alita_sdk/configurations/confluence.py

@@ -0,0 +1,132 @@
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr
+
+
+class ConfluenceConfiguration(BaseModel):
+    model_config = ConfigDict(
+        json_schema_extra={
+            "metadata": {
+                "label": "Confluence",
+                "icon_url": "confluence.svg",
+                "sections": {
+                    "auth": {
+                        "required": True,
+                        "subsections": [
+                            {
+                                "name": "Basic",
+                                "fields": ["username", "api_key"]
+                            },
+                            {
+                                "name": "Bearer",
+                                "fields": ["token"]
+                            }
+                        ]
+                    },
+                },
+                "section": "credentials",
+                "type": "confluence",
+                "categories": ["documentation"],
+                "extra_categories": ["confluence", "wiki", "documentation", "knowledge base"],
+            }
+        }
+    )
+    base_url: str = Field(description="Confluence URL")
+    username: Optional[str] = Field(description="Confluence Username", default=None)
+    api_key: Optional[SecretStr] = Field(description="Confluence API Key", default=None)
+    token: Optional[SecretStr] = Field(description="Confluence Token", default=None)
+
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """
+        Check the connection to Confluence.
+        
+        Args:
+            settings: Dictionary containing Confluence configuration
+                - base_url: Confluence instance URL (required)
+                - username: Username for Basic Auth (optional)
+                - api_key: API key/password for Basic Auth (optional)
+                - token: Bearer token for authentication (optional)
+        
+        Returns:
+            None if connection successful, error message string if failed
+        """
+        import requests
+        from requests.auth import HTTPBasicAuth
+        
+        # Validate base_url
+        base_url = settings.get("base_url", "").strip()
+        if not base_url:
+            return "Confluence URL is required"
+        
+        # Normalize URL - remove trailing slashes
+        base_url = base_url.rstrip("/")
+        
+        # Basic URL validation
+        if not base_url.startswith(("http://", "https://")):
+            return "Confluence URL must start with http:// or https://"
+        
+        # Check authentication credentials
+        username = settings.get("username")
+        api_key = settings.get("api_key")
+        token = settings.get("token")
+
+        # Validate authentication - at least one method must be provided
+        has_basic_auth = bool(username and api_key)
+        has_token = bool(token and str(token).strip())
+        
+        # Determine authentication method
+        auth_headers = {}
+        auth = None
+        
+        if has_token:
+            # Bearer token authentication
+            token_value = token.get_secret_value() if hasattr(token, 'get_secret_value') else token
+            auth_headers["Authorization"] = f"Bearer {token_value}"
+        elif has_basic_auth:
+            # Basic authentication
+            api_key_value = api_key.get_secret_value() if hasattr(api_key, 'get_secret_value') else api_key
+            auth = HTTPBasicAuth(username, api_key_value)
+        else:
+            return "Authentication required: provide either token or both username and api_key"
+        
+        # Test connection using /rest/api/user/current endpoint
+        # This endpoint returns current user info and validates authentication
+        test_url = f"{base_url}/rest/api/user/current"
+        
+        try:
+            response = requests.get(
+                test_url,
+                auth=auth,
+                headers=auth_headers,
+                timeout=10
+            )
+            
+            # Check response status
+            if response.status_code == 200:
+                # Successfully connected and authenticated
+                return None
+            elif response.status_code == 401:
+                # Authentication failed
+                if has_token:
+                    return "Authentication failed: Invalid token"
+                else:
+                    return "Authentication failed: Invalid username or API key"
+            elif response.status_code == 403:
+                return """Access forbidden: check permissions and verify the credentials you provided.
+Most probably you provided incorrect credentials (user name and api key or token)"""
+            elif response.status_code == 404:
+                return "Confluence API endpoint not found: verify the Confluence URL"
+            else:
+                return f"Confluence API returned status code {response.status_code}"
+
+        except requests.exceptions.SSLError as e:
+            return f"SSL certificate verification failed: {str(e)}"
+        except requests.exceptions.ConnectionError:
+            return f"Cannot connect to Confluence at {base_url}: connection refused"
+        except requests.exceptions.Timeout:
+            return f"Connection to Confluence at {base_url} timed out"
+        except requests.exceptions.RequestException as e:
+            return f"Error connecting to Confluence: {str(e)}"
+        except Exception as e:
+            return f"Unexpected error: {str(e)}"

{alita_sdk-0.3.276 → alita_sdk-0.3.432}/alita_sdk/configurations/figma.py

@@ -16,10 +16,6 @@ class FigmaConfiguration(BaseModel):
                             {
                                 "name": "Token",
                                 "fields": ["token"]
-                            },
-                            {
-                                "name": "Oath2",
-                                "fields": ["oauth2"]
                             }
                         ]
                     }
@@ -32,4 +28,3 @@ class FigmaConfiguration(BaseModel):
         }
     )
     token: Optional[SecretStr] = Field(description="Figma Token", json_schema_extra={"secret": True}, default=None)
-    oauth2: Optional[SecretStr] = Field(description="OAuth2 Token", json_schema_extra={"secret": True}, default=None)

{alita_sdk-0.3.276 → alita_sdk-0.3.432}/alita_sdk/configurations/github.py

@@ -84,4 +84,68 @@ class GithubConfiguration(BaseModel):
             "Authentication is misconfigured: provide either Token (access_token), "
             "Password (username + password), App private key (app_id + app_private_key), "
             "or leave all blank for anonymous access."
-        )
+        )
+
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """
+        Check GitHub connection using provided settings.
+        Returns None if connection is successful, error message otherwise.
+        """
+        import requests
+        from requests.auth import HTTPBasicAuth
+        import jwt
+        import time
+
+        base_url = settings.get('base_url', 'https://api.github.com')
+        access_token = settings.get('access_token')
+        username = settings.get('username')
+        password = settings.get('password')
+        app_id = settings.get('app_id')
+        app_private_key = settings.get('app_private_key')
+
+        # if all auth methods are None or empty, allow anonymous access
+        if not any([access_token, (username and password), (app_id and app_private_key)]):
+            return None
+
+        headers = {'Accept': 'application/vnd.github.v3+json'}
+        auth = None
+
+        try:
+            # Determine authentication method
+            if access_token:
+                headers['Authorization'] = f'token {access_token}'
+            elif username and password:
+                auth = HTTPBasicAuth(username, password)
+            elif app_id and app_private_key:
+                # Generate JWT for GitHub App authentication
+                payload = {
+                    'iat': int(time.time()),
+                    'exp': int(time.time()) + 600,  # 10 minutes
+                    'iss': app_id
+                }
+                jwt_token = jwt.encode(payload, app_private_key, algorithm='RS256')
+                headers['Authorization'] = f'Bearer {jwt_token}'
+
+            # Test connection with user endpoint
+            response = requests.get(f'{base_url}/user', headers=headers, auth=auth, timeout=10)
+
+            if response.status_code == 200:
+                return None
+            elif response.status_code == 401:
+                return "Authentication failed: Invalid credentials"
+            elif response.status_code == 403:
+                return "Access forbidden: Check your permissions"
+            elif response.status_code == 404:
+                return "GitHub API endpoint not found"
+            else:
+                return f"Connection failed with status {response.status_code}: {response.text}"
+
+        except requests.exceptions.ConnectionError:
+            return "Connection error: Unable to reach GitHub API"
+        except requests.exceptions.Timeout:
+            return "Connection timeout: GitHub API did not respond in time"
+        except jwt.InvalidKeyError:
+            return "Invalid private key format for GitHub App authentication"
+        except Exception as e:
+            return f"Unexpected error: {str(e)}"

alita_sdk-0.3.432/alita_sdk/configurations/gitlab.py

@@ -0,0 +1,110 @@
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr
+
+
+class GitlabConfiguration(BaseModel):
+    model_config = ConfigDict(
+        json_schema_extra={
+            "metadata": {
+                "label": "GitLab",
+                "icon_url": None,
+                "sections": {
+                    "auth": {
+                        "required": True,
+                        "subsections": [
+                            {
+                                "name": "GitLab private token",
+                                "fields": ["private_token"]
+                            }
+                        ]
+                    }
+                },
+                "section": "credentials",
+                "type": "gitlab",
+                "categories": ["code repositories"],
+                "extra_categories": ["gitlab", "git", "repository", "code", "version control"],
+            }
+        }
+    )
+    url: str = Field(description="GitLab URL")
+    private_token: SecretStr = Field(description="GitLab private token")
+
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """
+        Check the connection to GitLab.
+        
+        Args:
+            settings: Dictionary containing GitLab configuration
+                - url: GitLab instance URL (required)
+                - private_token: GitLab private token for authentication (required)
+        
+        Returns:
+            None if connection successful, error message string if failed
+        """
+        import requests
+        
+        # Validate url
+        url = settings.get("url", "").strip()
+        if not url:
+            return "GitLab URL is required"
+        
+        # Normalize URL - remove trailing slashes
+        url = url.rstrip("/")
+        
+        # Basic URL validation
+        if not url.startswith(("http://", "https://")):
+            return "GitLab URL must start with http:// or https://"
+        
+        # Validate private_token
+        private_token = settings.get("private_token")
+        if not private_token:
+            return "GitLab private token is required"
+        
+        # Extract token value if it's a SecretStr
+        token_value = private_token.get_secret_value() if hasattr(private_token, 'get_secret_value') else private_token
+        
+        if not token_value or not str(token_value).strip():
+            return "GitLab private token cannot be empty"
+        
+        # Test connection using /api/v4/user endpoint
+        # This endpoint returns current authenticated user info
+        test_url = f"{url}/api/v4/user"
+        
+        # GitLab supports both PRIVATE-TOKEN header and Authorization Bearer
+        # Using PRIVATE-TOKEN is GitLab-specific and more explicit
+        headers = {
+            "PRIVATE-TOKEN": str(token_value).strip()
+        }
+        
+        try:
+            response = requests.get(
+                test_url,
+                headers=headers,
+                timeout=10
+            )
+            
+            # Check response status
+            if response.status_code == 200:
+                # Successfully connected and authenticated
+                return None
+            elif response.status_code == 401:
+                return "Authentication failed: invalid private token"
+            elif response.status_code == 403:
+                return "Access forbidden: token lacks required permissions"
+            elif response.status_code == 404:
+                return "GitLab API endpoint not found: verify the GitLab URL"
+            else:
+                return f"GitLab API returned status code {response.status_code}"
+
+        except requests.exceptions.SSLError as e:
+            return f"SSL certificate verification failed: {str(e)}"
+        except requests.exceptions.ConnectionError:
+            return f"Cannot connect to GitLab at {url}: connection refused"
+        except requests.exceptions.Timeout:
+            return f"Connection to GitLab at {url} timed out"
+        except requests.exceptions.RequestException as e:
+            return f"Error connecting to GitLab: {str(e)}"
+        except Exception as e:
+            return f"Unexpected error: {str(e)}"