alita-sdk 0.3.486__py3-none-any.whl → 0.3.515__py3-none-any.whl

alita_sdk/community/inventory/toolkit_utils.py

@@ -0,0 +1,176 @@
+"""
+Toolkit configuration and instantiation utilities for inventory ingestion.
+
+This module provides functions to load toolkit configurations, instantiate source
+toolkits from various sources (filesystem, GitHub, ADO), and get LLM instances
+for entity extraction.
+"""
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from alita_sdk.alita_client import AlitaClient
+
+
+def load_toolkit_config(toolkit_path: str) -> Dict[str, Any]:
+    """
+    Load and parse a toolkit config JSON file.
+    
+    Supports environment variable substitution for values like ${GITHUB_PAT}.
+    
+    Args:
+        toolkit_path: Path to the toolkit configuration JSON file
+        
+    Returns:
+        Dictionary containing the parsed and environment-resolved configuration
+        
+    Example:
+        >>> config = load_toolkit_config("configs/github_toolkit.json")
+        >>> config['type']
+        'github'
+    """
+    with open(toolkit_path, 'r') as f:
+        config = json.load(f)
+    
+    # Recursively resolve environment variables
+    def resolve_env_vars(obj):
+        if isinstance(obj, str):
+            # Match ${VAR_NAME} pattern
+            pattern = r'\$\{([^}]+)\}'
+            matches = re.findall(pattern, obj)
+            for var_name in matches:
+                env_value = os.environ.get(var_name, '')
+                obj = obj.replace(f'${{{var_name}}}', env_value)
+            return obj
+        elif isinstance(obj, dict):
+            return {k: resolve_env_vars(v) for k, v in obj.items()}
+        elif isinstance(obj, list):
+            return [resolve_env_vars(item) for item in obj]
+        return obj
+    
+    return resolve_env_vars(config)
+
+
+def get_llm_for_config(
+    client: AlitaClient,
+    model: Optional[str] = None,
+    temperature: float = 0.0
+):
+    """
+    Get LLM instance from Alita client for entity extraction.
+    
+    Args:
+        client: AlitaClient instance
+        model: Model name (defaults to 'gpt-4o-mini' if not specified)
+        temperature: Temperature for the model (default 0.0 for deterministic output)
+        
+    Returns:
+        LLM instance configured with the specified model and parameters
+        
+    Example:
+        >>> client = AlitaClient(...)
+        >>> llm = get_llm_for_config(client, model='gpt-4o', temperature=0.0)
+    """
+    model_name = model or 'gpt-4o-mini'
+    
+    return client.get_llm(
+        model_name=model_name,
+        model_config={
+            'temperature': temperature,
+            'max_tokens': 4096
+        }
+    )
+
+
+def get_source_toolkit(toolkit_config: Dict[str, Any]):
+    """
+    Instantiate a source toolkit from configuration.
+    
+    Supports filesystem, GitHub, and Azure DevOps (ADO) toolkit types. For SDK-based
+    toolkits (GitHub, ADO), automatically handles configuration mapping and toolkit
+    instantiation from the registry.
+    
+    Args:
+        toolkit_config: Toolkit configuration dictionary with 'type' key
+                       and type-specific parameters
+                       
+    Returns:
+        Instantiated toolkit object ready for ingestion
+        
+    Raises:
+        ValueError: If toolkit type is unsupported or configuration is invalid
+        
+    Example:
+        >>> # Filesystem toolkit
+        >>> config = {'type': 'filesystem', 'base_path': '/path/to/code'}
+        >>> toolkit = get_source_toolkit(config)
+        
+        >>> # GitHub toolkit
+        >>> config = {
+        ...     'type': 'github',
+        ...     'github_token': 'ghp_...',
+        ...     'github_repository': 'owner/repo',
+        ...     'github_branch': 'main'
+        ... }
+        >>> toolkit = get_source_toolkit(config)
+    """
+    from alita_sdk.community.inventory.filesystem_toolkit import FilesystemToolkit
+    from alita_sdk.community.toolkits import AVAILABLE_TOOLS
+    
+    toolkit_type = toolkit_config.get('type')
+    
+    if toolkit_type == 'filesystem':
+        base_path = toolkit_config.get('base_path')
+        if not base_path:
+            raise ValueError("Filesystem toolkit requires 'base_path' configuration")
+        return FilesystemToolkit(base_path=Path(base_path))
+    
+    # Handle SDK toolkits (GitHub, ADO)
+    if toolkit_type not in AVAILABLE_TOOLS:
+        raise ValueError(
+            f"Unknown toolkit type: {toolkit_type}. "
+            f"Available types: filesystem, {', '.join(AVAILABLE_TOOLS.keys())}"
+        )
+    
+    toolkit_class = AVAILABLE_TOOLS[toolkit_type]
+    
+    # Flatten nested config if needed
+    config_for_init = {}
+    for key, value in toolkit_config.items():
+        if key == 'type':
+            continue
+        if isinstance(value, dict):
+            # Flatten nested dicts
+            config_for_init.update(value)
+        else:
+            config_for_init[key] = value
+    
+    # Map field names for specific toolkit types
+    if toolkit_type == 'github':
+        field_mapping = {
+            'github_token': 'token',
+            'github_repository': 'repository',
+            'github_branch': 'branch'
+        }
+        config_for_init = {
+            field_mapping.get(k, k): v 
+            for k, v in config_for_init.items()
+        }
+    elif toolkit_type == 'ado':
+        field_mapping = {
+            'ado_token': 'token',
+            'ado_organization': 'organization',
+            'ado_project': 'project',
+            'ado_repository': 'repository',
+            'ado_branch': 'branch'
+        }
+        config_for_init = {
+            field_mapping.get(k, k): v 
+            for k, v in config_for_init.items()
+        }
+    
+    # Instantiate toolkit
+    return toolkit_class(**config_for_init)

