@sisu-ai/mw-usage-tracker 1.0.0 → 2.0.0

package/README.md

@@ -2,14 +2,33 @@
 
 Track token usage across your pipeline and estimate cost.
 
+## Setup
+```bash
+npm i @sisu-ai/mw-usage-tracker
+```
+
+## Documentation
+Discover what you can do through examples or documentation. Check it out at https://github.com/finger-gun/sisu
+
 ## Usage
 ```ts
 import { usageTracker } from '@sisu-ai/mw-usage-tracker';
 
 const app = new Agent()
   .use(usageTracker({
-    'openai:gpt-4o-mini': { inputPer1K: 0.15, outputPer1K: 0.6 },
-    '*': { inputPer1K: 0.15, outputPer1K: 0.6 },
+    'openai:gpt-4o-mini': {
+      // Preferred: prices per 1M tokens (matches provider docs)
+      inputPer1M: 0.15,
+      outputPer1M: 0.60,
+      // Optional vision pricing (choose one):
+      // a) Per 1K images (e.g., $0.217/K images)
+      imagePer1K: 0.217,
+      // b) Approximate per-1K "image tokens"
+      // imageInputPer1K: 0.217,
+      // imageTokenPerImage: 1000,
+    },
+    // Fallback default for other models
+    '*': { inputPer1M: 0.15, outputPer1M: 0.60 },
   }, { logPerCall: true }))
 ```
 
@@ -17,8 +36,16 @@ const app = new Agent()
 - Wraps `ctx.model.generate` for the duration of the pipeline.
 - Accumulates `promptTokens`, `completionTokens`, `totalTokens` from `ModelResponse.usage`.
 - If a price table is provided, computes `costUSD` per call and totals.
+- Optional: for vision models
+  - Providers vary: some include image cost in native token usage; others bill separately per image.
+  - If billed per image batch, set `imagePer1K` (e.g., 0.217 USD per 1K images). The tracker converts this to per-image.
+  - Or configure `imageInputPer1K` + `imageTokenPerImage` to approximate per-1K image-token pricing. In that mode we split
+    prompt tokens into estimated `imageTokens = imageCount * imageTokenPerImage` (default 1000) and
+    `textPromptTokens = promptTokens - imageTokens`, then price them separately.
 - Writes totals to `ctx.state.usage` and logs them at the end.
+- Cost is rounded to 6 decimals to avoid showing small calls as 0.00.
 
 ## Notes
 - Each adapter should map its native usage fields to `ModelResponse.usage`.
 - If a provider doesn’t return usage, you’ll get counts of calls only (no cost).
+- Image cost estimation is an approximation unless your adapter returns precise image token usage.

package/dist/index.d.ts

