llm-cost-estimator

LLM usage cost accounting — you supply the price table, this tracks per-model/label cost breakdowns, projections, budget alerts, and CSV/JSON export. Zero runtime dependencies, strict TypeScript.

Prices change too fast to hardcode. This library ships no built-in model prices. You pass your own price table at construction time and keep it current from your provider's pricing page.

Quickstart

import { CostTracker } from "llm-cost-estimator";

// ILLUSTRATIVE prices only — check your provider's current pricing page.
const prices = {
  "example-large": { inputPer1M: 3.0, outputPer1M: 15.0, cacheReadPer1M: 0.3 },
  "example-small": { inputPer1M: 0.25, outputPer1M: 1.25 },
};

const tracker = new CostTracker(prices);

tracker.onBudgetThreshold(10, ({ totalCost, threshold }) => {
  console.log(`Crossed $${threshold}: total is now $${totalCost.toFixed(2)}`);
});

tracker.record({ model: "example-large", label: "chat", inputTokens: 1200, outputTokens: 400 });

tracker.breakdown();
// => [{ model, label, requestCount, totalInputTokens, totalOutputTokens, totalCacheReadTokens, totalCost, avgCostPerRequest }]

tracker.project(500); // requests/day
// => { avgCostPerRequest, requestsPerDay, projectedDailyCost, projectedMonthlyCost }

tracker.toCSV();  // CSV ledger
tracker.toJSON(); // JSON ledger (RecordedEntry[])

API

new CostTracker(prices: PriceTable)

PriceTable is Record<string, ModelPricing> where ModelPricing is { inputPer1M: number; outputPer1M: number; cacheReadPer1M?: number }.

computeCost(usage): number

Compute the cost of one UsageRecord without recording it.

record(usage): RecordedEntry

Records usage and returns the entry with its computed cost and timestamp (defaults to Date.now()). Checks all registered budget alerts after recording.

UsageRecord: { model, label?, inputTokens, outputTokens, cacheReadTokens?, timestamp? }

totalCost(): number / getEntries(): RecordedEntry[]

Running total and the full ledger, in insertion order.

breakdown(): BreakdownRow[]

Per model+label rows (unlabeled records group under "(unlabeled)"), sorted by totalCost descending: request count, token totals, total cost, average cost per request.

project(requestsPerDay): Projection

Projects avgCostPerRequest (computed from all recorded entries so far) forward to projectedDailyCost and projectedMonthlyCost (× 30).

onBudgetThreshold(threshold, callback): void

Registers a callback that fires once the first time total cost crosses threshold. Register multiple thresholds for a staged alert ladder.

toCSV(): string / toJSON(): RecordedEntry[]

Export the full ledger.

Limits

• No built-in prices. The PriceTable you provide is the sole source of truth; this library has no opinion on what any model costs and does not fetch prices from anywhere.
• project() extrapolates linearly from the observed average cost per request — it does not account for prompt-length drift, discount tiers, or caching hit-rate changes over time.
• onBudgetThreshold fires once per threshold for the lifetime of the tracker instance; it does not re-fire if cost later drops below and crosses again.

Part of the ferrow-toolkit collection · Sponsored by Ferrow