Upload 60 files

Initial upload of project

.gitattributes

@@ -0,0 +1,36 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,26 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.cadence
+.env
+.idea
+.mypy_cache/
+archive/
+cache
+logs
+
+# Test-generated files
+test_cache/
+.coverage
+htmlcov/
+.pytest_cache/
+.ruff_cache
+assets
+static

.python-version

@@ -0,0 +1 @@
+3.12

README.md

@@ -0,0 +1,180 @@
+---
+title: ShallowCodeResearch
+emoji: 📉
+colorFrom: blue
+colorTo: pink
+sdk: gradio
+sdk_version: 5.33.0
+app_file: app.py
+pinned: false
+short_description: Coding research assistant that generates code and tests it
+tags:
+  - mcp
+  - multi-agent
+  - research
+  - code-generation
+  - ai-assistant
+  - gradio
+  - python
+  - web-search
+  - llm
+  - modal
+python_version: "3.12"
+---
+---
+
+# MCP Hub - Multi-Agent AI Research & Code Assistant
+
+🚀 **Advanced multi-agent system for AI-powered research and code generation**
+
+## What is MCP Hub?
+
+MCP Hub is a sophisticated multi-agent research and code assistant built using Gradio's Model Context Protocol (MCP) server functionality. It orchestrates specialized AI agents to provide comprehensive research capabilities and generate executable Python code.
+
+## ✨ Key Features
+
+- 🧠 **Multi-Agent Architecture**: Specialized agents working in orchestrated workflows
+- 🔍 **Intelligent Research**: Web search with automatic summarization and citation formatting
+- 💻 **Code Generation**: Context-aware Python code creation with secure execution
+- 🔗 **MCP Server**: Built-in MCP server for seamless agent communication
+- 🎯 **Multiple LLM Support**: Compatible with Nebius, OpenAI, Anthropic, and HuggingFace
+- 🛡️ **Secure Execution**: Modal sandbox environment for safe code execution
+- 📊 **Performance Monitoring**: Advanced metrics collection and health monitoring
+
+## 🚀 Quick Start
+
+1. **Configure your environment** by setting up API keys in the Settings tab
+2. **Choose your LLM provider** (Nebius recommended for best performance)
+3. **Input your research query** in the Orchestrator Flow tab
+4. **Watch the magic happen** as agents collaborate to research and generate code
+
+## 🏗️ Architecture
+
+### Core Agents
+
+- **Question Enhancer**: Breaks down complex queries into focused sub-questions
+- **Web Search Agent**: Performs targeted searches using Tavily API
+- **LLM Processor**: Handles text processing, summarization, and analysis
+- **Citation Formatter**: Manages academic citation formatting (APA style)
+- **Code Generator**: Creates contextually-aware Python code
+- **Code Runner**: Executes code in secure Modal sandboxes
+- **Orchestrator**: Coordinates the complete workflow
+
+### Workflow Example
+
+```
+User Query: "Create Python code to analyze Twitter sentiment"
+    ↓
+Question Enhancement: Split into focused sub-questions
+    ↓
+Web Research: Search for Twitter APIs, sentiment libraries, examples
+    ↓
+Context Integration: Combine research into comprehensive context
+    ↓
+Code Generation: Create executable Python script
+    ↓
+Secure Execution: Run code in Modal sandbox
+    ↓
+Results: Code + output + research summary + citations
+```
+
+## 🛠️ Setup Requirements
+
+### Required API Keys
+
+- **LLM Provider** (choose one):
+  - Nebius API (recommended)
+  - OpenAI API
+  - Anthropic API
+  - HuggingFace Inference API
+- **Tavily API** (for web search)
+- **Modal Account** (for code execution)
+
+### Environment Configuration
+
+Set these environment variables or configure in the app:
+
+```bash
+LLM_PROVIDER=nebius  # Your chosen provider
+NEBIUS_API_KEY=your_key_here
+TAVILY_API_KEY=your_key_here
+# Modal setup handled automatically
+```
+
+## 🎯 Use Cases
+
+### Research & Development
+- **Academic Research**: Automated literature review and citation management
+- **Technical Documentation**: Generate comprehensive guides with current information
+- **Market Analysis**: Research trends and generate analytical reports
+
+### Code Generation
+- **Prototype Development**: Rapidly create functional code based on requirements
+- **API Integration**: Generate code for working with various APIs and services
+- **Data Analysis**: Create scripts for data processing and visualization
+
+### Learning & Education
+- **Code Examples**: Generate educational code samples with explanations
+- **Concept Exploration**: Research and understand complex programming concepts
+- **Best Practices**: Learn current industry standards and methodologies
+
+## 🔧 Advanced Features
+
+### Performance Monitoring
+- Real-time metrics collection
+- Response time tracking
+- Success rate monitoring
+- Resource usage analytics
+
+### Intelligent Caching
+- Reduces redundant API calls
+- Improves response times
+- Configurable TTL settings
+
+### Fault Tolerance
+- Circuit breaker protection
+- Rate limiting management
+- Graceful error handling
+- Automatic retry mechanisms
+
+### Sandbox Pool Management
+- Pre-warmed execution environments
+- Optimized performance
+- Resource pooling
+- Automatic scaling
+
+## 📱 Interface Tabs
+
+1. **Orchestrator Flow**: Complete end-to-end workflow
+2. **Individual Agents**: Access each agent separately for specific tasks
+3. **Advanced Features**: System monitoring and performance analytics
+
+## 🤝 MCP Integration
+
+This application demonstrates advanced MCP (Model Context Protocol) implementation:
+
+- **Server Architecture**: Full MCP server with schema generation
+- **Function Registry**: Proper MCP function definitions with typing
+- **Multi-Agent Communication**: Structured data flow between agents
+- **Error Handling**: Robust error management across agent interactions
+
+## 📊 Performance
+
+- **Response Times**: Optimized for sub-second agent responses
+- **Scalability**: Handles concurrent requests efficiently
+- **Reliability**: Built-in fault tolerance and monitoring
+- **Resource Management**: Intelligent caching and pooling
+
+## 🔍 Technical Details
+
+- **Python**: 3.12+ required
+- **Framework**: Gradio with MCP server capabilities
+- **Execution**: Modal for secure sandboxed code execution
+- **Search**: Tavily API for real-time web research
+- **Monitoring**: Comprehensive performance and health tracking
+
+---
+
+**Ready to experience the future of AI-assisted research and development?** 
+
+Start by configuring your API keys and dive into the world of multi-agent AI collaboration! 🚀

mcp_api_call.py

@@ -0,0 +1,39 @@
+from gradio_client import Client
+
+def print_human_readable_result(result):
+    # Print main request and status
+    if isinstance(result, tuple):
+        result = next((item for item in result if isinstance(item, dict)), result[0])
+    print("Status:", result.get('status', 'N/A'))
+    print("Status:", result.get('status', 'N/A'))
+    print("User Request:", result.get('user_request', 'N/A'))
+    print("\nSub-Questions:")
+    for i, sub_q in enumerate(result.get('sub_questions', []), 1):
+        print(f"  {i}. {sub_q}")
+
+    print("\nSearch Summaries:")
+    for i, summary in enumerate(result.get('search_summaries', []), 1):
+        print(f"  {i}. {summary}")
+
+    print("\nSearch Results:")
+    for i, res in enumerate(result.get('search_results', []), 1):
+        print(f"  {i}. {res['title']}\n     URL: {res['url']}\n     Content: {res['content'][:100]}{'...' if len(res['content']) > 100 else ''}\n     Score: {res['score']:.3f}")
+
+    print("\nGenerated Code:\n" + result.get('code_string', 'N/A'))
+
+    print("\nExecution Output:\n" + result.get('execution_output', 'N/A'))
+
+    print("\nCitations:")
+    for i, cit in enumerate(result.get('citations', []), 1):
+        print(f"  {i}. {cit}")
+
+    print("\nFinal Summary:\n" + result.get('final_summary', 'N/A'))
+
+    print("\nOrchestration Message:", result.get('message', 'N/A'))
+
+client = Client("http://127.0.0.1:7860/")
+result = client.predict(
+		user_request="How do I calculate the sum of an array in Python?",
+		api_name="/process_orchestrator_request"
+)
+print_human_readable_result(result)

mcp_hub/__init__.py

@@ -0,0 +1,20 @@
+"""MCP Hub - Multi-Agent Communication Protocol Hub for Research and Code Generation."""
+
+__version__ = "1.0.0"
+__author__ = "Your Name"
+__description__ = "Advanced MCP Hub with intelligent agent orchestration"
+
+# Core imports that should be available at package level
+try:
+    from .config import api_config, model_config, app_config
+    from .exceptions import APIError, ValidationError, CodeGenerationError, CodeExecutionError
+    from .logging_config import logger
+    
+    __all__ = [
+        "api_config", "model_config", "app_config",
+        "APIError", "ValidationError", "CodeGenerationError", "CodeExecutionError",
+        "logger"
+    ]
+except ImportError:
+    # Graceful degradation for missing dependencies
+    __all__ = []

mcp_hub/advanced_config.py

@@ -0,0 +1,272 @@
+"""Advanced configuration management with validation and environment-specific settings."""
+
+import os
+import json
+from pathlib import Path
+from typing import Dict, Any, Optional
+from dataclasses import dataclass, field
+from .logging_config import logger
+
+@dataclass
+class APIConfig:
+    """API configuration with validation."""
+    nebius_api_key: str = ""
+    nebius_base_url: str = "https://api.studio.nebius.ai/v1/"
+    tavily_api_key: str = ""
+    
+    # API-specific settings
+    nebius_model: str = "meta-llama/Meta-Llama-3.1-8B-Instruct"
+    nebius_max_tokens: int = 1000
+    nebius_temperature: float = 0.7
+    
+    tavily_search_depth: str = "basic"
+    tavily_max_results: int = 5
+    
+    def __post_init__(self):
+        """Validate configuration after initialization."""
+        if not self.nebius_api_key:
+            raise ValueError("NEBIUS_API_KEY is required")
+        if not self.tavily_api_key:
+            raise ValueError("TAVILY_API_KEY is required")
+        
+        # Validate numeric ranges
+        if not 0.0 <= self.nebius_temperature <= 2.0:
+            raise ValueError("nebius_temperature must be between 0.0 and 2.0")
+        if self.nebius_max_tokens <= 0:
+            raise ValueError("nebius_max_tokens must be positive")
+        if self.tavily_max_results <= 0:
+            raise ValueError("tavily_max_results must be positive")
+
+@dataclass
+class AppConfig:
+    """Application configuration."""
+    environment: str = "development"  # development, staging, production
+    debug: bool = True
+    log_level: str = "INFO"
+    
+    # Gradio settings
+    gradio_server_name: str = "0.0.0.0"
+    gradio_server_port: int = 7860
+    gradio_share: bool = False
+    gradio_auth: Optional[tuple] = None
+    
+    # Performance settings
+    max_search_results: int = 10
+    max_sub_questions: int = 5
+    cache_ttl_seconds: int = 3600
+    request_timeout_seconds: int = 30
+    
+    # Rate limiting
+    api_calls_per_second: float = 2.0
+    api_burst_size: int = 5
+    
+    # Circuit breaker settings
+    circuit_breaker_failure_threshold: int = 5
+    circuit_breaker_timeout_seconds: int = 60
+    
+    # Monitoring settings
+    metrics_retention_hours: int = 24
+    health_check_interval_seconds: int = 300  # 5 minutes
+    
+    def __post_init__(self):
+        """Validate application configuration."""
+        valid_environments = ["development", "staging", "production"]
+        if self.environment not in valid_environments:
+            raise ValueError(f"environment must be one of: {valid_environments}")
+        
+        valid_log_levels = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+        if self.log_level not in valid_log_levels:
+            raise ValueError(f"log_level must be one of: {valid_log_levels}")
+        
+        if self.gradio_server_port <= 0 or self.gradio_server_port > 65535:
+            raise ValueError("gradio_server_port must be between 1 and 65535")
+
+@dataclass
+class SecurityConfig:
+    """Security configuration."""
+    enable_authentication: bool = False
+    allowed_origins: list = field(default_factory=lambda: ["*"])
+    api_key_header: str = "X-API-Key"
+    rate_limit_per_ip: int = 100  # requests per hour
+    max_request_size_mb: int = 10
+    
+    # Content filtering
+    enable_content_filtering: bool = True
+    blocked_patterns: list = field(default_factory=list)
+    
+    def __post_init__(self):
+        """Validate security configuration."""
+        if self.rate_limit_per_ip <= 0:
+            raise ValueError("rate_limit_per_ip must be positive")
+        if self.max_request_size_mb <= 0:
+            raise ValueError("max_request_size_mb must be positive")
+
+class ConfigManager:
+    """Centralized configuration management with environment-specific overrides."""
+    
+    def __init__(self, config_dir: str = "config"):
+        """
+        Initialize configuration manager.
+        
+        Args:
+            config_dir: Directory containing configuration files
+        """
+        self.config_dir = Path(config_dir)
+        self.config_dir.mkdir(exist_ok=True)
+        
+        # Load environment variables
+        self._load_environment_variables()
+        
+        # Initialize configurations
+        self.api_config = self._load_api_config()
+        self.app_config = self._load_app_config()
+        self.security_config = self._load_security_config()
+        
+        logger.info(f"Configuration loaded for environment: {self.app_config.environment}")
+    
+    def _load_environment_variables(self):
+        """Load environment variables from .env file if it exists."""
+        env_file = Path(".env")
+        if env_file.exists():
+            from dotenv import load_dotenv
+            load_dotenv()
+            logger.info("Loaded environment variables from .env file")
+    
+    def _load_api_config(self) -> APIConfig:
+        """Load API configuration from environment and config files."""
+        # Start with environment variables
+        config_data = {
+            "nebius_api_key": os.getenv("NEBIUS_API_KEY", ""),
+            "nebius_base_url": os.getenv("NEBIUS_BASE_URL", "https://api.studio.nebius.ai/v1/"),
+            "tavily_api_key": os.getenv("TAVILY_API_KEY", ""),
+            "nebius_model": os.getenv("NEBIUS_MODEL", "meta-llama/Meta-Llama-3.1-8B-Instruct"),
+            "nebius_max_tokens": int(os.getenv("NEBIUS_MAX_TOKENS", "1000")),
+            "nebius_temperature": float(os.getenv("NEBIUS_TEMPERATURE", "0.7")),
+            "tavily_search_depth": os.getenv("TAVILY_SEARCH_DEPTH", "basic"),
+            "tavily_max_results": int(os.getenv("TAVILY_MAX_RESULTS", "5"))
+        }
+        
+        # Override with config file if it exists
+        config_file = self.config_dir / "api_config.json"
+        if config_file.exists():
+            try:
+                with open(config_file, 'r') as f:
+                    file_config = json.load(f)
+                config_data.update(file_config)
+                logger.info("Loaded API configuration from config file")
+            except Exception as e:
+                logger.warning(f"Failed to load API config file: {e}")
+        
+        return APIConfig(**config_data)
+    
+    def _load_app_config(self) -> AppConfig:
+        """Load application configuration."""
+        environment = os.getenv("ENVIRONMENT", "development")
+        
+        # Base configuration
+        config_data = {
+            "environment": environment,
+            "debug": environment == "development",
+            "log_level": os.getenv("LOG_LEVEL", "INFO"),
+            "gradio_server_name": os.getenv("GRADIO_SERVER_NAME", "0.0.0.0"),
+            "gradio_server_port": int(os.getenv("GRADIO_SERVER_PORT", "7860")),
+            "gradio_share": os.getenv("GRADIO_SHARE", "false").lower() == "true",
+            "max_search_results": int(os.getenv("MAX_SEARCH_RESULTS", "10")),
+            "max_sub_questions": int(os.getenv("MAX_SUB_QUESTIONS", "5")),
+            "cache_ttl_seconds": int(os.getenv("CACHE_TTL_SECONDS", "3600")),
+            "request_timeout_seconds": int(os.getenv("REQUEST_TIMEOUT_SECONDS", "30"))
+        }
+        
+        # Environment-specific overrides
+        env_config_file = self.config_dir / f"app_config_{environment}.json"
+        if env_config_file.exists():
+            try:
+                with open(env_config_file, 'r') as f:
+                    env_config = json.load(f)
+                config_data.update(env_config)
+                logger.info(f"Loaded environment-specific config: {environment}")
+            except Exception as e:
+                logger.warning(f"Failed to load environment config: {e}")
+        
+        return AppConfig(**config_data)
+    
+    def _load_security_config(self) -> SecurityConfig:
+        """Load security configuration."""
+        config_data = {
+            "enable_authentication": os.getenv("ENABLE_AUTH", "false").lower() == "true",
+            "rate_limit_per_ip": int(os.getenv("RATE_LIMIT_PER_IP", "100")),
+            "max_request_size_mb": int(os.getenv("MAX_REQUEST_SIZE_MB", "10")),
+            "enable_content_filtering": os.getenv("ENABLE_CONTENT_FILTERING", "true").lower() == "true"
+        }
+        
+        # Load from config file
+        config_file = self.config_dir / "security_config.json"
+        if config_file.exists():
+            try:
+                with open(config_file, 'r') as f:
+                    file_config = json.load(f)
+                config_data.update(file_config)
+                logger.info("Loaded security configuration from config file")
+            except Exception as e:
+                logger.warning(f"Failed to load security config: {e}")
+        
+        return SecurityConfig(**config_data)
+    
+    def save_config_template(self):
+        """Save configuration templates for easy editing."""
+        templates = {
+            "api_config.json": {
+                "nebius_model": "meta-llama/Meta-Llama-3.1-8B-Instruct",
+                "nebius_max_tokens": 1000,
+                "nebius_temperature": 0.7,
+                "tavily_search_depth": "basic",
+                "tavily_max_results": 5
+            },
+            "app_config_development.json": {
+                "debug": True,
+                "log_level": "DEBUG",
+                "gradio_share": False,
+                "max_search_results": 5
+            },
+            "app_config_production.json": {
+                "debug": False,
+                "log_level": "INFO",
+                "gradio_share": False,
+                "max_search_results": 10,
+                "cache_ttl_seconds": 7200
+            },
+            "security_config.json": {
+                "enable_authentication": False,
+                "allowed_origins": ["*"],
+                "rate_limit_per_ip": 100,
+                "enable_content_filtering": True,
+                "blocked_patterns": []
+            }
+        }
+        
+        for filename, template in templates.items():
+            config_file = self.config_dir / filename
+            if not config_file.exists():
+                try:
+                    with open(config_file, 'w') as f:
+                        json.dump(template, f, indent=2)
+                    logger.info(f"Created config template: {filename}")
+                except Exception as e:
+                    logger.error(f"Failed to create config template {filename}: {e}")
+    
+    def get_config_summary(self) -> Dict[str, Any]:
+        """Get a summary of current configuration (without sensitive data)."""
+        return {
+            "environment": self.app_config.environment,
+            "debug_mode": self.app_config.debug,
+            "log_level": self.app_config.log_level,
+            "gradio_port": self.app_config.gradio_server_port,
+            "cache_ttl": self.app_config.cache_ttl_seconds,
+            "max_search_results": self.app_config.max_search_results,
+            "authentication_enabled": self.security_config.enable_authentication,
+            "content_filtering_enabled": self.security_config.enable_content_filtering,
+            "api_endpoints": {
+                "nebius": bool(self.api_config.nebius_api_key),
+                "tavily": bool(self.api_config.tavily_api_key)
+            }
+        }

