# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence. """Family B, the time-of-day half: when the bot is actually used. Every query here filters ``local_hour >= 0``. That is the whole point of the filter: ``daily_uses`` rows carry ``UNKNOWN_HOUR`` because their source knew only a date, and letting them through would file a third of the history under hour -1 -- or, worse, under midnight if anybody later "tidied" the sentinel to 0. ``journald`` rows *are* included. They were matched to a real message, so their hour was observed even though their duration was not. Excluding them would throw away most of the history for no gain; that distinction is why ``scope`` names two predicates rather than one. A Warsaw day is not always 24 hours -- 2026-03-29 has 23 and 2026-10-25 has 25 -- so callers must not assume the buckets sum to a day, and nothing here divides by 24. """ from __future__ import annotations from dataclasses import dataclass from typing import TYPE_CHECKING, Final if TYPE_CHECKING: import sqlite3 from signal_bot.analytics.scope import Scope HOURS_IN_DAY: Final = 24 DAYS_IN_WEEK: Final = 7 @dataclass(frozen=True, slots=True) class Peak: """The busiest and quietest hours, when there is enough to say.""" busiest: int = -1 busiest_uses: int = 0 quietest: int = -1 quietest_uses: int = 0 BY_HOUR_SQL: Final = """ SELECT local_hour AS hour, COUNT(*) AS uses FROM command_events WHERE (:group IS NULL OR group_id = :group) AND local_hour >= 0 AND outcome != 'unknown_word' GROUP BY local_hour ORDER BY local_hour """ BY_WEEKDAY_HOUR_SQL: Final = """ SELECT weekday, local_hour AS hour, COUNT(*) AS uses FROM command_events WHERE (:group IS NULL OR group_id = :group) AND local_hour >= 0 AND weekday >= 0 AND outcome != 'unknown_word' GROUP BY weekday, local_hour ORDER BY weekday, local_hour """ BY_COMMAND_HOUR_SQL: Final = """ SELECT command, local_hour AS hour, COUNT(*) AS uses FROM command_events WHERE (:group IS NULL OR group_id = :group) AND local_hour >= 0 AND outcome != 'unknown_word' GROUP BY command, local_hour ORDER BY command, local_hour """ BY_WEEKDAY_SQL: Final = """ SELECT weekday, COUNT(*) AS uses, COUNT(DISTINCT day) AS days FROM command_events WHERE (:group IS NULL OR group_id = :group) AND weekday >= 0 AND outcome != 'unknown_word' GROUP BY weekday ORDER BY weekday """ def by_hour(conn: sqlite3.Connection, scope: Scope) -> list[int]: """Uses per hour of the day, as 24 buckets with the empty ones present. A dense list rather than the rows sqlite returns: a bar chart with a missing 04:00 draws the wrong shape, and "nobody uses it at four in the morning" is one of the things the panel is for. """ # Indexed without a bounds check: local_hour is written by hour_of(), # which cannot return anything outside 0-23, and the query already # excludes the UNKNOWN_HOUR sentinel. A guard here would be dead code # that hides a corrupt row instead of failing on one. buckets = [0] * HOURS_IN_DAY for row in conn.execute(BY_HOUR_SQL, scope.params()): buckets[int(row["hour"])] = int(row["uses"]) return buckets def by_weekday_hour(conn: sqlite3.Connection, scope: Scope) -> list[list[int]]: """A 7x24 grid, Monday first, matching date.weekday().""" grid = [[0] * HOURS_IN_DAY for _ in range(DAYS_IN_WEEK)] for row in conn.execute(BY_WEEKDAY_HOUR_SQL, scope.params()): grid[int(row["weekday"])][int(row["hour"])] = int(row["uses"]) return grid def by_command_hour(conn: sqlite3.Connection, scope: Scope) -> dict[str, list[int]]: """One 24-bucket row per command: which commands belong to which hours.""" grid: dict[str, list[int]] = {} for row in conn.execute(BY_COMMAND_HOUR_SQL, scope.params()): buckets = grid.setdefault(str(row["command"]), [0] * HOURS_IN_DAY) buckets[int(row["hour"])] = int(row["uses"]) return grid def by_weekday(conn: sqlite3.Connection, scope: Scope) -> list[tuple[int, int, int]]: """(weekday, uses, days seen) so an average can be taken honestly. Dividing by the number of weeks would be wrong on a history this short: a Tuesday that has happened once is not a weekly average. """ return [ (int(row["weekday"]), int(row["uses"]), int(row["days"])) for row in conn.execute(BY_WEEKDAY_SQL, scope.params()) ] def peak(buckets: list[int]) -> Peak: """The busiest hour, and the quietest hour that anybody ever used. "Quietest" skips hours with nothing at all: at three days old most of the night is empty, and "the deadest hour is 04:00 with zero" would be true of about nine different hours and interesting about none of them. """ if not any(buckets): return Peak() used = [(hour, uses) for hour, uses in enumerate(buckets) if uses] busiest = max(used, key=lambda pair: (pair[1], -pair[0])) quietest = min(used, key=lambda pair: (pair[1], pair[0])) return Peak( busiest=busiest[0], busiest_uses=busiest[1], quietest=quietest[0], quietest_uses=quietest[1], )