carbongate 0.7.2

Shift-left carbon analysis for Terraform — suggests lower-carbon cloud regions in pull requests.

🌱 CarbonGate

Shift-left carbon analysis for Terraform. Suggests lower-carbon cloud regions right in your Pull Requests.

🇫🇷 Lire en français

---

CarbonGate is a deterministic, zero-token, zero-latency CLI tool that analyzes Terraform infrastructure diffs and recommends AWS regions with lower carbon intensity — before you merge.

The Sweet Spot

You give away the software (free, open-source, runs on their own CI runner). You sell the data (fresh Parquet feed with real-time carbon intensity from emissions.dev). No dashboards. No LLM hallucinations. Just a YAML file, a ruthless parser, a DuckDB engine faster than electricity, and a gate (the data) that you control.

For buyers & sales calls

One-page pitch (FR), demo script, pricing summary, objections: docs/SALES_ONE_PAGER.md · product sheet: docs/FICHE_PRODUIT.md.

For executives (FR)

IMPACT© methodology — audit framework, ROI ranges, CSRD scope, 3× fee-back guarantee.
IMPACT Pre-Scan — qualification 1 repo + call 30 min → livrable 1 page (gratuit sous conditions).
Case study #0 — public terraform-aws-vpc demo (~86 % modeled carbon savings eu-west-1 → eu-north-1; not a paying client).
Trigger events playbook — CSRD / FinOps signals, CFO outreach, CHASE prioritization.
Executive audit template: gtm/templates/audit_report_exec.md · KPI Shield: CFO / CTO.

---

How It Works

Developer pushes Terraform on GitHub
        │
        ▼
GitHub Action triggers (ubuntu-latest)
        │
        ├── 1. Parse diff → extract AWS regions (regex, <0.1s)
        ├── 2. Query DuckDB over Parquet → find lowest-carbon alternative in same zone (0.01s)
        ├── 3. If savings ≥ 30%, format Markdown PR comment
        └── 4. Post comment via GitHub API

No API call per PR run. The intelligence is baked into the Parquet file. Your compute cost: $0.00.

Quick Start

pip install carbongate
carbongate --diff-file path/to/pr.diff
carbongate --hcl-file main.tf --tfvars-file terraform.tfvars  # optional
carbongate --plan-json plan.json             # terraform plan -json
carbongate --plan-json plan.json --json      # machine-readable output

# New in v0.6.0
carbongate --region eu-west-1               # analyze a single region directly
carbongate --list-regions                   # show all 28 supported regions
carbongate --region eu-west-1 --output-format csv  # CSV export for spreadsheets

# New in v0.7.0 — Graph Algorithms, TimeSeries, Predict & Dashboard
carbongate graph --algorithm pagerank       # identify backbone regions
carbongate graph --algorithm migration-priority  # composite migration ranking
carbongate graph --algorithm shortest-path --region eu-west-1 --target eu-west-3

# Predict cost savings from migrating to a lower-carbon region
carbongate predict --from eu-west-1 --to eu-north-1 --monthly-cost 2000 --months 12
carbongate predict --diff-file pr.diff --monthly-cost 2000   # batch-analyze all regions in diff
carbongate predict --report --monthly-cost 2000 --json         # CFO report across all 28 regions

# Generate an interactive HTML dashboard
carbongate dashboard --serve --port 8080

# New in v0.7.1 — Cache metrics & Prometheus
carbongate predict --report --json | python -c "from carbongate.query_engine import get_cache_metrics, get_prometheus_metrics; print(get_cache_metrics())"

Install with MCP support: pip install carbongate[mcp]

Agent-native usage (MCP)

CarbonGate exposes an MCP server for AI agents (Claude, Cursor, etc.):

carbongate serve

Configure your MCP client:

{
  "mcpServers": {
    "carbongate": {
      "command": "carbongate",
      "args": ["serve"]
    }
  }
}

Tools exposed:

Tool	Input	Description
analyze_plan	plan_json_path	Analyze a terraform plan -json file for carbon savings
analyze_diff	diff_path + tfvars_path? + threshold_pct?	Analyze a git diff file for carbon savings
suggest_region	region	Get the best lower-carbon alternative for an AWS region