mcp_hub/async_utils.py

@@ -0,0 +1,95 @@
+"""Async utilities for improved performance in concurrent operations."""
+
+import asyncio
+import aiohttp
+from typing import Dict, Any, List
+from concurrent.futures import ThreadPoolExecutor
+from .config import api_config, app_config
+from .exceptions import APIError
+from .logging_config import logger
+
+class AsyncWebSearchAgent:
+    """Async version of web search for concurrent operations."""
+    
+    def __init__(self):
+        self.session = None
+        
+    async def __aenter__(self):
+        """Async context manager entry."""
+        self.session = aiohttp.ClientSession()
+        return self
+        
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        if self.session:
+            await self.session.close()
+    
+    async def search_multiple_queries(self, queries: List[str]) -> List[Dict[str, Any]]:
+        """Search multiple queries concurrently."""
+        if not self.session:
+            raise APIError("AsyncWebSearch", "Session not initialized. Use as async context manager.")
+        
+        logger.info(f"Starting concurrent search for {len(queries)} queries")
+        
+        # Create tasks for concurrent execution
+        tasks = [self._search_single_query(query) for query in queries]
+        
+        # Execute all searches concurrently
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        
+        # Process results and handle any exceptions
+        processed_results = []
+        for i, result in enumerate(results):
+            if isinstance(result, Exception):
+                logger.error(f"Search failed for query {i}: {str(result)}")
+                processed_results.append({
+                    "error": str(result),
+                    "query": queries[i],
+                    "results": []
+                })
+            else:
+                processed_results.append(result)
+        
+        logger.info(f"Completed concurrent searches: {len([r for r in processed_results if not r.get('error')])} successful")
+        return processed_results
+    
+    async def _search_single_query(self, query: str) -> Dict[str, Any]:
+        """Search a single query using Tavily API."""
+        try:
+            # In a real implementation, you'd make async HTTP calls to Tavily
+            # For now, we'll use the sync version in a thread pool
+            from tavily import TavilyClient
+            client = TavilyClient(api_key=api_config.tavily_api_key)
+            
+            # Run sync operation in thread pool
+            loop = asyncio.get_event_loop()
+            with ThreadPoolExecutor() as executor:
+                response = await loop.run_in_executor(
+                    executor,
+                    lambda: client.search(
+                        query=query,
+                        search_depth="basic",
+                        max_results=app_config.max_search_results,
+                        include_answer=True
+                    )
+                )
+            
+            return {
+                "query": response.get("query", query),
+                "tavily_answer": response.get("answer"),
+                "results": response.get("results", []),
+                "data_source": "Tavily Search API (Async)",
+            }
+            
+        except Exception as e:
+            raise APIError("Tavily", f"Async search failed: {str(e)}")
+
+async def process_subquestions_concurrently(sub_questions: List[str]) -> List[Dict[str, Any]]:
+    """Process multiple sub-questions concurrently for better performance."""
+    logger.info(f"Processing {len(sub_questions)} sub-questions concurrently")
+    
+    async with AsyncWebSearchAgent() as async_searcher:
+        # Execute all searches concurrently
+        search_results = await async_searcher.search_multiple_queries(sub_questions)
+        
+        return search_results

mcp_hub/cache_utils.py

@@ -0,0 +1,211 @@
+"""Caching system for improved performance and reduced API calls."""
+
+import hashlib
+import json
+import pickle
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any, Dict, Optional, Callable
+from functools import wraps
+from .logging_config import logger
+
+class CacheManager:
+    """Simple file-based cache manager for API responses and computations."""
+    
+    def __init__(self, cache_dir: str = "cache", default_ttl: int = 3600):
+        """
+        Initialize cache manager.
+        
+        Args:
+            cache_dir: Directory to store cache files
+            default_ttl: Default time-to-live in seconds (1 hour default)
+        """
+        self.cache_dir = Path(cache_dir)
+        self.cache_dir.mkdir(exist_ok=True)
+        self.default_ttl = default_ttl
+        logger.info(f"Cache manager initialized with directory: {self.cache_dir}")
+    
+    def _get_cache_key(self, func_name: str, args: tuple, kwargs: dict) -> str:
+        """Generate a unique cache key based on function name and arguments."""
+        # Create a string representation of arguments
+        key_data = {
+            "func": func_name,
+            "args": args,
+            "kwargs": kwargs
+        }
+        key_string = json.dumps(key_data, sort_keys=True, default=str)
+        return hashlib.md5(key_string.encode()).hexdigest()
+    
+    def _get_cache_path(self, cache_key: str) -> Path:
+        """Get the file path for a cache key."""
+        return self.cache_dir / f"{cache_key}.cache"
+    
+    def get(self, cache_key: str) -> Optional[Any]:
+        """Retrieve a value from cache if it exists and is not expired."""
+        cache_path = self._get_cache_path(cache_key)
+        
+        if not cache_path.exists():
+            return None
+        
+        try:
+            with open(cache_path, 'rb') as f:
+                cache_data = pickle.load(f)
+            
+            # Check if cache has expired
+            if datetime.now() > cache_data['expires_at']:
+                logger.debug(f"Cache expired for key: {cache_key}")
+                cache_path.unlink()  # Delete expired cache
+                return None
+            
+            logger.debug(f"Cache hit for key: {cache_key}")
+            return cache_data['value']
+            
+        except (EOFError, pickle.PickleError, KeyError) as e:
+            logger.warning(f"Cache corruption for key {cache_key}: {e}")
+            cache_path.unlink()  # Delete corrupted cache
+            return None
+    
+    def set(self, cache_key: str, value: Any, ttl: Optional[int] = None) -> None:
+        """Store a value in cache with optional TTL."""
+        if ttl is None:
+            ttl = self.default_ttl
+        
+        cache_data = {
+            'value': value,
+            'created_at': datetime.now(),
+            'expires_at': datetime.now() + timedelta(seconds=ttl)
+        }
+        
+        cache_path = self._get_cache_path(cache_key)
+        
+        try:
+            with open(cache_path, 'wb') as f:
+                pickle.dump(cache_data, f)
+            logger.debug(f"Cached value for key: {cache_key} (TTL: {ttl}s)")
+        except Exception as e:
+            logger.error(f"Failed to cache value for key {cache_key}: {e}")
+    
+    def cached_call(self, func: Callable, args: tuple, kwargs: dict, ttl: Optional[int] = None) -> Any:
+        """Make a cached function call."""
+        cache_key = self._get_cache_key(func.__name__, args, kwargs)
+        
+        # Try to get from cache first
+        cached_result = self.get(cache_key)
+        if cached_result is not None:
+            return cached_result
+        
+        # Execute function and cache result
+        logger.debug(f"Cache miss for {func.__name__}, executing function")
+        result = func(*args, **kwargs)
+        self.set(cache_key, result, ttl)
+        
+        return result
+    
+    def clear_expired(self) -> int:
+        """Remove all expired cache files and return count of removed files."""
+        removed_count = 0
+        current_time = datetime.now()
+        
+        for cache_file in self.cache_dir.glob("*.cache"):
+            try:
+                with open(cache_file, 'rb') as f:
+                    cache_data = pickle.load(f)
+                
+                if current_time > cache_data['expires_at']:
+                    cache_file.unlink()
+                    removed_count += 1
+                    
+            except Exception as e:
+                logger.warning(f"Error checking cache file {cache_file}: {e}")
+                cache_file.unlink()  # Remove corrupted files
+                removed_count += 1
+        
+        if removed_count > 0:
+            logger.info(f"Removed {removed_count} expired cache files")
+        
+        return removed_count
+    
+    def clear_all(self) -> int:
+        """Remove all cache files and return count of removed files."""
+        removed_count = 0
+        for cache_file in self.cache_dir.glob("*.cache"):
+            cache_file.unlink()
+            removed_count += 1
+        
+        logger.info(f"Cleared all cache: removed {removed_count} files")
+        return removed_count
+    
+    def get_cache_status(self) -> Dict[str, Any]:
+        """Get detailed status information about the cache system."""
+        try:
+            # Count cache files
+            cache_files = list(self.cache_dir.glob("*.cache"))
+            cache_count = len(cache_files)
+            
+            # Calculate cache directory size
+            total_size = sum(f.stat().st_size for f in cache_files)
+            
+            # Count expired files
+            expired_count = 0
+            current_time = datetime.now()
+            for cache_file in cache_files:
+                try:
+                    with open(cache_file, 'rb') as f:
+                        cache_data = pickle.load(f)
+                    
+                    if current_time > cache_data['expires_at']:
+                        expired_count += 1
+                except Exception:
+                    expired_count += 1  # Count corrupted files as expired
+            
+            # Get cache stats
+            return {
+                "status": "healthy",
+                "cache_dir": str(self.cache_dir),
+                "total_files": cache_count,
+                "expired_files": expired_count,
+                "total_size_bytes": total_size,
+                "total_size_mb": round(total_size / (1024 * 1024), 2),
+                "default_ttl_seconds": self.default_ttl,
+                "timestamp": datetime.now().isoformat()
+            }
+        except Exception as e:
+            logger.error(f"Failed to get cache status: {str(e)}")
+            return {
+                "status": "error",
+                "error": str(e),
+                "timestamp": datetime.now().isoformat()
+            }
+
+# Global cache manager instance
+cache_manager = CacheManager()
+
+def cached(ttl: int = 3600):
+    """
+    Decorator to cache function results.
+    
+    Args:
+        ttl: Time-to-live in seconds
+    """
+    def decorator(func: Callable):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            return cache_manager.cached_call(func, args, kwargs, ttl)
+        return wrapper
+    return decorator
+
+# Specialized caching functions for common operations
+@cached(ttl=1800)  # 30 minutes
+def cached_web_search(query: str) -> Dict[str, Any]:
+    """Cached version of web search - import happens at runtime."""
+    # Import at runtime to avoid circular imports
+    from tavily import TavilyClient
+    client = TavilyClient(api_key="placeholder")  # Will be replaced at runtime
+    # This is a placeholder - actual implementation would use the real agent
+    return {"query": query, "results": [], "cached": True}
+
+@cached(ttl=3600)  # 1 hour  
+def cached_llm_processing(text_input: str, task: str, context: Optional[str] = None) -> Dict[str, Any]:
+    """Cached version of LLM processing - import happens at runtime."""
+    # This is a placeholder for the caching pattern
+    return {"input_text": text_input, "task": task, "cached": True}

