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 { deleteMcpServer, listMcpServers, mcpServerInputSchema, mcpServerPatchSchema, saveMcpServer, testMcpServer } from '../ai/mcp.ts'; import { CATALOG_UPDATED, listAdapterMeta } from '../ai/providers/index.ts'; import { addManualModel, aiStatus, deleteModel, deleteProvider, discoverModels, getTaskSettings, listModels, listProviders, manualModelSchema, modelPatchSchema, patchModel, providerInputSchema, runChat, runChatWithMcp, saveProvider, saveTaskSettings, TASK_INFO, testProvider, usageSummary, } from '../ai/service.ts'; import { embedTexts, embeddingSettingsSchema, getEmbeddingSettings, embeddingStatus, rebuildIndex, saveEmbeddingSettings, scheduleIndexing } from '../services/semantic.ts'; import { EXPLAIN_SYSTEM, explainPrompt } from '../ai/explain.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. */ export 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) }), ]); 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) }); }); // MCP servers the assistant can call as tools. r.get('/ai/mcp', (c) => c.json({ servers: listMcpServers(app) })); r.post('/ai/mcp', async (c) => c.json({ server: saveMcpServer(app, null, await readBody(c, mcpServerInputSchema)) }, 201)); r.patch('/ai/mcp/:id', async (c) => c.json({ server: saveMcpServer(app, idParam(c), await readBody(c, mcpServerPatchSchema)) })); r.delete('/ai/mcp/:id', (c) => { deleteMcpServer(app, idParam(c)); return c.json({ ok: true }); }); r.post('/ai/mcp/:id/test', async (c) => c.json({ result: await testMcpServer(app, idParam(c)) })); 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); const prompt = explainPrompt(body); 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 { let wrote = false; await runChatWithMcp( 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') return; wrote = true; emit({ type: 'text', delta: e.delta }); }, }, 'explain', { // Text before a tool call ends its paragraph. onTool: () => { if (wrote) emit({ type: 'text', delta: '\n\n' }); wrote = false; }, }, ); } 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; }