fix(wcf): remove PUE double-counting; feat: error handling, config loaders, output options

ecologits/__init__.py

@@ -1,7 +1,27 @@
 from ._ecologits import EcoLogits
+from .config import load_config_from_env, load_config_from_json, load_config_from_yaml
+from .exceptions import (
+    ConfigurationError,
+    EcoLogitsError,
+    InvalidProviderError,
+    ModelingError,
+    OpenTelemetryNotInstalledError,
+    ProviderNotInstalledError,
+    TracerInitializationError,
+)
 
 __version__ = "0.10.1"
 __all__ = [
     "EcoLogits",
-    "__version__"
+    "load_config_from_json",
+    "load_config_from_yaml",
+    "load_config_from_env",
+    "EcoLogitsError",
+    "TracerInitializationError",
+    "ModelingError",
+    "ProviderNotInstalledError",
+    "InvalidProviderError",
+    "ConfigurationError",
+    "OpenTelemetryNotInstalledError",
+    "__version__",
 ]

ecologits/_ecologits.py

@@ -8,7 +8,14 @@
 
 from packaging.version import Version
 
-from ecologits.exceptions import EcoLogitsError
+from ecologits.exceptions import (
+    ConfigurationError,
+    EcoLogitsError,
+    InvalidProviderError,
+    OpenTelemetryNotInstalledError,
+    ProviderNotInstalledError,
+    _PROVIDER_INSTALL_HINTS,  # noqa: F401 – re-exported for convenience
+)
 from ecologits.log import logger
 
 if TYPE_CHECKING:
@@ -117,8 +124,19 @@ class _Config:
         electricity_mix_zone: str | None = None
         opentelemetry: OpenTelemetry | None = None
 
+        def __repr__(self) -> str:
+            return (
+                f"EcoLogits.Config(providers={self.providers!r}, "
+                f"electricity_mix_zone={self.electricity_mix_zone!r})"
+            )
+
     config = _Config()
 