alita_sdk/configurations/ado.py

@@ -1,5 +1,8 @@
+import re
 from typing import Optional
+from urllib.parse import quote
 
+import requests
 from pydantic import BaseModel, ConfigDict, Field, SecretStr
 
 
@@ -19,6 +22,147 @@ class AdoConfiguration(BaseModel):
     project: str = Field(description="ADO project")
     token: Optional[SecretStr] = Field(description="ADO Token")
 
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """
+        Test the connection to Azure DevOps API.
+
+        Args:
+            settings: Dictionary containing 'organization_url', 'project', and optionally 'token'
+
+        Returns:
+            None if connection is successful, error message string otherwise
+        """
+        organization_url = settings.get("organization_url")
+        if organization_url is None or organization_url == "":
+            if organization_url == "":
+                return "Organization URL cannot be empty"
+            return "Organization URL is required"
+
+        # Validate organization URL format
+        if not isinstance(organization_url, str):
+            return "Organization URL must be a string"
+
+        organization_url = organization_url.strip()
+        if not organization_url:
+            return "Organization URL cannot be empty"
+
+        if not organization_url.startswith(("http://", "https://")):
+            return "Organization URL must start with http:// or https://"
+
+        # Remove trailing slash for consistency
+        organization_url = organization_url.rstrip("/")
+
+        project = settings.get("project")
+        if project is None or project == "":
+            if project == "":
+                return "Project cannot be empty"
+            return "Project is required"
+
+        # Validate project format
+        if not isinstance(project, str):
+            return "Project must be a string"
+
+        project = project.strip()
+        if not project:
+            return "Project cannot be empty"
+
+        token = settings.get("token")
+
+        # Extract secret value if it's a SecretStr
+        if token is not None and hasattr(token, "get_secret_value"):
+            token = token.get_secret_value()
+
+        # Validate token if provided
+        if token is not None and (not token or not token.strip()):
+            return "Token cannot be empty if provided"
+
+        # NOTE on verification strategy:
+        # - Project endpoints can work anonymously for public projects.
+        #   That makes them a weak signal for detecting a bad/expired token.
+        # - If a token is provided, first validate it against a profile endpoint
+        #   that requires authentication, then check project access.
+
+        # Strictly require a canonical organization URL so we can build reliable API URLs.
+        # Supported formats:
+        # - https://dev.azure.com/<org>
+        # - https://<org>.visualstudio.com
+        org_name: str | None = None
+        org_url_kind: str | None = None  # 'dev.azure.com' | '*.visualstudio.com'
+        m = re.match(r"^https?://dev\.azure\.com/(?P<org>[^/]+)$", organization_url, flags=re.IGNORECASE)
+        if m:
+            org_name = m.group('org')
+            org_url_kind = 'dev.azure.com'
+        else:
+            m = re.match(r"^https?://(?P<org>[^/.]+)\.visualstudio\.com$", organization_url, flags=re.IGNORECASE)
+            if m:
+                org_name = m.group('org')
+                org_url_kind = '*.visualstudio.com'
+
+        if org_name is None:
+            return (
+                "Organization URL format is invalid. Use 'https://dev.azure.com/<org>' "
+                "(recommended) or 'https://<org>.visualstudio.com'."
+            )
+
+        project_encoded = quote(project, safe="")
+        project_url = f"{organization_url}/_apis/projects/{project_encoded}?api-version=7.0"
+        # Auth-required endpoint to validate PAT (works regardless of project visibility)
+        if org_url_kind == 'dev.azure.com':
+            profile_url = f"https://vssps.dev.azure.com/{org_name}/_apis/profile/profiles/me?api-version=7.1-preview.3"
+        else:
+            # For legacy org URLs, use the matching vssps host
+            profile_url = f"https://{org_name}.vssps.visualstudio.com/_apis/profile/profiles/me?api-version=7.1-preview.3"
+
+        try:
+            headers = {}
+            if token:
+                # Use Basic Auth with PAT token (username can be empty)
+                from requests.auth import HTTPBasicAuth
+                auth = HTTPBasicAuth("", token)
+
+                # 1) Validate token first (strong signal)
+                profile_resp = requests.get(profile_url, auth=auth, timeout=10)
+                if profile_resp.status_code == 200:
+                    pass
+                elif profile_resp.status_code == 401:
+                    return "Invalid or expired token (PAT). Please generate a new token and try again."
+                elif profile_resp.status_code == 403:
+                    return "Token is valid but lacks permission to access profile. Check PAT scopes/permissions."
+                elif profile_resp.status_code == 404:
+                    return "Organization not found. Verify the Organization URL."
+                else:
+                    return f"Token validation failed (HTTP {profile_resp.status_code})."
+
+                # 2) Validate project access
+                response = requests.get(project_url, auth=auth, timeout=10)
+            else:
+                # Try without authentication (works for public projects)
+                response = requests.get(project_url, headers=headers, timeout=10)
+
+            if response.status_code == 200:
+                return None  # Connection successful
+            elif response.status_code == 401:
+                if token:
+                    return "Not authorized. Token may be invalid for this organization or expired."
+                else:
+                    return "Authentication required - project may be private"
+            elif response.status_code == 403:
+                return "Access forbidden - token may lack required permissions for this project"
+            elif response.status_code == 404:
+                return f"Project '{project}' not found or not accessible. Check project name and organization URL."
+            else:
+                return f"Connection failed (HTTP {response.status_code})."
+
+        except requests.exceptions.Timeout:
+            return "Connection timeout - Azure DevOps did not respond within 10 seconds"
+        except requests.exceptions.ConnectionError:
+            return "Connection error - unable to reach Azure DevOps. Check the Organization URL and your network."
+        except requests.exceptions.RequestException as e:
+            return f"Request failed: {str(e)}"
+        except Exception:
+            return "Unexpected error during Azure DevOps connection check"
+
 
 class AdoReposConfiguration(BaseModel):
     model_config = ConfigDict(

alita_sdk/configurations/confluence.py

@@ -1,5 +1,7 @@
 from typing import Optional
+from urllib.parse import urlparse, urlunparse
 
+from atlassian import Confluence
 from pydantic import BaseModel, ConfigDict, Field, SecretStr
 
 
@@ -55,25 +57,53 @@ class ConfluenceConfiguration(BaseModel):
         from requests.auth import HTTPBasicAuth
         
         # Validate base_url
-        base_url = settings.get("base_url", "").strip()
+        base_url_input = settings.get("base_url", "")
+        base_url = base_url_input.strip() if isinstance(base_url_input, str) else ""
         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://"
+
+        # Normalize URL - remove trailing slashes
+        base_url = base_url.rstrip("/")
+
+        # Build candidate base URLs.
+        # Confluence Cloud REST API is typically under /wiki. Users often paste
+        # https://<site>.atlassian.net and shouldn't be forced to know about /wiki.
+        parsed = urlparse(base_url)
+        host = (parsed.hostname or "").lower()
+        path = parsed.path or ""
+
+        def with_wiki_path(url: str) -> str:
+            p = urlparse(url)
+            # Keep existing path if it already starts with /wiki
+            if (p.path or "").startswith("/wiki"):
+                return url
+            # Append /wiki, preserving any existing path (rare but safe)
+            new_path = (p.path or "") + "/wiki"
+            return urlunparse(p._replace(path=new_path.rstrip("/")))
+
+        candidate_base_urls: list[str] = []
+        if host.endswith(".atlassian.net"):
+            # For Atlassian Cloud, prefer the /wiki variant first
+            candidate_base_urls.append(with_wiki_path(base_url))
+        candidate_base_urls.append(base_url)
+        # De-duplicate while preserving order
+        candidate_base_urls = list(dict.fromkeys(candidate_base_urls))
         
         # Check authentication credentials
         username = settings.get("username")
         api_key = settings.get("api_key")
         token = settings.get("token")
 
+        api_key_value = api_key.get_secret_value() if hasattr(api_key, 'get_secret_value') else api_key
+        token_value = token.get_secret_value() if hasattr(token, 'get_secret_value') else 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())
+        has_basic_auth = bool(username and api_key_value and str(api_key_value).strip())
+        has_token = bool(token_value and str(token_value).strip())
         
         # Determine authentication method
         auth_headers = {}
