Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

feat(google): support Gemini Google Search grounding via google_search tool (#59) (#301)

Tashfeen3eb8e28bcf87
diff --git a/README.md b/README.md
index bc4ec0ea..ba33fddf 100644
--- a/README.md
+++ b/README.md
@@ -330,6 +330,19 @@ final = client.chat.completions.create(
print(final.choices[0].message.content)
```
+**Gemini Google Search grounding**
+
+Google's models can ground their answers in live Google Search results. Since the OpenAI wire format has no way to express that, request a tool named `google_search` and the Google provider translates it into Gemini's native grounding tool. It can be sent on its own or alongside your normal function tools.
+
+```python
+resp = client.chat.completions.create(
+ model="gemini-2.5-flash", # pin a Google model so the request routes there
+ messages=[{"role": "user", "content": "Who won the F1 race this weekend?"}],
+ tools=[{"type": "function", "function": {"name": "google_search", "parameters": {}}}],
+)
+print(resp.choices[0].message.content)
+```
+
**Vision / image input**
Send images with the standard OpenAI `image_url` content blocks (base64 `data:` URLs or `http(s)` URLs). When a request contains an image, the router restricts itself to **vision-capable models** and ignores text-only ones. Vision models are tagged with a **Vision** badge on the Fallback Chain page; the current set includes Gemini (2.5 / 3.x), Llama 4 Scout/Maverick (Groq, NVIDIA), GLM-4.6V Flash (Z.ai), Nemotron Nano 12B VL (OpenRouter), and GitHub's GPT-4o / GPT-4.1.
diff --git a/server/src/__tests__/providers/google.test.ts b/server/src/__tests__/providers/google.test.ts
index c3b7dee1..13b139a2 100644
--- a/server/src/__tests__/providers/google.test.ts
+++ b/server/src/__tests__/providers/google.test.ts
@@ -196,6 +196,61 @@ describe('GoogleProvider', () => {
expect(capturedBody.toolConfig.functionCallingConfig.allowedFunctionNames).toEqual(['get_weather']);
});
+ it('maps a google_search tool to Gemini grounding, not a function declaration (#59)', async () => {
+ let capturedBody: any;
+ vi.spyOn(global, 'fetch').mockImplementation(async (_url, init) => {
+ capturedBody = JSON.parse((init as any).body);
+ return {
+ ok: true,
+ json: () => Promise.resolve({
+ candidates: [{ content: { parts: [{ text: 'grounded answer' }] }, finishReason: 'STOP' }],
+ usageMetadata: { promptTokenCount: 1, candidatesTokenCount: 1, totalTokenCount: 2 },
+ }),
+ } as any;
+ });
+
+ await provider.chatCompletion(
+ 'test-key',
+ [{ role: 'user', content: 'Who won the match today?' }],
+ 'gemini-2.5-flash',
+ { tools: [{ type: 'function', function: { name: 'google_search', description: '', parameters: {} } }] },
+ );
+
+ expect(capturedBody.tools).toEqual([{ google_search: {} }]);
+ // Grounding-only requests must not carry a functionCallingConfig.
+ expect(capturedBody.toolConfig).toBeUndefined();
+ });
+
+ it('combines google_search grounding with real function tools (#59)', async () => {
+ let capturedBody: any;
+ vi.spyOn(global, 'fetch').mockImplementation(async (_url, init) => {
+ capturedBody = JSON.parse((init as any).body);
+ return {
+ ok: true,
+ json: () => Promise.resolve({
+ candidates: [{ content: { parts: [{ text: 'ok' }] }, finishReason: 'STOP' }],
+ usageMetadata: { promptTokenCount: 1, candidatesTokenCount: 1, totalTokenCount: 2 },
+ }),
+ } as any;
+ });
+
+ await provider.chatCompletion(
+ 'test-key',
+ [{ role: 'user', content: 'Weather plus latest news?' }],
+ 'gemini-2.5-pro',
+ {
+ tools: [
+ { type: 'function', function: { name: 'google_search', description: '', parameters: {} } },
+ { type: 'function', function: { name: 'get_weather', description: 'Get weather', parameters: { type: 'object', properties: { city: { type: 'string' } } } } },
+ ],
+ },
+ );
+
+ expect(capturedBody.tools).toContainEqual({ google_search: {} });
+ const decls = capturedBody.tools.find((t: any) => t.functionDeclarations);
+ expect(decls.functionDeclarations[0].name).toBe('get_weather');
+ });
+
it('should translate Gemini functionCall response to OpenAI tool_calls', async () => {
vi.spyOn(global, 'fetch').mockResolvedValueOnce({
ok: true,
diff --git a/server/src/providers/google.ts b/server/src/providers/google.ts
index cc37b36f..e0f8882c 100644
--- a/server/src/providers/google.ts
+++ b/server/src/providers/google.ts
@@ -145,16 +145,37 @@ export function sanitizeForGemini(schema: unknown): unknown {
return schema;
}
-function toGeminiTools(tools?: ChatToolDefinition[]): Array<{ functionDeclarations: Array<Record<string, unknown>> }> | undefined {
+// OpenAI clients can't express Gemini's native Google Search grounding, so we
+// treat a tool named `google_search` (a few spellings) as the signal to enable
+// it. It maps to Gemini's `{ google_search: {} }` tool rather than a function
+// declaration, and can ride alongside real function tools in the same array. (#59)
+const GROUNDING_TOOL_NAMES = new Set(['google_search', 'googlesearch', 'google_search_retrieval']);
+
+function toGeminiTools(tools?: ChatToolDefinition[]): Array<Record<string, unknown>> | undefined {
if (!tools || tools.length === 0) return undefined;
- return [{
- functionDeclarations: tools.map(t => ({
+ const functionDeclarations: Array<Record<string, unknown>> = [];
+ let grounding = false;
+ for (const t of tools) {
+ if (GROUNDING_TOOL_NAMES.has(t.function.name.toLowerCase())) {
+ grounding = true;
+ continue;
+ }
+ functionDeclarations.push({
name: t.function.name,
description: t.function.description,
parameters: sanitizeForGemini(t.function.parameters),
- })),
- }];
+ });
+ }
+
+ const out: Array<Record<string, unknown>> = [];
+ if (grounding) out.push({ google_search: {} });
+ if (functionDeclarations.length > 0) out.push({ functionDeclarations });
+ return out.length > 0 ? out : undefined;
+}
+
+function hasFunctionDeclarations(tools?: Array<Record<string, unknown>>): boolean {
+ return tools?.some(t => 'functionDeclarations' in t) ?? false;
}
function toGeminiToolConfig(toolChoice?: ChatToolChoice): { functionCallingConfig: Record<string, unknown> } | undefined {
@@ -373,6 +394,7 @@ export class GoogleProvider extends BaseProvider {
): Promise<ChatCompletionResponse> {
const { contents, systemInstruction } = await toGeminiContents(messages);
+ const tools = toGeminiTools(options?.tools);
const body: Record<string, unknown> = {
contents,
generationConfig: {
@@ -380,8 +402,10 @@ export class GoogleProvider extends BaseProvider {
maxOutputTokens: options?.max_tokens,
topP: options?.top_p,
},
- tools: toGeminiTools(options?.tools),
- toolConfig: toGeminiToolConfig(options?.tool_choice),
+ tools,
+ // functionCallingConfig is only valid when real function tools are present;
+ // a grounding-only request (just google_search) must omit it. (#59)
+ toolConfig: hasFunctionDeclarations(tools) ? toGeminiToolConfig(options?.tool_choice) : undefined,
};
if (systemInstruction) body.systemInstruction = systemInstruction;
@@ -436,6 +460,7 @@ export class GoogleProvider extends BaseProvider {
): AsyncGenerator<ChatCompletionChunk> {
const { contents, systemInstruction } = await toGeminiContents(messages);
+ const tools = toGeminiTools(options?.tools);
const body: Record<string, unknown> = {
contents,
generationConfig: {
@@ -443,8 +468,8 @@ export class GoogleProvider extends BaseProvider {
maxOutputTokens: options?.max_tokens,
topP: options?.top_p,
},
- tools: toGeminiTools(options?.tools),
- toolConfig: toGeminiToolConfig(options?.tool_choice),
+ tools,
+ toolConfig: hasFunctionDeclarations(tools) ? toGeminiToolConfig(options?.tool_choice) : undefined,
};
if (systemInstruction) body.systemInstruction = systemInstruction;