ak-gemini 1.0.59 → 1.1.1

package/README.md

@@ -7,10 +7,12 @@ Use this to power LLM-driven data pipelines, JSON mapping, or any automated AI t
 
 ## Features
 
-* **Model-Agnostic:** Use any Gemini model (`gemini-2.0-flash` by default)
+* **Model-Agnostic:** Use any Gemini model (`gemini-2.5-flash` by default)
 * **Declarative Few-shot Examples:** Seed transformations using example mappings, with support for custom keys (`PROMPT`, `ANSWER`, `CONTEXT`, or your own)
 * **Automatic Validation & Repair:** Validate outputs with your own async function; auto-repair failed payloads with LLM feedback loop (exponential backoff, fully configurable)
 * **Token Counting & Safety:** Preview the *exact* Gemini token consumption for any operation—including all examples, instructions, and your input—before sending, so you can avoid window errors and manage costs.
+* **Conversation Management:** Clear conversation history while preserving examples, or send stateless one-off messages that don't affect history
+* **Response Metadata:** Access actual model version and token counts from API responses for billing verification and debugging
 * **Strong TypeScript/JSDoc Typings:** All public APIs fully typed (see `/types`)
 * **Minimal API Surface:** Dead simple, no ceremony—init, seed, transform, validate.
 * **Robust Logging:** Pluggable logger for all steps, easy debugging
