ak-gemini 2.0.2 → 2.0.3

package/GUIDE.md

@@ -22,12 +22,15 @@ npm install ak-gemini
 7. [ToolAgent — Agent with Custom Tools](#toolagent--agent-with-custom-tools)
 8. [CodeAgent — Agent That Writes and Runs Code](#codeagent--agent-that-writes-and-runs-code)
 9. [RagAgent — Document & Data Q&A](#ragagent--document--data-qa)
-10. [Observability & Usage Tracking](#observability--usage-tracking)
-11. [Thinking Configuration](#thinking-configuration)
-12. [Error Handling & Retries](#error-handling--retries)
-13. [Performance Tips](#performance-tips)
-14. [Common Integration Patterns](#common-integration-patterns)
-15. [Quick Reference](#quick-reference)
+10. [Embedding — Vector Embeddings](#embedding--vector-embeddings)
+11. [Google Search Grounding](#google-search-grounding)
+12. [Context Caching](#context-caching)
+13. [Observability & Usage Tracking](#observability--usage-tracking)
+14. [Thinking Configuration](#thinking-configuration)
+15. [Error Handling & Retries](#error-handling--retries)
+16. [Performance Tips](#performance-tips)
+17. [Common Integration Patterns](#common-integration-patterns)
+18. [Quick Reference](#quick-reference)
 
 ---
 
@@ -96,6 +99,7 @@ Vertex AI uses Application Default Credentials. Run `gcloud auth application-def
 | Give the AI tools to call (APIs, DB, etc.) | `ToolAgent` | `chat()` / `stream()` |
 | Let the AI write and run JavaScript | `CodeAgent` | `chat()` / `stream()` |
 | Q&A over documents, files, or data | `RagAgent` | `chat()` / `stream()` |
+| Generate vector embeddings | `Embedding` | `embed()` / `embedBatch()` |
 
 **Rule of thumb**: Start with `Message` for the simplest integration. Move to `Chat` if you need history. Use `Transformer` when you need structured JSON output with validation. Use agents when the AI needs to take action.
 
@@ -570,6 +574,313 @@ Prefer `localFiles` and `localData` when possible — they skip the upload step
 
 ---
 
+## Embedding — Vector Embeddings
+
+Generate vector embeddings for similarity search, clustering, classification, and deduplication. The `Embedding` class uses Google's text embedding models and provides a simple API for single and batch operations.
+
+```javascript
+import { Embedding } from 'ak-gemini';
+
+const embedder = new Embedding({
+  modelName: 'gemini-embedding-001', // default
+});
+```
+
+### Basic Embedding
+
+```javascript
+const result = await embedder.embed('The quick brown fox jumps over the lazy dog');
+console.log(result.values);      // [0.012, -0.034, 0.056, ...] — 768 dimensions by default
+console.log(result.values.length); // 768
+```
+
+### Batch Embedding
+
+Embed multiple texts in a single API call for efficiency:
+
+```javascript
+const texts = [
+  'Machine learning fundamentals',
+  'Deep neural networks',
+  'How to bake sourdough bread',
+];
+
+const results = await embedder.embedBatch(texts);
+// results[0].values, results[1].values, results[2].values
+```
+
+### Task Types
+
+Task types optimize embeddings for specific use cases:
+
+```javascript
+// For documents being indexed
+const docEmbedder = new Embedding({
+  taskType: 'RETRIEVAL_DOCUMENT',
+  title: 'API Reference'  // title only applies to RETRIEVAL_DOCUMENT
+});
+
+// For search queries against those documents
+const queryEmbedder = new Embedding({
+  taskType: 'RETRIEVAL_QUERY'
+});
+
+// Other task types
+new Embedding({ taskType: 'SEMANTIC_SIMILARITY' });
+new Embedding({ taskType: 'CLUSTERING' });
+new Embedding({ taskType: 'CLASSIFICATION' });
+```
+
+**Best practice**: Use `RETRIEVAL_DOCUMENT` when embedding content to store, and `RETRIEVAL_QUERY` when embedding the user's search query.
+
+### Output Dimensionality
+
+Reduce embedding dimensions to save storage space (trade-off with accuracy):
+
+```javascript
+// Constructor-level
+const embedder = new Embedding({ outputDimensionality: 256 });
+
+// Per-call override
+const result = await embedder.embed('Hello', { outputDimensionality: 128 });
+console.log(result.values.length); // 128
+```
+
+Supported by `gemini-embedding-001` (not `text-embedding-001`).
+
+### Cosine Similarity
+
+Compare two embeddings without an API call:
+
+```javascript
+const [a, b] = await Promise.all([
+  embedder.embed('cats are great pets'),
+  embedder.embed('dogs are wonderful companions'),
+]);
+
+const score = embedder.similarity(a.values, b.values);
+// score ≈ 0.85 (semantically similar)
+```
+
+Returns a value between -1 (opposite) and 1 (identical). Typical thresholds:
+- `> 0.8` — very similar
+- `0.5–0.8` — somewhat related
+- `< 0.5` — different topics
+
+### Integration Pattern: Semantic Search
+
+```javascript
+// Index phase
+const documents = ['doc1 text...', 'doc2 text...', 'doc3 text...'];
+const docEmbedder = new Embedding({ taskType: 'RETRIEVAL_DOCUMENT' });
+const docVectors = await docEmbedder.embedBatch(documents);
+
+// Search phase
+const queryEmbedder = new Embedding({ taskType: 'RETRIEVAL_QUERY' });
+const queryVector = await queryEmbedder.embed('how do I authenticate?');
+
+// Find best match
+const scores = docVectors.map((doc, i) => ({
+  index: i,
+  score: queryEmbedder.similarity(queryVector.values, doc.values)
+}));
+scores.sort((a, b) => b.score - a.score);
+console.log('Best match:', documents[scores[0].index]);
+```
+
+### When to Use Embedding
+
+- Semantic search — find documents similar to a query
+- Deduplication — detect near-duplicate content
+- Clustering — group similar items together
+- Classification — compare against known category embeddings
+- Recommendation — find items similar to user preferences
+
+---
+
+## Google Search Grounding
+
+Ground model responses in real-time Google Search results. Available on **all classes** via `enableGrounding` — not just Transformer.
+
+**Warning**: Google Search grounding costs approximately **$35 per 1,000 queries**. Use selectively.
+
+### Basic Usage
+
+```javascript
+import { Chat } from 'ak-gemini';
+
+const chat = new Chat({
+  enableGrounding: true
+});
+
+const result = await chat.send('What happened in tech news today?');
+console.log(result.text); // Response grounded in current search results
+```
+
+### Grounding Metadata
+
+When grounding is enabled, `getLastUsage()` includes source attribution:
+
+```javascript
+const usage = chat.getLastUsage();
+
+if (usage.groundingMetadata) {
+  // Search queries the model executed
+  console.log('Queries:', usage.groundingMetadata.webSearchQueries);
+
+  // Source citations
+  for (const chunk of usage.groundingMetadata.groundingChunks || []) {
+    if (chunk.web) {
+      console.log(`Source: ${chunk.web.title} — ${chunk.web.uri}`);
+    }
+  }
+}
+```
+
+### Grounding Configuration
+
+```javascript
+const chat = new Chat({
+  enableGrounding: true,
+  groundingConfig: {
+    // Exclude specific domains
+    excludeDomains: ['reddit.com', 'twitter.com'],
+
+    // Filter by time range (Gemini API only)
+    timeRangeFilter: {
+      startTime: '2025-01-01T00:00:00Z',
+      endTime: '2025-12-31T23:59:59Z'
+    }
+  }
+});
+```
+
+### Grounding with ToolAgent
+
+Grounding works alongside user-defined tools — both are merged into the tools array automatically:
+
+```javascript
+const agent = new ToolAgent({
+  enableGrounding: true,
+  tools: [
+    { name: 'save_result', description: 'Save a research result', parametersJsonSchema: { type: 'object', properties: { title: { type: 'string' }, summary: { type: 'string' } }, required: ['title', 'summary'] } }
+  ],
+  toolExecutor: async (name, args) => {
+    if (name === 'save_result') return await db.insert(args);
+  }
+});
+
+// The agent can search the web AND call your tools
+const result = await agent.chat('Research the latest AI safety developments and save the key findings');
+```
+
+### Per-Message Grounding Toggle (Transformer)
+
+Transformer supports toggling grounding per-message without rebuilding the instance:
+
+```javascript
+const t = new Transformer({ enableGrounding: false });
+
+// Enable grounding for just this call
+const result = await t.send(payload, { enableGrounding: true });
+
+// Back to no grounding for subsequent calls
+```
+
+### When to Use Grounding
+
+- Questions about current events, recent news, or real-time data
+- Fact-checking or verification tasks
+- Research assistants that need up-to-date information
+- Any scenario where the model's training data cutoff is a limitation
+
+---
+
+## Context Caching
+
+Cache system prompts, documents, or tool definitions to reduce costs when making many API calls with the same large context. Cached tokens are billed at a reduced rate.
+
+### When Context Caching Helps
+
+- **Large system prompts** reused across many calls
+- **RagAgent** with the same document set serving many queries
+- **ToolAgent** with many tool definitions
+- Any scenario with high token count in repeated context
+
+### Create and Use a Cache
+
+```javascript
+import { Chat } from 'ak-gemini';
+
+const chat = new Chat({
+  systemPrompt: veryLongSystemPrompt  // e.g., 10,000+ tokens
+});
+
+// Create a cache (auto-uses this instance's model and systemPrompt)
+const cache = await chat.createCache({
+  ttl: '3600s',           // 1 hour
+  displayName: 'my-app-system-prompt'
+});
+
+console.log(cache.name);       // Server-generated resource name
+console.log(cache.expireTime); // When it expires
+
+// Attach the cache to this instance
+await chat.useCache(cache.name);
+
+// All subsequent calls use cached tokens at reduced cost
+const r1 = await chat.send('Hello');
+const r2 = await chat.send('Tell me more');
+```
+
+### Cache Management
+
+```javascript
+// List all caches
+const caches = await chat.listCaches();
+
+// Get cache details
+const info = await chat.getCache(cache.name);
+console.log(info.usageMetadata?.totalTokenCount);
+
+// Extend TTL
+await chat.updateCache(cache.name, { ttl: '7200s' });
+
+// Delete when done
+await chat.deleteCache(cache.name);
+```
+
+### Cache with Constructor
+
+If you already have a cache name, pass it directly:
+
+```javascript
+const chat = new Chat({
+  cachedContent: 'projects/my-project/locations/us-central1/cachedContents/abc123'
+});
+```
+
+### What Can Be Cached
+
+The `createCache()` config accepts:
+
+| Field | Description |
+|---|---|
+| `systemInstruction` | System prompt (auto-populated from instance if not provided) |
+| `contents` | Content messages to cache |
+| `tools` | Tool declarations to cache |
+| `toolConfig` | Tool configuration to cache |
+| `ttl` | Time-to-live (e.g., `'3600s'`) |
+| `displayName` | Human-readable label |
+
+### Cost Savings
+
+Context caching reduces input token costs for cached content. The exact savings depend on the model — check [Google's pricing page](https://ai.google.dev/pricing) for current rates. The trade-off is the cache storage cost and the minimum cache size requirement.
+
+**Rule of thumb**: Caching pays off when you make many calls with the same large context (system prompt + documents) within the cache TTL.
+
+---
+
 ## Observability & Usage Tracking
 
 Every class provides consistent observability hooks.
@@ -954,7 +1265,7 @@ const result = await chat.send('Find users who signed up in the last 7 days');
 
 ```javascript
 // Named exports
-import { Transformer, Chat, Message, ToolAgent, CodeAgent, RagAgent, BaseGemini, log } from 'ak-gemini';
+import { Transformer, Chat, Message, ToolAgent, CodeAgent, RagAgent, Embedding, BaseGemini, log } from 'ak-gemini';
 import { extractJSON, attemptJSONRecovery } from 'ak-gemini';
 import { ThinkingLevel, HarmCategory, HarmBlockThreshold } from 'ak-gemini';
 
@@ -962,7 +1273,7 @@ import { ThinkingLevel, HarmCategory, HarmBlockThreshold } from 'ak-gemini';
 import AI from 'ak-gemini';
 
 // CommonJS
-const { Transformer, Chat } = require('ak-gemini');
+const { Transformer, Chat, Embedding } = require('ak-gemini');
 ```
 
 ### Constructor Options (All Classes)
@@ -980,6 +1291,9 @@ const { Transformer, Chat } = require('ak-gemini');
 | `maxOutputTokens` | number \| null | `50000` |
 | `logLevel` | string | based on `NODE_ENV` |
 | `labels` | object | `{}` (Vertex AI only) |
+| `enableGrounding` | boolean | `false` |
+| `groundingConfig` | object | `{}` |
+| `cachedContent` | string | `null` |
 
 ### Methods Available on All Classes
 
@@ -992,3 +1306,9 @@ const { Transformer, Chat } = require('ak-gemini');
 | `getLastUsage()` | `UsageData \| null` | Token usage from last call |
 | `estimate(payload)` | `Promise<{ inputTokens }>` | Estimate input tokens |
 | `estimateCost(payload)` | `Promise<object>` | Estimate cost in dollars |
+| `createCache(config?)` | `Promise<CachedContentInfo>` | Create a context cache |
+| `getCache(name)` | `Promise<CachedContentInfo>` | Get cache details |
+| `listCaches()` | `Promise<any>` | List all caches |
+| `updateCache(name, config?)` | `Promise<CachedContentInfo>` | Update cache TTL |
+| `deleteCache(name)` | `Promise<void>` | Delete a cache |
+| `useCache(name)` | `Promise<void>` | Attach a cache to this instance |

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,

package/index.js

@@ -26,6 +26,7 @@ export { default as Message } from './message.js';
 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 BaseGemini } from './base.js';
 export { default as log } from './logger.js';
 export { ThinkingLevel, HarmCategory, HarmBlockThreshold } from '@google/genai';
@@ -39,5 +40,6 @@ import Message from './message.js';
 import ToolAgent from './tool-agent.js';
 import CodeAgent from './code-agent.js';
 import RagAgent from './rag-agent.js';
+import Embedding from './embedding.js';
 
-export default { Transformer, Chat, Message, ToolAgent, CodeAgent, RagAgent };
+export default { Transformer, Chat, Message, ToolAgent, CodeAgent, RagAgent, Embedding };

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.0.2",
+	"version": "2.0.3",
 	"main": "index.js",
 	"files": [
 		"index.js",

package/transformer.js

@@ -96,27 +96,9 @@ class Transformer extends BaseGemini {
 		this.maxRetries = options.maxRetries || 3;
 		this.retryDelay = options.retryDelay || 1000;
 
-		// ── Grounding ──
-		this.enableGrounding = options.enableGrounding || false;
-		this.groundingConfig = options.groundingConfig || {};
-
 		log.debug(`Transformer keys — 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 }];
-			log.debug(`Search grounding ENABLED (WARNING: costs $35/1k queries)`);
-		}
-
-		return opts;
-	}
-
 	// ── Seeding ──────────────────────────────────────────────────────────────
 
 	/**

package/types.d.ts

@@ -32,6 +32,23 @@ export interface ChatConfig {
   [key: string]: any;
 }
 
+export interface GroundingChunk {
+  web?: { uri?: string; title?: string; domain?: string };
+}
+
+export interface GroundingSupport {
+  segment?: any;
+  groundingChunkIndices?: number[];
+  confidenceScores?: number[];
+}
+
+export interface GroundingMetadata {
+  groundingChunks?: GroundingChunk[];
+  groundingSupports?: GroundingSupport[];
+  webSearchQueries?: string[];
+  searchEntryPoint?: { renderedContent?: string };
+}
+
 export interface ResponseMetadata {
   modelVersion: string | null;
   requestedModel: string;
@@ -39,6 +56,7 @@ export interface ResponseMetadata {
   responseTokens: number;
   totalTokens: number;
   timestamp: number;
+  groundingMetadata?: GroundingMetadata | null;
 }
 
 export interface UsageData {
@@ -55,6 +73,7 @@ export interface UsageData {
   /** Model you requested (e.g., 'gemini-2.5-flash') */
   requestedModel: string;
   timestamp: number;
+  groundingMetadata?: GroundingMetadata | null;
 }
 
 export interface TransformationExample {
@@ -77,6 +96,38 @@ export interface GoogleAuthOptions {
   universeDomain?: string;
 }
 
+export interface CacheConfig {
+  /** Model to cache for (defaults to instance modelName) */
+  model?: string;
+  /** Time-to-live duration (e.g., '3600s') */
+  ttl?: string;
+  /** Human-readable display name */
+  displayName?: string;
+  /** Content to cache */
+  contents?: any[];
+  /** System instruction to cache (defaults to instance systemPrompt) */
+  systemInstruction?: string;
+  /** Tools to cache */
+  tools?: any[];
+  /** Tool configuration to cache */
+  toolConfig?: any;
+}
+
+export interface CachedContentInfo {
+  /** Server-generated resource name */
+  name: string;
+  /** User-provided display name */
+  displayName?: string;
+  /** Model this cache is for */
+  model: string;
+  /** Creation timestamp */
+  createTime: string;
+  /** Expiration timestamp */
+  expireTime: string;
+  /** Cache usage metadata */
+  usageMetadata?: { totalTokenCount?: number };
+}
+
 export type AsyncValidatorFunction = (payload: Record<string, unknown>) => Promise<unknown>;
 export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'none';
 
@@ -110,6 +161,14 @@ export interface BaseGeminiOptions {
 
   /** Billing labels for cost segmentation (Vertex AI only) */
   labels?: Record<string, string>;
+
+  /** Enable Google Search grounding (WARNING: costs $35/1k queries) */
+  enableGrounding?: boolean;
+  /** Google Search grounding configuration (searchTypes, excludeDomains, timeRangeFilter) */
+  groundingConfig?: Record<string, any>;
+
+  /** Cached content resource name to use for this session */
+  cachedContent?: string;
 }
 
 export interface TransformerOptions extends BaseGeminiOptions {
@@ -158,6 +217,35 @@ export interface MessageOptions extends BaseGeminiOptions {
   responseMimeType?: string;
 }
 
+export type EmbeddingTaskType = 'RETRIEVAL_DOCUMENT' | 'RETRIEVAL_QUERY' | 'SEMANTIC_SIMILARITY' | 'CLUSTERING' | 'CLASSIFICATION' | 'QUESTION_ANSWERING' | 'FACT_VERIFICATION';
+
+export interface EmbeddingOptions extends BaseGeminiOptions {
+  /** Embedding task type (affects how embeddings are optimized) */
+  taskType?: EmbeddingTaskType;
+  /** Title for the document being embedded (only with RETRIEVAL_DOCUMENT) */
+  title?: string;
+  /** Output dimensionality for the embedding vector */
+  outputDimensionality?: number;
+  /** Whether to auto-truncate long inputs (default: true) */
+  autoTruncate?: boolean;
+}
+
+export interface EmbedConfig {
+  /** Override task type for this call */
+  taskType?: EmbeddingTaskType;
+  /** Override title for this call */
+  title?: string;
+  /** Override output dimensionality for this call */
+  outputDimensionality?: number;
+}
+
+export interface EmbeddingResult {
+  /** The embedding vector */
+  values?: number[];
+  /** Embedding statistics (Vertex AI) */
+  statistics?: { tokenCount?: number; truncated?: boolean };
+}
+
 /** Tool declaration in @google/genai FunctionDeclaration format */
 export interface ToolDeclaration {
   name: string;
@@ -374,6 +462,9 @@ export declare class BaseGemini {
   exampleCount: number;
   labels: Record<string, string>;
   vertexai: boolean;
+  enableGrounding: boolean;
+  groundingConfig: Record<string, any>;
+  cachedContent: string | null;
 
   init(force?: boolean): Promise<void>;
   seed(examples?: TransformationExample[], opts?: SeedOptions): Promise<any[]>;
@@ -388,6 +479,14 @@ export declare class BaseGemini {
     estimatedInputCost: number;
     note: string;
   }>;
+
+  // Context Caching
+  createCache(config?: CacheConfig): Promise<CachedContentInfo>;
+  getCache(cacheName: string): Promise<CachedContentInfo>;
+  listCaches(): Promise<CachedContentInfo[]>;
+  updateCache(cacheName: string, config?: { ttl?: string; expireTime?: string }): Promise<CachedContentInfo>;
+  deleteCache(cacheName: string): Promise<void>;
+  useCache(cacheName: string): Promise<void>;
 }
 
 export declare class Transformer extends BaseGemini {
@@ -401,8 +500,6 @@ export declare class Transformer extends BaseGemini {
   asyncValidator: AsyncValidatorFunction | null;
   maxRetries: number;
   retryDelay: number;
-  enableGrounding: boolean;
-
   seed(examples?: TransformationExample[]): Promise<any[]>;
   send(payload: Record<string, unknown> | string, opts?: SendOptions, validatorFn?: AsyncValidatorFunction | null): Promise<Record<string, unknown>>;
   rawSend(payload: Record<string, unknown> | string, messageOptions?: { labels?: Record<string, string> }): Promise<Record<string, unknown>>;
@@ -496,6 +593,23 @@ export declare class CodeAgent extends BaseGemini {
   stop(): void;
 }
 
+export declare class Embedding extends BaseGemini {
+  constructor(options?: EmbeddingOptions);
+
+  taskType: EmbeddingTaskType | null;
+  title: string | null;
+  outputDimensionality: number | null;
+  autoTruncate: boolean;
+
+  init(force?: boolean): Promise<void>;
+  /** Embed a single text string */
+  embed(text: string, config?: EmbedConfig): Promise<EmbeddingResult>;
+  /** Embed multiple text strings in a single API call */
+  embedBatch(texts: string[], config?: EmbedConfig): Promise<EmbeddingResult[]>;
+  /** Compute cosine similarity between two embedding vectors (-1 to 1) */
+  similarity(a: number[], b: number[]): number;
+}
+
 // ── Module Exports ───────────────────────────────────────────────────────────
 
 export declare function extractJSON(text: string): any;
@@ -508,6 +622,7 @@ declare const _default: {
   ToolAgent: typeof ToolAgent;
   CodeAgent: typeof CodeAgent;
   RagAgent: typeof RagAgent;
+  Embedding: typeof Embedding;
 };
 
 export default _default;