signal-bot/signal_bot/stats/facts.py

# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence.
"""Everything known about one day, gathered once.

The candidates in ``curiosities`` each need some slice of the same handful of
queries. Gathering them once and passing this around keeps the night's work to
a fixed number of queries however many candidates are added later, and gives
every candidate the same uniform signature -- which is what makes the "not
enough history yet" guards mechanical to write and to test.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import TYPE_CHECKING

from signal_bot.stats import records, streaks
from signal_bot.stats.periods import weekday_of
from signal_bot.stats.queries_day import DayTotals, day_totals
from signal_bot.stats.queries_period import every_day, weekday_buckets

if TYPE_CHECKING:
    from signal_bot.stats.events import EventStore
    from signal_bot.stats.queries_day import DayRow


@dataclass(frozen=True, slots=True)
class DayFacts:
    """One day, plus the history it has to be interesting against."""

    day: str
    rows: list[DayRow]
    totals: DayTotals
    # Messages per recorded day across the whole history, the backfilled day
    # already removed. Missing days are silences, not zeros.
    history: dict[str, int]
    winners: dict[str, list[tuple[str, str]]]
    events: EventStore
    group_id: str
    exclude: str | None

    @property
    def leaders(self) -> list[tuple[str, str]]:
        """Whoever holds today's crown, as (uuid, display name). Ties included."""
        return self.winners.get(self.day, [])

    @property
    def speakers(self) -> list[DayRow]:
        """Everyone who actually wrote today, most talkative first."""
        return [row for row in self.rows if not row.is_silent]

    @property
    def weekday(self) -> int:
        """0 for Monday through 6 for Sunday."""
        return weekday_of(self.day)

    @property
    def same_weekday_before(self) -> list[int]:
        """Every earlier day that fell on the same weekday.

        Today is excluded, so "wtorki mają średnio 74" is a claim about the
        other Tuesdays rather than one that quietly includes the day it is
        being compared against.
        """
        buckets = weekday_buckets({d: n for d, n in self.history.items() if d < self.day})
        return buckets.get(self.weekday, [])

    def person_days(self, uuid: str) -> dict[str, int]:
        """One person's messages per day, across the whole history."""
        rows = self.events.connection.execute(
            """
            SELECT day, COUNT(*) AS messages
            FROM message_events
            WHERE group_id = ? AND uuid = ? AND day <> ?
            GROUP BY day
            """,
            (self.group_id, uuid, self.exclude or ""),
        ).fetchall()
        return {r["day"]: r["messages"] for r in rows}


def gather(
    events: EventStore,
    group_id: str,
    day: str,
    rows: list[DayRow],
    *,
    exclude: str | None = None,
) -> DayFacts:
    """Run the shared queries once and bundle them up."""
    return DayFacts(
        day=day,
        rows=rows,
        totals=day_totals(rows),
        history=every_day(events, group_id, exclude=exclude),
        winners=streaks.daily_winners(events, group_id, exclude=exclude),
        events=events,
        group_id=group_id,
        exclude=exclude,
    )


def personal_record(facts: DayFacts, uuid: str) -> records.DayRecord | None:
    """Today's count, if it is that person's best ever, else None."""
    best = records.personal_best(facts.events, facts.group_id, uuid, exclude=facts.exclude)
    if best is None or best.day != facts.day:
        return None
    return best