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>
342 lines
16 KiB
TypeScript
342 lines
16 KiB
TypeScript
/**
|
|
* 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,
|
|
};
|