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>
This commit is contained in:
parent
7bd0a9aad4
commit
3e74ecd843
268 changed files with 17740 additions and 55423 deletions
309
server/services/srs.ts
Normal file
309
server/services/srs.ts
Normal file
|
|
@ -0,0 +1,309 @@
|
|||
/**
|
||||
* Spaced repetition with FSRS (the algorithm Anki adopted in 2023), via ts-fsrs.
|
||||
* Scheduling state lives on each card row; every review is logged so it can be undone
|
||||
* and analysed later.
|
||||
*/
|
||||
import { createEmptyCard, fsrs, Rating, State, type Card as FsrsCard, type Grade } from 'ts-fsrs';
|
||||
import type { DB } from '../db.ts';
|
||||
import { badRequest, notFound } from '../http.ts';
|
||||
import type { AppSettings } from '../settings.ts';
|
||||
import { DAY_MS, now as clock, parseJson, startOfDay } from '../util.ts';
|
||||
import { mapCard, type CardRow } from './content.ts';
|
||||
|
||||
export const LEARN_AHEAD_MS = 20 * 60_000;
|
||||
export type RatingValue = 1 | 2 | 3 | 4;
|
||||
export const RATING_LABELS: Record<RatingValue, string> = { 1: 'Again', 2: 'Hard', 3: 'Good', 4: 'Easy' };
|
||||
|
||||
const schedulers = new Map<string, ReturnType<typeof fsrs>>();
|
||||
function scheduler(retention: number, fuzz: boolean) {
|
||||
const key = `${retention}:${fuzz}`;
|
||||
let s = schedulers.get(key);
|
||||
if (!s) {
|
||||
s = fsrs({ request_retention: retention, enable_fuzz: fuzz, enable_short_term: true, maximum_interval: 36500 });
|
||||
schedulers.set(key, s);
|
||||
}
|
||||
return s;
|
||||
}
|
||||
|
||||
function toFsrs(row: CardRow, at: number): FsrsCard {
|
||||
if (row.state === State.New || row.due === null) return createEmptyCard(new Date(at));
|
||||
return {
|
||||
due: new Date(row.due),
|
||||
stability: row.stability,
|
||||
difficulty: row.difficulty,
|
||||
scheduled_days: row.scheduled_days,
|
||||
learning_steps: row.learning_steps,
|
||||
reps: row.reps,
|
||||
lapses: row.lapses,
|
||||
state: row.state as State,
|
||||
last_review: row.last_review ? new Date(row.last_review) : undefined,
|
||||
} as FsrsCard;
|
||||
}
|
||||
|
||||
export function intervalLabel(ms: number): string {
|
||||
if (ms < 60_000) return '<1m';
|
||||
const minutes = ms / 60_000;
|
||||
if (minutes < 60) return `${Math.round(minutes)}m`;
|
||||
const hours = minutes / 60;
|
||||
if (hours < 24) return `${Math.round(hours)}h`;
|
||||
const days = hours / 24;
|
||||
if (days < 30.5) return `${Math.round(days)}d`;
|
||||
const months = days / 30.44;
|
||||
if (months < 12) return `${months.toFixed(months < 3 ? 1 : 0).replace(/\.0$/, '')}mo`;
|
||||
return `${(days / 365.25).toFixed(1).replace(/\.0$/, '')}y`;
|
||||
}
|
||||
|
||||
export interface RatingPreview {
|
||||
rating: RatingValue;
|
||||
label: string;
|
||||
interval: string;
|
||||
due: number;
|
||||
}
|
||||
|
||||
export function previewRatings(row: CardRow, settings: AppSettings, at: number): RatingPreview[] {
|
||||
// Previews never use fuzz so the labels are stable while the card is on screen.
|
||||
const options = scheduler(settings.desiredRetention, false).repeat(toFsrs(row, at), new Date(at));
|
||||
return ([1, 2, 3, 4] as RatingValue[]).map((rating) => {
|
||||
const due = options[rating as Grade].card.due.getTime();
|
||||
return { rating, label: RATING_LABELS[rating], interval: intervalLabel(due - at), due };
|
||||
});
|
||||
}
|
||||
|
||||
export interface QueueScope {
|
||||
deckId?: string;
|
||||
classId?: string;
|
||||
}
|
||||
|
||||
function scopeSql(scope: QueueScope): { where: string; params: string[] } {
|
||||
if (scope.deckId) return { where: 'AND c.deck_id = ?', params: [scope.deckId] };
|
||||
if (scope.classId) return { where: 'AND d.class_id = ?', params: [scope.classId] };
|
||||
return { where: '', params: [] };
|
||||
}
|
||||
|
||||
const BASE = `FROM cards c JOIN decks d ON d.id = c.deck_id JOIN classes k ON k.id = d.class_id WHERE c.suspended = 0 AND k.archived = 0`;
|
||||
|
||||
export interface DueCounts {
|
||||
learning: number;
|
||||
review: number;
|
||||
new: number;
|
||||
total: number;
|
||||
}
|
||||
|
||||
/** New cards still allowed today under the global daily limit. */
|
||||
export function newCardsLeftToday(db: DB, settings: AppSettings, at: number): number {
|
||||
const since = startOfDay(at, settings.timezone);
|
||||
const introduced = db.get<{ n: number }>('SELECT COUNT(*) AS n FROM cards WHERE introduced_at >= ?', since)?.n ?? 0;
|
||||
return Math.max(0, settings.newCardsPerDay - introduced);
|
||||
}
|
||||
|
||||
export function dueCounts(db: DB, scope: QueueScope, settings: AppSettings, at = clock()): DueCounts {
|
||||
const { where, params } = scopeSql(scope);
|
||||
const endOfDay = startOfDay(at, settings.timezone) + DAY_MS;
|
||||
const row = db.get<{ learning: number; review: number; fresh: number }>(
|
||||
`SELECT
|
||||
COALESCE(SUM(CASE WHEN c.state IN (1,3) AND c.due <= ? THEN 1 ELSE 0 END), 0) AS learning,
|
||||
COALESCE(SUM(CASE WHEN c.state = 2 AND c.due < ? THEN 1 ELSE 0 END), 0) AS review,
|
||||
COALESCE(SUM(CASE WHEN c.state = 0 THEN 1 ELSE 0 END), 0) AS fresh
|
||||
${BASE} ${where}`,
|
||||
at + LEARN_AHEAD_MS,
|
||||
endOfDay,
|
||||
...params,
|
||||
)!;
|
||||
const fresh = Math.min(row.fresh, newCardsLeftToday(db, settings, at));
|
||||
return { learning: row.learning, review: row.review, new: fresh, total: row.learning + row.review + fresh };
|
||||
}
|
||||
|
||||
export interface QueueCard {
|
||||
card: ReturnType<typeof mapCard>;
|
||||
deckTitle: string;
|
||||
classId: string;
|
||||
className: string;
|
||||
classColor: string;
|
||||
previews: RatingPreview[];
|
||||
}
|
||||
|
||||
type JoinedRow = CardRow & { deck_title: string; class_id: string; class_name: string; class_color: string };
|
||||
const SELECT = `SELECT c.*, d.title AS deck_title, d.class_id AS class_id, k.name AS class_name, k.color AS class_color`;
|
||||
|
||||
function toQueueCard(row: JoinedRow, settings: AppSettings, at: number): QueueCard {
|
||||
return {
|
||||
card: mapCard(row),
|
||||
deckTitle: row.deck_title,
|
||||
classId: row.class_id,
|
||||
className: row.class_name,
|
||||
classColor: row.class_color,
|
||||
previews: previewRatings(row, settings, at),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Builds the study queue: learning cards first (they are time-critical), then reviews
|
||||
* due today with new cards spread evenly among them.
|
||||
*/
|
||||
export function buildQueue(db: DB, scope: QueueScope, settings: AppSettings, limit = 100, at = clock()): { cards: QueueCard[]; counts: DueCounts } {
|
||||
const { where, params } = scopeSql(scope);
|
||||
const endOfDay = startOfDay(at, settings.timezone) + DAY_MS;
|
||||
const learning = db.all<JoinedRow>(`${SELECT} ${BASE} ${where} AND c.state IN (1,3) AND c.due <= ? ORDER BY c.due LIMIT ?`, ...params, at + LEARN_AHEAD_MS, limit);
|
||||
const reviews = db.all<JoinedRow>(`${SELECT} ${BASE} ${where} AND c.state = 2 AND c.due < ? ORDER BY c.due LIMIT ?`, ...params, endOfDay, limit);
|
||||
const newLeft = newCardsLeftToday(db, settings, at);
|
||||
const fresh =
|
||||
newLeft > 0
|
||||
? db.all<JoinedRow>(
|
||||
`${SELECT} ${BASE} ${where} AND c.state = 0 ORDER BY k.sort_order, d.sort_order, d.created_at, c.sort_order, c.created_at LIMIT ?`,
|
||||
...params,
|
||||
Math.min(newLeft, limit),
|
||||
)
|
||||
: [];
|
||||
|
||||
const mixed: JoinedRow[] = [];
|
||||
const every = fresh.length > 0 ? Math.max(1, Math.floor(reviews.length / fresh.length)) : 0;
|
||||
let f = 0;
|
||||
reviews.forEach((r, i) => {
|
||||
mixed.push(r);
|
||||
if (every > 0 && (i + 1) % every === 0 && f < fresh.length) mixed.push(fresh[f++]);
|
||||
});
|
||||
while (f < fresh.length) mixed.push(fresh[f++]);
|
||||
|
||||
const cards = [...learning, ...mixed].slice(0, limit).map((r) => toQueueCard(r, settings, at));
|
||||
return { cards, counts: dueCounts(db, scope, settings, at) };
|
||||
}
|
||||
|
||||
const SCHEDULE_FIELDS = ['state', 'due', 'stability', 'difficulty', 'scheduled_days', 'learning_steps', 'reps', 'lapses', 'last_review', 'introduced_at'] as const;
|
||||
|
||||
export function answerCard(
|
||||
db: DB,
|
||||
cardId: string,
|
||||
rating: RatingValue,
|
||||
settings: AppSettings,
|
||||
opts: { at?: number; fuzz?: boolean } = {},
|
||||
): QueueCard {
|
||||
const at = opts.at ?? clock();
|
||||
const row = db.get<JoinedRow>(`${SELECT} FROM cards c JOIN decks d ON d.id = c.deck_id JOIN classes k ON k.id = d.class_id WHERE c.id = ?`, cardId);
|
||||
if (!row) throw notFound('Card');
|
||||
if (![1, 2, 3, 4].includes(rating)) throw badRequest('Rating must be 1-4');
|
||||
const result = scheduler(settings.desiredRetention, opts.fuzz ?? true).next(toFsrs(row, at), new Date(at), rating as Grade);
|
||||
const next = result.card;
|
||||
const prev: Record<string, unknown> = {};
|
||||
for (const f of SCHEDULE_FIELDS) prev[f] = row[f];
|
||||
db.tx(() => {
|
||||
db.run(
|
||||
`UPDATE cards SET state = ?, due = ?, stability = ?, difficulty = ?, scheduled_days = ?, learning_steps = ?, reps = ?, lapses = ?, last_review = ?,
|
||||
introduced_at = COALESCE(introduced_at, ?) WHERE id = ?`,
|
||||
next.state,
|
||||
next.due.getTime(),
|
||||
next.stability,
|
||||
next.difficulty,
|
||||
next.scheduled_days,
|
||||
next.learning_steps,
|
||||
next.reps,
|
||||
next.lapses,
|
||||
at,
|
||||
at,
|
||||
cardId,
|
||||
);
|
||||
db.run(
|
||||
'INSERT INTO reviews (card_id, deck_id, class_id, rating, state_before, scheduled_days, mode, prev, reviewed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)',
|
||||
cardId,
|
||||
row.deck_id,
|
||||
row.class_id,
|
||||
rating,
|
||||
row.state,
|
||||
next.scheduled_days,
|
||||
'srs',
|
||||
JSON.stringify(prev),
|
||||
at,
|
||||
);
|
||||
});
|
||||
const updated = db.get<JoinedRow>(`${SELECT} FROM cards c JOIN decks d ON d.id = c.deck_id JOIN classes k ON k.id = d.class_id WHERE c.id = ?`, cardId)!;
|
||||
return toQueueCard(updated, settings, at);
|
||||
}
|
||||
|
||||
/** Reverts the most recent scheduled review of a card and returns it to its previous state. */
|
||||
export function undoReview(db: DB, cardId: string, settings: AppSettings, at = clock()): QueueCard {
|
||||
const review = db.get<{ id: number; prev: string }>(`SELECT id, prev FROM reviews WHERE card_id = ? AND mode = 'srs' ORDER BY id DESC LIMIT 1`, cardId);
|
||||
if (!review || !review.prev) throw badRequest('Nothing to undo for this card');
|
||||
const prev = parseJson<Record<string, number | null>>(review.prev, {});
|
||||
db.tx(() => {
|
||||
db.run(
|
||||
`UPDATE cards SET state = ?, due = ?, stability = ?, difficulty = ?, scheduled_days = ?, learning_steps = ?, reps = ?, lapses = ?, last_review = ?, introduced_at = ? WHERE id = ?`,
|
||||
prev.state ?? 0,
|
||||
prev.due ?? null,
|
||||
prev.stability ?? 0,
|
||||
prev.difficulty ?? 0,
|
||||
prev.scheduled_days ?? 0,
|
||||
prev.learning_steps ?? 0,
|
||||
prev.reps ?? 0,
|
||||
prev.lapses ?? 0,
|
||||
prev.last_review ?? null,
|
||||
prev.introduced_at ?? null,
|
||||
cardId,
|
||||
);
|
||||
db.run('DELETE FROM reviews WHERE id = ?', review.id);
|
||||
});
|
||||
const row = db.get<JoinedRow>(`${SELECT} FROM cards c JOIN decks d ON d.id = c.deck_id JOIN classes k ON k.id = d.class_id WHERE c.id = ?`, cardId);
|
||||
if (!row) throw notFound('Card');
|
||||
return toQueueCard(row, settings, at);
|
||||
}
|
||||
|
||||
export function resetCards(db: DB, where: { cardId?: string; deckId?: string }): number {
|
||||
const sql = `UPDATE cards SET state = 0, due = NULL, stability = 0, difficulty = 0, scheduled_days = 0, learning_steps = 0, reps = 0, lapses = 0, last_review = NULL, introduced_at = NULL WHERE `;
|
||||
if (where.cardId) return db.run(`${sql} id = ?`, where.cardId).changes;
|
||||
if (where.deckId) return db.run(`${sql} deck_id = ?`, where.deckId).changes;
|
||||
return 0;
|
||||
}
|
||||
|
||||
/** Logs a self-graded cram flip so it counts toward activity without touching the schedule. */
|
||||
export function logCram(db: DB, cardId: string, known: boolean, at = clock()): void {
|
||||
const row = db.get<{ deck_id: string; class_id: string; state: number }>(
|
||||
'SELECT c.deck_id, d.class_id, c.state FROM cards c JOIN decks d ON d.id = c.deck_id WHERE c.id = ?',
|
||||
cardId,
|
||||
);
|
||||
if (!row) return;
|
||||
db.run(
|
||||
`INSERT INTO reviews (card_id, deck_id, class_id, rating, state_before, scheduled_days, mode, prev, reviewed_at) VALUES (?, ?, ?, ?, ?, 0, 'cram', '', ?)`,
|
||||
cardId,
|
||||
row.deck_id,
|
||||
row.class_id,
|
||||
known ? Rating.Good : Rating.Again,
|
||||
row.state,
|
||||
at,
|
||||
);
|
||||
}
|
||||
|
||||
export interface DeckStats {
|
||||
total: number;
|
||||
new: number;
|
||||
learning: number;
|
||||
young: number;
|
||||
mature: number;
|
||||
suspended: number;
|
||||
dueNow: number;
|
||||
}
|
||||
|
||||
export function deckStats(db: DB, deckId: string, settings: AppSettings, at = clock()): DeckStats {
|
||||
const endOfDay = startOfDay(at, settings.timezone) + DAY_MS;
|
||||
const r = db.get<Record<string, number>>(
|
||||
`SELECT COUNT(*) AS total,
|
||||
COALESCE(SUM(suspended), 0) AS suspended,
|
||||
COALESCE(SUM(CASE WHEN suspended = 0 AND state = 0 THEN 1 ELSE 0 END), 0) AS fresh,
|
||||
COALESCE(SUM(CASE WHEN suspended = 0 AND state IN (1,3) THEN 1 ELSE 0 END), 0) AS learning,
|
||||
COALESCE(SUM(CASE WHEN suspended = 0 AND state = 2 AND scheduled_days < 21 THEN 1 ELSE 0 END), 0) AS young,
|
||||
COALESCE(SUM(CASE WHEN suspended = 0 AND state = 2 AND scheduled_days >= 21 THEN 1 ELSE 0 END), 0) AS mature,
|
||||
COALESCE(SUM(CASE WHEN suspended = 0 AND ((state IN (1,3) AND due <= ?) OR (state = 2 AND due < ?)) THEN 1 ELSE 0 END), 0) AS due_now
|
||||
FROM cards WHERE deck_id = ?`,
|
||||
at + LEARN_AHEAD_MS,
|
||||
endOfDay,
|
||||
deckId,
|
||||
)!;
|
||||
return { total: r.total, new: r.fresh, learning: r.learning, young: r.young, mature: r.mature, suspended: r.suspended, dueNow: r.due_now };
|
||||
}
|
||||
|
||||
/** Reviews coming due per day for the next `days` days (index 0 = today, including overdue). */
|
||||
export function forecast(db: DB, scope: QueueScope, settings: AppSettings, days = 14, at = clock()): number[] {
|
||||
const { where, params } = scopeSql(scope);
|
||||
const start = startOfDay(at, settings.timezone);
|
||||
const rows = db.all<{ due: number }>(`SELECT c.due AS due ${BASE} ${where} AND c.state != 0 AND c.due < ?`, ...params, start + days * DAY_MS);
|
||||
const out = new Array<number>(days).fill(0);
|
||||
for (const r of rows) out[Math.max(0, Math.min(days - 1, Math.floor((r.due - start) / DAY_MS)))] += 1;
|
||||
return out;
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue