exonware-xwlazy 0.1.0.11__py3-none-any.whl → 0.1.0.20__py3-none-any.whl

exonware/xwlazy/runtime/base.py

@@ -0,0 +1,274 @@
+"""
+#exonware/xwlazy/src/exonware/xwlazy/runtime/base.py
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+
+Generation Date: 10-Oct-2025
+
+Abstract Base Class for Runtime Services
+
+This module defines the abstract base class for runtime services.
+"""
+
+import threading
+from abc import ABC, abstractmethod
+from typing import Dict, List, Optional, Any, Tuple
+
+from ..contracts import (
+    IRuntime,
+)
+
+# =============================================================================
+# ABSTRACT RUNTIME (Unified - Merges all runtime services)
+# =============================================================================
+
+class ARuntimeHelper(IRuntime, ABC):
+    """
+    Unified abstract base for runtime services.
+    
+    Merges functionality from all runtime service interfaces.
+    Provides runtime services for state management, learning, monitoring, and caching.
+    
+    This abstract class combines:
+    - State management (persistent state for lazy installation)
+    - Adaptive learning (learning import patterns and optimizing loading)
+    - Intelligent selection (selecting optimal modes based on load characteristics)
+    - Metrics collection (collecting and aggregating performance metrics)
+    - Performance monitoring (monitoring lazy loading performance)
+    - Multi-tier caching (L1/L2/L3 caching)
+    - Registry (managing instances by key)
+    """
+    
+    __slots__ = (
+        # From IStateManager
+        '_manual_state', '_auto_state',
+        # From IMetricsCollector
+        '_metrics',
+        # From IPerformanceMonitor
+        '_load_times', '_access_counts',
+        # From IMultiTierCache
+        '_l1_cache', '_l2_cache', '_l3_cache',
+        # From IRegistry
+        '_registry',
+        # Common
+        '_lock'
+    )
+    
+    def __init__(self):
+        """Initialize unified runtime services."""
+        # From IStateManager
+        self._manual_state: Optional[bool] = None
+        self._auto_state: Optional[bool] = None
+        
+        # From IMetricsCollector
+        self._metrics: Dict[str, List[float]] = {}
+        
+        # From IPerformanceMonitor
+        self._load_times: Dict[str, List[float]] = {}
+        self._access_counts: Dict[str, int] = {}
+        
+        # From IMultiTierCache
+        self._l1_cache: Dict[str, Any] = {}
+        self._l2_cache: Dict[str, Any] = {}
+        self._l3_cache: Dict[str, Any] = {}
+        
+        # From IRegistry
+        self._registry: Dict[str, Any] = {}
+        
+        # Common
+        self._lock = threading.RLock()
+    
+    # ========================================================================
+    # State Management Methods (from IStateManager)
+    # ========================================================================
+    
+    def get_manual_state(self) -> Optional[bool]:
+        """Get manual state override (from IStateManager)."""
+        return self._manual_state
+    
+    def set_manual_state(self, value: Optional[bool]) -> None:
+        """Set manual state override (from IStateManager)."""
+        with self._lock:
+            self._manual_state = value
+    
+    def get_cached_auto_state(self) -> Optional[bool]:
+        """Get cached auto-detected state (from IStateManager)."""
+        return self._auto_state
+    
+    def set_auto_state(self, value: Optional[bool]) -> None:
+        """Set cached auto-detected state (from IStateManager)."""
+        with self._lock:
+            self._auto_state = value
+    
+    # ========================================================================
+    # Adaptive Learning Methods (from IAdaptiveLearner)
+    # ========================================================================
+    
+    @abstractmethod
+    def record_import(self, module_name: str, import_time: float) -> None:
+        """Record an import event (from IAdaptiveLearner)."""
+        pass
+    
+    @abstractmethod
+    def predict_next_imports(self, current_module: str, count: int = 3) -> List[str]:
+        """Predict next likely imports based on patterns (from IAdaptiveLearner)."""
+        pass
+    
+    @abstractmethod
+    def get_module_score(self, module_name: str) -> float:
+        """Get priority score for a module (from IAdaptiveLearner)."""
+        pass
+    
+    # ========================================================================
+    # Intelligent Selection Methods (from IIntelligentSelector)
+    # ========================================================================
+    
+    @abstractmethod
+    def detect_load_level(
+        self,
+        module_count: int = 0,
+        total_import_time: float = 0.0,
+        import_count: int = 0,
+        memory_usage_mb: float = 0.0
+    ) -> Any:
+        """Detect current load level (from IIntelligentSelector)."""
+        pass
+    
+    @abstractmethod
+    def get_optimal_mode(self, load_level: Any) -> Tuple[Any, Any]:
+        """Get optimal mode for a load level (from IIntelligentSelector)."""
+        pass
+    
+    @abstractmethod
+    def update_mode_map(self, mode_map: Dict[Any, Tuple[Any, Any]]) -> None:
+        """Update mode mapping with benchmark results (from IIntelligentSelector)."""
+        pass
+    
+    # ========================================================================
+    # Metrics Collection Methods (from IMetricsCollector)
+    # ========================================================================
+    
+    def record_metric(self, name: str, value: float, timestamp: Optional[Any] = None) -> None:
+        """Record a metric value (from IMetricsCollector)."""
+        with self._lock:
+            if name not in self._metrics:
+                self._metrics[name] = []
+            self._metrics[name].append(value)
+    
+    @abstractmethod
+    def get_metric_stats(self, name: str) -> Dict[str, Any]:
+        """Get statistics for a metric (from IMetricsCollector)."""
+        pass
+    
+    @abstractmethod
+    def get_all_stats(self) -> Dict[str, Dict[str, Any]]:
+        """Get statistics for all metrics (from IMetricsCollector)."""
+        pass
+    
+    def clear_metrics(self) -> None:
+        """Clear all collected metrics (from IMetricsCollector)."""
+        with self._lock:
+            self._metrics.clear()
+    
+    # ========================================================================
+    # Performance Monitoring Methods (from IPerformanceMonitor)
+    # ========================================================================
+    
+    def record_load_time(self, module: str, load_time: float) -> None:
+        """Record module load time (from IPerformanceMonitor)."""
+        with self._lock:
+            if module not in self._load_times:
+                self._load_times[module] = []
+            self._load_times[module].append(load_time)
+    
+    def record_access(self, module: str) -> None:
+        """Record module access (from IPerformanceMonitor)."""
+        with self._lock:
+            self._access_counts[module] = self._access_counts.get(module, 0) + 1
+    
+    @abstractmethod
+    def get_performance_stats(self) -> Dict[str, Any]:
+        """Get performance statistics (from IPerformanceMonitor)."""
+        pass
+    
+    # ========================================================================
+    # Multi-Tier Cache Methods (from IMultiTierCache)
+    # ========================================================================
+    
+    def get_multi_tier_cached(self, key: str) -> Optional[Any]:
+        """Get value from cache (L1 -> L2 -> L3) (from IMultiTierCache)."""
+        with self._lock:
+            # Check L1 first
+            if key in self._l1_cache:
+                return self._l1_cache[key]
+            # Check L2
+            if key in self._l2_cache:
+                value = self._l2_cache[key]
+                # Promote to L1
+                self._l1_cache[key] = value
+                return value
+            # Check L3
+            if key in self._l3_cache:
+                value = self._l3_cache[key]
+                # Promote to L2
+                self._l2_cache[key] = value
+                return value
+            return None
+    
+    def set_multi_tier_cached(self, key: str, value: Any) -> None:
+        """Set value in cache (L1 and L2) (from IMultiTierCache)."""
+        with self._lock:
+            self._l1_cache[key] = value
+            self._l2_cache[key] = value
+    
+    def clear_multi_tier_cache(self) -> None:
+        """Clear all cache tiers (from IMultiTierCache)."""
+        with self._lock:
+            self._l1_cache.clear()
+            self._l2_cache.clear()
+            self._l3_cache.clear()
+    
+    @abstractmethod
+    def shutdown_multi_tier_cache(self) -> None:
+        """Shutdown cache (flush L2, cleanup threads) (from IMultiTierCache)."""
+        pass
+    
+    # Alias method for backward compatibility
+    def shutdown_cache(self) -> None:
+        """Alias for shutdown_multi_tier_cache (backward compatibility)."""
+        self.shutdown_multi_tier_cache()
+    
+    # ========================================================================
+    # Registry Methods (from IRegistry)
+    # ========================================================================
+    
+    def get_instance(self, key: str) -> Any:
+        """Get instance by key (from IRegistry)."""
+        with self._lock:
+            return self._registry.get(key)
+    
+    def register(self, key: str, instance: Any) -> None:
+        """Register an instance (from IRegistry)."""
+        with self._lock:
+            self._registry[key] = instance
+    
+    def unregister(self, key: str) -> None:
+        """Unregister an instance (from IRegistry)."""
+        with self._lock:
+            self._registry.pop(key, None)
+    
+    def has_key(self, key: str) -> bool:
+        """Check if key is registered (from IRegistry)."""
+        with self._lock:
+            return key in self._registry
+
+# =============================================================================
+# EXPORT ALL
+# =============================================================================
+
+__all__ = [
+    'ARuntimeHelper',
+]
+

