llm-carbon-calculator 0.2.0

Calculate CO2 emissions from LLM API calls following Green Software Foundation standards.

llm-carbon-calculator

A lightweight, dependency-free Python library for estimating the carbon footprint of Large Language Model (LLM) API usage, following the Green Software Foundation SCI methodology.

---

Features

• Zero runtime dependencies
• Accepts total_api_requests and total_llm_tokens as inputs
• Outputs:
  • Total Emissions — total carbon emissions in kgCO2eq
  • Avg per Request — average emissions per API call (gCO2eq / request)
  • Weighted Carbon Intensity — energy-weighted average across multiple regions (gCO2eq / kWh)
• Multi-region support for Azure deployments
• JSON-ready API output via to_api_dict()

---

Installation

pip install llm-carbon-calculator

---

Quick Start

from llm_emissions import CarbonCalculator

calc = CarbonCalculator(
    total_api_requests=1_000,
    total_llm_tokens=500_000,
)

result = calc.calculate(region_intensity=156)

print(result.total_emissions_kg)        # kgCO2eq
print(result.avg_per_request_g)         # gCO2eq / request
print(result.weighted_carbon_intensity) # gCO2eq / kWh
print(result)                           # pretty-printed summary

Custom energy factor

calc = CarbonCalculator(
    total_api_requests=1_000,
    total_llm_tokens=500_000,
    model_energy_factor=0.000112,  # kWh per 1000 tokens
)
result = calc.calculate(region_intensity=156)

Multi-region weighted intensity

from llm_emissions.models import RegionEnergyInfo

calc = CarbonCalculator(
    total_api_requests=2_000,
    total_llm_tokens=400_000,
)
result = calc.calculate(
    region_intensity=156,
    regions=[
        RegionEnergyInfo(region_name="westeurope", tokens=300_000, region_intensity=156),
        RegionEnergyInfo(region_name="eastus",     tokens=100_000, region_intensity=380),
    ],
)
print(result.weighted_carbon_intensity)  # energy-weighted average

JSON API response

import json
print(json.dumps(result.to_api_dict(), indent=2))

Attach metadata

Extra keyword arguments are stored in result.metadata for traceability:

result = calc.calculate(
    region_intensity=156,
    model="gpt-4o",
    region="westeurope",
)
print(result.metadata)  # {'model': 'gpt-4o', 'region': 'westeurope'}

---

Formula

Based on the SCI (Software Carbon Intensity) specification:

emission_g = (tokens / 1000) × energy_factor × region_intensity × PUE

Parameter	Default	Description
PUE	1.125	Power Usage Effectiveness
model_energy_factor	0.000056	kWh per 1000 tokens (GPT-4o)
region_intensity	—	gCO2eq/kWh of the cloud region

---

API Reference

CarbonCalculator(total_api_requests, total_llm_tokens, model_energy_factor=0.000056, pue=1.125)

Parameter	Type	Description
total_api_requests	int	Number of LLM API requests. Must be a positive integer.
total_llm_tokens	int	Total tokens (input + output). Must be a positive integer.
model_energy_factor	float	Energy in kWh per 1000 tokens. Default: 0.000056 (GPT-4o).
pue	float	Power Usage Effectiveness. Default: 1.125.

.calculate(region_intensity, *, regions=None, **metadata) → EmissionsResult

Parameter	Type	Description
region_intensity	float	Grid carbon intensity (gCO2eq/kWh).
regions	list[RegionEnergyInfo]	Optional multi-region breakdown.
**metadata	any	Arbitrary key-value pairs stored in the result.

.calculate_as_dict(...) → dict

Same parameters as .calculate(). Returns a JSON-serialisable dictionary.

EmissionsResult

Attribute	Type	Description
total_emissions_kg	float	Total emissions in kgCO2eq.
avg_per_request_g	float	Average emissions per request (gCO2eq).
weighted_carbon_intensity	float	Energy-weighted intensity (gCO2eq/kWh).
total_energy_kwh	float	Operational energy consumed (kWh).
total_api_requests	int	Echo of the input.
total_llm_tokens	int	Echo of the input.
metadata	dict	Extra key-value pairs passed to calculate().

RegionEnergyInfo

Attribute	Type	Description
region_name	str	Region identifier (e.g. "westeurope").
tokens	int	Tokens processed in this region.
region_intensity	float	Grid intensity for this region (gCO2eq/kWh).

---

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

---

License

MIT