Metadata-Version: 2.4
Name: llm-carbon-calculator
Version: 0.2.0
Summary: Calculate CO2 emissions from LLM API calls following Green Software Foundation standards.
Project-URL: Homepage, https://pypi.org/project/llm-carbon-calculator/
Author: Alexandre Domingues
License-Expression: MIT
License-File: LICENSE
Keywords: azure-openai,carbon,co2,emissions,green-software,llm,sustainability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://sci-guide.greensoftware.foundation/).

---

## 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

```bash
pip install llm-carbon-calculator
```

---

## Quick Start

```python
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

```python
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

```python
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

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

### Attach metadata

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

```python
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

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

# Run tests
pytest tests/ -v
```

---

## License

[MIT](LICENSE)