exonware/xwlazy/runtime/facade.py

@@ -0,0 +1,94 @@
+"""
+Runtime Services Facade
+
+Main facade: XWRuntimeHelper extends ARuntimeHelper
+Provides concrete implementation for all runtime services.
+"""
+
+from typing import Dict, List, Optional, Tuple, Any
+from .base import ARuntimeHelper
+from ..defs import LazyLoadMode, LazyInstallMode
+
+class XWRuntimeHelper(ARuntimeHelper):
+    """
+    Concrete implementation of ARuntimeHelper.
+    
+    Provides runtime services for state management, learning, monitoring, and caching.
+    """
+    
+    def __init__(self):
+        """Initialize XW runtime services."""
+        super().__init__()
+    
+    # Abstract methods from ARuntime that need implementation
+    def record_import(self, module_name: str, import_time: float) -> None:
+        """Record an import event."""
+        # TODO: Implement import recording
+        pass
+    
+    def predict_next_imports(self, current_module: str, count: int = 3) -> List[str]:
+        """Predict next likely imports based on patterns."""
+        # TODO: Implement prediction logic
+        return []
+    
+    def get_module_score(self, module_name: str) -> float:
+        """Get priority score for a module."""
+        # TODO: Implement scoring logic
+        return 0.0
+    
+    def detect_load_level(
+        self,
+        module_count: int = 0,
+        total_import_time: float = 0.0,
+        import_count: int = 0,
+        memory_usage_mb: float = 0.0
+    ):
+        """Detect current load level."""
+        # TODO: Implement load level detection
+        from .intelligent_selector import LoadLevel
+        return LoadLevel.LIGHT
+    
+    def get_optimal_mode(self, load_level) -> Tuple[LazyLoadMode, LazyInstallMode]:
+        """Get optimal mode for a load level."""
+        # TODO: Implement mode selection
+        return LazyLoadMode.AUTO, LazyInstallMode.SMART
+    
+    def update_mode_map(self, mode_map: Dict[Any, Tuple[LazyLoadMode, LazyInstallMode]]) -> None:
+        """Update mode mapping with benchmark results."""
+        # TODO: Implement mode map update
+        pass
+    
+    def get_metric_stats(self, name: str) -> Dict[str, Any]:
+        """Get statistics for a metric."""
+        with self._lock:
+            values = self._metrics.get(name, [])
+            if not values:
+                return {'count': 0, 'total': 0.0, 'average': 0.0, 'min': 0.0, 'max': 0.0}
+            return {
+                'count': len(values),
+                'total': sum(values),
+                'average': sum(values) / len(values),
+                'min': min(values),
+                'max': max(values)
+            }
+    
+    def get_all_stats(self) -> Dict[str, Dict[str, Any]]:
+        """Get statistics for all metrics."""
+        with self._lock:
+            return {name: self.get_metric_stats(name) for name in self._metrics.keys()}
+    
+    def get_performance_stats(self) -> Dict[str, Any]:
+        """Get performance statistics."""
+        with self._lock:
+            return {
+                'load_times': {k: {'count': len(v), 'total': sum(v), 'average': sum(v) / len(v) if v else 0.0} 
+                              for k, v in self._load_times.items()},
+                'access_counts': self._access_counts.copy(),
+                'memory_usage': 0.0  # TODO: Implement memory usage tracking
+            }
+    
+    def shutdown_multi_tier_cache(self) -> None:
+        """Shutdown cache (flush L2, cleanup threads)."""
+        # TODO: Implement cache shutdown
+        pass
+

