ak-gemini 2.4.1 → 2.5.0

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+## 2.5.0
+
+Fixes from a downstream consumer's adversarial review. This is a **minor** bump —
+it includes small but real behavior changes (see "Behavior changes" below).
+
+### Behavior changes (read before upgrading)
+- **`Message` structured output:** passing `responseSchema` without
+  `responseMimeType` now auto-defaults `responseMimeType: 'application/json'`
+  (the SDK requires it and does not add it). Previously such a call returned a
+  400 or unparseable prose. Explicit `responseMimeType` is still honored.
+- **`init()` no longer validates connectivity by default.** `Message`,
+  `Embedding`, and `ImageGenerator` previously called `models.list()`
+  unconditionally during `init()`. This is now gated behind `healthCheck: true`
+  (default `false`), matching `BaseGemini`. If you relied on `init()` as a
+  startup credentials gate, pass `healthCheck: true`. `models.list()` is a
+  different IAM surface than `generateContent` and added a per-instance
+  round-trip.
+
+### Added
+- **`usage.estimatedCost`** — every `send()`/`generate()` result and
+  `getLastUsage()` now include an estimated USD cost from `MODEL_PRICING`
+  (`null` when the model is unpriced). Thinking ("thoughts") tokens are billed at
+  the output rate and are now included in cost and exposed as
+  `usage.thoughtsTokens`.
+- **Concurrency-safe per-call usage.** `Message.send()` and
+  `ImageGenerator.generate()` return `result.usage` computed synchronously from
+  that call's own response. `getLastUsage()` still reflects the instance's last
+  call and is unsafe to read across concurrent sends on a shared instance — use
+  `result.usage`.
+- **Pricing helpers exported:** `MODEL_PRICING`, `MODEL_ALIASES`,
+  `resolvePricing()`, `computeCost()`. `resolvePricing` follows `-latest`
+  aliases and peels version-build suffixes (e.g. `gemini-2.5-flash-001` →
+  `gemini-2.5-flash`).
+- **`validateSchema()`** JSON-Schema validator exported (for cross-package
+  symmetry; Gemini enforces schemas natively).
+
+### Fixed
+- `estimateCost()` now uses `resolvePricing()` and returns `null` cost fields for
+  unknown models (was `0`), consistent with `usage.estimatedCost`.
+- `estimatedCost` no longer returns `null` for a priced model when the API echoes
+  a version-suffixed build id in `modelVersion`.
+
+### Dependencies
+- `@google/genai` `^2.10.0` → `^2.12.0` (no breaking changes to the used surface).

package/GUIDE.md

@@ -147,6 +147,8 @@ console.log(result.data);
 
 Key difference from `Chat`: `result.data` contains the parsed JSON object. `result.text` contains the raw string.
 
+> **Note:** `responseSchema` requires `responseMimeType: 'application/json'`. If you pass `responseSchema` without a `responseMimeType`, ak-gemini now auto-defaults it to `'application/json'` (logged at debug). Passing an explicit `responseMimeType` is still honored.
+
 ### When to Use Message
 
 - Classification, tagging, or labeling
@@ -1037,10 +1039,18 @@ const usage = instance.getLastUsage();
 //   attempts: 1,             // 1 = first try, 2+ = retries needed
 //   modelVersion: 'gemini-2.5-flash-001',  // actual model that responded
 //   requestedModel: 'gemini-2.5-flash',    // model you requested
-//   timestamp: 1710000000000
+//   timestamp: 1710000000000,
+//   thoughtsTokens: 0,       // thinking tokens, billed at output rate (in totalTokens + cost)
+//   estimatedCost: 0.00123   // USD from MODEL_PRICING; null if model unpriced
 // }
 ```
 
+> **Thinking tokens:** for thinking-enabled models, `thoughtsTokens` are billed at the output rate and are included in both `totalTokens` and `estimatedCost`. `responseTokens` is candidate (visible) output only.
+
+> **Concurrency:** `getLastUsage()` reflects the **instance's last completed call** and mutates on every `send()` — it is **not** safe to read across concurrent sends on a shared instance. The **stateless** classes (`Message`, `ImageGenerator`) return a per-call **`result.usage`** computed synchronously from that call's own response, which *is* concurrency-safe — use it when sharing one instance across concurrent calls. The stateful classes (`Chat`, `Transformer`, `RagAgent`, `ToolAgent`, `CodeAgent`) maintain history/rounds and are not designed to be shared across concurrent calls; their `result.usage` is derived from instance state.
+
+> **`estimatedCost` / `MODEL_ALIASES` caveat:** `estimatedCost` resolves `-latest` aliases and version-suffixed builds via `MODEL_PRICING`/`MODEL_ALIASES`. Alias→price mappings are pinned as of 2026-07 (e.g. `gemini-flash-latest` → `gemini-3.5-flash`); when Google rotates what a `-latest` alias points to, `estimatedCost` for that alias may be wrong until the table is updated. Pin explicit model ids for billing-grade accuracy.
+
 ### Cost Estimation
 
 Estimate cost *before* sending:

package/README.md

@@ -86,8 +86,15 @@ const msg = new Message({
 
 const result = await msg.send('Alice works at Acme in New York.');
 // result.data → { entities: ['Alice', 'Acme', 'New York'] }
+// result.usage → { promptTokens, responseTokens, thoughtsTokens, totalTokens, estimatedCost, ... }
 ```
 
