ak-gemini 2.0.1 → 2.0.3

package/README.md

@@ -1,6 +1,6 @@
 # ak-gemini
 
-**Modular, type-safe wrapper for Google's Gemini AI.** Five class exports for different interaction patterns — JSON transformation, chat, stateless messages, tool-using agents, and code-writing agents — all sharing a common base.
+**Modular, type-safe wrapper for Google's Gemini AI.** Seven class exports for different interaction patterns — JSON transformation, chat, stateless messages, tool-using agents, code-writing agents, document Q&A, and embeddings — all sharing a common base.
 
 ```sh
 npm install ak-gemini
@@ -17,7 +17,7 @@ export GEMINI_API_KEY=your-key
 ```
 
 ```javascript
-import { Transformer, Chat, Message, ToolAgent, CodeAgent } from 'ak-gemini';
+import { Transformer, Chat, Message, ToolAgent, CodeAgent, RagAgent, Embedding } from 'ak-gemini';
 ```
 
 ---
@@ -176,6 +176,27 @@ for await (const event of agent.stream('Refactor the auth module')) {
 }
 ```
 
+### Embedding — Vector Embeddings
+
+Generate vector embeddings for similarity search, clustering, and classification.
+
+```javascript
+const embedder = new Embedding({
+  modelName: 'gemini-embedding-001', // default
+  taskType: 'RETRIEVAL_DOCUMENT'
+});
+
+// Single text
+const result = await embedder.embed('Hello world');
+console.log(result.values); // [0.012, -0.034, ...]
+
+// Batch
+const results = await embedder.embedBatch(['Hello', 'World']);
+
+// Cosine similarity (pure math, no API call)
+const score = embedder.similarity(results[0].values, results[1].values);
+```
+
 ---
 
 ## Stopping Agents
@@ -252,6 +273,43 @@ new Chat({
 });
 ```
 
+### Google Search Grounding
+
+Ground responses in real-time web search results. Available on all classes.
+
+```javascript
+const chat = new Chat({
+  enableGrounding: true,
+  groundingConfig: { excludeDomains: ['example.com'] }
+});
+
+const result = await chat.send('Who won the 2026 Super Bowl?');
+const sources = result.usage?.groundingMetadata?.groundingChunks;
+```
+
+**Warning**: Google Search grounding costs ~$35/1k queries.
+
+### Context Caching
+
+Reduce costs by caching repeated system prompts, documents, or tool definitions.
+
+```javascript
+const chat = new Chat({ systemPrompt: longSystemPrompt });
+
+// Create a cache
+const cache = await chat.createCache({
+  ttl: '3600s',
+  displayName: 'my-system-prompt-cache'
+});
+
+// Use the cache (subsequent calls use cached tokens at reduced cost)
+await chat.useCache(cache.name);
+const result = await chat.send('Hello!');
+
+// Clean up
+await chat.deleteCache(cache.name);
+```
+
 ### Billing Labels (Vertex AI)
 
 ```javascript
@@ -281,6 +339,9 @@ All classes accept `BaseGeminiOptions`:
 | `maxOutputTokens` | number | `50000` | Max tokens in response (`null` removes limit) |
 | `logLevel` | string | based on NODE_ENV | `'trace'`\|`'debug'`\|`'info'`\|`'warn'`\|`'error'`\|`'none'` |
 | `labels` | object | — | Billing labels (Vertex AI) |
+| `enableGrounding` | boolean | `false` | Enable Google Search grounding |
+| `groundingConfig` | object | — | Grounding config (excludeDomains, timeRangeFilter) |
+| `cachedContent` | string | — | Cached content resource name |
 
 ### Transformer-Specific
 
@@ -293,8 +354,6 @@ All classes accept `BaseGeminiOptions`:
 | `retryDelay` | number | `1000` | Initial retry delay (ms) |
 | `responseSchema` | object | — | JSON schema for output validation |
 | `asyncValidator` | function | — | Global async validator |
-| `enableGrounding` | boolean | `false` | Enable Google Search grounding |
-
 ### ToolAgent-Specific
 
 | Option | Type | Default | Description |
@@ -322,21 +381,31 @@ All classes accept `BaseGeminiOptions`:
 | `responseSchema` | object | — | Schema for structured output |
 | `responseMimeType` | string | — | e.g. `'application/json'` |
 
+### Embedding-Specific
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `taskType` | string | — | `'RETRIEVAL_DOCUMENT'`, `'RETRIEVAL_QUERY'`, `'SEMANTIC_SIMILARITY'`, `'CLUSTERING'` |
+| `title` | string | — | Document title (only with `RETRIEVAL_DOCUMENT`) |
+| `outputDimensionality` | number | — | Output vector dimensions |
+| `autoTruncate` | boolean | `true` | Auto-truncate long inputs |
+
 ---
 
 ## Exports
 
 ```javascript
 // Named exports
