Tokens-per-watt

Estimate the energy (Wh / kWh) behind LLM API usage — per conversation, per build, per CI run — and compare prompting strategies to see which one would have used less power.

This is a research estimate, not a hardware measurement. Cloud providers don't expose real-time datacenter power draw per API call, so no npm package — this one included — can hand you an audited electricity bill for a gpt-4o or claude call. What this package gives you is a transparent, order-of-magnitude estimate built from public research and published/rumored model sizes, useful for comparing prompt strategies against each other, not for auditing exact energy spend. See How accurate is this? before you trust a number from this tool in a report.

Credit / inspiration

This project takes its name and framing from Intelligence per Watt (IPW), Stanford Hazy Research's metric and empirical study of AI inference efficiency (Saad-Falcon et al., 2025). IPW measures task accuracy per unit of power across local models and hardware accelerators, and makes the case that efficiency, not just raw capability, should guide how and where AI runs.

tokens-per-watt asks a narrower, adjacent question: for cloud API usage specifically, roughly how much energy did this conversation or build cost, and would a different prompting strategy have cost less? It's not an implementation of IPW and doesn't measure accuracy — it's a smaller, practical tool inspired by the same underlying concern: that power consumption is a first-class metric for AI usage, not an afterthought. If you're interested in efficiency at the model/hardware level rather than the prompting/API level, go read their paper.

Install

npm install tokens-per-watt

Quickstart

import { estimateEnergyWh, EnergyTracker } from "tokens-per-watt";

// Single call
const result = estimateEnergyWh({
  model: "claude-3-5-sonnet-20241022",
  inputTokens: 1200,
  outputTokens: 400,
});
// { wh: ..., kWh: ..., coefficientSource: "known_model", sizeClass: "medium", disclaimer: "..." }

// Whole conversation / build
const tracker = new EnergyTracker();

// Accepts raw OpenAI SDK usage shape
tracker.add("gpt-4o", response.usage); // { prompt_tokens, completion_tokens }

// Accepts raw Anthropic SDK usage shape
tracker.add("claude-3-5-haiku-20241022", response.usage); // { input_tokens, output_tokens }

// Or manual shape
tracker.add("gpt-4o-mini", { inputTokens: 300, outputTokens: 120 });

const report = tracker.summary();
console.log(report.totalWh, report.perModel, report.disclaimer);

CLI

npx tpw calls.jsonl

Each line of calls.jsonl is one call:

{"provider": "anthropic", "model": "claude-3-5-sonnet", "inputTokens": 1200, "outputTokens": 400}

The CLI prints a summary table and, where relevant, suggestions from the advisor (see below) — always labeled as estimates.

What it does

• Estimator — converts input/output token counts into an estimated Wh figure using a per-model coefficient (Wh per output token, with input tokens priced at ~15% of output's per-token cost, reflecting that prefill is parallelized and decode is sequential).
• Tracker — accumulates calls across a conversation or build into a total, with a per-model breakdown, optional cost estimate (if you supply $/kWh), and optional CO2e estimate (if you supply a grid carbon intensity — opt-in only, since this varies enormously by region and time of day).
• Advisor — takes a tracked session and estimates what a different strategy would have cost: a smaller model in the same family, a shorter system prompt, prompt caching, capped output length, or batching several short calls into one.

How accurate is this?

Short answer: directionally useful, not audit-grade.

The per-model coefficients in this package are assembled from public research on inference energy cost — notably Luccioni et al., "Power Hungry Processing" (2023/2024), de Vries, "The growing energy footprint of AI" (2023), and public writeups of model sizes — combined with size-class heuristics for anything not explicitly in the table. They are not vendor-disclosed per-call energy figures; no major provider publishes those.

Real energy draw for any given API call depends on things this package cannot see from outside a datacenter:

• Hardware generation and accelerator type
• Batching and request concurrency at the time of your call
• Utilization / how "warm" the serving fleet is
• Datacenter Power Usage Effectiveness (PUE), cooling, and site efficiency

Use this package to compare relative energy cost between prompting choices ("would a shorter prompt or a smaller model have used less energy?") rather than to produce a number you'd defend in an audit. Every object this package returns includes a disclaimer field for this reason — please don't strip it out downstream.

You can override or extend any coefficient:

import { setModelCoefficient } from "tokens-per-watt";

// setModelCoefficient(model, whPerOutputToken, sizeClass, whPerInputToken?)
setModelCoefficient("my-custom-model", 0.002, "medium", 0.0003);

API reference

estimateEnergyWh(input: EstimateInput): EstimateResult

Estimate energy for a single API call.

interface EstimateInput {
  model: string;
  inputTokens: number;
  outputTokens: number;
  provider?: string;
  reasoningTokens?: number; // hidden thinking tokens (o1, Claude extended thinking)
}

EnergyTracker

Accumulates multiple calls into a session total.

const tracker = new EnergyTracker({
  dollarPerKwh: 0.12,    // optional — adds cost estimate
  gCo2PerKwh: 400,       // optional — adds CO2e estimate (opt-in only)
});

tracker.add(model, usage, meta?);  // returns EstimateResult
tracker.summary();                 // returns TrackerSummary
tracker.getEntries();              // returns TrackerEntry[]
tracker.reset();                   // clear all entries

advise(entries: TrackerEntry[]): AdvisorReport

Given tracked entries, suggests alternate strategies and estimates energy savings.

setModelCoefficient(model, whPerOutputToken, sizeClass, whPerInputToken?)

Override or add a coefficient for any model ID.

getCoefficients(model): { coefficients, source }

Look up the coefficient that would be used for a model.

listKnownModels(): string[]

List all model IDs with built-in coefficients.

Methodology appendix

The coefficient table lives in src/coefficients.ts. Each model's whPerOutputToken value is a rough estimate based on:

| Size class | Wh/output token | Basis | |---|---|---| | small (≤10B params) | ~0.0003–0.0004 | Luccioni et al. (2023) measurements of small models; Patterson et al. (2021) scaling | | medium (10–100B) | ~0.0012–0.0018 | Interpolation from Luccioni + de Vries (2023) growth curves | | large (100–200B) | ~0.0020–0.0025 | de Vries (2023) estimates for large dense models | | frontier (200B+, MoE-large) | ~0.0040–0.0055 | Extrapolation from Patterson/de Vries + public MoE size rumors |

Input tokens use 15% of the output coefficient by default (prefill is parallelized across the sequence, decode is sequential per token).

Cached/reused context is estimated at 10% of normal input cost (a rough approximation — actual savings depend on KV-cache implementation).

License

MIT