Méthodologie — lievito v1.0

Version : v1.0-methodology-2026-05 Mise à jour : 2026-05-16 Statut : ce document est versionné dans le git du repo. Tag : v1.0-methodology-2026-05.

lievito produit une estimation de l'empreinte CO₂e de l'usage Claude Code par équipe. Ce ne sont pas des mesures, ce sont des estimations dérivées du volume de tokens consommés et d'un facteur d'émission par modèle. Ce document décrit les hypothèses, les sources, l'équation, les limites connues, et comment vérifier les valeurs.

Hypothèses

L'unité de comptage est le token. Pour chaque session Claude Code (un cycle prompt-réponse complet, déclenché côté CLI via le hook Stop) on récupère trois valeurs :

• input_tokens : tokens du prompt utilisateur + contexte injecté
• output_tokens : tokens générés par le modèle
• cache_read_input_tokens : tokens servis depuis le cache Anthropic, exclus du calcul (voir caveats)

À chaque famille de modèle (opus, sonnet, haiku) on associe deux facteurs en gCO₂e par million de tokens, un pour l'input et un pour l'output. Les valeurs viennent de lib/co2-factors.json et sont reproduites plus bas.

Source primaire

Jegham N., Abdelatti M., Hendawi A. (2025), "How Hungry is AI? Benchmarking Energy, Water, and Carbon Footprint of LLM Inference", arXiv:2505.09598. Le papier benchmark l'inférence de plusieurs LLM grand public sur infrastructure AWS et produit un facteur composite couvrant l'électricité serveur, le cooling et l'overhead datacenter.

Constantes retenues de ce papier :

• PUE AWS : 1.14 (Power Usage Effectiveness moyen des datacenters AWS 2024-2025)
• Carbon Intensity Factor (CIF) : 0.287 kgCO₂e par kWh, qui correspond au mix électrique global pondéré par la répartition des régions AWS où Claude est servi en production

Ces valeurs représentent un worst case géographique. Un dev qui consomme du Claude depuis Paris ne paie pas un CIF français, il paie le CIF du datacenter qui sert l'inférence (potentiellement US East). C'est pour cette raison qu'on conserve le mix global et pas le mix français.

Source alternative ADEME (V2)

L'ADEME publie pour la France un facteur d'émission moyen du mix électrique à 0.057 kgCO₂e par kWh, soit environ 5 fois moins que le CIF global utilisé en V1. Une prochaine version supportera un override ADEME pour les équipes qui font tourner l'inférence sur un compute européen (par exemple via Bedrock région eu-central-1). Pour l'instant, V1 prend le worst case et la valeur affichée doit être lue comme une borne haute.

Équation

Pour une session :

co2_grams = (input_tokens * input_factor + output_tokens * output_factor) / 1_000_000

Avec input_factor et output_factor en gCO₂e par million de tokens, puisés selon le modèle. L'équation est implémentée dans lib/co2.ts, fonction computeCo2Grams, et le résultat est arrondi à 3 décimales (correspond au type numeric(12, 3) côté schéma).

Valeurs par modèle

Source : lib/co2-factors.json. Les valeurs ci-dessous sont en gCO₂e par million de tokens.

Les facteurs output sont environ 6 fois plus élevés que les facteurs input parce que la génération token-par-token est dominée par les passes de décodage autoregressives, là où l'input est traité en une seule passe parallélisable.

Coût USD

Le coût est calculé séparément à partir du tarif public Anthropic en vigueur au moment de l'écriture de cette méthodologie. Les valeurs sont en USD par million de tokens, tier 1, hors discount Entreprise négocié.

Pour une session :

cost_usd = (input_tokens * input_price + output_tokens * output_price) / 1_000_000

Implémenté dans lib/co2.ts, fonction co2ToCostUsd, arrondi à 4 décimales.

Équivalence kilomètres voiture

Le dashboard affiche aussi une équivalence "km voiture" pour rendre l'unité gCO₂e tangible. Le facteur utilisé est 120 gCO₂e par kilomètre, qui correspond au facteur ADEME pour une voiture particulière européenne moyenne (well-to-wheel, mix essence-diesel-hybride pondéré).

car_km = round(co2_grams / 120)

Implémenté dans lib/co2.ts, fonction co2ToCarKm.

Caveats

Ce qu'on ne mesure pas, et pourquoi.

• cache_read non comptabilisé. Les tokens servis depuis le cache Anthropic ne sont pas facturés (côté API) et leur coût énergétique marginal est négligeable (lecture mémoire, pas d'inférence). Les inclure surestimerait l'empreinte sans justification physique.
• Pas de couverture inference géo-spécifique. On ne sait pas dans quelle région AWS chaque requête Claude a été servie. On applique uniformément le CIF global de 0.287 kgCO₂e par kWh. Une org qui aurait visibilité sur sa répartition région via l'API Admin Anthropic pourra dans une future version overrider ce facteur.
• Pas de scope 3 Anthropic upstream. Le facteur Jegham 2025 couvre l'usage opérationnel (électricité + cooling du compute d'inférence). Il ne couvre pas l'embodied carbon des GPU H100, le training initial des modèles amorti sur leur lifetime d'inférence, ni l'overhead réseau end-user.
• Pas de session annulée. Une session interrompue par l'utilisateur avant la fin de la génération compte les tokens déjà générés, conformément à l'usage facturé Anthropic.
• Subagents agrégés au parent. Si Claude Code lance des sous-agents pendant une session, leurs tokens sont sommés dans la session parente (voir cli/scripts/persist-and-push.sh).

Comment vérifier

Le CLI lievito expose une commande qui montre les valeurs locales avant push, identiques à ce qui sera ingéré côté dashboard :

lievito org status

Vous y verrez par session : input_tokens, output_tokens, cache_creation_tokens, modèle détecté, et le co2_grams calculé localement. Si vous voulez auditer le calcul end-to-end, comparez avec le détail session affiché sur /employee/[id] du dashboard.

Le fichier lib/co2-factors.json est public et lisible directement dans le repo. Aucune valeur n'est calculée côté client opaque.

Versioning

Ce document est versionné dans le git, sous docs/methodology.md. La version courante est tagguée v1.0-methodology-2026-05. Les futures évolutions (override ADEME, scope 3, refresh des facteurs Jegham) seront tracées dans CHANGELOG.md et bumperont le tag.

Contact

Vous contestez une valeur, un facteur, une hypothèse ? Écrivez à gaetan.wittebolle@gmail.com ou réservez un échange. Les corrections argumentées sont les bienvenues, le but n'est pas de défendre les chiffres mais d'avoir la meilleure estimation possible avec les données disponibles.