@gullabs/google 0.5.2 → 0.6.1

package/README.md

@@ -44,13 +44,33 @@ const result = await client.generate(
 ## What it maps
 
 - `serviceTier: 'flex'` → Gemini Flex service tier when the model descriptor supports it
+- omitted `serviceTier` → provider-default request behavior
 - `reasoning.includeThoughts` → `thinkingConfig.includeThoughts`; thought parts become `reasoningText`
-- `reasoning.effort` → `thinkingBudget` (gemini-2.5) or `thinkingLevel` (gemini-3.x) with a warning when lossy
+- `reasoning.effort` → `thinkingBudget` (Gemini 2.5) or `thinkingLevel` (Gemini 3 / Gemma 4)
+- `reasoning.budgetTokens` → admitted only on Gemini 2.5 budget-api models; strict descriptors reject it on level-api models
 - `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.*` → forwarded verbatim to the SDK config, including Gemini `safetySettings`
+- `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
 
+## Strict model-config expectations
+
+This adapter expects config that has already been parsed through the selected
+descriptor boundary:
+
+- `descriptor.configSchema` is the runtime source of truth.
+- `descriptor.configJsonSchema` is the derived form/UI schema.
+- `providerOptions.google` is not a caller-wins override lane for
+  `serviceTier`, sampling, reasoning, or response schema.
+- `priority` stays rejected even though Google documents it, because the
+  library has not yet shipped the matching schema, pricing, served-tier
+  recording, and tests.
+
+For structured output with built-in tools, follow the exact public
+`generateContent` evidence: the current docs only admit that combination for
+`gemini-3.1-pro-preview` and `gemini-3.5-flash`. Other models should fail early
+instead of relying on adapter repair or provider-side surprises.
+
 ## Gemma 4
 
 The default registry includes two API-verified Gemma 4 models: `gemma-4-31b-it`
@@ -72,8 +92,9 @@ This follows the library-wide **reject, don't map** rule: unsupported or incorre
 typed `bad_request` `LlmError` at validation time rather than being silently clamped or coerced
 into something the model happens to accept.
 
-Gemma 4 models do **not** support Gemini Flex service tier (`serviceTiers` is absent from their
-descriptors) and are unpriced (`cost.microUsd` will be `null`).
+Gemma 4 models are intentionally unpriced (`cost.microUsd` will be `null`), and
+the strict contract does not admit any `serviceTier` for them until the public
+docs and live evidence line up on that field.
 
 ## Learn more
 

package/dist/index.cjs

@@ -3,14 +3,22 @@
 var core = require('@gullabs/core');
 
 // src/adapter.ts
-
-// src/client.ts
+function requireApiKey(auth) {
+  if (!("apiKey" in auth) || typeof auth.apiKey !== "string" || auth.apiKey.trim() === "") {
+    throw new core.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) {
@@ -21,6 +29,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,
@@ -51,6 +67,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 core.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 core.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) {
@@ -172,12 +413,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) {
@@ -189,7 +424,7 @@ function geminiAdapter(opts) {
           );
         }
         if (reasoningApi === "budget") {
-          const budget = reasoning.budgetTokens !== void 0 ? reasoning.budgetTokens : reasoning.effort !== void 0 ? core.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 } : {}
@@ -239,54 +474,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 core.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 core.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 core.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) {
@@ -473,11 +679,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({
@@ -660,7 +866,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);
@@ -915,5 +1121,6 @@ exports.buildGoogleClient = buildGoogleClient;
 exports.geminiAdapter = geminiAdapter;
 exports.isGeminiCapacityError = isGeminiCapacityError;
 exports.normalizeGroundingCitations = normalizeGroundingCitations;
+exports.requireApiKey = requireApiKey;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map