JSON output is versioned (schema_version: 1) for agent workflow stability. JSON Schema available for automated validation.

MCP example: analyze a diff

# Agent calls via MCP — no shell required
analyze_diff(
    diff_path="/path/to/terraform.diff",
    tfvars_path="/path/to/terraform.tfvars",  # optional: resolves var.region
    threshold_pct=20.0                         # optional: lower threshold
)
# → {"schema_version": 1, "suggestions": [{"current_region": "us-east-1", ...}]}

From source (dev):

git clone https://github.com/carbongate/carbongate.git && cd carbongate
pip install -e ".[dev]"
carbongate --diff-file tests/fixtures/sample.diff

Regenerate carbon data (optional): EMISSIONS_DEV_API_KEY=em_live_xxxx python data_packer.py

Output Example

## 🌱 CarbonGate Shift-Left Analysis

⚠️ **Optimization detected** for your infrastructure deployment:

- **Current Region:** `us-east-1` (Carbon: 322.0 gCO₂eq/kWh)
- **Suggested Region:** `us-west-2` (Carbon: 122.5 gCO₂eq/kWh)

💰 **Estimated Carbon Savings:** `62.0%`
📉 **Spot Price Multiplier:** `0.8x` (Lower is cheaper)

> 💡 **Action:** Consider updating your Terraform config to use the suggested
> region(s) and reduce both carbon footprint and cloud costs.

Architecture

carbongate/
├── data_packer.py       # Polars → Fetches real CI from emissions.dev, writes Parquet
├── query_engine.py      # DuckDB in-process: get_best_alternative(region) → dict
│                         #   + batch_get_best_alternatives() (batch API, ~200 µs for 28 regions)
│                         #   + _TimedLRUCache (TTL 300 s, maxsize 64) + Prometheus metrics
├── tf_parser.py         # Deterministic regex + plan JSON: extract AWS regions
├── judge.py             # Decision engine: ≥30% savings threshold, Markdown + JSON
├── carbongate_cli.py     # Typer CLI entry point (carbongate analyze / serve / graph / predict / dashboard)
├── mcp_server.py        # MCP server for AI agent integration (3 tools + 7 graph algorithms)
├── graph_algorithms.py  # PageRank, betweenness, Louvain, shortest path, migration priority
├── timeseries.py        # Historical CI tracking, cost prediction, compound effect
├── dashboard_generator.py  # Interactive HTML dashboard with visualizations
├── dream_cycle.py       # Nightly cron automation: batch migration analysis + briefing generation
├── entrypoint.sh        # GitHub Action entrypoint (fetches diff via API)
├── Dockerfile           # python:3.12-slim, ready for GitHub Actions
├── action.yml           # GitHub Action definition
├── pyproject.toml       # Package metadata (pip install .)
└── data/
    ├── eu/eu_carbon.parquet    # EU region carbon data
    └── us/us_carbon.parquet    # US region carbon data

Module Dependency Graph

                    ┌─────────────┐
                    │ carbongate_cli │  Typer CLI (analyze / serve / graph / predict / dashboard)
                    └──────┬──────┘
                           │
              ┌────────────▼────────────┐
  diff.txt ──►│        judge.py        │  Decision engine (≥30% threshold)
  plan.json ─►│   (analyze_diff /      │  Markdown + JSON formatter
              │    analyze_plan)         │
              └────┬──────────────┬─────┘
                   │              │
         ┌────────▼──┐     ┌────▼──────────┐
         │ tf_parser │     │ query_engine   │  DuckDB over Parquet
         └───────────┘     │  + _TimedLRUCache + batch API
                          └────┬────────────┘
                               │
                    ┌──────────▼──────────┐
                    │   data_packer.py    │  Polars → Parquet
                    │   emissions.dev     │  Real CI data
                    └─────────────────────┘

  ┌─────────────────────────────────────────────────────────────┐
  │  Ancillary modules (not in core pipeline)                   │
  │  ├── graph_algorithms.py — PageRank, betweenness, ...     │
  │  ├── timeseries.py      — predict_cost_savings()          │
  │  ├── dashboard_generator.py — HTML dashboard                │
  │  └── dream_cycle.py     — nightly cron + briefing         │
  └─────────────────────────────────────────────────────────────┘