mcp_hub/config.py

@@ -0,0 +1,120 @@
+"""Configuration management for the MCP Hub project."""
+
+import os
+from dataclasses import dataclass
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+@dataclass
+class APIConfig:
+    """API configuration settings."""
+    # Provider selection
+    llm_provider: str = "nebius"  # Options: "nebius", "openai", "anthropic", "huggingface"
+    
+    # Provider API keys
+    nebius_api_key: str = ""
+    openai_api_key: str = ""
+    anthropic_api_key: str = ""
+    huggingface_api_key: str = ""
+    
+    # Other APIs
+    tavily_api_key: str = ""
+    
+    # Provider URLs
+    nebius_base_url: str = "https://api.studio.nebius.com/v1/"
+    huggingface_base_url: str = "https://api-inference.huggingface.co"
+    
+    # Other settings
+    current_year: str = "2025"
+    
+    def __post_init__(self):
+        """Validate required API keys based on selected provider."""
+        # Always require Tavily for search functionality
+        if not self.tavily_api_key or not self.tavily_api_key.startswith("tvly-"):
+            raise RuntimeError("A valid TAVILY_API_KEY is required in your .env file.")
+        
+        # Validate LLM provider selection
+        valid_providers = ["nebius", "openai", "anthropic", "huggingface"]
+        if self.llm_provider not in valid_providers:
+            raise RuntimeError(f"LLM_PROVIDER must be one of: {', '.join(valid_providers)}")
+        
+        # Validate required API key for selected provider
+        if self.llm_provider == "nebius" and not self.nebius_api_key:
+            raise RuntimeError("NEBIUS_API_KEY is required when using nebius provider.")
+        elif self.llm_provider == "openai" and not self.openai_api_key:
+            raise RuntimeError("OPENAI_API_KEY is required when using openai provider.")
+        elif self.llm_provider == "anthropic" and not self.anthropic_api_key:
+            raise RuntimeError("ANTHROPIC_API_KEY is required when using anthropic provider.")
+        elif self.llm_provider == "huggingface" and not self.huggingface_api_key:
+            raise RuntimeError("HUGGINGFACE_API_KEY is required when using huggingface provider.")
+
+@dataclass
+class ModelConfig:
+    """Model configuration settings."""
+    # Default models (Nebius/HuggingFace compatible)
+    question_enhancer_model: str = "Qwen/Qwen3-4B-fast"
+    llm_processor_model: str = "meta-llama/Meta-Llama-3.1-8B-Instruct"
+    code_generator_model: str = "Qwen/Qwen2.5-Coder-32B-Instruct-fast"
+    orchestrator_model: str = "Qwen/Qwen3-32B-fast"
+    
+    def get_model_for_provider(self, task: str, provider: str) -> str:
+        """Get appropriate model for the given task and provider."""
+        
+        # Model mappings by provider
+        provider_models = {
+            "nebius": {
+                "question_enhancer": self.question_enhancer_model,
+                "llm_processor": self.llm_processor_model,
+                "code_generator": self.code_generator_model,
+                "orchestrator": self.orchestrator_model,
+            },
+            "openai": {
+                "question_enhancer": "gpt-4.1-nano",
+                "llm_processor": "gpt-4.1-nano",
+                "code_generator": "gpt-4.1",
+                "orchestrator": "gpt-4.1",
+            },
+            "anthropic": {
+                "question_enhancer": "claude-3-5-haiku-latest",#
+                "llm_processor": "claude-3-5-sonnet-latest",
+                "code_generator": "claude-sonnet-4-0",
+                "orchestrator": "claude-sonnet-4-0",
+            },
+            "huggingface": {
+                "question_enhancer": "microsoft/phi-4",
+                "llm_processor": "microsoft/phi-4", 
+                "code_generator": "Qwen/Qwen2.5-Coder-32B-Instruct",
+                "orchestrator": "microsoft/phi-4",
+            }
+        }
+        
+        if provider not in provider_models:
+            # Fall back to default models
+            return getattr(self, f"{task}_model", self.llm_processor_model)
+        
+        return provider_models[provider].get(task, provider_models[provider]["llm_processor"])
+
+@dataclass
+class AppConfig:
+    """Application configuration settings."""
+    modal_app_name: str = "my-sandbox-app"
+    max_search_results: int = 2
+    max_code_generation_attempts: int = 3
+    llm_temperature: float = 0.6
+    code_gen_temperature: float = 0.1
+
+# Create global configuration instances
+api_config = APIConfig(
+    llm_provider=os.environ.get("LLM_PROVIDER", "nebius"),
+    nebius_api_key=os.environ.get("NEBIUS_API_KEY", ""),
+    openai_api_key=os.environ.get("OPENAI_API_KEY", ""),
+    anthropic_api_key=os.environ.get("ANTHROPIC_API_KEY", ""),
+    huggingface_api_key=os.environ.get("HUGGINGFACE_API_KEY", ""),
+    tavily_api_key=os.environ.get("TAVILY_API_KEY", ""),
+    current_year=os.environ.get("CURRENT_YEAR", "2025")
+)
+
+model_config = ModelConfig()
+app_config = AppConfig()

mcp_hub/exceptions.py

@@ -0,0 +1,28 @@
+"""Custom exception classes for the MCP Hub project."""
+
+class MCPHubError(Exception):
+    """Base exception class for MCP Hub errors."""
+    pass
+
+class APIError(MCPHubError):
+    """Raised when API calls fail."""
+    def __init__(self, service: str, message: str):
+        self.service = service
+        self.message = message
+        super().__init__(f"{service} API Error: {message}")
+
+class ConfigurationError(MCPHubError):
+    """Raised when there are configuration issues."""
+    pass
+
+class ValidationError(MCPHubError):
+    """Raised when input validation fails."""
+    pass
+
+class CodeGenerationError(MCPHubError):
+    """Raised when code generation fails."""
+    pass
+
+class CodeExecutionError(MCPHubError):
+    """Raised when code execution fails."""
+    pass

mcp_hub/health_monitoring.py

@@ -0,0 +1,261 @@
+"""System health monitoring and status dashboard functionality."""
+
+import time
+import psutil
+from datetime import datetime
+from typing import Dict, Any
+from .config import api_config
+from .logging_config import logger
+from .reliability_utils import health_monitor
+from .performance_monitoring import metrics_collector
+
+class SystemHealthChecker:
+    """Comprehensive system health checking."""
+    
+    def __init__(self):
+        self.last_check = None
+        self.health_status = {}
+    
+    def check_api_connectivity(self) -> Dict[str, Any]:
+        """Check connectivity to external APIs."""
+        results = {}
+        
+        # Check Nebius API
+        try:
+            from openai import OpenAI
+            client = OpenAI(
+                api_key=api_config.nebius_api_key,
+                base_url=api_config.nebius_base_url
+            )
+            
+            start_time = time.time()
+            # Make a minimal test call
+            response = client.chat.completions.create(
+                model="meta-llama/Meta-Llama-3.1-8B-Instruct",
+                messages=[{"role": "user", "content": "test"}],
+                max_tokens=1
+            )
+            response_time = time.time() - start_time
+            
+            results["nebius"] = {
+                "status": "healthy",
+                "response_time_ms": response_time * 1000,
+                "last_checked": datetime.now().isoformat()
+            }
+            
+        except Exception as e:
+            results["nebius"] = {
+                "status": "unhealthy",
+                "error": str(e),
+                "last_checked": datetime.now().isoformat()
+            }
+        
+        # Check Tavily API
+        try:
+            from tavily import TavilyClient
+            client = TavilyClient(api_key=api_config.tavily_api_key)
+            
+            start_time = time.time()
+            # Make a minimal test search
+            response = client.search(query="test", max_results=1)
+            response_time = time.time() - start_time
+            
+            results["tavily"] = {
+                "status": "healthy",
+                "response_time_ms": response_time * 1000,
+                "last_checked": datetime.now().isoformat()
+            }
+            
+        except Exception as e:
+            results["tavily"] = {
+                "status": "unhealthy", 
+                "error": str(e),
+                "last_checked": datetime.now().isoformat()
+            }
+        
+        return results
+    
+    def check_system_resources(self) -> Dict[str, Any]:
+        """Check system resource usage."""
+        try:
+            # CPU usage
+            cpu_percent = psutil.cpu_percent(interval=1)
+            
+            # Memory usage
+            memory = psutil.virtual_memory()
+            
+            # Disk usage
+            disk = psutil.disk_usage('/')
+            
+            # Process-specific metrics
+            process = psutil.Process()
+            process_memory = process.memory_info()
+            
+            return {
+                "cpu_percent": cpu_percent,
+                "memory": {
+                    "total_gb": memory.total / (1024**3),
+                    "available_gb": memory.available / (1024**3),
+                    "percent_used": memory.percent
+                },
+                "disk": {
+                    "total_gb": disk.total / (1024**3),
+                    "free_gb": disk.free / (1024**3),
+                    "percent_used": (disk.used / disk.total) * 100
+                },
+                "process": {
+                    "memory_mb": process_memory.rss / (1024**2),
+                    "cpu_percent": process.cpu_percent()
+                },
+                "status": "healthy",
+                "last_checked": datetime.now().isoformat()
+            }
+            
+        except Exception as e:
+            return {
+                "status": "unhealthy",
+                "error": str(e),
+                "last_checked": datetime.now().isoformat()
+            }
+    
+    def check_cache_health(self) -> Dict[str, Any]:
+        """Check cache system health."""
+        try:
+            from cache_utils import cache_manager
+            
+            # Count cache files
+            cache_files = list(cache_manager.cache_dir.glob("*.cache"))
+            
+            # Calculate cache directory size
+            total_size = sum(f.stat().st_size for f in cache_files)
+            
+            return {
+                "cache_files_count": len(cache_files),
+                "total_size_mb": total_size / (1024**2),
+                "cache_directory": str(cache_manager.cache_dir),
+                "status": "healthy",
+                "last_checked": datetime.now().isoformat()
+            }
+            
+        except Exception as e:
+            return {
+                "status": "unhealthy",
+                "error": str(e),
+                "last_checked": datetime.now().isoformat()
+            }
+    
+    def get_comprehensive_health_report(self) -> Dict[str, Any]:
+        """Get a comprehensive health report of the entire system."""
+        logger.info("Generating comprehensive health report")
+        
+        report = {
+            "timestamp": datetime.now().isoformat(),
+            "overall_status": "healthy"  # Will be updated based on checks
+        }
+        
+        # Check API connectivity
+        api_health = self.check_api_connectivity()
+        report["api_connectivity"] = api_health
+        
+        # Check system resources
+        system_health = self.check_system_resources()
+        report["system_resources"] = system_health
+        
+        # Check cache health
+        cache_health = self.check_cache_health()
+        report["cache_system"] = cache_health
+        
+        # Get API health stats from monitor
+        try:
+            nebius_stats = health_monitor.get_health_stats("nebius")
+            tavily_stats = health_monitor.get_health_stats("tavily")
+            
+            report["api_performance"] = {
+                "nebius": nebius_stats,
+                "tavily": tavily_stats
+            }
+        except Exception as e:
+            report["api_performance"] = {"error": str(e)}
+        
+        # Get performance metrics
+        try:
+            performance_summary = metrics_collector.get_metrics_summary()
+            report["performance_metrics"] = performance_summary
+        except Exception as e:
+            report["performance_metrics"] = {"error": str(e)}
+        
+        # Determine overall status
+        unhealthy_components = []
+        
+        for service, status in api_health.items():
+            if status.get("status") == "unhealthy":
+                unhealthy_components.append(f"API:{service}")
+        
+        if system_health.get("status") == "unhealthy":
+            unhealthy_components.append("system_resources")
+        
+        if cache_health.get("status") == "unhealthy":
+            unhealthy_components.append("cache_system")
+        
+        if unhealthy_components:
+            report["overall_status"] = "degraded"
+            report["unhealthy_components"] = unhealthy_components
+        
+        self.last_check = datetime.now()
+        self.health_status = report
+        
+        logger.info(f"Health report generated: {report['overall_status']}")
+        return report
+
+# Global health checker instance
+health_checker = SystemHealthChecker()
+
+def create_health_dashboard() -> str:
+    """Create a formatted health dashboard for display."""
+    report = health_checker.get_comprehensive_health_report()
+    
+    dashboard = f"""
+# 🏥 System Health Dashboard
+**Last Updated:** {report['timestamp']}  
+**Overall Status:** {'🟢' if report['overall_status'] == 'healthy' else '🟡' if report['overall_status'] == 'degraded' else '🔴'} {report['overall_status'].upper()}
+
+## 🌐 API Connectivity
+"""
+    
+    for service, status in report.get("api_connectivity", {}).items():
+        status_icon = "🟢" if status.get("status") == "healthy" else "🔴"
+        response_time = status.get("response_time_ms", 0)
+        dashboard += f"- **{service.title()}:** {status_icon} {status.get('status', 'unknown')} ({response_time:.1f}ms)\n"
+    
+    dashboard += "\n## 💻 System Resources\n"
+    sys_resources = report.get("system_resources", {})
+    if "memory" in sys_resources:
+        memory = sys_resources["memory"]
+        dashboard += f"- **Memory:** {memory['percent_used']:.1f}% used ({memory['available_gb']:.1f}GB available)\n"
+    
+    if "cpu_percent" in sys_resources:
+        dashboard += f"- **CPU:** {sys_resources['cpu_percent']:.1f}% usage\n"
+    
+    if "process" in sys_resources:
+        process = sys_resources["process"]
+        dashboard += f"- **Process Memory:** {process['memory_mb']:.1f}MB\n"
+    
+    dashboard += "\n## 📊 Performance Metrics\n"
+    perf_metrics = report.get("performance_metrics", {})
+    if perf_metrics and not perf_metrics.get("error"):
+        for metric_name, metric_data in perf_metrics.items():
+            if isinstance(metric_data, dict) and "average" in metric_data:
+                dashboard += f"- **{metric_name}:** Avg: {metric_data['average']:.3f}, Count: {metric_data['count']}\n"
+    
+    dashboard += "\n## 🔧 Cache System\n"
+    cache_info = report.get("cache_system", {})
+    if cache_info.get("status") == "healthy":
+        dashboard += f"- **Cache Files:** {cache_info.get('cache_files_count', 0)} files\n"
+        dashboard += f"- **Cache Size:** {cache_info.get('total_size_mb', 0):.1f}MB\n"
+    
+    if report.get("unhealthy_components"):
+        dashboard += "\n## ⚠️ Issues Detected\n"
+        for component in report["unhealthy_components"]:
+            dashboard += f"- {component}\n"
+    
+    return dashboard

