@gullabs/google 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,10 +1,10 @@
-import { assertNever, LlmError, classifyError, redactSecrets } from '@gullabs/core';
-import { ZodOptional, ZodNullable, ZodDefault, ZodObject, ZodString, ZodNumber, ZodBoolean, ZodArray, ZodEnum, ZodLiteral } from 'zod';
+import { LlmError, EFFORT_BUDGET, assertNever, classifyError, redactSecrets } from '@gullabs/core';
 
 // 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');
@@ -18,130 +18,37 @@ async function buildGoogleClient(auth) {
     }
   };
 }
-function isOptionalField(schema) {
-  if (schema instanceof ZodOptional || schema instanceof ZodDefault) return true;
-  if (schema instanceof 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 ZodOptional) {
-    const unwrapped = schema.unwrap();
-    return convertSchema(unwrapped, nullable);
-  }
-  if (schema instanceof ZodNullable) {
-    const unwrapped = schema.unwrap();
-    return convertSchema(unwrapped, true);
-  }
-  if (schema instanceof ZodDefault) {
-    const innerType = schema._def.innerType;
-    return convertSchema(innerType, nullable);
-  }
-  if (schema instanceof 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 ZodString) {
-    return {
-      type: "string",
-      ...desc !== void 0 ? { description: desc } : {},
-      ...nullable ? { nullable: true } : {}
-    };
-  }
-  if (schema instanceof 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 ZodBoolean) {
-    return {
-      type: "boolean",
-      ...desc !== void 0 ? { description: desc } : {},
-      ...nullable ? { nullable: true } : {}
-    };
-  }
-  if (schema instanceof 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 ZodEnum) {
-    return {
-      type: "string",
-      enum: schema.options,
-      ...desc !== void 0 ? { description: desc } : {},
-      ...nullable ? { nullable: true } : {}
-    };
-  }
-  if (schema instanceof 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
-var EFFORT_BUDGET = {
-  none: 0,
-  low: 1024,
-  medium: 8192,
-  high: 24576
-};
 function mapFinishReason(raw) {
   if (raw === void 0) return void 0;
   switch (raw) {
@@ -253,24 +160,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 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 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;
+          const budget = reasoning.budgetTokens !== void 0 ? reasoning.budgetTokens : reasoning.effort !== void 0 ? EFFORT_BUDGET[reasoning.effort] : 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 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) {
@@ -290,73 +218,57 @@ function geminiAdapter(opts) {
                 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 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"];
       if (googleOpts !== void 0 && typeof googleOpts === "object" && googleOpts !== null) {
         Object.assign(config, googleOpts);
       }
+      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 (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 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;
@@ -367,32 +279,41 @@ function geminiAdapter(opts) {
         }
         return false;
       });
-      if (groundingRequested && req.outputSchema !== void 0) {
+      if (groundingRequested && structuredOutputRequested) {
         throw new 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
@@ -400,32 +321,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 = classifyError(rawErr);
-        throw new LlmError(classified.message, {
+        const typed = new 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 = classifyError(fallbackRawErr);
+            throw new 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;
@@ -468,7 +428,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 {
@@ -480,6 +440,7 @@ function geminiAdapter(opts) {
         model,
         usage,
         warnings,
+        ...servedServiceTier !== void 0 ? { servedServiceTier } : {},
         ...text.length > 0 ? { text } : {},
         ...reasoningText !== void 0 ? { reasoningText } : {},
         ...rawStructured !== void 0 ? { rawStructured } : {},
@@ -905,6 +866,6 @@ var GoogleCacheStore = class {
   }
 };
 
-export { FLEX_DEFAULT_TIMEOUT_MS, GoogleCacheStore, GoogleFileStore, TRANSPORT_TIMEOUT_BUFFER_MS, buildGoogleClient, geminiAdapter, zodToGeminiSchema };
+export { FLEX_DEFAULT_TIMEOUT_MS, GoogleCacheStore, GoogleFileStore, STANDARD_DEFAULT_TIMEOUT_MS, TRANSPORT_TIMEOUT_BUFFER_MS, buildGoogleClient, geminiAdapter, isGeminiCapacityError };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map