+> **`responseSchema` requires `responseMimeType: 'application/json'`.** As of 2.5.0, passing `responseSchema` without a `responseMimeType` auto-defaults it to `'application/json'` — you can omit the line above. An explicit `responseMimeType` is still honored.
+
+> **Connectivity check is opt-in.** `Message`, `Embedding`, and `ImageGenerator` do **not** ping the API during `init()` unless you pass `healthCheck: true` (default `false`, as of 2.5.0). The first `send()`/`embed()`/`generate()` surfaces auth/connectivity errors on its own.
+
+> **Per-call usage under concurrency.** Read `result.usage` (computed from that call's own response) rather than `getLastUsage()` when sharing a `Message`/`ImageGenerator` instance across concurrent `send()`s — `getLastUsage()` reflects only the instance's last completed call.
+
 ### ToolAgent — Agent with User-Provided Tools
 
 Provide tool declarations and an executor function. The agent manages the tool-use loop automatically.

package/base.js

@@ -71,7 +71,65 @@ const MODEL_PRICING = {
 	'gemini-embedding-001': { input: 0.15, output: 0 }
 };
 
-export { DEFAULT_SAFETY_SETTINGS, DEFAULT_THINKING_CONFIG, THINKING_SUPPORTED_MODELS, MODEL_PRICING, DEFAULT_MAX_OUTPUT_TOKENS };
+/**
+ * Alias → canonical model id map for pricing resolution.
+ * Google publishes floating `-latest` aliases that resolve server-side to a
+ * concrete model; they never appear in MODEL_PRICING directly. Map them to the
+ * canonical id whose rate they currently bill at so estimatedCost can resolve.
+ * Revisit when Google rotates what an alias points to.
+ */
+const MODEL_ALIASES = {
+	'gemini-flash-latest': 'gemini-3.5-flash',
+	'gemini-pro-latest': 'gemini-3.1-pro-preview',
+	'gemini-flash-lite-latest': 'gemini-3.1-flash-lite'
+};
+
+/**
+ * Resolves pricing for a model id, following `-latest` aliases.
+ * @param {string|null|undefined} modelId
+ * @returns {{ input: number, output: number }|null} Pricing, or null if unknown.
+ */
+function resolvePricing(modelId) {
+	if (!modelId) return null;
+	const tryKey = (id) => {
+		if (MODEL_PRICING[id]) return MODEL_PRICING[id];
+		const alias = MODEL_ALIASES[id];
+		if (alias && MODEL_PRICING[alias]) return MODEL_PRICING[alias];
+		return null;
+	};
+	let hit = tryKey(modelId);
+	if (hit) return hit;
+	// The API echoes a pinned build in modelVersion (e.g. 'gemini-2.5-flash-001',
+	// 'gemini-3-flash-preview-09-2025') even when you request the bare id. Peel
+	// trailing '-<digits>' groups and retry until a priced id matches.
+	let stripped = modelId;
+	while (true) {
+		const next = stripped.replace(/-\d{2,}$/, '');
+		if (next === stripped) break;
+		stripped = next;
+		hit = tryKey(stripped);
+		if (hit) return hit;
+	}
+	return null;
+}
+
+/**
+ * Computes estimated USD cost from token counts using MODEL_PRICING.
+ * Thinking ("thoughts") tokens are billed at the output rate.
+ * @param {string|null|undefined} modelId
+ * @param {number} promptTokens
+ * @param {number} responseTokens
+ * @param {number} [thoughtsTokens=0] - Thinking tokens (billed at output rate)
+ * @returns {number|null} Cost in USD, or null when pricing is unknown.
+ */
+function computeCost(modelId, promptTokens, responseTokens, thoughtsTokens = 0) {
+	const pricing = resolvePricing(modelId);
+	if (!pricing) return null;
+	return (promptTokens / 1_000_000) * pricing.input
+		+ ((responseTokens + thoughtsTokens) / 1_000_000) * pricing.output;
+}
+
+export { DEFAULT_SAFETY_SETTINGS, DEFAULT_THINKING_CONFIG, THINKING_SUPPORTED_MODELS, MODEL_PRICING, MODEL_ALIASES, DEFAULT_MAX_OUTPUT_TOKENS, resolvePricing, computeCost };
 
 // ── BaseGemini Class ─────────────────────────────────────────────────────────
 
@@ -237,18 +295,28 @@ class BaseGemini {
 		const chatOptions = this._getChatCreateOptions();
 		this.chatSession = this.genAIClient.chats.create(chatOptions);
 
-		if (this.healthCheck) {
-			try {
-				await this._withRetry(() => this.genAIClient.models.list());
-				log.debug(`${this.constructor.name}: API connection successful.`);
-			} catch (e) {
-				throw new Error(`${this.constructor.name} initialization failed: ${e.message}`);
-			}
-		}
+		await this._healthCheckPing();
 
 		log.debug(`${this.constructor.name}: Chat session initialized.`);
 	}
 
+	/**
+	 * Opt-in connectivity check via `models.list()` — runs only when
+	 * `healthCheck: true`. Fails fast (no exponential backoff): a readiness probe
+	 * should surface a bad config immediately, not after ~30s of 429 retries.
+	 * @returns {Promise<void>}
+	 * @protected
+	 */
+	async _healthCheckPing() {
+		if (!this.healthCheck) return;
+		try {
+			await this.genAIClient.models.list();
+			log.debug(`${this.constructor.name}: API connection successful.`);
+		} catch (e) {
+			throw new Error(`${this.constructor.name} initialization failed: ${e.message}`);
+		}
+	}
+
 	/**
 	 * Builds the options object for `genAIClient.chats.create()`.
 	 * Override in subclasses to add tools, grounding, etc.
@@ -416,12 +484,17 @@ class BaseGemini {
 	 */
 	_captureMetadata(response) {
 		const modelStatus = response?.modelStatus || null;
+		const promptTokens = response.usageMetadata?.promptTokenCount || 0;
+		const responseTokens = response.usageMetadata?.candidatesTokenCount || 0;
+		const thoughtsTokens = response.usageMetadata?.thoughtsTokenCount || 0;
 		this.lastResponseMetadata = {
 			modelVersion: response.modelVersion || null,
 			requestedModel: this.modelName,
-			promptTokens: response.usageMetadata?.promptTokenCount || 0,
-			responseTokens: response.usageMetadata?.candidatesTokenCount || 0,
-			totalTokens: response.usageMetadata?.totalTokenCount || 0,
+			promptTokens,
+			responseTokens,
+			thoughtsTokens,
+			// totalTokenCount includes thoughts; fall back to summing the parts.
+			totalTokens: response.usageMetadata?.totalTokenCount || (promptTokens + responseTokens + thoughtsTokens),
 			timestamp: Date.now(),
 			groundingMetadata: response.candidates?.[0]?.groundingMetadata || null,
 			modelStatus
@@ -441,19 +514,73 @@ class BaseGemini {
 		if (!this.lastResponseMetadata) return null;
 
 		const meta = this.lastResponseMetadata;
-		const cumulative = this._cumulativeUsage || { promptTokens: 0, responseTokens: 0, totalTokens: 0, attempts: 1 };
+		const cumulative = this._cumulativeUsage || { promptTokens: 0, responseTokens: 0, totalTokens: 0, thoughtsTokens: 0, attempts: 1 };
 		const useCumulative = cumulative.attempts > 0;
 
+		const promptTokens = useCumulative ? cumulative.promptTokens : meta.promptTokens;
+		const responseTokens = useCumulative ? cumulative.responseTokens : meta.responseTokens;
+		const thoughtsTokens = useCumulative ? (cumulative.thoughtsTokens || 0) : (meta.thoughtsTokens || 0);
+		const totalTokens = useCumulative ? cumulative.totalTokens : meta.totalTokens;
+
 		return {
-			promptTokens: useCumulative ? cumulative.promptTokens : meta.promptTokens,
-			responseTokens: useCumulative ? cumulative.responseTokens : meta.responseTokens,
-			totalTokens: useCumulative ? cumulative.totalTokens : meta.totalTokens,
+			promptTokens,
+			responseTokens,
+			thoughtsTokens,
+			totalTokens,
 			attempts: useCumulative ? cumulative.attempts : 1,
 			modelVersion: meta.modelVersion,
 			requestedModel: meta.requestedModel,
 			timestamp: meta.timestamp,
 			groundingMetadata: meta.groundingMetadata || null,
-			modelStatus: meta.modelStatus || null
+			modelStatus: meta.modelStatus || null,
+			estimatedCost: this._estimatedCost(meta.modelVersion, promptTokens, responseTokens, thoughtsTokens)
+		};
+	}
+
+	/**
+	 * Estimated USD cost, preferring the model id the API echoed (`modelVersion`)
+	 * and falling back to the requested model when that build isn't priced.
+	 * @param {string|null|undefined} modelVersion
+	 * @param {number} promptTokens
+	 * @param {number} responseTokens
+	 * @param {number} [thoughtsTokens=0]
+	 * @returns {number|null}
+	 * @protected
+	 */
+	_estimatedCost(modelVersion, promptTokens, responseTokens, thoughtsTokens = 0) {
+		return computeCost(modelVersion, promptTokens, responseTokens, thoughtsTokens)
+			?? computeCost(this.modelName, promptTokens, responseTokens, thoughtsTokens);
+	}
+
+	/**
+	 * Builds a usage object directly from a single API response, WITHOUT reading
+	 * mutable instance state (`lastResponseMetadata`/`_cumulativeUsage`). Safe to
+	 * call under concurrent send() calls on a shared instance — unlike
+	 * getLastUsage(), which reflects whichever call most recently mutated the
+	 * instance and can cross-talk between concurrent sends.
+	 * @param {Object} response - A single generateContent() response
+	 * @param {number} [attempts=1] - Attempts this call consumed
+	 * @returns {UsageData}
+	 * @protected
+	 */
+	_usageFromResponse(response, attempts = 1) {
+		const promptTokens = response?.usageMetadata?.promptTokenCount || 0;
+		const responseTokens = response?.usageMetadata?.candidatesTokenCount || 0;
+		const thoughtsTokens = response?.usageMetadata?.thoughtsTokenCount || 0;
+		const totalTokens = response?.usageMetadata?.totalTokenCount || (promptTokens + responseTokens + thoughtsTokens);
+		const modelVersion = response?.modelVersion || null;
+		return {
+			promptTokens,
+			responseTokens,
+			thoughtsTokens,
+			totalTokens,
+			attempts,
+			modelVersion,
+			requestedModel: this.modelName,
+			timestamp: Date.now(),
+			groundingMetadata: response?.candidates?.[0]?.groundingMetadata || null,
+			modelStatus: response?.modelStatus || null,
+			estimatedCost: this._estimatedCost(modelVersion, promptTokens, responseTokens, thoughtsTokens)
 		};
 	}
 
@@ -500,14 +627,16 @@ class BaseGemini {
 	 */
 	async estimateCost(nextPayload) {
 		const tokenInfo = await this.estimate(nextPayload);
-		const pricing = MODEL_PRICING[this.modelName] || { input: 0, output: 0 };
+		const pricing = resolvePricing(this.modelName);
 
 		return {
 			inputTokens: tokenInfo.inputTokens,
 			model: this.modelName,
 			pricing: pricing,
-			estimatedInputCost: (tokenInfo.inputTokens / 1_000_000) * pricing.input,
-			note: 'Cost is for input tokens only; output cost depends on response length'
+			estimatedInputCost: pricing ? (tokenInfo.inputTokens / 1_000_000) * pricing.input : null,
+			note: pricing
+				? 'Cost is for input tokens only; output cost depends on response length'
+				: `No pricing known for model "${this.modelName}"; estimatedInputCost is null`
 		};
 	}
 

package/embedding.js

@@ -54,12 +54,10 @@ export default class Embedding extends BaseGemini {
 
 		log.debug(`Initializing ${this.constructor.name} with model: ${this.modelName}...`);
 
-		try {
-			await this.genAIClient.models.list();
-			log.debug(`${this.constructor.name}: API connection successful.`);
-		} catch (e) {
-			throw new Error(`${this.constructor.name} initialization failed: ${e.message}`);
-		}
+		// Connectivity check is opt-in (healthCheck: true) — avoids an extra
+		// round-trip and the models.list() IAM surface. First embed() is a fine
+		// error signal on its own.
+		await this._healthCheckPing();
 
 		this._initialized = true;
 		log.debug(`${this.constructor.name}: Initialized (stateless mode).`);

package/image-generator.js

@@ -52,12 +52,10 @@ export default class ImageGenerator extends BaseGemini {
 
 		log.debug(`Initializing ${this.constructor.name} with model: ${this.modelName}...`);
 
-		try {
-			await this.genAIClient.models.list();
-			log.debug(`${this.constructor.name}: API connection successful.`);
-		} catch (e) {
-			throw new Error(`${this.constructor.name} initialization failed: ${e.message}`);
-		}
+		// Connectivity check is opt-in (healthCheck: true) — avoids an extra
+		// round-trip and the models.list() IAM surface. First generate() is a fine
+		// error signal on its own.
+		await this._healthCheckPing();
 
 		this._initialized = true;
 	}
@@ -108,10 +106,14 @@ export default class ImageGenerator extends BaseGemini {
 			config: this._buildConfig(opts)
 		}));
 
+		// Per-call usage computed synchronously from THIS response (concurrency-safe).
+		const usage = this._usageFromResponse(result);
+
 		this._captureMetadata(result);
 		this._cumulativeUsage = {
 			promptTokens: this.lastResponseMetadata.promptTokens,
 			responseTokens: this.lastResponseMetadata.responseTokens,
+			thoughtsTokens: this.lastResponseMetadata.thoughtsTokens,
 			totalTokens: this.lastResponseMetadata.totalTokens,
 			attempts: 1
 		};
@@ -134,7 +136,7 @@ export default class ImageGenerator extends BaseGemini {
 			log.warn('ImageGenerator: no images returned. Check prompt or safety filters.');
 		}
 
-		return { images, text: text || null, usage: this.getLastUsage() };
+		return { images, text: text || null, usage };
 	}
 
 	/**

package/index.cjs

@@ -36,15 +36,20 @@ __export(index_exports, {
   HarmBlockThreshold: () => import_genai2.HarmBlockThreshold,
   HarmCategory: () => import_genai2.HarmCategory,
   ImageGenerator: () => ImageGenerator,
+  MODEL_ALIASES: () => MODEL_ALIASES,
+  MODEL_PRICING: () => MODEL_PRICING,
   Message: () => message_default,
   RagAgent: () => rag_agent_default,
   ThinkingLevel: () => import_genai2.ThinkingLevel,
   ToolAgent: () => tool_agent_default,
   Transformer: () => transformer_default,
   attemptJSONRecovery: () => attemptJSONRecovery,
+  computeCost: () => computeCost,
   default: () => index_default,
   extractJSON: () => extractJSON,
-  log: () => logger_default
+  log: () => logger_default,
+  resolvePricing: () => resolvePricing,
+  validateSchema: () => validateSchema
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -255,6 +260,79 @@ function findCompleteJSONStructures(text) {
   }
   return results;
 }
+function validateSchema(data, schema, path2 = "$") {
+  const errors = [];
+  if (!schema || typeof schema !== "object") return errors;
+  if (data === null && schema.nullable === true) return errors;
+  if (Array.isArray(schema.enum)) {
+    const target = JSON.stringify(data);
+    const ok = schema.enum.some((v) => v === data || JSON.stringify(v) === target);
+    if (!ok) errors.push(`${path2}: value ${JSON.stringify(data)} is not one of allowed enum values ${JSON.stringify(schema.enum)}`);
+  }
+  if (schema.type !== void 0) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (schema.nullable === true) types.push("null");
+    if (!types.some((t) => matchesType(data, t))) {
+      errors.push(`${path2}: expected type ${types.join("|")} but got ${describeType(data)}`);
+      return errors;
+    }
+  }
+  const isObject = data !== null && typeof data === "object" && !Array.isArray(data);
+  if (isObject && (schema.properties || schema.required || schema.additionalProperties === false)) {
+    const props = schema.properties || {};
+    if (Array.isArray(schema.required)) {
+      for (const key of schema.required) {
+        if (!Object.hasOwn(data, key)) errors.push(`${path2}: missing required property "${key}"`);
+      }
+    }
+    if (schema.additionalProperties === false) {
+      for (const key of Object.keys(data)) {
+        if (!Object.hasOwn(props, key)) errors.push(`${path2}: unexpected property "${key}" (additionalProperties is false)`);
+      }
+    }
+    for (const [key, subSchema] of Object.entries(props)) {
+      if (Object.hasOwn(data, key)) {
+        errors.push(...validateSchema(
+          data[key],
+          /** @type {any} */
+          subSchema,
+          `${path2}.${key}`
+        ));
+      }
+    }
+  }
+  if (Array.isArray(data) && schema.items && typeof schema.items === "object" && !Array.isArray(schema.items)) {
+    data.forEach((item, i) => {
+      errors.push(...validateSchema(item, schema.items, `${path2}[${i}]`));
+    });
+  }
+  return errors;
+}
+function matchesType(value, type) {
+  switch (type) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number" && !Number.isNaN(value);
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "object":
+      return value !== null && typeof value === "object" && !Array.isArray(value);
+    case "array":
+      return Array.isArray(value);
+    case "null":
+      return value === null;
+    default:
+      return true;
+  }
+}
+function describeType(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
 function extractJSON(text) {
   if (!text || typeof text !== "string") {
     throw new Error("No text provided for JSON extraction");
@@ -359,6 +437,36 @@ var MODEL_PRICING = {
   // Embeddings
   "gemini-embedding-001": { input: 0.15, output: 0 }
 };
+var MODEL_ALIASES = {
+  "gemini-flash-latest": "gemini-3.5-flash",
+  "gemini-pro-latest": "gemini-3.1-pro-preview",
+  "gemini-flash-lite-latest": "gemini-3.1-flash-lite"
+};
+function resolvePricing(modelId) {
+  if (!modelId) return null;
+  const tryKey = (id) => {
+    if (MODEL_PRICING[id]) return MODEL_PRICING[id];
+    const alias = MODEL_ALIASES[id];
+    if (alias && MODEL_PRICING[alias]) return MODEL_PRICING[alias];
+    return null;
+  };
+  let hit = tryKey(modelId);
+  if (hit) return hit;
+  let stripped = modelId;
+  while (true) {
+    const next = stripped.replace(/-\d{2,}$/, "");
+    if (next === stripped) break;
+    stripped = next;
+    hit = tryKey(stripped);
+    if (hit) return hit;
+  }
+  return null;
+}
+function computeCost(modelId, promptTokens, responseTokens, thoughtsTokens = 0) {
+  const pricing = resolvePricing(modelId);
+  if (!pricing) return null;
+  return promptTokens / 1e6 * pricing.input + (responseTokens + thoughtsTokens) / 1e6 * pricing.output;
+}
 var BaseGemini = class {
   /**
    * @param {BaseGeminiOptions} [options={}]
@@ -453,16 +561,25 @@ var BaseGemini = class {
     logger_default.debug(`Initializing ${this.constructor.name} chat session with model: ${this.modelName}...`);
     const chatOptions = this._getChatCreateOptions();
     this.chatSession = this.genAIClient.chats.create(chatOptions);
-    if (this.healthCheck) {
-      try {
-        await this._withRetry(() => this.genAIClient.models.list());
-        logger_default.debug(`${this.constructor.name}: API connection successful.`);
-      } catch (e) {
-        throw new Error(`${this.constructor.name} initialization failed: ${e.message}`);
-      }
-    }
+    await this._healthCheckPing();
     logger_default.debug(`${this.constructor.name}: Chat session initialized.`);
   }
+  /**
+   * Opt-in connectivity check via `models.list()` — runs only when
+   * `healthCheck: true`. Fails fast (no exponential backoff): a readiness probe
+   * should surface a bad config immediately, not after ~30s of 429 retries.
+   * @returns {Promise<void>}
+   * @protected
+   */
+  async _healthCheckPing() {
+    if (!this.healthCheck) return;
+    try {
+      await this.genAIClient.models.list();
+      logger_default.debug(`${this.constructor.name}: API connection successful.`);
+    } catch (e) {
+      throw new Error(`${this.constructor.name} initialization failed: ${e.message}`);
+    }
+  }
   /**
    * Builds the options object for `genAIClient.chats.create()`.
    * Override in subclasses to add tools, grounding, etc.
@@ -609,12 +726,17 @@ ${contextText}
    */
   _captureMetadata(response) {
     const modelStatus = response?.modelStatus || null;
+    const promptTokens = response.usageMetadata?.promptTokenCount || 0;
+    const responseTokens = response.usageMetadata?.candidatesTokenCount || 0;
+    const thoughtsTokens = response.usageMetadata?.thoughtsTokenCount || 0;
     this.lastResponseMetadata = {
       modelVersion: response.modelVersion || null,
       requestedModel: this.modelName,
-      promptTokens: response.usageMetadata?.promptTokenCount || 0,
-      responseTokens: response.usageMetadata?.candidatesTokenCount || 0,
-      totalTokens: response.usageMetadata?.totalTokenCount || 0,
+      promptTokens,
+      responseTokens,
+      thoughtsTokens,
+      // totalTokenCount includes thoughts; fall back to summing the parts.
+      totalTokens: response.usageMetadata?.totalTokenCount || promptTokens + responseTokens + thoughtsTokens,
       timestamp: Date.now(),
       groundingMetadata: response.candidates?.[0]?.groundingMetadata || null,
       modelStatus
@@ -632,18 +754,68 @@ ${contextText}
   getLastUsage() {
     if (!this.lastResponseMetadata) return null;
     const meta = this.lastResponseMetadata;
-    const cumulative = this._cumulativeUsage || { promptTokens: 0, responseTokens: 0, totalTokens: 0, attempts: 1 };
+    const cumulative = this._cumulativeUsage || { promptTokens: 0, responseTokens: 0, totalTokens: 0, thoughtsTokens: 0, attempts: 1 };
     const useCumulative = cumulative.attempts > 0;
+    const promptTokens = useCumulative ? cumulative.promptTokens : meta.promptTokens;
+    const responseTokens = useCumulative ? cumulative.responseTokens : meta.responseTokens;
+    const thoughtsTokens = useCumulative ? cumulative.thoughtsTokens || 0 : meta.thoughtsTokens || 0;
+    const totalTokens = useCumulative ? cumulative.totalTokens : meta.totalTokens;
     return {
-      promptTokens: useCumulative ? cumulative.promptTokens : meta.promptTokens,
-      responseTokens: useCumulative ? cumulative.responseTokens : meta.responseTokens,
-      totalTokens: useCumulative ? cumulative.totalTokens : meta.totalTokens,
+      promptTokens,
+      responseTokens,
+      thoughtsTokens,
+      totalTokens,
       attempts: useCumulative ? cumulative.attempts : 1,
       modelVersion: meta.modelVersion,
       requestedModel: meta.requestedModel,
       timestamp: meta.timestamp,
       groundingMetadata: meta.groundingMetadata || null,
-      modelStatus: meta.modelStatus || null
+      modelStatus: meta.modelStatus || null,
+      estimatedCost: this._estimatedCost(meta.modelVersion, promptTokens, responseTokens, thoughtsTokens)
+    };
+  }
+  /**
+   * Estimated USD cost, preferring the model id the API echoed (`modelVersion`)
+   * and falling back to the requested model when that build isn't priced.
+   * @param {string|null|undefined} modelVersion
+   * @param {number} promptTokens
+   * @param {number} responseTokens
+   * @param {number} [thoughtsTokens=0]
+   * @returns {number|null}
+   * @protected
+   */
+  _estimatedCost(modelVersion, promptTokens, responseTokens, thoughtsTokens = 0) {
+    return computeCost(modelVersion, promptTokens, responseTokens, thoughtsTokens) ?? computeCost(this.modelName, promptTokens, responseTokens, thoughtsTokens);
+  }
+  /**
+   * Builds a usage object directly from a single API response, WITHOUT reading
+   * mutable instance state (`lastResponseMetadata`/`_cumulativeUsage`). Safe to
+   * call under concurrent send() calls on a shared instance — unlike
+   * getLastUsage(), which reflects whichever call most recently mutated the
+   * instance and can cross-talk between concurrent sends.
+   * @param {Object} response - A single generateContent() response
+   * @param {number} [attempts=1] - Attempts this call consumed
+   * @returns {UsageData}
+   * @protected
+   */
+  _usageFromResponse(response, attempts = 1) {
+    const promptTokens = response?.usageMetadata?.promptTokenCount || 0;
+    const responseTokens = response?.usageMetadata?.candidatesTokenCount || 0;
+    const thoughtsTokens = response?.usageMetadata?.thoughtsTokenCount || 0;
+    const totalTokens = response?.usageMetadata?.totalTokenCount || promptTokens + responseTokens + thoughtsTokens;
+    const modelVersion = response?.modelVersion || null;
+    return {
+      promptTokens,
+      responseTokens,
+      thoughtsTokens,
+      totalTokens,
+      attempts,
+      modelVersion,
+      requestedModel: this.modelName,
+      timestamp: Date.now(),
+      groundingMetadata: response?.candidates?.[0]?.groundingMetadata || null,
+      modelStatus: response?.modelStatus || null,
+      estimatedCost: this._estimatedCost(modelVersion, promptTokens, responseTokens, thoughtsTokens)
     };
   }
   // ── Token Estimation ─────────────────────────────────────────────────────
@@ -679,13 +851,13 @@ ${contextText}
    */
   async estimateCost(nextPayload) {
     const tokenInfo = await this.estimate(nextPayload);
-    const pricing = MODEL_PRICING[this.modelName] || { input: 0, output: 0 };
+    const pricing = resolvePricing(this.modelName);
     return {
       inputTokens: tokenInfo.inputTokens,
       model: this.modelName,
       pricing,
-      estimatedInputCost: tokenInfo.inputTokens / 1e6 * pricing.input,
-      note: "Cost is for input tokens only; output cost depends on response length"
+      estimatedInputCost: pricing ? tokenInfo.inputTokens / 1e6 * pricing.input : null,
+      note: pricing ? "Cost is for input tokens only; output cost depends on response length" : `No pricing known for model "${this.modelName}"; estimatedInputCost is null`
     };
   }
   // ── Context Caching ─────────────────────────────────────────────────────
@@ -1310,6 +1482,9 @@ var Message = class extends base_default {
     }
     if (options.responseMimeType) {
       this.chatConfig.responseMimeType = options.responseMimeType;
+    } else if (options.responseSchema) {
+      this.chatConfig.responseMimeType = "application/json";
+      logger_default.debug("responseSchema set without responseMimeType \u2014 defaulting responseMimeType to 'application/json'.");
     }
     this._isStructured = !!(options.responseSchema || options.responseMimeType === "application/json");
     logger_default.debug(`Message created (structured=${this._isStructured})`);
@@ -1323,12 +1498,7 @@ var Message = class extends base_default {
   async init(force = false) {
     if (this._initialized && !force) return;
     logger_default.debug(`Initializing ${this.constructor.name} with model: ${this.modelName}...`);
-    try {
-      await this.genAIClient.models.list();
-      logger_default.debug(`${this.constructor.name}: API connection successful.`);
-    } catch (e) {
-      throw new Error(`${this.constructor.name} initialization failed: ${e.message}`);
-    }
+    await this._healthCheckPing();
     this._initialized = true;
     logger_default.debug(`${this.constructor.name}: Initialized (stateless mode).`);
   }
@@ -1354,10 +1524,12 @@ var Message = class extends base_default {
         ...this.vertexai && Object.keys(mergedLabels).length > 0 && { labels: mergedLabels }
       }
     }));
+    const usage = this._usageFromResponse(result);
     this._captureMetadata(result);
     this._cumulativeUsage = {
       promptTokens: this.lastResponseMetadata.promptTokens,
       responseTokens: this.lastResponseMetadata.responseTokens,
+      thoughtsTokens: this.lastResponseMetadata.thoughtsTokens,
       totalTokens: this.lastResponseMetadata.totalTokens,
       attempts: 1
     };
@@ -1367,7 +1539,7 @@ var Message = class extends base_default {
     const text = result.text || "";
     const response = {
       text,
-      usage: this.getLastUsage()
+      usage
     };
     if (this._isStructured) {
       try {
@@ -2981,12 +3153,7 @@ var Embedding = class extends base_default {
   async init(force = false) {
     if (this._initialized && !force) return;
     logger_default.debug(`Initializing ${this.constructor.name} with model: ${this.modelName}...`);
-    try {
-      await this.genAIClient.models.list();
-      logger_default.debug(`${this.constructor.name}: API connection successful.`);
-    } catch (e) {
-      throw new Error(`${this.constructor.name} initialization failed: ${e.message}`);
-    }
+    await this._healthCheckPing();
     this._initialized = true;
     logger_default.debug(`${this.constructor.name}: Initialized (stateless mode).`);
   }
@@ -3118,12 +3285,7 @@ var ImageGenerator = class extends base_default {
   async init(force = false) {
     if (this._initialized && !force) return;
     logger_default.debug(`Initializing ${this.constructor.name} with model: ${this.modelName}...`);
-    try {
-      await this.genAIClient.models.list();
-      logger_default.debug(`${this.constructor.name}: API connection successful.`);
-    } catch (e) {
-      throw new Error(`${this.constructor.name} initialization failed: ${e.message}`);
-    }
+    await this._healthCheckPing();
     this._initialized = true;
   }
   /**
@@ -3165,10 +3327,12 @@ var ImageGenerator = class extends base_default {
       contents: [{ role: "user", parts }],
       config: this._buildConfig(opts)
     }));
+    const usage = this._usageFromResponse(result);
     this._captureMetadata(result);
     this._cumulativeUsage = {
       promptTokens: this.lastResponseMetadata.promptTokens,
       responseTokens: this.lastResponseMetadata.responseTokens,
+      thoughtsTokens: this.lastResponseMetadata.thoughtsTokens,
       totalTokens: this.lastResponseMetadata.totalTokens,
       attempts: 1
     };
@@ -3188,7 +3352,7 @@ var ImageGenerator = class extends base_default {
     if (images.length === 0) {
       logger_default.warn("ImageGenerator: no images returned. Check prompt or safety filters.");
     }
-    return { images, text: text || null, usage: this.getLastUsage() };
+    return { images, text: text || null, usage };
   }
   /**
    * Convenience: write one or all images to disk.
@@ -3248,12 +3412,17 @@ var index_default = { Transformer: transformer_default, Chat: chat_default, Mess
   HarmBlockThreshold,
   HarmCategory,
   ImageGenerator,
+  MODEL_ALIASES,
+  MODEL_PRICING,
   Message,
   RagAgent,
   ThinkingLevel,
   ToolAgent,
   Transformer,
   attemptJSONRecovery,
+  computeCost,
   extractJSON,
-  log
+  log,
+  resolvePricing,
+  validateSchema
 });

package/index.js

@@ -29,9 +29,10 @@ export { default as RagAgent } from './rag-agent.js';
 export { default as Embedding } from './embedding.js';
 export { default as ImageGenerator } from './image-generator.js';
 export { default as BaseGemini } from './base.js';
+export { MODEL_PRICING, MODEL_ALIASES, resolvePricing, computeCost } from './base.js';
 export { default as log } from './logger.js';
 export { ThinkingLevel, HarmCategory, HarmBlockThreshold } from '@google/genai';
-export { extractJSON, attemptJSONRecovery } from './json-helpers.js';
+export { extractJSON, attemptJSONRecovery, validateSchema } from './json-helpers.js';
 
 // ── Default Export (namespace object) ──
 

package/json-helpers.js

@@ -267,6 +267,111 @@ function findCompleteJSONStructures(text) {
 	return results;
 }
 
+/**
+ * Validates a parsed value against a (subset of) JSON Schema. Dependency-light —
+ * intended to guard fallback structured-output paths where the model isn't forced
+ * to emit schema-valid JSON.
+ *
+ * Supported keywords: `type` (string or array of strings; 'integer' checks for
+ * whole numbers), `required`, `properties`, `additionalProperties: false`,
+ * `items` (single schema), `enum`. Unknown keywords are ignored (lenient).
+ *
+ * @param {*} data - The parsed value to validate
+ * @param {Object} schema - JSON Schema object
+ * @param {string} [path='$'] - Internal: JSON path prefix for error messages
+ * @returns {string[]} Array of human-readable error strings; empty means valid.
+ */
+export function validateSchema(data, schema, path = '$') {
+	// NOTE: ak-gemini enforces structured output natively (responseSchema), so this
+	// validator has no runtime call site here — it exists for cross-package API
+	// symmetry with ak-claude (whose Vertex fallback path relies on it). Keep this
+	// implementation byte-identical to ak-claude/json-helpers.js; apply fixes to both.
+	const errors = [];
+	if (!schema || typeof schema !== 'object') return errors;
+
+	// ── nullable (OpenAPI-style) ── a null value is valid on a nullable node.
+	if (data === null && schema.nullable === true) return errors;
+
+	// ── enum ── strict equality first, then deep-equal for object/array members.
+	if (Array.isArray(schema.enum)) {
+		const target = JSON.stringify(data);
+		const ok = schema.enum.some(v => v === data || JSON.stringify(v) === target);
+		if (!ok) errors.push(`${path}: value ${JSON.stringify(data)} is not one of allowed enum values ${JSON.stringify(schema.enum)}`);
+	}
+
+	// ── type ──
+	if (schema.type !== undefined) {
+		const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+		if (schema.nullable === true) types.push('null');
+		if (!types.some(t => matchesType(data, t))) {
+			errors.push(`${path}: expected type ${types.join('|')} but got ${describeType(data)}`);
+			// If the type is wrong, deeper checks are meaningless — stop here for this node.
+			return errors;
+		}
+	}
+
+	// ── object ── (Object.hasOwn avoids prototype-chain keys like 'toString')
+	const isObject = data !== null && typeof data === 'object' && !Array.isArray(data);
+	if (isObject && (schema.properties || schema.required || schema.additionalProperties === false)) {
+		const props = schema.properties || {};
+
+		if (Array.isArray(schema.required)) {
+			for (const key of schema.required) {
+				if (!Object.hasOwn(data, key)) errors.push(`${path}: missing required property "${key}"`);
+			}
+		}
+
+		if (schema.additionalProperties === false) {
+			for (const key of Object.keys(data)) {
+				if (!Object.hasOwn(props, key)) errors.push(`${path}: unexpected property "${key}" (additionalProperties is false)`);
+			}
+		}
+
+		for (const [key, subSchema] of Object.entries(props)) {
+			if (Object.hasOwn(data, key)) {
+				errors.push(...validateSchema(data[key], /** @type {any} */ (subSchema), `${path}.${key}`));
+			}
+		}
+	}
+
+	// ── array ──
+	if (Array.isArray(data) && schema.items && typeof schema.items === 'object' && !Array.isArray(schema.items)) {
+		data.forEach((item, i) => {
+			errors.push(...validateSchema(item, schema.items, `${path}[${i}]`));
+		});
+	}
+
+	return errors;
+}
+
+/**
+ * @param {*} value
+ * @param {string} type - JSON Schema type name
+ * @returns {boolean}
+ */
+function matchesType(value, type) {
+	switch (type) {
+		case 'string': return typeof value === 'string';
+		case 'number': return typeof value === 'number' && !Number.isNaN(value);
+		case 'integer': return typeof value === 'number' && Number.isInteger(value);
+		case 'boolean': return typeof value === 'boolean';
+		case 'object': return value !== null && typeof value === 'object' && !Array.isArray(value);
+		case 'array': return Array.isArray(value);
+		case 'null': return value === null;
+		default: return true; // unknown type keyword — be lenient
+	}
+}
+
+/**
+ * @param {*} value
+ * @returns {string}
+ */
+function describeType(value) {
+	if (value === null) return 'null';
+	if (Array.isArray(value)) return 'array';
+	return typeof value;
+}
+
 /**
  * Extracts valid JSON from model response text using multiple strategies.
  * @param {string} text - The model response text

package/message.js

@@ -53,6 +53,13 @@ class Message extends BaseGemini {
 		}
 		if (options.responseMimeType) {
 			this.chatConfig.responseMimeType = options.responseMimeType;
+		} else if (options.responseSchema) {
+			// Google's @google/genai requires response_mime_type: 'application/json'
+			// whenever a responseSchema is set — it does NOT add it automatically.
+			// Passing a schema without the mime type yields a 400 INVALID_ARGUMENT
+			// (Vertex) or prose output that fails JSON extraction. Auto-pair them.
+			this.chatConfig.responseMimeType = 'application/json';
+			log.debug("responseSchema set without responseMimeType — defaulting responseMimeType to 'application/json'.");
 		}
 
 		this._isStructured = !!(options.responseSchema || options.responseMimeType === 'application/json');
@@ -71,12 +78,11 @@ class Message extends BaseGemini {
 
 		log.debug(`Initializing ${this.constructor.name} with model: ${this.modelName}...`);
 
-		try {
-			await this.genAIClient.models.list();
-			log.debug(`${this.constructor.name}: API connection successful.`);
-		} catch (e) {
-			throw new Error(`${this.constructor.name} initialization failed: ${e.message}`);
-		}
+		// Connectivity check is opt-in (healthCheck: true). models.list() is a
+		// different IAM surface than generateContent — a service account allowed to
+		// generate but not list publisher models would fail here misleadingly — and
+		// it adds a round-trip per instance. The first send() is a fine error signal.
+		await this._healthCheckPing();
 
 		this._initialized = true;
 		log.debug(`${this.constructor.name}: Initialized (stateless mode).`);
@@ -111,11 +117,17 @@ class Message extends BaseGemini {
 			}
 		}));
 
+		// Compute per-call usage synchronously from THIS response before any other
+		// concurrent send() can mutate instance state. result.usage is safe under
+		// concurrency; getLastUsage() (instance state, updated below) is not.
+		const usage = this._usageFromResponse(result);
+
 		this._captureMetadata(result);
 
 		this._cumulativeUsage = {
 			promptTokens: this.lastResponseMetadata.promptTokens,
 			responseTokens: this.lastResponseMetadata.responseTokens,
+			thoughtsTokens: this.lastResponseMetadata.thoughtsTokens,
 			totalTokens: this.lastResponseMetadata.totalTokens,
 			attempts: 1
 		};
@@ -127,7 +139,7 @@ class Message extends BaseGemini {
 		const text = result.text || '';
 		const response = {
 			text,
-			usage: this.getLastUsage()
+			usage
 		};
 
 		// Parse structured data if configured

package/package.json

@@ -2,7 +2,7 @@
 	"name": "ak-gemini",
 	"author": "ak@mixpanel.com",
 	"description": "AK's Generative AI Helper for doing... everything",
-	"version": "2.4.1",
+	"version": "2.5.0",
 	"main": "index.js",
 	"files": [
 		"index.js",
@@ -19,7 +19,8 @@
 		"json-helpers.js",
 		"types.d.ts",
 		"logger.js",
-		"GUIDE.md"
+		"GUIDE.md",
+		"CHANGELOG.md"
 	],
 	"types": "types.d.ts",
 	"exports": {
@@ -65,7 +66,7 @@
 	],
 	"license": "ISC",
 	"dependencies": {
-		"@google/genai": "^2.10.0",
+		"@google/genai": "^2.12.0",
 		"dotenv": "^17.3.1",
 		"pino": "^10.3.1",
 		"pino-pretty": "^13.1.3"

package/types.d.ts

@@ -64,7 +64,9 @@ export interface UsageData {
   promptTokens: number;
   /** CUMULATIVE output tokens across all retry attempts */
   responseTokens: number;
-  /** CUMULATIVE total tokens across all retry attempts */
+  /** CUMULATIVE thinking ("thoughts") tokens; billed at the output rate. Included in totalTokens and estimatedCost. */
+  thoughtsTokens?: number;
+  /** CUMULATIVE total tokens across all retry attempts (includes thoughtsTokens) */
   totalTokens: number;
   /** Number of attempts (1 = first try success, 2+ = retries needed) */
   attempts: number;
@@ -76,6 +78,8 @@ export interface UsageData {
   groundingMetadata?: GroundingMetadata | null;
   /** Model lifecycle status from Google (e.g., 'DEPRECATED'). Surfaced from @google/genai 1.47+. */
   modelStatus?: string | null;
+  /** Estimated USD cost from MODEL_PRICING (input+output). null when the model's pricing is unknown. */
+  estimatedCost?: number | null;
 }
 
 export interface TransformationExample {
@@ -602,8 +606,8 @@ export declare class BaseGemini {
   estimateCost(nextPayload: Record<string, unknown> | string): Promise<{
     inputTokens: number;
     model: string;
-    pricing: { input: number; output: number };
-    estimatedInputCost: number;
+    pricing: { input: number; output: number } | null;
+    estimatedInputCost: number | null;
     note: string;
   }>;
 
@@ -757,6 +761,17 @@ export declare class ImageGenerator extends BaseGemini {
 
 export declare function extractJSON(text: string): any;
 export declare function attemptJSONRecovery(text: string, maxAttempts?: number): any | null;
+/** Validates a parsed value against a subset of JSON Schema. Returns error strings ([] means valid). */
+export declare function validateSchema(data: any, schema: Record<string, any>, path?: string): string[];
+
+/** Per-million-token pricing keyed by model id. */
+export declare const MODEL_PRICING: Record<string, { input: number; output: number }>;
+/** Floating `-latest` alias → canonical model id, for pricing resolution. */
+export declare const MODEL_ALIASES: Record<string, string>;
+/** Resolves pricing for a model id (follows -latest aliases). null when unknown. */
+export declare function resolvePricing(modelId: string | null | undefined): { input: number; output: number } | null;
+/** Estimated USD cost from token counts. null when the model's pricing is unknown. */
+export declare function computeCost(modelId: string | null | undefined, promptTokens: number, responseTokens: number): number | null;
 
 declare const _default: {
   Transformer: typeof Transformer;