Study/server/routes/ai.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

297 lines
13 KiB
TypeScript

import { Hono, type Context } from 'hono';
import { streamSSE } from 'hono/streaming';
import { z } from 'zod';
import { assistantRequestSchema, displayMessages, listConversations, resolveAction, runAssistantTurn, type AssistantEvent } from '../ai/assistant.ts';
import {
cancelGeneration,
createDraft,
discardDraft,
draftSaveSchema,
generateRequestSchema,
getDraft,
improveRequestSchema,
listDrafts,
saveDraft,
startGeneration,
startImprove,
updateDraftPayload,
} from '../ai/generate.ts';
import { CATALOG_UPDATED, listAdapterMeta } from '../ai/providers/index.ts';
import {
addManualModel,
aiStatus,
deleteModel,
deleteProvider,
discoverModels,
getTaskSettings,
listModels,
listProviders,
manualModelSchema,
modelPatchSchema,
patchModel,
providerInputSchema,
runChat,
saveProvider,
saveTaskSettings,
TASK_INFO,
testProvider,
usageSummary,
} from '../ai/service.ts';
import { embedTexts, embeddingSettingsSchema, getEmbeddingSettings, embeddingStatus, rebuildIndex, saveEmbeddingSettings, scheduleIndexing } from '../services/semantic.ts';
import { AIError } from '../ai/types.ts';
import { badRequest, idParam, notFound, readBody, type AppContext } from '../http.ts';
type Emit<T> = (event: T) => void;
/** Server-sent events with ordered writes, keep-alive pings and abort propagation. */
function sse<T extends { type: string }>(c: Context, run: (emit: Emit<T>, signal: AbortSignal) => Promise<void>) {
c.header('X-Accel-Buffering', 'no');
c.header('Cache-Control', 'no-cache, no-transform');
return streamSSE(c, async (stream) => {
const controller = new AbortController();
stream.onAbort(() => controller.abort());
let chain: Promise<unknown> = Promise.resolve();
const emit = (event: T | { type: 'ping' }) => {
chain = chain.then(() => stream.writeSSE({ data: JSON.stringify(event) })).catch(() => undefined);
};
const ping = setInterval(() => emit({ type: 'ping' }), 15_000);
try {
await run(emit, controller.signal);
} finally {
clearInterval(ping);
await chain;
}
});
}
const contentDraftSchema = z.discriminatedUnion('kind', [
z.object({
kind: z.literal('quiz'),
title: z.string().max(200),
description: z.string().max(4000).optional().default(''),
questions: z
.array(
z.object({
type: z.enum(['single', 'multi']),
stem: z.string().max(20000),
options: z.array(z.object({ text: z.string().max(4000), correct: z.boolean(), why: z.string().max(20000).optional() })).max(12),
rationale: z.string().max(20000).optional().default(''),
topic: z.string().max(80).optional().default(''),
difficulty: z.enum(['easy', 'medium', 'hard']).optional().default('medium'),
tags: z.array(z.string().max(40)).max(12).optional().default([]),
source: z.string().max(300).optional(),
}),
)
.max(1000),
}),
z.object({
kind: z.literal('deck'),
title: z.string().max(200),
description: z.string().max(4000).optional().default(''),
cards: z.array(z.object({ front: z.string().max(20000), back: z.string().max(20000), hint: z.string().max(20000).optional(), tags: z.array(z.string().max(40)).max(12).optional().default([]) })).max(5000),
}),
z.object({ kind: z.literal('note'), title: z.string().max(200), content: z.string().max(400000) }),
]);
const EXPLAIN_SYSTEM = `You are a patient nursing instructor helping a student while they study. Explain clearly and briefly (aim for under 200 words unless asked for more).
Use Markdown. Lead with the key idea, explain the reasoning, and connect it to patient care. If answer choices are given, say why the correct one is right and, in a line each, why the others are wrong. Do not restate the whole question.`;
export function aiRoutes(app: AppContext): Hono {
const { db } = app;
const r = new Hono();
/* ------------------------------ configuration ------------------------------ */
r.get('/ai/meta', (c) => c.json({ adapters: listAdapterMeta(), tasks: TASK_INFO, catalogUpdated: CATALOG_UPDATED }));
r.get('/ai/status', (c) => c.json(aiStatus(app)));
r.get('/ai/providers', (c) => c.json({ providers: listProviders(app) }));
r.post('/ai/providers', async (c) => c.json({ provider: saveProvider(app, null, await readBody(c, providerInputSchema)) }, 201));
r.patch('/ai/providers/:id', async (c) => c.json({ provider: saveProvider(app, idParam(c), await readBody(c, providerInputSchema)) }));
r.delete('/ai/providers/:id', (c) => {
const id = idParam(c);
deleteProvider(app, id);
// Semantic search cannot keep using a provider that no longer exists.
if (getEmbeddingSettings(db).providerId === id) saveEmbeddingSettings(app, { providerId: null, model: '', dimensions: null });
return c.json({ ok: true });
});
r.post('/ai/providers/:id/test', async (c) => c.json({ result: await testProvider(app, idParam(c)) }));
r.post('/ai/providers/:id/discover', async (c) => {
const result = await discoverModels(app, idParam(c));
return c.json({ ...result, models: listModels(db) });
});
r.get('/ai/models', (c) => c.json({ models: listModels(db) }));
r.post('/ai/models', async (c) => c.json({ model: addManualModel(app, await readBody(c, manualModelSchema)) }, 201));
r.patch('/ai/models/:id', async (c) => c.json({ model: patchModel(db, idParam(c), await readBody(c, modelPatchSchema)) }));
r.delete('/ai/models/:id', (c) => {
deleteModel(db, idParam(c));
return c.json({ ok: true });
});
r.get('/ai/tasks', (c) => c.json({ tasks: getTaskSettings(db) }));
r.put('/ai/tasks', async (c) => c.json({ tasks: saveTaskSettings(db, await c.req.json().catch(() => ({}))) }));
r.get('/ai/usage', (c) => c.json(usageSummary(db, Math.min(Math.max(Number(c.req.query('days') ?? 30) || 30, 1), 365))));
/* ------------------------------ generation + drafts ------------------------------ */
r.post('/ai/generate', async (c) => {
const body = await readBody(c, generateRequestSchema);
const { draftId } = startGeneration(app, body);
return c.json({ draftId }, 202);
});
r.post('/ai/improve', async (c) => {
const body = await readBody(c, improveRequestSchema);
const { draftId } = startImprove(app, body);
return c.json({ draftId }, 202);
});
r.get('/drafts', (c) => c.json({ drafts: listDrafts(db) }));
/** A blank or pre-filled draft, used by the import preview so imports and AI output share one review screen. */
r.post('/drafts', async (c) => {
const body = await readBody(c, z.object({ payload: contentDraftSchema, classId: z.string().nullish(), folderId: z.string().nullish() }));
const id = createDraft(db, { kind: body.payload.kind, classId: body.classId ?? null, folderId: body.folderId ?? null, title: body.payload.title, payload: body.payload as never, meta: { origin: 'import' } });
return c.json({ draft: getDraft(db, id) }, 201);
});
r.get('/drafts/:id', (c) => c.json({ draft: getDraft(db, idParam(c)) }));
r.put('/drafts/:id', async (c) => {
const body = await readBody(c, z.object({ payload: contentDraftSchema, classId: z.string().nullish(), folderId: z.string().nullish() }));
return c.json({ draft: updateDraftPayload(db, idParam(c), body.payload as never, { classId: body.classId, folderId: body.folderId }) });
});
r.post('/drafts/:id/save', async (c) => {
const body = await readBody(c, draftSaveSchema);
return c.json({ saved: saveDraft(app, idParam(c), body) });
});
r.post('/drafts/:id/cancel', (c) => {
cancelGeneration(idParam(c));
return c.json({ ok: true });
});
r.delete('/drafts/:id', (c) => {
discardDraft(db, idParam(c));
return c.json({ ok: true });
});
/* ------------------------------ assistant ------------------------------ */
r.post('/ai/chat', async (c) => {
const body = await readBody(c, assistantRequestSchema);
return sse<AssistantEvent>(c, async (emit, signal) => {
try {
await runAssistantTurn(app, body, emit, signal);
} catch (err) {
// Failures before the turn starts (no model configured, bad input) still reach the client as an event.
const ai = err instanceof AIError ? err : null;
if (!ai) app.log('error', 'Assistant request failed', err);
emit({ type: 'error', code: ai?.code ?? 'server', message: ai?.message ?? 'The assistant could not start.', detail: ai?.providerMessage });
emit({ type: 'done', conversationId: body.conversationId ?? '', title: '' });
}
});
});
r.get('/ai/conversations', (c) => c.json({ conversations: listConversations(db) }));
r.get('/ai/conversations/:id', (c) => {
const id = idParam(c);
const row = db.get<{ id: string; title: string; class_id: string | null }>('SELECT id, title, class_id FROM conversations WHERE id = ?', id);
if (!row) throw notFound('Conversation');
return c.json({ conversation: { id: row.id, title: row.title, classId: row.class_id }, messages: displayMessages(db, id) });
});
r.delete('/ai/conversations/:id', (c) => {
const { changes } = db.run('DELETE FROM conversations WHERE id = ?', idParam(c));
if (!changes) throw notFound('Conversation');
return c.json({ ok: true });
});
r.post('/ai/actions/:id', async (c) => {
const body = await readBody(c, z.object({ confirm: z.boolean() }));
return c.json(resolveAction(app, idParam(c), body.confirm));
});
/* ------------------------------ inline explanations ------------------------------ */
const explainSchema = z.discriminatedUnion('kind', [
z.object({
kind: z.literal('question'),
stem: z.string().max(20000),
options: z.array(z.object({ text: z.string().max(4000), correct: z.boolean() })).max(12),
selected: z.array(z.string().max(4000)).max(12).optional(),
rationale: z.string().max(20000).optional(),
ask: z.string().max(2000).optional(),
}),
z.object({ kind: z.literal('card'), front: z.string().max(20000), back: z.string().max(20000), ask: z.string().max(2000).optional() }),
z.object({ kind: z.literal('text'), text: z.string().max(40000), ask: z.string().max(2000).optional() }),
]);
r.post('/ai/explain', async (c) => {
const body = await readBody(c, explainSchema);
let prompt: string;
if (body.kind === 'question') {
prompt = [
`Question:\n${body.stem}`,
`Choices:\n${body.options.map((o) => `- ${o.text}${o.correct ? ' (correct)' : ''}`).join('\n')}`,
body.selected?.length ? `The student chose: ${body.selected.join('; ')}` : '',
body.rationale ? `Existing rationale:\n${body.rationale}` : '',
body.ask ? `The student asks: ${body.ask}` : 'Explain this question so it finally makes sense. If the student chose wrongly, address the misunderstanding behind their choice.',
]
.filter(Boolean)
.join('\n\n');
} else if (body.kind === 'card') {
prompt = `Flashcard front:\n${body.front}\n\nFlashcard back:\n${body.back}\n\n${body.ask ? `The student asks: ${body.ask}` : 'Explain this card in more depth and give one way to remember it.'}`;
} else {
prompt = `${body.text}\n\n${body.ask ? `The student asks: ${body.ask}` : 'Explain this passage in simpler terms and point out what is most important to remember.'}`;
}
if (!prompt.trim()) throw badRequest('Nothing to explain');
return sse<{ type: 'text'; delta: string } | { type: 'error'; message: string; code: string } | { type: 'done' }>(c, async (emit, signal) => {
try {
await runChat(app, {
task: 'quick',
purpose: 'explanation',
system: EXPLAIN_SYSTEM,
messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
maxOutputTokens: 1500,
signal,
onEvent: (e) => {
if (e.type === 'text') emit({ type: 'text', delta: e.delta });
},
});
} catch (err) {
const ai = err instanceof AIError ? err : null;
if (ai?.code !== 'aborted') emit({ type: 'error', code: ai?.code ?? 'server', message: ai?.message ?? 'The explanation could not be generated.' });
}
emit({ type: 'done' });
});
});
/* ------------------------------ semantic search ------------------------------ */
r.get('/ai/embeddings', (c) => c.json(embeddingStatus(app)));
r.put('/ai/embeddings', async (c) => {
saveEmbeddingSettings(app, await readBody(c, embeddingSettingsSchema));
return c.json(embeddingStatus(app));
});
/** Embeds one sentence to prove the model works before indexing everything. */
r.post('/ai/embeddings/test', async (c) => {
const started = Date.now();
const [v] = await embedTexts(app, ['Furosemide is a loop diuretic.'], 'query');
return c.json({ ok: true, dimensions: v.length, latencyMs: Date.now() - started });
});
r.post('/ai/embeddings/rebuild', (c) => {
rebuildIndex(app);
return c.json(embeddingStatus(app));
});
r.post('/ai/embeddings/resume', (c) => {
scheduleIndexing(app);
return c.json(embeddingStatus(app));
});
return r;
}