Study/server/routes/ai.ts
Elijah f0aabe4d5d
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 1m2s
First revision: DeepSeek, numeric questions, background assistant, UI fixes
Providers and pricing
- Add a DeepSeek provider: thinking mode with low/high/max effort, reasoning_content
  replayed between tool steps, cache-hit usage, /models discovery and catalog prices.
- Fix "does not support tool calling": a rejected forced tool_choice (DeepSeek thinking
  mode) now asks for the call in the prompt; only a genuine no-tools 400 is "unsupported".
- Seven reasoning-effort levels (Off to Max) mapped per adapter.
- Cached-input price per model, cache-write and DeepSeek off-peak aware cost estimates.
- Built-in bge-small embedding model (transformers.js) as the semantic search default.

Quizzes
- Numeric (type-the-answer) questions: units ignored, optional ± tolerance; editor,
  runner, importer, templates and generation prompts.
- Quiz start screen instead of showing answers; navigator ring no longer clipped and
  key legend removed; clock only for timed exams; 7-point letter grades.

Assistant and generation
- Assistant turns run on the server independently of the browser, with re-attach and
  an explicit stop; drafts tray shows generations in progress.
- Per-chat model switcher, @-tagging of class materials, full-width assistant page and
  a smaller assistant button.
- Editable generation instructions and built-in presets, separate from the chatbot
  import instructions.

Other
- Dialog footer padding, keyboard hints removed, copy buttons work over plain HTTP,
  class and folder shares include documents.

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

342 lines
15 KiB
TypeScript

import { Hono, type Context } from 'hono';
import { streamSSE } from 'hono/streaming';
import { z } from 'zod';
import { assistantRequestSchema, displayMessages, followTurn, isTurnRunning, listConversations, mentionables, resolveAction, startAssistantTurn, stopTurn, type AssistantEvent } from '../ai/assistant.ts';
import {
cancelGeneration,
createDraft,
discardDraft,
draftSaveSchema,
generateRequestSchema,
getDraft,
improveRequestSchema,
instructionPatchSchema,
listInstructions,
saveInstruction,
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, HttpError, 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', 'numeric']),
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 }));
/** Instructions the built-in generator sends to the model (editable in Settings → Templates). */
r.get('/ai/instructions', (c) => c.json({ instructions: listInstructions(db) }));
r.put('/ai/instructions', async (c) => {
saveInstruction(db, await readBody(c, instructionPatchSchema));
return c.json({ instructions: listInstructions(db) });
});
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 ------------------------------ */
/** Streams a running turn's events (replayed from its start) until it ends or the client leaves. */
const follow = (conversationId: string, emit: Emit<AssistantEvent>, signal: AbortSignal) =>
new Promise<void>((resolve) => {
let unsubscribe: (() => void) | null = null;
const finish = () => {
unsubscribe?.();
resolve();
};
unsubscribe = followTurn(conversationId, (event) => {
emit(event);
if (event.type === 'done') queueMicrotask(finish);
});
if (!unsubscribe) {
emit({ type: 'done', conversationId, title: '' });
return resolve();
}
// Leaving the page only stops the stream; the turn keeps running on the server.
signal.addEventListener('abort', finish, { once: true });
});
r.post('/ai/chat', async (c) => {
const body = await readBody(c, assistantRequestSchema);
return sse<AssistantEvent>(c, async (emit, signal) => {
let conversationId: string;
try {
({ conversationId } = startAssistantTurn(app, body));
} catch (err) {
// Failures before the turn starts (no model configured, bad input, already running) still reach the client as an event.
const ai = err instanceof AIError ? err : null;
const http = err instanceof HttpError ? err : null;
if (!ai && !http) app.log('error', 'Assistant request failed', err);
emit({ type: 'error', code: ai?.code ?? http?.code ?? 'server', message: ai?.message ?? http?.message ?? 'The assistant could not start.', detail: ai?.providerMessage });
emit({ type: 'done', conversationId: body.conversationId ?? '', title: '' });
return;
}
await follow(conversationId, emit, signal);
});
});
/** Re-attaches to a turn that is still running (after leaving and coming back). */
r.get('/ai/chat/:id/stream', (c) => {
const id = idParam(c);
return sse<AssistantEvent>(c, (emit, signal) => follow(id, emit, signal));
});
r.post('/ai/chat/:id/stop', (c) => c.json({ stopped: stopTurn(idParam(c)) }));
/** Library items that can be tagged with @ in the assistant. */
r.get('/ai/mentionables', (c) => c.json({ items: mentionables(db, { classId: c.req.query('classId') || null, q: c.req.query('q') ?? '' }) }));
r.get('/ai/conversations', (c) => c.json({ conversations: listConversations(db).map((x) => ({ ...x, running: isTurnRunning(x.id) })) }));
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, running: isTurnRunning(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;
}