Data Flow

emissions.dev API (real CI data)
        │
        ▼
data_packer.py ─── Polars DataFrame ───► data/{eu,us}/*.parquet
                                              │
                                              ▼
query_engine.py ─── DuckDB read_parquet() ───► get_best_alternative()
                                              │
                                              ▼
tf_parser.py ─── extract regions from diff ──► judge.py ──► Markdown PR comment

Region coverage

Detected in PR diff	Notes
Literal region = "eu-west-1"	provider, resources, locals
availability_zone	Mapped to region when possible
region = var.region	Resolved if terraform.tfvars / --tfvars-file sets region or aws_region
Auto tfvars	terraform.tfvars, *.auto.tfvars, *.tfvars next to input file

Not covered (yet): unresolved var.region without tfvars, hourly carbon scheduling.

See Infracost integration, PyPI publish checklist, and sales one-pager (demo commands, pricing, objections).

Supported Regions

Region	Provider	Country	Data Source	Best EU/US pair (feed)	Typical savings
eu-west-1	AWS	Ireland	emissions.dev (IE)	→ eu-north-1	~86%
eu-west-2	AWS	United Kingdom	emissions.dev (GB)	→ eu-north-1	~84%
eu-west-3	AWS	France	emissions.dev (FR)	→ eu-north-1	~17% (below threshold)
eu-central-1	AWS	Germany	emissions.dev (DE)	→ eu-north-1	~90%
eu-north-1	AWS	Sweden	emissions.dev (SE)	already optimal	—
us-east-1	AWS	Virginia	eGRID 2023 (×0.92)	→ us-west-2	~62%
us-east-2	AWS	Ohio	eGRID 2023 (×1.25)	→ us-west-2	~72%
us-west-1	AWS	California	eGRID 2023 (×0.55)	→ us-west-2	~36%
us-west-2	AWS	Oregon	eGRID 2023 (×0.35)	already optimal	—
us-central1	GCP	Iowa	eGRID 2023 (×0.90)	→ us-west-2 (AWS)	~72%
us-east1	GCP	South Carolina	eGRID 2023 (×0.88)	→ us-west-2 (AWS)	~73%
europe-west1	GCP	Belgium	emissions.dev (BE)	→ eu-north-1 (AWS)	~85%
europe-north1	GCP	Finland	emissions.dev (FI)	already optimal	—
eastus	Azure	Virginia	eGRID 2023 (×0.92)	→ us-west-2 (AWS)	~62%
westus2	Azure	Washington	eGRID 2023 (×0.30)	already optimal	—
northeurope	Azure	Ireland	emissions.dev (IE)	→ eu-north-1 (AWS)	~86%
swedencentral	Azure	Sweden	emissions.dev (SE)	already optimal	—

Savings are vs the lowest-carbon region in the same zone (EU or US), using the bundled Parquet feed. See query_engine.get_best_alternative().

30% savings threshold

CarbonGate only posts a PR comment when estimated carbon savings are ≥ 30% (SAVINGS_THRESHOLD_PCT in judge.py, overridable with --threshold). This avoids noisy suggestions for marginal gains.

Silent output is expected, not a bug, when:

• The region is already near-optimal in its zone (e.g. eu-west-3 at ~42 gCO₂eq/kWh vs eu-north-1 at ~35 → ~17% savings, below threshold).
• No resolvable region in the diff (e.g. var.region without tfvars, or only removed lines).

Example — eu-west-3 (no suggestion):

carbongate --diff-file tests/fixtures/eu-west-3-only.diff

🔍 Analyzing diff for carbon optimization opportunities...
✅ No carbon optimization detected (all regions within 30% of optimal).

Example — eu-west-1 (suggestion emitted):

carbongate --diff-file gtm/audits/terraform-aws-vpc/audit_input.diff

## 🌱 CarbonGate Shift-Left Analysis
...
💰 **Estimated Carbon Savings:** `86.4%`

CLI options

Command / Flag	Description
analyze --diff-file	Git diff from PR
analyze --hcl-file	Static .tf scan (synthetic diff)
analyze --plan-json	terraform plan -json / terraform show -json output
analyze --tfvars-file	Explicit tfvars (repeatable); also auto-discovered
analyze --threshold	Min savings % to comment (default 30)
analyze --api-key	Fresh Parquet from emissions.dev
analyze --json	Machine-readable JSON output (all input modes)
analyze --output-format csv	CSV export for spreadsheets
analyze --region	Analyze a single cloud region directly
analyze --list-regions	List all 28 supported regions
serve	Start MCP server for AI agent integration
graph --algorithm	Run graph algorithms (pagerank, betweenness, louvain, shortest-path, migration-priority)
predict --from --to	Predict cost & carbon savings from migrating
predict --diff-file	Batch-analyze all regions in a diff
predict --report	CFO report across all 28 regions
dashboard --serve	Generate interactive HTML dashboard

Configuration

Variable	Required	Description
EMISSIONS_DEV_API_KEY	No	emissions.dev API key (free: 500 req/month). Without it, uses realistic mock data.

Using the Action (published vs local)

Published (after release on GitHub):

- uses: carbongate/carbongate@v0.2
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    api-key: ${{ secrets.CARBONGATE_API_KEY }}

Same repository (development):

- uses: ./
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}

See GitHub Marketplace checklist.

GitHub Action Setup

Add to .github/workflows/carbongate.yml (or use cost + carbon with Infracost):

name: CarbonGate Analysis
on:
  pull_request:
    paths:
      - '**/*.tf'
      - '**/*.tfvars'

