Leaderboards

class LeaderboardScoreTypes(models.TextChoices):
    PEER_TOURNAMENT = "peer_tournament"
    DEFAULT = "default"
    SPOT_PEER_TOURNAMENT = "spot_peer_tournament"
    SPOT_BASELINE_TOURNAMENT = "spot_baseline_tournament"
    RELATIVE_LEGACY_TOURNAMENT = "relative_legacy_tournament"
    BASELINE_GLOBAL = "baseline_global"
    PEER_GLOBAL = "peer_global"
    PEER_GLOBAL_LEGACY = "peer_global_legacy"
    COMMENT_INSIGHT = "comment_insight"
    QUESTION_WRITING = "question_writing"
    MANUAL = "manual"

class Leaderboard(TimeStampedModel):
    name = models.CharField(max_length=200, null=True, blank=True)
    project = models.ForeignKey(
        Project,
        null=True,
        blank=True,
        on_delete=models.CASCADE,
        related_name="leaderboards",
    )
    
    score_type = models.CharField(
        max_length=200,
        choices=LeaderboardScoreTypes.choices,
    )
    
    # Time boundaries
    start_time = models.DateTimeField(null=True, blank=True)
    end_time = models.DateTimeField(null=True, blank=True)
    finalize_time = models.DateTimeField(null=True, blank=True)
    finalized = models.BooleanField(default=False)
    
    # Prize configuration
    prize_pool = models.DecimalField(
        decimal_places=2,
        max_digits=15,
        null=True,
        blank=True,
    )
    minimum_prize_amount = models.DecimalField(
        default=50.00,
        decimal_places=2,
        max_digits=15,
    )
    
    # User filtering
    user_list = models.ManyToManyField(User, blank=True)
    bot_status = models.CharField(
        max_length=32,
        choices=Project.BotLeaderboardStatus.choices,
        null=True,
        blank=True,
    )
    
    # Display configuration
    display_config = models.JSONField(null=True, blank=True)

def get_questions(self) -> QuerySet[Question]:
    questions = Question.objects.filter(
        post__curation_status=Post.CurationStatus.APPROVED
    )
    
    if not (self.project and self.project.type == Project.ProjectTypes.SITE_MAIN):
        # Normal project leaderboard
        if self.project:
            questions = questions.filter(
                Q(post__projects=self.project) | Q(post__default_project=self.project)
            )
        return questions.distinct("id")

# Questions must:
# 1. Be public
questions = questions.filter_public().filter(
    post__in=Post.objects.filter_for_main_feed()
)

# 2. Have time boundaries within leaderboard period
questions = questions.filter(
    open_time__gte=self.start_time,
    open_time__lt=self.end_time,
    scheduled_close_time__lte=self.end_time + close_grace_period,
)

# 3. Exclude questions that belong to other overlapping leaderboards
# (Questions only count for the shortest matching time window)

start_time = models.DateTimeField(
    null=True,
    blank=True,
    help_text="""Optional (required for global leaderboards).
    Global Leaderboards: filters for questions that have an open time after this.
    Non-Global Leaderboards: has no effect on question filtering.
    Filtering MedalExclusionRecords: MedalExclusionRecords that have no end_time
    or an end_time greater than this will be triggered.
    """,
)

end_time = models.DateTimeField(
    null=True,
    blank=True,
    help_text="""Optional (required for global leaderboards).
    Global Leaderboards: filters for questions that have a scheduled_close_time
    before this (plus a grace period).
    """,
)

finalize_time = models.DateTimeField(
    null=True,
    blank=True,
    help_text="""Optional. If not set, the Project's close_date will be used instead.
    For all Leaderboards: used to filter out questions that have a
    resolution_set_time after this (as they were resolved after this
    Leaderboard was finalized).
    """,
)

finalized = models.BooleanField(
    default=False,
    help_text="If true, this Leaderboard's entries cannot be updated except by manual action.",
)

prize_pool = models.DecimalField(
    default=None,
    decimal_places=2,
    max_digits=15,
    null=True,
    blank=True,
    help_text="""Optional. If not set, the Project's prize_pool will be used.
    If the Project has a prize pool, but this leaderboard has none, set this to 0.
    """,
)

minimum_prize_amount = models.DecimalField(
    default=50.00,
    decimal_places=2,
    max_digits=15,
    help_text="""The minimum amount a user can win in this leaderboard.
    Any remaining money is redistributed. Tournaments that close before June 2025
    will have a value of 0.00.
    """,
)

bot_status = models.CharField(
    max_length=32,
    choices=Project.BotLeaderboardStatus.choices,
    null=True,
    blank=True,
    help_text="Optional. If not set, the Project's bot_leaderboard_status will be used.",
)

class BotLeaderboardStatus(models.TextChoices):
    EXCLUDE_AND_HIDE = "exclude_and_hide"  # Bots hidden completely
    EXCLUDE_AND_SHOW = "exclude_and_show"  # Bots shown but no prizes (default)
    INCLUDE = "include"                    # Bots compete for prizes
    BOTS_ONLY = "bots_only"               # Only bots compete

user_list = models.ManyToManyField(
    User,
    blank=True,
    help_text="""Optional. If not set, all users with scores will be included.
    If set, only users in this list will be included.
    Exclusion Records still apply independent of this list.
    """,
)

display_config = models.JSONField(
    null=True,
    blank=True,
    help_text=(
        "Optional JSON configuration for displaying this leaderboard."
        "If not set, default display settings will be used."
        "Example display_config:"
        """{
            "display_name": "My Custom Leaderboard",
            "column_renames": {
                "Questions": "Question Links"
            },
            "display_order": 1,
            "display_on_project": true
        }"""
    ),
)

GLOBAL_LEADERBOARD_STRING = "Leaderboard"
GLOBAL_LEADERBOARD_SLUG = "leaderboard"

def global_leaderboard_dates() -> list[tuple[datetime, datetime]]:
    # Returns list of (start_date, end_date) tuples for each period
    # Typically: quarterly periods (Q1 2024, Q2 2024, etc.)

def get_global_leaderboard_dates(self) -> tuple[datetime, datetime] | None:
    forecast_horizon_start = self.open_time
    forecast_horizon_end = self.scheduled_close_time
    
    # Find shortest window that contains this question's forecast period
    shortest_window = None
    for gl_start, gl_end in gl_dates[::-1]:  # Reverse order (shortest first)
        if forecast_horizon_start < gl_start:
            continue
        if forecast_horizon_end > gl_end + timedelta(days=3):
            continue
        if shortest_window is None or (gl_end - gl_start) < window_size:
            shortest_window = (gl_start, gl_end)

class Leaderboard(TimeStampedModel):
    entries: QuerySet["LeaderboardEntry"]  # Related model