# Méthodologie - TokenClimate v3.3

**Version** : `v3.3-methodology-2026-07`
**Mise à jour** : 2026-07-08
**Statut** : document versionné, chaque modification produit une nouvelle version.

TokenClimate produit une estimation de l'impact environnemental de l'usage des LLM par équipe, sur trois grandeurs : l'énergie consommée (Wh), les émissions de gaz à effet de serre (gCO₂e) et la consommation d'eau estimée (mL). Ce ne sont pas des mesures, ce sont des estimations dérivées du volume de tokens consommés et de paramètres publics sourcés. Ce document décrit le périmètre, les hypothèses, les équations, les sources, les limites connues, et comment vérifier les valeurs.

## Cadrage normatif et périmètre

La méthodologie est fondée sur les principes ACV (ISO 14040), en approche **attributionnelle**, et alignée sur l'AFNOR Spec 2314 pour le tiers datacenter. Ce n'est pas une ACV complète vérifiée par tierce partie. La structure de ce document suit la check-list AFNOR Spec 2314 §4.1 :

| Exigence §4.1 | Section de ce document |
| --- | --- |
| Unité fonctionnelle | "Unité fonctionnelle" |
| Frontières du système | "Frontières du système" |
| Règles d'allocation | "Allocation" |
| Hypothèses et incertitudes (min-best-max) | "Paramètres Anthropic", "Hypothèses et incertitudes" |
| Localisation supposée | "Localisation supposée" |
| Sources et dates | tableaux de paramètres, "Versioning" |
| Renouvellement au moins annuel | "Versioning" |
| Méthode versionnée | "Versioning" |

### Unité fonctionnelle

Le **token**. Toutes les grandeurs sont exprimées par million de tokens (Mtok), déclinées par type de token (input non caché, cache write, cache read, output) et par famille de modèle.

### Frontières du système

Le périmètre couvert est le **tiers datacenter, inférence seule** :

- électricité IT des serveurs d'inférence, majorée du PUE (cooling et overhead datacenter) ;
- carbone embodied du matériel d'inférence (GPU + serveur hôte), amorti ;
- eau de refroidissement on-site (WUE) et eau incorporée dans l'électricité achetée (EWIF, off-site).

