# earth-now.co
# Author:  Simon-Pierre Boucher
# Contact: contact@spboucher.ai
# File:    packages/registry/metrics/energy.yaml
# Purpose: MVP energy metrics (catalog §6, 🥇) — electricity produced, renewable share, coal burned, oil pumped

metrics:
  - id: electricity_ytd
    name: { fr: "Électricité produite cette année", en: "Electricity generated this year" }
    domain: energy
    priority: mvp
    kind: cumulative
    level: 1
    model: seasonal-ytd-v1
    unit: MWh
    sources:
      - id: ember_2025
        name: "Ember — Global Electricity Review / monthly data"
        url: https://ember-energy.org/
        license: "CC BY 4.0"
        cadence: monthly
      - id: iea_electricity
        name: "IEA Electricity"
        url: https://www.iea.org/data-and-statistics
        license: "CC BY 4.0"
        cadence: yearly
    refresh: on_source_update
    display:
      decimals: 2
      sigFigs: 5
      scale: 0.000001
      unit: { fr: "TWh", en: "TWh" }
    constraints: { maxAbsRatePerSec: 2000, maxJumpOnRefit: 20000000 }
    windows: [ytd, today, session]

  - id: renewable_share
    name:
      fr: "Part renouvelable de l'électricité"
      en: "Renewable share of electricity"
    domain: energy
    priority: mvp
    kind: stock
    level: 2
    model: seasonal-spline-v2
    unit: percent
    sources:
      - id: ember_2025
        name: "Ember — Global Electricity Review"
        url: https://ember-energy.org/
        license: "CC BY 4.0"
        cadence: monthly
    refresh: on_source_update
    display:
      decimals: 1
      sigFigs: 3
      unit: { fr: "%", en: "%" }
    constraints: { maxAbsRatePerSec: 0.000001, maxJumpOnRefit: 0.5 }
    windows: [total]
    editorialNote:
      fr: "v0.1 : tendance annuelle lissée — la saisonnalité intra-annuelle (hydro, solaire) sera ajoutée avec les données mensuelles Ember."
      en: "v0.1: smoothed annual trend — intra-year seasonality (hydro, solar) lands with Ember monthly data."

  - id: coal_burned_ytd
    name: { fr: "Charbon brûlé cette année", en: "Coal burned this year" }
    domain: energy
    priority: mvp
    kind: cumulative
    level: 1
    model: seasonal-ytd-v1
    unit: t
    sources:
      - id: iea_coal
        name: "IEA Coal / Energy Institute Statistical Review"
        url: https://www.iea.org/reports/coal-2024
        license: "CC BY 4.0"
        cadence: yearly
    refresh: on_source_update
    display:
      decimals: 0
      sigFigs: 4
      unit: { fr: "tonnes", en: "tonnes" }
    constraints: { maxAbsRatePerSec: 600, maxJumpOnRefit: 10000000 }
    windows: [ytd, today, session]

  - id: oil_pumped_ytd
    name: { fr: "Pétrole pompé cette année", en: "Oil pumped this year" }
    domain: energy
    priority: mvp
    kind: cumulative
    level: 1
    model: seasonal-ytd-v1
    unit: barrels
    sources:
      - id: eia_opec
        name: "US EIA / OPEC monthly reports"
        url: https://www.eia.gov/
        license: "US Government public domain"
        cadence: monthly
    refresh: on_source_update
    display:
      decimals: 0
      sigFigs: 5
      unit: { fr: "barils", en: "barrels" }
    constraints: { maxAbsRatePerSec: 2500, maxJumpOnRefit: 50000000 }
    windows: [ytd, today, session]

  - id: solar_installed_ytd
    name: { fr: "Capacité solaire installée cette année", en: "Solar capacity installed this year" }
    domain: energy
    priority: v1
    kind: cumulative
    level: 1
    model: seasonal-ytd-v1
    unit: W
    sources:
      - id: irena_bnef
        name: "IRENA / BloombergNEF — annual solar additions"
        url: https://www.irena.org/Data
        license: "IRENA open data — citation required"
        licenseNote: "verify reuse terms before launch"
        cadence: yearly
    refresh: on_source_update
    display:
      decimals: 0
      sigFigs: 4
      scale: 0.001
      unit: { fr: "kW", en: "kW" }
    constraints: { maxAbsRatePerSec: 30000, maxJumpOnRefit: 5000000000 }
    windows: [session, today, ytd]
    editorialNote:
      fr: "~600 GW ajoutés en 2026 (IRENA/BNEF), pic d'installations en fin d'année modélisé — regardez la fenêtre « depuis votre arrivée »."
      en: "~600 GW added in 2026 (IRENA/BNEF), year-end installation rush modelled — watch the 'since you arrived' window."