Start Study Desk V2: remove V1 sources, add backend foundation

V1 remains intact on main and in history. This branch replaces it with a new
application: node:sqlite storage with migrations, scrypt auth and sessions,
content/SRS/attempt/stats services, document extraction and chunking, a
provider-neutral AI layer (OpenAI, Anthropic, Gemini, OpenAI-compatible,
Ollama), the generation pipeline and the tool-using assistant.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
Elijah 2026-11-11 08:16:41 -07:00
parent 7bd0a9aad4
commit 3e74ecd843
268 changed files with 17740 additions and 55423 deletions

View file

@ -0,0 +1,342 @@
/**
* Google Gemini — `models/{model}:streamGenerateContent?alt=sse`.
* https://ai.google.dev/api/generate-content
* https://ai.google.dev/gemini-api/docs/function-calling
* https://ai.google.dev/gemini-api/docs/thinking
* https://ai.google.dev/gemini-api/docs/thought-signatures
*
* Quirks handled here:
* - The API key travels in the `x-goog-api-key` header, never in the URL.
* - Function declarations accept only a subset of JSON Schema, so schemas are
* down-converted (`toGeminiSchema`).
* - Gemini issues no tool-call ids; stable ones are synthesised.
* - Thinking models attach a `thoughtSignature` to parts (notably function calls)
* that must be sent back unchanged, so each turn's raw parts live in `providerData`.
* - Thinking is configured with `thinkingLevel` on Gemini 3 and later and with a
* numeric `thinkingBudget` on 2.5; an unsupported config is dropped and retried.
* - A response can be blocked (`promptFeedback.blockReason`, finishReason SAFETY).
*/
import {
AIError,
type ChatMessage,
type ChatRequest,
type ContentPart,
type DiscoveredModel,
type ModelCapabilities,
type ProviderAdapter,
type ProviderConfig,
type StopReason,
type StreamEvent,
type TestResult,
} from '../types.ts';
import { isChatModelId, makeUsage, newToolCallId, num, 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>;
const LABEL = 'Google Gemini';
const DEFAULT_BASE_URL = 'https://generativelanguage.googleapis.com';
function root(cfg: ProviderConfig): string {
return trimBaseUrl(cfg.baseUrl || DEFAULT_BASE_URL).replace(/\/v1(beta)?$/, '');
}
function errorContext(cfg: ProviderConfig): ErrorContext {
return { provider: LABEL, secrets: [cfg.apiKey, ...Object.values(cfg.headers ?? {})] };
}
function headers(cfg: ProviderConfig): Record<string, string> {
if (!cfg.apiKey) throw new AIError('not_configured', 'Add a Gemini API key in Settings to use Gemini models.');
return { ...cfg.headers, 'x-goog-api-key': cfg.apiKey };
}
const SCHEMA_KEYS = new Set(['type', 'description', 'enum', 'properties', 'required', 'items', 'nullable', 'format', 'minimum', 'maximum', 'minItems', 'maxItems', 'anyOf', 'title']);
const SCHEMA_FORMATS = new Set(['date-time', 'enum', 'int32', 'int64', 'float', 'double']);
/** Reduces JSON Schema to the OpenAPI-style subset Gemini's `parameters` field accepts. */
export function toGeminiSchema(schema: unknown): Json {
if (!isRecord(schema)) return { type: 'string' };
const out: Json = {};
for (const [key, value] of Object.entries(schema)) {
if (!SCHEMA_KEYS.has(key)) continue; // additionalProperties, $schema, default, pattern, const, ...
if (key === 'properties' && isRecord(value)) {
out.properties = Object.fromEntries(Object.entries(value).map(([k, v]) => [k, toGeminiSchema(v)]));
} else if (key === 'items') {
out.items = toGeminiSchema(value);
} else if (key === 'anyOf' && Array.isArray(value)) {
out.anyOf = value.map(toGeminiSchema);
} else if (key === 'type' && Array.isArray(value)) {
// ["string","null"] -> nullable string
const real = value.filter((t) => t !== 'null');
out.type = real[0] ?? 'string';
if (value.includes('null')) out.nullable = true;
} else if (key === 'format') {
if (typeof value === 'string' && SCHEMA_FORMATS.has(value)) out.format = value;
} else {
out[key] = value;
}
}
if (out.enum && !out.type) out.type = 'string';
if (out.type === 'object' && !out.properties) out.properties = {};
return out;
}
function userParts(parts: ContentPart[], caps: Partial<ModelCapabilities>): Json[] {
const out: Json[] = [];
for (const p of parts) {
if (p.type === 'tool_result') {
out.push({ functionResponse: { name: p.name, response: p.isError ? { error: p.output } : { result: p.output } } });
} else if (p.type === 'text' && p.text) {
out.push({ text: p.text });
} else if (p.type === 'image') {
if (caps.vision === false) out.push({ text: '[An image was attached, but this model cannot read images.]' });
else out.push({ inlineData: { mimeType: p.mime, data: p.data } });
} else if (p.type === 'file') {
if (p.mime === 'application/pdf' && caps.pdf !== false) out.push({ inlineData: { mimeType: p.mime, data: p.data } });
else if (p.mime.startsWith('text/')) out.push({ text: Buffer.from(p.data, 'base64').toString('utf8') });
else out.push({ text: `[The file "${p.filename ?? 'attachment'}" was attached, but this model cannot read it directly.]` });
}
}
return out;
}
function toContents(messages: ChatMessage[], caps: Partial<ModelCapabilities>): Json[] {
const contents: Json[] = [];
for (const msg of messages) {
let parts: Json[];
if (msg.role === 'assistant') {
const pd = msg.providerData;
if (pd?.kind === 'gemini' && isRecord(pd.data) && Array.isArray(pd.data.parts)) {
parts = pd.data.parts.filter(isRecord); // thought signatures included, exactly as received
} else {
parts = [];
for (const p of msg.content) {
if (p.type === 'text' && p.text) parts.push({ text: p.text });
else if (p.type === 'tool_call') parts.push({ functionCall: { name: p.name, args: p.input ?? {} } });
}
}
} else {
parts = userParts(msg.content, caps);
}
if (parts.length === 0) continue;
const role = msg.role === 'assistant' ? 'model' : 'user';
const last = contents[contents.length - 1];
// Gemini requires strictly alternating roles; merge consecutive turns of the same role.
if (last && last.role === role) (last.parts as Json[]).push(...parts);
else contents.push({ role, parts });
}
if (contents[0]?.role === 'model') contents.unshift({ role: 'user', parts: [{ text: '(continuing the conversation)' }] });
return contents;
}
type ThinkingStyle = 'level' | 'budget' | 'off';
function thinkingStyleFor(model: string): ThinkingStyle {
const m = /gemini-(\d+)(?:\.(\d+))?/.exec(model);
if (!m) return 'level';
const major = Number(m[1]);
if (major >= 3) return 'level';
if (major === 2 && Number(m[2] ?? 0) >= 5) return 'budget';
return 'off';
}
const BUDGETS = { none: 0, low: 2_048, medium: 8_192, high: 24_576 } as const;
function buildBody(req: ChatRequest, thinking: ThinkingStyle, jsonMode: boolean): Json {
const caps = req.capabilities ?? {};
const body: Json = { contents: toContents(req.messages, caps) };
if (req.system?.trim()) body.systemInstruction = { parts: [{ text: req.system.trim() }] };
const hasTools = caps.tools !== false && (req.tools?.length ?? 0) > 0;
if (hasTools) {
body.tools = [{ functionDeclarations: req.tools!.map((t) => ({ name: t.name, description: t.description, parameters: toGeminiSchema({ type: 'object', ...t.parameters }) })) }];
const choice = req.toolChoice;
if (choice === 'none') body.toolConfig = { functionCallingConfig: { mode: 'NONE' } };
else if (choice === 'required') body.toolConfig = { functionCallingConfig: { mode: 'ANY' } };
else if (isRecord(choice)) body.toolConfig = { functionCallingConfig: { mode: 'ANY', allowedFunctionNames: [choice.name] } };
}
const gen: Json = {};
if (req.temperature !== undefined && caps.temperature !== false) gen.temperature = req.temperature;
if (req.maxOutputTokens) gen.maxOutputTokens = req.maxOutputTokens;
// JSON mode cannot be combined with function calling on most models.
if (jsonMode && req.jsonMode && !hasTools) gen.responseMimeType = 'application/json';
if (caps.reasoning !== false && thinking !== 'off') {
const effort = req.reasoningEffort;
if (thinking === 'level') {
const cfg: Json = { includeThoughts: true };
if (effort) cfg.thinkingLevel = effort === 'none' ? 'minimal' : effort;
gen.thinkingConfig = cfg;
} else if (effort) {
// 2.5 Pro cannot switch thinking off; its minimum budget is 128 tokens.
const budget = effort === 'none' && /pro/.test(req.model) ? 128 : BUDGETS[effort];
gen.thinkingConfig = { thinkingBudget: budget, includeThoughts: budget > 0 };
} else {
gen.thinkingConfig = { includeThoughts: true };
}
}
if (Object.keys(gen).length > 0) body.generationConfig = gen;
return body;
}
function mapFinish(reason: string): StopReason {
switch (reason) {
case 'STOP':
return 'end';
case 'MAX_TOKENS':
return 'max_tokens';
case 'SAFETY':
case 'RECITATION':
case 'BLOCKLIST':
case 'PROHIBITED_CONTENT':
case 'SPII':
case 'IMAGE_SAFETY':
return 'refusal';
default:
return 'other'; // MALFORMED_FUNCTION_CALL, OTHER, UNEXPECTED_TOOL_CALL, ...
}
}
function modelPath(model: string): string {
return model.startsWith('models/') || model.startsWith('tunedModels/') ? model : `models/${model}`;
}
async function* stream(cfg: ProviderConfig, req: ChatRequest): AsyncGenerator<StreamEvent> {
const ctx = errorContext(cfg);
const url = `${root(cfg)}/v1beta/${modelPath(req.model)}:streamGenerateContent?alt=sse`;
let thinking = thinkingStyleFor(req.model);
let jsonMode = true;
let http: HttpResponse;
for (let attempt = 0; ; attempt += 1) {
http = await httpRequest(url, { ...ctx, headers: headers(cfg), body: buildBody(req, thinking, jsonMode), signal: req.signal });
try {
await ensureOk(http);
break;
} catch (err) {
if (!(err instanceof AIError) || err.status !== 400 || attempt >= 3) throw err;
const detail = (err.providerMessage ?? '').toLowerCase();
if (thinking !== 'off' && /thinking|thought/.test(detail)) thinking = thinking === 'level' ? 'budget' : 'off';
else if (jsonMode && req.jsonMode && /response_?mime|json/.test(detail)) jsonMode = false;
else throw err;
}
}
const parts: Json[] = [];
const calls: { id: string; name: string; input: Record<string, unknown> }[] = [];
let text = '';
let finish = '';
let blocked = '';
const usage = { input: 0, output: 0, cacheRead: 0, reasoning: 0 };
for await (const { data } of sseJson(http)) {
if (!isRecord(data)) continue;
if (isRecord(data.error)) throw errorFromProvider(ctx, undefined, data);
if (isRecord(data.promptFeedback) && str(data.promptFeedback.blockReason)) blocked = str(data.promptFeedback.blockReason);
if (isRecord(data.usageMetadata)) {
const u = data.usageMetadata;
usage.input = num(u.promptTokenCount) || usage.input;
usage.reasoning = num(u.thoughtsTokenCount) || usage.reasoning;
// candidatesTokenCount excludes thinking; both are billed as output.
usage.output = num(u.candidatesTokenCount) + num(u.thoughtsTokenCount) || usage.output;
usage.cacheRead = num(u.cachedContentTokenCount) || usage.cacheRead;
}
const candidate = Array.isArray(data.candidates) ? data.candidates[0] : undefined;
if (!isRecord(candidate)) continue;
if (str(candidate.finishReason)) finish = str(candidate.finishReason);
const chunkParts = isRecord(candidate.content) && Array.isArray(candidate.content.parts) ? candidate.content.parts.filter(isRecord) : [];
for (const part of chunkParts) {
if (isRecord(part.functionCall)) {
const call = { id: str(part.functionCall.id) || newToolCallId('gem'), name: str(part.functionCall.name), input: isRecord(part.functionCall.args) ? part.functionCall.args : {} };
calls.push(call);
parts.push(part);
yield { type: 'tool_call', call };
} else if (typeof part.text === 'string') {
if (part.thought === true) {
if (part.text) yield { type: 'reasoning', delta: part.text };
// Thought summaries are display-only; only a signature needs to survive.
if (part.thoughtSignature) parts.push({ text: '', thought: true, thoughtSignature: part.thoughtSignature });
} else {
if (part.text) {
text += part.text;
yield { type: 'text', delta: part.text };
}
// Merge streamed text fragments, but keep a part that carries a signature intact.
const last = parts[parts.length - 1];
if (last && typeof last.text === 'string' && last.thought !== true && !last.thoughtSignature && !part.thoughtSignature) last.text += part.text;
else parts.push({ ...part });
}
} else {
parts.push(part); // inlineData, executableCode, ... replayed untouched
}
}
}
if (blocked && !text && calls.length === 0) {
throw new AIError('content_filter', 'Gemini blocked this request under its safety policy.', { providerMessage: `blockReason: ${blocked}` });
}
if (!finish && !text && calls.length === 0) {
throw new AIError('network', 'The connection to Gemini closed before the response finished.', { retryable: true });
}
if (finish === 'MALFORMED_FUNCTION_CALL' && calls.length === 0) {
throw new AIError('invalid_response', 'Gemini produced a malformed tool call. Try again.', { retryable: true });
}
const content: ContentPart[] = [];
if (text) content.push({ type: 'text', text });
for (const call of calls) content.push({ type: 'tool_call', ...call });
const message: ChatMessage = { role: 'assistant', content };
const replay = parts.filter((p) => !(typeof p.text === 'string' && p.text === '' && !p.thoughtSignature));
if (replay.length > 0) message.providerData = { kind: 'gemini', data: { parts: replay } };
yield {
type: 'done',
message,
stopReason: calls.length > 0 ? 'tool_use' : mapFinish(finish || 'STOP'),
usage: makeUsage({ input: usage.input, output: usage.output, cacheRead: usage.cacheRead, reasoning: usage.reasoning }),
};
}
async function listModels(cfg: ProviderConfig, signal?: AbortSignal, timeoutMs?: number): Promise<DiscoveredModel[]> {
const found: DiscoveredModel[] = [];
let pageToken = '';
for (let page = 0; page < 10; page += 1) {
const url = `${root(cfg)}/v1beta/models?pageSize=1000${pageToken ? `&pageToken=${encodeURIComponent(pageToken)}` : ''}`;
const res = await requestJson<Json>(url, { ...errorContext(cfg), headers: headers(cfg), signal, firstByteTimeoutMs: timeoutMs, totalTimeoutMs: timeoutMs });
for (const m of Array.isArray(res.models) ? res.models.filter(isRecord) : []) {
const id = str(m.name).replace(/^models\//, '');
const methods = Array.isArray(m.supportedGenerationMethods) ? m.supportedGenerationMethods.map(String) : [];
if (!id || !methods.includes('generateContent') || !isChatModelId(id)) continue;
if (!/^(gemini|gemma|learnlm)/.test(id)) continue;
const model: DiscoveredModel = { id };
if (str(m.displayName)) model.label = str(m.displayName);
if (num(m.inputTokenLimit)) model.contextWindow = num(m.inputTokenLimit);
if (num(m.outputTokenLimit)) model.maxOutput = num(m.outputTokenLimit);
if (typeof m.thinking === 'boolean') model.capabilities = { reasoning: m.thinking };
if (id.startsWith('gemma')) model.capabilities = { ...model.capabilities, tools: false, pdf: false };
found.push(model);
}
pageToken = str(res.nextPageToken);
if (!pageToken) break;
}
return withCatalogDefaults('gemini', found);
}
async function test(cfg: ProviderConfig): Promise<TestResult> {
return runTest(LABEL, async () => ({ modelCount: (await listModels(cfg, undefined, TEST_TIMEOUT_MS)).length }));
}
export const geminiAdapter: ProviderAdapter = {
kind: 'gemini',
meta: {
label: LABEL,
defaultBaseUrl: DEFAULT_BASE_URL,
requiresApiKey: true,
requiresBaseUrl: false,
supportsDiscovery: true,
docsUrl: 'https://aistudio.google.com/apikey',
keyHint: 'AIza…',
},
stream,
listModels: (cfg, signal) => listModels(cfg, signal),
test,
};