exonware-xwlazy 0.1.0.10__py3-none-any.whl → 0.1.0.19__py3-none-any.whl

exonware/xwlazy/runtime/facade.py

@@ -0,0 +1,95 @@
+"""
+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,173 @@
+"""
+#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
+Version: 0.1.0.19
+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,64 @@
+"""
+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,39 @@
+"""
+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.10"
+__version__ = "0.1.0.19"
 
 # Version components for programmatic access
 VERSION_MAJOR = 0
 VERSION_MINOR = 1
 VERSION_PATCH = 0
-VERSION_BUILD = 10  # Set to None for releases, or build number for dev builds
+VERSION_BUILD = 19  # Set to None for releases, or build number for dev builds
 
 # Version metadata
 VERSION_SUFFIX = ""  # e.g., "dev", "alpha", "beta", "rc1"