ak-gemini 2.2.1 → 2.4.1

package/base.js

@@ -25,26 +25,50 @@ const DEFAULT_THINKING_CONFIG = {
 
 const DEFAULT_MAX_OUTPUT_TOKENS = 50_000;
 
-/** Models that support thinking features */
+/** Models that support thinking features. Image / live / tts variants intentionally excluded. */
 const THINKING_SUPPORTED_MODELS = [
-	/^gemini-3-flash(-preview)?$/,
-	/^gemini-3-pro(-preview|-image-preview)?$/,
+	/^gemini-3(\.\d+)?-pro(-preview)?$/,
+	/^gemini-3(\.\d+)?-flash(-preview)?$/,
+	/^gemini-3(\.\d+)?-flash-lite(-preview)?$/,
 	/^gemini-2\.5-pro/,
 	/^gemini-2\.5-flash(-preview)?$/,
 	/^gemini-2\.5-flash-lite(-preview)?$/,
 	/^gemini-2\.0-flash$/
 ];
 
-/** Model pricing per million tokens (as of Dec 2025) */
+/**
+ * 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.
+ */
 const MODEL_PRICING = {
-	'gemini-2.5-flash': { input: 0.15, output: 0.60 },
-	'gemini-2.5-flash-lite': { input: 0.02, output: 0.10 },
-	'gemini-2.5-pro': { input: 2.50, output: 10.00 },
-	'gemini-3-pro': { input: 2.00, output: 12.00 },
-	'gemini-3-pro-preview': { input: 2.00, output: 12.00 },
+	// Gemini 3.x stable
+	'gemini-3.5-flash': { input: 1.50, output: 9.00 },
+	'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
+	'gemini-3-pro-image-preview': { input: 2.00, output: 12.00 },   // text-only; image-output is $120/M
+	// Gemini 2.5 stable
+	'gemini-2.5-flash': { input: 0.30, output: 2.50 },
+	'gemini-2.5-flash-lite': { input: 0.10, output: 0.40 },
+	'gemini-2.5-pro': { input: 1.25, output: 10.00 }, // ≤200k tier
+	'gemini-2.5-flash-image': { input: 0.30, output: 0 }, // image-output is ~$0.039/image (1290 tokens)
+	// Deprecated but kept for back-compat (shut down June 2026)
 	'gemini-2.0-flash': { input: 0.10, output: 0.40 },
 	'gemini-2.0-flash-lite': { input: 0.02, output: 0.10 },
-	'gemini-embedding-001': { input: 0.006, output: 0 }
+	// Embeddings
+	'gemini-embedding-001': { input: 0.15, output: 0 }
 };
 
 export { DEFAULT_SAFETY_SETTINGS, DEFAULT_THINKING_CONFIG, THINKING_SUPPORTED_MODELS, MODEL_PRICING, DEFAULT_MAX_OUTPUT_TOKENS };
@@ -70,7 +94,7 @@ class BaseGemini {
 	 */
 	constructor(options = {}) {
 		// ── Model ──
-		this.modelName = options.modelName || 'gemini-2.5-flash';
+		this.modelName = options.modelName || 'gemini-3-flash-preview';
 
 		// ── System Prompt ──
 		// Subclasses set their own default if options.systemPrompt is undefined
@@ -114,6 +138,14 @@ class BaseGemini {
 		// ── Caching ──
 		this.cachedContent = options.cachedContent || null;
 
+		// ── Service Tier (Gemini API / Vertex AI 2026+) ──
+		// Allowed values: 'STANDARD' | 'FLEX' | 'PRIORITY' — cost vs latency trade.
+		this.serviceTier = options.serviceTier || null;
+
+		// ── Server-Side Tool Invocation Visibility (1.46.0+) ──
+		// When grounding is on, surface the server's tool calls (e.g. Google Search) in the response.
+		this.includeServerSideToolInvocations = options.includeServerSideToolInvocations ?? false;
+
 		// ── Chat Config ──
 		this.chatConfig = {
 			temperature: 0.7,
@@ -123,6 +155,16 @@ class BaseGemini {
 			...options.chatConfig
 		};
 
+		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;
@@ -289,6 +331,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 = {}) {
@@ -304,6 +347,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]);
@@ -335,9 +379,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() }] });
@@ -365,6 +415,7 @@ class BaseGemini {
 	 * @protected
 	 */
 	_captureMetadata(response) {
+		const modelStatus = response?.modelStatus || null;
 		this.lastResponseMetadata = {
 			modelVersion: response.modelVersion || null,
 			requestedModel: this.modelName,
@@ -372,8 +423,13 @@ class BaseGemini {
 			responseTokens: response.usageMetadata?.candidatesTokenCount || 0,
 			totalTokens: response.usageMetadata?.totalTokenCount || 0,
 			timestamp: Date.now(),
-			groundingMetadata: response.candidates?.[0]?.groundingMetadata || null
+			groundingMetadata: response.candidates?.[0]?.groundingMetadata || null,
+			modelStatus
 		};
+		if (modelStatus === 'DEPRECATED' && !this._deprecationWarned) {
+			log.warn(`Model "${this.modelName}" is marked DEPRECATED by Google. Plan migration.`);
+			this._deprecationWarned = true;
+		}
 	}
 
 	/**
@@ -396,7 +452,8 @@ class BaseGemini {
 			modelVersion: meta.modelVersion,
 			requestedModel: meta.requestedModel,
 			timestamp: meta.timestamp,
-			groundingMetadata: meta.groundingMetadata || null
+			groundingMetadata: meta.groundingMetadata || null,
+			modelStatus: meta.modelStatus || 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/image-generator.js

@@ -0,0 +1,186 @@
+/**
+ * @fileoverview ImageGenerator — Generate images via Gemini's Nano Banana models.
+ *
+ * Extends BaseGemini for auth/client reuse but overrides init() to skip chat session
+ * creation (image gen is stateless). Mirrors the Embedding class pattern.
+ *
+ * @example
+ * ```javascript
+ * import { ImageGenerator } from 'ak-gemini';
+ * import { writeFileSync } from 'node:fs';
+ *
+ * const gen = new ImageGenerator({ apiKey: 'your-key' });
+ * const result = await gen.generate('A cat astronaut on the moon');
+ * writeFileSync('cat.png', Buffer.from(result.images[0].data, 'base64'));
+ * ```
+ */
+
+import BaseGemini from './base.js';
+import log from './logger.js';
+import { writeFileSync } from 'node:fs';
+
+const DEFAULT_IMAGE_MODEL = 'gemini-3.1-flash-image-preview';
+
+export default class ImageGenerator extends BaseGemini {
+
+	/**
+	 * @param {import('./types.d.ts').ImageGeneratorOptions} [options={}]
+	 */
+	constructor(options = {}) {
+		if (options.modelName === undefined) {
+			options = { ...options, modelName: DEFAULT_IMAGE_MODEL };
+		}
+		if (options.systemPrompt === undefined) {
+			options = { ...options, systemPrompt: null };
+		}
+		super(options);
+
+		this.aspectRatio = options.aspectRatio || null;
+		this.imageSize = options.imageSize || null;
+		this.personGeneration = options.personGeneration || null;
+		this.includeText = options.includeText ?? false;
+
+		log.debug(`ImageGenerator created with model: ${this.modelName}`);
+	}
+
+	/**
+	 * Validate API connection only; no chat session (stateless).
+	 * @param {boolean} [force=false]
+	 */
+	async init(force = false) {
+		if (this._initialized && !force) return;
+
+		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}`);
+		}
+
+		this._initialized = true;
+	}
+
+	/**
+	 * Build a FRESH config — Gemini image models reject safetySettings/temp/topK/topP/thinkingConfig.
+	 * Do NOT spread this.chatConfig.
+	 * @private
+	 */
+	_buildConfig(overrides = {}) {
+		const includeText = overrides.includeText ?? this.includeText;
+		const config = { responseModalities: includeText ? ['IMAGE', 'TEXT'] : ['IMAGE'] };
+
+		const imageConfig = {};
+		const aspectRatio = overrides.aspectRatio || this.aspectRatio;
+		const imageSize = overrides.imageSize || this.imageSize;
+		const personGeneration = overrides.personGeneration || this.personGeneration;
+		if (aspectRatio) imageConfig.aspectRatio = aspectRatio;
+		if (imageSize) imageConfig.imageSize = imageSize;
+		if (personGeneration) imageConfig.personGeneration = personGeneration;
+		if (Object.keys(imageConfig).length > 0) config.imageConfig = imageConfig;
+
+		return config;
+	}
+
+	/**
+	 * Generate one or more images from a text prompt.
+	 * Optionally accepts `inputImages` for image editing / multi-image composition.
+	 *
+	 * @param {string} prompt
+	 * @param {import('./types.d.ts').ImageGenerateOptions} [opts={}]
+	 * @returns {Promise<import('./types.d.ts').ImageGenerationResult>}
+	 */
+	async generate(prompt, opts = {}) {
+		if (!this._initialized) await this.init();
+
+		/** @type {any[]} */
+		const parts = [{ text: prompt }];
+		if (Array.isArray(opts.inputImages)) {
+			for (const img of opts.inputImages) {
+				parts.push({ inlineData: { data: img.data, mimeType: img.mimeType } });
+			}
+		}
+
+		const result = await this._withRetry(() => this.genAIClient.models.generateContent({
+			model: this.modelName,
+			contents: [{ role: 'user', parts }],
+			config: this._buildConfig(opts)
+		}));
+
+		this._captureMetadata(result);
+		this._cumulativeUsage = {
+			promptTokens: this.lastResponseMetadata.promptTokens,
+			responseTokens: this.lastResponseMetadata.responseTokens,
+			totalTokens: this.lastResponseMetadata.totalTokens,
+			attempts: 1
+		};
+
+		const images = [];
+		let text = '';
+		const responseParts = result.candidates?.[0]?.content?.parts || [];
+		for (const part of responseParts) {
+			if (part.inlineData?.data) {
+				images.push({
+					data: part.inlineData.data,
+					mimeType: part.inlineData.mimeType || 'image/png'
+				});
+			} else if (part.text) {
+				text += part.text;
+			}
+		}
+
+		if (images.length === 0) {
+			log.warn('ImageGenerator: no images returned. Check prompt or safety filters.');
+		}
+
+		return { images, text: text || null, usage: this.getLastUsage() };
+	}
+
+	/**
+	 * Convenience: write one or all images to disk.
+	 * If multiple images, suffixes with `_N` before extension.
+	 * @param {import('./types.d.ts').ImageGenerationResult} result
+	 * @param {string} filePath
+	 * @returns {string[]} Written file paths
+	 */
+	save(result, filePath) {
+		if (!result?.images?.length) {
+			log.warn('ImageGenerator.save(): no images to save.');
+			return [];
+		}
+		const paths = [];
+		const dot = filePath.lastIndexOf('.');
+		const base = dot >= 0 ? filePath.slice(0, dot) : filePath;
+		const ext = dot >= 0 ? filePath.slice(dot) : '.png';
+		result.images.forEach((img, i) => {
+			const out = result.images.length === 1 ? filePath : `${base}_${i}${ext}`;
+			writeFileSync(out, Buffer.from(img.data, 'base64'));
+			paths.push(out);
+		});
+		return paths;
+	}
+
+	// ── No-ops (image gen is stateless) ──
+
+	/** @returns {any[]} Always returns empty array */
+	getHistory() { return []; }
+
+	/** No-op for ImageGenerator */
+	async clearHistory() {}
+
+	/** No-op for ImageGenerator */
+	async seed() {
+		log.warn('ImageGenerator.seed() is a no-op — image generation does not support few-shot.');
+		return [];
+	}
+
+	/**
+	 * @param {any} _nextPayload
+	 * @throws {Error} ImageGenerator does not support token estimation
+	 * @returns {Promise<{ inputTokens: number }>}
+	 */
+	async estimate(_nextPayload) {
+		throw new Error('ImageGenerator does not support token estimation. Use generate() directly.');
+	}
+}

package/index.cjs

@@ -35,6 +35,7 @@ __export(index_exports, {
   Embedding: () => Embedding,
   HarmBlockThreshold: () => import_genai2.HarmBlockThreshold,
   HarmCategory: () => import_genai2.HarmCategory,
+  ImageGenerator: () => ImageGenerator,
   Message: () => message_default,
   RagAgent: () => rag_agent_default,
   ThinkingLevel: () => import_genai2.ThinkingLevel,
@@ -322,29 +323,48 @@ var DEFAULT_THINKING_CONFIG = {
 };
 var DEFAULT_MAX_OUTPUT_TOKENS = 5e4;
 var THINKING_SUPPORTED_MODELS = [
-  /^gemini-3-flash(-preview)?$/,
-  /^gemini-3-pro(-preview|-image-preview)?$/,
+  /^gemini-3(\.\d+)?-pro(-preview)?$/,
+  /^gemini-3(\.\d+)?-flash(-preview)?$/,
+  /^gemini-3(\.\d+)?-flash-lite(-preview)?$/,
   /^gemini-2\.5-pro/,
   /^gemini-2\.5-flash(-preview)?$/,
   /^gemini-2\.5-flash-lite(-preview)?$/,
   /^gemini-2\.0-flash$/
 ];
 var MODEL_PRICING = {
-  "gemini-2.5-flash": { input: 0.15, output: 0.6 },
-  "gemini-2.5-flash-lite": { input: 0.02, output: 0.1 },
-  "gemini-2.5-pro": { input: 2.5, output: 10 },
-  "gemini-3-pro": { input: 2, output: 12 },
+  // Gemini 3.x stable
+  "gemini-3.5-flash": { input: 1.5, output: 9 },
+  "gemini-3.1-flash-lite": { input: 0.25, output: 1.5 },
+  // 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 },
+  // text-only; image-output is $60/M
+  "gemini-3-pro-image-preview": { input: 2, output: 12 },
+  // text-only; image-output is $120/M
+  // Gemini 2.5 stable
+  "gemini-2.5-flash": { input: 0.3, output: 2.5 },
+  "gemini-2.5-flash-lite": { input: 0.1, output: 0.4 },
+  "gemini-2.5-pro": { input: 1.25, output: 10 },
+  // ≤200k tier
+  "gemini-2.5-flash-image": { input: 0.3, output: 0 },
+  // image-output is ~$0.039/image (1290 tokens)
+  // Deprecated but kept for back-compat (shut down June 2026)
   "gemini-2.0-flash": { input: 0.1, output: 0.4 },
   "gemini-2.0-flash-lite": { input: 0.02, output: 0.1 },
-  "gemini-embedding-001": { input: 6e-3, output: 0 }
+  // Embeddings
+  "gemini-embedding-001": { input: 0.15, output: 0 }
 };
 var BaseGemini = class {
   /**
    * @param {BaseGeminiOptions} [options={}]
    */
   constructor(options = {}) {
-    this.modelName = options.modelName || "gemini-2.5-flash";
+    this.modelName = options.modelName || "gemini-3-flash-preview";
     if (options.systemPrompt !== void 0) {
       this.systemPrompt = options.systemPrompt;
     } else {
@@ -369,6 +389,8 @@ var BaseGemini = class {
     this.enableGrounding = options.enableGrounding || false;
     this.groundingConfig = options.groundingConfig || {};
     this.cachedContent = options.cachedContent || null;
+    this.serviceTier = options.serviceTier || null;
+    this.includeServerSideToolInvocations = options.includeServerSideToolInvocations ?? false;
     this.chatConfig = {
       temperature: 0.7,
       topP: 0.95,
@@ -376,6 +398,11 @@ var BaseGemini = class {
       safetySettings: DEFAULT_SAFETY_SETTINGS,
       ...options.chatConfig
     };
+    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) {
@@ -509,6 +536,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 = {}) {
@@ -522,6 +550,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.`);
@@ -550,9 +579,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() }] });
@@ -573,6 +608,7 @@ ${contextText}
    * @protected
    */
   _captureMetadata(response) {
+    const modelStatus = response?.modelStatus || null;
     this.lastResponseMetadata = {
       modelVersion: response.modelVersion || null,
       requestedModel: this.modelName,
@@ -580,8 +616,13 @@ ${contextText}
       responseTokens: response.usageMetadata?.candidatesTokenCount || 0,
       totalTokens: response.usageMetadata?.totalTokenCount || 0,
       timestamp: Date.now(),
-      groundingMetadata: response.candidates?.[0]?.groundingMetadata || null
+      groundingMetadata: response.candidates?.[0]?.groundingMetadata || null,
+      modelStatus
     };
+    if (modelStatus === "DEPRECATED" && !this._deprecationWarned) {
+      logger_default.warn(`Model "${this.modelName}" is marked DEPRECATED by Google. Plan migration.`);
+      this._deprecationWarned = true;
+    }
   }
   /**
    * Returns structured usage data from the last API call for billing verification.
@@ -601,7 +642,8 @@ ${contextText}
       modelVersion: meta.modelVersion,
       requestedModel: meta.requestedModel,
       timestamp: meta.timestamp,
-      groundingMetadata: meta.groundingMetadata || null
+      groundingMetadata: meta.groundingMetadata || null,
+      modelStatus: meta.modelStatus || null
     };
   }
   // ── Token Estimation ─────────────────────────────────────────────────────
@@ -909,7 +951,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 ──────────────────────────────────────────────────
@@ -1187,6 +1230,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.
    *
@@ -3035,9 +3090,155 @@ var Embedding = class extends base_default {
   }
 };
 
+// image-generator.js
+var import_node_fs = require("node:fs");
+var DEFAULT_IMAGE_MODEL = "gemini-3.1-flash-image-preview";
+var ImageGenerator = class extends base_default {
+  /**
+   * @param {import('./types.d.ts').ImageGeneratorOptions} [options={}]
+   */
+  constructor(options = {}) {
+    if (options.modelName === void 0) {
+      options = { ...options, modelName: DEFAULT_IMAGE_MODEL };
+    }
+    if (options.systemPrompt === void 0) {
+      options = { ...options, systemPrompt: null };
+    }
+    super(options);
+    this.aspectRatio = options.aspectRatio || null;
+    this.imageSize = options.imageSize || null;
+    this.personGeneration = options.personGeneration || null;
+    this.includeText = options.includeText ?? false;
+    logger_default.debug(`ImageGenerator created with model: ${this.modelName}`);
+  }
+  /**
+   * Validate API connection only; no chat session (stateless).
+   * @param {boolean} [force=false]
+   */
+  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}`);
+    }
+    this._initialized = true;
+  }
+  /**
+   * Build a FRESH config — Gemini image models reject safetySettings/temp/topK/topP/thinkingConfig.
+   * Do NOT spread this.chatConfig.
+   * @private
+   */
+  _buildConfig(overrides = {}) {
+    const includeText = overrides.includeText ?? this.includeText;
+    const config = { responseModalities: includeText ? ["IMAGE", "TEXT"] : ["IMAGE"] };
+    const imageConfig = {};
+    const aspectRatio = overrides.aspectRatio || this.aspectRatio;
+    const imageSize = overrides.imageSize || this.imageSize;
+    const personGeneration = overrides.personGeneration || this.personGeneration;
+    if (aspectRatio) imageConfig.aspectRatio = aspectRatio;
+    if (imageSize) imageConfig.imageSize = imageSize;
+    if (personGeneration) imageConfig.personGeneration = personGeneration;
+    if (Object.keys(imageConfig).length > 0) config.imageConfig = imageConfig;
+    return config;
+  }
+  /**
+   * Generate one or more images from a text prompt.
+   * Optionally accepts `inputImages` for image editing / multi-image composition.
+   *
+   * @param {string} prompt
+   * @param {import('./types.d.ts').ImageGenerateOptions} [opts={}]
+   * @returns {Promise<import('./types.d.ts').ImageGenerationResult>}
+   */
+  async generate(prompt, opts = {}) {
+    if (!this._initialized) await this.init();
+    const parts = [{ text: prompt }];
+    if (Array.isArray(opts.inputImages)) {
+      for (const img of opts.inputImages) {
+        parts.push({ inlineData: { data: img.data, mimeType: img.mimeType } });
+      }
+    }
+    const result = await this._withRetry(() => this.genAIClient.models.generateContent({
+      model: this.modelName,
+      contents: [{ role: "user", parts }],
+      config: this._buildConfig(opts)
+    }));
+    this._captureMetadata(result);
+    this._cumulativeUsage = {
+      promptTokens: this.lastResponseMetadata.promptTokens,
+      responseTokens: this.lastResponseMetadata.responseTokens,
+      totalTokens: this.lastResponseMetadata.totalTokens,
+      attempts: 1
+    };
+    const images = [];
+    let text = "";
+    const responseParts = result.candidates?.[0]?.content?.parts || [];
+    for (const part of responseParts) {
+      if (part.inlineData?.data) {
+        images.push({
+          data: part.inlineData.data,
+          mimeType: part.inlineData.mimeType || "image/png"
+        });
+      } else if (part.text) {
+        text += part.text;
+      }
+    }
+    if (images.length === 0) {
+      logger_default.warn("ImageGenerator: no images returned. Check prompt or safety filters.");
+    }
+    return { images, text: text || null, usage: this.getLastUsage() };
+  }
+  /**
+   * Convenience: write one or all images to disk.
+   * If multiple images, suffixes with `_N` before extension.
+   * @param {import('./types.d.ts').ImageGenerationResult} result
+   * @param {string} filePath
+   * @returns {string[]} Written file paths
+   */
+  save(result, filePath) {
+    if (!result?.images?.length) {
+      logger_default.warn("ImageGenerator.save(): no images to save.");
+      return [];
+    }
+    const paths = [];
+    const dot = filePath.lastIndexOf(".");
+    const base = dot >= 0 ? filePath.slice(0, dot) : filePath;
+    const ext = dot >= 0 ? filePath.slice(dot) : ".png";
+    result.images.forEach((img, i) => {
+      const out = result.images.length === 1 ? filePath : `${base}_${i}${ext}`;
+      (0, import_node_fs.writeFileSync)(out, Buffer.from(img.data, "base64"));
+      paths.push(out);
+    });
+    return paths;
+  }
+  // ── No-ops (image gen is stateless) ──
+  /** @returns {any[]} Always returns empty array */
+  getHistory() {
+    return [];
+  }
+  /** No-op for ImageGenerator */
+  async clearHistory() {
+  }
+  /** No-op for ImageGenerator */
+  async seed() {
+    logger_default.warn("ImageGenerator.seed() is a no-op \u2014 image generation does not support few-shot.");
+    return [];
+  }
+  /**
+   * @param {any} _nextPayload
+   * @throws {Error} ImageGenerator does not support token estimation
+   * @returns {Promise<{ inputTokens: number }>}
+   */
+  async estimate(_nextPayload) {
+    throw new Error("ImageGenerator does not support token estimation. Use generate() directly.");
+  }
+};
+
 // index.js
 var import_genai2 = require("@google/genai");
-var index_default = { Transformer: transformer_default, Chat: chat_default, Message: message_default, ToolAgent: tool_agent_default, CodeAgent: code_agent_default, RagAgent: rag_agent_default, Embedding };
+var index_default = { Transformer: transformer_default, Chat: chat_default, Message: message_default, ToolAgent: tool_agent_default, CodeAgent: code_agent_default, RagAgent: rag_agent_default, Embedding, ImageGenerator };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BaseGemini,
@@ -3046,6 +3247,7 @@ var index_default = { Transformer: transformer_default, Chat: chat_default, Mess
   Embedding,
   HarmBlockThreshold,
   HarmCategory,
+  ImageGenerator,
   Message,
   RagAgent,
   ThinkingLevel,

package/index.js

@@ -27,6 +27,7 @@ export { default as ToolAgent } from './tool-agent.js';
 export { default as CodeAgent } from './code-agent.js';
 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 { default as log } from './logger.js';
 export { ThinkingLevel, HarmCategory, HarmBlockThreshold } from '@google/genai';
@@ -41,5 +42,6 @@ import ToolAgent from './tool-agent.js';
 import CodeAgent from './code-agent.js';
 import RagAgent from './rag-agent.js';
 import Embedding from './embedding.js';
+import ImageGenerator from './image-generator.js';
 
-export default { Transformer, Chat, Message, ToolAgent, CodeAgent, RagAgent, Embedding };
+export default { Transformer, Chat, Message, ToolAgent, CodeAgent, RagAgent, Embedding, ImageGenerator };

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.2.1",
+	"version": "2.4.1",
 	"main": "index.js",
 	"files": [
 		"index.js",
@@ -15,6 +15,7 @@
 		"code-agent.js",
 		"rag-agent.js",
 		"embedding.js",
+		"image-generator.js",
 		"json-helpers.js",
 		"types.d.ts",
 		"logger.js",
@@ -64,7 +65,7 @@
 	],
 	"license": "ISC",
 	"dependencies": {
-		"@google/genai": "^1.44.0",
+		"@google/genai": "^2.10.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

@@ -68,12 +68,14 @@ export interface UsageData {
   totalTokens: number;
   /** Number of attempts (1 = first try success, 2+ = retries needed) */
   attempts: number;
-  /** Actual model that responded (e.g., 'gemini-2.5-flash-001') */
+  /** Actual model that responded (e.g., 'gemini-3-flash-preview-001') */
   modelVersion: string | null;
-  /** Model you requested (e.g., 'gemini-2.5-flash') */
+  /** Model you requested (e.g., 'gemini-3-flash-preview') */
   requestedModel: string;
   timestamp: number;
   groundingMetadata?: GroundingMetadata | null;
+  /** Model lifecycle status from Google (e.g., 'DEPRECATED'). Surfaced from @google/genai 1.47+. */
+  modelStatus?: string | null;
 }
 
 export interface TransformationExample {
@@ -130,11 +132,12 @@ export interface CachedContentInfo {
 
 export type AsyncValidatorFunction = (payload: Record<string, unknown>) => Promise<unknown>;
 export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'none';
+export type ServiceTier = 'STANDARD' | 'FLEX' | 'PRIORITY';
 
 // ── Constructor Options ──────────────────────────────────────────────────────
 
 export interface BaseGeminiOptions {
-  /** Gemini model to use (default: 'gemini-2.5-flash') */
+  /** Gemini model to use (default: 'gemini-3-flash-preview') */
   modelName?: string;
   /** System prompt for the model (null or false to disable) */
   systemPrompt?: string | null | false;
@@ -144,6 +147,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;
 
@@ -177,6 +186,12 @@ export interface BaseGeminiOptions {
 
   /** Run models.list() health check during init() (default: false) */
   healthCheck?: boolean;
+
+  /** Service tier for generateContent (STANDARD | FLEX | PRIORITY). @google/genai 1.47+ */
+  serviceTier?: ServiceTier;
+
+  /** Surface server-side tool invocations (e.g. Google Search) in the response. @google/genai 1.46+ */
+  includeServerSideToolInvocations?: boolean;
 }
 
 export interface TransformerOptions extends BaseGeminiOptions {
@@ -254,6 +269,48 @@ export interface EmbeddingResult {
   statistics?: { tokenCount?: number; truncated?: boolean };
 }
 
+// ── ImageGenerator ───────────────────────────────────────────────────────────
+
+export type ImageAspectRatio = '1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '9:16' | '16:9' | '21:9';
+export type ImageSize = '1K' | '2K' | '4K';
+export type PersonGeneration = 'ALLOW_ALL' | 'ALLOW_ADULT' | 'ALLOW_NONE';
+
+export interface ImageGeneratorOptions extends BaseGeminiOptions {
+  /** Default aspect ratio for generated images */
+  aspectRatio?: ImageAspectRatio;
+  /** Default output resolution (1K/2K/4K) */
+  imageSize?: ImageSize;
+  /** Default people-generation policy */
+  personGeneration?: PersonGeneration;
+  /** Include text output alongside images (default: false) */
+  includeText?: boolean;
+}
+
+export interface ImageGenerateOptions {
+  aspectRatio?: ImageAspectRatio;
+  imageSize?: ImageSize;
+  personGeneration?: PersonGeneration;
+  includeText?: boolean;
+  /** Reference images for editing / multi-image composition (base64) */
+  inputImages?: Array<{ data: string; mimeType: string }>;
+}
+
+export interface GeneratedImage {
+  /** Base64-encoded image data */
+  data: string;
+  /** MIME type (e.g. "image/png") */
+  mimeType: string;
+}
+
+export interface ImageGenerationResult {
+  /** One or more generated images */
+  images: GeneratedImage[];
+  /** Optional text response (only when includeText: true) */
+  text: string | null;
+  /** Token usage */
+  usage: UsageData | null;
+}
+
 /** Tool declaration in @google/genai FunctionDeclaration format */
 export interface ToolDeclaration {
   name: string;
@@ -512,6 +569,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 ───────────────────────────────────────────────────────
@@ -531,6 +590,8 @@ export declare class BaseGemini {
   enableGrounding: boolean;
   groundingConfig: Record<string, any>;
   cachedContent: string | null;
+  serviceTier: ServiceTier | null;
+  includeServerSideToolInvocations: boolean;
 
   init(force?: boolean): Promise<void>;
   seed(examples?: TransformationExample[], opts?: SeedOptions): Promise<any[]>;
@@ -677,6 +738,21 @@ export declare class Embedding extends BaseGemini {
   similarity(a: number[], b: number[]): number;
 }
 
+export declare class ImageGenerator extends BaseGemini {
+  constructor(options?: ImageGeneratorOptions);
+
+  aspectRatio: ImageAspectRatio | null;
+  imageSize: ImageSize | null;
+  personGeneration: PersonGeneration | null;
+  includeText: boolean;
+
+  init(force?: boolean): Promise<void>;
+  /** Generate one or more images from a text prompt. Supports optional reference images for editing. */
+  generate(prompt: string, opts?: ImageGenerateOptions): Promise<ImageGenerationResult>;
+  /** Write generated images to disk (suffixes `_N` before extension if >1 image) */
+  save(result: ImageGenerationResult, filePath: string): string[];
+}
+
 // ── Module Exports ───────────────────────────────────────────────────────────
 
 export declare function extractJSON(text: string): any;
@@ -690,6 +766,7 @@ declare const _default: {
   CodeAgent: typeof CodeAgent;
   RagAgent: typeof RagAgent;
   Embedding: typeof Embedding;
+  ImageGenerator: typeof ImageGenerator;
 };
 
 export default _default;