Add drag reordering, exam deadlines, frozen shared quizzes, batched OCR and semantic search
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 33s

- 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>
This commit is contained in:
Elijah 2026-11-12 11:48:20 -07:00
parent 3046e46d1c
commit ccdad9728b
39 changed files with 1772 additions and 121 deletions

View file

@ -16,6 +16,7 @@ import { getAppSettings } from '../settings.ts';
import { createAttempt, missedQuestionIds } from '../services/attempts.ts';
import { createClass, createFolder, getClass, getDeck, getQuiz, listCards, listQuestions, resolveFolder } from '../services/content.ts';
import { deleteDocument, listChunks, searchChunks, sourceLabel } from '../services/documents.ts';
import { hybridSearch } from '../services/semantic.ts';
import { dueCounts } from '../services/srs.ts';
import { topicStats, totals } from '../services/stats.ts';
import { newId, now, parseJson } from '../util.ts';
@ -167,11 +168,11 @@ const TOOLS: ToolSpec[] = [
),
},
label: (i) => `Searching documents for "${clip(String(i.query ?? ''), 50)}"`,
run: (input, env) => {
run: async (input, env) => {
const docIds = (Array.isArray(input.document_ids) && input.document_ids.length ? input.document_ids : env.context.documentIds) as string[] | undefined;
const scope = docIds?.length ? { documentIds: docIds } : { classId: classIdOr(env, input.class_id) ?? null };
const limit = Math.max(1, Math.min(12, Number(input.limit) || 6));
const hits = searchChunks(env.app.db, String(input.query ?? ''), scope, limit);
const hits = await hybridSearch(env.app, String(input.query ?? ''), scope, limit);
if (hits.length === 0) return { output: { results: [], note: 'No matching passages. Try different keywords, or list_materials to check which documents exist.' }, summary: 'No matches' };
return {
output: { results: hits.map((h) => ({ ref: `c${h.id}`, document_id: h.documentId, source: sourceLabel(h), heading: h.heading || undefined, text: clip(h.text, 2400) })) },

View file

@ -37,6 +37,7 @@ import {
updateQuestion,
} from '../services/content.ts';
import { chunkById, formatExcerpts, searchChunks, selectContext, sourceLabel, type ChunkHit } from '../services/documents.ts';
import { hybridSearch } from '../services/semantic.ts';
import { weakTopics } from '../services/stats.ts';
import { newId, now, parseJson } from '../util.ts';
import { generateStructured, resolveModel, runChat } from './service.ts';
@ -403,7 +404,7 @@ interface Sources {
totalTokens: number;
}
function gatherSources(app: AppContext, req: GenerateRequest, budgetTokens: number, groups: number): Sources {
async function gatherSources(app: AppContext, req: GenerateRequest, budgetTokens: number, groups: number): Promise<Sources> {
const { db } = app;
const src = req.source;
const out: Sources = { groups: [], inline: '', docs: [], refs: new Map(), totalTokens: 0 };
@ -423,7 +424,9 @@ function gatherSources(app: AppContext, req: GenerateRequest, budgetTokens: numb
throw badRequest(rows.some((r) => r.status !== 'ready') ? 'Those documents are still being processed. Try again in a moment.' : 'Those documents have no readable text yet.');
}
out.docs = usable.map((r) => ({ documentId: r.id, title: r.title }));
out.groups = selectContext(db, { documentIds: usable.map((r) => r.id) }, { focus: req.focus, budgetTokens, groups });
const scope = { documentIds: usable.map((r) => r.id) };
const ranked = req.focus?.trim() ? await hybridSearch(app, req.focus, scope, 400) : undefined;
out.groups = selectContext(db, scope, { focus: req.focus, budgetTokens, groups, ranked });
}
if (src.text?.trim()) inline.push(`Notes provided by the student:\n${src.text.trim()}`);
@ -466,7 +469,7 @@ function gatherSources(app: AppContext, req: GenerateRequest, budgetTokens: numb
// Pull supporting passages from the class documents for those topics.
if (req.classId && out.groups.length === 0) {
const query = [...topics.map((t) => t.topic), ...missed.slice(0, 10).map((q) => q.topic)].filter(Boolean).join(' ');
const hits = query ? searchChunks(db, query, { classId: req.classId }, 24) : [];
const hits = query ? await hybridSearch(app, query, { classId: req.classId }, 24) : [];
if (hits.length > 0) {
const perGroup = Math.max(1, Math.ceil(hits.length / groups));
for (let i = 0; i < hits.length; i += perGroup) out.groups.push(hits.slice(i, i + perGroup));
@ -583,7 +586,7 @@ async function runGeneration(app: AppContext, draftId: string, req: GenerateRequ
count = Math.min(Math.max(count, 1), 100);
}
const batches = Math.ceil(count / perBatch);
const sources = gatherSources(app, req, budgetTokens, batches);
const sources = await gatherSources(app, req, budgetTokens, batches);
const hasSources = sources.groups.length > 0 || Boolean(sources.inline);
if (!hasSources && !req.focus && !req.instructions) throw badRequest('Choose source material or describe a topic to generate from.');
@ -696,7 +699,7 @@ async function generateNote(app: AppContext, draftId: string, req: GenerateReque
const style = req.noteStyle ?? 'study_guide';
// A guide reads the material in as few passes as possible; allow a bigger slice per pass than item generation.
const perPass = Math.max(budgetTokens, Math.min(Math.floor(window * 0.55), 90_000));
const sources = gatherSources(app, req, perPass, 12);
const sources = await gatherSources(app, req, perPass, 12);
const hasSources = sources.groups.length > 0 || Boolean(sources.inline);
if (!hasSources && !req.focus) throw badRequest('Choose source material or describe a topic to write about.');
const title = defaultTitle(app, req, sources);

View file

@ -49,6 +49,21 @@ export function newToolCallId(prefix: string): string {
return `${prefix}_${globalThis.crypto.randomUUID().replace(/-/g, '').slice(0, 24)}`;
}
/** Parses an OpenAI-style `/embeddings` response ({ data: [{ index, embedding }], usage }). */
export function parseEmbeddings(res: unknown, expected: number, label: string): { vectors: number[][]; inputTokens: number } {
const body = res as { data?: { index?: number; embedding?: unknown }[]; usage?: { prompt_tokens?: number; total_tokens?: number } };
const rows = Array.isArray(body?.data) ? body.data : [];
const vectors: number[][] = new Array(expected);
rows.forEach((row, i) => {
const at = typeof row.index === 'number' ? row.index : i;
if (Array.isArray(row.embedding)) vectors[at] = row.embedding.map(Number);
});
if (rows.length !== expected || vectors.some((v) => !v || v.length === 0)) {
throw new AIError('invalid_response', `${label} returned ${rows.length} embeddings for ${expected} inputs.`);
}
return { vectors, inputTokens: num(body?.usage?.prompt_tokens ?? body?.usage?.total_tokens) };
}
export function dataUrl(mime: string, base64: string): string {
return `data:${mime};base64,${base64}`;
}

View file

@ -16,7 +16,7 @@
* numeric `thinkingBudget` on 2.5; an unsupported config is dropped and retried.
* - A response can be blocked (`promptFeedback.blockReason`, finishReason SAFETY).
*/
import {
import { type EmbedRequest, type EmbedResult,
AIError,
type ChatMessage,
type ChatRequest,
@ -296,6 +296,30 @@ async function* stream(cfg: ProviderConfig, req: ChatRequest): AsyncGenerator<St
};
}
async function embed(cfg: ProviderConfig, req: EmbedRequest): Promise<EmbedResult> {
const name = req.model.startsWith('models/') ? req.model : `models/${req.model}`;
const requests = req.inputs.map((text) => ({
model: name,
content: { parts: [{ text }] },
taskType: req.purpose === 'query' ? 'RETRIEVAL_QUERY' : 'RETRIEVAL_DOCUMENT',
...(req.dimensions ? { outputDimensionality: req.dimensions } : {}),
}));
const res = await requestJson<{ embeddings?: { values?: number[] }[] }>(`${root(cfg)}/v1beta/${name}:batchEmbedContents`, {
...errorContext(cfg),
headers: headers(cfg),
body: { requests },
signal: req.signal,
firstByteTimeoutMs: 60_000,
totalTimeoutMs: 120_000,
});
const vectors = (res.embeddings ?? []).map((e) => (Array.isArray(e.values) ? e.values.map(Number) : []));
if (vectors.length !== req.inputs.length || vectors.some((v) => v.length === 0)) {
throw new AIError('invalid_response', `${LABEL} returned ${vectors.length} embeddings for ${req.inputs.length} inputs.`);
}
// Gemini does not report token use for embeddings; estimate it for the usage log.
return { vectors, inputTokens: Math.ceil(req.inputs.reduce((n, t) => n + t.length, 0) / 4) };
}
async function listModels(cfg: ProviderConfig, signal?: AbortSignal, timeoutMs?: number): Promise<DiscoveredModel[]> {
const found: DiscoveredModel[] = [];
let pageToken = '';
@ -338,5 +362,6 @@ export const geminiAdapter: ProviderAdapter = {
},
stream,
listModels: (cfg, signal) => listModels(cfg, signal),
embed,
test,
};

View file

@ -9,7 +9,7 @@
import { AIError, type DiscoveredModel, type ModelCapabilities, type ProviderAdapter, type ProviderConfig, type TestResult } from '../types.ts';
import { num, runTest, str, TEST_TIMEOUT_MS } from './common.ts';
import { isRecord, requestJson, trimBaseUrl, type ErrorContext } from './http.ts';
import { streamChatCompletions, type CompatOptions } from './openaiCompatible.ts';
import { compatEmbed, streamChatCompletions, type CompatOptions } from './openaiCompatible.ts';
const LABEL = 'Ollama';
const DEFAULT_BASE_URL = 'http://localhost:11434';
@ -98,5 +98,7 @@ export const ollamaAdapter: ProviderAdapter = {
},
stream: (cfg, req) => streamChatCompletions(compat(cfg), req),
listModels: (cfg, signal) => listModels(cfg, signal),
// Ollama serves OpenAI-style embeddings at /v1/embeddings (e.g. nomic-embed-text).
embed: (cfg, req) => compatEmbed(compat(cfg), req),
test,
};

View file

@ -14,7 +14,7 @@
* rejects the chosen value the request is retried once with a safe one.
* - Tool-call arguments arrive as deltas keyed by output item.
*/
import {
import { type EmbedRequest, type EmbedResult,
AIError,
type ChatMessage,
type ChatRequest,
@ -28,7 +28,7 @@ import {
type TestResult,
} from '../types.ts';
import { lookupModelDefaults } from './catalog.ts';
import { dataUrl, isChatModelId, makeUsage, num, parseArgsStrict, parseToolArguments, runTest, str, TEST_TIMEOUT_MS, withCatalogDefaults } from './common.ts';
import { parseEmbeddings, dataUrl, isChatModelId, makeUsage, num, parseArgsStrict, parseToolArguments, runTest, str, TEST_TIMEOUT_MS, withCatalogDefaults } from './common.ts';
import { ensureOk, errorFromProvider, httpRequest, isRecord, requestJson, sseJson, trimBaseUrl, type ErrorContext, type HttpResponse } from './http.ts';
type Json = Record<string, unknown>;
@ -292,6 +292,13 @@ async function listModels(cfg: ProviderConfig, signal?: AbortSignal, timeoutMs?:
return withCatalogDefaults('openai', found);
}
async function embed(cfg: ProviderConfig, req: EmbedRequest): Promise<EmbedResult> {
const body: Json = { model: req.model, input: req.inputs, encoding_format: 'float' };
if (req.dimensions && /text-embedding-3/.test(req.model)) body.dimensions = req.dimensions;
const res = await requestJson(`${base(cfg)}/embeddings`, { ...errorContext(cfg), headers: headers(cfg), body, signal: req.signal, firstByteTimeoutMs: 60_000, totalTimeoutMs: 120_000 });
return parseEmbeddings(res, req.inputs.length, LABEL);
}
async function test(cfg: ProviderConfig): Promise<TestResult> {
return runTest(LABEL, async () => ({ modelCount: (await listModels(cfg, undefined, TEST_TIMEOUT_MS)).length }));
}
@ -309,5 +316,6 @@ export const openaiAdapter: ProviderAdapter = {
},
stream,
listModels: (cfg, signal) => listModels(cfg, signal),
embed,
test,
};

View file

@ -13,7 +13,7 @@
* - reasoning text may arrive as `reasoning_content`, `reasoning` or `thinking`;
* - the last chunk may lack a `finish_reason`.
*/
import {
import { type EmbedRequest, type EmbedResult,
AIError,
type ChatMessage,
type ChatRequest,
@ -27,7 +27,7 @@ import {
type StreamEvent,
type TestResult,
} from '../types.ts';
import { dataUrl, isChatModelId, makeUsage, newToolCallId, num, parseArgsStrict, parseToolArguments, runTest, str, TEST_TIMEOUT_MS, withCatalogDefaults } from './common.ts';
import { parseEmbeddings, dataUrl, isChatModelId, makeUsage, newToolCallId, num, parseArgsStrict, parseToolArguments, runTest, str, TEST_TIMEOUT_MS, withCatalogDefaults } from './common.ts';
import { ensureOk, errorFromProvider, hostOf, httpRequest, isLocalUrl, isRecord, requestJson, sseJson, trimBaseUrl, type ErrorContext, type HttpResponse } from './http.ts';
type Json = Record<string, unknown>;
@ -62,6 +62,8 @@ function userContent(parts: ContentPart[], caps: Partial<ModelCapabilities>): st
else blocks.push({ type: 'image_url', image_url: { url: dataUrl(p.mime, p.data) } });
} else if (p.type === 'file') {
if (p.mime.startsWith('text/')) blocks.push({ type: 'text', text: Buffer.from(p.data, 'base64').toString('utf8') });
// Chat Completions "file" parts (OpenAI, OpenRouter and others) for models marked as reading PDFs.
else if (p.mime === 'application/pdf' && caps.pdf) blocks.push({ type: 'file', file: { filename: p.filename ?? 'document.pdf', file_data: dataUrl(p.mime, p.data) } });
else blocks.push({ type: 'text', text: `[The file "${p.filename ?? 'attachment'}" was attached, but this model cannot read it directly.]` });
}
}
@ -319,6 +321,14 @@ export async function listCompatModels(o: CompatOptions, signal?: AbortSignal, t
return withCatalogDefaults(o.kind, found);
}
/** OpenAI-style `/embeddings`, shared with Ollama's compatible endpoint. */
export async function compatEmbed(o: CompatOptions, req: EmbedRequest): Promise<EmbedResult> {
const body: Record<string, unknown> = { model: req.model, input: req.inputs, encoding_format: 'float' };
if (req.dimensions && /text-embedding-3/.test(req.model)) body.dimensions = req.dimensions;
const res = await requestJson(`${normalizeCompatBase(o.baseUrl)}/embeddings`, { ...errorContext(o), headers: authHeaders(o), body, signal: req.signal, firstByteTimeoutMs: 120_000, totalTimeoutMs: 300_000 });
return parseEmbeddings(res, req.inputs.length, o.label);
}
function options(cfg: ProviderConfig): CompatOptions {
if (!cfg.baseUrl?.trim()) throw new AIError('not_configured', `Add the server URL for "${cfg.name}" in Settings.`);
return { kind: 'openai_compatible', label: cfg.name || hostOf(cfg.baseUrl), baseUrl: cfg.baseUrl, apiKey: cfg.apiKey, headers: cfg.headers };
@ -360,4 +370,5 @@ export const openaiCompatibleAdapter: ProviderAdapter = {
stream: (cfg, req) => streamChatCompletions(options(cfg), req),
listModels: (cfg, signal) => listCompatModels(options(cfg), signal),
test,
embed: (cfg, req) => compatEmbed(options(cfg), req),
};

View file

@ -157,6 +157,13 @@ function providerConfig(app: AppContext, row: ProviderRow): ProviderConfig {
};
}
/** Decrypted connection details for one enabled provider (server-side use only, never sent to clients). */
export function providerConfigById(app: AppContext, id: string): { cfg: ProviderConfig; kind: ProviderKind; name: string } {
const row = providerRow(app.db, id);
if (!row.enabled) throw new AIError('not_configured', `The provider "${row.name}" is turned off. Turn it on in Settings.`);
return { cfg: providerConfig(app, row), kind: row.kind, name: row.name };
}
function providerRow(db: DB, id: string): ProviderRow {
const row = db.get<ProviderRow>('SELECT * FROM ai_providers WHERE id = ?', id);
if (!row) throw notFound('Provider');

View file

@ -118,6 +118,21 @@ export interface TestResult {
modelCount?: number;
}
export interface EmbedRequest {
model: string;
inputs: string[];
/** Some providers embed search queries and stored passages differently. */
purpose: 'document' | 'query';
/** Requested vector size, for models that can shorten their output (OpenAI v3, Gemini). */
dimensions?: number;
signal?: AbortSignal;
}
export interface EmbedResult {
vectors: number[][];
inputTokens: number;
}
export interface ProviderAdapter {
kind: ProviderKind;
/** Human label and defaults used by the settings UI. */
@ -136,6 +151,8 @@ export interface ProviderAdapter {
listModels(cfg: ProviderConfig, signal?: AbortSignal): Promise<DiscoveredModel[]>;
/** Cheap credential / connectivity check. Never throws. */
test(cfg: ProviderConfig, model?: string): Promise<TestResult>;
/** Text embeddings for semantic search. Absent when the provider has no embeddings API. */
embed?(cfg: ProviderConfig, req: EmbedRequest): Promise<EmbedResult>;
}
export type AIErrorCode =