ak-gemini 2.3.0 → 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

@@ -37,11 +37,13 @@ const THINKING_SUPPORTED_MODELS = [
 ];
 
 /**
- * Model pricing per million tokens (Paid Tier Standard, base rate, as of May 2026).
+ * Model pricing per million tokens (Paid Tier Standard, base rate, as of July 2026).
  * Source: https://ai.google.dev/gemini-api/docs/pricing
  *
  * NOTES:
  * - Pro models use tiered pricing (≤200k vs >200k context). Listed rate is ≤200k base tier.
+ * - Gemma models (e.g. Gemma 4) are intentionally excluded — they are open models with
+ *   no paid per-token tier on the Gemini API (Vertex deployments bill by compute).
  * - Image-output tokens on Nano Banana models bill at $60/M (1.5 Flash Image) or $120/M (3 Pro Image).
  *   Only text-input/text-output rates are modelled here; image-output cost is NOT included in estimateCost().
  * - Audio input is more expensive on most models — listed rate covers text/image/video input.
@@ -52,6 +54,7 @@ const MODEL_PRICING = {
 	'gemini-3.1-flash-lite': { input: 0.25, output: 1.50 },
 	// Gemini 3.x preview
 	'gemini-3.1-pro-preview': { input: 2.00, output: 12.00 }, // ≤200k tier
+	'gemini-3-pro-preview': { input: 2.00, output: 12.00 },   // ≤200k tier; launch rate (superseded by 3.1, off the pricing page)
 	'gemini-3-flash-preview': { input: 0.50, output: 3.00 },
 	'gemini-3.1-flash-lite-preview': { input: 0.25, output: 1.50 },
 	'gemini-3.1-flash-image-preview': { input: 0.50, output: 3.00 }, // text-only; image-output is $60/M
@@ -68,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 ─────────────────────────────────────────────────────────
 
@@ -155,6 +216,13 @@ class BaseGemini {
 		if (this.serviceTier) this.chatConfig['serviceTier'] = this.serviceTier;
 		if (this.includeServerSideToolInvocations) this.chatConfig['includeServerSideToolInvocations'] = true;
 
+		// ── Sampling Shortcuts ──
+		// Top-level sugar for chatConfig sampling knobs; wins over chatConfig
+		// (same precedence as the maxOutputTokens promotion below)
+		for (const key of ['temperature', 'topP', 'topK']) {
+			if (options[key] !== undefined) this.chatConfig[key] = options[key];
+		}
+
 		// Apply systemPrompt to chatConfig
 		if (this.systemPrompt) {
 			this.chatConfig.systemInstruction = this.systemPrompt;
@@ -227,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.
@@ -321,6 +399,7 @@ class BaseGemini {
 	 * @param {string} [opts.contextKey='CONTEXT'] - Key for optional context
 	 * @param {string} [opts.explanationKey='EXPLANATION'] - Key for optional explanations
 	 * @param {string} [opts.systemPromptKey='SYSTEM'] - Key for system prompt overrides in examples
+	 * @param {'json'|'text'} [opts.format='json'] - Model-turn format: 'json' wraps answers in a {data} envelope (Transformer protocol); 'text' stores ANSWER verbatim (prose agents like Chat)
 	 * @returns {Promise<Array>} The updated chat history
 	 */
 	async seed(examples, opts = {}) {
@@ -336,6 +415,7 @@ class BaseGemini {
 		const contextKey = opts.contextKey || 'CONTEXT';
 		const explanationKey = opts.explanationKey || 'EXPLANATION';
 		const systemPromptKey = opts.systemPromptKey || 'SYSTEM';
+		const format = opts.format || 'json';
 
 		// Check for system prompt override in examples
 		const instructionExample = examples.find(ex => ex[systemPromptKey]);
@@ -367,9 +447,15 @@ class BaseGemini {
 				userText += promptText;
 			}
 
-			if (answerValue) modelResponse.data = answerValue;
-			if (explanationValue) modelResponse.explanation = explanationValue;
-			const modelText = JSON.stringify(modelResponse, null, 2);
+			let modelText;
+			if (format === 'text') {
+				modelText = isJSON(answerValue) ? JSON.stringify(answerValue, null, 2) : String(answerValue || '');
+				if (explanationValue) log.warn('seed(): EXPLANATION has no representation in text format; ignored.');
+			} else {
+				if (answerValue) modelResponse.data = answerValue;
+				if (explanationValue) modelResponse.explanation = explanationValue;
+				modelText = JSON.stringify(modelResponse, null, 2);
+			}
 
 			if (userText.trim().length && modelText.trim().length > 0) {
 				historyToAdd.push({ role: 'user', parts: [{ text: userText.trim() }] });
@@ -398,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
@@ -423,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)
 		};
 	}
 
