@future-explorer/lib 1.0.11 → 1.0.12

package/README.md

@@ -107,9 +107,52 @@ console.log(result.summary); // '...'
 
 ### Methods
 
-- `generateStructuredResponse<T>(schema: ZodSchema<T>, params: GenerateObjectParams<T>)`: Generates a structured response matching the Zod schema. Accepts `prompt`, `system`, plus any additional options
+- `generateStructuredResponse<T>(schema, params, usageTracker?)`: Generates a structured response matching the Zod schema. Accepts `prompt`, `system`, plus any additional options. Optionally pass an `AiUsageTracker` to record usage.
 - `getModel()`: Returns the underlying LanguageModel instance
 
+## AiUsageTracker
+
+Tracks and accumulates AI usage costs across multiple `generateStructuredResponse()` calls. Useful for calculating the total cost of processing a single input that requires multiple AI calls.
+
+### Basic Usage
+
+```typescript
+import { UnifiedAiClient, AiUsageTracker, Provider } from '@future-explorer/lib';
+import { z } from 'zod';
+
+const client = new UnifiedAiClient(Provider.XAI);
+const tracker = new AiUsageTracker();
+
+const Schema = z.object({ summary: z.string() });
+
+// Each call automatically records usage in the tracker
+await client.generateStructuredResponse(Schema, { prompt: 'First call...' }, tracker);
+await client.generateStructuredResponse(Schema, { prompt: 'Second call...' }, tracker);
+
+// Get accumulated results
+console.log(tracker.getSummary());
+// AI Usage: 2 call(s), $0.001234 estimated
+//   Tokens - input: 500, output: 200, reasoning: 0, total: 700
+//   [xai/grok-4-1-fast-reasoning] in=250 out=100 $0.000617 3200ms
+//   [xai/grok-4-1-fast-reasoning] in=250 out=100 $0.000617 2800ms
+
+console.log(tracker.getTotalCost());   // 0.001234
+console.log(tracker.getTotalTokens()); // { input: 500, output: 200, reasoning: 0, total: 700 }
+console.log(tracker.getCalls());       // AiCallUsage[]
+```
+
+### Supported Models
+
+Built-in pricing for cost estimation (easily extensible):
+
+| Provider | Models |
+| -------- | ------ |
+| xAI      | grok-4-1-fast, grok-4-fast, grok-4, grok-3, grok-3-mini, grok-2 |
+| OpenAI   | gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-4o, gpt-4o-mini, o3, o3-mini, o4-mini |
+| Gemini   | gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite, gemini-2.0-flash |
+
+Model IDs are matched by substring, so `grok-4-1-fast-reasoning` matches the `grok-4-1-fast` pricing entry.
+
 ## Development
 
 ### Build
@@ -162,6 +205,20 @@ npm publish
 
 ## Changelog
 
+### 1.0.12
+
+- Added `AiUsageTracker` for tracking AI usage costs across multiple calls
+- `generateStructuredResponse()` now accepts optional `usageTracker` parameter
+
+### 1.0.11
+
+- Moved `schema` out of `GenerateObjectParams` into a separate parameter
+- Renamed `userPrompt`/`systemMessage` to `prompt`/`system`
+
+### 1.0.10
+
+- Refactored `generateStructuredResponse()` to accept a single `GenerateObjectParams<T>` object
+
 ### 1.0.7
 
 - Updated peer dependency to zod 4.2.x

package/dist/clients/ai/index.d.ts

@@ -1,5 +1,6 @@
 export * from './grok';
 export * from './shared';
+export * from './unified/ai-usage-tracker';
 export * from './unified/unified-ai-client';
 export * from './unified/unified-ai-client.model';
 //# sourceMappingURL=index.d.ts.map

package/dist/clients/ai/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/clients/ai/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/clients/ai/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC"}

package/dist/clients/ai/index.js

@@ -16,5 +16,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./grok"), exports);
 __exportStar(require("./shared"), exports);
+__exportStar(require("./unified/ai-usage-tracker"), exports);
 __exportStar(require("./unified/unified-ai-client"), exports);
 __exportStar(require("./unified/unified-ai-client.model"), exports);

package/dist/clients/ai/unified/ai-usage-tracker.d.ts

