runbooks 1.0.3__py3-none-any.whl → 1.1.0__py3-none-any.whl

runbooks/common/business_logic.py

@@ -0,0 +1,485 @@
+"""
+Business Logic Extraction for runbooks package - Universal Business Patterns
+
+Extracts and standardizes business logic patterns from existing modules,
+providing reusable components that maintain consistency across the platform.
+
+Following KISS & DRY principles - extract proven patterns from existing successful modules.
+"""
+
+from datetime import datetime
+from typing import Dict, Any, List, Optional, Union
+from dataclasses import dataclass, field
+from enum import Enum
+
+from .rich_utils import (
+    create_table, console, print_header, print_success, print_info,
+    print_warning, format_cost, create_panel, create_progress_bar
+)
+from .profile_utils import get_profile_for_operation
+
+
+class BusinessImpactLevel(Enum):
+    """Business impact classification for operations and optimizations."""
+    CRITICAL = "CRITICAL"  # >$100K annual impact
+    HIGH = "HIGH"         # $20K-100K annual impact
+    MEDIUM = "MEDIUM"     # $5K-20K annual impact
+    LOW = "LOW"          # <$5K annual impact
+
+
+class OptimizationType(Enum):
+    """Types of optimization operations supported."""
+    COST_REDUCTION = "COST_REDUCTION"
+    RESOURCE_EFFICIENCY = "RESOURCE_EFFICIENCY"
+    SECURITY_COMPLIANCE = "SECURITY_COMPLIANCE"
+    PERFORMANCE_IMPROVEMENT = "PERFORMANCE_IMPROVEMENT"
+    OPERATIONAL_EXCELLENCE = "OPERATIONAL_EXCELLENCE"
+
+
+@dataclass
+class BusinessMetrics:
+    """Universal business metrics for operations and optimizations."""
+    annual_savings: float = 0.0
+    monthly_cost_current: float = 0.0
+    monthly_cost_optimized: float = 0.0
+    roi_percentage: float = 0.0
+    payback_period_months: int = 0
+    confidence_level: float = 95.0
+    implementation_effort: str = "Medium"
+    business_risk: str = "Low"
+
+    def calculate_roi(self) -> float:
+        """Calculate ROI percentage from current metrics."""
+        if self.annual_savings > 0 and self.monthly_cost_current > 0:
+            investment_cost = self.monthly_cost_current * 12  # Annual current cost as investment
+            self.roi_percentage = (self.annual_savings / investment_cost) * 100
+        return self.roi_percentage
+
+    def determine_impact_level(self) -> BusinessImpactLevel:
+        """Determine business impact level from annual savings."""
+        if self.annual_savings >= 100000:
+            return BusinessImpactLevel.CRITICAL
+        elif self.annual_savings >= 20000:
+            return BusinessImpactLevel.HIGH
+        elif self.annual_savings >= 5000:
+            return BusinessImpactLevel.MEDIUM
+        else:
+            return BusinessImpactLevel.LOW
+
+
+@dataclass
+class OptimizationResult:
+    """Universal optimization result structure."""
+    resource_type: str
+    operation_type: OptimizationType
+    business_metrics: BusinessMetrics
+    recommendations: List[str] = field(default_factory=list)
+    implementation_steps: List[str] = field(default_factory=list)
+    technical_details: Dict[str, Any] = field(default_factory=dict)
+    timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
+    validated_by_mcp: bool = False
+
+    def get_executive_summary(self) -> str:
+        """Get executive-friendly summary of the optimization."""
+        impact = self.business_metrics.determine_impact_level()
+        return (
+            f"{self.resource_type} optimization with "
+            f"${self.business_metrics.annual_savings:,.0f} annual savings "
+            f"({impact.value} impact, {self.business_metrics.confidence_level:.1f}% confidence)"
+        )
+
+
+class UniversalBusinessLogic:
+    """
+    Universal business logic extraction and standardization.
+
+    Provides reusable business logic patterns extracted from proven modules
+    like FinOps for consistent application across all runbooks modules.
+    """
+
+    def __init__(self, module_name: str):
+        self.module_name = module_name
+        self.session_metrics = []
+
+    def create_cost_analysis_table(self, cost_data: Dict[str, Any], title: str,
+                                 include_quarterly: bool = False) -> None:
+        """
+        Standardized cost analysis table creation following FinOps patterns.
+
+        Args:
+            cost_data: Cost data dictionary with resource costs
+            title: Table title for display
+            include_quarterly: Include quarterly intelligence columns
+        """
+        table = create_table(
+            title=title,
+            caption="Enterprise cost analysis with MCP validation"
+        )
+
+        # Standard columns based on successful FinOps patterns
+        table.add_column("Resource", style="cyan", no_wrap=True)
+        table.add_column("Current Cost", justify="right", style="cost")
+        table.add_column("Optimization %", justify="right", style="yellow")
+        table.add_column("Annual Savings", justify="right", style="bright_green")
+
+        if include_quarterly:
+            table.add_column("Q3 Trend", justify="right", style="magenta")
+            table.add_column("Strategic Context", style="dim", max_width=20)
+
+        # Add rows with consistent formatting
+        total_savings = 0.0
+        for resource, data in cost_data.items():
+            current_cost = data.get('current', 0.0)
+            optimization_pct = data.get('optimization_percentage', 0.0)
+            annual_savings = data.get('annual_savings', 0.0)
+            total_savings += annual_savings
+
+            row_data = [
+                resource,
+                format_cost(current_cost),
+                f"{optimization_pct:.1f}%",
+                format_cost(annual_savings)
+            ]
+
+            if include_quarterly:
+                quarterly_trend = data.get('quarterly_trend', 'Stable')
+                strategic_context = data.get('strategic_context', 'Monitor')
+                row_data.extend([quarterly_trend, strategic_context])
+
+            table.add_row(*row_data)
+
+        # Add total row
+        total_row = ["[bold]TOTAL[/]", "", "", f"[bold bright_green]{format_cost(total_savings)}[/]"]
+        if include_quarterly:
+            total_row.extend(["", ""])
+        table.add_row(*total_row)
+
+        console.print(table)
+
+        # Executive summary panel
+        if total_savings > 0:
+            impact_level = BusinessMetrics(annual_savings=total_savings).determine_impact_level()
+            summary_text = f"""
+[bold bright_green]Total Annual Savings: {format_cost(total_savings)}[/]
+[yellow]Business Impact: {impact_level.value}[/]
+[cyan]Resources Analyzed: {len(cost_data)}[/]
+[dim]Analysis Timestamp: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}[/]
+            """
+            summary_panel = create_panel(
+                summary_text.strip(),
+                title="💰 Executive Summary",
+                border_style="green"
+            )
+            console.print(summary_panel)
+
+    def standardize_resource_operations(self, resource_type: str, operation: str,
+                                      profile: Optional[str] = None, **kwargs) -> Dict[str, Any]:
+        """
+        Standardized resource operation pattern following proven CLI patterns.
+
+        Args:
+            resource_type: Type of AWS resource (EC2, S3, RDS, etc.)
+            operation: Operation being performed (analyze, optimize, inventory)
+            profile: AWS profile to use
+            **kwargs: Additional operation parameters
+
+        Returns:
+            Dictionary with standardized operation results
+        """
+        # Apply proven profile management patterns
+        selected_profile = get_profile_for_operation("operational", profile)
+
+        print_header(f"{resource_type.title()} {operation.title()}", f"v1.0.0 - {self.module_name}")
+        print_info(f"Using profile: {selected_profile}")
+
+        # Standard operation tracking
+        operation_start = datetime.now()
+
+        # Standard result format following successful patterns
+        result = {
+            'module': self.module_name,
+            'resource_type': resource_type,
+            'operation': operation,
+            'profile_used': selected_profile,
+            'timestamp': operation_start.isoformat(),
+            'success': True,
+            'results': {},
+            'business_metrics': BusinessMetrics(),
+            'recommendations': [],
+            'performance_data': {
+                'start_time': operation_start.isoformat(),
+                'execution_time_seconds': 0.0
+            }
+        }
+
+        return result
+
+    def generate_optimization_recommendations(self, optimization_result: OptimizationResult) -> List[str]:
+        """
+        Generate standardized optimization recommendations based on business impact.
+
+        Args:
+            optimization_result: Optimization analysis result
+
+        Returns:
+            List of actionable recommendations
+        """
+        recommendations = []
+        metrics = optimization_result.business_metrics
+        impact = metrics.determine_impact_level()
+
+        # Impact-based recommendations
+        if impact == BusinessImpactLevel.CRITICAL:
+            recommendations.extend([
+                f"🚨 CRITICAL: Immediate action required - ${metrics.annual_savings:,.0f} annual savings opportunity",
+                "📋 Executive approval recommended for implementation",
+                "⏰ Target implementation: Within 30 days",
+                "📊 Monthly progress tracking recommended"
+            ])
+        elif impact == BusinessImpactLevel.HIGH:
+            recommendations.extend([
+                f"🔴 HIGH PRIORITY: ${metrics.annual_savings:,.0f} annual savings available",
+                "📋 Business case development recommended",
+                "⏰ Target implementation: Within 90 days",
+                "📊 Quarterly progress review recommended"
+            ])
+        elif impact == BusinessImpactLevel.MEDIUM:
+            recommendations.extend([
+                f"🟡 MEDIUM PRIORITY: ${metrics.annual_savings:,.0f} annual savings potential",
+                "📋 Consider in next planning cycle",
+                "⏰ Target implementation: Within 6 months"
+            ])
+        else:
+            recommendations.extend([
+                f"🟢 LOW PRIORITY: ${metrics.annual_savings:,.0f} annual savings",
+                "📋 Include in routine optimization reviews"
+            ])
+
+        # ROI-based recommendations
+        if metrics.roi_percentage > 200:
+            recommendations.append(f"💰 Excellent ROI: {metrics.roi_percentage:.1f}% return on investment")
+        elif metrics.roi_percentage > 100:
+            recommendations.append(f"💰 Good ROI: {metrics.roi_percentage:.1f}% return on investment")
+
+        # Risk-based recommendations
+        if metrics.business_risk == "Low":
+            recommendations.append("✅ Low implementation risk - safe to proceed")
+        elif metrics.business_risk == "Medium":
+            recommendations.append("⚠️ Medium risk - consider phased implementation")
+        else:
+            recommendations.append("🚨 High risk - detailed planning and approval required")
+
+        return recommendations
+
+    def create_executive_dashboard(self, results: List[OptimizationResult],
+                                 dashboard_title: str = "Executive Dashboard") -> None:
+        """
+        Create executive dashboard following successful FinOps patterns.
+
+        Args:
+            results: List of optimization results
+            dashboard_title: Title for the dashboard
+        """
+        print_header(dashboard_title, f"{self.module_name} Module")
+
+        if not results:
+            print_info("No optimization opportunities identified at this time")
+            return
+
+        # Summary metrics
+        total_savings = sum(r.business_metrics.annual_savings for r in results)
+        high_impact_count = len([r for r in results if r.business_metrics.determine_impact_level() in [BusinessImpactLevel.CRITICAL, BusinessImpactLevel.HIGH]])
+
+        # Executive summary table
+        summary_table = create_table(
+            title="📊 Executive Summary",
+            columns=[
+                {"name": "Metric", "style": "cyan", "justify": "left"},
+                {"name": "Value", "style": "bright_green", "justify": "right"},
+                {"name": "Impact", "style": "yellow", "justify": "left"}
+            ]
+        )
+
+        summary_table.add_row("Total Annual Savings", format_cost(total_savings), f"{len(results)} opportunities")
+        summary_table.add_row("High Priority Items", str(high_impact_count), "Immediate attention required")
+        summary_table.add_row("Average Confidence", f"{sum(r.business_metrics.confidence_level for r in results) / len(results):.1f}%", "Validation accuracy")
+
+        console.print(summary_table)
+
+        # Top opportunities table
+        if results:
+            # Sort by annual savings
+            top_results = sorted(results, key=lambda x: x.business_metrics.annual_savings, reverse=True)[:5]
+
+            opportunities_table = create_table(
+                title="🎯 Top Optimization Opportunities",
+                columns=[
+                    {"name": "Resource", "style": "cyan", "justify": "left"},
+                    {"name": "Annual Savings", "style": "bright_green", "justify": "right"},
+                    {"name": "Impact", "style": "yellow", "justify": "center"},
+                    {"name": "Confidence", "style": "blue", "justify": "right"},
+                    {"name": "Next Action", "style": "white", "justify": "left"}
+                ]
+            )
+
+            for result in top_results:
+                impact = result.business_metrics.determine_impact_level()
+                next_action = "Executive Review" if impact == BusinessImpactLevel.CRITICAL else "Business Case"
+
+                opportunities_table.add_row(
+                    result.resource_type,
+                    format_cost(result.business_metrics.annual_savings),
+                    impact.value,
+                    f"{result.business_metrics.confidence_level:.1f}%",
+                    next_action
+                )
+
+            console.print(opportunities_table)
+
+    def calculate_business_impact(self, resource_type: str, usage_data: Dict[str, Any]) -> BusinessMetrics:
+        """
+        Standardized business impact calculation following proven FinOps methodology.
+
+        Args:
+            resource_type: Type of resource being analyzed
+            usage_data: Resource usage and cost data
+
+        Returns:
+            BusinessMetrics with calculated impact values
+        """
+        metrics = BusinessMetrics()
+
+        # Extract costs
+        current_monthly = usage_data.get('monthly_cost_current', 0.0)
+        optimized_monthly = usage_data.get('monthly_cost_optimized', current_monthly * 0.7)  # Default 30% optimization
+
+        metrics.monthly_cost_current = current_monthly
+        metrics.monthly_cost_optimized = optimized_monthly
+        metrics.annual_savings = (current_monthly - optimized_monthly) * 12
+
+        # Calculate ROI
+        metrics.calculate_roi()
+
+        # Set confidence based on resource type (following successful patterns)
+        confidence_levels = {
+            'NAT Gateway': 95.0,  # High confidence from proven results
+            'Elastic IP': 90.0,
+            'EBS Volume': 85.0,
+            'EC2 Instance': 80.0,
+            'RDS Instance': 75.0,
+            'Generic': 70.0
+        }
+        metrics.confidence_level = confidence_levels.get(resource_type, 70.0)
+
+        # Estimate implementation effort and risk
+        if metrics.annual_savings > 50000:
+            metrics.implementation_effort = "High"
+            metrics.business_risk = "Medium"
+        elif metrics.annual_savings > 10000:
+            metrics.implementation_effort = "Medium"
+            metrics.business_risk = "Low"
+        else:
+            metrics.implementation_effort = "Low"
+            metrics.business_risk = "Low"
+
+        return metrics
+
+    def export_business_results(self, results: List[OptimizationResult],
+                               export_formats: List[str] = None) -> Dict[str, str]:
+        """
+        Export business results in multiple formats following successful patterns.
+
+        Args:
+            results: List of optimization results
+            export_formats: List of formats to export ('csv', 'json', 'markdown')
+
+        Returns:
+            Dictionary with export file paths
+        """
+        if export_formats is None:
+            export_formats = ['csv', 'json', 'markdown']
+
+        timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
+        base_filename = f"{self.module_name}_optimization_results_{timestamp}"
+
+        exported_files = {}
+
+        print_info(f"Exporting results in {len(export_formats)} formats...")
+
+        for fmt in export_formats:
+            filename = f"./awso_evidence/{base_filename}.{fmt}"
+
+            if fmt == 'csv':
+                # CSV export for analysis
+                csv_content = "Resource,Annual_Savings,Impact_Level,Confidence,ROI_Percentage\n"
+                for result in results:
+                    csv_content += f"{result.resource_type},{result.business_metrics.annual_savings},"
+                    csv_content += f"{result.business_metrics.determine_impact_level().value},"
+                    csv_content += f"{result.business_metrics.confidence_level},{result.business_metrics.roi_percentage}\n"
+
+                with open(filename, 'w') as f:
+                    f.write(csv_content)
+
+            elif fmt == 'json':
+                # JSON export for systems integration
+                import json
+                json_data = {
+                    'module': self.module_name,
+                    'timestamp': timestamp,
+                    'total_results': len(results),
+                    'total_annual_savings': sum(r.business_metrics.annual_savings for r in results),
+                    'results': [
+                        {
+                            'resource_type': r.resource_type,
+                            'annual_savings': r.business_metrics.annual_savings,
+                            'impact_level': r.business_metrics.determine_impact_level().value,
+                            'confidence_level': r.business_metrics.confidence_level,
+                            'executive_summary': r.get_executive_summary()
+                        }
+                        for r in results
+                    ]
+                }
+
+                with open(filename, 'w') as f:
+                    json.dump(json_data, f, indent=2)
+
+            elif fmt == 'markdown':
+                # Markdown export for documentation and reports
+                md_content = f"# {self.module_name.title()} Optimization Results\n\n"
+                md_content += f"**Generated**: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n"
+
+                total_savings = sum(r.business_metrics.annual_savings for r in results)
+                md_content += f"## Executive Summary\n\n"
+                md_content += f"- **Total Annual Savings**: ${total_savings:,.0f}\n"
+                md_content += f"- **Optimization Opportunities**: {len(results)}\n"
+                md_content += f"- **High Priority Items**: {len([r for r in results if r.business_metrics.determine_impact_level() in [BusinessImpactLevel.CRITICAL, BusinessImpactLevel.HIGH]])}\n\n"
+
+                md_content += "## Detailed Results\n\n"
+                for i, result in enumerate(results, 1):
+                    md_content += f"### {i}. {result.resource_type}\n\n"
+                    md_content += f"- **Annual Savings**: ${result.business_metrics.annual_savings:,.0f}\n"
+                    md_content += f"- **Impact Level**: {result.business_metrics.determine_impact_level().value}\n"
+                    md_content += f"- **Confidence**: {result.business_metrics.confidence_level:.1f}%\n"
+                    md_content += f"- **ROI**: {result.business_metrics.roi_percentage:.1f}%\n\n"
+
+                with open(filename, 'w') as f:
+                    f.write(md_content)
+
+            exported_files[fmt] = filename
+            print_success(f"Exported {fmt.upper()}: {filename}")
+
+        return exported_files
+
+
+# Factory function for easy integration
+def create_business_logic_handler(module_name: str) -> UniversalBusinessLogic:
+    """
+    Factory function to create business logic handler for any module.
+
+    Args:
+        module_name: Name of the module using business logic
+
+    Returns:
+        UniversalBusinessLogic instance configured for the module
+    """
+    return UniversalBusinessLogic(module_name)