@@ -81,52 +111,56 @@ class ConfluenceConfiguration(BaseModel):
         
         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}"
+            # Test connection using /rest/api/user/current endpoint
+            # This endpoint returns current user info and validates authentication
+            last_status = None
+            for candidate_base in candidate_base_urls:
+                test_url = f"{candidate_base}/rest/api/user/current"
+                response = requests.get(
+                    test_url,
+                    auth=auth,
+                    headers=auth_headers,
+                    timeout=10
+                )
+                last_status = response.status_code
+
+                if response.status_code == 200:
+                    return None
+
+                # If we get 404 on the first candidate, try the next one
+                if response.status_code == 404:
+                    continue
+
+                if response.status_code == 401:
+                    return "Invalid credentials (401) - check token or username/api_key"
+                if response.status_code == 403:
+                    return "Access forbidden (403) - credentials lack Confluence permissions"
+                if response.status_code == 429:
+                    return "Rate limited (429) - please try again later"
+                if 500 <= response.status_code <= 599:
+                    return f"Confluence service error (HTTP {response.status_code})"
+                return f"Confluence request failed (HTTP {response.status_code})"
+
+            # All candidates returned 404
+            return "Confluence API endpoint not found (404) - verify the Confluence URL"
 
         except requests.exceptions.SSLError as e:
