/** * 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; 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 { 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): 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): 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 { 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 }[] = []; 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 { 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(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 { 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, };