mcp_hub/logging_config.py

@@ -0,0 +1,51 @@
+"""Logging configuration for the MCP Hub project."""
+
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+
+def setup_logging(
+    log_level: str = "INFO",
+    log_to_file: bool = True,
+    log_dir: str = "logs"
+) -> logging.Logger:
+    """Set up logging configuration."""
+    
+    # Create logs directory if it doesn't exist
+    if log_to_file:
+        log_path = Path(log_dir)
+        log_path.mkdir(exist_ok=True)
+    
+    # Create logger
+    logger = logging.getLogger("mcp_hub")
+    logger.setLevel(getattr(logging, log_level.upper()))
+    
+    # Clear any existing handlers
+    logger.handlers = []
+    
+    # Create formatter
+    formatter = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(funcName)s:%(lineno)d - %(message)s"
+    )
+    
+    # Console handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(getattr(logging, log_level.upper()))
+    console_handler.setFormatter(formatter)
+    logger.addHandler(console_handler)
+    
+    # File handler
+    if log_to_file:
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        file_handler = logging.FileHandler(
+            log_path / f"mcp_hub_{timestamp}.log"
+        )
+        file_handler.setLevel(logging.DEBUG)
+        file_handler.setFormatter(formatter)
+        logger.addHandler(file_handler)
+    
+    return logger
+
+# Create global logger instance
+logger = setup_logging()

mcp_hub/package_utils.py

@@ -0,0 +1,192 @@
+"""
+Package management utilities for dynamic package installation in Modal sandboxes.
+This module provides functions to analyze code for imports and manage package installation.
+"""
+import ast
+import re
+from typing import Set, List
+
+try:
+    from mcp_hub.logging_config import logger
+except ImportError:
+    # Fallback logger for testing/standalone use
+    import logging
+    logger = logging.getLogger(__name__)
+
+
+# Core packages that should be preinstalled in the base image
+CORE_PREINSTALLED_PACKAGES = {
+    "numpy", "pandas", "matplotlib", "requests", "json", "os", "sys", 
+    "time", "datetime", "math", "random", "collections", "itertools",
+    "functools", "re", "urllib", "csv", "sqlite3", "pathlib", "typing",
+    "asyncio", "threading", "multiprocessing", "subprocess", "shutil",
+    "tempfile", "io", "gzip", "zipfile", "tarfile", "base64", "hashlib",
+    "secrets", "uuid", "pickle", "copy", "operator", "bisect", "heapq",
+    "contextlib", "weakref", "gc", "inspect", "types", "enum", "dataclasses",
+    "decimal", "fractions", "statistics", "string", "textwrap", "locale",
+    "calendar", "timeit", "argparse", "getopt", "logging", "warnings",
+    "platform", "signal", "errno", "ctypes", "struct", "array", "queue",
+    "socketserver", "http", "urllib2", "html", "xml", "email", "mailbox"
+}
+
+# Extended packages that can be dynamically installed
+COMMON_PACKAGES = {
+    "scikit-learn": "sklearn", 
+    "beautifulsoup4": "bs4",
+    "pillow": "PIL",
+    "opencv-python-headless": "cv2",
+    "python-dateutil": "dateutil",
+    "plotly": "plotly",
+    "seaborn": "seaborn",
+    "polars": "polars",
+    "lightgbm": "lightgbm", 
+    "xgboost": "xgboost",
+    "flask": "flask",
+    "fastapi": "fastapi",
+    "httpx": "httpx",
+    "networkx": "networkx",
+    "wordcloud": "wordcloud",
+    "textblob": "textblob",
+    "spacy": "spacy",
+    "nltk": "nltk"
+}
+
+# Map import names to package names
+IMPORT_TO_PACKAGE = {v: k for k, v in COMMON_PACKAGES.items()}
+IMPORT_TO_PACKAGE.update({k: k for k in COMMON_PACKAGES.keys()})
+
+
+def extract_imports_from_code(code_str: str) -> Set[str]:
+    """
+    Extract all import statements from Python code using AST parsing.
+    
+    Args:
+        code_str: The Python code to analyze
+        
+    Returns:
+        Set of imported module names (top-level only)
+    """
+    imports = set()
+    
+    try:
+        tree = ast.parse(code_str)
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    # Get top-level module name
+                    module_name = alias.name.split('.')[0]
+                    imports.add(module_name)
+            elif isinstance(node, ast.ImportFrom):
+                if node.module:
+                    # Get top-level module name
+                    module_name = node.module.split('.')[0]
+                    imports.add(module_name)
+    except Exception as e:
+        logger.warning(f"Failed to parse code with AST, falling back to regex: {e}")
+        # Fallback to regex-based extraction
+        imports.update(extract_imports_with_regex(code_str))
+    
+    return imports
+
+
+def extract_imports_with_regex(code_str: str) -> Set[str]:
+    """
+    Fallback method to extract imports using regex patterns.
+    
+    Args:
+        code_str: The Python code to analyze
+        
+    Returns:
+        Set of imported module names
+    """
+    imports = set()
+    
+    # Pattern for "import module" statements
+    import_pattern = r'^import\s+([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)'
+    
+    # Pattern for "from module import ..." statements  
+    from_pattern = r'^from\s+([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)\s+import'
+    
+    for line in code_str.split('\n'):
+        line = line.strip()
+        if not line or line.startswith('#'):
+            continue
+            
+        # Check for import statements
+        import_match = re.match(import_pattern, line)
+        if import_match:
+            module_name = import_match.group(1).split('.')[0]
+            imports.add(module_name)
+            continue
+            
+        # Check for from...import statements
+        from_match = re.match(from_pattern, line)
+        if from_match:
+            module_name = from_match.group(1).split('.')[0]
+            imports.add(module_name)
+            
+    return imports
+
+
+def get_packages_to_install(detected_imports: Set[str]) -> List[str]:
+    """
+    Determine which packages need to be installed based on detected imports.
+    
+    Args:
+        detected_imports: Set of module names found in the code
+        
+    Returns:
+        List of package names that need to be pip installed
+    """
+    packages_to_install = []
+    
+    for import_name in detected_imports:
+        # Skip if it's a core preinstalled package
+        if import_name in CORE_PREINSTALLED_PACKAGES:
+            continue
+            
+        # Check if we have a known package mapping
+        if import_name in IMPORT_TO_PACKAGE:
+            package_name = IMPORT_TO_PACKAGE[import_name]
+            packages_to_install.append(package_name)
+        # For unknown packages, assume package name matches import name
+        elif import_name not in CORE_PREINSTALLED_PACKAGES:
+            packages_to_install.append(import_name)
+    
+    return packages_to_install
+
+
+def get_warmup_import_commands() -> List[str]:
+    """
+    Get list of import commands to run during sandbox warmup.
+    
+    Returns:
+        List of Python import statements for core packages
+    """
+    core_imports = [
+        "import numpy",
+        "import pandas", 
+        "import matplotlib.pyplot",
+        "import requests",
+        "print('Core packages warmed up successfully')"
+    ]
+    
+    return core_imports
+
+
+def create_package_install_command(packages: List[str]) -> str:
+    """
+    Create a pip install command for the given packages.
+    
+    Args:
+        packages: List of package names to install
+        
+    Returns:
+        Pip install command string
+    """
+    if not packages:
+        return ""
+    
+    # Remove duplicates and sort
+    unique_packages = sorted(set(packages))
+    return f"pip install {' '.join(unique_packages)}"

mcp_hub/performance_monitoring.py

@@ -0,0 +1,232 @@
+"""Performance monitoring and metrics collection for the MCP Hub."""
+
+import time
+import psutil
+import threading
+from datetime import datetime, timedelta
+from typing import Dict, Any, Optional
+from collections import defaultdict, deque
+from dataclasses import dataclass
+from contextlib import contextmanager
+from .logging_config import logger
+
+@dataclass
+class MetricPoint:
+    """Single metric measurement."""
+    timestamp: datetime
+    metric_name: str
+    value: float
+    tags: Dict[str, str]
+
+class MetricsCollector:
+    """Collects and stores application metrics."""
+    
+    def __init__(self, max_points: int = 10000):
+        """
+        Initialize metrics collector.
+        
+        Args:
+            max_points: Maximum number of metric points to store
+        """
+        self.max_points = max_points
+        self.metrics = defaultdict(lambda: deque(maxlen=max_points))
+        self.lock = threading.Lock()
+        self.counters = defaultdict(int)
+        self.timers = {}
+        
+        # Start system metrics collection thread
+        self.system_thread = threading.Thread(target=self._collect_system_metrics, daemon=True)
+        self.system_thread.start()
+        logger.info("Metrics collector initialized")
+    
+    def record_metric(self, name: str, value: float, tags: Optional[Dict[str, str]] = None):
+        """Record a metric value."""
+        if tags is None:
+            tags = {}
+        
+        point = MetricPoint(
+            timestamp=datetime.now(),
+            metric_name=name,
+            value=value,
+            tags=tags
+        )
+        
+        with self.lock:
+            self.metrics[name].append(point)
+    
+    def increment_counter(self, name: str, amount: int = 1, tags: Optional[Dict[str, str]] = None):
+        """Increment a counter metric."""
+        with self.lock:
+            self.counters[name] += amount
+        
+        self.record_metric(f"{name}_count", self.counters[name], tags)
+    
+    @contextmanager
+    def timer(self, name: str, tags: Optional[Dict[str, str]] = None):
+        """Context manager for timing operations."""
+        start_time = time.time()
+        try:
+            yield
+        finally:
+            duration = time.time() - start_time
+            self.record_metric(f"{name}_duration_seconds", duration, tags)
+    
+    def get_metrics_summary(self, 
+                          metric_name: Optional[str] = None, 
+                          last_minutes: int = 5) -> Dict[str, Any]:
+        """Get summary statistics for metrics."""
+        cutoff_time = datetime.now() - timedelta(minutes=last_minutes)
+        
+        with self.lock:
+            if metric_name:
+                metrics_to_analyze = {metric_name: self.metrics[metric_name]}
+            else:
+                metrics_to_analyze = dict(self.metrics)
+        
+        summary = {}
+        
+        for name, points in metrics_to_analyze.items():
+            recent_points = [p for p in points if p.timestamp >= cutoff_time]
+            
+            if not recent_points:
+                continue
+            
+            values = [p.value for p in recent_points]
+            summary[name] = {
+                "count": len(values),
+                "average": sum(values) / len(values),
+                "min": min(values),
+                "max": max(values),
+                "latest": values[-1] if values else 0,
+                "last_updated": recent_points[-1].timestamp.isoformat() if recent_points else None
+            }
+        
+        return summary
+    
+    def _collect_system_metrics(self):
+        """Background thread to collect system metrics."""
+        while True:
+            try:
+                # CPU and memory metrics
+                cpu_percent = psutil.cpu_percent(interval=1)
+                memory = psutil.virtual_memory()
+                
+                self.record_metric("system_cpu_percent", cpu_percent)
+                self.record_metric("system_memory_percent", memory.percent)
+                self.record_metric("system_memory_available_mb", memory.available / 1024 / 1024)
+                
+                # Process-specific metrics
+                process = psutil.Process()
+                process_memory = process.memory_info()
+                
+                self.record_metric("process_memory_rss_mb", process_memory.rss / 1024 / 1024)
+                self.record_metric("process_cpu_percent", process.cpu_percent())
+                
+                time.sleep(30)  # Collect every 30 seconds
+                
+            except Exception as e:
+                logger.error(f"Error collecting system metrics: {e}")
+                time.sleep(60)  # Wait longer if there's an error
+
+class PerformanceProfiler:
+    """Profile performance of agent operations."""
+    
+    def __init__(self, metrics_collector: MetricsCollector):
+        self.metrics = metrics_collector
+        self.operation_stats = defaultdict(list)
+    
+    @contextmanager
+    def profile_operation(self, operation_name: str, **tags):
+        """Context manager to profile an operation."""
+        start_time = time.time()
+        start_memory = psutil.Process().memory_info().rss
+        
+        try:
+            yield
+            success = True
+        except Exception as e:
+            success = False
+            logger.error(f"Operation {operation_name} failed: {e}")
+            raise
+        finally:
+            end_time = time.time()
+            end_memory = psutil.Process().memory_info().rss
+            
+            duration = end_time - start_time
+            memory_delta = (end_memory - start_memory) / 1024 / 1024  # MB
+            
+            # Record metrics
+            operation_tags = {"operation": operation_name, "success": str(success), **tags}
+            self.metrics.record_metric("operation_duration_seconds", duration, operation_tags)
+            self.metrics.record_metric("operation_memory_delta_mb", memory_delta, operation_tags)
+            
+            # Update operation stats
+            self.operation_stats[operation_name].append({
+                "duration": duration,
+                "memory_delta": memory_delta,
+                "success": success,
+                "timestamp": datetime.now()
+            })
+    
+    def get_operation_summary(self, operation_name: str = None) -> Dict[str, Any]:
+        """Get summary of operation performance."""
+        if operation_name:
+            operations_to_analyze = {operation_name: self.operation_stats[operation_name]}
+        else:
+            operations_to_analyze = dict(self.operation_stats)
+        
+        summary = {}
+        
+        for op_name, stats in operations_to_analyze.items():
+            if not stats:
+                continue
+            
+            durations = [s["duration"] for s in stats]
+            memory_deltas = [s["memory_delta"] for s in stats]
+            success_rate = sum(1 for s in stats if s["success"]) / len(stats)
+            
+            summary[op_name] = {
+                "total_calls": len(stats),
+                "success_rate": success_rate,
+                "avg_duration_seconds": sum(durations) / len(durations),
+                "avg_memory_delta_mb": sum(memory_deltas) / len(memory_deltas),
+                "min_duration": min(durations),
+                "max_duration": max(durations)
+            }
+        
+        return summary
+
+# Global instances
+metrics_collector = MetricsCollector()
+performance_profiler = PerformanceProfiler(metrics_collector)
+
+# Convenience decorators
+def track_performance(operation_name: str = None):
+    """Decorator to automatically track function performance."""
+    def decorator(func):
+        nonlocal operation_name
+        if operation_name is None:
+            operation_name = f"{func.__module__}.{func.__name__}"
+        
+        def wrapper(*args, **kwargs):
+            with performance_profiler.profile_operation(operation_name):
+                result = func(*args, **kwargs)
+                metrics_collector.increment_counter(f"{operation_name}_calls")
+                return result
+        return wrapper
+    return decorator
+
+def track_api_call(service_name: str):
+    """Decorator specifically for tracking API calls."""
+    def decorator(func):
+        def wrapper(*args, **kwargs):
+            with performance_profiler.profile_operation("api_call", service=service_name):
+                try:
+                    result = func(*args, **kwargs)
+                    metrics_collector.increment_counter("api_calls_success", tags={"service": service_name})
+                    return result
+                except Exception:
+                    metrics_collector.increment_counter("api_calls_failed", tags={"service": service_name})
+                    raise
+        return wrapper
+    return decorator