-            return f"SSL certificate verification failed: {str(e)}"
+            if 'Hostname mismatch' in str(e):
+                return "SSL error - hostname mismatch. Verify the Confluence URL"
+            return "SSL error - certificate verification failed"
         except requests.exceptions.ConnectionError:
-            return f"Cannot connect to Confluence at {base_url}: connection refused"
+            return "Connection error - unable to reach Confluence. Check URL and network."
         except requests.exceptions.Timeout:
-            return f"Connection to Confluence at {base_url} timed out"
+            return "Connection timeout - Confluence did not respond within 10 seconds. Check URL and network."
         except requests.exceptions.RequestException as e:
-            return f"Error connecting to Confluence: {str(e)}"
-        except Exception as e:
-            return f"Unexpected error: {str(e)}"
+            return f"Request failed: {str(e)}"
+        except Exception:
+            return "Unexpected error during Confluence connection check"

alita_sdk/configurations/figma.py

@@ -1,8 +1,30 @@
+from json import JSONDecodeError
 from typing import Optional
 
+import requests
 from pydantic import BaseModel, ConfigDict, Field, SecretStr
 
 
+def _parse_error_response(response: requests.Response) -> Optional[str]:
+    """
+    Parse error response from Figma API to extract detailed error message.
+
+    Args:
+        response: Response object from requests
+
+    Returns:
+        Detailed error message if found, None otherwise
+    """
+    try:
+        json_response = response.json()
+        error = json_response.get("err") or json_response.get("error")
+        if error and 'Invalid token' in str(error):
+            return "Invalid token. Please verify the Figma token and try again."
+    except (JSONDecodeError, KeyError, AttributeError):
+        pass
+    return None
+
+
 class FigmaConfiguration(BaseModel):
     model_config = ConfigDict(
         json_schema_extra={
@@ -28,3 +50,57 @@ class FigmaConfiguration(BaseModel):
         }
     )
     token: Optional[SecretStr] = Field(description="Figma Token", json_schema_extra={"secret": True}, default=None)