@@ -1,13 +1,21 @@
 import type { Middleware } from '@sisu-ai/core';
 export type PriceTable = Record<string, {
-    inputPer1K: number;
-    outputPer1K: number;
+    inputPer1M?: number;
+    outputPer1M?: number;
+    inputPer1K?: number;
+    outputPer1K?: number;
+    imagePerImage?: number;
+    imagePer1K?: number;
+    imageInputPer1K?: number;
+    imageTokenPerImage?: number;
 }>;
 export interface UsageTotals {
     promptTokens: number;
     completionTokens: number;
     totalTokens: number;
     costUSD?: number;
+    imageTokens?: number;
+    imageCount?: number;
 }
 export declare function usageTracker(prices: PriceTable, opts?: {
     logPerCall?: boolean;

package/dist/index.js

@@ -10,6 +10,10 @@ export function usageTracker(prices, opts = {}) {
             costUSD: Number(ctx.state?.usage?.costUSD ?? 0),
         };
         async function withUsage(...args) {
+            // Inspect request messages to estimate image inputs
+            const reqMessages = args?.[0];
+            const imageCount = countImageInputs(reqMessages);
+            const imageTokens = imageCount * Number(price?.imageTokenPerImage ?? 1000);
             const out = await orig(...args);
             const u = out.usage;
             if (u) {
@@ -20,11 +24,41 @@ export function usageTracker(prices, opts = {}) {
                 totals.completionTokens += c;
                 totals.totalTokens += t;
                 if (price) {
-                    const cost = (p / 1000) * price.inputPer1K + (c / 1000) * price.outputPer1K;
+                    // Resolve effective per-1K pricing from provided per-1M or per-1K fields
+                    const inPer1K = price.inputPer1K ?? (price.inputPer1M != null ? price.inputPer1M / 1000 : undefined) ?? 0;
+                    const outPer1K = price.outputPer1K ?? (price.outputPer1M != null ? price.outputPer1M / 1000 : undefined) ?? 0;
+                    // Base text+completion token cost
+                    const textPromptTokens = Math.max(0, p - (price.imageInputPer1K ? imageTokens : 0));
+                    const tokenCost = (textPromptTokens / 1000) * inPer1K + (c / 1000) * outPer1K;
+                    // Image cost (prefer per-image if provided)
+                    const perImage = price.imagePerImage != null ? price.imagePerImage : (price.imagePer1K != null ? price.imagePer1K / 1000 : undefined);
+                    const imageCost = perImage != null
+                        ? imageCount * perImage
+                        : price.imageInputPer1K
+                            ? (imageTokens / 1000) * price.imageInputPer1K
+                            : 0;
+                    const cost = tokenCost + imageCost;
                     totals.costUSD = Number((totals.costUSD ?? 0) + cost);
+                    if (imageCount > 0 && price.imageInputPer1K) {
+                        totals.imageTokens = Number((totals.imageTokens ?? 0) + imageTokens);
+                        totals.imageCount = Number((totals.imageCount ?? 0) + imageCount);
+                    }
                 }
                 if (opts.logPerCall)
-                    ctx.log.info?.('[usage] call', { promptTokens: p, completionTokens: c, totalTokens: t, estCostUSD: price ? round2((p / 1000) * price.inputPer1K + (c / 1000) * price.outputPer1K) : undefined });
+                    ctx.log.info?.('[usage] call', {
+                        promptTokens: p, completionTokens: c, totalTokens: t,
+                        imageTokens: (imageCount > 0 && price?.imageInputPer1K) ? imageTokens : undefined,
+                        imageCount: imageCount > 0 ? imageCount : undefined,
+                        estCostUSD: price ? (() => {
+                            const inPer1K = price.inputPer1K ?? (price.inputPer1M != null ? price.inputPer1M / 1000 : 0);
+                            const outPer1K = price.outputPer1K ?? (price.outputPer1M != null ? price.outputPer1M / 1000 : 0);
+                            const textPromptTokens = Math.max(0, p - (price?.imageInputPer1K ? imageTokens : 0));
+                            const perImage = price?.imagePerImage != null ? price.imagePerImage : (price?.imagePer1K != null ? price.imagePer1K / 1000 : undefined);
+                            const tokenCost = (textPromptTokens / 1000) * inPer1K + (c / 1000) * outPer1K;
+                            const imageCost = perImage != null ? (imageCount * perImage) : (price?.imageInputPer1K ? (imageTokens / 1000) * price.imageInputPer1K : 0);
+                            return roundUSD(tokenCost + imageCost);
+                        })() : undefined,
+                    });
             }
             return out;
         }
@@ -39,8 +73,34 @@ export function usageTracker(prices, opts = {}) {
         ctx.state.usage.completionTokens = totals.completionTokens;
         ctx.state.usage.totalTokens = totals.totalTokens;
         if (price)
-            ctx.state.usage.costUSD = round2(totals.costUSD ?? 0);
+            ctx.state.usage.costUSD = roundUSD(totals.costUSD ?? 0);
+        if (totals.imageTokens)
+            ctx.state.usage.imageTokens = totals.imageTokens;
+        if (totals.imageCount)
+            ctx.state.usage.imageCount = totals.imageCount;
         ctx.log.info?.('[usage] totals', ctx.state.usage);
     };
 }
-function round2(n) { return Math.round(n * 100) / 100; }
+function roundUSD(n) { return Math.round(n * 1e6) / 1e6; }
+function countImageInputs(msgs) {
+    if (!Array.isArray(msgs))
+        return 0;
+    let count = 0;
+    for (const m of msgs) {
+        const c = m?.content;
+        if (Array.isArray(c)) {
+            for (const part of c) {
+                if (part && typeof part === 'object' && (part.type === 'image_url' || part.type === 'image'))
+                    count += 1;
+            }
+        }
+        // Convenience shapes supported by adapters (count regardless of content presence)
+        if (Array.isArray(m?.images))
+            count += m.images.length;
+        if (typeof m?.image_url === 'string')
+            count += 1;
+        if (typeof m?.image === 'string')
+            count += 1;
+    }
+    return count;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sisu-ai/mw-usage-tracker",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,6 +14,15 @@
     "build": "tsc -b"
   },
   "peerDependencies": {
-    "@sisu-ai/core": "0.2.0"
+    "@sisu-ai/core": "0.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/finger-gun/sisu",
+    "directory": "packages/middleware/usage-tracker"
+  },
+  "homepage": "https://github.com/finger-gun/sisu#readme",
+  "bugs": {
+    "url": "https://github.com/finger-gun/sisu/issues"
   }
 }