mcp_hub/reliability_utils.py

@@ -0,0 +1,254 @@
+"""Rate limiting and circuit breaker patterns for robust API interactions."""
+
+import time
+from datetime import datetime
+from typing import Callable, Any, Dict
+from functools import wraps
+from threading import Lock
+from collections import deque
+from .exceptions import APIError
+from .logging_config import logger
+
+class RateLimiter:
+    """Token bucket rate limiter for API calls."""
+    
+    def __init__(self, calls_per_second: float = 1.0, burst_size: int = 5):
+        """
+        Initialize rate limiter.
+        
+        Args:
+            calls_per_second: Maximum calls per second
+            burst_size: Maximum burst of calls allowed
+        """
+        self.calls_per_second = calls_per_second
+        self.burst_size = float(burst_size)
+        self.tokens = float(burst_size)
+        self.last_update = time.time()
+        self.lock = Lock()
+    
+    def acquire(self, timeout: float = None) -> bool:
+        """
+        Acquire a token for making an API call.
+        
+        Args:
+            timeout: Maximum time to wait for a token
+            
+        Returns:
+            True if token acquired, False if timeout
+        """
+        start_time = time.time()
+        
+        while True:
+            with self.lock:
+                now = time.time()
+                # Add tokens based on elapsed time
+                time_passed = now - self.last_update
+                self.tokens = min(
+                    self.burst_size,
+                    self.tokens + time_passed * self.calls_per_second
+                )
+                self.last_update = now
+                
+                if self.tokens >= 1:
+                    self.tokens -= 1
+                    return True
+            
+            # Check timeout
+            if timeout and (time.time() - start_time) >= timeout:
+                return False
+            
+            # Wait before retrying
+            time.sleep(0.1)
+
+class CircuitBreaker:
+    """Circuit breaker pattern for handling API failures gracefully."""
+    
+    def __init__(
+        self,
+        failure_threshold: int = 5,
+        timeout: int = 60,
+        expected_exception: type = Exception
+    ):
+        """
+        Initialize circuit breaker.
+        
+        Args:
+            failure_threshold: Number of failures before opening circuit
+            timeout: Seconds to wait before trying again
+            expected_exception: Exception type that triggers circuit breaker
+        """
+        self.failure_threshold = failure_threshold
+        self.timeout = timeout
+        self.expected_exception = expected_exception
+        
+        self.failure_count = 0
+        self.last_failure_time = None
+        self.state = "CLOSED"  # CLOSED, OPEN, HALF_OPEN
+        self.lock = Lock()
+    
+    def _can_attempt(self) -> bool:
+        """Check if we can attempt the operation."""
+        if self.state == "CLOSED":
+            return True
+        elif self.state == "OPEN":
+            if (datetime.now() - self.last_failure_time).seconds >= self.timeout:
+                self.state = "HALF_OPEN"
+                return True
+            return False
+        else:  # HALF_OPEN
+            return True
+    
+    def _record_success(self):
+        """Record a successful operation."""
+        self.failure_count = 0
+        self.state = "CLOSED"
+    
+    def _record_failure(self):
+        """Record a failed operation."""
+        self.failure_count += 1
+        self.last_failure_time = datetime.now()
+        
+        if self.failure_count >= self.failure_threshold:
+            self.state = "OPEN"
+            logger.warning(f"Circuit breaker opened after {self.failure_count} failures")
+    
+    def call(self, func: Callable, *args, **kwargs) -> Any:
+        """
+        Execute function with circuit breaker protection.
+        
+        Args:
+            func: Function to execute
+            *args, **kwargs: Arguments for the function
+            
+        Returns:
+            Function result
+            
+        Raises:
+            APIError: If circuit is open or function fails
+        """
+        with self.lock:
+            if not self._can_attempt():
+                raise APIError(
+                    "CircuitBreaker",
+                    f"Circuit breaker is OPEN. Last failure: {self.last_failure_time}"
+                )
+        
+        try:
+            result = func(*args, **kwargs)
+            with self.lock:
+                self._record_success()
+            return result
+            
+        except self.expected_exception as e:
+            with self.lock:
+                self._record_failure()
+            logger.error(f"Circuit breaker recorded failure: {str(e)}")
+            raise APIError("CircuitBreaker", f"Protected function failed: {str(e)}")
+
+# Global instances for different services
+nebius_rate_limiter = RateLimiter(calls_per_second=2.0, burst_size=5)
+tavily_rate_limiter = RateLimiter(calls_per_second=1.0, burst_size=3)
+
+nebius_circuit_breaker = CircuitBreaker(failure_threshold=3, timeout=30)
+tavily_circuit_breaker = CircuitBreaker(failure_threshold=3, timeout=30)
+
+def rate_limited(service: str = "default", timeout: float = 10.0):
+    """
+    Decorator to rate limit function calls.
+    
+    Args:
+        service: Service name (nebius, tavily, or default)
+        timeout: Maximum time to wait for rate limit token
+    """
+    def decorator(func: Callable):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # Select appropriate rate limiter
+            if service == "nebius":
+                limiter = nebius_rate_limiter
+            elif service == "tavily":
+                limiter = tavily_rate_limiter
+            else:
+                limiter = RateLimiter()  # Default limiter
+            
+            if not limiter.acquire(timeout=timeout):
+                raise APIError(service, f"Rate limit timeout after {timeout}s")
+            
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator
+
+def circuit_protected(service: str = "default"):
+    """
+    Decorator to protect function calls with circuit breaker.
+    
+    Args:
+        service: Service name (nebius, tavily, or default)
+    """
+    def decorator(func: Callable):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # Select appropriate circuit breaker
+            if service == "nebius":
+                breaker = nebius_circuit_breaker
+            elif service == "tavily":
+                breaker = tavily_circuit_breaker
+            else:
+                breaker = CircuitBreaker()  # Default breaker
+            
+            return breaker.call(func, *args, **kwargs)
+        return wrapper
+    return decorator
+
+class APIHealthMonitor:
+    """Monitor API health and performance metrics."""
+    
+    def __init__(self, window_size: int = 100):
+        """
+        Initialize health monitor.
+        
+        Args:
+            window_size: Number of recent calls to track
+        """
+        self.window_size = window_size
+        self.call_history = deque(maxlen=window_size)
+        self.lock = Lock()
+    
+    def record_call(self, service: str, success: bool, response_time: float):
+        """Record an API call result."""
+        with self.lock:
+            self.call_history.append({
+                "service": service,
+                "success": success,
+                "response_time": response_time,
+                "timestamp": datetime.now()
+            })
+    
+    def get_health_stats(self, service: str = None) -> Dict[str, Any]:
+        """Get health statistics for a service or all services."""
+        with self.lock:
+            if service:
+                calls = [call for call in self.call_history if call["service"] == service]
+            else:
+                calls = list(self.call_history)
+        
+        if not calls:
+            return {"error": "No call history available"}
+        
+        total_calls = len(calls)
+        successful_calls = sum(1 for call in calls if call["success"])
+        success_rate = successful_calls / total_calls
+        
+        response_times = [call["response_time"] for call in calls]
+        avg_response_time = sum(response_times) / len(response_times)
+        
+        return {
+            "service": service or "all",
+            "total_calls": total_calls,
+            "success_rate": success_rate,
+            "avg_response_time_ms": avg_response_time * 1000,
+            "recent_failures": total_calls - successful_calls
+        }
+
+# Global health monitor
+health_monitor = APIHealthMonitor()

mcp_hub/sandbox_pool.py

