Study/server/ai/localEmbed.ts
Elijah 031f7bec31
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 30s
Second revision: MCP servers, shared-link AI, flashcard modes, document previews
Generation
- Every quiz is NCLEX style; "Practice exam" writes 50 questions.
- Calculation questions only when the material involves calculations (max 5 per exam).
- Broad topics: the class's topics are listed in the prompt, a quick grouping call maps
  narrow labels onto broad ones, and leftover variants are merged.
- Exact select-all count per batch; option order shuffled.
- Python check: at most 3 runs, fixed problems count as passed, cosmetic remarks ignored.

Assistant
- Text, tool steps and cards appear in the order they happen, with paragraph breaks
  between steps.
- Optional thinking box: fixed height, follows the newest text, can be scrolled back.
- "+" opens a material picker listing recent items; items can be dragged in from class
  pages; shorter placeholder.

MCP servers
- Streamable HTTP client; encrypted headers.
- Per-server instructions and switches for chat, Explain, generation and the quiz check.
- Settings UI.

Share links
- Optional "Explain this" and "Ask about this material" per link, off by default.
- Items are loaded on the server and checked against the share; no tools; rate-limited.
- Migration 4 stores the switches.

Study and documents
- Standard flashcard mode (optionally repeat missed cards until known) next to spaced
  repetition.
- Streak visuals restyled in the app palette.
- Side by side / Original document views, with sandboxed previews of Word and PowerPoint
  files.

Other
- Built-in embedding model baked into the image; sharp stubbed if it cannot load; real
  load error shown in Settings.
- Python runner blocks network and process modules in JavaScript too.
- "View questions and answers" removed from the quiz start screen.
- Docs updated.

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

140 lines
6.3 KiB
TypeScript