-import { Transformer, Chat, Message, ToolAgent, CodeAgent, BaseGemini, log } from 'ak-gemini';
+import { Transformer, Chat, Message, ToolAgent, CodeAgent, RagAgent, Embedding, BaseGemini, log } from 'ak-gemini';
 import { extractJSON, attemptJSONRecovery } from 'ak-gemini';
 
 // Default export (namespace)
 import AI from 'ak-gemini';
 new AI.Transformer({ ... });
+new AI.Embedding({ ... });
 
 // CommonJS
-const { Transformer, Chat } = require('ak-gemini');
+const { Transformer, Chat, Embedding } = require('ak-gemini');
 ```
 
 ---

package/base.js

@@ -5,7 +5,7 @@
  */
 
 import dotenv from 'dotenv';
-dotenv.config();
+dotenv.config({ quiet: true });
 const { NODE_ENV = "unknown", LOG_LEVEL = "" } = process.env;
 
 import { GoogleGenAI, HarmCategory, HarmBlockThreshold } from '@google/genai';
@@ -43,7 +43,8 @@ const MODEL_PRICING = {
 	'gemini-3-pro': { input: 2.00, output: 12.00 },
 	'gemini-3-pro-preview': { input: 2.00, output: 12.00 },
 	'gemini-2.0-flash': { input: 0.10, output: 0.40 },
-	'gemini-2.0-flash-lite': { input: 0.02, output: 0.10 }
+	'gemini-2.0-flash-lite': { input: 0.02, output: 0.10 },
+	'gemini-embedding-001': { input: 0.006, output: 0 }
 };
 
 export { DEFAULT_SAFETY_SETTINGS, DEFAULT_THINKING_CONFIG, THINKING_SUPPORTED_MODELS, MODEL_PRICING, DEFAULT_MAX_OUTPUT_TOKENS };
@@ -99,6 +100,13 @@ class BaseGemini {
 		// ── Labels ──
 		this.labels = options.labels || {};
 
+		// ── Grounding ──
+		this.enableGrounding = options.enableGrounding || false;
+		this.groundingConfig = options.groundingConfig || {};
+
+		// ── Caching ──
+		this.cachedContent = options.cachedContent || null;
+
 		// ── Chat Config ──
 		this.chatConfig = {
 			temperature: 0.7,
@@ -197,14 +205,24 @@ class BaseGemini {
 	 * @protected
 	 */
 	_getChatCreateOptions() {
-		return {
+		const opts = {
 			model: this.modelName,
 			config: {
 				...this.chatConfig,
-				...(this.vertexai && Object.keys(this.labels).length > 0 && { labels: this.labels })
+				...(this.vertexai && Object.keys(this.labels).length > 0 && { labels: this.labels }),
+				...(this.cachedContent && { cachedContent: this.cachedContent })
 			},
 			history: []
 		};
+
+		// Merge grounding into tools (preserving existing tools like functionDeclarations)
+		if (this.enableGrounding) {
+			const existingTools = opts.config.tools || [];
+			opts.config.tools = [...existingTools, { googleSearch: this.groundingConfig }];
+			log.debug('Search grounding ENABLED (WARNING: costs $35/1k queries)');
+		}
+
+		return opts;
 	}
 
 	// ── Chat Session Management ──────────────────────────────────────────────
@@ -344,7 +362,8 @@ class BaseGemini {
 			promptTokens: response.usageMetadata?.promptTokenCount || 0,
 			responseTokens: response.usageMetadata?.candidatesTokenCount || 0,
 			totalTokens: response.usageMetadata?.totalTokenCount || 0,
-			timestamp: Date.now()
+			timestamp: Date.now(),
+			groundingMetadata: response.candidates?.[0]?.groundingMetadata || null
 		};
 	}
 
@@ -367,7 +386,8 @@ class BaseGemini {
 			attempts: useCumulative ? cumulative.attempts : 1,
 			modelVersion: meta.modelVersion,
 			requestedModel: meta.requestedModel,
-			timestamp: meta.timestamp
+			timestamp: meta.timestamp,
+			groundingMetadata: meta.groundingMetadata || null
 		};
 	}
 
@@ -425,6 +445,112 @@ class BaseGemini {
 		};
 	}
 
+	// ── Context Caching ─────────────────────────────────────────────────────
+
+	/**
+	 * Creates a cached content resource for cost reduction on repeated prompts.
+	 * Auto-populates model and systemInstruction from this instance if not provided.
+	 * @param {Object} [config={}] - Cache configuration
+	 * @param {string} [config.model] - Model (defaults to this.modelName)
+	 * @param {string} [config.ttl] - Time-to-live (e.g., '3600s')
+	 * @param {string} [config.displayName] - Human-readable name
+	 * @param {Array} [config.contents] - Content to cache
+	 * @param {string} [config.systemInstruction] - System prompt to cache (defaults to this.systemPrompt)
+	 * @param {Array} [config.tools] - Tools to cache
+	 * @param {Object} [config.toolConfig] - Tool configuration to cache
+	 * @returns {Promise<Object>} The created cache resource
+	 */
+	async createCache(config = {}) {
+		const cacheConfig = {};
+		if (config.ttl) cacheConfig.ttl = config.ttl;
+		if (config.displayName) cacheConfig.displayName = config.displayName;
+		if (config.contents) cacheConfig.contents = config.contents;
+		if (config.tools) cacheConfig.tools = config.tools;
+		if (config.toolConfig) cacheConfig.toolConfig = config.toolConfig;
+
+		// Auto-populate systemInstruction from instance if not provided
+		const sysInstruction = config.systemInstruction !== undefined ? config.systemInstruction : this.systemPrompt;
+		if (sysInstruction) cacheConfig.systemInstruction = sysInstruction;
+
+		const cached = await this.genAIClient.caches.create({
+			model: config.model || this.modelName,
+			config: cacheConfig
+		});
+
+		log.debug(`Cache created: ${cached.name}`);
+		return cached;
+	}
+
+	/**
+	 * Retrieves a cached content resource by name.
+	 * @param {string} cacheName - Server-generated resource name
+	 * @returns {Promise<Object>} The cached content resource
+	 */
+	async getCache(cacheName) {
+		return await this.genAIClient.caches.get({ name: cacheName });
+	}
+
+	/**
+	 * Lists all cached content resources.
+	 * @returns {Promise<Object>} Pager of cached content resources
+	 */
+	async listCaches() {
+		const pager = await this.genAIClient.caches.list();
+		const results = [];
+		for await (const cache of pager) {
+			results.push(cache);
+		}
+		return results;
+	}
+
+	/**
+	 * Updates a cached content resource (TTL or expiration).
+	 * @param {string} cacheName - Server-generated resource name
+	 * @param {Object} [config={}] - Update config
+	 * @param {string} [config.ttl] - New TTL (e.g., '7200s')
+	 * @param {string} [config.expireTime] - New expiration (RFC 3339)
+	 * @returns {Promise<Object>} The updated cache resource
+	 */
+	async updateCache(cacheName, config = {}) {
+		return await this.genAIClient.caches.update({
+			name: cacheName,
+			config: {
+				...(config.ttl && { ttl: config.ttl }),
+				...(config.expireTime && { expireTime: config.expireTime })
+			}
+		});
+	}
+
+	/**
+	 * Deletes a cached content resource.
+	 * Clears this.cachedContent if it matches the deleted cache.
+	 * @param {string} cacheName - Server-generated resource name
+	 * @returns {Promise<void>}
+	 */
+	async deleteCache(cacheName) {
+		await this.genAIClient.caches.delete({ name: cacheName });
+		log.debug(`Cache deleted: ${cacheName}`);
+		if (this.cachedContent === cacheName) {
+			this.cachedContent = null;
+		}
+	}
+
+	/**
+	 * Sets the cached content for this instance and reinitializes the session.
+	 * @param {string} cacheName - Server-generated cache resource name
+	 * @returns {Promise<void>}
+	 */
+	async useCache(cacheName) {
+		this.cachedContent = cacheName;
+		// When using cached content, remove systemInstruction from chatConfig
+		// since it's already baked into the cache — the API rejects duplicates
+		delete this.chatConfig.systemInstruction;
+		if (this.chatSession) {
+			await this.init(true);
+		}
+		log.debug(`Using cache: ${cacheName}`);
+	}
+
 	// ── Private Helpers ──────────────────────────────────────────────────────
 
 	/**

package/index.cjs

@@ -32,6 +32,7 @@ __export(index_exports, {
   BaseGemini: () => base_default,
   Chat: () => chat_default,
   CodeAgent: () => code_agent_default,
+  Embedding: () => Embedding,
   HarmBlockThreshold: () => import_genai2.HarmBlockThreshold,
   HarmCategory: () => import_genai2.HarmCategory,
   Message: () => message_default,
@@ -310,7 +311,7 @@ function extractJSON(text) {
 }
 
 // base.js
-import_dotenv.default.config();
+import_dotenv.default.config({ quiet: true });
 var { NODE_ENV = "unknown", LOG_LEVEL = "" } = process.env;
 var DEFAULT_SAFETY_SETTINGS = [
   { category: import_genai.HarmCategory.HARM_CATEGORY_HARASSMENT, threshold: import_genai.HarmBlockThreshold.BLOCK_NONE },
@@ -335,7 +336,8 @@ var MODEL_PRICING = {
   "gemini-3-pro": { input: 2, output: 12 },
   "gemini-3-pro-preview": { input: 2, output: 12 },
   "gemini-2.0-flash": { input: 0.1, output: 0.4 },
-  "gemini-2.0-flash-lite": { input: 0.02, output: 0.1 }
+  "gemini-2.0-flash-lite": { input: 0.02, output: 0.1 },
+  "gemini-embedding-001": { input: 6e-3, output: 0 }
 };
 var BaseGemini = class {
   /**
@@ -361,6 +363,9 @@ var BaseGemini = class {
     }
     this._configureLogLevel(options.logLevel);
     this.labels = options.labels || {};
+    this.enableGrounding = options.enableGrounding || false;
+    this.groundingConfig = options.groundingConfig || {};
+    this.cachedContent = options.cachedContent || null;
     this.chatConfig = {
       temperature: 0.7,
       topP: 0.95,
@@ -433,14 +438,21 @@ var BaseGemini = class {
    * @protected
    */
   _getChatCreateOptions() {
-    return {
+    const opts = {
       model: this.modelName,
       config: {
         ...this.chatConfig,
-        ...this.vertexai && Object.keys(this.labels).length > 0 && { labels: this.labels }
+        ...this.vertexai && Object.keys(this.labels).length > 0 && { labels: this.labels },
+        ...this.cachedContent && { cachedContent: this.cachedContent }
       },
       history: []
     };
+    if (this.enableGrounding) {
+      const existingTools = opts.config.tools || [];
+      opts.config.tools = [...existingTools, { googleSearch: this.groundingConfig }];
+      logger_default.debug("Search grounding ENABLED (WARNING: costs $35/1k queries)");
+    }
+    return opts;
   }
   // ── Chat Session Management ──────────────────────────────────────────────
   /**
@@ -562,7 +574,8 @@ ${contextText}
       promptTokens: response.usageMetadata?.promptTokenCount || 0,
       responseTokens: response.usageMetadata?.candidatesTokenCount || 0,
       totalTokens: response.usageMetadata?.totalTokenCount || 0,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      groundingMetadata: response.candidates?.[0]?.groundingMetadata || null
     };
   }
   /**
@@ -582,7 +595,8 @@ ${contextText}
       attempts: useCumulative ? cumulative.attempts : 1,
       modelVersion: meta.modelVersion,
       requestedModel: meta.requestedModel,
-      timestamp: meta.timestamp
+      timestamp: meta.timestamp,
+      groundingMetadata: meta.groundingMetadata || null
     };
   }
   // ── Token Estimation ─────────────────────────────────────────────────────
@@ -627,6 +641,99 @@ ${contextText}
       note: "Cost is for input tokens only; output cost depends on response length"
     };
   }
+  // ── Context Caching ─────────────────────────────────────────────────────
+  /**
+   * Creates a cached content resource for cost reduction on repeated prompts.
+   * Auto-populates model and systemInstruction from this instance if not provided.
+   * @param {Object} [config={}] - Cache configuration
+   * @param {string} [config.model] - Model (defaults to this.modelName)
+   * @param {string} [config.ttl] - Time-to-live (e.g., '3600s')
+   * @param {string} [config.displayName] - Human-readable name
+   * @param {Array} [config.contents] - Content to cache
+   * @param {string} [config.systemInstruction] - System prompt to cache (defaults to this.systemPrompt)
+   * @param {Array} [config.tools] - Tools to cache
+   * @param {Object} [config.toolConfig] - Tool configuration to cache
+   * @returns {Promise<Object>} The created cache resource
+   */
+  async createCache(config = {}) {
+    const cacheConfig = {};
+    if (config.ttl) cacheConfig.ttl = config.ttl;
+    if (config.displayName) cacheConfig.displayName = config.displayName;
+    if (config.contents) cacheConfig.contents = config.contents;
+    if (config.tools) cacheConfig.tools = config.tools;
+    if (config.toolConfig) cacheConfig.toolConfig = config.toolConfig;
+    const sysInstruction = config.systemInstruction !== void 0 ? config.systemInstruction : this.systemPrompt;
+    if (sysInstruction) cacheConfig.systemInstruction = sysInstruction;
+    const cached = await this.genAIClient.caches.create({
+      model: config.model || this.modelName,
+      config: cacheConfig
+    });
+    logger_default.debug(`Cache created: ${cached.name}`);
+    return cached;
+  }
+  /**
+   * Retrieves a cached content resource by name.
+   * @param {string} cacheName - Server-generated resource name
+   * @returns {Promise<Object>} The cached content resource
+   */
+  async getCache(cacheName) {
+    return await this.genAIClient.caches.get({ name: cacheName });
+  }
+  /**
+   * Lists all cached content resources.
+   * @returns {Promise<Object>} Pager of cached content resources
+   */
+  async listCaches() {
+    const pager = await this.genAIClient.caches.list();
+    const results = [];
+    for await (const cache of pager) {
+      results.push(cache);
+    }
+    return results;
+  }
+  /**
+   * Updates a cached content resource (TTL or expiration).
+   * @param {string} cacheName - Server-generated resource name
+   * @param {Object} [config={}] - Update config
+   * @param {string} [config.ttl] - New TTL (e.g., '7200s')
+   * @param {string} [config.expireTime] - New expiration (RFC 3339)
+   * @returns {Promise<Object>} The updated cache resource
+   */
+  async updateCache(cacheName, config = {}) {
+    return await this.genAIClient.caches.update({
+      name: cacheName,
+      config: {
+        ...config.ttl && { ttl: config.ttl },
+        ...config.expireTime && { expireTime: config.expireTime }
+      }
+    });
+  }
+  /**
+   * Deletes a cached content resource.
+   * Clears this.cachedContent if it matches the deleted cache.
+   * @param {string} cacheName - Server-generated resource name
+   * @returns {Promise<void>}
+   */
+  async deleteCache(cacheName) {
+    await this.genAIClient.caches.delete({ name: cacheName });
+    logger_default.debug(`Cache deleted: ${cacheName}`);
+    if (this.cachedContent === cacheName) {
+      this.cachedContent = null;
+    }
+  }
+  /**
+   * Sets the cached content for this instance and reinitializes the session.
+   * @param {string} cacheName - Server-generated cache resource name
+   * @returns {Promise<void>}
+   */
+  async useCache(cacheName) {
+    this.cachedContent = cacheName;
+    delete this.chatConfig.systemInstruction;
+    if (this.chatSession) {
+      await this.init(true);
+    }
+    logger_default.debug(`Using cache: ${cacheName}`);
+  }
   // ── Private Helpers ──────────────────────────────────────────────────────
   /**
    * Configures the log level based on options, env vars, or NODE_ENV.
@@ -722,20 +829,8 @@ var Transformer = class extends base_default {
     this.asyncValidator = options.asyncValidator || null;
     this.maxRetries = options.maxRetries || 3;
     this.retryDelay = options.retryDelay || 1e3;
-    this.enableGrounding = options.enableGrounding || false;
-    this.groundingConfig = options.groundingConfig || {};
     logger_default.debug(`Transformer keys \u2014 Source: "${this.promptKey}", Target: "${this.answerKey}", Context: "${this.contextKey}"`);
   }
-  // ── Chat Create Options Override ──────────────────────────────────────────
-  /** @protected */
-  _getChatCreateOptions() {
-    const opts = super._getChatCreateOptions();
-    if (this.enableGrounding) {
-      opts.config.tools = [{ googleSearch: this.groundingConfig }];
-      logger_default.debug(`Search grounding ENABLED (WARNING: costs $35/1k queries)`);
-    }
-    return opts;
-  }
   // ── Seeding ──────────────────────────────────────────────────────────────
   /**
    * Seeds the chat with transformation examples using the configured key mapping.
@@ -2221,14 +2316,152 @@ ${serialized}` });
 };
 var rag_agent_default = RagAgent;
 
