feat(impacts): support legacy signature of impacts usage (#791)

* feat(impacts): support legacy signature of impacts usage

* Update unit coverage badge

---------

Co-authored-by: leoguillaume <leoguillaume@users.noreply.github.com>

Author: leoguillaume

.github/badges/coverage.json

@@ -1 +1 @@
-{"schemaVersion":1,"label":"coverage","message":"50.82%","color":"red"}
+{"schemaVersion":1,"label":"coverage","message":"50.86%","color":"red"}

api/clients/model/_basemodelprovider.py

@@ -130,8 +130,15 @@ def _get_usage(self, request_content: RequestContent, response_data: dict | list
                 usage.completion_tokens += completion_tokens
                 usage.total_tokens += total_tokens
                 usage.cost += cost
-                usage.carbon.kgCO2eq += carbon_footprint.kgCO2eq
-                usage.carbon.kWh += carbon_footprint.kWh
+
+                # legacy usage
+                usage.carbon.kgCO2eq.min += carbon_footprint.kgCO2eq
+                usage.carbon.kgCO2eq.max += carbon_footprint.kgCO2eq
+                usage.carbon.kWh.min += carbon_footprint.kWh
+                usage.carbon.kWh.max += carbon_footprint.kWh
+
+                usage.impacts.kgCO2eq += carbon_footprint.kgCO2eq
+                usage.impacts.kWh += carbon_footprint.kWh
                 usage.requests += 1
 
                 request_context.get().usage = usage

api/helpers/_usagemanager.py

@@ -6,12 +6,12 @@
 from sqlalchemy.future import select
 
 from api.schemas.me.usage import (
-    CarbonFootprintUsage,
     EndpointUsage,
     MetricsUsage,
     Usage,
     UsageDetail,
 )
+from api.schemas.usage import EnvironmentalImpacts
 from api.sql.models import Usage as UsageTable
 
 
@@ -79,7 +79,7 @@ async def get_usages(
                         completion_tokens=row.completion_tokens,
                         total_tokens=row.total_tokens,
                         cost=row.cost,
-                        carbon=CarbonFootprintUsage(kWh=row.kwh, kgCO2eq=row.kgco2eq),
+                        impacts=EnvironmentalImpacts(kWh=row.kwh, kgCO2eq=row.kgco2eq),
                         metrics=MetricsUsage(latency=row.latency, ttft=row.ttft),
                     ),
                 )

api/schemas/me/usage.py

@@ -4,6 +4,7 @@
 from pydantic import Field
 
 from api.schemas import BaseModel
+from api.schemas.usage import EnvironmentalImpacts
 
 
 class EndpointUsage(Enum):
@@ -20,17 +21,12 @@ class MetricsUsage(BaseModel):
     ttft: int | None = None
 
 
-class CarbonFootprintUsage(BaseModel):
-    kWh: Annotated[float | None, Field(default=None, description="Carbon footprint in kWh.")]
-    kgCO2eq: Annotated[float | None, Field(default=None, description="Carbon footprint in kgCO2eq (global warming potential).")]
-
-
 class UsageDetail(BaseModel):
     prompt_tokens: Annotated[int | None, Field(default=None, description="Number of prompt tokens (e.g. input tokens).")]
     completion_tokens: Annotated[int | None, Field(default=None, description="Number of completion tokens (e.g. output tokens).")]
     total_tokens: Annotated[int | None, Field(default=None, description="Total number of tokens (e.g. input and output tokens).")]
     cost: Annotated[float | None, Field(default=None, description="Total cost of the request.")]
-    carbon: Annotated[CarbonFootprintUsage, Field(default_factory=CarbonFootprintUsage)]
+    impacts: Annotated[EnvironmentalImpacts, Field(default_factory=EnvironmentalImpacts)]
     metrics: Annotated[MetricsUsage, Field(default_factory=MetricsUsage)]
 
 

api/schemas/usage.py

@@ -3,15 +3,31 @@
 from api.schemas import BaseModel
 
 
-class CarbonFootprintUsage(BaseModel):
+class EnvironmentalImpacts(BaseModel):
     kWh: float = Field(default=0.0, description="Carbon footprint in kWh.")
     kgCO2eq: float = Field(default=0.0, description="Carbon footprint in kgCO2eq (global warming potential).")
 
 
+class CarbonFootprintUsageKWh(BaseModel):
+    min: float = Field(default=0.0, description="Minimum carbon footprint in kWh.", deprecated=True)
+    max: float = Field(default=0.0, description="Maximum carbon footprint in kWh.", deprecated=True)
+
+
+class CarbonFootprintUsageKgCO2eq(BaseModel):
+    min: float = Field(default=0.0, description="Minimum carbon footprint in kgCO2eq (global warming potential).", deprecated=True)
+    max: float = Field(default=0.0, description="Maximum carbon footprint in kgCO2eq (global warming potential).", deprecated=True)
+
+
+class CarbonFootprintUsage(BaseModel):
+    kWh: CarbonFootprintUsageKWh = Field(default_factory=CarbonFootprintUsageKWh, deprecated=True)
+    kgCO2eq: CarbonFootprintUsageKgCO2eq = Field(default_factory=CarbonFootprintUsageKgCO2eq, deprecated=True)
+
+
 class Usage(BaseModel):
     prompt_tokens: int = Field(default=0, description="Number of prompt tokens (e.g. input tokens).")
     completion_tokens: int = Field(default=0, description="Number of completion tokens (e.g. output tokens).")
     total_tokens: int = Field(default=0, description="Total number of tokens (e.g. input and output tokens).")
     cost: float = Field(default=0.0, description="Total cost of the request.")
-    carbon: CarbonFootprintUsage = Field(default_factory=CarbonFootprintUsage)
+    carbon: CarbonFootprintUsage = Field(default_factory=CarbonFootprintUsage, deprecated=True)
+    impacts: EnvironmentalImpacts = Field(default_factory=EnvironmentalImpacts)
     requests: int = Field(default=0, description="Number of model requests.")

api/tests/unit/test_utils/test_carbon.py

@@ -1,7 +1,7 @@
 from types import SimpleNamespace
 
 from api.schemas.admin.providers import ProviderCarbonFootprintZone
-from api.schemas.usage import CarbonFootprintUsage
+from api.schemas.usage import EnvironmentalImpacts
 from api.utils.carbon import get_carbon_footprint
 
 
@@ -23,7 +23,7 @@ def test_get_carbon_footprint_return_null_footprint_when_model_params_not_define
         model_zone = ProviderCarbonFootprintZone.WOR
         token_count = 1
         request_latency = 0.01
-        expected_carbon_footprint = CarbonFootprintUsage(kWh=0.0, kgCO2eq=0.0)
+        expected_carbon_footprint = EnvironmentalImpacts(kWh=0.0, kgCO2eq=0.0)
         # When
         result = get_carbon_footprint(active_params, total_params, model_zone, token_count, request_latency)
         # Then
@@ -36,7 +36,7 @@ def test_get_carbon_footprint_return_null_footprint_when_token_count_is_null(sel
         model_zone = ProviderCarbonFootprintZone.WOR
         token_count = 0
         request_latency = 0.01
-        expected_carbon_footprint = CarbonFootprintUsage(kWh=0.0, kgCO2eq=0.0)
+        expected_carbon_footprint = EnvironmentalImpacts(kWh=0.0, kgCO2eq=0.0)
         # When
         result = get_carbon_footprint(active_params, total_params, model_zone, token_count, request_latency)
         # Then
@@ -47,18 +47,16 @@ def test_get_carbon_footprint_return_footprint(self, mocker):
         mocked_electricity_mix = mocker.patch("api.utils.carbon.electricity_mixes.find_electricity_mix")
         mocked_electricity_mix.return_value = SimpleNamespace(adpe=1, pe=2, gwp=3, wue=4)
         mocked_compute_llm_impacts = mocker.patch("api.utils.carbon.compute_llm_impacts")
-        mocked_compute_llm_impacts.return_value = dict_to_namespace(
-            {
-                "energy": {"value": 1},
-                "gwp": {"value": 3},
-            }
-        )
+        mocked_compute_llm_impacts.return_value = dict_to_namespace({
+            "energy": {"value": 1},
+            "gwp": {"value": 3},
+        })
         active_params = 1
         total_params = 1
         model_zone = ProviderCarbonFootprintZone.WOR
         token_count = 1
         request_latency = 10  # 10 milliseconds, will be converted to 0.01 seconds
-        expected_carbon_footprint = CarbonFootprintUsage(kWh=1.0, kgCO2eq=3.0)
+        expected_carbon_footprint = EnvironmentalImpacts(kWh=1.0, kgCO2eq=3.0)
         expected_compute_llm_impacts_args = {
             "if_electricity_mix_adpe": 1,
             "if_electricity_mix_pe": 2,

api/utils/carbon.py

@@ -1,7 +1,7 @@
 from ecologits.tracers.utils import compute_llm_impacts, electricity_mixes
 
 from api.schemas.admin.providers import ProviderCarbonFootprintZone
-from api.schemas.usage import CarbonFootprintUsage
+from api.schemas.usage import EnvironmentalImpacts
 
 
 def get_carbon_footprint(
@@ -10,7 +10,7 @@ def get_carbon_footprint(
     model_zone: ProviderCarbonFootprintZone,
     token_count: int,
     request_latency: int | None = None,
-) -> CarbonFootprintUsage:
+) -> EnvironmentalImpacts:
     """Calculate carbon impact of a model inference using direct parameters.
 
     Args:
@@ -28,7 +28,7 @@ def get_carbon_footprint(
         raise ValueError(f"Electricity zone {model_zone.value} not found")
 
     if not active_params or not total_params:
-        return CarbonFootprintUsage(kWh=0, kgCO2eq=0)
+        return EnvironmentalImpacts(kWh=0, kgCO2eq=0)
 
     impacts = compute_llm_impacts(
         model_active_parameter_count=active_params,
@@ -45,6 +45,6 @@ def get_carbon_footprint(
         datacenter_wue=1.8,
         request_latency=request_latency / 1000,  # convert to seconds
     )
-    carbon_footprint = CarbonFootprintUsage(kWh=impacts.energy.value, kgCO2eq=impacts.gwp.value)
+    impacts = EnvironmentalImpacts(kWh=impacts.energy.value, kgCO2eq=impacts.gwp.value)
 
-    return carbon_footprint
+    return impacts

api/utils/hooks_decorator.py

@@ -81,8 +81,8 @@ def set_usage_from_context(usage: Usage):
     usage.completion_tokens = context.usage.completion_tokens
     usage.total_tokens = context.usage.total_tokens
     usage.cost = context.usage.cost
-    usage.kwh = context.usage.carbon.kWh
-    usage.kgco2eq = context.usage.carbon.kgCO2eq
+    usage.kwh = context.usage.impacts.kWh
+    usage.kgco2eq = context.usage.impacts.kgCO2eq
     usage.ttft = context.ttft
     usage.latency = context.latency
 

docs/src/content/docs/features/usage/environmental_footprint.mdx

@@ -74,7 +74,7 @@ There are three way to configure environmental impact tracking, by Playground, A
 
 ## Environmental impact metrics
 
-For each call to a generative AI model, the API returns environmental impact metrics in the response, in the `usage.carbon` field. The metrics include minimum and maximum estimates to account for variability in model efficiency:
+For each call to a generative AI model, the API returns environmental impact metrics in the response, in the `usage.impacts` field. The metrics include minimum and maximum estimates to account for variability in model efficiency:
 
 - **kWh**: Energy consumption in kilowatt-hours (kWh), representing the final electricity consumption.
 - **kgCO2eq**: Global Warming Potential (GWP) in kilograms of CO2 equivalent (kgCO2eq), representing greenhouse gas emissions related to climate change.
@@ -95,7 +95,7 @@ For each call to a generative AI model, the API returns environmental impact met
     "completion_tokens": 20,
     "total_tokens": 30,
     "cost": 0.000015,
-+    "carbon": {"kWh": 0.0001456, "kgCO2eq": 0.0000672 }
++    "impacts": {"kWh": 0.0001456, "kgCO2eq": 0.0000672 }
   }
 }
 ```

playground/app/features/usage/components/lists.py

@@ -64,12 +64,12 @@ def usage_table() -> rx.Component:
                 rx.table.column_header_cell(
                     rx.tooltip(
                         rx.hstack(
-                            rx.text("Carbon"),
+                            rx.text("Impacts"),
                             rx.icon("info", size=ICON_SIZE_TINY),
                             spacing=SPACING_TINY,
                             align="center",
                         ),
-                        content="Carbon footprint in kgCO2eq (Global warming potential)",
+                        content="Footprint impacts in kgCO2eq (Global warming potential)",
                     ),
                     width="150px",
                 ),