codecarbon 3.2.5__tar.gz → 3.2.6__tar.gz

{codecarbon-3.2.5 → codecarbon-3.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecarbon
-Version: 3.2.5
+Version: 3.2.6
 Author: Mila, DataForGood, BCG GAMMA, Comet.ml, Haverford College
 License-Expression: MIT
 Project-URL: Homepage, https://codecarbon.io/
@@ -52,8 +52,8 @@ Estimate and track carbon emissions from your computer, quantify and analyze the
 
 CodeCarbon websites:
 - [Main website](https://codecarbon.io) to learn why we do this.
-- [Dashboard](https://dashboard.codecarbon.io/) to see your emissions, [read the API doc](https://mlco2.github.io/codecarbon/api.html) before.
-- [Documentation](https://mlco2.github.io/codecarbon) to learn how to use the package and our methodology.
+- [Dashboard](https://dashboard.codecarbon.io/) to see your emissions, [read the API doc](https://docs.codecarbon.io/latest/getting-started/api/) before.
+- [Documentation](https://docs.codecarbon.io) to learn how to use the package and our methodology.
 - [GitHub](https://github.com/mlco2/codecarbon) to look at the source code and contribute.
 - [Discord](https://discord.gg/GS9js2XkJR) to chat with us.
 
@@ -99,7 +99,7 @@ We created a Python package that estimates your hardware electricity power consu
 
 ![calculation Summary](docs/images/calculation.png)
 
-We explain more about this calculation in the [**Methodology**](https://mlco2.github.io/codecarbon/methodology.html#) section of the documentation.
+We explain more about this calculation in the [**Methodology**](https://docs.codecarbon.io/latest/introduction/methodology/) section of the documentation.
 
 Our hope is that this package will be used widely for estimating the carbon footprint of computing, and for establishing best practices with regards to the disclosure and reduction of this footprint.
 
@@ -121,7 +121,7 @@ conda activate your_env
 pip install codecarbon
 ```
 
-To see more installation options please refer to the documentation: [**Installation**](https://mlco2.github.io/codecarbon/installation.html#)
+To see more installation options please refer to the documentation: [**Installation**](https://docs.codecarbon.io/latest/getting-started/installation/)
 
 ## Start to estimate your impact 📏
 
@@ -175,7 +175,7 @@ def your_function_to_track():
   ```
 The package will track the emissions generated by the execution of your function.
 
-There is other ways to use **codecarbon** package, please refer to the documentation to learn more about it:  [**Usage**](https://mlco2.github.io/codecarbon/usage.html#)
+There is other ways to use **codecarbon** package, please refer to the documentation to learn more about it:  [**Usage**](https://docs.codecarbon.io/latest/getting-started/usage/)
 
 ## Visualize 📊
 
@@ -189,7 +189,7 @@ You can now visualize your experiment emissions on the [dashboard](https://dashb
 > - cloud mode
 > - comet integration...
 >
-> Please explore the [**Documentation**](https://mlco2.github.io/codecarbon) to learn about it
+> Please explore the [**Documentation**](https://docs.codecarbon.io/) to learn about it
 > If ever what your are looking for is not yet implemented, let us know through the *issues* and even better become one of our 🦸🏼‍♀️🦸🏼‍♂️ contributors! more info 👇🏼
 
 
@@ -201,7 +201,7 @@ You are welcome to open issues, even suggest solutions and better still contribu
 
 In order to contribute a change to our code base, please submit a pull request (PR) via GitHub and someone from our team will go over it and accept it.
 
-Check out our [contribution guidelines :arrow_upper_right:](https://github.com/mlco2/codecarbon/blob/master/CONTRIBUTING.md)
+Check out our [contribution guidelines :arrow_upper_right:](https://github.com/mlco2/codecarbon/blob/master/docs/contributing/CONTRIBUTING.md)
 
 Feel free to chat with us on [Discord](https://discord.gg/GS9js2XkJR).
 

{codecarbon-3.2.5 → codecarbon-3.2.6}/README.md

@@ -4,8 +4,8 @@ Estimate and track carbon emissions from your computer, quantify and analyze the
 
 CodeCarbon websites:
 - [Main website](https://codecarbon.io) to learn why we do this.
-- [Dashboard](https://dashboard.codecarbon.io/) to see your emissions, [read the API doc](https://mlco2.github.io/codecarbon/api.html) before.
-- [Documentation](https://mlco2.github.io/codecarbon) to learn how to use the package and our methodology.
+- [Dashboard](https://dashboard.codecarbon.io/) to see your emissions, [read the API doc](https://docs.codecarbon.io/latest/getting-started/api/) before.
+- [Documentation](https://docs.codecarbon.io) to learn how to use the package and our methodology.
 - [GitHub](https://github.com/mlco2/codecarbon) to look at the source code and contribute.
 - [Discord](https://discord.gg/GS9js2XkJR) to chat with us.
 
@@ -51,7 +51,7 @@ We created a Python package that estimates your hardware electricity power consu
 
 ![calculation Summary](docs/images/calculation.png)
 
-We explain more about this calculation in the [**Methodology**](https://mlco2.github.io/codecarbon/methodology.html#) section of the documentation.
+We explain more about this calculation in the [**Methodology**](https://docs.codecarbon.io/latest/introduction/methodology/) section of the documentation.
 
 Our hope is that this package will be used widely for estimating the carbon footprint of computing, and for establishing best practices with regards to the disclosure and reduction of this footprint.
 
@@ -73,7 +73,7 @@ conda activate your_env
 pip install codecarbon
 ```
 
-To see more installation options please refer to the documentation: [**Installation**](https://mlco2.github.io/codecarbon/installation.html#)
+To see more installation options please refer to the documentation: [**Installation**](https://docs.codecarbon.io/latest/getting-started/installation/)
 
 ## Start to estimate your impact 📏
 
@@ -127,7 +127,7 @@ def your_function_to_track():
   ```
 The package will track the emissions generated by the execution of your function.
 
-There is other ways to use **codecarbon** package, please refer to the documentation to learn more about it:  [**Usage**](https://mlco2.github.io/codecarbon/usage.html#)
+There is other ways to use **codecarbon** package, please refer to the documentation to learn more about it:  [**Usage**](https://docs.codecarbon.io/latest/getting-started/usage/)
 
 ## Visualize 📊
 
@@ -141,7 +141,7 @@ You can now visualize your experiment emissions on the [dashboard](https://dashb
 > - cloud mode
 > - comet integration...
 >
-> Please explore the [**Documentation**](https://mlco2.github.io/codecarbon) to learn about it
+> Please explore the [**Documentation**](https://docs.codecarbon.io/) to learn about it
 > If ever what your are looking for is not yet implemented, let us know through the *issues* and even better become one of our 🦸🏼‍♀️🦸🏼‍♂️ contributors! more info 👇🏼
 
 
@@ -153,7 +153,7 @@ You are welcome to open issues, even suggest solutions and better still contribu
 
 In order to contribute a change to our code base, please submit a pull request (PR) via GitHub and someone from our team will go over it and accept it.
 
-Check out our [contribution guidelines :arrow_upper_right:](https://github.com/mlco2/codecarbon/blob/master/CONTRIBUTING.md)
+Check out our [contribution guidelines :arrow_upper_right:](https://github.com/mlco2/codecarbon/blob/master/docs/contributing/CONTRIBUTING.md)
 
 Feel free to chat with us on [Discord](https://discord.gg/GS9js2XkJR).
 

codecarbon-3.2.6/codecarbon/_version.py

@@ -0,0 +1 @@
+__version__ = "3.2.6"

{codecarbon-3.2.5 → codecarbon-3.2.6}/codecarbon/cli/cli_utils.py

@@ -5,6 +5,8 @@ from typing import Optional
 import typer
 from rich.prompt import Confirm
 
+from codecarbon.core.config import get_hierarchical_config
+
 
 def get_config(path: Optional[Path] = None):
     p = path or Path.cwd().resolve() / ".codecarbon.config"
@@ -37,22 +39,16 @@ def get_api_endpoint(path: Optional[Path] = None):
     return "https://api.codecarbon.io"
 
 
-def get_existing_local_exp_id(path: Optional[Path] = None):
-    p = path or Path.cwd().resolve() / ".codecarbon.config"
-    if p.exists():
-        existing_path = p
-    else:
-        existing_path = Path("~/.codecarbon.config").expanduser()
-    return _get_local_exp_id(existing_path)
-
-
-def _get_local_exp_id(p: Optional[Path] = None):
-    config = configparser.ConfigParser()
-    config.read(str(p))
-    if "codecarbon" in config.sections():
-        d = dict(config["codecarbon"])
-        if "experiment_id" in d:
-            return d["experiment_id"]
+def get_existing_exp_id() -> Optional[str]:
+    """
+    Return experiment_id resolved from the same hierarchical config strategy
+    used by EmissionsTracker (global file, local file, then CODECARBON_* env).
+    """
+    try:
+        conf = get_hierarchical_config()
+    except KeyError:
+        return None
+    return conf.get("experiment_id")
 
 
 def write_local_exp_id(exp_id, path: Optional[Path] = None):

{codecarbon-3.2.5 → codecarbon-3.2.6}/codecarbon/cli/main.py

@@ -18,7 +18,7 @@ from codecarbon.cli.cli_utils import (
     create_new_config_file,
     get_api_endpoint,
     get_config,
-    get_existing_local_exp_id,
+    get_existing_exp_id,
     overwrite_local_config,
 )
 from codecarbon.cli.monitor import run_and_monitor
@@ -114,7 +114,8 @@ def api_get():
     """
     ex: test-api
     """
-    api = ApiClient(endpoint_url=API_URL)  # TODO: get endpoint from config
+    api_endpoint = get_api_endpoint()
+    api = ApiClient(endpoint_url=api_endpoint)
     api.set_access_token(get_access_token())
     organizations = api.get_list_organizations()
     print(organizations)
@@ -123,15 +124,18 @@ def api_get():
 @codecarbon.command("login", short_help="Login to CodeCarbon")
 def login():
     authorize()
-    api = ApiClient(endpoint_url=API_URL)  # TODO: get endpoint from config
+    api_endpoint = get_api_endpoint()
+    api = ApiClient(endpoint_url=api_endpoint)
     access_token = get_access_token()
     api.set_access_token(access_token)
     api.check_auth()
 
 
 def get_api_key(project_id: str):
+    api_endpoint = get_api_endpoint()
+    api_endpoint = api_endpoint.rstrip("/")
     req = requests.post(
-        f"{API_URL}/projects/{project_id}/api-tokens",
+        f"{api_endpoint}/projects/{project_id}/api-tokens",
         json={
             "project_id": project_id,
             "name": "api token",
@@ -306,7 +310,7 @@ def config():
     overwrite_local_config("api_key", api_key, path=file_path)
     show_config(file_path)
     print(
-        "Consult [link=https://mlco2.github.io/codecarbon/usage.html#configuration]configuration documentation[/link] for more configuration options"
+        "Consult [link=https://docs.codecarbon.io/latest/getting-started/usage/#configuration]configuration documentation[/link] for more configuration options"
     )
 
 
@@ -318,20 +322,25 @@ def config():
 def monitor(
     ctx: typer.Context,
     measure_power_secs: Annotated[
-        int, typer.Option(help="Interval between two measures.")
+        int,
+        typer.Option(help="Interval between two measures."),
     ] = 10,
     api_call_interval: Annotated[
-        int, typer.Option(help="Number of measures between API calls.")
+        int,
+        typer.Option(help="Number of measures between API calls."),
     ] = 30,
     api: Annotated[
-        bool, typer.Option(help="Choose to call Code Carbon API or not")
+        bool,
+        typer.Option(help="Choose to call Code Carbon API or not"),
     ] = True,
     offline: Annotated[bool, typer.Option(help="Run in offline mode")] = False,
     country_iso_code: Annotated[
-        str, typer.Option(help="3-letter country ISO code for offline mode")
+        str,
+        typer.Option(help="3-letter country ISO code for offline mode"),
     ] = None,
     region: Annotated[
-        str, typer.Option(help="Region/province for offline mode")
+        str,
+        typer.Option(help="Region/province for offline mode"),
     ] = None,
 ):
     """Monitor your machine's carbon emissions."""
@@ -356,10 +365,10 @@ def monitor(
             "region": region,
         }
     else:
-        experiment_id = get_existing_local_exp_id()
+        experiment_id = get_existing_exp_id()
         if api and experiment_id is None:
             print(
-                "ERROR: No experiment id, call 'codecarbon config' first. Or run in offline mode with `--offline --country-iso-code FRA` flag if you don't want to connect to the API.",
+                "ERROR: No experiment id. Set CODECARBON_EXPERIMENT_ID, call 'codecarbon config' first, or run in offline mode with `--offline --country-iso-code FRA`.",
                 file=sys.stderr,
             )
             raise typer.Exit(1)

{codecarbon-3.2.5 → codecarbon-3.2.6}/codecarbon/cli/monitor.py

@@ -14,7 +14,8 @@ from codecarbon.emissions_tracker import EmissionsTracker
 def run_and_monitor(
     ctx: typer.Context,
     log_level: Annotated[
-        str, typer.Option(help="Log level (critical, error, warning, info, debug)")
+        str,
+        typer.Option(help="Log level (critical, error, warning, info, debug)"),
     ] = "error",
     **tracker_args,
 ):

{codecarbon-3.2.5 → codecarbon-3.2.6}/codecarbon/core/powermetrics.py

@@ -58,7 +58,7 @@ def _has_powermetrics_sudo() -> bool:
                 """Not using PowerMetrics, sudo password prompt detected.
                     If you want to enable Powermetrics please modify your sudoers file
                     as described in :
-                    https://mlco2.github.io/codecarbon/methodology.html#power-usage
+                    https://docs.codecarbon.io/latest/introduction/methodology/#power-usage
                 """
             )
             return False

{codecarbon-3.2.5 → codecarbon-3.2.6}/codecarbon/emissions_tracker.py

@@ -978,9 +978,10 @@ class BaseEmissionsTracker(ABC):
             if isinstance(hardware, GPU):
                 gpu_ids_to_monitor = hardware.gpu_ids
                 gpu_details = hardware.devices.get_gpu_details()
-                for gpu_detail in gpu_details:
+                for gpu_index, gpu_detail in enumerate(gpu_details):
+                    resolved_gpu_index = gpu_detail.get("gpu_index", gpu_index)
                     if (
-                        gpu_detail["gpu_index"] in gpu_ids_to_monitor
+                        resolved_gpu_index in gpu_ids_to_monitor
                         and "gpu_utilization" in gpu_detail
                     ):
                         self._gpu_utilization_history.append(

{codecarbon-3.2.5 → codecarbon-3.2.6}/codecarbon/external/hardware.py

@@ -377,12 +377,12 @@ class CPU(BaseHardware):
 
     def total_power(self) -> Power:
         self._power_history.append(self._get_power_from_cpus())
-        if len(self._power_history) == 0:
-            logger.warning("Power history is empty, returning 0 W")
-            return Power.from_watts(0)
         power_history_in_W = [power.W for power in self._power_history]
-        cpu_power = sum(power_history_in_W) / len(power_history_in_W)
         self._power_history = []
+        if not power_history_in_W:
+            logger.warning("No power samples collected, returning 0 W")
+            return Power.from_watts(0)
+        cpu_power = sum(power_history_in_W) / len(power_history_in_W)
         return Power.from_watts(cpu_power)
 
     def measure_power_and_energy(self, last_duration: float) -> Tuple[Power, Energy]:

{codecarbon-3.2.5 → codecarbon-3.2.6}/codecarbon/external/ram.py

@@ -24,7 +24,7 @@ class RAM(BaseHardware):
     In V3, we need to improve the accuracy of the RAM power estimation.
     Because the power consumption of RAM is not linear with the amount of memory used,
 
-    See https://mlco2.github.io/codecarbon/methodology.html#ram for details on the RAM
+    See https://docs.codecarbon.io/latest/introduction/methodology/#ram for details on the RAM
     power estimation methodology.
 
     """

{codecarbon-3.2.5 → codecarbon-3.2.6}/codecarbon/output.py

@@ -4,6 +4,9 @@ Provides functionality for persistence of data
 
 from codecarbon.output_methods.base_output import BaseOutput  # noqa: F401
 
+# Output to BoAmps format
+from codecarbon.output_methods.boamps import BoAmpsOutput  # noqa: F401
+
 # emissions data
 from codecarbon.output_methods.emissions_data import (  # noqa: F401
     EmissionsData,

codecarbon-3.2.6/codecarbon/output_methods/boamps/__init__.py

@@ -0,0 +1,25 @@
+"""
+BoAmps output support for CodeCarbon.
+
+Provides first-class support for generating BoAmps (Boavizta) standardized
+JSON reports from CodeCarbon emission tracking data.
+"""
+
+from codecarbon.output_methods.boamps.mapper import (  # noqa: F401
+    map_emissions_to_boamps,
+)
+from codecarbon.output_methods.boamps.models import (  # noqa: F401
+    BoAmpsAlgorithm,
+    BoAmpsDataset,
+    BoAmpsEnvironment,
+    BoAmpsHardware,
+    BoAmpsHeader,
+    BoAmpsInfrastructure,
+    BoAmpsMeasure,
+    BoAmpsPublisher,
+    BoAmpsReport,
+    BoAmpsSoftware,
+    BoAmpsSystem,
+    BoAmpsTask,
+)
+from codecarbon.output_methods.boamps.output import BoAmpsOutput  # noqa: F401

codecarbon-3.2.6/codecarbon/output_methods/boamps/mapper.py

@@ -0,0 +1,260 @@
+"""
+Maps CodeCarbon EmissionsData to BoAmps report format.
+"""
+
+import warnings
+from dataclasses import fields as dataclass_fields
+from dataclasses import replace
+from typing import Optional
+
+from codecarbon.output_methods.boamps.models import (
+    BoAmpsEnvironment,
+    BoAmpsHardware,
+    BoAmpsHeader,
+    BoAmpsInfrastructure,
+    BoAmpsMeasure,
+    BoAmpsReport,
+    BoAmpsSoftware,
+    BoAmpsSystem,
+    BoAmpsTask,
+)
+from codecarbon.output_methods.emissions_data import EmissionsData
+
+BOAMPS_FORMAT_VERSION = "0.1"
+BOAMPS_FORMAT_SPEC_URI = "https://github.com/Boavizta/BoAmps/tree/main/model"
+
+
+def _to_boamps_datetime(timestamp: str) -> str:
+    """Normalize a timestamp to BoAmps format (YYYY-MM-DD HH:MM:SS)."""
+    return timestamp.replace("T", " ") if timestamp else timestamp
+
+
+def map_emissions_to_boamps(
+    emissions: EmissionsData,
+    task: Optional[BoAmpsTask] = None,
+    header: Optional[BoAmpsHeader] = None,
+    quality: Optional[str] = None,
+    infra_overrides: Optional[dict] = None,
+    environment_overrides: Optional[dict] = None,
+) -> BoAmpsReport:
+    """
+    Map CodeCarbon EmissionsData to a BoAmps report.
+
+    Auto-fills fields from EmissionsData and merges with user-provided context.
+    User-provided values take precedence over auto-detected values.
+
+    Args:
+        emissions: CodeCarbon emissions data from a completed run.
+        task: User-provided task context (required for schema-valid BoAmps).
+        header: User-provided header overrides.
+        quality: Quality assessment ("high", "medium", "low").
+        infra_overrides: Additional infrastructure fields (cloud_instance, cloud_service).
+        environment_overrides: Additional environment fields (power_source, etc.).
+
+    Returns:
+        A BoAmpsReport populated with auto-detected and user-provided data.
+    """
+    report_header = _build_header(emissions, header)
+    measures = [_build_measure(emissions)]
+    system = _build_system(emissions)
+    software = _build_software(emissions)
+    infrastructure = _build_infrastructure(emissions, infra_overrides)
+    environment = _build_environment(emissions, environment_overrides)
+
+    if task is None:
+        warnings.warn(
+            "No BoAmps task context provided. The output will be missing required "
+            "fields (taskStage, taskFamily, algorithms, dataset) and will not "
+            "validate against the BoAmps schema.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    return BoAmpsReport(
+        header=report_header,
+        task=task,
+        measures=measures,
+        system=system,
+        software=software,
+        infrastructure=infrastructure,
+        environment=environment,
+        quality=quality,
+    )
+
+
+def _build_header(
+    emissions: EmissionsData, user_header: Optional[BoAmpsHeader]
+) -> BoAmpsHeader:
+    """Build header from EmissionsData, merging with user overrides."""
+    auto_header = BoAmpsHeader(
+        format_version=BOAMPS_FORMAT_VERSION,
+        format_version_specification_uri=BOAMPS_FORMAT_SPEC_URI,
+        report_id=emissions.run_id,
+        report_datetime=_to_boamps_datetime(emissions.timestamp),
+    )
+
+    if user_header is None:
+        return auto_header
+
+    # User values override auto-detected values
+    return BoAmpsHeader(
+        licensing=user_header.licensing or auto_header.licensing,
+        format_version=user_header.format_version or auto_header.format_version,
+        format_version_specification_uri=(
+            user_header.format_version_specification_uri
+            or auto_header.format_version_specification_uri
+        ),
+        report_id=user_header.report_id or auto_header.report_id,
+        report_datetime=user_header.report_datetime or auto_header.report_datetime,
+        report_status=user_header.report_status or auto_header.report_status,
+        publisher=user_header.publisher or auto_header.publisher,
+    )
+
+
+def _build_measure(emissions: EmissionsData) -> BoAmpsMeasure:
+    """Build a BoAmps measure from EmissionsData."""
+    # Note: emissions.tracking_mode is "process"/"machine" (CodeCarbon's scope),
+    # not the CPU/GPU power tracking method (rapl, nvml, etc.) that BoAmps expects
+    # for cpuTrackingMode/gpuTrackingMode. We omit these fields since we don't
+    # have the actual tracker implementation details in EmissionsData.
+    measure = BoAmpsMeasure(
+        measurement_method="codecarbon",
+        version=emissions.codecarbon_version,
+        power_consumption=emissions.energy_consumed,
+        measurement_duration=emissions.duration,
+        measurement_date_time=_to_boamps_datetime(emissions.timestamp),
+    )
+
+    # CPU utilization as fraction (0-1)
+    if emissions.cpu_utilization_percent > 0:
+        measure.average_utilization_cpu = round(
+            emissions.cpu_utilization_percent / 100.0, 4
+        )
+
+    # GPU fields only if GPU is present
+    if emissions.gpu_count and emissions.gpu_count > 0:
+        if emissions.gpu_utilization_percent > 0:
+            measure.average_utilization_gpu = round(
+                emissions.gpu_utilization_percent / 100.0, 4
+            )
+
+    return measure
+
+
+def _build_system(emissions: EmissionsData) -> BoAmpsSystem:
+    """Build system info from EmissionsData."""
+    return BoAmpsSystem(os=emissions.os)
+
+
+def _build_software(emissions: EmissionsData) -> BoAmpsSoftware:
+    """Build software info from EmissionsData."""
+    return BoAmpsSoftware(
+        language="python",
+        version=emissions.python_version,
+    )
+
+
+def _build_infrastructure(
+    emissions: EmissionsData, overrides: Optional[dict] = None
+) -> BoAmpsInfrastructure:
+    """Build infrastructure from EmissionsData hardware fields."""
+    components = []
+
+    # CPU component (always present)
+    # emissions.cpu_count is logical thread count. BoAmps nbComponent expects
+    # physical cores. Standard SMT/HT uses 2 threads per core.
+    cpu_cores = max(1, int(emissions.cpu_count) // 2) if emissions.cpu_count else 1
+    cpu_component = BoAmpsHardware(
+        component_type="cpu",
+        component_name=emissions.cpu_model,
+        nb_component=cpu_cores,
+    )
+    components.append(cpu_component)
+
+    # GPU component (only if present)
+    if emissions.gpu_count and emissions.gpu_count > 0:
+        gpu_component = BoAmpsHardware(
+            component_type="gpu",
+            component_name=emissions.gpu_model if emissions.gpu_model else None,
+            nb_component=int(emissions.gpu_count),
+        )
+        components.append(gpu_component)
+
+    # RAM component (always present)
+    ram_component = BoAmpsHardware(
+        component_type="ram",
+        nb_component=1,
+        memory_size=emissions.ram_total_size,
+    )
+    components.append(ram_component)
+
+    # emissions.on_cloud can be "N" even on public cloud (the tracker clears
+    # cloud_provider/region for some providers). Use cloud_provider as a
+    # secondary signal to avoid misreporting cloud runs as on-premise.
+    is_cloud = emissions.on_cloud == "Y" or bool(emissions.cloud_provider)
+    infra = BoAmpsInfrastructure(
+        infra_type="publicCloud" if is_cloud else "onPremise",
+        cloud_provider=(
+            emissions.cloud_provider if is_cloud and emissions.cloud_provider else None
+        ),
+        components=components,
+    )
+
+    # Apply overrides from context file
+    if overrides:
+        for attr in ("cloud_instance", "cloud_service", "infra_type"):
+            if attr in overrides:
+                setattr(infra, attr, overrides[attr])
+
+        # Merge user-provided components: enrich auto-detected components
+        # with user-supplied details (manufacturer, family, series, share, etc.)
+        # by matching on component_type. Extra user components are appended.
+        if "components" in overrides:
+            user_components = overrides["components"]
+            auto_by_type = {c.component_type: c for c in infra.components}
+            merged = []
+            used_types = set()
+            for user_comp in user_components:
+                if user_comp.component_type in auto_by_type:
+                    auto = auto_by_type[user_comp.component_type]
+                    # Build a merged copy: user values take precedence,
+                    # auto-detected fill blanks. Avoids mutating the originals.
+                    fill = {
+                        f.name: getattr(auto, f.name)
+                        for f in dataclass_fields(user_comp)
+                        if f.name != "component_type"
+                        and getattr(user_comp, f.name) is None
+                    }
+                    user_comp = replace(user_comp, **fill) if fill else user_comp
+                    used_types.add(user_comp.component_type)
+                merged.append(user_comp)
+            # Keep auto-detected components that the user didn't override
+            for auto in infra.components:
+                if auto.component_type not in used_types:
+                    merged.append(auto)
+            infra.components = merged
+
+    return infra
+
+
+def _build_environment(
+    emissions: EmissionsData, overrides: Optional[dict] = None
+) -> BoAmpsEnvironment:
+    """Build environment from EmissionsData location fields."""
+    env = BoAmpsEnvironment(
+        country=emissions.country_name,
+        latitude=emissions.latitude,
+        longitude=emissions.longitude,
+    )
+
+    if overrides:
+        for attr in (
+            "location",
+            "power_supplier_type",
+            "power_source",
+            "power_source_carbon_intensity",
+        ):
+            if attr in overrides:
+                setattr(env, attr, overrides[attr])
+
+    return env