@gullabs/google 0.2.0 → 0.3.0

package/LICENSE

@@ -176,7 +176,7 @@
       comment syntax for the file format in please. Also attach a copy of
       this License to your work.
 
-      Copyright 2026 Atif Gul
+      Copyright 2026 Gul Labs
 
       Licensed under the Apache License, Version 2.0 (the "License");
       you may not use this file except in compliance with the License.

package/README.md

@@ -6,13 +6,13 @@ Gemini provider adapter for any-llm. A thin mapping layer over `@google/genai` t
 
 ## Key exports
 
-| Export                      | What it is                                                                    |
-| --------------------------- | ----------------------------------------------------------------------------- |
-| `geminiAdapter(opts?)`      | Creates the `ProviderAdapter` for Gemini                                      |
-| `GeminiAdapterOptions`      | `{ client?: GeminiClientLike }` — inject a pre-built or fake client           |
-| `GeminiClientLike`          | Structural interface the adapter depends on (satisfied by real SDK and fakes) |
-| `buildGoogleClient(auth)`   | Builds the real `@google/genai` client from `AuthMaterial`                    |
-| `zodToGeminiSchema(schema)` | Converts a Zod schema to a Gemini `responseSchema` object                     |
+| Export                       | What it is                                                                    |
+| ---------------------------- | ----------------------------------------------------------------------------- |
+| `geminiAdapter(opts?)`       | Creates the `ProviderAdapter` for Gemini                                      |
+| `GeminiAdapterOptions`       | `{ client?: GeminiClientLike }` — inject a pre-built or fake client           |
+| `GeminiClientLike`           | Structural interface the adapter depends on (satisfied by real SDK and fakes) |
+| `buildGoogleClient(auth)`    | Builds the real `@google/genai` client from `AuthMaterial`                    |
+| `isGeminiCapacityError(err)` | Detects Gemini Flex shared-capacity errors for built-in fallback              |
 
 ## Quick example
 
@@ -37,10 +37,30 @@ const result = await client.generate(
 
 ## What it maps
 
-- `serviceTier: 'flex'` → Gemini Flex service tier (default)
+- `serviceTier: 'flex'` → Gemini Flex service tier when the model descriptor supports it
 - `reasoning.includeThoughts` → `thinkingConfig.includeThoughts`; thought parts become `reasoningText`
 - `reasoning.effort` → `thinkingBudget` (gemini-2.5) or `thinkingLevel` (gemini-3.x) with a warning when lossy
-- `output.schema` → `responseMimeType: 'application/json'` + `responseSchema` (Zod-converted)
-- `providerOptions.google.*` → forwarded verbatim to the SDK config
+- `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`
 - Usage: `promptTokenCount`→`inputTokens`, `candidatesTokenCount`+`thoughtsTokenCount`→`outputTokens` (GROSS)
 - Errors: `401/403`→`invalid_auth`, `429`→`rate_limited`, `5xx`→`server`, timeouts, safety blocks
+
+## Gemma 4
+
+The default registry includes two API-verified Gemma 4 models: `gemma-4-31b-it`
+and `gemma-4-26b-a4b-it`. Both route through this adapter and support:
+
+- **Native structured output** — `responseMimeType` + verbatim `responseSchema` are sent
+  automatically when `output.jsonSchema` is set.
+- **Grounding** — `tools:[{googleSearch:{}}]` via `providerOptions.google`.
+- **Vision** — `inline-media` and `file-uri` multimodal message parts.
+- **Thinking** — `reasoning.effort` maps to `thinkingLevel` (`reasoningApi: 'level'`).
+  Gemma 4 thinking is binary: only `effort: 'none'` (MINIMAL) and `effort: 'high'`
+  (HIGH) are accepted. Passing `effort: 'low'` or `effort: 'medium'` is rejected at
+  validation time with a `bad_request` error because the model only supports MINIMAL
+  and HIGH `thinkingLevel` values. Note: `thinkingBudget` is **not** supported
+  (rejected by the API with HTTP 400).
+- **Tunable sampling** — `temperature`, `topP`, `topK` are accepted.
+
+Gemma 4 models do **not** support Gemini Flex service tier (`serviceTiers` is absent from their
+descriptors) and are unpriced (`cost.microUsd` will be `null`).

package/dist/index.cjs

@@ -1,12 +1,12 @@
 'use strict';
 
 var core = require('@gullabs/core');
-var zod = require('zod');
 
 // src/adapter.ts
 
 // src/client.ts
 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');
@@ -20,121 +20,34 @@ async function buildGoogleClient(auth) {
     }
   };
 }
