Study/server/ai/providers/common.ts
Elijah ccdad9728b
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 33s
Add drag reordering, exam deadlines, frozen shared quizzes, batched OCR and semantic search
- 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>
2026-11-12 11:48:20 -07:00

153 lines
6.5 KiB
TypeScript

/**
* Helpers shared by the adapters that are about our neutral contract rather
* than about HTTP: tool-argument parsing, model-list post-processing, the
* connection-test wrapper.
*/
import { jsonrepair } from 'jsonrepair';
import { AIError, type DiscoveredModel, type ProviderKind, type TestResult, type Usage } from '../types.ts';
import { lookupModelDefaults } from './catalog.ts';
import { isRecord } from './http.ts';
/** Strict parse of tool-call arguments; `undefined` when they are not a JSON object. */
export function parseArgsStrict(raw: string): Record<string, unknown> | undefined {
const text = raw.trim();
if (text === '') return {};
try {
const value: unknown = JSON.parse(text);
return isRecord(value) ? value : undefined;
} catch {
return undefined;
}
}
/**
* Parses the JSON arguments of a completed tool call. Models occasionally emit
* slightly broken JSON (trailing commas, unescaped newlines); `jsonrepair`
* fixes those. Anything still unparseable is an `invalid_response`.
*
* Do NOT use this on a call that was cut off by the output-token limit —
* repairing a truncated call would silently invent a shorter input.
*/
export function parseToolArguments(raw: unknown, provider: string, toolName: string): Record<string, unknown> {
if (isRecord(raw)) return raw; // some servers send an object instead of a JSON string
const text = typeof raw === 'string' ? raw : raw == null ? '' : String(raw);
const strict = parseArgsStrict(text);
if (strict) return strict;
try {
const repaired: unknown = JSON.parse(jsonrepair(text));
if (isRecord(repaired)) return repaired;
} catch {
/* fall through */
}
throw new AIError('invalid_response', `${provider} produced a tool call for "${toolName}" with arguments that are not valid JSON.`, {
providerMessage: text.length > 300 ? `${text.slice(0, 300)}…` : text,
});
}
/** Stable id for providers that do not issue tool-call ids themselves. */
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}`;
}
export function num(v: unknown): number {
return typeof v === 'number' && Number.isFinite(v) ? v : 0;
}
export function str(v: unknown): string {
return typeof v === 'string' ? v : '';
}
/**
* Usage convention used by every adapter:
* inputTokens = ALL prompt tokens, including cached ones
* cacheRead/cacheWriteTokens = the cached subsets of inputTokens
* outputTokens = ALL generated tokens, including reasoning
* reasoningTokens = the reasoning subset of outputTokens
*/
export function makeUsage(u: { input: number; output: number; cacheRead?: number; cacheWrite?: number; reasoning?: number }): Usage {
const usage: Usage = { inputTokens: u.input, outputTokens: u.output };
if (u.cacheRead) usage.cacheReadTokens = u.cacheRead;
if (u.cacheWrite) usage.cacheWriteTokens = u.cacheWrite;
if (u.reasoning) usage.reasoningTokens = u.reasoning;
return usage;
}
/**
* Ids that are obviously not text-chat models: embeddings, speech, image and
* video generation, moderation, realtime/audio-only, rerankers, legacy
* completion-only models.
*/
const NON_CHAT_RE = new RegExp(
[
'embed', // text-embedding-3-large, gemini-embedding-001, nomic-embed-text
'\\btts\\b|whisper|transcri|speech|\\baudio\\b|realtime|\\blive\\b',
'dall-e|gpt-image|image-generation|imagen|-image\\b|image-preview|\\bsora\\b|\\bveo\\b|lyria|stable-diffusion',
'moderation|-guard\\b|rerank|\\baqa\\b',
'computer-use|robotics|deep-research',
'^(babbage|davinci|curie|ada)\\b|^text-|turbo-instruct',
].join('|'),
'i',
);
export function isChatModelId(id: string): boolean {
return !NON_CHAT_RE.test(id);
}
/** Merges discovery results with catalog defaults; values the provider reported always win. */
export function withCatalogDefaults(kind: ProviderKind, models: DiscoveredModel[]): DiscoveredModel[] {
const seen = new Set<string>();
const out: DiscoveredModel[] = [];
for (const m of models) {
if (!m.id || seen.has(m.id)) continue;
seen.add(m.id);
const d = lookupModelDefaults(kind, m.id);
const merged: DiscoveredModel = { ...d, ...stripUndefined(m), id: m.id };
if (d.capabilities || m.capabilities) merged.capabilities = { ...d.capabilities, ...stripUndefined(m.capabilities ?? {}) };
out.push(merged);
}
return out;
}
function stripUndefined<T extends object>(obj: T): T {
const out = {} as Record<string, unknown>;
for (const [k, v] of Object.entries(obj)) if (v !== undefined && v !== null) out[k] = v;
return out as T;
}
/** Shared implementation of `ProviderAdapter.test()`: never throws, always friendly. */
export async function runTest(label: string, check: () => Promise<{ modelCount?: number; note?: string }>): Promise<TestResult> {
const started = Date.now();
try {
const { modelCount, note } = await check();
const latencyMs = Date.now() - started;
const message =
note ?? (modelCount !== undefined ? `Connected to ${label}: ${modelCount} model${modelCount === 1 ? '' : 's'} available.` : `Connected to ${label}.`);
return modelCount !== undefined ? { ok: true, message, latencyMs, modelCount } : { ok: true, message, latencyMs };
} catch (err) {
const latencyMs = Date.now() - started;
const message = err instanceof AIError ? err.message : `Could not connect to ${label}.`;
return { ok: false, message, latencyMs };
}
}
/** Timeout used by `test()` so a dead endpoint fails fast instead of hanging the settings page. */
export const TEST_TIMEOUT_MS = 20_000;