+// embedding.js
+var Embedding = class extends base_default {
+  /**
+   * @param {import('./types.d.ts').EmbeddingOptions} [options={}]
+   */
+  constructor(options = {}) {
+    if (options.modelName === void 0) {
+      options = { ...options, modelName: "gemini-embedding-001" };
+    }
+    if (options.systemPrompt === void 0) {
+      options = { ...options, systemPrompt: null };
+    }
+    super(options);
+    this.taskType = options.taskType || null;
+    this.title = options.title || null;
+    this.outputDimensionality = options.outputDimensionality || null;
+    this.autoTruncate = options.autoTruncate ?? true;
+    logger_default.debug(`Embedding created with model: ${this.modelName}`);
+  }
+  /**
+   * Initialize the Embedding client.
+   * Override: validates API connection only, NO chat session (stateless).
+   * @param {boolean} [force=false]
+   * @returns {Promise<void>}
+   */
+  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;
+    logger_default.debug(`${this.constructor.name}: Initialized (stateless mode).`);
+  }
+  /**
+   * Builds the config object for embedContent calls.
+   * @param {Object} [overrides={}] - Per-call config overrides
+   * @returns {Object} The config object
+   * @private
+   */
+  _buildConfig(overrides = {}) {
+    const config = {};
+    const taskType = overrides.taskType || this.taskType;
+    const title = overrides.title || this.title;
+    const dims = overrides.outputDimensionality || this.outputDimensionality;
+    if (taskType) config.taskType = taskType;
+    if (title) config.title = title;
+    if (dims) config.outputDimensionality = dims;
+    return config;
+  }
+  /**
+  	 * Embed a single text string.
+  	 * @param {string} text - The text to embed
+  	 * @param {Object} [config={}] - Per-call config overrides
+  	 * @param {string} [config.taskType] - Override task type
+  	 * @param {string} [config.title] - Override title
+  	 * @param {number} [config.outputDimensionality] - Override dimensions
+  
+  	 * @returns {Promise<import('./types.d.ts').EmbeddingResult>} The embedding result
+  	 */
+  async embed(text, config = {}) {
+    if (!this._initialized) await this.init();
+    const result = await this.genAIClient.models.embedContent({
+      model: this.modelName,
+      contents: text,
+      config: this._buildConfig(config)
+    });
+    return result.embeddings[0];
+  }
+  /**
+  	 * Embed multiple text strings in a single API call.
+  	 * @param {string[]} texts - Array of texts to embed
+  	 * @param {Object} [config={}] - Per-call config overrides
+  	 * @param {string} [config.taskType] - Override task type
+  	 * @param {string} [config.title] - Override title
+  	 * @param {number} [config.outputDimensionality] - Override dimensions
+  
+  	 * @returns {Promise<import('./types.d.ts').EmbeddingResult[]>} Array of embedding results
+  	 */
+  async embedBatch(texts, config = {}) {
+    if (!this._initialized) await this.init();
+    const result = await this.genAIClient.models.embedContent({
+      model: this.modelName,
+      contents: texts,
+      config: this._buildConfig(config)
+    });
+    return result.embeddings;
+  }
+  /**
+   * Compute cosine similarity between two embedding vectors.
+   * Pure math — no API call.
+   * @param {number[]} a - First embedding vector
+   * @param {number[]} b - Second embedding vector
+   * @returns {number} Cosine similarity between -1 and 1
+   */
+  similarity(a, b) {
+    if (!a || !b || a.length !== b.length) {
+      throw new Error("Vectors must be non-null and have the same length");
+    }
+    let dot = 0;
+    let magA = 0;
+    let magB = 0;
+    for (let i = 0; i < a.length; i++) {
+      dot += a[i] * b[i];
+      magA += a[i] * a[i];
+      magB += b[i] * b[i];
+    }
+    const magnitude = Math.sqrt(magA) * Math.sqrt(magB);
+    if (magnitude === 0) return 0;
+    return dot / magnitude;
+  }
+  // ── No-ops (embeddings don't use chat sessions) ──
+  /** @returns {any[]} Always returns empty array */
+  getHistory() {
+    return [];
+  }
+  /** No-op for Embedding */
+  async clearHistory() {
+  }
+  /** No-op for Embedding */
+  async seed() {
+    logger_default.warn("Embedding.seed() is a no-op \u2014 embeddings do not support few-shot examples.");
+    return [];
+  }
+  /**
+   * @param {any} _nextPayload
+   * @throws {Error} Embedding does not support token estimation
+   * @returns {Promise<{inputTokens: number}>}
+   */
+  async estimate(_nextPayload) {
+    throw new Error("Embedding does not support token estimation. Use embed() 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 };
+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 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BaseGemini,
   Chat,
   CodeAgent,
+  Embedding,
   HarmBlockThreshold,
   HarmCategory,
   Message,