-function isOptionalField(schema) {
-  if (schema instanceof zod.ZodOptional || schema instanceof zod.ZodDefault) return true;
-  if (schema instanceof zod.ZodNullable) {
-    const unwrapped = schema.unwrap();
-    return isOptionalField(unwrapped);
-  }
-  return false;
-}
-function zodToGeminiSchema(schema) {
-  return convertSchema(schema, false);
-}
-function convertSchema(schema, nullable) {
-  const desc = typeof schema.description === "string" ? schema.description : void 0;
-  if (schema instanceof zod.ZodOptional) {
-    const unwrapped = schema.unwrap();
-    return convertSchema(unwrapped, nullable);
-  }
-  if (schema instanceof zod.ZodNullable) {
-    const unwrapped = schema.unwrap();
-    return convertSchema(unwrapped, true);
-  }
-  if (schema instanceof zod.ZodDefault) {
-    const innerType = schema._def.innerType;
-    return convertSchema(innerType, nullable);
-  }
-  if (schema instanceof zod.ZodObject) {
-    const shape = schema.shape;
-    const properties = {};
-    const required = [];
-    for (const [key, fieldType] of Object.entries(shape)) {
-      const fieldSchema = convertSchema(fieldType, false);
-      if (fieldSchema === void 0) return void 0;
-      properties[key] = fieldSchema;
-      if (!isOptionalField(fieldType)) {
-        required.push(key);
-      }
-    }
-    const result = {
-      type: "object",
-      properties,
-      ...required.length > 0 ? { required } : {},
-      ...desc !== void 0 ? { description: desc } : {},
-      ...nullable ? { nullable: true } : {}
-    };
-    return result;
-  }
-  if (schema instanceof zod.ZodString) {
-    return {
-      type: "string",
-      ...desc !== void 0 ? { description: desc } : {},
-      ...nullable ? { nullable: true } : {}
-    };
-  }
-  if (schema instanceof zod.ZodNumber) {
-    const checks = schema._def.checks ?? [];
-    const isInt = checks.some((c) => c.kind === "int");
-    return {
-      type: isInt ? "integer" : "number",
-      ...desc !== void 0 ? { description: desc } : {},
-      ...nullable ? { nullable: true } : {}
-    };
-  }
-  if (schema instanceof zod.ZodBoolean) {
-    return {
-      type: "boolean",
-      ...desc !== void 0 ? { description: desc } : {},
-      ...nullable ? { nullable: true } : {}
-    };
-  }
-  if (schema instanceof zod.ZodArray) {
-    const element = schema.element;
-    const items = convertSchema(element, false);
-    if (items === void 0) return void 0;
-    return {
-      type: "array",
-      items,
-      ...desc !== void 0 ? { description: desc } : {},
-      ...nullable ? { nullable: true } : {}
-    };
-  }
-  if (schema instanceof zod.ZodEnum) {
-    return {
-      type: "string",
-      enum: schema.options,
-      ...desc !== void 0 ? { description: desc } : {},
-      ...nullable ? { nullable: true } : {}
-    };
-  }
-  if (schema instanceof zod.ZodLiteral) {
-    const val = schema.value;
-    if (typeof val === "string") {
-      return {
-        type: "string",
-        enum: [val],
-        ...desc !== void 0 ? { description: desc } : {},
-        ...nullable ? { nullable: true } : {}
-      };
-    }
-    if (typeof val === "number") {
-      return {
-        type: "number",
-        ...desc !== void 0 ? { description: desc } : {},
-        ...nullable ? { nullable: true } : {}
-      };
-    }
-    if (typeof val === "boolean") {
-      return {
-        type: "boolean",
-        ...desc !== void 0 ? { description: desc } : {},
-        ...nullable ? { nullable: true } : {}
-      };
-    }
-    return void 0;
+
+// src/flex-fallback.ts
+var CAPACITY_PATTERNS = [
+  /capacity/i,
+  /overload/i,
+  /overloaded/i,
+  /unavailable/i,
+  /no\s+capacity/i,
+  /temporar(?:y|ily)/i,
+  /try\s+again/i
+];
+var QUOTA_PATTERNS = [
+  /quota/i,
+  /billing/i,
+  /billable/i,
+  /payment/i,
+  /rate\s+limit/i,
+  /exceeded/i,
+  /insufficient/i
+];
+function isGeminiCapacityError(err) {
+  if (err.kind === "server") return err.httpStatus === 503;
+  if (err.kind !== "rate_limited") return false;
+  const message = err.message;
+  if (QUOTA_PATTERNS.some((pattern) => pattern.test(message))) {
+    return false;
   }
-  return void 0;
+  return CAPACITY_PATTERNS.some((pattern) => pattern.test(message));
 }
 
 // src/adapter.ts
@@ -255,24 +168,45 @@ function geminiAdapter(opts) {
       if (genConfig.stopSequences !== void 0) {
         config.stopSequences = genConfig.stopSequences;
       }
-      config.serviceTier = genConfig.serviceTier === "standard" ? "standard" : "flex";
+      const explicit = genConfig.serviceTier;
+      const supported = req.modelDescriptor?.capabilities?.serviceTiers;
+      if (explicit !== void 0) {
+        if (req.modelDescriptor !== void 0 && (supported === void 0 || !supported.includes(explicit))) {
+          throw new core.LlmError(
+            `serviceTier "${explicit}" is not supported for model "${model}".`,
+            { kind: "bad_request", retryable: false }
+          );
+        }
+        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) {
         const reasoningApi = req.modelDescriptor?.capabilities?.reasoningApi;
+        if (reasoning.effort !== void 0 && reasoning.budgetTokens !== void 0) {
+          throw new core.LlmError(
+            `Provide either reasoning.effort or reasoning.budgetTokens, not both, for model "${model}".`,
+            { kind: "bad_request", retryable: false }
+          );
+        }
         if (reasoningApi === "budget") {
           const budget = reasoning.budgetTokens !== void 0 ? reasoning.budgetTokens : reasoning.effort !== void 0 ? EFFORT_BUDGET[reasoning.effort] ?? 0 : void 0;
           config.thinkingConfig = {
             ...budget !== void 0 ? { thinkingBudget: budget } : {},
             ...reasoning.includeThoughts === true ? { includeThoughts: true } : {}
           };
-          if (reasoning.effort !== void 0 && reasoning.budgetTokens !== void 0) {
-            warnings.push({
-              type: "reasoning-mapping",
-              quality: "approximate",
-              details: "budgetTokens takes precedence over effort for thinkingBudget"
-            });
-          }
         } else if (reasoningApi === "level") {
+          if (reasoning.budgetTokens !== void 0) {
+            throw new core.LlmError(
+              `reasoning.budgetTokens is not supported for model "${model}" (it uses thinkingLevel, not thinkingBudget); use reasoning.effort instead.`,
+              { kind: "bad_request", retryable: false }
+            );
+          }
           let thinkingLevel;
           if (reasoning.effort !== void 0) {
             switch (reasoning.effort) {
@@ -292,45 +226,23 @@ function geminiAdapter(opts) {
                 core.assertNever(reasoning.effort);
             }
           }
-          if (reasoning.budgetTokens !== void 0) {
-            warnings.push({
-              type: "reasoning-mapping",
-              quality: "approximate",
-              details: "budgetTokens is not supported for gemini-3.x models; mapping effort to thinkingLevel instead"
-            });
-          }
           config.thinkingConfig = {
             ...thinkingLevel !== void 0 ? { thinkingLevel } : {},
             ...reasoning.includeThoughts === true ? { includeThoughts: true } : {}
           };
         } else {
-          warnings.push({
-            type: "reasoning-mapping",
-            quality: "unsupported",
-            details: `thinkingConfig not mapped for model "${model}"; unknown generation`
-          });
+          throw new core.LlmError(
+            `Model "${model}" does not support reasoning/thinkingConfig.`,
+            { kind: "bad_request", retryable: false }
+          );
         }
       }
-      let outputSchemaRequested = false;
-      if (req.outputSchema !== void 0) {
-        outputSchemaRequested = true;
-        config.responseMimeType = "application/json";
-        if (req.outputSchema["~standard"].vendor === "zod") {
-          const geminiSchema = zodToGeminiSchema(req.outputSchema);
-          if (geminiSchema !== void 0) {
-            config.responseSchema = geminiSchema;
-          } else {
-            warnings.push({
-              type: "unsupported-setting",
-              setting: "output.schema",
-              details: "Could not convert Zod schema to Gemini responseSchema; proceeding with responseMimeType only. Engine will still validate."
-            });
-          }
-        } else {
-          warnings.push({
-            type: "other",
-            message: `Native Gemini responseSchema conversion is not available for vendor "${req.outputSchema["~standard"].vendor}"; proceeding with responseMimeType only. Engine will validate output client-side via Standard Schema.`
-          });
+      const structuredOutputRequested = req.outputJsonSchema !== void 0;
+      if (structuredOutputRequested) {
+        const nativeStructuredOutput = req.modelDescriptor?.capabilities?.nativeStructuredOutput !== false;
+        if (nativeStructuredOutput) {
+          config.responseMimeType = "application/json";
+          config.responseSchema = req.outputJsonSchema;
         }
       }
       const googleOpts = genConfig.providerOptions?.["google"];
@@ -338,27 +250,23 @@ function geminiAdapter(opts) {
         Object.assign(config, googleOpts);
       }
       if (req.modelDescriptor?.capabilities?.sampling === "fixed") {
-        const droppedSampling = [];
+        const offendingSampling = [];
         if ("temperature" in config) {
-          delete config.temperature;
-          droppedSampling.push("temperature");
+          offendingSampling.push("temperature");
         }
         if ("topP" in config) {
-          delete config.topP;
-          droppedSampling.push("topP");
+          offendingSampling.push("topP");
         }
         if ("topK" in config) {
-          delete config.topK;
-          droppedSampling.push("topK");
+          offendingSampling.push("topK");
         }
-        if (droppedSampling.length > 0) {
-          warnings.push({
-            type: "unsupported-setting",
-            setting: droppedSampling.join(", "),
-            details: `Sampling parameter(s) [${droppedSampling.join(
+        if (offendingSampling.length > 0) {
+          throw new core.LlmError(
+            `Sampling parameters [${offendingSampling.join(
               ", "
-            )}] from providerOptions.google were stripped: this model has fixed sampling (Gemini 3.x) and the API rejects these fields.`
-          });
+            )}] are not supported for model "${model}" (fixed sampling); they were supplied via providerOptions.google.`,
+            { kind: "bad_request", retryable: false }
+          );
         }
       }
       const configAsAny = config;
@@ -369,32 +277,41 @@ function geminiAdapter(opts) {
         }
         return false;
       });
-      if (groundingRequested && req.outputSchema !== void 0) {
+      if (groundingRequested && structuredOutputRequested) {
         throw new core.LlmError(
-          "Grounding (googleSearch) cannot be combined with structured output (output.schema) on Gemini; choose one.",
+          "Grounding (googleSearch) cannot be combined with structured output (output.jsonSchema) on Gemini; choose one.",
           { kind: "bad_request", retryable: false }
         );
       }
-      let _flexTimeoutHandle;
-      if (config.serviceTier === "flex" && genConfig.timeoutMs === void 0) {
-        const flexController = new AbortController();
-        const timeoutReason = new DOMException(
-          `Flex timeout: call exceeded ${FLEX_DEFAULT_TIMEOUT_MS}ms client-side ceiling (@google/genai #1277 belt-and-suspenders)`,
-          "TimeoutError"
-        );
-        _flexTimeoutHandle = setTimeout(() => {
-          flexController.abort(timeoutReason);
-        }, FLEX_DEFAULT_TIMEOUT_MS);
-        if (ctx.signal !== void 0) {
-          config.abortSignal = AbortSignal.any([flexController.signal, ctx.signal]);
-        } else {
-          config.abortSignal = flexController.signal;
+      let tierTimeoutHandle;
+      const clearTierTimeout = () => {
+        if (tierTimeoutHandle !== void 0) {
+          clearTimeout(tierTimeoutHandle);
+          tierTimeoutHandle = void 0;
         }
-      } else if (ctx.signal !== void 0) {
-        config.abortSignal = ctx.signal;
-      }
+      };
+      const applyTierTimeout = (tier) => {
+        clearTierTimeout();
+        delete config.abortSignal;
+        const defaultTimeoutMs = genConfig.timeoutMs === void 0 ? tier === "flex" ? FLEX_DEFAULT_TIMEOUT_MS : tier === "standard" ? STANDARD_DEFAULT_TIMEOUT_MS : void 0 : void 0;
+        if (defaultTimeoutMs !== void 0) {
+          const tierController = new AbortController();
+          const tierLabel = tier === "standard" ? "Standard" : "Flex";
+          const timeoutReason = new DOMException(
+            `${tierLabel} timeout: call exceeded ${defaultTimeoutMs}ms client-side ceiling (@google/genai #1277 belt-and-suspenders)`,
+            "TimeoutError"
+          );
+          tierTimeoutHandle = setTimeout(() => {
+            tierController.abort(timeoutReason);
+          }, defaultTimeoutMs);
+          config.abortSignal = ctx.signal !== void 0 ? AbortSignal.any([tierController.signal, ctx.signal]) : tierController.signal;
+        } else if (ctx.signal !== void 0) {
+          config.abortSignal = ctx.signal;
+        }
+      };
+      applyTierTimeout(config.serviceTier);
       const callerHttpOptions = config.httpOptions;
-      const computedTimeoutMs = genConfig.timeoutMs !== void 0 ? genConfig.timeoutMs + TRANSPORT_TIMEOUT_BUFFER_MS : genConfig.serviceTier === "flex" ? FLEX_DEFAULT_TIMEOUT_MS : void 0;
+      const computedTimeoutMs = genConfig.timeoutMs !== void 0 ? genConfig.timeoutMs + TRANSPORT_TIMEOUT_BUFFER_MS : config.serviceTier === "flex" ? FLEX_DEFAULT_TIMEOUT_MS : config.serviceTier === "standard" ? STANDARD_DEFAULT_TIMEOUT_MS : void 0;
       const mergedHttpOptions = {
         ...computedTimeoutMs !== void 0 ? { timeout: computedTimeoutMs } : {},
         ...callerHttpOptions
@@ -402,32 +319,71 @@ function geminiAdapter(opts) {
       if (Object.keys(mergedHttpOptions).length > 0) {
         config.httpOptions = mergedHttpOptions;
       }
-      const params = {
-        model,
-        contents,
-        config
-      };
       let response;
-      try {
+      let servedServiceTier = config.serviceTier;
+      const dispatch = async () => {
+        const dispatchConfig = {
+          ...config,
+          ...config.httpOptions !== void 0 ? { httpOptions: { ...config.httpOptions } } : {}
+        };
+        const params = {
+          model,
+          contents,
+          config: dispatchConfig
+        };
         const buildClient = opts?._clientFactory ?? buildGoogleClient;
         const client = opts?.client !== void 0 ? opts.client : await buildClient(ctx.auth);
         ctx.logger.debug(
-          { model, configKeys: Object.keys(config) },
+          {
+            model,
+            configKeys: Object.keys(dispatchConfig),
+            serviceTier: dispatchConfig.serviceTier
+          },
           "llm.adapter.dispatch"
         );
-        response = await client.models.generateContent(params);
+        return client.models.generateContent(params);
+      };
+      try {
+        response = await dispatch();
       } catch (rawErr) {
         const classified = core.classifyError(rawErr);
-        throw new core.LlmError(classified.message, {
+        const typed = new core.LlmError(classified.message, {
           kind: classified.kind,
           retryable: classified.retryable,
           ...classified.httpStatus !== void 0 ? { httpStatus: classified.httpStatus } : {},
           ...classified.retryAfterMs !== void 0 ? { retryAfterMs: classified.retryAfterMs } : {},
           provider: "google",
-          cause: classified.cause ?? rawErr
+          cause: classified.cause ?? rawErr,
+          ...servedServiceTier !== void 0 ? { servedServiceTier } : {}
         });
+        if (config.serviceTier === "flex" && genConfig.flexFallback !== false && isGeminiCapacityError(typed)) {
+          config.serviceTier = "standard";
+          servedServiceTier = "standard";
+          const fallbackTimeout = genConfig.timeoutMs !== void 0 ? genConfig.timeoutMs + TRANSPORT_TIMEOUT_BUFFER_MS : STANDARD_DEFAULT_TIMEOUT_MS;
+          config.httpOptions = {
+            timeout: fallbackTimeout,
+            ...callerHttpOptions
+          };
+          applyTierTimeout("standard");
+          try {
+            response = await dispatch();
+          } catch (fallbackRawErr) {
+            const fallbackClassified = core.classifyError(fallbackRawErr);
+            throw new core.LlmError(fallbackClassified.message, {
+              kind: fallbackClassified.kind,
+              retryable: fallbackClassified.retryable,
+              ...fallbackClassified.httpStatus !== void 0 ? { httpStatus: fallbackClassified.httpStatus } : {},
+              ...fallbackClassified.retryAfterMs !== void 0 ? { retryAfterMs: fallbackClassified.retryAfterMs } : {},
+              provider: "google",
+              cause: fallbackClassified.cause ?? fallbackRawErr,
+              servedServiceTier: "standard"
+            });
+          }
+        } else {
+          throw typed;
+        }
       } finally {
-        if (_flexTimeoutHandle !== void 0) clearTimeout(_flexTimeoutHandle);
+        clearTierTimeout();
       }
       const hasBlockReason = response.promptFeedback?.blockReason !== void 0;
       const hasCandidates = response.candidates !== void 0 && response.candidates.length > 0;
@@ -470,7 +426,7 @@ function geminiAdapter(opts) {
       const text = textParts.join("");
       const reasoningText = thoughtParts.length > 0 ? thoughtParts.join("") : void 0;
       let rawStructured;
-      if (outputSchemaRequested && text.length > 0) {
+      if (structuredOutputRequested && text.length > 0) {
         try {
           rawStructured = JSON.parse(text);
         } catch {
@@ -482,6 +438,7 @@ function geminiAdapter(opts) {
         model,
         usage,
         warnings,
+        ...servedServiceTier !== void 0 ? { servedServiceTier } : {},
         ...text.length > 0 ? { text } : {},
         ...reasoningText !== void 0 ? { reasoningText } : {},
         ...rawStructured !== void 0 ? { rawStructured } : {},
@@ -910,9 +867,10 @@ var GoogleCacheStore = class {
 exports.FLEX_DEFAULT_TIMEOUT_MS = FLEX_DEFAULT_TIMEOUT_MS;
 exports.GoogleCacheStore = GoogleCacheStore;
 exports.GoogleFileStore = GoogleFileStore;
+exports.STANDARD_DEFAULT_TIMEOUT_MS = STANDARD_DEFAULT_TIMEOUT_MS;
 exports.TRANSPORT_TIMEOUT_BUFFER_MS = TRANSPORT_TIMEOUT_BUFFER_MS;
 exports.buildGoogleClient = buildGoogleClient;
 exports.geminiAdapter = geminiAdapter;
-exports.zodToGeminiSchema = zodToGeminiSchema;
+exports.isGeminiCapacityError = isGeminiCapacityError;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map