exonware/xwlazy/runtime/intelligent_selector.py

@@ -0,0 +1,170 @@
+"""
+#exonware/xwlazy/src/exonware/xwlazy/loading/intelligent_utils.py
+
+Intelligent mode utilities for automatic mode switching.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+
+Generation Date: 19-Nov-2025
+
+This module provides intelligent mode switching based on load level.
+"""
+
+from typing import Dict, Tuple, Optional
+
+from ..defs import LazyLoadMode, LazyInstallMode, LoadLevel
+
+# Lazy import to avoid circular dependency
+logger = None
+
+def _get_logger():
+    """Get logger (lazy import to avoid circular dependency)."""
+    global logger
+    if logger is None:
+        from ..common.logger import get_logger
+        logger = get_logger("xwlazy.loading.intelligent")
+    return logger
+
+# Optimal mode mappings based on benchmark results (updated from consistency test)
+# Format: {LoadLevel: (LazyLoadMode, LazyInstallMode)}
+# Updated: 2025-11-19 - Based on 20-iteration consistency test averages
+# Light: ultra+full (0.568ms avg), Medium: hyperparallel+full (5.134ms avg)
+# Heavy: preload+size_aware (18.475ms avg), Enterprise: preload+full (44.742ms avg)
+INTELLIGENT_MODE_MAP: Dict[LoadLevel, Tuple[LazyLoadMode, LazyInstallMode]] = {
+    LoadLevel.LIGHT: (LazyLoadMode.ULTRA, LazyInstallMode.FULL),  # Winner: 0.568ms avg (±26.1% CV)
+    LoadLevel.MEDIUM: (LazyLoadMode.HYPERPARALLEL, LazyInstallMode.FULL),  # Winner: 5.134ms avg (±4.7% CV)
+    LoadLevel.HEAVY: (LazyLoadMode.PRELOAD, LazyInstallMode.SIZE_AWARE),  # Winner: 18.475ms avg (±10.2% CV)
+    LoadLevel.ENTERPRISE: (LazyLoadMode.PRELOAD, LazyInstallMode.FULL),  # Winner: 44.742ms avg (±1.5% CV)
+}
+
+class IntelligentModeSelector:
+    """Selects optimal mode based on current load characteristics."""
+    
+    def __init__(self, mode_map: Optional[Dict[LoadLevel, Tuple[LazyLoadMode, LazyInstallMode]]] = None):
+        """
+        Initialize intelligent mode selector.
+        
+        Args:
+            mode_map: Custom mode mapping (defaults to INTELLIGENT_MODE_MAP)
+        """
+        self._mode_map = mode_map or INTELLIGENT_MODE_MAP.copy()
+        self._current_load_level: Optional[LoadLevel] = None
+        self._module_count = 0
+        self._total_import_time = 0.0
+        self._import_count = 0
+    
+    def update_mode_map(self, mode_map: Dict[LoadLevel, Tuple[LazyLoadMode, LazyInstallMode]]) -> None:
+        """Update the mode mapping with benchmark results."""
+        self._mode_map = mode_map.copy()
+        _get_logger().info(f"Updated INTELLIGENT mode mapping: {mode_map}")
+    
+    def detect_load_level(
+        self,
+        module_count: int = 0,
+        total_import_time: float = 0.0,
+        import_count: int = 0,
+        memory_usage_mb: float = 0.0
+    ) -> LoadLevel:
+        """
+        Detect current load level based on system characteristics.
+        
+        Args:
+            module_count: Number of modules loaded
+            total_import_time: Total time spent on imports (seconds)
+            import_count: Number of imports performed
+            memory_usage_mb: Current memory usage in MB
+            
+        Returns:
+            Detected LoadLevel
+        """
+        # Update internal state
+        self._module_count = module_count
+        self._total_import_time = total_import_time
+        self._import_count = import_count
+        
+        # Simple heuristics based on module count and import patterns
+        # These thresholds can be tuned based on actual usage patterns
+        
+        if import_count == 0:
+            # Initial state - default to light
+            self._current_load_level = LoadLevel.LIGHT
+        elif module_count < 5 and import_count < 10:
+            # Light load: few modules, few imports
+            self._current_load_level = LoadLevel.LIGHT
+        elif module_count < 20 and import_count < 50:
+            # Medium load: moderate number of modules/imports
+            self._current_load_level = LoadLevel.MEDIUM
+        elif module_count < 100 and import_count < 200:
+            # Heavy load: many modules, many imports
+            self._current_load_level = LoadLevel.HEAVY
+        else:
+            # Enterprise load: very large scale
+            self._current_load_level = LoadLevel.ENTERPRISE
+        
+        # Override based on memory usage if significant
+        if memory_usage_mb > 300:
+            self._current_load_level = LoadLevel.ENTERPRISE
+        elif memory_usage_mb > 150:
+            self._current_load_level = LoadLevel.HEAVY
+        
+        return self._current_load_level
+    
+    def get_optimal_mode(self, load_level: Optional[LoadLevel] = None) -> Tuple[LazyLoadMode, LazyInstallMode]:
+        """
+        Get optimal mode combination for given load level.
+        
+        Args:
+            load_level: Load level (if None, uses detected level)
+            
+        Returns:
+            Tuple of (LazyLoadMode, LazyInstallMode)
+        """
+        if load_level is None:
+            load_level = self._current_load_level or LoadLevel.LIGHT
+        
+        optimal = self._mode_map.get(load_level)
+        if optimal is None:
+            # Fallback to default
+            _get_logger().warning(f"No optimal mode found for {load_level}, using default")
+            optimal = (LazyLoadMode.AUTO, LazyInstallMode.SMART)
+        
+        return optimal
+    
+    def should_switch_mode(
+        self,
+        current_mode: Tuple[LazyLoadMode, LazyInstallMode],
+        detected_level: LoadLevel
+    ) -> bool:
+        """
+        Determine if mode should be switched based on detected load level.
+        
+        Args:
+            current_mode: Current (load_mode, install_mode) tuple
+            detected_level: Detected load level
+            
+        Returns:
+            True if mode should be switched
+        """
+        optimal_mode = self.get_optimal_mode(detected_level)
+        return current_mode != optimal_mode
+    
+    def get_stats(self) -> Dict:
+        """Get intelligent mode statistics."""
+        return {
+            'current_load_level': self._current_load_level.value if self._current_load_level else None,
+            'module_count': self._module_count,
+            'import_count': self._import_count,
+            'total_import_time': self._total_import_time,
+            'mode_map': {
+                level.value: {
+                    'load_mode': mode[0].value,
+                    'install_mode': mode[1].value
+                }
+                for level, mode in self._mode_map.items()
+            }
+        }
+
+__all__ = ['LoadLevel', 'INTELLIGENT_MODE_MAP', 'IntelligentModeSelector']
+

