hvac-kia-content/src/content_analysis/competitive/models/comparative_analysis.py

"""
Comparative Analysis Data Models

Data structures for cross-competitor market analysis and performance benchmarking.
"""

from dataclasses import dataclass, field
from datetime import datetime
from typing import Dict, List, Any, Optional
from enum import Enum


class TrendDirection(Enum):
    """Direction of performance trends"""
    INCREASING = "increasing"
    DECREASING = "decreasing"
    STABLE = "stable"
    VOLATILE = "volatile"


@dataclass
class PerformanceGap:
    """Represents a performance gap between HKIA and competitors"""
    gap_type: str  # engagement_rate, views, technical_depth, etc.
    hkia_value: float
    competitor_benchmark: float
    performance_gap: float  # negative means underperforming
    improvement_potential: float  # potential % improvement
    top_performing_competitor: str
    recommendation: str
    
    def to_dict(self) -> Dict[str, Any]:
        return {
            'gap_type': self.gap_type,
            'hkia_value': self.hkia_value,
            'competitor_benchmark': self.competitor_benchmark,
            'performance_gap': self.performance_gap,
            'improvement_potential': self.improvement_potential,
            'top_performing_competitor': self.top_performing_competitor,
            'recommendation': self.recommendation
        }


@dataclass
class TrendAnalysis:
    """Analysis of content and performance trends"""
    analysis_window: str
    trending_topics: List[Dict[str, Any]] = field(default_factory=list)
    content_format_trends: List[Dict[str, Any]] = field(default_factory=list)
    engagement_trends: List[Dict[str, Any]] = field(default_factory=list)
    publishing_patterns: Dict[str, Any] = field(default_factory=dict)
    
    def to_dict(self) -> Dict[str, Any]:
        return {
            'analysis_window': self.analysis_window,
            'trending_topics': self.trending_topics,
            'content_format_trends': self.content_format_trends,
            'engagement_trends': self.engagement_trends,
            'publishing_patterns': self.publishing_patterns
        }


@dataclass
class MarketInsights:
    """Strategic market insights and recommendations"""
    strategic_recommendations: List[str] = field(default_factory=list)
    opportunity_areas: List[str] = field(default_factory=list)
    competitive_threats: List[str] = field(default_factory=list)
    market_trends: List[str] = field(default_factory=list)
    confidence_score: float = 0.0
    
    def to_dict(self) -> Dict[str, Any]:
        return {
            'strategic_recommendations': self.strategic_recommendations,
            'opportunity_areas': self.opportunity_areas,
            'competitive_threats': self.competitive_threats,
            'market_trends': self.market_trends,
            'confidence_score': self.confidence_score
        }


@dataclass
class ComparativeMetrics:
    """Comprehensive comparative market analysis metrics"""
    timeframe: str
    analysis_date: datetime
    
    # HKIA Performance
    hkia_performance: Dict[str, Any] = field(default_factory=dict)
    
    # Competitor Performance
    competitor_performance: List[Dict[str, Any]] = field(default_factory=list)
    
    # Market Analysis
    market_position: str = "follower"
    market_share_estimate: Dict[str, float] = field(default_factory=dict)
    competitive_advantages: List[str] = field(default_factory=list)
    competitive_gaps: List[str] = field(default_factory=list)
    
    def to_dict(self) -> Dict[str, Any]:
        return {
            'timeframe': self.timeframe,
            'analysis_date': self.analysis_date.isoformat(),
            'hkia_performance': self.hkia_performance,
            'competitor_performance': self.competitor_performance,
            'market_position': self.market_position,
            'market_share_estimate': self.market_share_estimate,
            'competitive_advantages': self.competitive_advantages,
            'competitive_gaps': self.competitive_gaps
        }