@gullabs/google 0.5.2 → 0.6.1

package/dist/index.js

@@ -1,14 +1,22 @@
-import { LlmError, EFFORT_BUDGET, assertNever, classifyError, redactSecrets } from '@gullabs/core';
+import { LlmError, assertNever, classifyError, redactSecrets } from '@gullabs/core';
 
 // src/adapter.ts
-
-// src/client.ts
+function requireApiKey(auth) {
+  if (!("apiKey" in auth) || typeof auth.apiKey !== "string" || auth.apiKey.trim() === "") {
+    throw new LlmError("@gullabs/google requires auth.apiKey", {
+      kind: "invalid_auth",
+      retryable: false,
+      provider: "google"
+    });
+  }
+  return auth.apiKey;
+}
 var FLEX_DEFAULT_TIMEOUT_MS = 15e5;
 var STANDARD_DEFAULT_TIMEOUT_MS = 3e5;
 var TRANSPORT_TIMEOUT_BUFFER_MS = 5e3;
 async function buildGoogleClient(auth) {
   const { GoogleGenAI } = await import('@google/genai');
-  const ai = new GoogleGenAI({ apiKey: auth.apiKey });
+  const ai = new GoogleGenAI({ apiKey: requireApiKey(auth) });
   return {
     models: {
       async generateContent(params) {
@@ -19,6 +27,14 @@ async function buildGoogleClient(auth) {
   };
 }
 
+// src/reasoning-budget.ts
+var GOOGLE_REASONING_EFFORT_BUDGET = {
+  none: 0,
+  low: 1024,
+  medium: 8192,
+  high: 24576
+};
+
 // src/flex-fallback.ts
 var CAPACITY_PATTERNS = [
   /capacity/i,
@@ -49,6 +65,231 @@ function isGeminiCapacityError(err) {
 }
 
 // src/adapter.ts
+var ALLOWED_GOOGLE_PROVIDER_OPTION_KEYS = /* @__PURE__ */ new Set([
+  "cachedContent",
+  "httpOptions",
+  "safetySettings",
+  "tools"
+]);
+var ALLOWED_GOOGLE_HTTP_OPTION_KEYS = /* @__PURE__ */ new Set(["timeout"]);
+var RESERVED_GOOGLE_PROVIDER_OPTION_KEYS = /* @__PURE__ */ new Set([
+  "abortSignal",
+  "imageConfig",
+  "maxOutputTokens",
+  "mediaResolution",
+  "responseFormat",
+  "responseMimeType",
+  "responseModalities",
+  "responseSchema",
+  "responseJsonSchema",
+  "serviceTier",
+  "speechConfig",
+  "stopSequences",
+  "temperature",
+  "thinkingConfig",
+  "topK",
+  "topP",
+  "_responseJsonSchema"
+]);
+var GOOGLE_SEARCH_SUPPORTED_MODELS = /* @__PURE__ */ new Set([
+  "gemini-2.5-flash",
+  "gemini-2.5-flash-lite",
+  "gemini-2.5-pro",
+  "gemini-3-flash-preview",
+  "gemini-3.1-flash-lite",
+  "gemini-3.1-pro-preview",
+  "gemini-3.5-flash"
+]);
+var STRUCTURED_OUTPUT_GOOGLE_SEARCH_ALLOWLIST = /* @__PURE__ */ new Set([
+  "gemini-3.1-pro-preview",
+  "gemini-3.5-flash"
+]);
+function isPlainRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isEmptyPlainObject(value) {
+  return isPlainRecord(value) && Object.keys(value).length === 0;
+}
+function badGoogleProviderOptions(message) {
+  return new LlmError(message, { kind: "bad_request", retryable: false });
+}
+function parseGoogleTool(tool, model) {
+  if (!isPlainRecord(tool)) {
+    throw badGoogleProviderOptions(
+      `providerOptions.google.tools entries must be objects for model "${model}".`
+    );
+  }
+  const keys = Object.keys(tool);
+  if (keys.length !== 1) {
+    throw badGoogleProviderOptions(
+      `providerOptions.google.tools entries must have exactly one supported tool key for model "${model}".`
+    );
+  }
+  const key = keys[0];
+  switch (key) {
+    case "googleSearch": {
+      if (!isEmptyPlainObject(tool["googleSearch"])) {
+        throw badGoogleProviderOptions(
+          `providerOptions.google.tools[].googleSearch must be an empty object for model "${model}".`
+        );
+      }
+      return { googleSearch: {} };
+    }
+    default:
+      throw badGoogleProviderOptions(
+        `providerOptions.google.tools[].${key} is not supported for model "${model}".`
+      );
+  }
+}
+function parseGoogleSafetySetting(setting, index, model) {
+  if (!isPlainRecord(setting)) {
+    throw badGoogleProviderOptions(
+      `providerOptions.google.safetySettings[${index}] must be an object for model "${model}".`
+    );
+  }
+  const keys = Object.keys(setting);
+  const unknownKeys = keys.filter((key) => key !== "category" && key !== "threshold");
+  if (unknownKeys.length > 0) {
+    throw badGoogleProviderOptions(
+      `providerOptions.google.safetySettings[${index}] contains unsupported keys [${unknownKeys.join(
+        ", "
+      )}] for model "${model}". Allowed keys: category, threshold.`
+    );
+  }
+  if (typeof setting["category"] !== "string" || setting["category"].length === 0) {
+    throw badGoogleProviderOptions(
+      `providerOptions.google.safetySettings[${index}].category must be a non-empty string for model "${model}".`
+    );
+  }
+  if (typeof setting["threshold"] !== "string" || setting["threshold"].length === 0) {
+    throw badGoogleProviderOptions(
+      `providerOptions.google.safetySettings[${index}].threshold must be a non-empty string for model "${model}".`
+    );
+  }
+  return {
+    category: setting["category"],
+    threshold: setting["threshold"]
+  };
+}
+function mapGoogleProviderOptions(googleOpts, model, structuredOutputRequested, descriptorGrounding) {
+  if (googleOpts === void 0) {
+    return {};
+  }
+  if (!isPlainRecord(googleOpts)) {
+    throw badGoogleProviderOptions(
+      `providerOptions.google must be an object for model "${model}".`
+    );
+  }
+  const reservedKeys = Object.keys(googleOpts).filter(
+    (key) => RESERVED_GOOGLE_PROVIDER_OPTION_KEYS.has(key)
+  );
+  if (reservedKeys.length > 0) {
+    throw badGoogleProviderOptions(
+      `providerOptions.google reserves keys [${reservedKeys.join(
+        ", "
+      )}] for typed model config on "${model}".`
+    );
+  }
+  const unknownKeys = Object.keys(googleOpts).filter(
+    (key) => !ALLOWED_GOOGLE_PROVIDER_OPTION_KEYS.has(key) && !RESERVED_GOOGLE_PROVIDER_OPTION_KEYS.has(key)
+  );
+  if (unknownKeys.length > 0) {
+    throw badGoogleProviderOptions(
+      `providerOptions.google contains unsupported keys [${unknownKeys.join(
+        ", "
+      )}] for model "${model}". Allowed keys: cachedContent, httpOptions, safetySettings, tools.`
+    );
+  }
+  const mapped = {};
+  if (googleOpts["cachedContent"] !== void 0) {
+    if (typeof googleOpts["cachedContent"] !== "string" || googleOpts["cachedContent"].length === 0) {
+      throw badGoogleProviderOptions(
+        `providerOptions.google.cachedContent must be a non-empty string for model "${model}".`
+      );
+    }
+    mapped.cachedContent = googleOpts["cachedContent"];
+  }
+  if (googleOpts["httpOptions"] !== void 0) {
+    if (!isPlainRecord(googleOpts["httpOptions"])) {
+      throw badGoogleProviderOptions(
+        `providerOptions.google.httpOptions must be an object for model "${model}".`
+      );
+    }
+    const unknownHttpOptionKeys = Object.keys(googleOpts["httpOptions"]).filter(
+      (key) => !ALLOWED_GOOGLE_HTTP_OPTION_KEYS.has(key)
+    );
+    if (unknownHttpOptionKeys.length > 0) {
+      throw badGoogleProviderOptions(
+        `providerOptions.google.httpOptions contains unsupported keys [${unknownHttpOptionKeys.join(
+          ", "
+        )}] for model "${model}". Allowed keys: timeout.`
+      );
+    }
+    const timeout = googleOpts["httpOptions"]["timeout"];
+    if (timeout !== void 0) {
+      if (typeof timeout !== "number" || !Number.isInteger(timeout) || timeout <= 0) {
+        throw badGoogleProviderOptions(
+          `providerOptions.google.httpOptions.timeout must be a positive integer for model "${model}".`
+        );
+      }
+      mapped.httpOptions = { timeout };
+    } else {
+      mapped.httpOptions = {};
+    }
+  }
+  if (googleOpts["safetySettings"] !== void 0) {
+    if (!Array.isArray(googleOpts["safetySettings"])) {
+      throw badGoogleProviderOptions(
+        `providerOptions.google.safetySettings must be an array for model "${model}".`
+      );
+    }
+    mapped.safetySettings = googleOpts["safetySettings"].map(
+      (setting, index) => parseGoogleSafetySetting(setting, index, model)
+    );
+  }
+  if (googleOpts["tools"] !== void 0) {
+    if (!Array.isArray(googleOpts["tools"])) {
+      throw badGoogleProviderOptions(
+        `providerOptions.google.tools must be an array for model "${model}".`
+      );
+    }
+    const tools = googleOpts["tools"].map((tool) => parseGoogleTool(tool, model));
+    const groundingSupported = descriptorGrounding === true || descriptorGrounding === void 0 && GOOGLE_SEARCH_SUPPORTED_MODELS.has(model);
+    if (!groundingSupported) {
+      throw badGoogleProviderOptions(
+        `providerOptions.google.tools is not supported for model "${model}".`
+      );
+    }
+    if (structuredOutputRequested && !STRUCTURED_OUTPUT_GOOGLE_SEARCH_ALLOWLIST.has(model)) {
+      throw badGoogleProviderOptions(
+        `Structured output with googleSearch is supported only for models "gemini-3.1-pro-preview" and "gemini-3.5-flash"; got "${model}".`
+      );
+    }
+    mapped.tools = tools;
+  }
+  return mapped;
+}
+function assertSamplingAllowed(config, model, sampling) {
+  if (sampling !== "fixed") {
+    return;
+  }
+  const offendingSampling = [];
+  if ("temperature" in config) {
+    offendingSampling.push("temperature");
+  }
+  if ("topP" in config) {
+    offendingSampling.push("topP");
+  }
+  if ("topK" in config) {
+    offendingSampling.push("topK");
+  }
+  if (offendingSampling.length > 0) {
+    throw new LlmError(
+      `Sampling parameters [${offendingSampling.join(", ")}] are not supported for model "${model}" (fixed sampling).`,
+      { kind: "bad_request", retryable: false }
+    );
+  }
+}
 function mapFinishReason(raw) {
   if (raw === void 0) return void 0;
   switch (raw) {
@@ -170,12 +411,6 @@ function geminiAdapter(opts) {
           );
         }
         config.serviceTier = explicit;
-      } else {
-        if (req.modelDescriptor === void 0) {
-          config.serviceTier = "flex";
-        } else if (supported?.includes("flex") === true) {
-          config.serviceTier = "flex";
-        }
       }
       const reasoning = genConfig.reasoning;
       if (reasoning !== void 0) {
@@ -187,7 +422,7 @@ function geminiAdapter(opts) {
           );
         }
         if (reasoningApi === "budget") {
-          const budget = reasoning.budgetTokens !== void 0 ? reasoning.budgetTokens : reasoning.effort !== void 0 ? EFFORT_BUDGET[reasoning.effort] : void 0;
+          const budget = reasoning.budgetTokens !== void 0 ? reasoning.budgetTokens : reasoning.effort !== void 0 ? GOOGLE_REASONING_EFFORT_BUDGET[reasoning.effort] : void 0;
           config.thinkingConfig = {
             ...budget !== void 0 ? { thinkingBudget: budget } : {},
             ...reasoning.includeThoughts === true ? { includeThoughts: true } : {}
@@ -237,54 +472,25 @@ function geminiAdapter(opts) {
           config.responseSchema = req.outputJsonSchema;
         }
       }
-      const googleOpts = genConfig.providerOptions?.["google"];
-      if (googleOpts !== void 0 && typeof googleOpts === "object" && googleOpts !== null) {
-        Object.assign(config, googleOpts);
+      const googleProviderConfig = mapGoogleProviderOptions(
+        genConfig.providerOptions?.["google"],
+        model,
+        structuredOutputRequested,
+        req.modelDescriptor?.capabilities?.grounding
+      );
+      if (googleProviderConfig.cachedContent !== void 0) {
+        config.cachedContent = googleProviderConfig.cachedContent;
       }
-      const mergedServiceTier = config.serviceTier;
-      if (mergedServiceTier !== void 0 && req.modelDescriptor !== void 0) {
-        const supportedAfterMerge = req.modelDescriptor.capabilities?.serviceTiers;
-        if (supportedAfterMerge === void 0 || !supportedAfterMerge.includes(mergedServiceTier)) {
-          throw new LlmError(
-            `serviceTier "${mergedServiceTier}" is not supported for model "${model}".`,
-            { kind: "bad_request", retryable: false }
-          );
-        }
+      if (googleProviderConfig.httpOptions !== void 0) {
+        config.httpOptions = googleProviderConfig.httpOptions;
       }
-      if (req.modelDescriptor?.capabilities?.sampling === "fixed") {
-        const offendingSampling = [];
-        if ("temperature" in config) {
-          offendingSampling.push("temperature");
-        }
-        if ("topP" in config) {
-          offendingSampling.push("topP");
-        }
-        if ("topK" in config) {
-          offendingSampling.push("topK");
-        }
-        if (offendingSampling.length > 0) {
-          throw new LlmError(
-            `Sampling parameters [${offendingSampling.join(
-              ", "
-            )}] are not supported for model "${model}" (fixed sampling); they were supplied via providerOptions.google.`,
-            { kind: "bad_request", retryable: false }
-          );
-        }
+      if (googleProviderConfig.safetySettings !== void 0) {
+        config.safetySettings = googleProviderConfig.safetySettings;
       }
-      const configAsAny = config;
-      const groundingRequested = Array.isArray(configAsAny.tools) && configAsAny.tools.some((t) => {
-        if (t !== null && typeof t === "object") {
-          const tool = t;
-          return "googleSearch" in tool || "googleSearchRetrieval" in tool;
-        }
-        return false;
-      });
-      if (groundingRequested && structuredOutputRequested) {
-        throw new LlmError(
-          "Grounding (googleSearch) cannot be combined with structured output (output.jsonSchema) on Gemini; choose one.",
-          { kind: "bad_request", retryable: false }
-        );
+      if (googleProviderConfig.tools !== void 0) {
+        config.tools = googleProviderConfig.tools;
       }
+      assertSamplingAllowed(config, model, req.modelDescriptor?.capabilities?.sampling);
       let tierTimeoutHandle;
       const clearTierTimeout = () => {
         if (tierTimeoutHandle !== void 0) {
@@ -471,11 +677,11 @@ var DEFAULT_TIMEOUT_MS = 3e5;
 var realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 async function buildFilesClient(auth) {
   const { GoogleGenAI } = await import('@google/genai');
-  const ai = new GoogleGenAI({ apiKey: auth.apiKey });
+  const ai = new GoogleGenAI({ apiKey: requireApiKey(auth) });
   return {
     async upload(params) {
       const fileArg = params.file instanceof Uint8Array ? new Blob(
-        [params.file],
+        [Uint8Array.from(params.file)],
         params.config?.mimeType !== void 0 && params.config.mimeType.length > 0 ? { type: params.config.mimeType } : {}
       ) : params.file;
       const result = await ai.files.upload({
@@ -658,7 +864,7 @@ var DEFAULT_SKEW_SECONDS = 30;
 var DEFAULT_EXTENSION_SECONDS = 3600;
 async function buildCachesClient(auth) {
   const { GoogleGenAI } = await import('@google/genai');
-  const ai = new GoogleGenAI({ apiKey: auth.apiKey });
+  const ai = new GoogleGenAI({ apiKey: requireApiKey(auth) });
   return {
     async create(params) {
       const result = await ai.caches.create(params);
@@ -904,6 +1110,6 @@ function normalizeGroundingCitations(groundingMetadata) {
   return citations;
 }
 
-export { FLEX_DEFAULT_TIMEOUT_MS, GoogleCacheStore, GoogleFileStore, STANDARD_DEFAULT_TIMEOUT_MS, TRANSPORT_TIMEOUT_BUFFER_MS, buildGoogleClient, geminiAdapter, isGeminiCapacityError, normalizeGroundingCitations };
+export { FLEX_DEFAULT_TIMEOUT_MS, GoogleCacheStore, GoogleFileStore, STANDARD_DEFAULT_TIMEOUT_MS, TRANSPORT_TIMEOUT_BUFFER_MS, buildGoogleClient, geminiAdapter, isGeminiCapacityError, normalizeGroundingCitations, requireApiKey };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map