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:
parent
7bd0a9aad4
commit
3e74ecd843
268 changed files with 17740 additions and 55423 deletions
342
server/ai/providers/gemini.ts
Normal file
342
server/ai/providers/gemini.ts
Normal 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,
|
||||
};
|
||||
Loading…
Add table
Add a link
Reference in a new issue