@@ -47,7 +49,7 @@ or pass it directly in the constructor options.
 import AITransformer from 'ak-gemini';
 
 const transformer = new AITransformer({
-  modelName: 'gemini-2.0-flash',    // or your preferred Gemini model
+  modelName: 'gemini-2.5-flash',    // or your preferred Gemini model
   sourceKey: 'INPUT',               // Custom prompt key (default: 'PROMPT')
   targetKey: 'OUTPUT',              // Custom answer key (default: 'ANSWER')
   contextKey: 'CONTEXT',            // Optional, for per-example context
@@ -75,15 +77,19 @@ console.log(result);
 
 ### 3. **Token Window Safety/Preview**
 
-Before calling `.message()` or `.seed()`, you can preview the exact token usage that will be sent to Gemini—*including* your system instructions, examples, and user input. This is vital for avoiding window errors and managing context size:
+Before calling `.message()` or `.seed()`, you can preview the INPUT token usage that will be sent to Gemini—*including* your system instructions, examples, and user input. This is vital for avoiding window errors and managing context size:
 
 ```js
-const { totalTokens, breakdown } = await transformer.estimateTokenUsage({ name: "Bob" });
-console.log(`Total tokens: ${totalTokens}`);
-console.log(breakdown); // See per-section token counts
+const { inputTokens } = await transformer.estimate({ name: "Bob" });
+console.log(`Input tokens: ${inputTokens}`);
 
 // Optional: abort or trim if over limit
-if (totalTokens > 32000) throw new Error("Request too large for selected Gemini model");
+if (inputTokens > 32000) throw new Error("Request too large for selected Gemini model");
+
+// After the call, check actual usage (input + output)
+await transformer.message({ name: "Bob" });
+const usage = transformer.getLastUsage();
+console.log(`Actual usage: ${usage.promptTokens} in, ${usage.responseTokens} out`);
 ```
 
 ---
@@ -106,6 +112,25 @@ console.log(validPayload);
 
 ---
 
+### 5. **Conversation Management**
+
+Manage chat history to control costs and isolate requests:
+
+```js
+// Clear conversation history while preserving seeded examples
+await transformer.clearConversation();
+
+// Send a stateless message that doesn't affect chat history
+const result = await transformer.message({ query: "one-off question" }, { stateless: true });
+
+// Check actual model and token usage from last API call
+console.log(transformer.lastResponseMetadata);
+// → { modelVersion: 'gemini-2.5-flash-001', requestedModel: 'gemini-2.5-flash',
+//    promptTokens: 150, responseTokens: 42, totalTokens: 192, timestamp: 1703... }
+```
+
+---
+
 ## API
 
 ### Constructor
@@ -116,7 +141,7 @@ new AITransformer(options)
 
 | Option             | Type   | Default            | Description                                       |
 | ------------------ | ------ | ------------------ | ------------------------------------------------- |
-| modelName          | string | 'gemini-2.0-flash' | Gemini model to use                               |
+| modelName          | string | 'gemini-2.5-flash' | Gemini model to use                               |
 | sourceKey          | string | 'PROMPT'           | Key for prompt/example input                      |
 | targetKey          | string | 'ANSWER'           | Key for expected output in examples               |
 | contextKey         | string | 'CONTEXT'          | Key for per-example context (optional)            |
@@ -125,6 +150,7 @@ new AITransformer(options)
 | responseSchema     | object | null               | Optional JSON schema for strict output validation |
 | maxRetries         | number | 3                  | Retries for validation+rebuild loop               |
 | 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                          |
 
@@ -141,14 +167,20 @@ Initializes Gemini chat session (idempotent).
 Seeds the model with example transformations (uses keys from constructor).
 You can omit `examples` to use the `examplesFile` (if provided).
 
-#### `await transformer.message(sourcePayload)`
+#### `await transformer.message(sourcePayload, options?)`
 
 Transforms input JSON to output JSON using the seeded examples and system instructions. Throws if estimated token window would be exceeded.
 
-#### `await transformer.estimateTokenUsage(sourcePayload)`
+**Options:**
+- `stateless: true` — Send a one-off message without affecting chat history (uses `generateContent` instead of chat)
+- `labels: {}` — Per-message billing labels
+
+#### `await transformer.estimate(sourcePayload)`
 
-Returns `{ totalTokens, breakdown }` for the *full request* that would be sent to Gemini (system instructions + all examples + your sourcePayload as the new prompt).
-Lets you preview token window safety and abort/trim as needed.
+Returns `{ inputTokens }` — the estimated INPUT tokens for the request (system instructions + all examples + your sourcePayload).
+Use this to preview token window safety and manage costs before sending.
+
+**Note:** This only estimates input tokens. Output tokens cannot be predicted before the API call. Use `getLastUsage()` after `message()` to see actual consumption.
 
 #### `await transformer.transformWithValidation(sourcePayload, validatorFn, options?)`
 
@@ -167,6 +199,48 @@ Resets the Gemini chat session, clearing all history/examples.
 
 Returns the current chat history (for debugging).
 
+#### `await transformer.clearConversation()`
+
+Clears conversation history while preserving seeded examples. Useful for starting fresh user sessions without re-seeding.
+
+#### `transformer.getLastUsage()`
+
+Returns structured usage data for billing verification. Token counts are **cumulative across all retry attempts** - if validation failed and a retry was needed, you see the total tokens consumed, not just the final successful call. Returns `null` if no API call has been made yet.
+
+```js
+const usage = transformer.getLastUsage();
+// {
+//   promptTokens: 300,      // CUMULATIVE input tokens across all attempts
+//   responseTokens: 84,     // CUMULATIVE output tokens across all attempts
+//   totalTokens: 384,       // CUMULATIVE total tokens
+//   attempts: 2,            // Number of attempts (1 = first try success, 2+ = retries needed)
+//   modelVersion: 'gemini-2.5-flash-001',  // Actual model that responded
+//   requestedModel: 'gemini-2.5-flash',    // Model you requested
+//   timestamp: 1703...      // When response was received
+// }
+```
+
+---
+
+### Properties
+
+#### `transformer.lastResponseMetadata`
+
+After each API call, contains metadata from the response:
+
+```js
+{
+  modelVersion: string | null,  // Actual model version that responded (e.g., 'gemini-2.5-flash-001')
+  requestedModel: string,       // Model you requested (e.g., 'gemini-2.5-flash')
+  promptTokens: number,         // Tokens in the prompt
+  responseTokens: number,       // Tokens in the response
+  totalTokens: number,          // Total tokens used
+  timestamp: number             // When response was received
+}
+```
+
+Useful for verifying billing, debugging model behavior, and tracking token usage.
+
 ---
 
 ## Examples