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 = (event: T) => void; /** Server-sent events with ordered writes, keep-alive pings and abort propagation. */ function sse(c: Context, run: (emit: Emit, signal: AbortSignal) => Promise) { 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 = 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, signal: AbortSignal) => new Promise((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(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(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; }