signal-bot/signal_bot/analytics/trend.py

# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence.
"""Family B, the calendar half: day series, months, and what is dying.

Day-granular, so every source counts -- a ``daily_uses`` row has no hour but
it does know its day, which is exactly what these questions need.

The direction of a trend is deliberately not always stated. ``Window``
carries the day count and ``TREND_MIN_DAYS`` is the threshold; below it the
series is returned and drawn but ``direction`` stays ``UNKNOWN``. A bot that
is three days old has a novelty curve, not a trend, and an arrow drawn from
three points is a claim the data cannot support.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import TYPE_CHECKING, Final

from signal_bot.stats.periods import shift

if TYPE_CHECKING:
    import sqlite3
    from collections.abc import Sequence

    from signal_bot.analytics.scope import Scope, Window

RISING: Final = "rising"
FALLING: Final = "falling"
FLAT: Final = "flat"
UNKNOWN: Final = "unknown"

# How much the second half must differ from the first to be called a
# direction rather than noise. A tenth: below that, on counts this small,
# one busy evening decides the answer.
TREND_MARGIN: Final = 0.10

# A command not used for this many days is called dying rather than merely
# quiet. Deliberately short, because the whole history is days long; it is
# a relative statement and the panel says so.
DYING_AFTER_DAYS: Final = 3

# A direction needs a before and an after to compare.
MIN_POINTS: Final = 2

BY_DAY_SQL: Final = """
SELECT day, COUNT(*) AS uses, COUNT(DISTINCT user_uuid) AS people
FROM command_events
WHERE (:group IS NULL OR group_id = :group)
  AND outcome != 'unknown_word'
GROUP BY day
ORDER BY day
"""

BY_COMMAND_DAY_SQL: Final = """
SELECT command, day, COUNT(*) AS uses
FROM command_events
WHERE (:group IS NULL OR group_id = :group)
  AND outcome != 'unknown_word'
GROUP BY command, day
ORDER BY command, day
"""

BY_MONTH_SQL: Final = """
SELECT substr(day, 1, 7) AS month, COUNT(*) AS uses, COUNT(DISTINCT day) AS days
FROM command_events
WHERE (:group IS NULL OR group_id = :group)
  AND outcome != 'unknown_word'
GROUP BY month
ORDER BY month
"""

LAST_USED_SQL: Final = """
SELECT command, MAX(day) AS last_day, COUNT(*) AS uses
FROM command_events
WHERE (:group IS NULL OR group_id = :group)
  AND outcome = 'ok'
GROUP BY command
ORDER BY last_day, command
"""


@dataclass(frozen=True, slots=True)
class Dying:
    """A command that used to be used and has gone quiet."""

    command: str
    last_day: str
    idle_days: int
    uses: int


def by_day(conn: sqlite3.Connection, scope: Scope) -> list[tuple[str, int, int]]:
    """(day, uses, people) for every day anything happened."""
    return [
        (str(row["day"]), int(row["uses"]), int(row["people"]))
        for row in conn.execute(BY_DAY_SQL, scope.params())
    ]


def dense_days(series: Sequence[tuple[str, int, int]]) -> list[tuple[str, int]]:
    """Fill in the days nothing happened on.

    A sparse series draws a line straight over a silent day, which reads as
    "steady" when the truth is "nobody used it". Built by stepping the date
    rather than by adding 86_400 seconds, because Warsaw days are not all
    the same length.
    """
    if not series:
        return []
    filled: list[tuple[str, int]] = []
    day = series[0][0]
    last = series[-1][0]
    counts = {entry[0]: entry[1] for entry in series}
    while day <= last:
        filled.append((day, counts.get(day, 0)))
        day = shift(day, 1)
    return filled


def by_command_day(conn: sqlite3.Connection, scope: Scope) -> dict[str, dict[str, int]]:
    """Per-command day series, for the sparklines."""
    series: dict[str, dict[str, int]] = {}
    for row in conn.execute(BY_COMMAND_DAY_SQL, scope.params()):
        series.setdefault(str(row["command"]), {})[str(row["day"])] = int(row["uses"])
    return series


def by_month(conn: sqlite3.Connection, scope: Scope) -> list[tuple[str, int, int]]:
    """(month, uses, days seen). The days matter: a partial month is not low."""
    return [
        (str(row["month"]), int(row["uses"]), int(row["days"]))
        for row in conn.execute(BY_MONTH_SQL, scope.params())
    ]


def direction(series: Sequence[tuple[str, int]], measured: Window) -> str:
    """Whether use is rising, falling, flat -- or too early to say.

    Compares the mean of the second half against the first. Not a
    least-squares fit: on a dozen points a fit is no more truthful and far
    harder to explain in a chat message.
    """
    if not measured.enough_for_a_trend or len(series) < MIN_POINTS:
        return UNKNOWN
    # MIN_POINTS above guarantees half >= 1, so neither slice is empty and
    # neither division below is by zero.
    half = len(series) // 2
    first = [count for _day, count in series[:half]]
    second = [count for _day, count in series[half:]]
    before = sum(first) / len(first)
    after = sum(second) / len(second)
    if before == 0:
        return RISING if after > 0 else FLAT
    change = (after - before) / before
    if change > TREND_MARGIN:
        return RISING
    if change < -TREND_MARGIN:
        return FALLING
    return FLAT


def dying(conn: sqlite3.Connection, scope: Scope, today: str) -> list[Dying]:
    """Commands that worked, were used, and then stopped being used."""
    found: list[Dying] = []
    for row in conn.execute(LAST_USED_SQL, scope.params()):
        last_day = str(row["last_day"])
        idle = _days_between(last_day, today)
        if idle >= DYING_AFTER_DAYS:
            found.append(
                Dying(
                    command=str(row["command"]),
                    last_day=last_day,
                    idle_days=idle,
                    uses=int(row["uses"]),
                )
            )
    return sorted(found, key=lambda entry: (-entry.idle_days, entry.command))


def _days_between(start: str, end: str) -> int:
    """Whole calendar days from one day to another, never negative."""
    days = 0
    day = start
    while day < end:
        day = shift(day, 1)
        days += 1
    return days