Study/server/services/stats.ts
Elijah 3e74ecd843 Start Study Desk V2: remove V1 sources, add backend foundation
V1 remains intact on main and in history. This branch replaces it with a new
application: node:sqlite storage with migrations, scrypt auth and sessions,
content/SRS/attempt/stats services, document extraction and chunking, a
provider-neutral AI layer (OpenAI, Anthropic, Gemini, OpenAI-compatible,
Ollama), the generation pipeline and the tool-using assistant.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-11 08:16:41 -07:00

185 lines
7.4 KiB
TypeScript

/** Study activity, streaks, accuracy and weak-topic analytics. All derived from the review and response logs. */
import type { DB } from '../db.ts';
import type { AppSettings } from '../settings.ts';
import { addDaysToKey, DAY_MS, dayKey, now as clock, startOfDay } from '../util.ts';
export interface DayActivity {
date: string;
cards: number;
questions: number;
total: number;
}
/** Per-day totals for the trailing `days` days (oldest first, always dense). */
export function activityByDay(db: DB, settings: AppSettings, days: number, scope: { classId?: string } = {}, at = clock()): DayActivity[] {
const tz = settings.timezone;
const today = dayKey(at, tz);
const since = startOfDay(at, tz) - (days - 1) * DAY_MS - DAY_MS; // one extra day absorbs DST shifts
const map = new Map<string, DayActivity>();
const bump = (ts: number, field: 'cards' | 'questions') => {
const key = dayKey(ts, tz);
let d = map.get(key);
if (!d) {
d = { date: key, cards: 0, questions: 0, total: 0 };
map.set(key, d);
}
d[field] += 1;
d.total += 1;
};
const cls = scope.classId ? 'AND class_id = ?' : '';
const p = scope.classId ? [scope.classId] : [];
for (const r of db.all<{ t: number }>(`SELECT reviewed_at AS t FROM reviews WHERE reviewed_at >= ? ${cls}`, since, ...p)) bump(r.t, 'cards');
for (const r of db.all<{ t: number }>(`SELECT answered_at AS t FROM responses WHERE answered_at >= ? ${cls}`, since, ...p)) bump(r.t, 'questions');
const out: DayActivity[] = [];
for (let i = days - 1; i >= 0; i -= 1) {
const key = addDaysToKey(today, -i);
out.push(map.get(key) ?? { date: key, cards: 0, questions: 0, total: 0 });
}
return out;
}
export interface Streak {
current: number;
longest: number;
/** Today already meets the daily goal. */
todayDone: boolean;
todayTotal: number;
goal: number;
}
export function computeStreak(days: DayActivity[], goal: number): Streak {
const met = days.map((d) => d.total >= goal);
const todayDone = met[met.length - 1] ?? false;
let current = 0;
// Today only counts once the goal is met; an unfinished today does not break yesterday's streak.
for (let i = met.length - (todayDone ? 1 : 2); i >= 0 && met[i]; i -= 1) current += 1;
let longest = 0;
let run = 0;
for (const m of met) {
run = m ? run + 1 : 0;
longest = Math.max(longest, run);
}
return { current, longest, todayDone, todayTotal: days[days.length - 1]?.total ?? 0, goal };
}
export interface TopicStat {
topic: string;
classId: string | null;
className: string;
classColor: string;
seen: number;
accuracy: number;
/** Distinct questions available on this topic right now. */
questions: number;
}
/** Accuracy per topic over the trailing window. Topics need a few answers before they count. */
export function topicStats(db: DB, scope: { classId?: string }, windowDays = 90, at = clock()): TopicStat[] {
const since = at - windowDays * DAY_MS;
const cls = scope.classId ? 'AND r.class_id = ?' : '';
const p = scope.classId ? [scope.classId] : [];
const rows = db.all<{ topic: string; class_id: string | null; class_name: string | null; class_color: string | null; seen: number; acc: number; questions: number }>(
`SELECT r.topic AS topic, r.class_id AS class_id, k.name AS class_name, k.color AS class_color,
COUNT(*) AS seen, AVG(r.score) AS acc,
(SELECT COUNT(*) FROM questions q JOIN quizzes z ON z.id = q.quiz_id WHERE q.topic = r.topic AND z.class_id = r.class_id) AS questions
FROM responses r LEFT JOIN classes k ON k.id = r.class_id
WHERE r.answered_at >= ? AND r.topic != '' ${cls}
GROUP BY r.topic, r.class_id
ORDER BY acc ASC, seen DESC`,
since,
...p,
);
return rows.map((r) => ({
topic: r.topic,
classId: r.class_id,
className: r.class_name ?? '',
classColor: r.class_color ?? 'slate',
seen: r.seen,
accuracy: r.acc,
questions: r.questions,
}));
}
export function weakTopics(db: DB, scope: { classId?: string }, limit = 6): TopicStat[] {
return topicStats(db, scope)
.filter((t) => t.seen >= 3 && t.accuracy < 0.75 && t.questions > 0)
.slice(0, limit);
}
export interface QuestionStat {
seen: number;
correct: number;
lastCorrect: boolean;
}
export function questionStats(db: DB, quizId: string): Record<string, QuestionStat> {
const rows = db.all<{ question_id: string; seen: number; correct: number; last_correct: number }>(
`SELECT r.question_id, COUNT(*) AS seen, SUM(r.correct) AS correct,
(SELECT r2.correct FROM responses r2 WHERE r2.question_id = r.question_id ORDER BY r2.answered_at DESC LIMIT 1) AS last_correct
FROM responses r JOIN questions q ON q.id = r.question_id WHERE q.quiz_id = ? GROUP BY r.question_id`,
quizId,
);
return Object.fromEntries(rows.map((r) => [r.question_id, { seen: r.seen, correct: r.correct, lastCorrect: Boolean(r.last_correct) }]));
}
export interface AccuracyPoint {
date: string;
answered: number;
accuracy: number | null;
}
export function accuracyTrend(db: DB, settings: AppSettings, days: number, scope: { classId?: string } = {}, at = clock()): AccuracyPoint[] {
const tz = settings.timezone;
const since = startOfDay(at, tz) - days * DAY_MS;
const cls = scope.classId ? 'AND class_id = ?' : '';
const p = scope.classId ? [scope.classId] : [];
const sums = new Map<string, { n: number; s: number }>();
for (const r of db.all<{ t: number; score: number }>(`SELECT answered_at AS t, score FROM responses WHERE answered_at >= ? ${cls}`, since, ...p)) {
const key = dayKey(r.t, tz);
const cur = sums.get(key) ?? { n: 0, s: 0 };
cur.n += 1;
cur.s += r.score;
sums.set(key, cur);
}
const today = dayKey(at, tz);
const out: AccuracyPoint[] = [];
for (let i = days - 1; i >= 0; i -= 1) {
const key = addDaysToKey(today, -i);
const v = sums.get(key);
out.push({ date: key, answered: v?.n ?? 0, accuracy: v ? v.s / v.n : null });
}
return out;
}
export interface Totals {
questionsAnswered: number;
accuracy: number | null;
cardsReviewed: number;
retention: number | null;
quizzesCompleted: number;
studyDays: number;
}
export function totals(db: DB, settings: AppSettings, scope: { classId?: string } = {}, windowDays = 30, at = clock()): Totals {
const since = at - windowDays * DAY_MS;
const cls = scope.classId ? 'AND class_id = ?' : '';
const p = scope.classId ? [scope.classId] : [];
const resp = db.get<{ n: number; acc: number | null }>(`SELECT COUNT(*) AS n, AVG(score) AS acc FROM responses WHERE answered_at >= ? ${cls}`, since, ...p)!;
const rev = db.get<{ n: number }>(`SELECT COUNT(*) AS n FROM reviews WHERE reviewed_at >= ? ${cls}`, since, ...p)!;
// Retention: share of reviews of already-learned cards that were remembered (not "Again").
const ret = db.get<{ n: number; ok: number | null }>(
`SELECT COUNT(*) AS n, SUM(CASE WHEN rating > 1 THEN 1 ELSE 0 END) AS ok FROM reviews WHERE reviewed_at >= ? AND mode = 'srs' AND state_before = 2 ${cls}`,
since,
...p,
)!;
const done = db.get<{ n: number }>(`SELECT COUNT(*) AS n FROM attempts WHERE status = 'completed' AND completed_at >= ? ${cls}`, since, ...p)!;
const days = activityByDay(db, settings, windowDays, scope, at).filter((d) => d.total > 0).length;
return {
questionsAnswered: resp.n,
accuracy: resp.n > 0 ? resp.acc : null,
cardsReviewed: rev.n,
retention: ret.n >= 5 ? (ret.ok ?? 0) / ret.n : null,
quizzesCompleted: done.n,
studyDays: days,
};
}