moai-adk 0.34.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-workflow-testing/modules/performance-optimization/optimization-plan.md

@@ -0,0 +1,315 @@
+# Optimization Planning
+
+> Module: Comprehensive optimization plan generation
+> Complexity: Advanced
+> Time: 15+ minutes
+> Dependencies: asyncio
+
+## Core Implementation
+
+### Optimization Planning System
+
+```python
+from typing import Dict, List
+from dataclasses import dataclass
+import re
+from collections import defaultdict
+
+@dataclass
+class OptimizationPlan:
+    """Comprehensive optimization plan with prioritized actions."""
+    bottlenecks: List[PerformanceBottleneck]
+    execution_order: List[int]
+    estimated_total_improvement: str
+    implementation_complexity: str
+    risk_level: str
+    prerequisites: List[str]
+    validation_strategy: str
+
+class OptimizationPlanner:
+    """Create comprehensive optimization plans."""
+
+    def __init__(self, detector):
+        self.detector = detector
+
+    async def create_optimization_plan(
+        self, bottlenecks: List[PerformanceBottleneck],
+        context7_patterns: Dict[str, Any] = None
+    ) -> OptimizationPlan:
+        """Create comprehensive optimization plan."""
+
+        # Prioritize bottlenecks by impact and severity
+        prioritized_bottlenecks = self._prioritize_bottlenecks(bottlenecks)
+
+        # Create execution order
+        execution_order = self._create_optimization_execution_order(prioritized_bottlenecks)
+
+        # Estimate total improvement
+        total_improvement = self._estimate_total_improvement(prioritized_bottlenecks)
+
+        # Assess implementation complexity
+        complexity = self._assess_implementation_complexity(prioritized_bottlenecks)
+
+        # Assess risk level
+        risk_level = self._assess_optimization_risk(prioritized_bottlenecks)
+
+        # Identify prerequisites
+        prerequisites = self._identify_optimization_prerequisites(prioritized_bottlenecks)
+
+        # Create validation strategy
+        validation_strategy = self._create_validation_strategy(prioritized_bottlenecks)
+
+        return OptimizationPlan(
+            bottlenecks=prioritized_bottlenecks,
+            execution_order=execution_order,
+            estimated_total_improvement=total_improvement,
+            implementation_complexity=complexity,
+            risk_level=risk_level,
+            prerequisites=prerequisites,
+            validation_strategy=validation_strategy
+        )
+
+    def _prioritize_bottlenecks(
+        self, bottlenecks: List[PerformanceBottleneck]
+    ) -> List[PerformanceBottleneck]:
+        """Prioritize bottlenecks by impact and implementation complexity."""
+
+        # Sort by severity, impact score, and optimization type
+        severity_order = {'critical': 4, 'high': 3, 'medium': 2, 'low': 1}
+
+        return sorted(
+            bottlenecks,
+            key=lambda x: (
+                severity_order.get(x.severity, 0),
+                x.impact_score,
+                self._get_optimization_priority(x.optimization_type)
+            ),
+            reverse=True
+        )
+
+    def _get_optimization_priority(self, opt_type: OptimizationType) -> int:
+        """Get priority weight for optimization type."""
+        priorities = {
+            OptimizationType.ALGORITHM_IMPROVEMENT: 4,
+            OptimizationType.CACHING: 3,
+            OptimizationType.CONCURRENCY: 3,
+            OptimizationType.MEMORY_OPTIMIZATION: 2,
+            OptimizationType.DATA_STRUCTURE_CHANGE: 2,
+            OptimizationType.I_O_OPTIMIZATION: 2,
+            OptimizationType.DATABASE_OPTIMIZATION: 1
+        }
+        return priorities.get(opt_type, 1)
+
+    def _create_optimization_execution_order(
+        self, bottlenecks: List[PerformanceBottleneck]
+    ) -> List[int]:
+        """Create optimal execution order for optimizations."""
+
+        # Group by optimization type
+        type_groups = defaultdict(list)
+        for i, bottleneck in enumerate(bottlenecks):
+            type_groups[bottleneck.optimization_type].append(i)
+
+        # Define execution order by type
+        execution_order = []
+        type_order = [
+            OptimizationType.ALGORITHM_IMPROVEMENT,
+            OptimizationType.DATA_STRUCTURE_CHANGE,
+            OptimizationType.CACHING,
+            OptimizationType.MEMORY_OPTIMIZATION,
+            OptimizationType.CONCURRENCY,
+            OptimizationType.I_O_OPTIMIZATION,
+            OptimizationType.DATABASE_OPTIMIZATION
+        ]
+
+        for opt_type in type_order:
+            if opt_type in type_groups:
+                execution_order.extend(type_groups[opt_type])
+
+        return execution_order
+
+    def _estimate_total_improvement(
+        self, bottlenecks: List[PerformanceBottleneck]
+    ) -> str:
+        """Estimate total performance improvement."""
+
+        if not bottlenecks:
+            return "No significant improvement expected"
+
+        # Calculate weighted improvement
+        total_weighted_improvement = 0
+        total_weight = 0
+
+        for bottleneck in bottlenecks:
+            # Extract improvement percentage from description
+            improvement_range = self._parse_improvement_estimate(bottleneck.estimated_improvement)
+            if improvement_range:
+                avg_improvement = (improvement_range[0] + improvement_range[1]) / 2
+                weight = bottleneck.impact_score
+                total_weighted_improvement += avg_improvement * weight
+                total_weight += weight
+
+        if total_weight > 0:
+            avg_improvement = total_weighted_improvement / total_weight
+            return f"{avg_improvement:.0f}% average performance improvement"
+
+        return "Performance improvement depends on implementation"
+
+    def _parse_improvement_estimate(self, estimate: str) -> tuple:
+        """Parse improvement percentage from estimate string."""
+
+        # Look for percentage ranges like "20-50%" or "30%"
+        match = re.search(r'(\d+)-?(\d+)?%', estimate)
+        if match:
+            start = int(match.group(1))
+            end = int(match.group(2)) if match.group(2) else start
+            return (start, end)
+
+        return None
+
+    def _assess_implementation_complexity(
+        self, bottlenecks: List[PerformanceBottleneck]
+    ) -> str:
+        """Assess overall implementation complexity."""
+
+        complexity_scores = {
+            OptimizationType.ALGORITHM_IMPROVEMENT: 3,
+            OptimizationType.DATA_STRUCTURE_CHANGE: 3,
+            OptimizationType.CONCURRENCY: 4,
+            OptimizationType.DATABASE_OPTIMIZATION: 3,
+            OptimizationType.CACHING: 2,
+            OptimizationType.MEMORY_OPTIMIZATION: 2,
+            OptimizationType.I_O_OPTIMIZATION: 2
+        }
+
+        if not bottlenecks:
+            return "low"
+
+        avg_complexity = sum(
+            complexity_scores.get(b.optimization_type, 2) * b.impact_score
+            for b in bottlenecks
+        ) / sum(b.impact_score for b in bottlenecks)
+
+        if avg_complexity > 3.5:
+            return "high"
+        elif avg_complexity > 2.5:
+            return "medium"
+        else:
+            return "low"
+
+    def _assess_optimization_risk(
+        self, bottlenecks: List[PerformanceBottleneck]
+    ) -> str:
+        """Assess risk level of optimizations."""
+
+        high_risk_types = {
+            OptimizationType.ALGORITHM_IMPROVEMENT,
+            OptimizationType.DATA_STRUCTURE_CHANGE,
+            OptimizationType.CONCURRENCY
+        }
+
+        high_risk_count = sum(
+            1 for b in bottlenecks
+            if b.optimization_type in high_risk_types and b.impact_score > 0.3
+        )
+
+        if high_risk_count > 3:
+            return "high"
+        elif high_risk_count > 1:
+            return "medium"
+        else:
+            return "low"
+
+    def _identify_optimization_prerequisites(
+        self, bottlenecks: List[PerformanceBottleneck]
+    ) -> List[str]:
+        """Identify prerequisites for safe optimization."""
+
+        prerequisites = [
+            "Create comprehensive performance benchmarks",
+            "Ensure version control with current implementation",
+            "Set up performance testing environment"
+        ]
+
+        # Add specific prerequisites based on bottleneck types
+        optimization_types = set(b.optimization_type for b in bottlenecks)
+
+        if OptimizationType.CONCURRENCY in optimization_types:
+            prerequisites.extend([
+                "Review thread safety and shared resource access",
+                "Implement proper synchronization mechanisms"
+            ])
+
+        if OptimizationType.DATABASE_OPTIMIZATION in optimization_types:
+            prerequisites.extend([
+                "Create database backup before optimization",
+                "Set up database performance monitoring"
+            ])
+
+        if OptimizationType.ALGORITHM_IMPROVEMENT in optimization_types:
+            prerequisites.extend([
+                "Verify algorithm correctness with test suite",
+                "Compare against known reference implementations"
+            ])
+
+        return prerequisites
+
+    def _create_validation_strategy(
+        self, bottlenecks: List[PerformanceBottleneck]
+    ) -> str:
+        """Create validation strategy for optimizations."""
+
+        strategy = """
+Validation Strategy:
+1. Baseline Performance Measurement
+   - Record current performance metrics
+   - Establish performance regression thresholds
+
+2. Incremental Testing
+   - Apply optimizations one at a time
+   - Measure performance impact after each change
+
+3. Automated Performance Testing
+   - Implement performance regression tests
+   - Set up continuous performance monitoring
+
+4. Functional Validation
+   - Run complete test suite after each optimization
+   - Verify no functional regressions introduced
+
+5. Production Monitoring
+   - Monitor performance in staging environment
+   - Gradual rollout with performance validation
+"""
+
+        return strategy
+```
+
+## Usage Examples
+
+```python
+# Create optimization plan
+planner = OptimizationPlanner(detector)
+optimization_plan = await planner.create_optimization_plan(bottlenecks)
+
+print(f"\nOptimization Plan:")
+print(f"  Estimated improvement: {optimization_plan.estimated_total_improvement}")
+print(f"  Implementation complexity: {optimization_plan.implementation_complexity}")
+print(f"  Risk level: {optimization_plan.risk_level}")
+print(f"  Prerequisites: {len(optimization_plan.prerequisites)} items")
+print(f"  Execution order: {optimization_plan.execution_order}")
+print(f"\nValidation Strategy:")
+print(optimization_plan.validation_strategy)
+```
+
+## Best Practices
+
+1. **Prioritization**: Address high-impact, low-complexity optimizations first
+2. **Risk Assessment**: Understand and mitigate optimization risks
+3. **Incremental Approach**: Apply optimizations one at a time
+4. **Baseline Measurement**: Establish performance baselines before optimization
+5. **Validation Strategy**: Comprehensive testing prevents regressions
+
+---
+
+Related: [Bottleneck Detection](./bottleneck-detection.md) | [AI-Powered Optimization](./ai-optimization.md)