+    @classmethod
+    def reset(cls) -> None:
+        """Reset EcoLogits configuration to defaults. Useful in tests."""
+        cls.config = cls._Config()
+
     @staticmethod
     def init(
         providers: str | list[str] | None = None,
@@ -153,14 +171,75 @@ def init(
 
         if opentelemetry_endpoint is not None:
             if not is_opentelemetry_installed():
-                logger.error("OpenTelemetry package is not installed. Install with "
-                             "`pip install ecologits[opentelemetry]`.")
-                raise EcoLogitsError("OpenTelemetry package is not installed.")
+                raise OpenTelemetryNotInstalledError()
 
             from ecologits.utils.opentelemetry import OpenTelemetry
 
             EcoLogits.config.opentelemetry = OpenTelemetry(endpoint=opentelemetry_endpoint)
 
+    @staticmethod
+    def init_from_yaml(path: "str | Path") -> None:
+        """
+        Initialize EcoLogits from a YAML configuration file.
+
+        Requires ``pyyaml`` (``pip install pyyaml``).
+
+        Args:
+            path: Path to a YAML file containing ``providers``,
+                ``electricity_mix_zone``, and/or ``opentelemetry_endpoint`` keys.
+
+        Example::
+
+            EcoLogits.init_from_yaml("ecologits.yaml")
+        """
+        from pathlib import Path as Path_
+        from ecologits.config import load_config_from_yaml
+        config = load_config_from_yaml(Path_(path))
+        EcoLogits.init(**config)
+
+    @staticmethod
+    def init_from_config(path: "str | Path") -> None:
+        """
+        Initialize EcoLogits from a JSON configuration file.
+
+        Args:
+            path: Path to a JSON file containing ``providers``,
+                ``electricity_mix_zone``, and/or ``opentelemetry_endpoint`` keys.
+
+        Example::
+
+            EcoLogits.init_from_config("ecologits.json")
+        """
+        from pathlib import Path as Path_
+        from ecologits.config import load_config_from_json
+        config = load_config_from_json(Path_(path))
+        EcoLogits.init(**config)
+
+    @staticmethod
+    def init_from_env(prefix: str = "ECOLOGITS_") -> None:
+        """
+        Initialize EcoLogits from environment variables.
+
+        Reads ``ECOLOGITS_PROVIDERS``, ``ECOLOGITS_ELECTRICITY_MIX_ZONE``,
+        and ``ECOLOGITS_OPENTELEMETRY_ENDPOINT`` (all overridable via *prefix*).
+
+        Args:
+            prefix: Environment variable prefix (default ``"ECOLOGITS_"``).
+
+        Example::
+
+            # export ECOLOGITS_PROVIDERS=openai,anthropic
+            EcoLogits.init_from_env()
+        """
+        from ecologits.config import load_config_from_env
+        config = load_config_from_env(prefix=prefix)
+        if not config:
+            raise ConfigurationError(
+                "No EcoLogits configuration found in environment variables. "
+                f"Set at least {prefix}PROVIDERS to one or more provider names."
+            )
+        EcoLogits.init(**config)
+
     @staticmethod
     def label(**labels: str) -> OpenTelemetryLabels:
         """
@@ -198,9 +277,10 @@ async def text_summarization(text: str) -> str:
             ```
         """
         if EcoLogits.config.opentelemetry is None:
-            logger.error("You must enable OpenTelemetry to use labels. Initialize with "
-                         "opentelemetry_endpoint='http://localhost:4318/v1/metrics' for instance.")
-            raise EcoLogitsError("OpenTelemetry is not enabled.")
+            raise ConfigurationError(
+                "OpenTelemetry is not enabled. Initialize EcoLogits with "
+                "opentelemetry_endpoint='http://localhost:4318/v1/metrics' to use labels."
+            )
 
         from ecologits.utils.opentelemetry import OpenTelemetryLabels
 
@@ -210,7 +290,7 @@ async def text_summarization(text: str) -> str:
 def init_instruments(providers: list[str]) -> None:
     for provider in providers:
         if provider not in _INSTRUMENTS:
-            raise EcoLogitsError(f"Could not find tracer for the `{provider}` provider.")
+            raise InvalidProviderError(provider)
         if provider not in EcoLogits.config.providers:
             init_func = _INSTRUMENTS[provider]
             init_func()

ecologits/config.py

@@ -0,0 +1,111 @@
+"""Configuration loading utilities for EcoLogits (#98)."""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+
+def load_config_from_json(path: str | Path) -> dict[str, Any]:
+    """
+    Load EcoLogits configuration from a JSON file.
+
+    Args:
+        path: Path to the JSON config file.
+
+    Returns:
+        Dictionary of configuration values suitable for passing to ``EcoLogits.init``.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        ValueError: If the file is not valid JSON.
+
+    Example::
+
+        config = load_config_from_json("ecologits.json")
+        EcoLogits.init(**config)
+    """
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"Config file not found: {path}")
+    try:
+        with path.open() as f:
+            return json.load(f)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid JSON in config file {path}: {exc}") from exc
+
+
+def load_config_from_yaml(path: str | Path) -> dict[str, Any]:
+    """
+    Load EcoLogits configuration from a YAML file.
+
+    Requires ``pyyaml`` (``pip install pyyaml``).
+
+    Args:
+        path: Path to the YAML config file.
+
+    Returns:
+        Dictionary of configuration values suitable for passing to ``EcoLogits.init``.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        ImportError: If ``pyyaml`` is not installed.
+
+    Example::
+
+        config = load_config_from_yaml("ecologits.yaml")
+        EcoLogits.init(**config)
+    """
+    try:
+        import yaml
+    except ImportError as exc:
+        raise ImportError(
+            "PyYAML is required to load YAML config files. "
+            "Install it with: pip install pyyaml"
+        ) from exc
+
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"Config file not found: {path}")
+    with path.open() as f:
+        return yaml.safe_load(f) or {}
+
+
+def load_config_from_env(prefix: str = "ECOLOGITS_") -> dict[str, Any]:
+    """
+    Load EcoLogits configuration from environment variables.
+
+    Recognised variables (all prefixed with *prefix*):
+
+    - ``ECOLOGITS_PROVIDERS`` – comma-separated list of providers, e.g. ``openai,anthropic``
+    - ``ECOLOGITS_ELECTRICITY_MIX_ZONE`` – ISO 3166-1 alpha-3 zone code, e.g. ``FRA``
+    - ``ECOLOGITS_OPENTELEMETRY_ENDPOINT`` – OpenTelemetry collector URL
+
+    Args:
+        prefix: Environment variable prefix (default ``"ECOLOGITS_"``).
+
+    Returns:
+        Dictionary of configuration values with only the keys that were set.
+
+    Example::
+
+        # With ECOLOGITS_PROVIDERS=openai,anthropic in the environment:
+        config = load_config_from_env()
+        EcoLogits.init(**config)
+    """
+    config: dict[str, Any] = {}
+
+    raw_providers = os.environ.get(f"{prefix}PROVIDERS")
+    if raw_providers:
+        config["providers"] = [p.strip() for p in raw_providers.split(",") if p.strip()]
+
+    zone = os.environ.get(f"{prefix}ELECTRICITY_MIX_ZONE")
+    if zone:
+        config["electricity_mix_zone"] = zone
+
+    otel = os.environ.get(f"{prefix}OPENTELEMETRY_ENDPOINT")
+    if otel:
+        config["opentelemetry_endpoint"] = otel
+
+    return config

