alita-sdk 0.3.532__py3-none-any.whl → 0.3.602__py3-none-any.whl

alita_sdk/community/__init__.py

@@ -96,18 +96,22 @@ def get_toolkits():
 def get_tools(tools_list: list, alita_client, llm) -> list:
     """Get community tools based on the tools list configuration."""
     tools = []
-    
+
     # Tool type to class mapping
     _tool_mapping = {
         'analyse_jira': 'AnalyseJira',
         'analyse_ado': 'AnalyseAdo',
-        'analyse_gitlab': 'AnalyseGitLab', 
+        'analyse_gitlab': 'AnalyseGitLab',
         'analyse_github': 'AnalyseGithub',
         'inventory': 'InventoryToolkit'
     }
-    
+
     for tool in tools_list:
-        tool_type = tool.get('type')
+        if isinstance(tool, dict):
+            tool_type = tool.get('type')
+        else:
+            logger.error(f"Community tools received non-dict tool: {tool} (type: {type(tool)})")
+            continue
         class_name = _tool_mapping.get(tool_type)
         
         if class_name and class_name in globals():

alita_sdk/configurations/__init__.py

@@ -53,6 +53,7 @@ _safe_import_configuration('sharepoint', 'sharepoint', 'SharepointConfiguration'
 _safe_import_configuration('carrier', 'carrier', 'CarrierConfiguration')
 _safe_import_configuration('report_portal', 'report_portal', 'ReportPortalConfiguration')
 _safe_import_configuration('testio', 'testio', 'TestIOConfiguration')
+_safe_import_configuration('openapi', 'openapi', 'OpenApiConfiguration')
 
 # Log import summary
 available_count = len(AVAILABLE_CONFIGURATIONS)

alita_sdk/configurations/openapi.py

@@ -0,0 +1,323 @@
+from typing import Any, Literal, Optional
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, model_validator
+
+import base64
+import requests
+
+
+class OpenApiConfiguration(BaseModel):
+    """
+    OpenAPI configuration for authentication.
+    
+    Supports three authentication modes:
+    - Anonymous: No authentication (all fields empty)
+    - API Key: Static key sent via header (Bearer, Basic, or Custom)
+    - OAuth2 Client Credentials: Machine-to-machine authentication flow
+    
+    Note: Only OAuth2 Client Credentials flow is supported. Authorization Code flow
+    is not supported as it requires user interaction and pre-registered redirect URLs.
+    """
+    
+    model_config = ConfigDict(
+        extra='allow',
+        json_schema_extra={
+            "metadata": {
+                "label": "OpenAPI",
+                "icon_url": "openapi.svg",
+                "categories": ["integrations"],
+                "type": "openapi",
+                "extra_categories": ["api", "openapi", "swagger"],
+                "sections": {
+                    "auth": {
+                        "required": False,
+                        "subsections": [
+                            {
+                                "name": "API Key",
+                                "fields": ["api_key", "auth_type", "custom_header_name"],
+                            },
+                            {
+                                "name": "OAuth",
+                                "fields": [
+                                    "client_id",
+                                    "client_secret",
+                                    "token_url",
+                                    "scope",
+                                    "method",
+                                ],
+                            },
+                        ],
+                    },
+                },
+                "section": "credentials",
+            }
+        }
+    )
+
+    # =========================================================================
+    # API Key Authentication Fields
+    # =========================================================================
+    
+    api_key: Optional[SecretStr] = Field(
+        default=None,
+        description=(
+            "API key value (stored as a secret). Used when selecting 'API Key' authentication subsection."
+        ),
+    )
+    auth_type: Optional[Literal['Basic', 'Bearer', 'Custom']] = Field(
+        default='Bearer',
+        description=(
+            "How to apply the API key. "
+            "- 'Bearer': sets 'Authorization: Bearer <api_key>' "
+            "- 'Basic': sets 'Authorization: Basic <api_key>' "
+            "- 'custom': sets '<custom_header_name>: <api_key>'"
+        ),
+    )
+    custom_header_name: Optional[str] = Field(
+        default=None,
+        description="Custom header name to use when auth_type='custom' (e.g. 'X-Api-Key').",
+        json_schema_extra={'visible_when': {'field': 'auth_type', 'value': 'custom'}},
+    )
+
+    # =========================================================================
+    # OAuth2 Client Credentials Flow Fields
+    # =========================================================================
+    
+    client_id: Optional[str] = Field(
+        default=None, 
+        description='OAuth2 client ID (also known as Application ID or App ID)'
+    )
+    client_secret: Optional[SecretStr] = Field(
+        default=None, 
+        description='OAuth2 client secret (stored securely)'
+    )
+    token_url: Optional[str] = Field(
+        default=None, 
+        description=(
+            'OAuth2 token endpoint URL for obtaining access tokens. '
+            'Examples: '
+            'Azure AD: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token, '
+            'Google: https://oauth2.googleapis.com/token, '
+            'Auth0: https://{domain}/oauth/token, '
+            'Spotify: https://accounts.spotify.com/api/token'
+        )
+    )
+    scope: Optional[str] = Field(
+        default=None, 
+        description=(
+            'OAuth2 scope(s), space-separated if multiple (per OAuth2 RFC 6749). '
+            'Examples: "user-read-private user-read-email" (Spotify), '
+            '"api://app-id/.default" (Azure), '
+            '"https://www.googleapis.com/auth/cloud-platform" (Google)'
+        )
+    )
+    method: Optional[Literal['default', 'Basic']] = Field(
+        default='default',
+        description=(
+            "Token exchange method for client credentials flow. "
+            "'default': Sends client_id and client_secret in POST body (Azure AD, Auth0, most providers). "
+            "'Basic': Sends credentials via HTTP Basic auth header - required by Spotify, some AWS services, and certain OAuth providers."
+        ),
+    )
+
+    @model_validator(mode='before')
+    @classmethod
+    def _validate_auth_consistency(cls, values):
+        if not isinstance(values, dict):
+            return values
+
+        # OAuth: if any OAuth field is provided, require the essential ones
+        has_any_oauth = any(
+            (values.get('client_id'), values.get('client_secret'), values.get('token_url'))
+        )
+        if has_any_oauth:
+            missing = []
+            if not values.get('client_id'):
+                missing.append('client_id')
+            if not values.get('client_secret'):
+                missing.append('client_secret')
+            if not values.get('token_url'):
+                missing.append('token_url')
+            if missing:
+                raise ValueError(f"OAuth is misconfigured; missing: {', '.join(missing)}")
+
+        # API key: if auth_type is custom, custom_header_name must be present
+        auth_type = values.get('auth_type')
+        if isinstance(auth_type, str) and auth_type.strip().lower() == 'custom' and values.get('api_key'):
+            if not values.get('custom_header_name'):
+                raise ValueError("custom_header_name is required when auth_type='custom'")
+
+        return values
+
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """
+        Validate the OpenAPI configuration by testing connectivity where possible.
+        
+        Validation behavior by authentication type:
+        
+        1. ANONYMOUS (no auth fields configured):
+           - Cannot validate without making actual API calls
+           - Returns None (success) - validation skipped
+           
+        2. API KEY (api_key field configured):
+           - Cannot validate without knowing which endpoint to call
+           - The OpenAPI spec is not available at configuration time
+           - Returns None (success) - validation skipped
+           
+        3. OAUTH2 CLIENT CREDENTIALS (client_id, client_secret, token_url configured):
+           - CAN validate by attempting token exchange with the OAuth provider
+           - Makes a real HTTP request to token_url
+           - Returns None on success, error message on failure
+        
+        Args:
+            settings: Dictionary containing OpenAPI configuration fields
+        
+        Returns:
+            None: Configuration is valid (or cannot be validated for this auth type)
+            str: Error message describing the validation failure
+        """
+        
+        # =====================================================================
+        # Determine authentication type from configured fields
+        # =====================================================================
+        
+        client_id = settings.get('client_id')
+        client_secret = settings.get('client_secret')
+        token_url = settings.get('token_url')
+        
+        has_oauth_fields = client_id or client_secret or token_url
+        
+        # =====================================================================
+        # ANONYMOUS or API KEY: Cannot validate, return success
+        # =====================================================================
+        
+        if not has_oauth_fields:
+            # No OAuth fields configured - this is either:
+            # - Anonymous authentication (no auth at all)
+            # - API Key authentication (api_key field may be set)
+            # 
+            # Neither can be validated without making actual API calls to the
+            # target service, and we don't have the OpenAPI spec available here.
+            return None
+        
+        # =====================================================================
+        # OAUTH2: Validate by attempting token exchange
+        # =====================================================================
+        
+        # Check for required OAuth fields
+        if not client_id:
+            return "OAuth client_id is required when using OAuth authentication"
+        if not client_secret:
+            return "OAuth client_secret is required when using OAuth authentication"
+        if not token_url:
+            return "OAuth token_url is required when using OAuth authentication"
+        
+        # Extract secret value if it's a SecretStr
+        if hasattr(client_secret, 'get_secret_value'):
+            client_secret = client_secret.get_secret_value()
+        
+        if not client_secret or not str(client_secret).strip():
+            return "OAuth client_secret cannot be empty"
+        
+        # Validate token_url format
+        token_url = token_url.strip()
+        if not token_url.startswith(('http://', 'https://')):
+            return "OAuth token_url must start with http:// or https://"
+        
+        # Get optional OAuth settings
+        scope = settings.get('scope')
+        method = settings.get('method', 'default') or 'default'
+        
+        # ---------------------------------------------------------------------
+        # Attempt OAuth2 Client Credentials token exchange
+        # ---------------------------------------------------------------------
+        
+        try:
+            headers = {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                'Accept': 'application/json',
+            }
+            
+            data = {
+                'grant_type': 'client_credentials',
+            }
+            
+            # Apply credentials based on method
+            if method == 'Basic':
+                # Basic method: credentials in Authorization header (Spotify, some AWS)
+                credentials = f"{client_id}:{client_secret}"
+                encoded = base64.b64encode(credentials.encode('utf-8')).decode('utf-8')
+                headers['Authorization'] = f'Basic {encoded}'
+            else:
+                # Default method: credentials in POST body (Azure AD, Auth0, most providers)
+                data['client_id'] = client_id
+                data['client_secret'] = str(client_secret)
+            
+            if scope:
+                data['scope'] = scope
+            
+            response = requests.post(
+                token_url,
+                headers=headers,
+                data=data,
+                timeout=30,
+            )
+            
+            # ---------------------------------------------------------------------
+            # Handle response
+            # ---------------------------------------------------------------------
+            
+            if response.status_code == 200:
+                try:
+                    token_data = response.json()
+                    if 'access_token' in token_data:
+                        return None  # Success - token obtained
+                    return "OAuth response did not contain 'access_token'"
+                except Exception:
+                    return "Failed to parse OAuth token response"
+            
+            # Handle common error status codes with helpful messages
+            if response.status_code == 400:
+                try:
+                    error_data = response.json()
+                    error = error_data.get('error', 'bad_request')
+                    error_desc = error_data.get('error_description', '')
+                    if error_desc:
+                        return f"OAuth error: {error} - {error_desc}"
+                    return f"OAuth error: {error}"
+                except Exception:
+                    return "OAuth request failed: bad request (400)"
+            
+            if response.status_code == 401:
+                return "OAuth authentication failed: invalid client_id or client_secret"
+            
+            if response.status_code == 403:
+                return "OAuth access forbidden: client may lack required permissions"
+            
+            if response.status_code == 404:
+                return f"OAuth token endpoint not found: {token_url}"
+            
+            return f"OAuth token request failed with status {response.status_code}"
+            
+        except requests.exceptions.SSLError as e:
+            error_str = str(e).lower()
+            if 'hostname mismatch' in error_str:
+                return "OAuth token_url hostname does not match SSL certificate - verify the URL is correct"
+            if 'certificate verify failed' in error_str:
+                return "SSL certificate verification failed for OAuth endpoint - the server may have an invalid or self-signed certificate"
+            if 'certificate has expired' in error_str:
+                return "SSL certificate has expired for OAuth endpoint"
+            return "SSL error connecting to OAuth endpoint - verify the token_url is correct"
+        except requests.exceptions.ConnectionError as e:
+            error_str = str(e).lower()
+            if 'name or service not known' in error_str or 'nodename nor servname provided' in error_str:
+                return "OAuth token_url hostname could not be resolved - verify the URL is correct"
+            if 'connection refused' in error_str:
+                return "Connection refused by OAuth endpoint - verify the token_url and port are correct"
+            return "Cannot connect to OAuth token endpoint - verify the token_url is correct"
+        except requests.exceptions.Timeout:
+            return "OAuth token request timed out - the endpoint may be unreachable"
+        except requests.exceptions.RequestException:
+            return "OAuth request failed - verify the token_url is correct and accessible"
+        except Exception:
+            return "Unexpected error during OAuth configuration validation"

alita_sdk/runtime/clients/client.py

@@ -259,21 +259,22 @@ class AlitaClient:
                     use_responses_api = True
                     break
 
-        # handle case when max_tokens are auto-configurable == -1
+        # handle case when max_tokens are auto-configurable == -1 or None
         llm_max_tokens = model_config.get("max_tokens", None)
-        if llm_max_tokens and llm_max_tokens == -1:
-            logger.warning(f'User selected `MAX COMPLETION TOKENS` as `auto`')
-            # default nuber for a case when auto is selected for an agent
+        if llm_max_tokens is None or llm_max_tokens == -1:
+            logger.warning(f'User selected `MAX COMPLETION TOKENS` as `auto` or value is None/missing')
+            # default number for a case when auto is selected for an agent
             llm_max_tokens = 4000
 
         if is_anthropic:
             # ChatAnthropic configuration
+            # Anthropic requires max_tokens to be an integer, never None
             target_kwargs = {
                 "base_url": f"{self.base_url}{self.allm_path}",
                 "model": model_name,
                 "api_key": self.auth_token,
                 "streaming": model_config.get("streaming", True),
-                "max_tokens": llm_max_tokens,
+                "max_tokens": llm_max_tokens,  # Always an integer now
                 "temperature": model_config.get("temperature"),
                 "max_retries": model_config.get("max_retries", 3),
                 "default_headers": {"openai-organization": str(self.project_id),
@@ -716,7 +717,7 @@ class AlitaClient:
                       memory=None, runtime='langchain', variables: Optional[list] = None,
                       store: Optional[BaseStore] = None, debug_mode: Optional[bool] = False,
                       mcp_tokens: Optional[dict] = None, conversation_id: Optional[str] = None,
-                      ignored_mcp_servers: Optional[list] = None):
+                      ignored_mcp_servers: Optional[list] = None, persona: Optional[str] = "generic"):
         """
         Create a predict-type agent with minimal configuration.
 
@@ -733,6 +734,7 @@ class AlitaClient:
             store: Optional store for memory
             debug_mode: Enable debug mode for cases when assistant can be initialized without tools
             ignored_mcp_servers: Optional list of MCP server URLs to ignore (user chose to continue without auth)
+            persona: Default persona for chat: 'generic' or 'qa' (default: 'generic')
 
         Returns:
             Runnable agent ready for execution
@@ -767,7 +769,8 @@ class AlitaClient:
             debug_mode=debug_mode,
             mcp_tokens=mcp_tokens,
             conversation_id=conversation_id,
-            ignored_mcp_servers=ignored_mcp_servers
+            ignored_mcp_servers=ignored_mcp_servers,
+            persona=persona
         ).runnable()
 
     def test_toolkit_tool(self, toolkit_config: dict, tool_name: str, tool_params: dict = None,
@@ -1153,3 +1156,158 @@ class AlitaClient:
                 "events_dispatched": [],
                 "execution_time_seconds": 0.0
             }
+
+    def test_mcp_connection(self, toolkit_config: dict, mcp_tokens: dict = None) -> dict:
+        """
+        Test MCP server connection using protocol-level list_tools.
+
+        This method verifies MCP server connectivity and authentication by calling
+        the protocol-level tools/list JSON-RPC method (NOT executing a tool).
+        This is ideal for auth checks as it validates the connection without
+        requiring any tool execution.
+
+        Args:
+            toolkit_config: Configuration dictionary for the MCP toolkit containing:
+                - toolkit_name: Name of the toolkit
+                - settings: Dictionary with 'url', optional 'headers', 'session_id'
+            mcp_tokens: Optional dictionary of MCP OAuth tokens by server URL
+                Format: {canonical_url: {access_token: str, session_id: str}}
+
+        Returns:
+            Dictionary containing:
+                - success: Boolean indicating if the connection was successful
+                - tools: List of tool names available on the MCP server (if successful)
+                - tools_count: Number of tools discovered
+                - server_session_id: Session ID provided by the server (if any)
+                - error: Error message (if unsuccessful)
+                - toolkit_config: Original toolkit configuration
+
+        Raises:
+            McpAuthorizationRequired: If MCP server requires OAuth authorization
+
+        Example:
+            >>> config = {
+            ...     'toolkit_name': 'my-mcp-server',
+            ...     'type': 'mcp',
+            ...     'settings': {
+            ...         'url': 'https://mcp-server.example.com/mcp',
+            ...         'headers': {'X-Custom': 'value'}
+            ...     }
+            ... }
+            >>> result = client.test_mcp_connection(config)
+            >>> if result['success']:
+            ...     print(f"Connected! Found {result['tools_count']} tools")
+        """
+        import asyncio
+        import time
+        from ..utils.mcp_client import McpClient
+        from ..utils.mcp_oauth import canonical_resource
+
+        toolkit_name = toolkit_config.get('toolkit_name', 'unknown')
+        settings = toolkit_config.get('settings', {})
+
+        # Extract connection parameters
+        url = settings.get('url')
+        if not url:
+            return {
+                "success": False,
+                "error": "MCP toolkit configuration missing 'url' in settings",
+                "toolkit_config": toolkit_config,
+                "tools": [],
+                "tools_count": 0
+            }
+
+        headers = settings.get('headers') or {}
+        session_id = settings.get('session_id')
+
+        # Apply OAuth token if available
+        if mcp_tokens and url:
+            canonical_url = canonical_resource(url)
+            token_data = mcp_tokens.get(canonical_url)
+            if token_data:
+                if isinstance(token_data, dict):
+                    access_token = token_data.get('access_token')
+                    if not session_id:
+                        session_id = token_data.get('session_id')
+                else:
+                    # Backward compatibility: plain token string
+                    access_token = token_data
+
+                if access_token:
+                    headers = dict(headers)  # Copy to avoid mutating original
+                    headers.setdefault('Authorization', f'Bearer {access_token}')
+                    logger.info(f"[MCP Auth Check] Applied OAuth token for {canonical_url}")
+
+        logger.info(f"Testing MCP connection to '{toolkit_name}' at {url}")
+
+        start_time = time.time()
+
+        async def _test_connection():
+            client = McpClient(
+                url=url,
+                session_id=session_id,
+                headers=headers,
+                timeout=60  # Reasonable timeout for connection test
+            )
+
+            async with client:
+                # Initialize MCP protocol session
+                await client.initialize()
+                logger.info(f"[MCP Auth Check] Session initialized (transport={client.detected_transport})")
+
+                # Call protocol-level list_tools (tools/list JSON-RPC method)
+                tools = await client.list_tools()
+
+                return {
+                    "tools": tools,
+                    "server_session_id": client.server_session_id,
+                    "transport": client.detected_transport
+                }
+
+        try:
+            # Run async operation
+            try:
+                loop = asyncio.get_event_loop()
+                if loop.is_running():
+                    # If we're already in an async context, create a new task
+                    import concurrent.futures
+                    with concurrent.futures.ThreadPoolExecutor() as executor:
+                        future = executor.submit(asyncio.run, _test_connection())
+                        result = future.result(timeout=120)
+                else:
+                    result = loop.run_until_complete(_test_connection())
+            except RuntimeError:
+                # No event loop, create one
+                result = asyncio.run(_test_connection())
+
+            execution_time = time.time() - start_time
+
+            # Extract tool names for the response
+            tool_names = [tool.get('name', 'unknown') for tool in result.get('tools', [])]
+
+            logger.info(f"[MCP Auth Check] Connection successful to '{toolkit_name}': {len(tool_names)} tools in {execution_time:.3f}s")
+
+            return {
+                "success": True,
+                "tools": tool_names,
+                "tools_count": len(tool_names),
+                "server_session_id": result.get('server_session_id'),
+                "transport": result.get('transport'),
+                "toolkit_config": toolkit_config,
+                "execution_time_seconds": execution_time
+            }
+
+        except McpAuthorizationRequired:
+            # Re-raise to allow proper handling upstream
+            raise
+        except Exception as e:
+            execution_time = time.time() - start_time
+            logger.error(f"[MCP Auth Check] Connection failed to '{toolkit_name}': {str(e)}")
+            return {
+                "success": False,
+                "error": f"MCP connection failed: {str(e)}",
+                "toolkit_config": toolkit_config,
+                "tools": [],
+                "tools_count": 0,
+                "execution_time_seconds": execution_time
+            }