@@ -482,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/chat.js

@@ -47,6 +47,19 @@ class Chat extends BaseGemini {
 		log.debug(`Chat created with model: ${this.modelName}`);
 	}
 
+	/**
+	 * Seeds the conversation with example pairs stored as plain prose turns.
+	 * Chat is a prose agent — model turns are stored verbatim, not wrapped in
+	 * Transformer's {data} JSON envelope.
+	 *
+	 * @param {import('./types').TransformationExample[]} [examples]
+	 * @param {import('./types').SeedOptions} [opts={}]
+	 * @returns {Promise<Array>} The updated chat history
+	 */
+	async seed(examples, opts = {}) {
+		return super.seed(examples, { format: 'text', ...opts });
+	}
+
 	/**
 	 * Send a text message and get a response. Adds to conversation history.
 	 *

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");
@@ -338,6 +416,8 @@ var MODEL_PRICING = {
   // Gemini 3.x preview
   "gemini-3.1-pro-preview": { input: 2, output: 12 },
   // ≤200k tier
+  "gemini-3-pro-preview": { input: 2, output: 12 },
+  // ≤200k tier; launch rate (superseded by 3.1, off the pricing page)
   "gemini-3-flash-preview": { input: 0.5, output: 3 },
   "gemini-3.1-flash-lite-preview": { input: 0.25, output: 1.5 },
   "gemini-3.1-flash-image-preview": { input: 0.5, output: 3 },
@@ -357,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={}]
@@ -398,6 +508,9 @@ var BaseGemini = class {
     };
     if (this.serviceTier) this.chatConfig["serviceTier"] = this.serviceTier;
     if (this.includeServerSideToolInvocations) this.chatConfig["includeServerSideToolInvocations"] = true;
+    for (const key of ["temperature", "topP", "topK"]) {
+      if (options[key] !== void 0) this.chatConfig[key] = options[key];
+    }
     if (this.systemPrompt) {
       this.chatConfig.systemInstruction = this.systemPrompt;
     } else if (this.systemPrompt === null && options.systemPrompt === void 0) {
@@ -448,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.
@@ -531,6 +653,7 @@ var BaseGemini = class {
    * @param {string} [opts.contextKey='CONTEXT'] - Key for optional context
    * @param {string} [opts.explanationKey='EXPLANATION'] - Key for optional explanations
    * @param {string} [opts.systemPromptKey='SYSTEM'] - Key for system prompt overrides in examples
+   * @param {'json'|'text'} [opts.format='json'] - Model-turn format: 'json' wraps answers in a {data} envelope (Transformer protocol); 'text' stores ANSWER verbatim (prose agents like Chat)
    * @returns {Promise<Array>} The updated chat history
    */
   async seed(examples, opts = {}) {
@@ -544,6 +667,7 @@ var BaseGemini = class {
     const contextKey = opts.contextKey || "CONTEXT";
     const explanationKey = opts.explanationKey || "EXPLANATION";
     const systemPromptKey = opts.systemPromptKey || "SYSTEM";
+    const format = opts.format || "json";
     const instructionExample = examples.find((ex) => ex[systemPromptKey]);
     if (instructionExample) {
       logger_default.debug(`Found system prompt in examples; reinitializing chat.`);
@@ -572,9 +696,15 @@ ${contextText}
         let promptText = isJSON(promptValue) ? JSON.stringify(promptValue, null, 2) : promptValue;
         userText += promptText;
       }
-      if (answerValue) modelResponse.data = answerValue;
-      if (explanationValue) modelResponse.explanation = explanationValue;
-      const modelText = JSON.stringify(modelResponse, null, 2);
+      let modelText;
+      if (format === "text") {
+        modelText = isJSON(answerValue) ? JSON.stringify(answerValue, null, 2) : String(answerValue || "");
+        if (explanationValue) logger_default.warn("seed(): EXPLANATION has no representation in text format; ignored.");
+      } else {
+        if (answerValue) modelResponse.data = answerValue;
+        if (explanationValue) modelResponse.explanation = explanationValue;
+        modelText = JSON.stringify(modelResponse, null, 2);
+      }
       if (userText.trim().length && modelText.trim().length > 0) {
         historyToAdd.push({ role: "user", parts: [{ text: userText.trim() }] });
         historyToAdd.push({ role: "model", parts: [{ text: modelText.trim() }] });
@@ -596,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
@@ -619,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 ─────────────────────────────────────────────────────
@@ -666,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 ─────────────────────────────────────────────────────
@@ -938,7 +1123,8 @@ var Transformer = class extends base_default {
       answerKey: this.answerKey,
       contextKey: this.contextKey,
       explanationKey: this.explanationKey,
-      systemPromptKey: this.systemPromptKey
+      systemPromptKey: this.systemPromptKey,
+      format: "json"
     });
   }
   // ── Primary Send Method ──────────────────────────────────────────────────
@@ -1216,6 +1402,18 @@ var Chat = class extends base_default {
     super(options);
     logger_default.debug(`Chat created with model: ${this.modelName}`);
   }
+  /**
+   * Seeds the conversation with example pairs stored as plain prose turns.
+   * Chat is a prose agent — model turns are stored verbatim, not wrapped in
+   * Transformer's {data} JSON envelope.
+   *
+   * @param {import('./types').TransformationExample[]} [examples]
+   * @param {import('./types').SeedOptions} [opts={}]
+   * @returns {Promise<Array>} The updated chat history
+   */
+  async seed(examples, opts = {}) {
+    return super.seed(examples, { format: "text", ...opts });
+  }
   /**
    * Send a text message and get a response. Adds to conversation history.
    *
@@ -1284,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})`);
@@ -1297,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).`);
   }
@@ -1328,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
     };
@@ -1341,7 +1539,7 @@ var Message = class extends base_default {
     const text = result.text || "";
     const response = {
       text,
-      usage: this.getLastUsage()
+      usage
     };
     if (this._isStructured) {
       try {
@@ -2955,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).`);
   }
@@ -3092,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;
   }
   /**
@@ -3139,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
     };
@@ -3162,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.
@@ -3222,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.3.0",
+	"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.6.0",
+		"@google/genai": "^2.12.0",
 		"dotenv": "^17.3.1",
 		"pino": "^10.3.1",
 		"pino-pretty": "^13.1.3"

package/transformer.js

@@ -141,7 +141,8 @@ class Transformer extends BaseGemini {
 			answerKey: this.answerKey,
 			contextKey: this.contextKey,
 			explanationKey: this.explanationKey,
-			systemPromptKey: this.systemPromptKey
+			systemPromptKey: this.systemPromptKey,
+			format: 'json'
 		});
 	}
 

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 {
@@ -147,6 +151,12 @@ export interface BaseGeminiOptions {
   thinkingConfig?: ThinkingConfig | null;
   /** Maximum output tokens (default: 50000, null removes limit) */
   maxOutputTokens?: number | null;
+  /** Sampling temperature (shorthand for chatConfig.temperature; wins over chatConfig) */
+  temperature?: number;
+  /** Nucleus sampling (shorthand for chatConfig.topP; wins over chatConfig) */
+  topP?: number;
+  /** Top-k sampling (shorthand for chatConfig.topK; wins over chatConfig) */
+  topK?: number;
   /** Log level (default: based on NODE_ENV) */
   logLevel?: LogLevel;
 
@@ -563,6 +573,8 @@ export interface SeedOptions {
   contextKey?: string;
   explanationKey?: string;
   systemPromptKey?: string;
+  /** Model-turn format: 'json' wraps answers in a {data} envelope (Transformer protocol); 'text' stores ANSWER verbatim (prose agents like Chat). Default: 'json' */
+  format?: 'json' | 'text';
 }
 
 // ── Class Declarations ───────────────────────────────────────────────────────
@@ -594,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;
   }>;
 
@@ -749,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;