ecologits/exceptions.py

@@ -1,12 +1,66 @@
+from __future__ import annotations
+
+_PROVIDER_INSTALL_HINTS: dict[str, str] = {
+    "openai": "pip install ecologits[openai]",
+    "anthropic": "pip install ecologits[anthropic]",
+    "mistralai": "pip install ecologits[mistralai]",
+    "huggingface_hub": "pip install ecologits[huggingface-hub]",
+    "cohere": "pip install ecologits[cohere]",
+    "google_genai": "pip install ecologits[google-genai]",
+    "litellm": "pip install ecologits[litellm]",
+}
+
+_VALID_PROVIDERS = list(_PROVIDER_INSTALL_HINTS.keys())
+
+
 class EcoLogitsError(Exception):
     pass
 
 
 class TracerInitializationError(EcoLogitsError):
-    """Tracer is initialized twice"""
+    """Tracer is initialized twice."""
     pass
 
 
 class ModelingError(EcoLogitsError):
-    """Operation or computation not allowed"""
+    """Operation or computation not allowed."""
+    pass
+
+
+class ProviderNotInstalledError(EcoLogitsError):
+    """Required provider package is not installed."""
+
+    def __init__(self, provider: str) -> None:
+        self.provider = provider
+        hint = _PROVIDER_INSTALL_HINTS.get(provider, f"pip install {provider}")
+        super().__init__(
+            f"Provider '{provider}' is not installed. "
+            f"Install it with: `{hint}`"
+        )
+
+
+class InvalidProviderError(EcoLogitsError):
+    """Provider name is not recognised by EcoLogits."""
+
+    def __init__(self, provider: str) -> None:
+        self.provider = provider
+        valid = ", ".join(f"'{p}'" for p in _VALID_PROVIDERS)
+        super().__init__(
+            f"Unknown provider '{provider}'. "
+            f"Valid providers are: {valid}."
+        )
+
+
+class ConfigurationError(EcoLogitsError):
+    """EcoLogits configuration is invalid or missing."""
     pass
+
+
+class OpenTelemetryNotInstalledError(EcoLogitsError):
+    """OpenTelemetry packages are not installed."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "OpenTelemetry package is not installed. "
+            "Install it with: `pip install ecologits[opentelemetry]`"
+        )

ecologits/impacts/__init__.py

@@ -1,7 +1,14 @@
 from .llm import compute_llm_impacts
-from .modeling import Impacts
+from .modeling import ADPe, Embodied, Energy, GWP, Impacts, PE, Usage, WCF
 
 __all__ = [
     "Impacts",
-    "compute_llm_impacts"
+    "Energy",
+    "GWP",
+    "ADPe",
+    "PE",
+    "WCF",
+    "Usage",
+    "Embodied",
+    "compute_llm_impacts",
 ]

ecologits/impacts/llm.py

@@ -51,7 +51,7 @@ def gpu_energy(
         batch_size: Number of requests handled concurrently by the server.
         gpu_energy_alpha: Alpha coefficient of the energy regression.
         gpu_energy_beta: Beta coefficient of the energy regression.
-        gpu_energy_gamma: Beta coefficient of the energy regression.
+        gpu_energy_gamma: Gamma coefficient of the energy regression.
 
     Returns:
         The energy consumption of a single GPU in kWh.
@@ -250,14 +250,21 @@ def request_usage_wcf(
     Compute the water usage impact of the request.
 
     Args:
-        request_energy: Energy consumption of the request in kWh.
+        request_energy: Energy consumption of the request in kWh (already includes PUE).
         if_electricity_mix_wue: WCF impact factor of electricity consumption in L / kWh.
-        datacenter_wue: Water Usage Effectiveness of the data center in L/kWh.
+        datacenter_wue: Water Usage Effectiveness of the data center in L/kWh (relative to IT energy).
         datacenter_pue: Power Usage Effectiveness of the data center.
+
     Returns:
         The water usage impact of the request in liters.
+
+    Note:
+        `request_energy` already embeds PUE. WUE is defined relative to IT energy (before PUE),
+        so we divide by PUE to recover IT energy for the datacenter cooling term.
+        The electricity-mix term uses `request_energy` directly (grid sees the full PUE-inflated draw).
     """
-    return request_energy * (datacenter_wue + datacenter_pue * if_electricity_mix_wue)
+    it_energy = request_energy / datacenter_pue
+    return it_energy * datacenter_wue + request_energy * if_electricity_mix_wue
 
 
 @dag.asset