alita-sdk 0.3.376__py3-none-any.whl → 0.3.435__py3-none-any.whl

alita_sdk/configurations/zephyr_essential.py

@@ -18,3 +18,78 @@ class ZephyrEssentialConfiguration(BaseModel):
     )
     base_url: Optional[str] = Field(description="Zephyr Essential API Base URL", default=None)
     token: SecretStr = Field(description="Zephyr Essential API Token")
+
+    @staticmethod
+    def check_connection(settings: dict) -> str | None:
+        """
+        Check the connection to Zephyr Essential (Zephyr Scale).
+        
+        Args:
+            settings: Dictionary containing Zephyr Essential configuration
+                - base_url: Zephyr Essential API Base URL (optional, defaults to Zephyr Scale Cloud API)
+                - token: Zephyr Essential API Token (required)
+        
+        Returns:
+            None if connection successful, error message string if failed
+        """
+        import requests
+        
+        # Get base_url or use default
+        base_url = settings.get("base_url")
+        if base_url:
+            base_url = base_url.strip().rstrip("/")
+            # Validate URL format if provided
+            if not base_url.startswith(("http://", "https://")):
+                return "Zephyr Essential URL must start with http:// or https://"
+        else:
+            # Default to Zephyr Scale Cloud API
+            base_url = "https://api.zephyrscale.smartbear.com/v2"
+        
+        # Validate token
+        token = settings.get("token")
+        if not token:
+            return "Zephyr Essential API token is required"
+        
+        # Extract token value if it's a SecretStr
+        token_value = token.get_secret_value() if hasattr(token, 'get_secret_value') else token
+        
+        if not token_value or not str(token_value).strip():
+            return "Zephyr Essential API token cannot be empty"
+        
+        # Test connection using /projects endpoint (requires authentication)
+        test_url = f"{base_url}/projects"
+        
+        headers = {
+            "Authorization": f"Bearer {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 API token"
+            elif response.status_code == 403:
+                return "Access forbidden: token lacks required permissions"
+            elif response.status_code == 404:
+                return "Zephyr Essential API endpoint not found: verify the API URL"
+            else:
+                return f"Zephyr Essential 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 Zephyr Essential at {base_url}: connection refused"
+        except requests.exceptions.Timeout:
+            return f"Connection to Zephyr Essential at {base_url} timed out"
+        except requests.exceptions.RequestException as e:
+            return f"Error connecting to Zephyr Essential: {str(e)}"
+        except Exception as e:
+            return f"Unexpected error: {str(e)}"

alita_sdk/runtime/clients/client.py

@@ -568,19 +568,22 @@ class AlitaClient:
     def predict_agent(self, llm: ChatOpenAI, instructions: str = "You are a helpful assistant.",
                       tools: Optional[list] = None, chat_history: Optional[List[Any]] = None,
                       memory=None, runtime='langchain', variables: Optional[list] = None,
-                      store: Optional[BaseStore] = None):
+                      store: Optional[BaseStore] = None, debug_mode: Optional[bool] = False):
         """
         Create a predict-type agent with minimal configuration.
 
         Args:
             llm: The LLM to use
             instructions: System instructions for the agent
-            tools: Optional list of tools to provide to the agent
+            tools: Optional list of tool configurations (not tool instances) to provide to the agent.
+                   Tool configs will be processed through get_tools() to create tool instances.
+                   Each tool config should have 'type', 'settings', etc.
             chat_history: Optional chat history
             memory: Optional memory/checkpointer
             runtime: Runtime type (default: 'langchain')
             variables: Optional list of variables for the agent
             store: Optional store for memory
+            debug_mode: Enable debug mode for cases when assistant can be initialized without tools
 
         Returns:
             Runnable agent ready for execution
@@ -594,13 +597,15 @@ class AlitaClient:
 
         # Create a minimal data structure for predict agent
         # All LLM settings are taken from the passed client instance
+        # Note: 'tools' here are tool CONFIGURATIONS, not tool instances
+        # They will be converted to tool instances by LangChainAssistant via get_tools()
         agent_data = {
             'instructions': instructions,
-            'tools': tools,  # Tools are handled separately in predict agents
+            'tools': tools,  # Tool configs that will be processed by get_tools()
             'variables': variables
         }
         return LangChainAssistant(self, agent_data, llm,
-                                  chat_history, "predict", memory=memory, store=store).runnable()
+                                  chat_history, "predict", memory=memory, store=store, debug_mode=debug_mode).runnable()
 
     def test_toolkit_tool(self, toolkit_config: dict, tool_name: str, tool_params: dict = None,
                           runtime_config: dict = None, llm_model: str = None,

alita_sdk/runtime/clients/mcp_discovery.py

@@ -0,0 +1,342 @@
+"""
+Dynamic MCP Server Discovery Client.
+Implements the MCP protocol for discovering tools from remote servers.
+"""
+
+import asyncio
+import json
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Any, Set
+from urllib.parse import urlparse
+import aiohttp
+from datetime import datetime, timedelta
+
+from ..models.mcp_models import McpConnectionConfig, McpToolMetadata
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class McpServerInfo:
+    """Information about an MCP server."""
+    name: str
+    url: str
+    headers: Optional[Dict[str, str]] = None
+    last_discovery: Optional[datetime] = None
+    tools: List[McpToolMetadata] = field(default_factory=list)
+    status: str = "unknown"  # unknown, online, offline, error
+    error: Optional[str] = None
+
+
+class McpDiscoveryClient:
+    """
+    Client for dynamically discovering tools from MCP servers.
+    Implements the MCP protocol for tool discovery.
+    """
+
+    def __init__(
+        self,
+        discovery_interval: int = 300,  # 5 minutes
+        request_timeout: int = 30,
+        max_retries: int = 3,
+        cache_ttl: int = 600  # 10 minutes
+    ):
+        self.discovery_interval = discovery_interval
+        self.request_timeout = request_timeout
+        self.max_retries = max_retries
+        self.cache_ttl = cache_ttl
+
+        # Server registry
+        self.servers: Dict[str, McpServerInfo] = {}
+        self.session: Optional[aiohttp.ClientSession] = None
+
+        # Discovery state
+        self._discovery_task: Optional[asyncio.Task] = None
+        self._running = False
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        await self.start()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.stop()
+
+    async def start(self):
+        """Start the discovery client."""
+        if self._running:
+            return
+
+        self.session = aiohttp.ClientSession(
+            timeout=aiohttp.ClientTimeout(total=self.request_timeout)
+        )
+        self._running = True
+
+        # Start background discovery task
+        self._discovery_task = asyncio.create_task(self._discovery_loop())
+        logger.info("MCP Discovery Client started")
+
+    async def stop(self):
+        """Stop the discovery client."""
+        if not self._running:
+            return
+
+        self._running = False
+
+        if self._discovery_task:
+            self._discovery_task.cancel()
+            try:
+                await self._discovery_task
+            except asyncio.CancelledError:
+                pass
+
+        if self.session:
+            await self.session.close()
+
+        logger.info("MCP Discovery Client stopped")
+
+    def add_server(self, server_name: str, connection_config: McpConnectionConfig):
+        """Add an MCP server to discovery."""
+        server_info = McpServerInfo(
+            name=server_name,
+            url=connection_config.url,
+            headers=connection_config.headers
+        )
+        self.servers[server_name] = server_info
+        logger.info(f"Added MCP server for discovery: {server_name} at {connection_config.url}")
+
+    def remove_server(self, server_name: str):
+        """Remove an MCP server from discovery."""
+        if server_name in self.servers:
+            del self.servers[server_name]
+            logger.info(f"Removed MCP server from discovery: {server_name}")
+
+    async def discover_server_tools(self, server_name: str, force: bool = False) -> List[McpToolMetadata]:
+        """Discover tools from a specific MCP server."""
+        if server_name not in self.servers:
+            raise ValueError(f"Server {server_name} not registered for discovery")
+
+        server_info = self.servers[server_name]
+
+        # Check cache unless force refresh
+        if not force and self._is_cache_valid(server_info):
+            logger.debug(f"Using cached tools for server {server_name}")
+            return server_info.tools
+
+        try:
+            tools = await self._fetch_server_tools(server_info)
+            server_info.tools = tools
+            server_info.last_discovery = datetime.now()
+            server_info.status = "online"
+            server_info.error = None
+
+            logger.info(f"Discovered {len(tools)} tools from server {server_name}")
+            return tools
+
+        except Exception as e:
+            error_msg = f"Failed to discover tools from {server_name}: {e}"
+            logger.error(error_msg)
+            server_info.status = "error"
+            server_info.error = str(e)
+            return []
+
+    async def get_all_tools(self) -> Dict[str, List[McpToolMetadata]]:
+        """Get all discovered tools from all servers."""
+        all_tools = {}
+
+        for server_name in self.servers:
+            tools = await self.discover_server_tools(server_name)
+            all_tools[server_name] = tools
+
+        return all_tools
+
+    def get_server_status(self, server_name: str) -> Optional[McpServerInfo]:
+        """Get status information for a server."""
+        return self.servers.get(server_name)
+
+    def get_all_server_status(self) -> Dict[str, McpServerInfo]:
+        """Get status information for all servers."""
+        return self.servers.copy()
+
+    async def _discovery_loop(self):
+        """Background task for periodic tool discovery."""
+        while self._running:
+            try:
+                await self._perform_discovery()
+                await asyncio.sleep(self.discovery_interval)
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"Error in discovery loop: {e}")
+                await asyncio.sleep(60)  # Wait before retrying
+
+    async def _perform_discovery(self):
+        """Perform discovery on all registered servers."""
+        if not self.servers:
+            return
+
+        discovery_tasks = [
+            self.discover_server_tools(server_name)
+            for server_name in self.servers
+        ]
+
+        results = await asyncio.gather(*discovery_tasks, return_exceptions=True)
+
+        # Log any errors
+        for i, result in enumerate(results):
+            if isinstance(result, Exception):
+                server_name = list(self.servers.keys())[i]
+                logger.error(f"Discovery failed for server {server_name}: {result}")
+
+    async def _fetch_server_tools(self, server_info: McpServerInfo) -> List[McpToolMetadata]:
+        """Fetch tools from an MCP server using HTTP requests."""
+        if not self.session:
+            raise RuntimeError("Discovery client not started")
+
+        # MCP protocol: list_tools request
+        mcp_request = {
+            "jsonrpc": "2.0",
+            "id": f"discover_{int(time.time())}",
+            "method": "tools/list",
+            "params": {}
+        }
+
+        headers = {"Content-Type": "application/json"}
+        if server_info.headers:
+            headers.update(server_info.headers)
+
+        async with self.session.post(
+            server_info.url,
+            json=mcp_request,
+            headers=headers
+        ) as response:
+
+            if response.status != 200:
+                raise Exception(f"HTTP {response.status}: {await response.text()}")
+
+            data = await response.json()
+
+            if "error" in data:
+                raise Exception(f"MCP Error: {data['error']}")
+
+            # Parse MCP response
+            tools_data = data.get("result", {}).get("tools", [])
+            tools = []
+
+            for tool_data in tools_data:
+                try:
+                    tool_metadata = McpToolMetadata(
+                        name=tool_data.get("name", ""),
+                        description=tool_data.get("description", ""),
+                        server=server_info.name,
+                        input_schema=tool_data.get("inputSchema", {}),
+                        enabled=True
+                    )
+                    tools.append(tool_metadata)
+                except Exception as e:
+                    logger.warning(f"Failed to parse tool from {server_info.name}: {e}")
+
+            return tools
+
+    def _is_cache_valid(self, server_info: McpServerInfo) -> bool:
+        """Check if cached tools are still valid."""
+        if not server_info.last_discovery:
+            return False
+
+        cache_age = datetime.now() - server_info.last_discovery
+        return cache_age.total_seconds() < self.cache_ttl
+
+
+class McpDiscoveryService:
+    """
+    High-level service for managing MCP server discovery.
+    Integrates with the existing toolkit system.
+    """
+
+    def __init__(self, discovery_client: Optional[McpDiscoveryClient] = None):
+        self.client = discovery_client or McpDiscoveryClient()
+        self._started = False
+
+    async def start(self):
+        """Start the discovery service."""
+        if not self._started:
+            await self.client.start()
+            self._started = True
+
+    async def stop(self):
+        """Stop the discovery service."""
+        if self._started:
+            await self.client.stop()
+            self._started = False
+
+    async def register_server(self, server_name: str, connection_config: McpConnectionConfig):
+        """Register an MCP server for discovery."""
+        self.client.add_server(server_name, connection_config)
+
+        # Perform immediate discovery
+        await self.client.discover_server_tools(server_name, force=True)
+
+    def unregister_server(self, server_name: str):
+        """Unregister an MCP server."""
+        self.client.remove_server(server_name)
+
+    async def get_server_tools(self, server_name: str) -> List[McpToolMetadata]:
+        """Get tools from a specific server."""
+        return await self.client.discover_server_tools(server_name)
+
+    async def get_all_available_tools(self) -> Dict[str, List[McpToolMetadata]]:
+        """Get all available tools from all registered servers."""
+        return await self.client.get_all_tools()
+
+    def get_server_health(self) -> Dict[str, Dict[str, Any]]:
+        """Get health status of all servers."""
+        status_info = {}
+
+        for name, server_info in self.client.get_all_server_status().items():
+            status_info[name] = {
+                "status": server_info.status,
+                "url": server_info.url,
+                "last_discovery": server_info.last_discovery.isoformat() if server_info.last_discovery else None,
+                "tool_count": len(server_info.tools),
+                "error": server_info.error
+            }
+
+        return status_info
+
+    async def refresh_server(self, server_name: str):
+        """Force refresh tools from a specific server."""
+        await self.client.discover_server_tools(server_name, force=True)
+
+    async def refresh_all_servers(self):
+        """Force refresh tools from all servers."""
+        for server_name in self.client.servers:
+            await self.client.discover_server_tools(server_name, force=True)
+
+
+# Global discovery service instance
+_discovery_service: Optional[McpDiscoveryService] = None
+
+
+def get_discovery_service() -> McpDiscoveryService:
+    """Get the global MCP discovery service instance."""
+    global _discovery_service
+    if _discovery_service is None:
+        _discovery_service = McpDiscoveryService()
+    return _discovery_service
+
+
+async def init_discovery_service():
+    """Initialize the global discovery service."""
+    service = get_discovery_service()
+    await service.start()
+
+
+async def shutdown_discovery_service():
+    """Shutdown the global discovery service."""
+    global _discovery_service
+    if _discovery_service:
+        await _discovery_service.stop()
+        _discovery_service = None