exonware/xwlazy/runtime/metrics.py

@@ -0,0 +1,60 @@
+"""
+Performance metrics tracking for lazy loading system.
+
+This module provides utilities for tracking and aggregating performance metrics.
+"""
+
+from typing import Dict, Any, List, Optional
+from datetime import datetime
+from collections import defaultdict
+
+class MetricsCollector:
+    """Collects and aggregates performance metrics."""
+    
+    def __init__(self):
+        """Initialize metrics collector."""
+        self._metrics: Dict[str, List[float]] = defaultdict(list)
+        self._counts: Dict[str, int] = defaultdict(int)
+        self._timestamps: Dict[str, List[datetime]] = defaultdict(list)
+    
+    def record_metric(self, name: str, value: float, timestamp: Optional[datetime] = None) -> None:
+        """Record a metric value."""
+        self._metrics[name].append(value)
+        self._counts[name] += 1
+        if timestamp is None:
+            timestamp = datetime.now()
+        self._timestamps[name].append(timestamp)
+    
+    def get_metric_stats(self, name: str) -> Dict[str, Any]:
+        """Get statistics for a specific metric."""
+        values = self._metrics.get(name, [])
+        if not values:
+            return {}
+        
+        return {
+            'count': len(values),
+            'total': sum(values),
+            'average': sum(values) / len(values),
+            'min': min(values),
+            'max': max(values),
+        }
+    
+    def get_all_stats(self) -> Dict[str, Dict[str, Any]]:
+        """Get statistics for all metrics."""
+        return {name: self.get_metric_stats(name) for name in self._metrics.keys()}
+    
+    def clear(self) -> None:
+        """Clear all collected metrics."""
+        self._metrics.clear()
+        self._counts.clear()
+        self._timestamps.clear()
+
+# Global metrics collector instance
+_global_metrics = MetricsCollector()
+
+def get_metrics_collector() -> MetricsCollector:
+    """Get the global metrics collector instance."""
+    return _global_metrics
+
+__all__ = ['MetricsCollector', 'get_metrics_collector']
+