jobs:
  carbongate:
    runs-on: ubuntu-latest
    steps:
      - uses: carbongate/carbongate@v0.2
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          api-key: ${{ secrets.CARBONGATE_API_KEY }}

Tech Stack

Component	Technology	Why
Data processing	Polars	Zero-copy, columnar, faster than Pandas
Query engine	DuckDB	In-process OLAP, reads Parquet in <1ms
CLI	Typer	Type-safe Click wrapper
Data format	Apache Parquet	Compressed columnar, 2MB per zone
Data source	emissions.dev	Free tier, annual CI per country + cloud region
Packaging	Docker / pip	GitHub Action + PyPI ready (85 pytest)

Performance

• Parse diff: <0.1s (regex)
• Query DuckDB: <0.01s (in-memory Parquet)
• Batch query (28 regions): ~200 µs (cached)
• End-to-end: <0.2s
• API calls per PR run: 0 (data pre-baked in Parquet)
• Compute cost per PR: $0.00

Cache Performance

The DuckDB query engine uses a _TimedLRUCache (maxsize=64, TTL=300 s) to avoid redundant Parquet reads:

from carbongate.query_engine import get_cache_metrics

print(get_cache_metrics())
# {'hits': 42, 'misses': 2, 'entries': 2, 'hit_rate': 95.45,
#  'avg_lookup_us': 0.234, 'evictions': 0}

Prometheus exposition format (get_prometheus_metrics()) can be exposed on a /metrics endpoint for scraping.

License

MIT

---

CarbonGate — Analyse Carbone Shift-Left pour Terraform

🇫🇷 Français

CarbonGate est un outil CLI déterministe, zéro-token, zéro-latence qui analyse les diffs d'infrastructure Terraform et recommande des régions AWS avec une intensité carbone plus faible — avant le merge.

Le Sweet Spot

Tu donnes le logiciel (gratuit, open-source, tourne sur leur propre runner CI). Tu vends la donnée (feed Parquet frais avec l'intensité carbone temps réel d'emissions.dev). Pas de dashboards. Pas d'hallucinations LLM. Juste un fichier YAML, un parser impitoyable, un moteur DuckDB plus rapide que l'électricité, et une porte d'entrée (la donnée) que tu contrôles.

Comment ça marche

Le développeur pousse du Terraform sur GitHub
        │
        ▼
GitHub Action se déclenche (ubuntu-latest)
        │
        ├── 1. Parse le diff → extrait les régions AWS (regex, <0.1s)
        ├── 2. Interroge DuckDB sur le Parquet → trouve l'alternative la moins carbonée dans la même zone (0.01s)
        ├── 3. Si économies ≥ 30%, formate un commentaire Markdown PR
        └── 4. Poste le commentaire via l'API GitHub

