"""Seasonal calendar — event-to-demand-multiplier lookup table.

TODO: Implement seasonal event management:
    - Calendar of known events (holidays, promotions, local events)
    - Per-event demand multipliers by category
    - Compose with forecasting for event-adjusted predictions
    - Custom event registration

Planned backend:
    - builtin: Static calendar with configurable events and multipliers

Usage (planned):
    from platoon.learning.providers import get_provider
    cal = get_provider("seasonal")
    events = cal.events_in_range("2025-11-01", "2025-12-31")
    multiplier = cal.get_multiplier("2025-11-29", category="Electronics")
"""

from dataclasses import dataclass, field
from typing import Any, Dict, List, Optional

from platoon.learning.providers import ModelProvider, register_provider


# ---------------------------------------------------------------------------
# Result types
# ---------------------------------------------------------------------------


@dataclass
class SeasonalEvent:
    """A calendar event with demand impact."""

    name: str
    start_date: str  # ISO date
    end_date: str  # ISO date
    multiplier: float  # demand multiplier (1.0 = no impact, 2.0 = double demand)
    categories: List[str] = field(default_factory=list)  # affected categories (empty = all)


@dataclass
class SeasonalCalendar:
    """Collection of seasonal events with lookup methods."""

    events: List[SeasonalEvent]
    year: int = 2025


# ---------------------------------------------------------------------------
# Provider stub
# ---------------------------------------------------------------------------


@register_provider
class BuiltinSeasonalProvider(ModelProvider):
    """Static seasonal calendar with configurable events and multipliers.

    TODO: Implement events_in_range() and get_multiplier() with a default
    calendar covering major US/UK retail events.
    """

    name = "builtin_seasonal"
    domain = "seasonal"
    backend = "builtin"

    def events_in_range(self, start_date: str, end_date: str, **kwargs) -> List[SeasonalEvent]:
        """Get events within a date range."""
        raise NotImplementedError("builtin seasonal provider not yet implemented")

    def get_multiplier(self, date: str, category: Optional[str] = None, **kwargs) -> float:
        """Get the demand multiplier for a specific date and optional category."""
        raise NotImplementedError("builtin seasonal provider not yet implemented")

    def get_calendar(self, year: int = 2025, **kwargs) -> SeasonalCalendar:
        """Get the full seasonal calendar for a year."""
        raise NotImplementedError("builtin seasonal provider not yet implemented")