@@ -0,0 +1,701 @@
+"""
+Warm Sandbox Pool for Modal - Async Queue-Based Implementation
+This module provides a pre-warmed pool of Modal sandboxes to reduce cold-start latency.
+"""
+import asyncio
+import time
+from typing import Optional, Dict, Any
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from enum import Enum
+
+import modal
+
+from mcp_hub.logging_config import logger
+from mcp_hub.exceptions import CodeExecutionError
+
+
+class SandboxHealth(Enum):
+    """Sandbox health status."""
+    HEALTHY = "healthy"
+    UNHEALTHY = "unhealthy"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class PooledSandbox:
+    """Container for a pooled sandbox with metadata."""
+    sandbox: modal.Sandbox
+    created_at: float
+    last_used: float
+    health: SandboxHealth = SandboxHealth.UNKNOWN
+    use_count: int = 0
+
+
+class WarmSandboxPool:
+    """Async queue-based warm sandbox pool with health checking."""
+    
+    def __init__(
+        self,
+        app: modal.App,
+        image: modal.Image,
+        pool_size: int = 3,
+        max_age_seconds: int = 300,  # 5 minutes
+        max_uses_per_sandbox: int = 10,
+        health_check_interval: int = 60,  # 1 minute
+    ):
+        self.app = app
+        self.image = image
+        self.pool_size = pool_size
+        self.max_age_seconds = max_age_seconds
+        self.max_uses_per_sandbox = max_uses_per_sandbox
+        self.health_check_interval = health_check_interval
+        
+        # Queue to hold available sandboxes
+        self._sandbox_queue: asyncio.Queue[PooledSandbox] = asyncio.Queue(maxsize=pool_size)
+        
+        # Background tasks
+        self._warmup_task: Optional[asyncio.Task] = None
+        self._health_check_task: Optional[asyncio.Task] = None
+        self._cleanup_task: Optional[asyncio.Task] = None
+        
+        # Pool statistics
+        self._stats = {
+            "created": 0,
+            "reused": 0,
+            "recycled": 0,
+            "health_checks": 0,
+            "failures": 0
+        }
+        
+        # Health tracking for better error recovery
+        self._consecutive_failures = 0
+        self._last_successful_creation = time.time()
+        self._pool_reset_threshold = 5  # Reset pool after 5 consecutive failures
+        
+        self._running = False
+        
+    async def start(self):
+        """Start the pool and background tasks."""
+        if self._running:
+            return
+            
+        self._running = True
+        logger.info(f"Starting warm sandbox pool with {self.pool_size} sandboxes")
+        
+        # Start background tasks
+        self._warmup_task = asyncio.create_task(self._warmup_pool())
+        self._health_check_task = asyncio.create_task(self._health_check_loop())
+        self._cleanup_task = asyncio.create_task(self._cleanup_loop())
+        
+        # Wait for initial warmup
+        await asyncio.sleep(1)  # Give warmup a moment to start
+        
+    async def stop(self):
+        """Stop the pool and cleanup resources."""
+        if not self._running:
+            return
+            
+        self._running = False
+        logger.info("Stopping warm sandbox pool")
+        
+        # Cancel background tasks
+        for task in [self._warmup_task, self._health_check_task, self._cleanup_task]:
+            if task and not task.done():
+                task.cancel()
+                try:
+                    await task
+                except asyncio.CancelledError:
+                    pass
+          # Cleanup remaining sandboxes
+        while not self._sandbox_queue.empty():
+            try:
+                pooled_sb = self._sandbox_queue.get_nowait()
+                await self._terminate_sandbox(pooled_sb.sandbox)
+            except asyncio.QueueEmpty:
+                break
+                
+    @asynccontextmanager
+    async def get_sandbox(self, timeout: float = 5.0):
+        pooled_sb = None
+        created_new = False
+        try:
+            # Check if we need to reset the pool due to consecutive failures
+            if self._consecutive_failures >= self._pool_reset_threshold:
+                logger.warning(f"Pool has {self._consecutive_failures} consecutive failures, attempting reset")
+                await self._emergency_pool_reset()
+            
+            # Try to get a warm sandbox from the pool, retry if not alive
+            max_retries = 3  # Increased retries for better reliability
+            for attempt in range(max_retries):
+                try:
+                    # Try to get from pool first
+                    pooled_sb = await asyncio.wait_for(self._sandbox_queue.get(), timeout=timeout)
+                    # Check if the sandbox is alive
+                    alive = await self._is_sandbox_alive(pooled_sb.sandbox)
+                    if not alive:
+                        logger.info(f"Got dead sandbox from pool on attempt {attempt + 1}, terminating and trying next.")
+                        await self._terminate_sandbox(pooled_sb.sandbox)
+                        pooled_sb = None
+                        continue  # Try again
+                    
+                    # Sandbox is alive, use it
+                    pooled_sb.last_used = time.time()
+                    pooled_sb.use_count += 1
+                    self._stats["reused"] += 1
+                    self._consecutive_failures = 0  # Reset failure counter on success
+                    break
+                    
+                except asyncio.TimeoutError:
+                    # Pool empty or taking too long, create a new one
+                    logger.info(f"Pool timeout on attempt {attempt + 1}, creating new sandbox")
+                    try:
+                        sandbox = await self._create_sandbox()
+                        pooled_sb = PooledSandbox(
+                            sandbox=sandbox,
+                            created_at=time.time(),
+                            last_used=time.time(),
+                            use_count=1
+                        )
+                        created_new = True
+                        self._stats["created"] += 1
+                        self._consecutive_failures = 0  # Reset failure counter on success
+                        self._last_successful_creation = time.time()
+                        break
+                    except Exception as create_error:
+                        logger.error(f"Failed to create sandbox on attempt {attempt + 1}: {create_error}")
+                        self._consecutive_failures += 1
+                        if attempt == max_retries - 1:  # Last attempt
+                            raise CodeExecutionError(f"Failed to create sandbox after {max_retries} attempts: {create_error}")
+                        await asyncio.sleep(2 ** attempt)  # Exponential backoff
+            else:
+                self._consecutive_failures += 1
+                raise CodeExecutionError("Could not obtain a live sandbox from the pool after all retry attempts.")
+            
+            logger.info(f"Yielding sandbox of type from sandbox_pool: {type(pooled_sb.sandbox)}")    
+            yield pooled_sb.sandbox
+            
+        except Exception as e:
+            logger.error(f"Error getting sandbox: {e}")
+            self._stats["failures"] += 1
+            self._consecutive_failures += 1
+            raise CodeExecutionError(f"Failed to get sandbox: {e}")        
+        finally:
+            if pooled_sb:
+                should_recycle = (
+                    not created_new and
+                    self._should_recycle_sandbox(pooled_sb) and
+                    self._running
+                )
+                if should_recycle:
+                    # Double-check sandbox is alive and functional before returning to pool
+                    if await self._is_sandbox_alive(pooled_sb.sandbox):
+                        # Additional check: try a quick execution to ensure sandbox is fully functional
+                        try:
+                            await asyncio.wait_for(
+                                asyncio.get_event_loop().run_in_executor(
+                                    None,
+                                    lambda: pooled_sb.sandbox.exec("python", "-c", "import sys; print('ready')", timeout=2)
+                                ),
+                                timeout=3.0
+                            )
+                            
+                            # Sandbox is healthy and functional - return to pool
+                            try:
+                                self._sandbox_queue.put_nowait(pooled_sb)
+                                logger.debug("Returned healthy sandbox to pool")
+                            except asyncio.QueueFull:
+                                # Pool is full - terminate excess sandbox
+                                await self._terminate_sandbox(pooled_sb.sandbox)
+                                logger.debug("Pool full, terminated excess sandbox")
+                        except Exception as e:
+                            # Sandbox failed functional test - terminate it
+                            logger.debug(f"Sandbox failed functional test, terminating: {e}")
+                            await self._terminate_sandbox(pooled_sb.sandbox)
+                    else:
+                        # Sandbox is dead - terminate it
+                        logger.debug("Sandbox is dead, terminating instead of recycling")
+                        await self._terminate_sandbox(pooled_sb.sandbox)
+                else:
+                    # Should not recycle - terminate sandbox
+                    await self._terminate_sandbox(pooled_sb.sandbox)
+                    if not created_new:
+                        self._stats["recycled"] += 1
+                        logger.debug("Terminated sandbox (exceeded recycle criteria)")
+    
+    async def _create_sandbox(self) -> modal.Sandbox:
+        """Create a new Modal sandbox with timeout protection."""
+        try:
+            # Add timeout protection for sandbox creation
+            sandbox_creation = asyncio.get_event_loop().run_in_executor(
+                None,
+                lambda: modal.Sandbox.create(
+                    app=self.app,
+                    image=self.image,
+                    cpu=2.0,
+                    memory=1024,
+                    timeout=35
+                )
+            )
+              # Wait for sandbox creation with timeout
+            sandbox = await asyncio.wait_for(sandbox_creation, timeout=120)  # 2 minute timeout
+            logger.debug(f"Created new sandbox of type: {type(sandbox)}")
+            return sandbox
+        except asyncio.TimeoutError:
+            logger.error("Sandbox creation timed out after 2 minutes")
+            raise Exception("Sandbox creation timed out - Modal may be experiencing issues")
+        except Exception as e:
+            logger.error(f"Failed to create sandbox: {e}")
+            raise
+    
+    async def _terminate_sandbox(self, sandbox: modal.Sandbox):
+        """Safely terminate a sandbox with better error handling."""
+        try:
+            # Check if sandbox is still responsive before termination
+            if hasattr(sandbox, '_terminated') and sandbox._terminated:
+                logger.debug("Sandbox already terminated")
+                return
+                
+            # Use asyncio timeout for termination
+            await asyncio.wait_for(
+                asyncio.get_event_loop().run_in_executor(None, sandbox.terminate),
+                timeout=10.0  # 10 second timeout for termination
+            )
+            logger.debug("Terminated sandbox successfully")
+        except asyncio.TimeoutError:
+            logger.warning("Sandbox termination timed out - may be unresponsive")
+        except Exception as e:
+            # Log the error but don't fail - sandbox may already be dead
+            logger.warning(f"Failed to terminate sandbox (may already be dead): {e}")
+            # Mark sandbox as terminated to avoid repeated attempts
+            if hasattr(sandbox, '_terminated'):
+                sandbox._terminated = True
+    
+    def _should_recycle_sandbox(self, pooled_sb: PooledSandbox) -> bool:
+        """Determine if a sandbox should be recycled back to the pool."""
+        now = time.time()
+        
+        # Check age
+        if now - pooled_sb.created_at > self.max_age_seconds:
+            logger.debug("Sandbox too old, not recycling")
+            return False
+            
+        # Check usage count
+        if pooled_sb.use_count >= self.max_uses_per_sandbox:
+            logger.debug("Sandbox used too many times, not recycling")
+            return False
+            
+        # Check health (if we've checked it)
+        if pooled_sb.health == SandboxHealth.UNHEALTHY:
+            logger.debug("Sandbox unhealthy, not recycling")
+            return False
+            
+        return True
+    async def _warmup_pool(self):
+        """Background task to maintain warm sandboxes in the pool with aggressive replenishment."""
+        while self._running:
+            try:
+                current_size = self._sandbox_queue.qsize()
+                
+                # More aggressive warmup - start warming when below 90% capacity
+                warmup_threshold = max(1, int(self.pool_size * 0.9))
+                
+                if current_size < warmup_threshold:
+                    needed = self.pool_size - current_size
+                    logger.info(f"Pool size ({current_size}) below threshold ({warmup_threshold}). Warming {needed} sandboxes...")
+                    
+                    # Create new sandboxes to fill the pool - but limit concurrent creation
+                    max_concurrent = min(needed, 2)  # Don't overwhelm Modal
+                    tasks = []
+                    for _ in range(max_concurrent):
+                        task = asyncio.create_task(self._create_and_queue_sandbox())
+                        tasks.append(task)
+                    
+                    if tasks:
+                        results = await asyncio.gather(*tasks, return_exceptions=True)
+                        # Log any failures
+                        successful = 0
+                        for i, result in enumerate(results):
+                            if isinstance(result, Exception):
+                                logger.warning(f"Failed to create sandbox {i+1}/{max_concurrent}: {result}")
+                            else:
+                                successful += 1
+                        
+                        if successful > 0:
+                            logger.info(f"Successfully warmed {successful}/{max_concurrent} sandboxes")
+                
+                # Adaptive sleep interval based on pool health
+                if current_size == 0:
+                    # Critical: no sandboxes available
+                    sleep_interval = 1
+                elif current_size < warmup_threshold:
+                    # Low: need more sandboxes
+                    sleep_interval = 2
+                else:
+                    # Healthy: normal monitoring
+                    sleep_interval = 5
+                    
+                await asyncio.sleep(sleep_interval)
+                
+            except Exception as e:
+                logger.error(f"Error in warmup loop: {e}")
+                await asyncio.sleep(10)  # Wait longer on error
+    
+    async def _create_and_queue_sandbox(self):
+        """Create a sandbox and add it to the queue."""
+        start_time = time.time()
+        try:
+            # Create the sandbox
+            sandbox = await self._create_sandbox()
+            creation_time = time.time() - start_time
+            logger.info(f"Sandbox creation took {creation_time:.2f}s")
+            
+            # Proactively warm up the sandbox with core imports
+            warmup_start = time.time()
+            await self._warmup_sandbox_imports(sandbox)
+            warmup_time = time.time() - warmup_start
+            logger.info(f"Sandbox warmup with imports took {warmup_time:.2f}s")
+            
+            pooled_sb = PooledSandbox(
+                sandbox=sandbox,
+                created_at=time.time(),
+                last_used=time.time()
+            )
+            
+            try:
+                self._sandbox_queue.put_nowait(pooled_sb)
+                total_time = time.time() - start_time
+                logger.info(f"Added warm sandbox to pool (total time: {total_time:.2f}s)")
+            except asyncio.QueueFull:
+                # Pool is full, terminate this sandbox
+                await self._terminate_sandbox(sandbox)
+                
+        except Exception as e:
+            total_time = time.time() - start_time
+            logger.error(f"Failed to create and queue sandbox after {total_time:.2f}s: {e}")
+
+    async def _warmup_sandbox_imports(self, sandbox: modal.Sandbox):
+        """Warm up sandbox by importing core packages."""
+        try:
+            from mcp_hub.package_utils import get_warmup_import_commands
+            
+            # Get warmup commands
+            import_commands = get_warmup_import_commands()
+            warmup_script = "; ".join(import_commands)
+            
+            # Execute the warmup script
+            logger.debug("Running sandbox warmup imports...")
+            proc = await asyncio.get_event_loop().run_in_executor(
+                None,
+                lambda: sandbox.exec("python", "-c", warmup_script, timeout=30)
+            )
+            
+            # Check if warmup was successful
+            if hasattr(proc, 'stdout') and hasattr(proc.stdout, 'read'):
+                output = proc.stdout.read()
+                if "Core packages warmed up successfully" in output:
+                    logger.debug("Sandbox warmup imports completed successfully")
+                else:
+                    logger.warning(f"Sandbox warmup completed but output unexpected: {output}")
+            else:
+                logger.debug("Sandbox warmup imports completed")
+                
+        except Exception as e:
+            logger.warning(f"Failed to warm up sandbox imports (sandbox still usable): {e}")
+    async def _health_check_loop(self):
+        """Background task to check sandbox health and perform proactive cleanup."""
+        while self._running:
+            try:
+                # Perform regular health checks every interval
+                await asyncio.sleep(self.health_check_interval)
+                
+                # First do a quick proactive cleanup
+                cleaned = await self._proactive_cleanup()
+                
+                # Then do the full health check
+                await self._perform_health_checks()
+                
+                # If we cleaned up sandboxes, trigger warmup
+                if cleaned > 0:
+                    logger.info(f"Health check cleaned {cleaned} sandboxes, pool may need warming")
+                    
+            except Exception as e:
+                logger.error(f"Error in health check loop: {e}")
+                await asyncio.sleep(10)  # Wait longer on error
+    
+    async def _perform_health_checks(self):
+        """Perform health checks on sandboxes in the pool."""
+        # This is a simplified health check - in practice you might want
+        # to run a simple command to verify the sandbox is responsive
+        temp_sandboxes = []
+        
+        # Drain the queue to check each sandbox
+        while not self._sandbox_queue.empty():
+            try:
+                pooled_sb = self._sandbox_queue.get_nowait()
+                is_healthy = await self._check_sandbox_health(pooled_sb.sandbox)
+                pooled_sb.health = SandboxHealth.HEALTHY if is_healthy else SandboxHealth.UNHEALTHY
+                if is_healthy:
+                    temp_sandboxes.append(pooled_sb)
+                else:
+                    # TERMINATE unhealthy sandbox
+                    await self._terminate_sandbox(pooled_sb.sandbox)
+                    self._stats["recycled"] += 1
+            except asyncio.QueueEmpty:
+                break
+        
+        # Put healthy sandboxes back
+        for pooled_sb in temp_sandboxes:
+            try:
+                self._sandbox_queue.put_nowait(pooled_sb)
+            except asyncio.QueueFull:
+                await self._terminate_sandbox(pooled_sb.sandbox)
+        
+        self._stats["health_checks"] += 1
+        logger.debug(f"Health check completed. Pool size: {self._sandbox_queue.qsize()}")
+    
+    async def _check_sandbox_health(self, sandbox: modal.Sandbox) -> bool:
+        """Check if a sandbox is healthy."""
+        try:
+            # Run a simple Python command to check if the sandbox is responsive
+            proc = await asyncio.get_event_loop().run_in_executor(
+                None,
+                lambda: sandbox.exec("python", "-c", "print('health_check')", timeout=5)
+            )
+            output = proc.stdout.read()
+            return "health_check" in output
+        except Exception as e:
+            logger.debug(f"Sandbox health check failed: {e}")
+            return False
+    
+    async def _cleanup_loop(self):
+        """Background task to cleanup old sandboxes."""
+        while self._running:
+            try:
+                await asyncio.sleep(30)  # Check every 30 seconds
+                await self._cleanup_old_sandboxes()
+            except Exception as e:
+                logger.error(f"Error in cleanup loop: {e}")
+    
+    async def _cleanup_old_sandboxes(self):
+        """Remove old sandboxes from the pool."""
+        now = time.time()
+        temp_sandboxes = []
+        
+        while not self._sandbox_queue.empty():
+            try:
+                pooled_sb = self._sandbox_queue.get_nowait()
+                if now - pooled_sb.created_at < self.max_age_seconds:
+                    temp_sandboxes.append(pooled_sb)
+                else:
+                    # TERMINATE expired sandbox
+                    await self._terminate_sandbox(pooled_sb.sandbox)
+                    self._stats["recycled"] += 1
+                    logger.debug("Cleaned up old sandbox")
+            except asyncio.QueueEmpty:
+                break
+        
+        # Put non-expired sandboxes back
+        for pooled_sb in temp_sandboxes:
+            try:
+                self._sandbox_queue.put_nowait(pooled_sb)            
+            except asyncio.QueueFull:
+                await self._terminate_sandbox(pooled_sb.sandbox)
+
+    async def _is_sandbox_alive(self, sandbox: modal.Sandbox) -> bool:
+        """Check if a sandbox is alive by running a trivial command with better error handling."""
+        try:
+            # Check if sandbox was already marked as terminated
+            if hasattr(sandbox, '_terminated') and sandbox._terminated:
+                return False
+                
+            # Use a shorter timeout for liveness checks
+            proc = await asyncio.wait_for(
+                asyncio.get_event_loop().run_in_executor(
+                    None,
+                    lambda: sandbox.exec("python", "-c", "print('ping')", timeout=3)
+                ),
+                timeout=5.0  # Overall timeout
+            )
+            
+            if hasattr(proc, "stdout") and hasattr(proc.stdout, "read"):
+                out = proc.stdout.read()
+                return "ping" in out
+            else:
+                # For some Modal versions, output might be returned directly
+                out = str(proc)
+                return "ping" in out
+                
+        except asyncio.TimeoutError:
+            logger.debug("Liveness check timed out - sandbox likely dead")
+            return False
+        except Exception as e:
+            logger.debug(f"Liveness check failed: {e}")
+            # Mark sandbox as dead to avoid repeated checks
+            if hasattr(sandbox, '_terminated'):
+                sandbox._terminated = True
+            return False
+    
+    async def _emergency_pool_reset(self):
+        """Emergency reset of the pool when too many consecutive failures occur."""
+        logger.warning("Performing emergency pool reset due to consecutive failures")
+        
+        # Drain and terminate all sandboxes in the pool
+        terminated_count = 0
+        while not self._sandbox_queue.empty():
+            try:
+                pooled_sb = self._sandbox_queue.get_nowait()
+                await self._terminate_sandbox(pooled_sb.sandbox)
+                terminated_count += 1
+            except asyncio.QueueEmpty:
+                break
+        
+        logger.info(f"Emergency reset: terminated {terminated_count} sandboxes")
+        
+        # Reset failure counter
+        self._consecutive_failures = 0
+        
+        # Try to create one fresh sandbox to test if the underlying issue is resolved
+        try:
+            test_sandbox = await self._create_sandbox()
+            test_pooled = PooledSandbox(
+                sandbox=test_sandbox,
+                created_at=time.time(),
+                last_used=time.time(),
+                use_count=0
+            )            
+            self._sandbox_queue.put_nowait(test_pooled)
+            logger.info("Emergency reset successful: created test sandbox")
+        except Exception as e:
+            logger.error(f"Emergency reset failed to create test sandbox: {e}")
+            # Still reset the counter to allow retries
+            pass
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get pool statistics including health metrics."""
+        return {
+            **self._stats,
+            "pool_size": self._sandbox_queue.qsize(),
+            "target_pool_size": self.pool_size,
+            "running": self._running,
+            "consecutive_failures": self._consecutive_failures,
+            "last_successful_creation": self._last_successful_creation,
+            "time_since_last_success": time.time() - self._last_successful_creation,
+            "health_status": "healthy" if self._consecutive_failures < 3 else "degraded" if self._consecutive_failures < self._pool_reset_threshold else "critical"
+        }
+
+    async def _proactive_cleanup(self):
+        """Proactively clean up dead or unhealthy sandboxes from the pool."""
+        temp_sandboxes = []
+        cleaned_count = 0
+        
+        # Drain the queue to check each sandbox
+        while not self._sandbox_queue.empty():
+            try:
+                pooled_sb = self._sandbox_queue.get_nowait()
+                
+                # Quick health check
+                if await self._is_sandbox_alive(pooled_sb.sandbox):
+                    # Sandbox is alive - keep it
+                    temp_sandboxes.append(pooled_sb)
+                else:
+                    # Sandbox is dead - terminate it
+                    await self._terminate_sandbox(pooled_sb.sandbox)
+                    cleaned_count += 1
+                    logger.debug("Cleaned up dead sandbox during proactive cleanup")
+                    
+            except asyncio.QueueEmpty:
+                break
+        
+        # Put healthy sandboxes back
+        for pooled_sb in temp_sandboxes:
+            try:
+                self._sandbox_queue.put_nowait(pooled_sb)
+            except asyncio.QueueFull:
+                # Shouldn't happen, but terminate if it does
+                await self._terminate_sandbox(pooled_sb.sandbox)
+                cleaned_count += 1
+        
+        if cleaned_count > 0:
+            logger.info(f"Proactive cleanup removed {cleaned_count} dead sandboxes")
+            
+        return cleaned_count
+
+# Helper function for testing and debugging the sandbox pool
+async def test_sandbox_pool_health(pool: WarmSandboxPool) -> Dict[str, Any]:
+    """Test sandbox pool health and return detailed diagnostics."""
+    diagnostics: Dict[str, Any] = {
+        "timestamp": time.time(),
+        "pool_stats": pool.get_stats(),
+        "tests": {}
+    }
+    
+    logger.info("Starting sandbox pool health test...")
+    
+    # Test 1: Pool basic stats
+    stats = pool.get_stats()
+    diagnostics["tests"]["pool_stats"] = {
+        "passed": True,
+        "details": stats
+    }
+    
+    # Test 2: Try to get a sandbox
+    try:
+        async with pool.get_sandbox(timeout=10.0) as sandbox:
+            # Test 3: Try to run a simple command
+            try:
+                proc = await asyncio.get_event_loop().run_in_executor(
+                    None,
+                    lambda: sandbox.exec("python", "-c", "print('health_test_ok')", timeout=5)
+                )
+                output = proc.stdout.read() if hasattr(proc.stdout, "read") else str(proc)
+                
+                diagnostics["tests"]["sandbox_execution"] = {
+                    "passed": "health_test_ok" in output,
+                    "output": output[:200],  # First 200 chars
+                    "details": "Successfully executed test command"
+                }
+            except Exception as e:
+                diagnostics["tests"]["sandbox_execution"] = {
+                    "passed": False,
+                    "error": str(e),
+                    "details": "Failed to execute test command in sandbox"
+                }
+        
+        diagnostics["tests"]["sandbox_acquisition"] = {
+            "passed": True,
+            "details": "Successfully acquired and released sandbox"
+        }
+        
+    except Exception as e:
+        diagnostics["tests"]["sandbox_acquisition"] = {
+            "passed": False,
+            "error": str(e),
+            "details": "Failed to acquire sandbox from pool"
+        }
+        
+        diagnostics["tests"]["sandbox_execution"] = {
+            "passed": False,
+            "error": "Could not test - no sandbox available",
+            "details": "Skipped due to sandbox acquisition failure"
+        }
+    
+    # Test 4: Check pool warmup status
+    if pool._running:
+        warmup_needed = pool.pool_size - stats["pool_size"]
+        diagnostics["tests"]["pool_warmup"] = {
+            "passed": warmup_needed <= 1,  # Allow 1 sandbox to be missing
+            "details": f"Pool has {stats['pool_size']}/{pool.pool_size} sandboxes, {warmup_needed} needed"
+        }
+    else:
+        diagnostics["tests"]["pool_warmup"] = {
+            "passed": False,
+            "details": "Pool is not running"
+        }
+    
+    # Overall health assessment
+    all_tests_passed = all(test.get("passed", False) for test in diagnostics["tests"].values())
+    diagnostics["overall_health"] = "healthy" if all_tests_passed else "unhealthy"
+    
+    logger.info(f"Sandbox pool health test completed. Overall health: {diagnostics['overall_health']}")
+    return diagnostics

mcp_hub/utils.py

@@ -0,0 +1,439 @@
+"""Utility functions for the MCP Hub project."""
+
+import json
+import re
+from typing import Dict, Any, List, Optional, Union
+from openai import OpenAI, AsyncOpenAI
+from .config import api_config, model_config
+from .exceptions import APIError, ValidationError
+from .logging_config import logger
+import aiohttp
+from huggingface_hub import InferenceClient
+
+
+def create_nebius_client() -> OpenAI:
+    """Create and return a Nebius OpenAI client."""
+    return OpenAI(
+        base_url=api_config.nebius_base_url,
+        api_key=api_config.nebius_api_key,
+    )
+
+def create_async_nebius_client() -> AsyncOpenAI:
+    """Create and return an async Nebius OpenAI client."""
+    return AsyncOpenAI(
+        base_url=api_config.nebius_base_url,
+        api_key=api_config.nebius_api_key,
+    )
+
+def create_llm_client() -> Union[OpenAI, object]:
+    """Create and return an LLM client based on the configured provider."""
+    if api_config.llm_provider == "nebius":
+        return create_nebius_client()
+    elif api_config.llm_provider == "openai":
+        return OpenAI(api_key=api_config.openai_api_key)
+    elif api_config.llm_provider == "anthropic":
+        try:
+            import anthropic
+            return anthropic.Anthropic(api_key=api_config.anthropic_api_key)
+        except ImportError:
+            raise APIError("Anthropic", "anthropic package not installed. Install with: pip install anthropic")
+    elif api_config.llm_provider == "huggingface":
+        # Try different HuggingFace client configurations for better compatibility
+        try:
+            # First try with hf-inference provider (most recent approach)
+            return InferenceClient(
+                provider="hf-inference",
+                api_key=api_config.huggingface_api_key,
+            )
+        except Exception:
+            # Fallback to token-based authentication
+            return InferenceClient(
+                token=api_config.huggingface_api_key,
+            )
+    else:
+        raise APIError("Config", f"Unsupported LLM provider: {api_config.llm_provider}")
+
+def create_async_llm_client() -> Union[AsyncOpenAI, object]:
+    """Create and return an async LLM client based on the configured provider."""
+    if api_config.llm_provider == "nebius":
+        return create_async_nebius_client()
+    elif api_config.llm_provider == "openai":
+        return AsyncOpenAI(api_key=api_config.openai_api_key)
+    elif api_config.llm_provider == "anthropic":
+        try:
+            import anthropic
+            return anthropic.AsyncAnthropic(api_key=api_config.anthropic_api_key)
+        except ImportError:
+            raise APIError("Anthropic", "anthropic package not installed. Install with: pip install anthropic")
+    elif api_config.llm_provider == "huggingface":
+        # Try different HuggingFace client configurations for better compatibility
+        try:
+            # First try with hf-inference provider (most recent approach)
+            return InferenceClient(
+                provider="hf-inference",
+                api_key=api_config.huggingface_api_key,
+            )
+        except Exception:
+            # Fallback to token-based authentication
+            return InferenceClient(
+                token=api_config.huggingface_api_key,
+            )
+    else:
+        raise APIError("Config", f"Unsupported LLM provider: {api_config.llm_provider}")
+
+def validate_non_empty_string(value: str, field_name: str) -> None:
+    """Validate that a string is not empty or None."""
+    if not value or not value.strip():
+        raise ValidationError(f"{field_name} cannot be empty.")
+
+def extract_json_from_text(text: str) -> Dict[str, Any]:
+    """Extract JSON object from text that may contain markdown fences."""
+    # Remove markdown code fences if present
+    if text.startswith("```"):
+        parts = text.split("```")
+        if len(parts) >= 3:
+            text = parts[1].strip()
+        else:
+            text = text.strip("```").strip()
+    
+    # Find JSON object boundaries
+    start_idx = text.find("{")
+    end_idx = text.rfind("}")
+    
+    if start_idx == -1 or end_idx == -1 or end_idx < start_idx:
+        raise ValidationError("Failed to locate JSON object in text.")
+    
+    json_candidate = text[start_idx:end_idx + 1]
+    
+    try:
+        return json.loads(json_candidate)
+    except json.JSONDecodeError as e:
+        raise ValidationError(f"Failed to parse JSON: {str(e)}")
+
+def extract_urls_from_text(text: str) -> List[str]:
+    """Extract URLs from text using regex."""
+    url_pattern = r"(https?://[^\s]+)"
+    return re.findall(url_pattern, text)
+
+def make_nebius_completion(
+    model: str,
+    messages: List[Dict[str, str]],
+    temperature: float = 0.6,
+    response_format: Optional[Dict[str, Any]] = None
+) -> str:
+    """Make a completion request to Nebius and return the content."""
+    client = create_nebius_client()
+    
+    try:
+        kwargs = {
+            "model": model,
+            "messages": messages,
+            "temperature": temperature,
+        }
+        
+        if response_format:
+            kwargs["response_format"] = response_format
+        
+        completion = client.chat.completions.create(**kwargs)
+        return completion.choices[0].message.content.strip()
+    except Exception as e:
+        raise APIError("Nebius", str(e))
+
+async def make_async_nebius_completion(
+    model: str,
+    messages: List[Dict[str, Any]],
+    temperature: float = 0.0,
+    response_format: Optional[Dict[str, Any]] = None,
+) -> str:
+    """Make an async completion request to Nebius API."""
+    try:
+        client = create_async_nebius_client()
+        
+        kwargs = {
+            "model": model,
+            "messages": messages,
+            "temperature": temperature
+        }
+        
+        if response_format:
+            kwargs["response_format"] = response_format
+        
+        response = await client.chat.completions.create(**kwargs)
+        
+        if not response.choices:
+            raise APIError("Nebius", "No completion choices returned")
+        
+        content = response.choices[0].message.content
+        if content is None:
+            raise APIError("Nebius", "Empty response content")
+        
+        return content.strip()
+        
+    except Exception as e:
+        if isinstance(e, APIError):
+            raise
+        raise APIError("Nebius", f"API call failed: {str(e)}")
+
+def make_llm_completion(
+    model: str,
+    messages: List[Dict[str, str]], 
+    temperature: float = 0.6,
+    response_format: Optional[Dict[str, Any]] = None
+) -> str:
+    """Make a completion request using the configured LLM provider."""
+    provider = api_config.llm_provider
+    
+    try:
+        if provider == "nebius":
+            return make_nebius_completion(model, messages, temperature, response_format)
+        
+        elif provider == "openai":
+            client = create_llm_client()
+            kwargs = {
+                "model": model,
+                "messages": messages,
+                "temperature": temperature,
+            }
+            # OpenAI only supports simple response_format, not the extended Nebius format
+            if response_format and response_format.get("type") == "json_object":
+                kwargs["response_format"] = {"type": "json_object"}
+            completion = client.chat.completions.create(**kwargs)
+            return completion.choices[0].message.content.strip()
+        
+        elif provider == "anthropic":
+            client = create_llm_client()
+            # Convert OpenAI format to Anthropic format
+            anthropic_messages = []
+            system_message = None
+            
+            for msg in messages:
+                if msg["role"] == "system":
+                    system_message = msg["content"]
+                else:
+                    anthropic_messages.append({
+                        "role": msg["role"],
+                        "content": msg["content"]
+                    })
+            
+            kwargs = {
+                "model": model,
+                "messages": anthropic_messages,
+                "temperature": temperature,
+                "max_tokens": 1000,
+            }
+            if system_message:
+                kwargs["system"] = system_message
+            
+            response = client.messages.create(**kwargs)
+            return response.content[0].text.strip()
+        
+        elif provider == "huggingface":
+            # Try HuggingFace with fallback to Nebius
+            hf_error = None
+            try:
+                client = create_llm_client()
+                
+                # Try multiple HuggingFace API approaches
+                
+                # Method 1: Try chat.completions.create (OpenAI-compatible)
+                try:
+                    response = client.chat.completions.create(
+                        model=model,
+                        messages=messages,
+                        temperature=temperature,
+                        max_tokens=1000,
+                    )
+                    
+                    # Extract the response content
+                    if hasattr(response, 'choices') and response.choices:
+                        return response.choices[0].message.content.strip()
+                    else:
+                        return str(response).strip()
+                        
+                except Exception as e1:
+                    hf_error = e1
+                    
+                    # Method 2: Try chat_completion method (HuggingFace native)
+                    try:
+                        response = client.chat_completion(
+                            messages=messages,
+                            model=model,
+                            temperature=temperature,
+                            max_tokens=1000,
+                        )
+                        
+                        # Handle different response formats
+                        if hasattr(response, 'generated_text'):
+                            return response.generated_text.strip()
+                        elif isinstance(response, dict) and 'generated_text' in response:
+                            return response['generated_text'].strip()
+                        elif isinstance(response, list) and len(response) > 0:
+                            if isinstance(response[0], dict) and 'generated_text' in response[0]:
+                                return response[0]['generated_text'].strip()
+                        
+                        return str(response).strip()
+                        
+                    except Exception as e2:
+                        # Both HuggingFace methods failed
+                        hf_error = f"Method 1: {str(e1)}. Method 2: {str(e2)}"
+                        raise APIError("HuggingFace", f"All HuggingFace methods failed. {hf_error}")
+                
+            except Exception as e:
+                # HuggingFace failed, try fallback to Nebius
+                if hf_error is None:
+                    hf_error = str(e)
+                logger.warning(f"HuggingFace API failed: {hf_error}, falling back to Nebius")
+                
+                try:
+                    # Use Nebius model appropriate for the task
+                    nebius_model = model_config.get_model_for_provider("question_enhancer", "nebius")
+                    return make_nebius_completion(nebius_model, messages, temperature, response_format)
+                except Exception as nebius_error:
+                    raise APIError("HuggingFace", f"HuggingFace failed: {hf_error}. Nebius fallback also failed: {str(nebius_error)}")
+        
+        else:
+            raise APIError("Config", f"Unsupported LLM provider: {provider}")
+        
+    except Exception as e:
+        raise APIError(provider.title(), f"Completion failed: {str(e)}")
+
+
+async def make_async_llm_completion(
+    model: str,
+    messages: List[Dict[str, Any]],
+    temperature: float = 0.0,
+    response_format: Optional[Dict[str, Any]] = None,
+) -> str:
+    """Make an async completion request using the configured LLM provider."""
+    provider = api_config.llm_provider
+
+    try:
+        if provider == "nebius":
+            return await make_async_nebius_completion(model, messages, temperature, response_format)
+
+        elif provider == "openai":
+            client = create_async_llm_client()
+            kwargs = {
+                "model": model,
+                "messages": messages,
+                "temperature": temperature
+            }
+            if response_format and response_format.get("type") == "json_object":
+                kwargs["response_format"] = {"type": "json_object"}
+
+            response = await client.chat.completions.create(**kwargs)
+
+            if not response.choices:
+                raise APIError("OpenAI", "No completion choices returned")
+
+            content = response.choices[0].message.content
+            if content is None:
+                raise APIError("OpenAI", "Empty response content")
+
+            return content.strip()
+
+        elif provider == "anthropic":
+            client = create_async_llm_client()
+            anthropic_messages = []
+            system_message = None
+
+            for msg in messages:
+                if msg["role"] == "system":
+                    system_message = msg["content"]
+                else:
+                    anthropic_messages.append({
+                        "role": msg["role"],
+                        "content": msg["content"]
+                    })
+
+            kwargs = {
+                "model": model,
+                "messages": anthropic_messages,
+                "temperature": temperature,
+                "max_tokens": 1000,
+            }
+            if system_message:
+                kwargs["system"] = system_message
+
+            response = await client.messages.create(**kwargs)
+            return response.content[0].text.strip()
+
+        elif provider == "huggingface":
+            # HuggingFace doesn't support async, fallback to Nebius
+            logger.warning("HuggingFace does not support async operations, falling back to Nebius")
+            
+            try:
+                # Use Nebius model appropriate for the task
+                nebius_model = model_config.get_model_for_provider("question_enhancer", "nebius")
+                return await make_async_nebius_completion(nebius_model, messages, temperature, response_format)
+            except Exception as nebius_error:
+                raise APIError("HuggingFace", f"HuggingFace async not supported. Nebius fallback failed: {str(nebius_error)}")
+
+        else:
+            raise APIError("Config", f"Unsupported LLM provider: {provider}")
+
+    except Exception as e:
+        raise APIError(provider.title(), f"Async completion failed: {str(e)}")
+
+async def async_tavily_search(query: str, max_results: int = 3) -> Dict[str, Any]:
+    """Perform async web search using Tavily API."""
+    try:
+        async with aiohttp.ClientSession() as session:
+            url = "https://api.tavily.com/search"
+            headers = {
+                "Content-Type": "application/json"
+            }
+            data = {
+                "api_key": api_config.tavily_api_key,
+                "query": query,
+                "search_depth": "basic",
+                "max_results": max_results,
+                "include_answer": True
+            }
+            
+            async with session.post(url, headers=headers, json=data) as response:
+                if response.status != 200:
+                    raise APIError("Tavily", f"HTTP {response.status}: {await response.text()}")
+                
+                result = await response.json()
+                return {
+                    "query": result.get("query", query),
+                    "tavily_answer": result.get("answer"),
+                    "results": result.get("results", []),
+                    "data_source": "Tavily Search API",
+                }
+                
+    except aiohttp.ClientError as e:
+        raise APIError("Tavily", f"HTTP request failed: {str(e)}")
+    except Exception as e:
+        if isinstance(e, APIError):
+            raise
+        raise APIError("Tavily", f"Search failed: {str(e)}")
+
+def format_search_results(results: List[Dict[str, Any]]) -> str:
+    """Format search results into a readable string."""
+    if not results:
+        return "No search results found."
+    
+    snippets = []
+    for idx, item in enumerate(results, 1):
+        title = item.get("title", "No Title")
+        url = item.get("url", "")
+        content = item.get("content", "")
+        
+        snippet = f"Result {idx}:\nTitle: {title}\nURL: {url}\nSnippet: {content}\n"
+        snippets.append(snippet)
+    
+    return "\n".join(snippets).strip()
+
+def create_apa_citation(url: str, year: str = None) -> str:
+    """Create a simple APA-style citation from a URL."""
+    if not year:
+        year = api_config.current_year
+    
+    try:
+        domain = url.split("/")[2]
+        title = domain.replace("www.", "").split(".")[0].capitalize()
+        return f"{title}. ({year}). Retrieved from {url}"
+    except (IndexError, AttributeError):
+        return f"Unknown Source. ({year}). Retrieved from {url}"

pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "mcp-hub-project"
+version = "0.2.0"
+description = "Advanced MCP Hub with Inter-Agent Communication and Performance Monitoring"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "gradio-client>=1.10.2",
+    "gradio[mcp]>=5.33.0",
+    "modal>=1.0.2",
+    "openai>=1.84.0",
+    "tavily-python>=0.7.4",
+    "python-dotenv>=1.0.0",
+    "psutil>=5.9.0",
+    "aiohttp>=3.8.0",
+    "anthropic>=0.52.2",
+    "huggingface>=0.0.1",
+    "huggingface-hub>=0.32.4",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "black>=23.0.0",
+    "isort>=5.12.0",
+    "mypy>=1.5.0",
+]

pytest.ini

@@ -0,0 +1,11 @@
+[pytest]
+minversion = 6.0
+addopts = -ra --strict-markers --strict-config --cov=app --cov=mcp_hub --cov-report=term-missing --cov-report=html:htmlcov --cov-branch
+testpaths = tests
+markers =
+    unit: Unit tests
+    integration: Integration tests
+    async_test: Async test cases
+    slow: Slow running tests
+    requires_api: Tests that need API keys
+asyncio_mode = auto

requirements.txt

@@ -0,0 +1,11 @@
+gradio-client>=1.10.2,
+gradio[mcp]>=5.33.0,
+modal>=1.0.2
+openai>=1.84.0
+tavily-python>=0.7.4
+python-dotenv>=1.0.0
+psutil>=5.9.0
+aiohttp>=3.8.0
+anthropic>=0.52.2
+huggingface>=0.0.1
+huggingface-hub>=0.32.4

tests/__init__.py

@@ -0,0 +1 @@
+"""Test package for MCP Hub."""

tests/conftest.py

@@ -0,0 +1,142 @@
+"""Common test fixtures and configuration."""
+
+import pytest
+import asyncio
+import os
+from unittest.mock import Mock, MagicMock, patch
+from typing import Dict, Any, Generator
+
+# Mock environment variables for testing - set them globally before any imports
+TEST_ENV_VARS = {
+    "TAVILY_API_KEY": "tvly-test-key-12345",
+    "NEBIUS_API_KEY": "test-nebius-key",
+    "OPENAI_API_KEY": "test-openai-key", 
+    "ANTHROPIC_API_KEY": "test-anthropic-key",
+    "HUGGINGFACE_API_KEY": "test-hf-key",
+    "LLM_PROVIDER": "nebius"
+}
+
+# Set environment variables immediately
+for key, value in TEST_ENV_VARS.items():
+    os.environ[key] = value
+
+@pytest.fixture
+def mock_tavily_client():
+    """Mock Tavily client for web search tests."""
+    mock_client = Mock()
+    mock_client.search.return_value = {
+        "results": [
+            {
+                "title": "Test Result 1",
+                "url": "https://example.com/1",
+                "content": "Test content 1",
+                "score": 0.9
+            },
+            {
+                "title": "Test Result 2", 
+                "url": "https://example.com/2",
+                "content": "Test content 2",
+                "score": 0.8
+            }
+        ],
+        "answer": "Test search summary"
+    }
+    return mock_client
+
+@pytest.fixture
+def mock_llm_response():
+    """Mock LLM completion response."""
+    return '{"sub_questions": ["Question 1?", "Question 2?", "Question 3?"]}'
+
+@pytest.fixture
+def mock_modal_sandbox():
+    """Mock Modal sandbox for code execution tests."""
+    mock_sandbox = Mock()
+    mock_sandbox.exec.return_value = Mock(stdout="Test output", stderr="", returncode=0)
+    return mock_sandbox
+
+@pytest.fixture
+def sample_user_request():
+    """Sample user request for testing."""
+    return "Create a Python script to analyze CSV data and generate charts"
+
+@pytest.fixture
+def sample_search_results():
+    """Sample search results for testing."""
+    return [
+        {
+            "title": "Python Data Analysis Tutorial",
+            "url": "https://example.com/pandas-tutorial",
+            "content": "Learn how to analyze CSV data with pandas and matplotlib...",
+            "score": 0.95
+        },
+        {
+            "title": "Chart Generation with Python",
+            "url": "https://example.com/charts",
+            "content": "Create stunning charts and visualizations...",
+            "score": 0.87
+        }
+    ]
+
+@pytest.fixture
+def sample_code():
+    """Sample Python code for testing."""
+    return '''
+import pandas as pd
+import matplotlib.pyplot as plt
+
+# Load data
+df = pd.read_csv('data.csv')
+
+# Generate chart
+df.plot(kind='bar')
+plt.show()
+'''
+
+@pytest.fixture
+def mock_config():
+    """Mock configuration objects."""
+    api_config = Mock()
+    api_config.tavily_api_key = "tvly-test-key"
+    api_config.llm_provider = "nebius"
+    api_config.nebius_api_key = "test-nebius-key"
+    
+    model_config = Mock()
+    model_config.get_model_for_provider.return_value = "meta-llama/llama-3.1-8b-instruct"
+    
+    return api_config, model_config
+
+@pytest.fixture
+def event_loop():
+    """Create an event loop for async tests."""
+    loop = asyncio.new_event_loop()
+    yield loop
+    loop.close()
+
+class MockAgent:
+    """Base mock agent class for testing."""
+    def __init__(self, name: str):
+        self.name = name
+        self.call_count = 0
+        
+    def __call__(self, *args, **kwargs):
+        self.call_count += 1
+        return {"success": True, "agent": self.name, "calls": self.call_count}
+
+@pytest.fixture  
+def mock_agents():
+    """Mock agent instances for orchestrator testing."""
+    return {
+        "question_enhancer": MockAgent("question_enhancer"),
+        "web_search": MockAgent("web_search"),
+        "llm_processor": MockAgent("llm_processor"), 
+        "citation_formatter": MockAgent("citation_formatter"),
+        "code_generator": MockAgent("code_generator"),
+        "code_runner": MockAgent("code_runner")
+    }
+
+@pytest.fixture
+def disable_advanced_features():
+    """Disable advanced features for basic testing."""
+    with patch('app.ADVANCED_FEATURES_AVAILABLE', False):
+        yield

tests/integration/__init__.py

@@ -0,0 +1 @@
+"""Integration tests package."""

tests/unit/__init__.py

@@ -0,0 +1 @@
+"""Unit tests package."""