moai_adk/templates/.claude/skills/moai-workflow-testing/modules/performance-optimization/profiler-core.md

@@ -0,0 +1,277 @@
+# Performance Profiler Core
+
+> Module: CPU, memory, and line profiling with analysis
+> Complexity: Advanced
+> Time: 20+ minutes
+> Dependencies: cProfile, memory_profiler, line_profiler, tracemalloc
+
+## Core Implementation
+
+### PerformanceProfiler Class
+
+```python
+import cProfile
+import pstats
+import io
+from typing import Dict, List, Any, Optional
+from dataclasses import dataclass, field
+from enum import Enum
+import memory_profiler
+import line_profiler
+import tracemalloc
+from collections import defaultdict
+
+class PerformanceMetric(Enum):
+    """Types of performance metrics to track."""
+    CPU_TIME = "cpu_time"
+    WALL_TIME = "wall_time"
+    MEMORY_USAGE = "memory_usage"
+    MEMORY_PEAK = "memory_peak"
+    FUNCTION_CALLS = "function_calls"
+    EXECUTION_COUNT = "execution_count"
+    AVERAGE_TIME = "average_time"
+    MAX_TIME = "max_time"
+    MIN_TIME = "min_time"
+
+@dataclass
+class FunctionProfile:
+    """Detailed profile information for a function."""
+    name: str
+    file_path: str
+    line_number: int
+    total_time: float
+    cumulative_time: float
+    call_count: int
+    per_call_time: float
+    cummulative_per_call_time: float
+    memory_before: float
+    memory_after: float
+    memory_delta: float
+    optimization_suggestions: List[str] = field(default_factory=list)
+
+class PerformanceProfiler:
+    """Advanced performance profiler with bottleneck detection."""
+
+    def __init__(self, context7_client=None):
+        self.context7 = context7_client
+        self.profiler = None
+        self.memory_profiler = None
+        self.line_profiler = None
+        self.realtime_monitor = None
+        self.profiles = {}
+        self.bottlenecks = []
+
+    def start_profiling(self, profile_types: List[str] = None):
+        """Start performance profiling with specified types."""
+        if profile_types is None:
+            profile_types = ['cpu', 'memory']
+
+        # Start CPU profiling
+        if 'cpu' in profile_types:
+            self.profiler = cProfile.Profile()
+            self.profiler.enable()
+
+        # Start memory profiling
+        if 'memory' in profile_types:
+            tracemalloc.start()
+            self.memory_profiler = memory_profiler.Profile()
+
+        # Start line profiling for specific functions
+        if 'line' in profile_types:
+            self.line_profiler = line_profiler.LineProfiler()
+            self.line_profiler.enable_by_count()
+
+    def stop_profiling(self) -> Dict[str, Any]:
+        """Stop profiling and collect results."""
+        results = {}
+
+        # Stop CPU profiling
+        if self.profiler:
+            self.profiler.disable()
+            results['cpu_profile'] = self._analyze_cpu_profile()
+
+        # Stop memory profiling
+        if tracemalloc.is_tracing():
+            current, peak = tracemalloc.get_traced_memory()
+            tracemalloc.stop()
+            results['memory_profile'] = {
+                'current_mb': current / 1024 / 1024,
+                'peak_mb': peak / 1024 / 1024
+            }
+
+        if self.memory_profiler:
+            self.memory_profiler.disable()
+            results['memory_line_profile'] = self._analyze_memory_profile()
+
+        # Stop line profiling
+        if self.line_profiler:
+            self.line_profiler.disable()
+            results['line_profile'] = self._analyze_line_profile()
+
+        return results
+
+    def _analyze_cpu_profile(self) -> List[FunctionProfile]:
+        """Analyze CPU profiling results."""
+        if not self.profiler:
+            return []
+
+        # Create stats object
+        s = io.StringIO()
+        ps = pstats.Stats(self.profiler, stream=s)
+        ps.sort_stats('cumulative')
+        ps.print_stats()
+
+        # Parse the stats
+        function_profiles = []
+        lines = s.getvalue().split('\n')
+
+        # Skip header lines
+        for line in lines[6:]:
+            if line.strip() and not line.startswith('ncalls'):
+                try:
+                    parts = line.split()
+                    if len(parts) >= 6:
+                        ncalls = parts[0]
+                        tottime = float(parts[1])
+                        cumtime = float(parts[3])
+
+                        # Extract function name and location
+                        filename_func = ' '.join(parts[5:])
+                        if '{' in filename_func:
+                            filename, line_num, func_name = self._parse_function_line(filename_func)
+                        else:
+                            continue
+
+                        # Convert ncalls to integer (handle format like "1000/1000")
+                        if '/' in ncalls:
+                            ncalls = int(ncalls.split('/')[0])
+                        else:
+                            ncalls = int(ncalls)
+
+                        profile = FunctionProfile(
+                            name=func_name,
+                            file_path=filename,
+                            line_number=int(line_num),
+                            total_time=tottime,
+                            cumulative_time=cumtime,
+                            call_count=ncalls,
+                            per_call_time=tottime / max(ncalls, 1),
+                            cummulative_per_call_time=cumtime / max(ncalls, 1),
+                            memory_before=0.0,  # Will be filled by memory profiler
+                            memory_after=0.0,
+                            memory_delta=0.0
+                        )
+                        function_profiles.append(profile)
+
+                except (ValueError, IndexError) as e:
+                    continue
+
+        return function_profiles
+
+    def _parse_function_line(self, line: str) -> tuple:
+        """Parse function line from pstats output."""
+        # Format: "filename(line_number)function_name"
+        try:
+            paren_idx = line.rfind('(')
+            if paren_idx == -1:
+                return line, "0", "unknown"
+
+            filename = line[:paren_idx]
+            rest = line[paren_idx:]
+
+            closing_idx = rest.find(')')
+            if closing_idx == -1:
+                return filename, "0", "unknown"
+
+            line_num = rest[1:closing_idx]
+            func_name = rest[closing_idx + 1:]
+
+            return filename, line_num, func_name
+        except Exception:
+            return line, "0", "unknown"
+
+    def _analyze_memory_profile(self) -> Dict[str, Any]:
+        """Analyze memory profiling results."""
+        if not self.memory_profiler:
+            return {}
+
+        # Get memory profile statistics
+        stats = self.memory_profiler.get_stats()
+
+        return {
+            'total_samples': len(stats),
+            'max_memory_usage': max((stat[2] for stat in stats), default=0),
+            'memory_by_function': self._group_memory_by_function(stats)
+        }
+
+    def _group_memory_by_function(self, stats: List) -> Dict[str, float]:
+        """Group memory usage by function."""
+        memory_by_function = defaultdict(float)
+
+        for stat in stats:
+            filename, line_no, mem_usage = stat
+            # Extract function name from filename and line
+            func_key = f"{filename}:{line_no}"
+            memory_by_function[func_key] += mem_usage
+
+        return dict(memory_by_function)
+
+    def _analyze_line_profile(self) -> Dict[str, Any]:
+        """Analyze line profiling results."""
+        if not self.line_profiler:
+            return {}
+
+        # Get line profiler statistics
+        stats = self.line_profiler.get_stats()
+
+        return {
+            'timings': stats.timings,
+            'unit': stats.unit
+        }
+```
+
+## Usage Examples
+
+```python
+# Initialize performance profiler
+profiler = PerformanceProfiler(context7_client=context7)
+
+# Example function to profile
+def expensive_function(n):
+    result = []
+    for i in range(n):
+        # Simulate expensive computation
+        temp = []
+        for j in range(i):
+            temp.append(j * j)
+        result.extend(temp)
+    return result
+
+# Start profiling
+profiler.start_profiling(['cpu', 'memory', 'line'])
+
+# Add line profiler for specific function
+if profiler.line_profiler:
+    profiler.line_profiler.add_function(expensive_function)
+
+# Run the code to be profiled
+result = expensive_function(1000)
+
+# Stop profiling and get results
+profile_results = profiler.stop_profiling()
+
+print(f"CPU Profile: {len(profile_results.get('cpu_profile', []))} functions")
+print(f"Memory Peak: {profile_results.get('memory_profile', {}).get('peak_mb', 0):.2f} MB")
+```
+
+## Best Practices
+
+1. **Profile Types**: Start with CPU and memory profiling, add line profiling for specific functions
+2. **Baseline Measurement**: Always profile before optimization
+3. **Realistic Workloads**: Profile with production-like data and patterns
+4. **Multiple Runs**: Profile multiple times to account for variability
+5. **Statistical Significance**: Ensure sufficient execution time for accurate measurements
+
+---
+
+Related: [Real-Time Monitoring](./real-time-monitoring.md) | [Bottleneck Detection](./bottleneck-detection.md)