ak-gemini 1.1.0 → 1.1.11

package/README.md

@@ -152,7 +152,16 @@ new AITransformer(options)
 | retryDelay         | number | 1000               | Initial retry delay in ms (exponential backoff)   |
 | logLevel           | string | 'info'             | Log level: 'trace', 'debug', 'info', 'warn', 'error', 'fatal', or 'none' |
 | chatConfig         | object | ...                | Gemini chat config overrides                      |
-| systemInstructions | string | ...                | System prompt for Gemini                          |
+| systemInstructions | string/null/false | (default prompt) | System prompt for Gemini. Pass `null` or `false` to disable. |
+| maxOutputTokens    | number | 50000              | Maximum tokens in generated response              |
+| thinkingConfig     | object | null               | Thinking features config (see below)              |
+| enableGrounding    | boolean | false             | Enable Google Search grounding (WARNING: $35/1k queries) |
+| labels             | object | null               | Billing labels for cost attribution               |
+| apiKey             | string | env var            | Gemini API key (or use `GEMINI_API_KEY` env var)  |
+| vertexai           | boolean | false             | Use Vertex AI instead of Gemini API               |
+| project            | string | env var            | GCP project ID (for Vertex AI)                    |
+| location           | string | 'global'           | GCP region (for Vertex AI)                        |
+| googleAuthOptions  | object | null               | Auth options for Vertex AI (keyFilename, credentials) |
 
 ---
 