@@ -0,0 +1,34 @@
+import { LanguageModelUsage } from 'ai';
+export interface AiCallUsage {
+    provider: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    reasoningTokens?: number;
+    cachedInputTokens?: number;
+    estimatedCost: number;
+    durationMs: number;
+}
+export interface ModelPricing {
+    inputPer1MTokens: number;
+    outputPer1MTokens: number;
+    reasoningPer1MTokens?: number;
+    cachedInputPer1MTokens?: number;
+}
+export declare class AiUsageTracker {
+    private calls;
+    addCall(call: AiCallUsage): void;
+    getCalls(): AiCallUsage[];
+    getTotalCost(): number;
+    getTotalTokens(): {
+        input: number;
+        output: number;
+        reasoning: number;
+        total: number;
+    };
+    getSummary(): string;
+    static findPricing(model: string): ModelPricing | undefined;
+    static estimateCost(model: string, usage: LanguageModelUsage): number;
+}
+//# sourceMappingURL=ai-usage-tracker.d.ts.map

package/dist/clients/ai/unified/ai-usage-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-usage-tracker.d.ts","sourceRoot":"","sources":["../../../../src/clients/ai/unified/ai-usage-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,IAAI,CAAC;AAExC,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AA0BD,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAqB;IAElC,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAIhC,QAAQ,IAAI,WAAW,EAAE;IAIzB,YAAY,IAAI,MAAM;IAItB,cAAc,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAYrF,UAAU,IAAI,MAAM;IAepB,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAe3D,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,MAAM;CAsBtE"}

package/dist/clients/ai/unified/ai-usage-tracker.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiUsageTracker = void 0;
+const MODEL_PRICING = {
+    // xAI / Grok
+    'grok-4-1-fast': { inputPer1MTokens: 0.2, outputPer1MTokens: 0.5, reasoningPer1MTokens: 0.5, cachedInputPer1MTokens: 0.05 },
+    'grok-4-fast': { inputPer1MTokens: 0.2, outputPer1MTokens: 0.5, reasoningPer1MTokens: 0.5, cachedInputPer1MTokens: 0.05 },
+    'grok-4': { inputPer1MTokens: 3, outputPer1MTokens: 15, cachedInputPer1MTokens: 0.75 },
+    'grok-3-mini': { inputPer1MTokens: 0.3, outputPer1MTokens: 0.5, reasoningPer1MTokens: 0.5, cachedInputPer1MTokens: 0.075 },
+    'grok-3': { inputPer1MTokens: 3, outputPer1MTokens: 15, cachedInputPer1MTokens: 0.75 },
+    'grok-2': { inputPer1MTokens: 2, outputPer1MTokens: 10 },
+    // OpenAI
+    'gpt-4.1': { inputPer1MTokens: 2, outputPer1MTokens: 8, cachedInputPer1MTokens: 0.5 },
+    'gpt-4.1-mini': { inputPer1MTokens: 0.4, outputPer1MTokens: 1.6, cachedInputPer1MTokens: 0.1 },
+    'gpt-4.1-nano': { inputPer1MTokens: 0.1, outputPer1MTokens: 0.4, cachedInputPer1MTokens: 0.025 },
+    'gpt-4o': { inputPer1MTokens: 2.5, outputPer1MTokens: 10, cachedInputPer1MTokens: 1.25 },
+    'gpt-4o-mini': { inputPer1MTokens: 0.15, outputPer1MTokens: 0.6, cachedInputPer1MTokens: 0.075 },
+    'o3': { inputPer1MTokens: 2, outputPer1MTokens: 8, reasoningPer1MTokens: 8, cachedInputPer1MTokens: 0.5 },
+    'o3-mini': { inputPer1MTokens: 1.1, outputPer1MTokens: 4.4, reasoningPer1MTokens: 4.4, cachedInputPer1MTokens: 0.275 },
+    'o4-mini': { inputPer1MTokens: 1.1, outputPer1MTokens: 4.4, reasoningPer1MTokens: 4.4, cachedInputPer1MTokens: 0.275 },
+    // Google Gemini
+    'gemini-2.5-pro': { inputPer1MTokens: 1.25, outputPer1MTokens: 10, reasoningPer1MTokens: 10 },
+    'gemini-2.5-flash': { inputPer1MTokens: 0.15, outputPer1MTokens: 0.6, reasoningPer1MTokens: 0.6 },
+    'gemini-2.5-flash-lite': { inputPer1MTokens: 0.1, outputPer1MTokens: 0.4 },
+    'gemini-2.0-flash': { inputPer1MTokens: 0.1, outputPer1MTokens: 0.4 },
+};
+class AiUsageTracker {
+    calls = [];
+    addCall(call) {
+        this.calls.push(call);
+    }
+    getCalls() {
+        return this.calls;
+    }
+    getTotalCost() {
+        return this.calls.reduce((sum, c) => sum + c.estimatedCost, 0);
+    }
+    getTotalTokens() {
+        return this.calls.reduce((acc, c) => ({
+            input: acc.input + c.inputTokens,
+            output: acc.output + c.outputTokens,
+            reasoning: acc.reasoning + (c.reasoningTokens ?? 0),
+            total: acc.total + c.totalTokens,
+        }), { input: 0, output: 0, reasoning: 0, total: 0 });
+    }
+    getSummary() {
+        const tokens = this.getTotalTokens();
+        const cost = this.getTotalCost();
+        const lines = [
+            `AI Usage: ${this.calls.length} call(s), $${cost.toFixed(6)} estimated`,
+            `  Tokens — input: ${tokens.input}, output: ${tokens.output}, reasoning: ${tokens.reasoning}, total: ${tokens.total}`,
+        ];
+        for (const c of this.calls) {
+            lines.push(`  [${c.provider}/${c.model}] in=${c.inputTokens} out=${c.outputTokens}${c.reasoningTokens ? ` reasoning=${c.reasoningTokens}` : ''} $${c.estimatedCost.toFixed(6)} ${c.durationMs}ms`);
+        }
+        return lines.join('\n');
+    }
+    static findPricing(model) {
+        // Exact match first
+        if (MODEL_PRICING[model])
+            return MODEL_PRICING[model];
+        // Substring match — find the longest key that matches
+        let bestMatch;
+        for (const key of Object.keys(MODEL_PRICING)) {
+            if (model.includes(key)) {
+                if (!bestMatch || key.length > bestMatch.length) {
+                    bestMatch = key;
+                }
+            }
+        }
+        return bestMatch ? MODEL_PRICING[bestMatch] : undefined;
+    }
+    static estimateCost(model, usage) {
+        const pricing = AiUsageTracker.findPricing(model);
+        if (!pricing)
+            return 0;
+        const inputTokens = usage.inputTokens ?? 0;
+        const outputTokens = usage.outputTokens ?? 0;
+        const reasoningTokens = usage.reasoningTokens ?? 0;
+        const cachedInputTokens = usage.cachedInputTokens ?? 0;
+        const billableInputTokens = inputTokens - cachedInputTokens;
+        let cost = 0;
+        cost += (billableInputTokens / 1_000_000) * pricing.inputPer1MTokens;
+        cost += (outputTokens / 1_000_000) * pricing.outputPer1MTokens;
+        if (pricing.cachedInputPer1MTokens) {
+            cost += (cachedInputTokens / 1_000_000) * pricing.cachedInputPer1MTokens;
+        }
+        if (pricing.reasoningPer1MTokens) {
+            cost += (reasoningTokens / 1_000_000) * pricing.reasoningPer1MTokens;
+        }
+        return cost;
+    }
+}
+exports.AiUsageTracker = AiUsageTracker;