/**
* Built-in embedding model, used for semantic search when no cloud embedding provider is
* configured. Runs on the server's CPU through ONNX Runtime (transformers.js), so it needs no
* API key and costs nothing.
*
* Model: BAAI bge-small-en-v1.5 (ONNX, 8-bit quantised, about 34 MB, 384 dimensions). It is a
* strong small retrieval model; queries get BGE's recommended instruction prefix. The files
* are downloaded from Hugging Face on first use into DATA_DIR/models and reused afterwards.
*
* The library is imported lazily: the app starts (and tests run) without loading ONNX Runtime
* until something actually needs an embedding.
*
* The Docker image ships the model in /app/models (LOCAL_MODELS_DIR), so nothing is downloaded
* at runtime there. Elsewhere it is downloaded once into DATA_DIR/models.
*/
import fs from 'node:fs';
import path from 'node:path';
import { AIError } from './types.ts';
export const LOCAL_PROVIDER_ID = 'local';
export const LOCAL_EMBEDDING_MODEL = 'Xenova/bge-small-en-v1.5';
export const LOCAL_EMBEDDING_LABEL = 'bge-small-en-v1.5 (built in)';
export const LOCAL_EMBEDDING_DIMS = 384;
const QUERY_PREFIX = 'Represent this sentence for searching relevant passages: ';
/** Inputs per forward pass: small enough to keep memory flat on a home server. */
const BATCH = 16;
/** About 512 tokens, the model's window. Longer input is truncated by the tokenizer anyway. */
const MAX_CHARS = 2000;
type Extractor = (texts: string[], opts: { pooling: 'cls' | 'mean'; normalize: boolean }) => Promise<{ tolist(): number[][] }>;
const state: { extractor: Promise<Extractor> | null; cacheDir: string; status: 'idle' | 'loading' | 'ready' | 'error'; error: string } = {
extractor: null,
cacheDir: '',
status: 'idle',
error: '',
};
export function localModelDir(dataDir: string): string {
return path.join(dataDir, 'models');
}
function hasModel(root: string | undefined): boolean {
if (!root) return false;
const dir = path.join(root, ...LOCAL_EMBEDDING_MODEL.split('/'));
try {
return fs.existsSync(path.join(dir, 'onnx', 'model_quantized.onnx')) && fs.existsSync(path.join(dir, 'tokenizer.json'));
} catch {
return false;
}
}
/** A copy of the model shipped with the installation (the Docker image), if any. */
function bundledModelDir(): string | undefined {
const dir = process.env.LOCAL_MODELS_DIR?.trim();
return dir && hasModel(dir) ? dir : undefined;
}
/** True when the model files are already on disk (no download needed). */
export function localModelDownloaded(dataDir: string): boolean {
return Boolean(bundledModelDir()) || hasModel(localModelDir(dataDir));
}
/**
* transformers.js imports `sharp` (image processing) when it loads, although text embeddings
* never use it. sharp's prebuilt binary needs a fairly recent x86-64 CPU; on hosts where it
* cannot load, the whole library failed. Route `sharp` to an empty stand-in in that case.
*/
async function stubSharpIfBroken(): Promise<void> {
try {
await import('sharp');
return;
} catch {
/* fall through */
}
const { registerHooks } = (await import('node:module')) as unknown as { registerHooks?: (hooks: unknown) => void };
const stub = 'data:text/javascript,' + encodeURIComponent('export default function sharp(){throw new Error("Image processing is not available on this server.")}');
registerHooks?.({
resolve(specifier: string, context: unknown, next: (s: string, c: unknown) => unknown) {
if (specifier === 'sharp') return { url: stub, shortCircuit: true, format: 'module' };
return next(specifier, context);
},
});
}
export function localModelStatus(dataDir: string) {
return { model: LOCAL_EMBEDDING_MODEL, label: LOCAL_EMBEDDING_LABEL, dimensions: LOCAL_EMBEDDING_DIMS, downloaded: localModelDownloaded(dataDir), status: state.status, error: state.error };
}
async function load(dataDir: string): Promise<Extractor> {
const cacheDir = localModelDir(dataDir);
if (state.extractor && state.cacheDir === cacheDir) return state.extractor;
state.cacheDir = cacheDir;
state.status = 'loading';
state.error = '';
state.extractor = (async () => {
const bundled = bundledModelDir();
if (!bundled) fs.mkdirSync(cacheDir, { recursive: true });
let lib: typeof import('@huggingface/transformers');
try {
await stubSharpIfBroken();
lib = await import('@huggingface/transformers');
} catch (err) {
throw new AIError('unsupported', `The built-in embedding model could not start on this server: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
}
lib.env.cacheDir = cacheDir;
lib.env.allowLocalModels = true;
lib.env.localModelPath = bundled ?? cacheDir;
// With a bundled copy there is nothing to download.
lib.env.allowRemoteModels = !bundled;
const extractor = await lib.pipeline('feature-extraction', LOCAL_EMBEDDING_MODEL, { dtype: 'q8' });
return extractor as unknown as Extractor;
})();
try {
const ready = await state.extractor;
state.status = 'ready';
return ready;
} catch (err) {
state.extractor = null;
state.status = 'error';
const message = err instanceof AIError ? err.message : `The built-in embedding model could not be loaded: ${err instanceof Error ? err.message : String(err)}`;
state.error = message;
throw err instanceof AIError ? err : new AIError('network', `${message}. It is downloaded once (about 35 MB) from huggingface.co; check that the server can reach the internet.`, { cause: err, retryable: true });
}
}
/** Embeds texts with the built-in model. Vectors come back L2-normalised. */
export async function localEmbed(dataDir: string, texts: string[], purpose: 'document' | 'query', signal?: AbortSignal): Promise<number[][]> {
const extractor = await load(dataDir);
const out: number[][] = [];
for (let i = 0; i < texts.length; i += BATCH) {
if (signal?.aborted) throw new AIError('aborted', 'The request was cancelled.');
const batch = texts.slice(i, i + BATCH).map((t) => (purpose === 'query' ? QUERY_PREFIX : '') + (t.slice(0, MAX_CHARS) || ' '));
const tensor = await extractor(batch, { pooling: 'cls', normalize: true });
out.push(...tensor.tolist());
// Let the event loop serve requests between batches; indexing runs in the background.
await new Promise((resolve) => setImmediate(resolve));
}
return out;
}