"""
Core Data Models for U-ITE
===========================
Defines the fundamental data structures used throughout the application.
These models ensure consistent data representation across different modules.

This module uses Python's modern features:
- Enums for type-safe constants
- Dataclasses for lightweight, immutable data containers
- Type hints for better IDE support and documentation

Features:
- NetworkState: Enum for network health status
- Severity: Enum for event severity levels
- Event: Dataclass for event data structure
"""

from enum import Enum
from dataclasses import dataclass
from typing import Optional
from datetime import datetime


class NetworkState(str, Enum):
    """
    Network health states.
    
    Represents the current status of a monitored network connection.
    Used by the state engine to track network conditions over time.
    
    Values:
        UP: Network is operational and healthy
        DOWN: Network is completely down/unreachable
        DEGRADED: Network is up but experiencing issues
        UNKNOWN: Network state cannot be determined
    
    Example:
        >>> current_state = NetworkState.UP
        >>> if current_state == NetworkState.DOWN:
        ...     alert_admin()
    """
    UP = "UP"
    DOWN = "DOWN"
    DEGRADED = "DEGRADED"
    UNKNOWN = "UNKNOWN"


class Severity(str, Enum):
    """
    Event severity levels.
    
    Indicates the importance/urgency of an event.
    Used for filtering and alerting priorities.
    
    Values:
        INFO:  Informational, no action needed
        WARNING: Potential issue, should be investigated
        CRITICAL: Severe issue, immediate attention required
    
    Example:
        >>> if event.severity == Severity.CRITICAL:
        ...     send_urgent_notification()
    """
    INFO = "INFO"
    WARNING = "WARNING"
    CRITICAL = "CRITICAL"


@dataclass
class Event:
    """
    Network event data structure.
    
    Represents a significant occurrence in the network (outage, recovery,
    degradation, etc.). Events are generated by the event detector and
    stored for historical analysis and alerting.
    
    Attributes:
        id: Unique event identifier (UUID)
        network_id: ID of the affected network
        device_id: ID of the device that detected the event
        severity: Event severity level (INFO/WARNING/CRITICAL)
        message: Human-readable event description
        timestamp: When the event occurred (ISO format)
        correlation_id: Optional ID to group related events
    
    Example:
        >>> event = Event(
        ...     id="123e4567-e89b-12d3-a456-426614174000",
        ...     network_id="a1b2c3d4",
        ...     device_id="dev-001",
        ...     severity=Severity.CRITICAL,
        ...     message="Internet connection lost",
        ...     timestamp=datetime.now().isoformat()
        ... )
    """
    id: str
    network_id: str
    device_id: str
    severity: str
    message: str
    timestamp: str
    correlation_id: Optional[str] = None


# ============================================================================
# Optional: Add validation methods if needed
# ============================================================================
def validate_event(event: Event) -> bool:
    """
    Validate that an event has all required fields.
    
    This can be used by the event factory to ensure data integrity.
    
    Args:
        event: Event object to validate
        
    Returns:
        bool: True if event is valid, False otherwise
    """
    required_fields = [event.id, event.network_id, event.device_id, 
                      event.severity, event.message, event.timestamp]
    
    return all(field is not None for field in required_fields)


# ============================================================================
# Optional: Add helper functions for working with events
# ============================================================================
def format_event_for_logging(event: Event) -> str:
    """
    Format an event for log output.
    
    Creates a consistent, readable log entry for events.
    
    Args:
        event: Event to format
        
    Returns:
        str: Formatted log string
    """
    return f"[{event.severity}] {event.timestamp}: {event.message} (network: {event.network_id[:8]})"


# ============================================================================
# Version info for the models (optional)
# ============================================================================
__version__ = "1.0.0"
__all__ = ['NetworkState', 'Severity', 'Event', 'validate_event', 'format_event_for_logging']
