@gullabs/google 0.10.0 → 0.11.0

package/README.md

@@ -22,10 +22,8 @@ pnpm add @gullabs/google @gullabs/core @google/genai
 | `isGeminiCapacityError(err)`                                               | Detects Gemini Flex shared-capacity errors for built-in fallback                      |
 | `geminiModelDescriptors`, `gemmaModelDescriptors`, `defaultGeminiRegistry` | Built-in model descriptors + pre-built registry                                       |
 | `geminiPricingSource()`, `GEMINI_PRICING`, `TIER_FACTOR`                   | Built-in Gemini pricing snapshot and tier-factor map                                  |
-
-
-| `GoogleFileStore` | Files API: upload + poll ACTIVE + delete |
-| `FileDeleteOptions` | `{ failClosed?, signal? }` — opt-in fail-closed delete (parity with `@gullabs/xai`) |
+| `GoogleFileStore`                                                          | Files API: upload + poll ACTIVE + delete                                              |
+| `FileDeleteOptions`                                                        | `{ failClosed?, signal? }` — opt-in fail-closed delete (parity with `@gullabs/xai`)   |
 
 ## File store delete modes
 
@@ -67,7 +65,7 @@ const result = await client.generate(
 - `output.jsonSchema` → `responseMimeType: 'application/json'` + verbatim `responseSchema` when native structured output is enabled; the engine returns parsed output and `outputParsed` without validating shape
 - `providerOptions.google.*` → typed provider-extension lane for admitted keys such as `cachedContent`, `safetySettings`, and exact tool declarations
 - Usage: `promptTokenCount`→`inputTokens`, `candidatesTokenCount`+`thoughtsTokenCount`→`outputTokens` (GROSS)
-- Errors: `401/403`→`invalid_auth`, `429`→`rate_limited`, `5xx`→`server`, timeouts, safety blocks
+- Errors: `401` and a bare `403` default to `invalid_auth`; `429`→`rate_limited`; `5xx`→`server`; timeouts; Gemini safety blocks are a 200-path `content_filter` (`promptFeedback.blockReason` / no candidates), not an HTTP 403
 
 ## Strict model-config expectations
 

package/dist/index.cjs

@@ -42,6 +42,49 @@ var GOOGLE_REASONING_EFFORT_BUDGET = {
   high: 24576
 };
 
+// src/grounding.ts
+function hostnameFrom(url) {
+  return url.hostname.startsWith("www.") ? url.hostname.slice(4) : url.hostname;
+}
+function toCitation(chunk) {
+  if (chunk === null || typeof chunk !== "object") return void 0;
+  const web = chunk["web"];
+  if (web === null || typeof web !== "object") return void 0;
+  const uri = web["uri"];
+  if (typeof uri !== "string" || uri.length === 0) return void 0;
+  let parsed;
+  try {
+    parsed = new URL(uri);
+  } catch {
+    return void 0;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return void 0;
+  if (parsed.hostname === "") return void 0;
+  const title = web["title"];
+  const hasTitle = typeof title === "string" && title.length > 0;
+  const sourceName = hasTitle ? title : hostnameFrom(parsed);
+  return {
+    url: uri,
+    ...hasTitle ? { title } : {},
+    sourceName
+  };
+}
+function normalizeGroundingCitations(groundingMetadata) {
+  if (groundingMetadata === null || typeof groundingMetadata !== "object") return [];
+  const chunks = groundingMetadata["groundingChunks"];
+  if (!Array.isArray(chunks)) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const citations = [];
+  for (const chunk of chunks) {
+    const citation = toCitation(chunk);
+    if (citation === void 0) continue;
+    if (seen.has(citation.url)) continue;
+    seen.add(citation.url);
+    citations.push(citation);
+  }
+  return citations;
+}
+
 // src/flex-fallback.ts
 var CAPACITY_PATTERNS = [
   /capacity/i,
@@ -389,6 +432,12 @@ function mapUsage(meta) {
   };
   return usage;
 }
+function mapGoogleToolChoice(choice) {
+  if (choice === "auto") return { mode: "AUTO" };
+  if (choice === "required") return { mode: "ANY" };
+  if (choice === "none") return { mode: "NONE" };
+  return { mode: "ANY", allowedFunctionNames: [choice.name] };
+}
 function mapPart(p) {
   switch (p.kind) {
     case "text":
@@ -416,6 +465,20 @@ function mapPart(p) {
         "Google Gemini expects FileUriPart with a Files API uri; got file-ref (provider file id). Upload via GoogleFileStore and pass the returned uri.",
         { kind: "bad_request", retryable: false, provider: "google" }
       );
+    case "tool-call":
+      return {
+        functionCall: {
+          name: p.toolName,
+          args: p.args
+        }
+      };
+    case "tool-result":
+      return {
+        functionResponse: {
+          name: p.toolName,
+          response: p.isError === true ? { error: p.result } : p.result
+        }
+      };
     default:
       return core.assertNever(p);
   }
@@ -559,6 +622,34 @@ function geminiAdapter(opts) {
       if (googleProviderConfig.tools !== void 0) {
         config.tools = googleProviderConfig.tools;
       }
+      if (req.tools !== void 0 && req.tools.length > 0) {
+        if (req.modelDescriptor?.capabilities?.functionCalling !== true) {
+          throw new core.LlmError(
+            `tools is not supported for google model "${model}" (capabilities.functionCalling is not true).`,
+            { kind: "bad_request", retryable: false, provider: "google" }
+          );
+        }
+        if (googleProviderConfig.tools !== void 0) {
+          throw new core.LlmError(
+            "tools cannot be combined with providerOptions.google.tools (googleSearch) in this iteration.",
+            { kind: "bad_request", retryable: false, provider: "google" }
+          );
+        }
+        config.tools = [
+          {
+            functionDeclarations: req.tools.map((tool) => ({
+              name: tool.name,
+              description: tool.description,
+              parameters: tool.inputJsonSchema
+            }))
+          }
+        ];
+        if (req.toolChoice !== void 0) {
+          config.toolConfig = {
+            functionCallingConfig: mapGoogleToolChoice(req.toolChoice)
+          };
+        }
+      }
       assertSamplingAllowed(config, model, req.modelDescriptor?.capabilities?.sampling);
       let tierTimeoutHandle;
       const clearTierTimeout = () => {
@@ -676,7 +767,15 @@ function geminiAdapter(opts) {
       const parts = candidate.content?.parts ?? [];
       const textParts = [];
       const thoughtParts = [];
+      const toolCalls = [];
       for (const part of parts) {
+        if (part.functionCall !== void 0 && typeof part.functionCall.name === "string") {
+          toolCalls.push({
+            toolCallId: part.functionCall.name,
+            toolName: part.functionCall.name,
+            args: part.functionCall.args ?? {}
+          });
+        }
         if (part.text !== void 0) {
           if (part.thought === true) {
             thoughtParts.push(part.text);
@@ -704,7 +803,7 @@ function geminiAdapter(opts) {
         ...text.length > 0 ? { text } : {},
         ...reasoningText !== void 0 ? { reasoningText } : {},
         ...rawStructured !== void 0 ? { rawStructured } : {},
-        ...finishReason !== void 0 ? { finishReason } : {},
+        ...toolCalls.length > 0 ? { toolCalls, finishReason: "tool_calls" } : finishReason !== void 0 ? { finishReason } : {},
         ...response.modelVersion !== void 0 ? { modelVersion: response.modelVersion } : {},
         ...response.responseId !== void 0 ? { responseId: response.responseId } : {},
         // Build providerMetadata — merge promptFeedback + groundingMetadata when present.
@@ -720,6 +819,12 @@ function geminiAdapter(opts) {
             meta["groundingMetadata"] = gm;
           }
           return { providerMetadata: meta };
+        })(),
+        ...(() => {
+          const gm = candidate.groundingMetadata;
+          if (gm === void 0) return {};
+          const citations = normalizeGroundingCitations(gm);
+          return citations.length > 0 ? { citations } : {};
         })()
       };
       return result;
@@ -732,13 +837,23 @@ function geminiAdapter(opts) {
         );
       }
       const contents = mapMessagesToGeminiContents(req.messages);
+      const countTools = req.tools !== void 0 && req.tools.length > 0 ? [
+        {
+          functionDeclarations: req.tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.inputJsonSchema
+          }))
+        }
+      ] : void 0;
       const params = {
         model: req.model,
         contents,
-        ...req.system !== void 0 || ctx.signal !== void 0 ? {
+        ...req.system !== void 0 || ctx.signal !== void 0 || countTools !== void 0 ? {
           config: {
             ...req.system !== void 0 ? { systemInstruction: { parts: [{ text: req.system }] } } : {},
-            ...ctx.signal !== void 0 ? { abortSignal: ctx.signal } : {}
+            ...ctx.signal !== void 0 ? { abortSignal: ctx.signal } : {},
+            ...countTools !== void 0 ? { tools: countTools } : {}
           }
         } : {}
       };
@@ -755,6 +870,7 @@ function geminiAdapter(opts) {
         const details = response.cachedContentTokenCount !== void 0 ? { cached: response.cachedContentTokenCount } : void 0;
         return {
           totalTokens: response.totalTokens,
+          accuracy: "exact",
           ...details !== void 0 ? { details } : {},
           raw: response
         };
@@ -2538,6 +2654,7 @@ var geminiModelDescriptors = [
       sampling: "tunable",
       caching: { explicit: true, minTokens: 2048 },
       grounding: true,
+      functionCalling: true,
       serviceTiers: ["flex", "standard"]
     },
     configSchema: Gemini25ProConfigSchema,
@@ -2558,6 +2675,7 @@ var geminiModelDescriptors = [
       sampling: "tunable",
       caching: { explicit: true, minTokens: 2048 },
       grounding: true,
+      functionCalling: true,
       serviceTiers: ["flex", "standard"]
     },
     configSchema: Gemini25FlashConfigSchema,
@@ -2578,6 +2696,7 @@ var geminiModelDescriptors = [
       sampling: "tunable",
       caching: { explicit: true, minTokens: 2048 },
       grounding: true,
+      functionCalling: true,
       serviceTiers: ["flex", "standard"]
     },
     configSchema: Gemini25FlashLiteConfigSchema,
@@ -2598,6 +2717,7 @@ var geminiModelDescriptors = [
       sampling: "fixed",
       caching: { explicit: true, minTokens: 2048 },
       grounding: true,
+      functionCalling: true,
       serviceTiers: ["flex", "standard"]
     },
     configSchema: Gemini35FlashConfigSchema,
@@ -2618,6 +2738,7 @@ var geminiModelDescriptors = [
       sampling: "fixed",
       caching: { explicit: true, minTokens: 2048 },
       grounding: true,
+      functionCalling: true,
       serviceTiers: ["flex", "standard"]
     },
     configSchema: Gemini31FlashLiteConfigSchema,
@@ -2638,6 +2759,7 @@ var geminiModelDescriptors = [
       sampling: "fixed",
       caching: { explicit: true, minTokens: 2048 },
       grounding: true,
+      functionCalling: true,
       serviceTiers: ["flex", "standard"]
     },
     configSchema: Gemini31ProPreviewConfigSchema,
@@ -2658,6 +2780,7 @@ var geminiModelDescriptors = [
       sampling: "fixed",
       caching: { explicit: true, minTokens: 2048 },
       grounding: true,
+      functionCalling: true,
       serviceTiers: ["flex", "standard"]
     },
     configSchema: Gemini3FlashPreviewConfigSchema,
@@ -3193,44 +3316,6 @@ var GoogleCacheStore = class {
     }
   }
 };
-
-// src/grounding.ts
-function hostnameFrom(url) {
-  return url.hostname.startsWith("www.") ? url.hostname.slice(4) : url.hostname;
-}
-function toCitation(chunk) {
-  if (chunk === null || typeof chunk !== "object") return void 0;
-  const web = chunk["web"];
-  if (web === null || typeof web !== "object") return void 0;
-  const uri = web["uri"];
-  if (typeof uri !== "string" || uri.length === 0) return void 0;
-  let parsed;
-  try {
-    parsed = new URL(uri);
-  } catch {
-    return void 0;
-  }
-  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return void 0;
-  if (parsed.hostname === "") return void 0;
-  const title = web["title"];
-  const sourceName = typeof title === "string" && title.length > 0 ? title : hostnameFrom(parsed);
-  return { url: uri, sourceName };
-}
-function normalizeGroundingCitations(groundingMetadata) {
-  if (groundingMetadata === null || typeof groundingMetadata !== "object") return [];
-  const chunks = groundingMetadata["groundingChunks"];
-  if (!Array.isArray(chunks)) return [];
-  const seen = /* @__PURE__ */ new Set();
-  const citations = [];
-  for (const chunk of chunks) {
-    const citation = toCitation(chunk);
-    if (citation === void 0) continue;
-    if (seen.has(citation.url)) continue;
-    seen.add(citation.url);
-    citations.push(citation);
-  }
-  return citations;
-}
 function badRequest(message) {
   return new core.LlmError(message, { kind: "bad_request", retryable: false });
 }
@@ -3273,13 +3358,37 @@ function convertPart(part, location) {
     (key) => key === "text" || key === "inlineData" || key === "fileData"
   );
   if (baseKeys.length === 0) {
+    if (keys.includes("functionCall") && keys.every((k) => k === "functionCall")) {
+      const fc = part.functionCall;
+      if (fc === void 0 || typeof fc.name !== "string" || fc.name.length === 0) {
+        throw badRequest(`${location}: functionCall.name is required.`);
+      }
+      return {
+        kind: "tool-call",
+        toolCallId: fc.name,
+        toolName: fc.name,
+        args: fc.args ?? {}
+      };
+    }
+    if (keys.includes("functionResponse") && keys.every((k) => k === "functionResponse")) {
+      const fr = part.functionResponse;
+      if (fr === void 0 || typeof fr.name !== "string" || fr.name.length === 0) {
+        throw badRequest(`${location}: functionResponse.name is required.`);
+      }
+      return {
+        kind: "tool-result",
+        toolCallId: fr.name,
+        toolName: fr.name,
+        result: fr.response ?? null
+      };
+    }
     if (keys.length === 0) {
       throw badRequest(
         `${location}: Part has no recognized fields set (expected exactly one of text, inlineData, fileData).`
       );
     }
     throw badRequest(
-      `${location}: Part keys [${keys.join(", ")}] are not supported by geminiContentToMessages \u2014 only text, inlineData, and fileData parts can be represented in any-llm.`
+      `${location}: Part keys [${keys.join(", ")}] are not supported by geminiContentToMessages \u2014 only text, inlineData, fileData, functionCall, and functionResponse parts can be represented in any-llm.`
     );
   }
   if (baseKeys.length > 1) {
@@ -3418,7 +3527,6 @@ exports.geminiPricingSource = geminiPricingSource;
 exports.gemmaModelDescriptors = gemmaModelDescriptors;
 exports.googleProvider = googleProvider;
 exports.isGeminiCapacityError = isGeminiCapacityError;
-exports.normalizeGroundingCitations = normalizeGroundingCitations;
 exports.pricingVersion = pricingVersion;
 exports.requireApiKey = requireApiKey;
 //# sourceMappingURL=index.cjs.map