Study/server/routes/study.ts
Elijah ccdad9728b
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 33s
Add drag reordering, exam deadlines, frozen shared quizzes, batched OCR and semantic search
- Drag-to-reorder for class materials, folders, quiz questions and deck cards. Pointer-based
  so touch works, plus keyboard (arrows/Home/End) with screen-reader announcements.
- Timed exams get a wall-clock deadline. The server refuses late answers, submits overdue
  exams with what was saved, and the countdown keeps running while the page is closed.
- Shared quiz sessions keep a frozen copy of their questions and flag later owner edits.
- Scanned PDFs are read in cached 8-page batches with real page numbers (pdf-lib), removing
  the 30 MB whole-file limit. Compatible providers now receive PDFs as file parts.
- Semantic search: embeddings for OpenAI, Gemini, Ollama and compatible servers, background
  indexing into chunk_vectors (migration 2), hybrid keyword + vector ranking for search, the
  assistant and focused generation, and a Settings -> AI section.

181 tests pass locally and in the Docker test stage on Node 24.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 11:48:20 -07:00

221 lines
10 KiB
TypeScript

import { Hono } from 'hono';
import { getEmbeddingSettings, semanticSearch } from '../services/semantic.ts';
import { z } from 'zod';
import { badRequest, idParam, readBody, type AppContext } from '../http.ts';
import { getAppSettings } from '../settings.ts';
import {
attemptCreateSchema,
attemptPatchSchema,
completeAttempt,
createAttempt,
deleteAttempt,
getAttempt,
listAttempts,
missedQuestionIds,
patchAttempt,
} from '../services/attempts.ts';
import { answerCard, buildQueue, dueCounts, forecast, logCram, undoReview, type RatingValue } from '../services/srs.ts';
import { accuracyTrend, activityByDay, computeStreak, topicStats, totals, weakTopics } from '../services/stats.ts';
import { ftsQuery } from '../util.ts';
export function studyRoutes(app: AppContext): Hono {
const { db } = app;
const r = new Hono();
const settings = () => getAppSettings(db, app.config.timezone);
/* ------------------------------ quiz sessions ------------------------------ */
r.post('/attempts', async (c) => {
const body = await readBody(c, attemptCreateSchema);
const id = createAttempt(db, body, settings().sataScoring);
return c.json({ attempt: getAttempt(db, id) }, 201);
});
r.get('/attempts', (c) => {
const status = c.req.query('status');
return c.json({
attempts: listAttempts(db, {
status: status === 'active' || status === 'completed' ? status : undefined,
quizId: c.req.query('quizId') || undefined,
classId: c.req.query('classId') || undefined,
limit: Number(c.req.query('limit') ?? 50) || 50,
}),
});
});
r.get('/attempts/:id', (c) => c.json({ attempt: getAttempt(db, idParam(c)) }));
r.patch('/attempts/:id', async (c) => {
const body = await readBody(c, attemptPatchSchema);
return c.json({ attempt: patchAttempt(db, idParam(c), body) });
});
r.post('/attempts/:id/complete', async (c) => {
const body = (await c.req.json().catch(() => ({}))) as { elapsedSec?: unknown };
const elapsed = typeof body.elapsedSec === 'number' && Number.isFinite(body.elapsedSec) ? Math.max(0, Math.round(body.elapsedSec)) : undefined;
return c.json({ attempt: completeAttempt(db, idParam(c), elapsed) });
});
r.delete('/attempts/:id', (c) => {
deleteAttempt(db, idParam(c));
return c.json({ ok: true });
});
/* ------------------------------ spaced repetition ------------------------------ */
r.get('/review/queue', (c) => {
const scope = { deckId: c.req.query('deckId') || undefined, classId: c.req.query('classId') || undefined };
const limit = Math.min(Number(c.req.query('limit') ?? 100) || 100, 300);
return c.json(buildQueue(db, scope, settings(), limit));
});
r.post('/review/answer', async (c) => {
const body = await readBody(c, z.object({ cardId: z.string(), rating: z.number().int().min(1).max(4) }));
return c.json({ result: answerCard(db, body.cardId, body.rating as RatingValue, settings()) });
});
r.post('/review/undo', async (c) => {
const body = await readBody(c, z.object({ cardId: z.string() }));
return c.json({ result: undoReview(db, body.cardId, settings()) });
});
r.post('/review/cram', async (c) => {
const body = await readBody(c, z.object({ cardId: z.string(), known: z.boolean() }));
logCram(db, body.cardId, body.known);
return c.json({ ok: true });
});
/* ------------------------------ dashboards ------------------------------ */
r.get('/overview', (c) => {
const s = settings();
const days = activityByDay(db, s, 26 * 7);
return c.json({
settings: s,
due: dueCounts(db, {}, s),
streak: computeStreak(days, s.dailyGoal),
activity: days,
activeAttempts: listAttempts(db, { status: 'active', limit: 6 }),
recentAttempts: listAttempts(db, { status: 'completed', limit: 6 }),
weakTopics: weakTopics(db, {}, 6),
missedCount: missedQuestionIds(db, {}, 500).length,
totals: totals(db, s, {}, 7),
forecast: forecast(db, {}, s, 7),
});
});
r.get('/insights', (c) => {
const s = settings();
const classId = c.req.query('classId') || undefined;
const range = Math.min(Math.max(Number(c.req.query('days') ?? 30) || 30, 7), 365);
const scope = { classId };
const days = activityByDay(db, s, 53 * 7, scope);
return c.json({
range,
totals: totals(db, s, scope, range),
streak: computeStreak(activityByDay(db, s, 53 * 7), s.dailyGoal),
activity: days,
accuracy: accuracyTrend(db, s, range, scope),
topics: topicStats(db, scope, range),
forecast: forecast(db, scope, s, 14),
due: dueCounts(db, scope, s),
missedCount: missedQuestionIds(db, scope, 500).length,
recentAttempts: listAttempts(db, { status: 'completed', classId, limit: 15 }),
});
});
/* ------------------------------ search ------------------------------ */
r.get('/search', async (c) => {
const q = (c.req.query('q') ?? '').trim().slice(0, 120);
if (q.length < 2) return c.json({ query: q, results: [] });
const like = `%${q.replace(/[\\%_]/g, (m) => `\\${m}`)}%`;
const classId = c.req.query('classId') || null;
const scoped = (col: string) => (classId ? `AND ${col} = ?` : '');
const p = (...base: string[]) => (classId ? [...base, classId] : base);
type Hit = { kind: string; id: string; title: string; snippet: string; classId: string; className: string; classColor: string; parentId?: string; page?: number | null; semantic?: boolean };
const results: Hit[] = [];
for (const row of db.all<Record<string, string>>(`SELECT id, name, color FROM classes WHERE name LIKE ? ESCAPE '\\' OR code LIKE ? ESCAPE '\\' LIMIT 5`, like, like)) {
results.push({ kind: 'class', id: row.id, title: row.name, snippet: '', classId: row.id, className: row.name, classColor: row.color });
}
const simple = (kind: string, table: string) => {
for (const row of db.all<Record<string, string>>(
`SELECT t.id, t.title, k.id AS class_id, k.name AS class_name, k.color AS class_color FROM ${table} t JOIN classes k ON k.id = t.class_id
WHERE t.title LIKE ? ESCAPE '\\' ${scoped('t.class_id')} ORDER BY t.updated_at DESC LIMIT 8`,
...p(like),
)) {
results.push({ kind, id: row.id, title: row.title, snippet: '', classId: row.class_id, className: row.class_name, classColor: row.class_color });
}
};
simple('quiz', 'quizzes');
simple('deck', 'decks');
simple('note', 'notes');
simple('document', 'documents');
for (const row of db.all<Record<string, string>>(
`SELECT q.id, q.stem, z.id AS quiz_id, z.title AS quiz_title, k.id AS class_id, k.name AS class_name, k.color AS class_color
FROM questions q JOIN quizzes z ON z.id = q.quiz_id JOIN classes k ON k.id = z.class_id
WHERE (q.stem LIKE ? ESCAPE '\\' OR q.topic LIKE ? ESCAPE '\\') ${scoped('z.class_id')} LIMIT 10`,
...p(like, like),
)) {
results.push({ kind: 'question', id: row.id, parentId: row.quiz_id, title: row.stem.slice(0, 140), snippet: row.quiz_title, classId: row.class_id, className: row.class_name, classColor: row.class_color });
}
for (const row of db.all<Record<string, string>>(
`SELECT c.id, c.front, c.back, d.id AS deck_id, d.title AS deck_title, k.id AS class_id, k.name AS class_name, k.color AS class_color
FROM cards c JOIN decks d ON d.id = c.deck_id JOIN classes k ON k.id = d.class_id
WHERE (c.front LIKE ? ESCAPE '\\' OR c.back LIKE ? ESCAPE '\\') ${scoped('d.class_id')} LIMIT 10`,
...p(like, like),
)) {
results.push({ kind: 'card', id: row.id, parentId: row.deck_id, title: row.front.slice(0, 140), snippet: row.deck_title, classId: row.class_id, className: row.class_name, classColor: row.class_color });
}
const match = ftsQuery(q, 'and');
if (match) {
try {
for (const row of db.all<Record<string, any>>(
`SELECT ch.id, ch.page_start, d.id AS doc_id, d.title AS doc_title, k.id AS class_id, k.name AS class_name, k.color AS class_color,
snippet(chunks_fts, 0, '', '', ' … ', 18) AS snip
FROM chunks_fts JOIN chunks ch ON ch.id = chunks_fts.rowid JOIN documents d ON d.id = ch.document_id JOIN classes k ON k.id = d.class_id
WHERE chunks_fts MATCH ? ${scoped('d.class_id')} ORDER BY bm25(chunks_fts) LIMIT 10`,
...p(match),
)) {
results.push({ kind: 'passage', id: String(row.id), parentId: row.doc_id, page: row.page_start, title: row.doc_title, snippet: row.snip, classId: row.class_id, className: row.class_name, classColor: row.class_color });
}
} catch {
/* a malformed FTS query should never break search */
}
}
// Passages that match the meaning rather than the words (when semantic search is set up).
// Only for phrases or longer terms: single short words are already well served by keywords.
if ((/\s/.test(q) || q.length >= 8) && getEmbeddingSettings(db).providerId) {
try {
const seen = new Set(results.filter((r) => r.kind === 'passage').map((r) => r.id));
for (const hit of await semanticSearch(app, q, { classId }, 6, 0.35)) {
if (seen.has(String(hit.id))) continue;
const doc = db.get<Record<string, string>>(
'SELECT k.id AS class_id, k.name AS class_name, k.color AS class_color FROM documents d JOIN classes k ON k.id = d.class_id WHERE d.id = ?',
hit.documentId,
);
if (!doc) continue;
const text = hit.text.replace(/\s+/g, ' ').trim();
results.push({ kind: 'passage', id: String(hit.id), parentId: hit.documentId, page: hit.pageStart, title: hit.documentTitle, snippet: text.length > 160 ? `${text.slice(0, 160)} …` : text, classId: doc.class_id, className: doc.class_name, classColor: doc.class_color, semantic: true });
}
} catch (err) {
app.log('warn', `Semantic search failed: ${err instanceof Error ? err.message : String(err)}`);
}
}
return c.json({ query: q, results });
});
r.get('/topics', (c) => {
const classId = c.req.query('classId');
if (!classId) throw badRequest('classId is required');
const rows = db.all<{ topic: string; n: number }>(
`SELECT q.topic AS topic, COUNT(*) AS n FROM questions q JOIN quizzes z ON z.id = q.quiz_id WHERE z.class_id = ? AND q.topic != '' GROUP BY q.topic ORDER BY n DESC`,
classId,
);
return c.json({ topics: rows });
});
return r;
}