+
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """
+        Test the connection to Figma API.
+
+        Args:
+            settings: Dictionary containing 'token' (required)
+
+        Returns:
+            None if connection is successful, error message string otherwise
+        """
+        token = settings.get("token")
+        if token is None:
+            return "Token is required"
+
+        # Extract secret value if it's a SecretStr
+        if hasattr(token, "get_secret_value"):
+            token = token.get_secret_value()
+
+        # Validate token is not empty
+        if not token or not token.strip():
+            return "Token cannot be empty"
+
+        # Figma API endpoint
+        base_url = "https://api.figma.com"
+        endpoint = f"{base_url}/v1/me"
+
+        try:
+            response = requests.get(
+                endpoint,
+                headers={"X-Figma-Token": token},
+                timeout=10,
+            )
+
+            if response.status_code == 200:
+                return None  # Connection successful
+            elif response.status_code == 401:
+                detailed_error = _parse_error_response(response)
+                return detailed_error if detailed_error else "Invalid token"
+            elif response.status_code == 403:
+                detailed_error = _parse_error_response(response)
+                return detailed_error if detailed_error else "Access forbidden - token may lack required permissions"
+            else:
+                return f"Connection failed with status {response.status_code}"
+
+        except requests.exceptions.Timeout:
+            return "Connection timeout - Figma API is not responding"
+        except requests.exceptions.ConnectionError:
+            return "Connection error - unable to reach Figma API"
+        except requests.exceptions.RequestException as e:
+            return f"Request failed: {str(e)}"
+        except Exception as e:
+            return f"Unexpected error: {str(e)}"

alita_sdk/configurations/gitlab.py

@@ -99,6 +99,8 @@ class GitlabConfiguration(BaseModel):
                 return f"GitLab API returned status code {response.status_code}"
 
         except requests.exceptions.SSLError as e:
+            if 'Hostname mismatch' in str(e):
+                return "GitLab API endpoint not found: verify the GitLab URL"
             return f"SSL certificate verification failed: {str(e)}"
         except requests.exceptions.ConnectionError:
             return f"Cannot connect to GitLab at {url}: connection refused"

alita_sdk/configurations/qtest.py

@@ -1,3 +1,6 @@
+import re
+
+import requests
 from pydantic import BaseModel, ConfigDict, Field, SecretStr
 
 
@@ -14,6 +17,74 @@ class QtestConfiguration(BaseModel):
             }
         }
     )
-    base_url: str = Field(description="QTest base url")
+    base_url: str = Field(description="QTest base URL")
     qtest_api_token: SecretStr = Field(description="QTest API token")
 
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """Check connectivity and credentials for qTest.
+
+        Strategy:
+        - Validate token against an auth-required endpoint (so an incorrect token is detected).
+
+        Returns:
+            None if successful, otherwise a short actionable error message.
+        """
+        base_url_input = settings.get("base_url")
+        base_url = base_url_input.strip() if isinstance(base_url_input, str) else ""
+        if not base_url:
+            return "QTest base URL is required"
+
+        if not base_url.startswith(("http://", "https://")):
+            return "QTest base URL must start with http:// or https://"
+
+        base_url = base_url.rstrip("/")
+        # If user pasted /api/v3 (or similar), strip it so we can build canonical API URLs.
+        base_url = re.sub(r"/api/v\d+/?$", "", base_url, flags=re.IGNORECASE)
+
+        token = settings.get("qtest_api_token")
+        if token is None:
+            return "QTest API token is required"
+        token_value = token.get_secret_value() if hasattr(token, "get_secret_value") else str(token)
+        if not token_value or not token_value.strip():
+            return "QTest API token cannot be empty"
+
+        headers = {
+            "Authorization": f"Bearer {token_value}",
+            "Content-Type": "application/json",
+        }
+
+        # Auth-required endpoint to validate the token.
+        # /projects works on v3 and requires auth in typical qTest deployments.
+        token_check_url = f"{base_url}/api/v3/projects?pageSize=1&page=1"
+
+        try:
+            resp = requests.get(token_check_url, headers=headers, timeout=10)
+            if resp.status_code == 200:
+                return None
+            elif resp.status_code == 401:
+                return "Invalid or expired QTest API token"
+            elif resp.status_code == 403:
+                return "Access forbidden - token lacks required permissions"
+            elif resp.status_code == 404:
+                return "QTest API not found (404) - verify base URL (do not include /api/v3)"
+            elif resp.status_code == 429:
+                return "Rate limited (429) - please try again later"
+            elif 500 <= resp.status_code <= 599:
+                return f"QTest service error (HTTP {resp.status_code})"
+            else:
+                return f"QTest connection failed (HTTP {resp.status_code})"
+
+        except requests.exceptions.Timeout:
+            return "Connection timeout - qTest did not respond within 10 seconds"
+        except requests.exceptions.ConnectionError:
+            return "Connection error - unable to reach qTest. Check base URL and network."
+        except requests.exceptions.SSLError:
+            return "SSL error - certificate verification failed"
+        except requests.exceptions.RequestException as e:
+            return f"Request failed: {str(e)}"
+        except Exception:
+            return "Unexpected error during qTest connection check"
+
+
+