# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence. """Family E, the adoption half: who came back, and what a release did. Three questions that are about the bot rather than about any one command. * **Retention** -- of the people who used it on their first day, how many were still using it N days later. On a history this short this is one or two points, and the panel says so rather than drawing a curve. * **Novelty** -- what a release actually did. ``DOCS-changelog.md`` is the only record of when each version shipped and it is the one the maintainer actually keeps, so the dates come from there rather than from git tags. * **Share of chat** -- what fraction of everything said in the group was a command. This is the only query in the package that reads ``message_events``, and it is the number that says whether the bot is a fixture or a curiosity. """ 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 FIRST_DAY_SQL: Final = """ SELECT user_uuid, MIN(day) AS first_day FROM command_events WHERE (:group IS NULL OR group_id = :group) AND outcome = 'ok' GROUP BY user_uuid """ ACTIVE_DAYS_SQL: Final = """ SELECT DISTINCT user_uuid, day FROM command_events WHERE (:group IS NULL OR group_id = :group) AND outcome = 'ok' """ SHARE_SQL: Final = """ SELECT COUNT(*) AS messages, SUM(is_command) AS commands FROM message_events WHERE (:group IS NULL OR group_id = :group) AND local_hour >= 0 """ NEW_PEOPLE_SQL: Final = """ SELECT day, COUNT(*) AS people FROM ( SELECT user_uuid, MIN(day) AS day FROM command_events WHERE (:group IS NULL OR group_id = :group) AND outcome = 'ok' GROUP BY user_uuid ) GROUP BY day ORDER BY day """ @dataclass(frozen=True, slots=True) class Share: """How much of the group's talking is people talking to the bot.""" messages: int = 0 commands: int = 0 @property def fraction(self) -> float: """Commands as a share of every counted message.""" return self.commands / self.messages if self.messages else 0.0 def retention(conn: sqlite3.Connection, scope: Scope, horizon: int) -> list[tuple[int, int, int]]: """(day offset, still active, cohort size) for offsets 0..horizon. Days are stepped as dates, never as 86_400_000 milliseconds: Warsaw days are not all the same length and the arithmetic version drifts an hour twice a year, which would move somebody between buckets. """ firsts = { str(row["user_uuid"]): str(row["first_day"]) for row in conn.execute(FIRST_DAY_SQL, scope.params()) } if not firsts: return [] active: set[tuple[str, str]] = { (str(row["user_uuid"]), str(row["day"])) for row in conn.execute(ACTIVE_DAYS_SQL, scope.params()) } cohort = len(firsts) return [ ( offset, sum(1 for uuid, first in firsts.items() if (uuid, shift(first, offset)) in active), cohort, ) for offset in range(horizon + 1) ] def newcomers(conn: sqlite3.Connection, scope: Scope) -> list[tuple[str, int]]: """(day, how many people used the bot for the first time).""" return [ (str(row["day"]), int(row["people"])) for row in conn.execute(NEW_PEOPLE_SQL, scope.params()) ] def share_of_chat(conn: sqlite3.Connection, scope: Scope) -> Share: """What fraction of the group's messages were commands. Excludes the synthetic rows seeded from the pre-0.1.0 counter, which carry UNKNOWN_HOUR and no is_command flag -- counting them would put a whole day's messages in the denominator against no commands at all. """ # An aggregate SELECT returns one row even against an empty table, with # NULLs in it -- so there is no None to guard against, only the NULLs. row = conn.execute(SHARE_SQL, scope.params()).fetchone() return Share(messages=int(row["messages"] or 0), commands=int(row["commands"] or 0)) def around_releases( series: Sequence[tuple[str, int]], releases: Sequence[tuple[str, str]], span: int ) -> list[tuple[str, str, int, int]]: """(version, day, uses just after, uses just before) for each release. "Just after" is the release day and the ``span`` days following it; "just before" is the same number of days ending the day before. Equal windows, so the comparison means something even at the edges of a short history -- a release on the first recorded day gets a before-window of zero and reads as such rather than as a spike. """ counts = dict(series) out: list[tuple[str, str, int, int]] = [] for version, day in releases: after = sum(counts.get(shift(day, offset), 0) for offset in range(span + 1)) before = sum(counts.get(shift(day, -offset), 0) for offset in range(1, span + 1)) out.append((version, day, after, before)) return out