exonware/xwlazy/runtime/performance.py

@@ -0,0 +1,37 @@
+"""
+Performance monitoring for lazy loading system.
+
+This module contains LazyPerformanceMonitor extracted from lazy_core.py Section 4.
+"""
+
+from typing import Dict, Any
+
+class LazyPerformanceMonitor:
+    """Performance monitor for lazy loading operations."""
+    
+    __slots__ = ('_load_times', '_access_counts', '_memory_usage')
+    
+    def __init__(self):
+        """Initialize performance monitor."""
+        self._load_times: Dict[str, float] = {}
+        self._access_counts: Dict[str, int] = {}
+        self._memory_usage: Dict[str, Any] = {}
+    
+    def record_load_time(self, module: str, load_time: float) -> None:
+        """Record module load time."""
+        self._load_times[module] = load_time
+    
+    def record_access(self, module: str) -> None:
+        """Record module access."""
+        self._access_counts[module] = self._access_counts.get(module, 0) + 1
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get performance statistics."""
+        return {
+            'load_times': self._load_times.copy(),
+            'access_counts': self._access_counts.copy(),
+            'memory_usage': self._memory_usage.copy()
+        }
+
+__all__ = ['LazyPerformanceMonitor']
+

exonware/xwlazy/version.py

@@ -14,13 +14,13 @@ All version references should import from this module to ensure consistency.
 # =============================================================================
 
 # Main version - update this to change version across entire project
-__version__ = "0.1.0.16"
+__version__ = "0.1.0.20"
 
 # Version components for programmatic access
 VERSION_MAJOR = 0
 VERSION_MINOR = 1
 VERSION_PATCH = 0
-VERSION_BUILD = 16  # Set to None for releases, or build number for dev builds
+VERSION_BUILD = 20  # Set to None for releases, or build number for dev builds
 
 # Version metadata
 VERSION_SUFFIX = ""  # e.g., "dev", "alpha", "beta", "rc1"