package/dist/clients/ai/unified/index.d.ts

@@ -1,3 +1,4 @@
+export * from './ai-usage-tracker';
 export * from './unified-ai-client';
 export * from './unified-ai-client.model';
 //# sourceMappingURL=index.d.ts.map

package/dist/clients/ai/unified/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/clients/ai/unified/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/clients/ai/unified/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC"}

package/dist/clients/ai/unified/index.js

@@ -14,5 +14,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ai-usage-tracker"), exports);
 __exportStar(require("./unified-ai-client"), exports);
 __exportStar(require("./unified-ai-client.model"), exports);

package/dist/clients/ai/unified/unified-ai-client.d.ts

@@ -1,5 +1,6 @@
 import { LanguageModel } from 'ai';
 import { ZodSchema } from 'zod';
+import { AiUsageTracker } from './ai-usage-tracker';
 import { GenerateObjectParams, Provider } from './unified-ai-client.model';
 /**
  * Unified AI Client that supports multiple AI providers (OpenAI, XAI, Gemini)
@@ -7,6 +8,7 @@ import { GenerateObjectParams, Provider } from './unified-ai-client.model';
  */
 export declare class UnifiedAiClient {
     private model;
+    private provider;
     constructor(provider: Provider);
     /**
      * Generates a structured response from the AI model based on a Zod schema.
@@ -40,7 +42,7 @@ export declare class UnifiedAiClient {
      * console.log(result.sentiment);   // 'positive'
      * console.log(result.confidence);  // 0.95
      */
-    generateStructuredResponse<T>(schema: ZodSchema<T>, params: GenerateObjectParams<T>): Promise<T>;
+    generateStructuredResponse<T>(schema: ZodSchema<T>, params: GenerateObjectParams<T>, usageTracker?: AiUsageTracker): Promise<T>;
     /**
      * Retrieves the underlying LanguageModel instance.
      * @returns The LanguageModel instance used by the UnifiedAiClient.

package/dist/clients/ai/unified/unified-ai-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unified-ai-client.d.ts","sourceRoot":"","sources":["../../../../src/clients/ai/unified/unified-ai-client.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkB,aAAa,EAAE,MAAM,IAAI,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAChC,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE3E;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAAgB;gBAEjB,QAAQ,EAAE,QAAQ;IAI9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,0BAA0B,CAAC,CAAC,EAChC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EACpB,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC9B,OAAO,CAAC,CAAC,CAAC;IAcb;;;OAGG;IACH,QAAQ,IAAI,aAAa;IAIzB,OAAO,CAAC,WAAW;CAYpB"}
+{"version":3,"file":"unified-ai-client.d.ts","sourceRoot":"","sources":["../../../../src/clients/ai/unified/unified-ai-client.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkB,aAAa,EAAE,MAAM,IAAI,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAChC,OAAO,EAAe,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE3E;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAAgB;IAE7B,OAAO,CAAC,QAAQ,CAAW;gBAEf,QAAQ,EAAE,QAAQ;IAK9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,0BAA0B,CAAC,CAAC,EAChC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EACpB,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC,EAC/B,YAAY,CAAC,EAAE,cAAc,GAC5B,OAAO,CAAC,CAAC,CAAC;IAuCb;;;OAGG;IACH,QAAQ,IAAI,aAAa;IAIzB,OAAO,CAAC,WAAW;CAYpB"}

package/dist/clients/ai/unified/unified-ai-client.js

@@ -5,6 +5,7 @@ const google_1 = require("@ai-sdk/google");
 const openai_1 = require("@ai-sdk/openai");
 const xai_1 = require("@ai-sdk/xai");
 const ai_1 = require("ai");
+const ai_usage_tracker_1 = require("./ai-usage-tracker");
 const unified_ai_client_model_1 = require("./unified-ai-client.model");
 /**
  * Unified AI Client that supports multiple AI providers (OpenAI, XAI, Gemini)
@@ -12,7 +13,9 @@ const unified_ai_client_model_1 = require("./unified-ai-client.model");
  */
 class UnifiedAiClient {
     model;
+    provider;
     constructor(provider) {
+        this.provider = provider;
         this.model = this.createModel(provider);
     }
     /**
@@ -47,8 +50,9 @@ class UnifiedAiClient {
      * console.log(result.sentiment);   // 'positive'
      * console.log(result.confidence);  // 0.95
      */
-    async generateStructuredResponse(schema, params) {
+    async generateStructuredResponse(schema, params, usageTracker) {
         const { prompt, system, ...rest } = params;
+        const startTime = Date.now();
         const result = await (0, ai_1.generateObject)({
             ...rest,
             model: this.model,
@@ -56,6 +60,24 @@ class UnifiedAiClient {
             prompt: prompt,
             system: system,
         });
+        const durationMs = Date.now() - startTime;
+        const usage = result.usage;
+        const model = result.response.modelId;
+        const aiCallUsage = {
+            provider: this.provider,
+            model,
+            inputTokens: usage.inputTokens ?? 0,
+            outputTokens: usage.outputTokens ?? 0,
+            totalTokens: usage.totalTokens ?? 0,
+            reasoningTokens: usage.reasoningTokens ?? undefined,
+            cachedInputTokens: usage.cachedInputTokens ?? undefined,
+            estimatedCost: ai_usage_tracker_1.AiUsageTracker.estimateCost(model, usage),
+            durationMs,
+        };
+        console.log(`[AI Call Usage] ${aiCallUsage.provider}/${aiCallUsage.model} in=${aiCallUsage.inputTokens} out=${aiCallUsage.outputTokens}${aiCallUsage.reasoningTokens ? ` reasoning=${aiCallUsage.reasoningTokens}` : ''} $${aiCallUsage.estimatedCost.toFixed(6)} ${aiCallUsage.durationMs}ms`);
+        if (usageTracker) {
+            usageTracker.addCall(aiCallUsage);
+        }
         return result.object;
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@future-explorer/lib",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "description": "Shared utilities and clients for Future Explorer projects",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -63,6 +63,6 @@
     "rimraf": "^6.0.1",
     "ts-node": "^10.9.2",
     "typescript": "^5.6.3",
-    "zod": "4.2.0"
+    "zod": "^4.3.6"
   }
 }