Aucun appel API par exécution de PR. L'intelligence est pré-cuite dans le fichier Parquet. Ton coût compute : 0,00 €.

Démarrage Rapide

git clone https://github.com/carbongate/carbongate.git
cd carbongate
pip install -e ".[dev]"
export EMISSIONS_DEV_API_KEY=em_live_xxxx    # Gratuit sur https://emissions.dev
python data_packer.py
carbongate --diff-file chemin/vers/terraform.diff

# Analyse batch de toutes les régions (~200 µs)
carbongate predict --report --monthly-cost 2000 --json

# Graph algorithms
carbongate graph --algorithm pagerank

# Dashboard interactif
carbongate dashboard --serve

Architecture

carbongate/
├── data_packer.py       # Polars → Récupère CI réelle d'emissions.dev, écrit Parquet
├── query_engine.py      # DuckDB in-process : get_best_alternative(region) → dict
│                         #   + batch_get_best_alternatives() (batch API, ~200 µs pour 28 régions)
│                         #   + _TimedLRUCache (TTL 300 s, maxsize 64) + métriques Prometheus
├── tf_parser.py         # Regex déterministe : extrait les régions du diff git
├── judge.py             # Moteur de décision : seuil ≥30%, formatage Markdown + JSON
├── carbongate_cli.py    # Point d'entrée CLI Typer (analyze / serve / graph / predict / dashboard)
├── mcp_server.py        # Serveur MCP pour intégration agent IA (3 tools + 7 graph algorithms)
├── graph_algorithms.py  # PageRank, betweenness, Louvain, shortest path, migration priority
├── timeseries.py        # Historique CI, prédiction de coûts, compound effect
├── dashboard_generator.py  # Dashboard HTML interactif avec visualisations
├── dream_cycle.py       # Automation nocturne : analyse batch + génération de briefing
├── entrypoint.sh        # Entrypoint GitHub Action
├── Dockerfile           # python:3.12-slim, prêt pour GitHub Actions
├── action.yml           # Définition GitHub Action
├── pyproject.toml       # Métadonnées package (pip install .)
└── data/
    ├── eu/eu_carbon.parquet
    └── us/us_carbon.parquet

Régions supportées

Région AWS	Pays	Source données	Meilleur pair (feed)	Économie typique
eu-west-1	Irlande	emissions.dev (IE)	→ eu-north-1	~86 %
eu-west-2	Royaume-Uni	emissions.dev (GB)	→ eu-north-1	~84 %
eu-west-3	France	emissions.dev (FR)	→ eu-north-1	~17 % (sous seuil)
eu-central-1	Allemagne	emissions.dev (DE)	→ eu-north-1	~90 %
eu-north-1	Suède	emissions.dev (SE)	déjà optimal	—
us-east-1	Virginie	eGRID 2023 (×0.92)	→ us-west-2	~62 %
us-east-2	Ohio	eGRID 2023 (×1.25)	→ us-west-2	~72 %
us-west-1	Californie	eGRID 2023 (×0.55)	→ us-west-2	~36 %
us-west-2	Oregon	eGRID 2023 (×0.35)	déjà optimal	—

Seuil 30 %

CarbonGate ne commente une PR que si l'économie carbone estimée est ≥ 30 % (SAVINGS_THRESHOLD_PCT dans judge.py). Exemple : eu-west-3 (~42 gCO₂eq/kWh) vs eu-north-1 (~35) → ~17 % → sortie silencieuse (« No carbon optimization detected »), pas un bug.

---

AI / LLM / Agent Usage

For AI Agents (Claude Code, Cursor, Copilot, etc.)

CarbonGate is designed to be operated by AI agents as well as humans. The codebase follows these agent-friendly conventions:

1. Single-file modules: each .py file is a self-contained module with a clear single responsibility
2. Type-safe: all public functions use TypedDict or explicit return types
3. Deterministic: zero LLM calls in the pipeline; everything is regex + SQL
4. Silent on success: functions return None when there's nothing to report; no spam
5. Idempotent: data_packer.py can be re-run safely; query_engine.py reads latest data
6. Mock fallback: works without API keys for dev/testing