@@ -282,9 +291,85 @@ const result = await transformer.transformWithValidation(
 
 ---
 
+## Vertex AI Authentication
+
+Use Vertex AI instead of the Gemini API for enterprise features, VPC controls, and GCP billing integration.
+
+### With Service Account Key File
+
+```js
+const transformer = new AITransformer({
+  vertexai: true,
+  project: 'my-gcp-project',
+  location: 'us-central1',  // Optional: defaults to 'global' endpoint
+  googleAuthOptions: {
+    keyFilename: './service-account.json'
+  }
+});
+```
+
+### With Application Default Credentials
+
+```js
+// Uses GOOGLE_APPLICATION_CREDENTIALS env var or `gcloud auth application-default login`
+const transformer = new AITransformer({
+  vertexai: true,
+  project: 'my-gcp-project'  // or GOOGLE_CLOUD_PROJECT env var
+});
+```
+
+---
+
+## Advanced Configuration
+
+### Disabling System Instructions
+
+By default, the transformer uses built-in system instructions optimized for JSON transformation. You can provide custom instructions or disable them entirely:
+
+```js
+// Custom system instructions
+new AITransformer({ systemInstructions: "You are a helpful assistant..." });
+
+// Disable system instructions entirely (use Gemini's default behavior)
+new AITransformer({ systemInstructions: null });
+new AITransformer({ systemInstructions: false });
+```
+
+### Thinking Configuration
+
+For models that support extended thinking (like `gemini-2.5-flash`):
+
+```js
+const transformer = new AITransformer({
+  modelName: 'gemini-2.5-flash',
+  thinkingConfig: {
+    thinkingBudget: 1024,  // Token budget for thinking
+  }
+});
+```
+
+### Billing Labels
+
+Labels flow through to GCP billing reports for cost attribution:
+
+```js
+const transformer = new AITransformer({
+  labels: {
+    client: 'acme_corp',
+    app: 'data_pipeline',
+    environment: 'production'
+  }
+});
+
+// Override per-message
+await transformer.message(payload, { labels: { request_type: 'batch' } });
+```
+
+---
+
 ## Token Window Management & Error Handling
 
-* Throws on missing `GEMINI_API_KEY`
+* Throws on missing credentials (API key for Gemini API, or project ID for Vertex AI)
 * `.message()` and `.seed()` will *estimate* and prevent calls that would exceed Gemini's model window
 * All API and parsing errors surfaced as `Error` with context
 * Validator and retry failures include the number of attempts and last error

package/index.cjs

@@ -116,7 +116,6 @@ var AITransformer = class {
     this.systemInstructionKey = "";
     this.maxRetries = 3;
     this.retryDelay = 1e3;
-    this.systemInstructions = "";
     this.chatConfig = {};
     this.apiKey = GEMINI_API_KEY;
     this.onlyJSON = true;
@@ -152,7 +151,11 @@ var AITransformer = class {
 var index_default = AITransformer;
 function AITransformFactory(options = {}) {
   this.modelName = options.modelName || "gemini-2.5-flash";
-  this.systemInstructions = options.systemInstructions || DEFAULT_SYSTEM_INSTRUCTIONS;
+  if (options.systemInstructions === void 0) {
+    this.systemInstructions = DEFAULT_SYSTEM_INSTRUCTIONS;
+  } else {
+    this.systemInstructions = options.systemInstructions;
+  }
   if (options.logLevel) {
     this.logLevel = options.logLevel;
     if (this.logLevel === "none") {
@@ -178,7 +181,7 @@ function AITransformFactory(options = {}) {
   }
   this.vertexai = options.vertexai || false;
   this.project = options.project || process.env.GOOGLE_CLOUD_PROJECT || null;
-  this.location = options.location || process.env.GOOGLE_CLOUD_LOCATION || "us-central1";
+  this.location = options.location || process.env.GOOGLE_CLOUD_LOCATION || void 0;
   this.googleAuthOptions = options.googleAuthOptions || null;
   this.apiKey = options.apiKey !== void 0 && options.apiKey !== null ? options.apiKey : GEMINI_API_KEY;
   if (!this.vertexai && !this.apiKey) {
@@ -189,9 +192,13 @@ function AITransformFactory(options = {}) {
   }
   this.chatConfig = {
     ...DEFAULT_CHAT_CONFIG,
-    ...options.chatConfig,
-    systemInstruction: this.systemInstructions
+    ...options.chatConfig
   };
+  if (this.systemInstructions) {
+    this.chatConfig.systemInstruction = this.systemInstructions;
+  } else if (options.systemInstructions !== void 0) {
+    delete this.chatConfig.systemInstruction;
+  }
   if (options.maxOutputTokens !== void 0) {
     if (options.maxOutputTokens === null) {
       delete this.chatConfig.maxOutputTokens;
@@ -249,7 +256,11 @@ function AITransformFactory(options = {}) {
   this.groundingConfig = options.groundingConfig || {};
   this.labels = options.labels || {};
   if (Object.keys(this.labels).length > 0 && logger_default.level !== "silent") {
-    logger_default.debug(`Billing labels configured: ${JSON.stringify(this.labels)}`);
+    if (!this.vertexai) {
+      logger_default.warn(`Billing labels are only supported with Vertex AI. Labels will be ignored.`);
+    } else {
+      logger_default.debug(`Billing labels configured: ${JSON.stringify(this.labels)}`);
+    }
   }
   if (this.promptKey === this.answerKey) {
     throw new Error("Source and target keys cannot be the same. Please provide distinct keys.");
@@ -259,7 +270,7 @@ function AITransformFactory(options = {}) {
     logger_default.debug(`Using keys - Source: "${this.promptKey}", Target: "${this.answerKey}", Context: "${this.contextKey}"`);
     logger_default.debug(`Max output tokens set to: ${this.chatConfig.maxOutputTokens}`);
     if (this.vertexai) {
-      logger_default.debug(`Using Vertex AI - Project: ${this.project}, Location: ${this.location}`);
+      logger_default.debug(`Using Vertex AI - Project: ${this.project}, Location: ${this.location || "global (default)"}`);
       if (this.googleAuthOptions?.keyFilename) {
         logger_default.debug(`Auth: Service account key file: ${this.googleAuthOptions.keyFilename}`);
       } else if (this.googleAuthOptions?.credentials) {
@@ -275,7 +286,7 @@ function AITransformFactory(options = {}) {
   const clientOptions = this.vertexai ? {
     vertexai: true,
     project: this.project,
-    location: this.location,
+    ...this.location && { location: this.location },
     ...this.googleAuthOptions && { googleAuthOptions: this.googleAuthOptions }
   } : { apiKey: this.apiKey };
   const ai = new import_genai.GoogleGenAI(clientOptions);
@@ -290,7 +301,7 @@ async function initChat(force = false) {
     // @ts-ignore
     config: {
       ...this.chatConfig,
-      ...Object.keys(this.labels).length > 0 && { labels: this.labels }
+      ...this.vertexai && Object.keys(this.labels).length > 0 && { labels: this.labels }
     },
     history: []
   };
@@ -373,7 +384,7 @@ ${contextText}
     // @ts-ignore
     config: {
       ...this.chatConfig,
-      ...Object.keys(this.labels).length > 0 && { labels: this.labels }
+      ...this.vertexai && Object.keys(this.labels).length > 0 && { labels: this.labels }
     },
     history: [...currentHistory, ...historyToAdd]
   });
@@ -388,7 +399,7 @@ async function rawMessage(sourcePayload, messageOptions = {}) {
   }
   const actualPayload = typeof sourcePayload === "string" ? sourcePayload : JSON.stringify(sourcePayload, null, 2);
   const mergedLabels = { ...this.labels, ...messageOptions.labels || {} };
-  const hasLabels = Object.keys(mergedLabels).length > 0;
+  const hasLabels = this.vertexai && Object.keys(mergedLabels).length > 0;
   try {
     const sendParams = { message: actualPayload };
     if (hasLabels) {
@@ -603,7 +614,7 @@ async function resetChat() {
       // @ts-ignore
       config: {
         ...this.chatConfig,
-        ...Object.keys(this.labels).length > 0 && { labels: this.labels }
+        ...this.vertexai && Object.keys(this.labels).length > 0 && { labels: this.labels }
       },
       history: []
     };
@@ -647,7 +658,7 @@ async function clearConversation() {
     // @ts-ignore
     config: {
       ...this.chatConfig,
-      ...Object.keys(this.labels).length > 0 && { labels: this.labels }
+      ...this.vertexai && Object.keys(this.labels).length > 0 && { labels: this.labels }
     },
     history: exampleHistory
   });
@@ -701,7 +712,7 @@ async function statelessMessage(sourcePayload, options = {}, validatorFn = null)
     contents,
     config: {
       ...this.chatConfig,
-      ...Object.keys(mergedLabels).length > 0 && { labels: mergedLabels }
+      ...this.vertexai && Object.keys(mergedLabels).length > 0 && { labels: mergedLabels }
     }
   });
   this.lastResponseMetadata = {

package/index.js

@@ -106,7 +106,7 @@ class AITransformer {
 		this.systemInstructionKey = "";
 		this.maxRetries = 3;
 		this.retryDelay = 1000;
-		this.systemInstructions = "";
+		// this.systemInstructions = "";
 		this.chatConfig = {};
 		this.apiKey = GEMINI_API_KEY;
 		this.onlyJSON = true; // always return JSON
@@ -160,7 +160,14 @@ export { attemptJSONRecovery }; // Export for testing
 function AITransformFactory(options = {}) {
 	// ? https://ai.google.dev/gemini-api/docs/models
 	this.modelName = options.modelName || 'gemini-2.5-flash';
-	this.systemInstructions = options.systemInstructions || DEFAULT_SYSTEM_INSTRUCTIONS;
+
+	// Only use default if systemInstructions was not provided at all
+	if (options.systemInstructions === undefined) {
+		this.systemInstructions = DEFAULT_SYSTEM_INSTRUCTIONS;
+	} else {
+		// Use the provided value (could be null, false, or a custom string)
+		this.systemInstructions = options.systemInstructions;
+	}
 
 	// Configure log level - priority: options.logLevel > LOG_LEVEL env > NODE_ENV based defaults > 'info'
 	if (options.logLevel) {
@@ -194,7 +201,7 @@ function AITransformFactory(options = {}) {
 	// Vertex AI configuration
 	this.vertexai = options.vertexai || false;
 	this.project = options.project || process.env.GOOGLE_CLOUD_PROJECT || null;
-	this.location = options.location || process.env.GOOGLE_CLOUD_LOCATION || 'us-central1';
+	this.location = options.location || process.env.GOOGLE_CLOUD_LOCATION || undefined;
 	this.googleAuthOptions = options.googleAuthOptions || null;
 
 	// API Key (for Gemini API, not Vertex AI)
@@ -211,10 +218,18 @@ function AITransformFactory(options = {}) {
 	// Build chat config, making sure systemInstruction uses the custom instructions
 	this.chatConfig = {
 		...DEFAULT_CHAT_CONFIG,
-		...options.chatConfig,
-		systemInstruction: this.systemInstructions
+		...options.chatConfig		
 	};
 
+	// Handle systemInstructions: use custom if provided, otherwise keep default from DEFAULT_CHAT_CONFIG
+	// If explicitly set to null/false, remove it entirely
+	if (this.systemInstructions) {
+		this.chatConfig.systemInstruction = this.systemInstructions;
+	} else if (options.systemInstructions !== undefined) {
+		// Explicitly set to null/false/empty - remove system instruction
+		delete this.chatConfig.systemInstruction;
+	}
+
 	// Handle maxOutputTokens with explicit null check
 	// Priority: options.maxOutputTokens > options.chatConfig.maxOutputTokens > DEFAULT
 	// Setting to null explicitly removes the limit
@@ -295,10 +310,14 @@ function AITransformFactory(options = {}) {
 	this.enableGrounding = options.enableGrounding || false;
 	this.groundingConfig = options.groundingConfig || {};
 
-	// Billing labels for cost segmentation
+	// Billing labels for cost segmentation (Vertex AI only)
 	this.labels = options.labels || {};
 	if (Object.keys(this.labels).length > 0 && log.level !== 'silent') {
-		log.debug(`Billing labels configured: ${JSON.stringify(this.labels)}`);
+		if (!this.vertexai) {
+			log.warn(`Billing labels are only supported with Vertex AI. Labels will be ignored.`);
+		} else {
+			log.debug(`Billing labels configured: ${JSON.stringify(this.labels)}`);
+		}
 	}
 
 	if (this.promptKey === this.answerKey) {
@@ -311,7 +330,7 @@ function AITransformFactory(options = {}) {
 		log.debug(`Max output tokens set to: ${this.chatConfig.maxOutputTokens}`);
 		// Log authentication method
 		if (this.vertexai) {
-			log.debug(`Using Vertex AI - Project: ${this.project}, Location: ${this.location}`);
+			log.debug(`Using Vertex AI - Project: ${this.project}, Location: ${this.location || 'global (default)'}`);
 			if (this.googleAuthOptions?.keyFilename) {
 				log.debug(`Auth: Service account key file: ${this.googleAuthOptions.keyFilename}`);
 			} else if (this.googleAuthOptions?.credentials) {
@@ -330,7 +349,7 @@ function AITransformFactory(options = {}) {
 		? {
 			vertexai: true,
 			project: this.project,
-			location: this.location,
+			...(this.location && { location: this.location }),
 			...(this.googleAuthOptions && { googleAuthOptions: this.googleAuthOptions })
 		}
 		: { apiKey: this.apiKey };
@@ -357,7 +376,7 @@ async function initChat(force = false) {
 		// @ts-ignore
 		config: {
 			...this.chatConfig,
-			...(Object.keys(this.labels).length > 0 && { labels: this.labels })
+			...(this.vertexai && Object.keys(this.labels).length > 0 && { labels: this.labels })
 		},
 		history: [],
 	};
@@ -472,7 +491,7 @@ async function seedWithExamples(examples) {
 		// @ts-ignore
 		config: {
 			...this.chatConfig,
-			...(Object.keys(this.labels).length > 0 && { labels: this.labels })
+			...(this.vertexai && Object.keys(this.labels).length > 0 && { labels: this.labels })
 		},
 		history: [...currentHistory, ...historyToAdd],
 	});
@@ -509,13 +528,14 @@ async function rawMessage(sourcePayload, messageOptions = {}) {
 		: JSON.stringify(sourcePayload, null, 2);
 
 	// Merge instance labels with per-message labels (per-message takes precedence)
+	// Labels only supported with Vertex AI
 	const mergedLabels = { ...this.labels, ...(messageOptions.labels || {}) };
-	const hasLabels = Object.keys(mergedLabels).length > 0;
+	const hasLabels = this.vertexai && Object.keys(mergedLabels).length > 0;
 
 	try {
 		const sendParams = { message: actualPayload };
 
-		// Add config with labels if we have any
+		// Add config with labels if we have any (Vertex AI only)
 		if (hasLabels) {
 			sendParams.config = { labels: mergedLabels };
 		}
@@ -862,7 +882,7 @@ async function resetChat() {
 			// @ts-ignore
 			config: {
 				...this.chatConfig,
-				...(Object.keys(this.labels).length > 0 && { labels: this.labels })
+				...(this.vertexai && Object.keys(this.labels).length > 0 && { labels: this.labels })
 			},
 			history: [],
 		};
@@ -933,7 +953,7 @@ async function clearConversation() {
 		// @ts-ignore
 		config: {
 			...this.chatConfig,
-			...(Object.keys(this.labels).length > 0 && { labels: this.labels })
+			...(this.vertexai && Object.keys(this.labels).length > 0 && { labels: this.labels })
 		},
 		history: exampleHistory,
 	});
@@ -1019,7 +1039,7 @@ async function statelessMessage(sourcePayload, options = {}, validatorFn = null)
 	// Add the user message
 	contents.push({ role: 'user', parts: [{ text: payloadStr }] });
 
-	// Merge labels
+	// Merge labels (Vertex AI only)
 	const mergedLabels = { ...this.labels, ...(options.labels || {}) };
 
 	// Use generateContent instead of chat.sendMessage
@@ -1028,7 +1048,7 @@ async function statelessMessage(sourcePayload, options = {}, validatorFn = null)
 		contents: contents,
 		config: {
 			...this.chatConfig,
-			...(Object.keys(mergedLabels).length > 0 && { labels: mergedLabels })
+			...(this.vertexai && Object.keys(mergedLabels).length > 0 && { labels: mergedLabels })
 		}
 	});
 

package/package.json

@@ -2,7 +2,7 @@
 	"name": "ak-gemini",
 	"author": "ak@mixpanel.com",
 	"description": "AK's Generative AI Helper for doing... transforms",
-	"version": "1.1.0",
+	"version": "1.1.11",
 	"main": "index.js",
 	"files": [
 		"index.js",
@@ -38,8 +38,6 @@
 		"update-deps": "npx npm-check-updates -u && npm install",
 		"prune": "rm -rf tmp/*",
 		"test": "node --no-warnings --experimental-vm-modules node_modules/jest/bin/jest.js",
-		"test:unit": "npm test -- tests/module.test.js",
-		"test:fixed": "npm test -- --testNamePattern=\"should use context in the prompt and transform accordingly|should augment the payload as instructed by system instructions|should succeed on the first try if validation passes|should handle invalid model names|should handle multiple concurrent messages|should use the constructor-provided asyncValidator|should override system instructions from the file\"",
 		"build:cjs": "esbuild index.js --bundle --platform=node --format=cjs --outfile=index.cjs --external:@google/genai --external:ak-tools --external:dotenv --external:pino-pretty --external:pino",
 		"coverage": "node --no-warnings --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
 		"typecheck": "tsc --noEmit",

package/types.d.ts

@@ -87,6 +87,7 @@ export interface AITransformerContext {
   enableGrounding?: boolean; // Enable Google Search grounding (default: false, WARNING: costs $35/1k queries)
   groundingConfig?: Record<string, any>; // Additional grounding configuration options
   labels?: Record<string, string>; // Custom labels for billing segmentation (keys: 1-63 chars lowercase, values: max 63 chars)
+  vertexai?: boolean; // Whether using Vertex AI (true) or Gemini API (false)
   estimate?: (nextPayload: Record<string, unknown> | string) => Promise<{ inputTokens: number }>;
   getLastUsage?: () => UsageData | null;
   lastResponseMetadata?: ResponseMetadata | null; // Metadata from the last API response
@@ -124,7 +125,7 @@ export interface GoogleAuthOptions {
 export interface AITransformerOptions {
 	// ? https://ai.google.dev/gemini-api/docs/models
   modelName?: string; // The Gemini model to use
-  systemInstructions?: string; // Custom system instructions for the model
+  systemInstructions?: string | null | false; // Custom system instructions for the model (null/false = no instructions)
   chatConfig?: ChatConfig; // Configuration object for the chat session
   thinkingConfig?: ThinkingConfig; // Thinking features configuration (defaults to thinkingBudget: 0, thinkingLevel: "MINIMAL")
   maxOutputTokens?: number; // Maximum number of tokens that can be generated in the response (defaults to 50000)
@@ -153,7 +154,7 @@ export interface AITransformerOptions {
   // Use these instead of apiKey for Vertex AI with service account authentication
   vertexai?: boolean; // Set to true to use Vertex AI instead of Gemini API
   project?: string; // Google Cloud project ID (required for Vertex AI)
-  location?: string; // Google Cloud location/region (e.g., 'us-central1') - required for Vertex AI
+  location?: string; // Google Cloud location/region (e.g., 'us-central1'). If not set, defaults to 'global' endpoint
   googleAuthOptions?: GoogleAuthOptions; // Authentication options for Vertex AI (keyFilename, credentials, etc.)
 }
 
@@ -174,7 +175,7 @@ export declare class AITransformer {
   systemInstructionKey: string;
   maxRetries: number;
   retryDelay: number;
-  systemInstructions: string;
+  systemInstructions: string | null | false;
   chatConfig: ChatConfig;
   apiKey: string;
   onlyJSON: boolean;
@@ -185,6 +186,7 @@ export declare class AITransformer {
   enableGrounding: boolean;
   groundingConfig: Record<string, any>;
   labels: Record<string, string>;
+  vertexai: boolean;
   /** Metadata from the last API response (model version, token counts, etc.) */
   lastResponseMetadata: ResponseMetadata | null;
   /** Number of history items that are seeded examples (used by clearConversation) */