Sont **exclus** : les terminaux utilisateurs et les réseaux (respectivement ~50 % et ~4 % de l'empreinte du numérique en France selon le rapport Arcep de mai 2026 : le tiers datacenter n'est qu'une partie du tout), et l'**entraînement** des modèles (non alloué à l'inférence, répartition non publiée par Anthropic).

### Allocation

L'impact d'une infrastructure mutualisée est alloué au prorata de l'énergie IT attribuable aux tokens de la session. L'embodied est amorti sur 5 ans de service du matériel puis alloué au kWh IT. Les tokens des sous-agents Claude Code sont agrégés à la session parente (voir Caveats). Aucun offset, aucune compensation : les instruments de marché sont hors du calcul, conformément au SCI.

### Vocabulaire SCI (ISO/IEC 21031)

Le calcul se décrit dans le vocabulaire du Software Carbon Intensity for AI : un score de type **Consumer** (usage de l'inférence, pas l'entraînement), par token (R = le token). Les trois composantes sont publiées séparément et jamais fusionnées en un score opaque :

- **E** (énergie) : `energy_wh`, l'énergie IT estimée ;
- **I** (intensité) : `PUE × CIF`, en location-based ;
- **M** (embodied) : `EMB`, le terme matériel.

Soit `SCI = (E × I) + M` par token. Les offsets sont exclus par construction.

### Localisation supposée

On ne sait pas dans quelle région chaque requête est servie. L'hypothèse de localisation est **US multi-cloud, AWS-dominant** : le CIF retenu est le mix pondéré des régions AWS d'inférence (voir section suivante). Anthropic opère aussi sur GCP, Azure et Colossus, sans répartition publiée : on estime la sensibilité du CIF à cette inconnue à **±30 %**.

### Sur l'eau

On parle de **consommation d'eau estimée**, jamais d'« empreinte eau ». Une empreinte eau au sens ISO 14046 exigerait une caractérisation d'impact (par exemple AWARE, pondération par stress hydrique local), que la v3 ne fait pas faute de connaître la localisation des requêtes.

## Équations

Pour une session, avec les énergies `E_in` et `E_out` en Wh par million de tokens (énergie IT, côté serveur) :

```
energy_wh = (
    (input_tokens + cache_creation_tokens) * E_in
  + cache_read_tokens * E_in * 0.08
  + output_tokens * E_out
) / 1_000_000

co2_grams = energy_wh * (PUE * CIF + EMB)
water_ml  = energy_wh * (WUE + PUE * EWIF)
```

Avec les paramètres Anthropic de la section suivante, les constantes composites valent :

| Constante | Définition | Valeur |
| --- | --- | --- |
| K_usage | PUE × CIF (CO₂e opérationnel) | 0.32718 gCO₂e/Wh |
| K_co2 | PUE × CIF + EMB (CO₂e total) | 0.37118 gCO₂e/Wh |
| K_water | WUE + PUE × EWIF | 6.0054 mL/Wh |

L'embodied représente 11.9 % du CO₂e total (0.044 / 0.37118). Le CO₂e total vaut donc le CO₂e d'usage × 1.1345.

L'équation est implémentée dans `lib/co2.ts`, fonction `computeImpact`, qui retourne `{ energyWh, co2Grams, waterMl }`. Les trois valeurs sont stockées par ligne d'usage (`energy_wh`, `co2_grams`, `water_ml`). Le coût USD est calculé à part (voir "Coût USD").

### Exemple

Une session Sonnet avec 50 000 tokens d'input, 200 000 de cache write, 3 000 000 de cache read et 30 000 d'output :

```
energy_wh = (250_000 * 119 + 3_000_000 * 119 * 0.08 + 30_000 * 2525) / 1e6
          = 134.06 Wh
co2_grams = 134.06 * 0.37118 = 49.76 g   (usage 43.86 g + embodied 5.90 g)
water_ml  = 134.06 * 6.0054  = 805.1 mL
```

## Paramètres Anthropic

Bloc `params` de `lib/providers/seed/anthropic.json`. Source primaire épinglée : Jegham N., Abdelatti M., Hendawi A., "How Hungry is AI? Benchmarking Energy, Water, and Carbon Footprint of LLM Inference", arXiv:2505.09598, **version v6, Table 1**.

Tiers de source : T1 = mesure ou rapport primaire publié, T2 = dérivation documentée à partir de sources T1, T3 = estimation d'ingénierie.

| Paramètre | Best | Plage (min-max) | Source | Tier |
| --- | ---: | --- | --- | --- |
| PUE | 1.14 | non publiée | Jegham v6 Table 1 (datacenters AWS) | T1 |
| CIF (location-based) | 0.287 kgCO₂e/kWh | ±30 % (localisation) | Jegham v6 Table 1, via Electricity Maps, pondéré par les régions AWS d'inférence | T1 |
| WUE on-site | 0.18 L/kWh | non publiée | Amazon 2023 Sustainability Report | T1 |
| EWIF off-site | 5.11 L/kWh | non publiée | WRI 2024, "Guidance for calculating water use embedded in purchased electricity" | T1 |
| EMB (embodied) | 44 gCO₂e/kWh IT | 22-66 (amortissement 3-6 ans) | dérivé : NVIDIA PCF HGX H100 (1312 kgCO₂e/baseboard) + serveur hôte BoaviztAPI (5700 kgCO₂e), amorti 5 ans | T2 |
| cache_read_factor | 0.08 | 0.05-0.15 (borne dure 0-0.20) | résidu de relecture KV en décodage, voir "Énergie du cache" | T3 |
| E_in / E_out (Anthropic) | ~1/21 | 1/26 à 1/4 | récupéré du fit OLS 3 points sur les mesures Jegham v6, voir "Le ratio input/output" | T2 |

### Pin de version sur la source primaire

Le CIF a changé pendant la vie du papier source : 0.385 kgCO₂e/kWh jusqu'à la v4, 0.287 depuis la v5 (sourcé Electricity Maps). La valeur utilisée ici est épinglée sur la **v6, Table 1**. À noter : 0.287 n'est pas « le mix électrique global », c'est un mix pondéré par les régions AWS d'inférence (« mix-weighted across AWS inference regions »).

## Énergie par famille de modèle

Source : `lib/providers/seed/anthropic.json`, bloc `energy` par modèle. Valeurs en Wh par million de tokens, énergie IT.

| Modèle | E_in (Wh/Mtok) | E_out (Wh/Mtok) | Provenance |
| ------ | -------------: | --------------: | ---------- |
| Fable  | 476 | 10100 | Extrapolé (2x Opus, proxy prix) |
| Opus   | 238 |  5050 | Extrapolé (2x Sonnet, proxy paramètres + prix) |
| Sonnet | 119 |  2525 | Fit OLS 3 points sur Jegham v6 (classe Sonnet mesurée) |
| Haiku  |  61 |  1262 | Extrapolé (0.5x Sonnet) |

Recalibration 2026-07 : les trois énergies par requête mesurées par Jegham v6 pour Claude 3.7 Sonnet (0.950 / 2.989 / 5.671 Wh, PUE inclus) sont ajustées par régression OLS passant par l'origine, ce qui donne les facteurs d'usage 39/826 gCO₂e/Mtok du plugin OSS ; les énergies IT ci-dessus en sont dé-compoundées (E = facteur / (PUE × CIF), arrondi à l'entier). La calibration précédente (`tokenclimate-v3-2026-06`, Sonnet 580/3480) reposait sur les composites pré-v6 (190/1140). Ces énergies restent alignées sur celles du plugin open source claude-carbon (même auteur), un contrôle automatique hebdomadaire vérifie la cohérence à ±0.5 %.

### Le ratio input/output

Depuis la recalibration v6, le ratio n'est plus une hypothèse : il est **récupéré du fit** sur les trois points mesurés, soit ~21:1 output:input (2525 vs 119 Wh/Mtok pour Sonnet). Un long contexte ajoute peu d'énergie par rapport au même volume de tokens générés, ce qu'un ratio plat bas manquerait. Pour les providers non-Anthropic dont l'énergie input n'est pas mesurée (énergies EcoLogits, qui ne publie que du output, ou fit Jegham dont le coefficient d'input est forcé à 0 par NNLS), la convention E_in = E_out/6 reste appliquée : la littérature publie des ratios de E_out/26 à E_out/4, et E_out/6 reste un choix conservateur dans la moitié haute de cette plage.

### Le cas Fable

Aucune source publique ne documente la taille ou l'énergie de Fable 5 / Mythos 5. L'ancre retenue est le **proxy prix** : 2x Opus, le ratio des prix publics (10/50 vs 5/25). À réviser dès qu'une estimation indépendante est publiée.

## Énergie du cache (cache_read_factor = 0.08)

Un token `cache_read` est un token de contexte déjà traité dont les tenseurs key/value sont réutilisés : son compute de prefill est évité. Il n'est pas gratuit pour autant : pendant le décodage, chaque token généré relit l'intégralité du KV cache depuis la HBM, tokens cachés inclus (GreenCache, SIGMETRICS : "caching does not reduce computation in the decode phase"). L'énergie d'un token caché est donc le résidu de lecture KV en phase de décodage qui survit au caching.

Aucune étude ne mesure directement le ratio énergie cache_read / input. La valeur par défaut de **0.08** (plage défendable 0.05-0.15, borne dure 0-0.20) est une estimation d'ingénierie dérivée de mesures adjacentes : le prefill représente au plus 3.4 % de l'énergie totale d'inférence sur des workloads de génération (Solovyeva & Castor), un KV cache plus gros amplifie l'énergie de décodage par token de 1.3 à 51.8 %, et l'énergie par token triple environ entre 2K et 10K de contexte (TokenPowerBench, H100). Le facteur dépend du workload et croît avec la longueur de contexte ; une constante plate sous-estime les très longs préfixes réutilisés.

Ce facteur n'est **pas** le ratio de facturation 0.1x d'Anthropic. C'est un prix, pas une mesure d'énergie (OpenAI facture le même mécanisme à 0.5x). Mettre `cache_read_factor` à 0 serait une borne basse défendable, mais traiterait un system prompt de 100K tokens réutilisé comme neutre en carbone, ce qui ignore un coût réel de bande passante mémoire.

Sources : GreenCache (arXiv:2505.23970), TokenPowerBench (arXiv:2512.03024), Solovyeva & Castor (arXiv:2602.05712), From Prompts to Power (arXiv:2511.05597).

Le facteur vit dans `lib/providers/seed/anthropic.json` (clé `cacheReadFactor`) et est exposé par `lib/providers/registry.ts`.

## Dual reporting : location-based et market-based

Le CO₂e affiché par défaut est **location-based** : l'intensité carbone du réseau électrique réel des régions où l'inférence tourne. C'est l'exigence de l'AFNOR Spec 2314 (§4.3) et du SCI, qui excluent les instruments de marché (PPA, RECs, offsets) du score.

Le market-based est publié à titre de comparaison, jamais comme valeur par défaut :

- **Google 2024** : 94 gCO₂e/kWh market-based vs 345 location-based (arXiv:2508.15734). L'écart 3.7x montre ce que les instruments de marché masquent.
- **AWS** (l'hypothèse de localisation dominante de TokenClimate) : revendique un matching 100 % renouvelable, mais déclare 2.80 MtCO₂e de scope 2 market-based résiduel en 2024 et **ne publie aucun facteur kg/kWh market-based**. La valeur market-based AWS est donc « non publiée par AWS ». On n'écrira jamais « market-based = 0 ».

## Providers tiers (EcoLogits + Jegham v6)

TokenClimate est construit multi-provider (OpenAI, Google, Mistral, DeepSeek, Meta), même si le produit vendu est Claude-first. Google et Mistral restent entièrement sourcés depuis **EcoLogits 0.10.2** (repo mlco2/ecologits, release du 2026-06-04, version épinglée) : PUE google 1.09, mistral 1.16, énergies output dérivées de leur modèle paramétrique (par exemple gpt-4o : 1676 Wh/Mtok IT, encore sourcé EcoLogits, voir OpenAI ci-dessous). La famille `gemini-1.5-*` est **absente** d'EcoLogits 0.10.2 : ses valeurs restent marquées `tokenclimate-manual` avec une confiance `low`.

OpenAI et DeepSeek ont été recalibrés en 2026-07 sur **Jegham et al. v6, Table 1 et Table 4** (la même source primaire que les paramètres Anthropic) :

- **OpenAI**, infra : PUE 1.12, CIF 0.35 kgCO₂e/kWh, WUE on-site 0.30 L/kWh, EWIF off-site 4.35 L/kWh (Table 1, ligne OpenAI/Azure, verbatim). Corrige une citation erronée de cette même Table 1 dans le seed précédent (PUE 1.20, CIF 0.3844, EWIF 3.13 : seul le WUE on-site était juste). Énergies : gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini et o3-mini restent sourcés EcoLogits (confiance `low`, architectures non publiées) ; o3, o4-mini, gpt-4.1-nano, gpt-4-turbo et o1 passent en mesure directe Table 4 (fit OLS 3 points, même méthode que le seed Anthropic). o3 et gpt-4-turbo ont un fit propre à deux coefficients (confiance `high`) ; o4-mini, gpt-4.1-nano et o1 donnent un coefficient d'input négatif sous contrainte, forcé à 0 par NNLS, d'où `E_in = E_out/6` et une confiance `medium`.
- **DeepSeek**, infra : PUE 1.27, CIF 0.6 kgCO₂e/kWh, WUE on-site 1.20 L/kWh, EWIF off-site 6.016 L/kWh (Table 1, ligne DeepSeek/China, verbatim) - remplace les anciens chiffres génériques « colo Chine / IEA » (PUE 1.30, CIF 0.555, WUE 0.18, EWIF 3.13), dont le WUE on-site était sous-estimé d'environ 7x. Énergies : `deepseek-chat` et `deepseek-reasoner` ne sont plus des estimations manuelles, ce sont des mesures directes Table 4 sur les rows DS (China-hosted, l'API réellement facturée par ces modèles) : 6940 et 17442 Wh/Mtok en sortie, confiance `high`. Le fit NNLS force aussi le coefficient d'input à 0 pour les deux modèles, d'où `E_in = E_out/6`.

**Meta** (nouveau provider) : `llama-3.1-8b-instant` et `llama-3.3-70b-versatile`, mesurés Table 4 avec un fit propre à deux coefficients (pas de convention E_in = E_out/6 ici). Groq, l'hébergeur tarifé, ne publie ni PUE ni mix électrique : la décompression utilise un PUE générique 1.2 (placeholder mi-gamme hyperscale, non spécifique à Groq), et le CIF/WUE/EWIF sont proxés depuis la ligne AWS/Anthropic de la Table 1 (0.287 kgCO₂e/kWh, 0.18 L/kWh, 5.11 L/kWh) faute de mieux. Confiance `medium` : PUE et grille non sourcés pour Groq, infra de mesure Jegham (GPU) différente du matériel de service réel (LPU Groq).

Le ratio `E_in = E_out/6` et le `cache_read_factor` 0.08 appliqués à ces providers non-Anthropic sont des **extensions TokenClimate**, quelle que soit la source de l'énergie output (EcoLogits ou Jegham).

## Coût USD

Le coût est la valeur API théorique de l'usage (ce qu'il coûterait en pay-as-you-go), pas le prix d'abonnement réellement payé. Tarif public Anthropic en vigueur au 2026-06-12, en USD par million de tokens, tier 1, hors discount Entreprise négocié.

| Modèle | Input ($/Mtok) | Output ($/Mtok) | Cache write (1.25x) | Cache read (0.1x) |
| ------ | -------------: | --------------: | ------------------: | ----------------: |
| Fable  |             10 |              50 |                12.5 |                 1 |
| Opus   |              5 |              25 |                6.25 |               0.5 |
| Sonnet |              3 |              15 |                3.75 |               0.3 |
| Haiku  |              1 |               5 |                1.25 |               0.1 |

Note : Opus 4.6+ est à 5/25. Les 15/75 mentionnés dans la v1 de ce document correspondaient aux Opus 4.0/4.1, retirés du catalogue.

Pour une session :

```
cost_usd = (
    input_tokens * input_price
  + cache_creation_tokens * (input_price * 1.25)
  + cache_read_tokens * (input_price * 0.1)
  + output_tokens * output_price
) / 1_000_000
```

Implémenté dans `lib/co2.ts`, fonction `co2ToCostUsd`, arrondi à 4 décimales. Les prix cache par modèle sont matérialisés dans `lib/providers/seed/anthropic.json` (`cacheWriteUsdPerMtok`, `cacheReadUsdPerMtok`). Sur des données dédupliquées, ce calcul se réconcilie à quelques pourcents près avec ccusage.

## Comptage des tokens et déduplication

Les comptes viennent du parsing des transcripts JSONL (`message.usage`). Les messages assistant sont dédupliqués par `(message.id, requestId)` en gardant la dernière occurrence, avant sommation. C'est nécessaire parce que les sessions reprises ou compactées rejouent les messages précédents dans le même fichier, et que le streaming réécrit le même message plusieurs fois avec un `output_tokens` croissant. Sans dédup, la somme brute sur-compte d'environ 3x. Ce comportement correspond à la déduplication effectuée par ccusage.

## Modèles exclus (non Anthropic)

Claude Code peut être pointé vers des modèles non Anthropic (par exemple un modèle local derrière `ANTHROPIC_BASE_URL`). Leur profil d'impact n'est pas celui d'un datacenter AWS : ni les énergies ni le pricing API ne s'appliquent. Les sessions dont le modèle dominant ne contient pas `claude` (y compris le marqueur `<synthetic>`) ne sont pas poussées par le CLI.

## Équivalences affichées

Pour rendre les unités tangibles, le dashboard affiche des équivalences. Toutes sont sourcées :

- **Eau** : douches de 60 L (équivalence primaire affichée, `round(water_ml / 60_000)`, fonction `waterToShowers` de `lib/co2.ts` ; en dessous d'une douche, aucune équivalence n'est affichée).
- **CO₂e, voiture** : 120 gCO₂e par kilomètre, 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)`, fonction `co2ToCarKm` de `lib/co2.ts`.
- **CO₂e, prompt de référence** : un prompt Gemini médian émet 0.09 gCO₂e en location-based (Google 2025, arXiv:2508.15734).

## Hypothèses et incertitudes

Les plages min-best-max par paramètre sont dans le tableau "Paramètres Anthropic". Les leviers dominants sur le chiffre final, par ordre d'importance estimé :

- **cache_read_factor (0.08)** : les cache reads représentent plus de 90 % des tokens en usage Claude Code intensif. Plage 0.05-0.15, soit environ -40 %/+90 % sur le terme cache.
- **Localisation (±30 % sur le CIF)** : répartition AWS/GCP/Azure/Colossus non publiée par Anthropic.
- **E_out Fable** : proxy prix sans aucune mesure publiée, sur la famille la plus chère du catalogue.
- **E_in = E_out/6 (providers non-Anthropic)** : plage publiée E_out/26 à E_out/4, choix dans la moitié haute. Pour Anthropic, le ratio ~1/21 est récupéré du fit v6, ce n'est plus une hypothèse libre.
- **EMB (44)** : sensibilité 22-66 selon l'amortissement (3-6 ans).

## Annexe : ADPe (informationnel)

L'épuisement des ressources abiotiques, éléments (ADPe) est le troisième indicateur prioritaire de l'AFNOR Spec 2314 (priorité 1). La v3 le documente à titre informationnel : pas de colonne en base, pas d'UI.

Usage : `adpe = energy_kwh × 9.855e-8 kgSbeq/kWh` (facteur ADEME Base Empreinte, via EcoLogits). Par million de tokens, sur les énergies IT v3 :

| Modèle | ADPe input (kgSbeq/Mtok) | ADPe output (kgSbeq/Mtok) |
| ------ | -----------------------: | ------------------------: |
| Fable  | 4.7e-8 | 1.0e-6 |
| Opus   | 2.3e-8 | 5.0e-7 |
| Sonnet | 1.2e-8 | 2.5e-7 |
| Haiku  | 6.0e-9 | 1.2e-7 |

Ce terme ne couvre que la part « usage » (électricité). La part fabrication de l'ADPe, dominante pour cet indicateur, demanderait une ACV matérielle complète que la v3 ne fait pas.

## Caveats

Ce qu'on ne mesure pas, et pourquoi.

- **Ordre de grandeur seulement**. Ces chiffres sont des estimations structurées et sourcées, pas un bilan réglementaire ni une ACV vérifiée.
- **Périmètre tiers datacenter, inférence seule**. Terminaux (~50 % de l'empreinte du numérique en France), réseaux (~4 %) et entraînement sont exclus (rapport Arcep, mai 2026).
- **L'énergie du cache_read est une estimation dérivée, pas une mesure**. C'est le levier le plus important du chiffre final.
- **Pas de couverture géo-spécifique**. CIF appliqué uniformément, sensibilité ±30 % à la localisation réelle.
- **Fable est une extrapolation prix**. Aucune mesure publiée, à réviser dès publication indépendante (Epoch AI ou équivalent).
- **L'embodied est une dérivation**, pas une donnée constructeur de bout en bout : PCF NVIDIA + BoaviztAPI, amorti 5 ans, sensibilité 22-66 gCO₂e/kWh.
- **L'eau est une consommation estimée**, pas une empreinte ISO 14046 : pas de pondération par stress hydrique local.
- **Market-based AWS non publié**. AWS ne publie pas de facteur kg/kWh market-based : on l'écrit tel quel, on n'affiche jamais zéro.
- **Pas de session annulée**. Une session interrompue 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 au modèle dominant de celle-ci (voir `cli/scripts/persist-and-push.sh`). Petite approximation quand un sous-agent tourne sur une autre famille Claude.
- **Historique antérieur au 2026-06-12**. Les lignes ingérées avant cette date portent un `input_tokens` qui inclut les cache writes, et leur co2/coût ne comptait pas le terme cache_read. Elles sont conservées telles quelles (légère sous-estimation).

## Comment vérifier

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

```bash
tokenclimate org status
```

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

Toutes les énergies, tous les paramètres et tous les prix utilisés sont publiés dans ce document, avec leurs sources. Des vecteurs de test donnent des valeurs attendues exactes pour `energy_wh`, `co2_grams` et `water_ml`, rejouées en CI à chaque changement. Aucune valeur n'est calculée côté client opaque.

## Recomputabilité

Chaque ligne `usage_events` conserve ses composantes brutes (input, output, cache write, cache read) : `energy_wh`, `co2_grams`, `water_ml` et `cost_usd` restent re-dérivables à tout moment depuis la méthodologie courante. Après un changement de paramètres ou de pricing, `pnpm recompute:co2` (script `scripts/recompute-co2.ts`, dry-run par défaut, `--apply` pour écrire) recalcule tout l'historique avec les fonctions de `lib/co2.ts` et restampe `factor_version`. Les lignes dont le modèle ne résout pas dans le registry gardent un impact null, jamais inventé.

## Versioning

La version courante est `v3.3-methodology-2026-07`. Les paramètres sont renouvelés **au moins une fois par an** (exigence AFNOR Spec 2314), et plus tôt si une source épinglée bouge : nouvelle version de Jegham et al., release EcoLogits, publication d'une mesure Fable, facteur market-based AWS. Chaque évolution produit une nouvelle version de ce document.

L'outil EcoLogits, épinglé ici en release 0.10.2, est cité par la fiche MiNumEco de novembre 2025, dont l'exigence de mesure prend plein effet en août 2026. Les formulations livrées avec le Bilan IA renvoient à cette section pour vérification.

Historique :

- `v3.3-methodology-2026-07` : ajout d'un paragraphe reliant explicitement EcoLogits (release épinglée) à la fiche MiNumEco de novembre 2025, citée par les formulations du Bilan IA ; aucun changement méthodologique.
- `v3.2-methodology-2026-07` : recalibration DeepSeek (mesures directes Jegham v6 DS-native) et OpenAI (Table 1 verbatim), ajout du provider Meta.
- `v3.1-methodology-2026-07` : recalibration des énergies Anthropic sur le fit OLS 3 points de Jegham v6 (Sonnet 119/2525 Wh/Mtok, précédemment 580/3480) ; le ratio input/output Anthropic devient une valeur mesurée (~1/21) au lieu de la convention 1/6 ; Opus passe de 3x à 2x Sonnet. Prix, paramètres infra, cache_read_factor et formules inchangés.
- `v3.0-methodology-2026-06` : passage énergie-first (Wh/Mtok + paramètres infra), ajout eau et embodied.

## Contact

Vous contestez une valeur, un paramètre, une hypothèse ? Écrivez à [gaetan.wittebolle@gmail.com](mailto:gaetan.wittebolle@gmail.com) ou [réservez un échange](https://app.lemcal.com/@gwittebolle/30-minutes). 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.