For LLM Context Windows

When an AI agent reads this project, the optimal files to load are:

Priority	File	Purpose
1	README.md	This file — architecture overview
2	pyproject.toml	Dependencies and entry points
3	cli.py	Understand the CLI surface
4	judge.py	Decision logic + Markdown format
5	query_engine.py	DuckDB query patterns
6	tf_parser.py	Region extraction regex
7	data_packer.py	Data pipeline (only if modifying data sources)

llms.txt

# CarbonGate — Shift-left carbon analysis for Terraform
# Architecture (12 files, ~1800 lines)

## Core Pipeline
carbongate_cli.py: Typer CLI (analyze, serve, graph, predict, dashboard)
judge.py: Decision engine (≥30% savings threshold), Markdown + JSON formatter
tf_parser.py: hcl2 + regex + plan JSON recursive; tfvars; var.region resolution
query_engine.py: DuckDB in-process query engine over Parquet carbon data
                 + _TimedLRUCache (TTL 300s, maxsize 64) with Prometheus metrics
                 + batch_get_best_alternatives() — 2 queries for all 28 regions
                 + get_cache_metrics() / get_prometheus_metrics()

## Graph & TimeSeries
graph_algorithms.py: PageRank, betweenness, Louvain, shortest path, migration priority
timeseries.py: predict_cost_savings(), compare_regions_history(), get_compound_value()
dashboard_generator.py: Interactive HTML dashboard with carbon visualizations

## Agent Integration
mcp_server.py: FastMCP server — 3 core tools + 7 graph algorithms
               Entry point: carbongate serve or carbongate-serve
               JSON output: schema_version: 1 envelope

## Data Pipeline
data_packer.py: Polars-based ETL. Fetches real CI from emissions.dev API, falls back to mock data.
                 Reads EMISSIONS_DEV_API_KEY from env. Writes data/{eu,us}/*.parquet.

## Nightly Automation
dream_cycle.py: run_batch_migration_analysis() — top 10 + per-provider best
                generate_briefing() — Markdown morning briefing
                Cron-ready: sys.path guarded, PYTHONPATH in subprocess

## Deployment
action.yml: GitHub Action definition (docker-based)
entrypoint.sh: Extracts PR diff via GitHub API, runs carbongate (supports INPUT_PLAN_JSON_FILE)
Dockerfile: python:3.12-slim with curl, jq, duckdb, polars
pyproject.toml: Package metadata, dependencies, entry points (carbongate, carbongate-serve)

## Data
data/eu/eu_carbon.parquet: EU region carbon intensity (5 AWS + 5 GCP + 9 Azure regions)
data/us/us_carbon.parquet: US region carbon intensity (4 AWS + 4 GCP + 3 Azure regions)

## External APIs
emissions.dev /v1/electricity/grid: country-level grid carbon intensity (free tier: 500 req/month)
GitHub REST API: POST /repos/{owner}/{repo}/issues/{pr_number}/comments

## Key Design Decisions
- Annual average CI (not real-time): structural advantage matters more than hourly fluctuations for infra decisions
- No LLM calls in pipeline: purely deterministic (regex + SQL)
- Data pre-baked as Parquet: zero API calls per PR run, $0 compute cost for user
- Multi-cloud region → country mapping: static table, no runtime lookups
- 30% savings threshold: avoids noisy suggestions for marginal improvements
- Provider isolation: GCP users never see AWS alternatives (and vice versa)
- Cache invalidation on set_data_dir(): prevents stale data after API refresh

---

Competitor Landscape (2026)

Tool	Position	CarbonGate Advantage
Infracost + InfraCarbon	PR comments, closed backend	Open-source CLI, Parquet data feed, no dashboard lock-in
CarbonAware	Scheduling, K8s/Airflow	Pre-merge analysis, not post-deploy
Cloud Carbon Footprint	Post-deploy reporting dashboard	Shift-left: catch it before merge
Climatiq	General carbon API	Deprecated cloud endpoint (Sep 2026)

---

Built with ❤️ and DuckDB.