Implement AddComponentBounds

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

src/frequenz/client/microgrid/__init__.py

@@ -11,6 +11,7 @@
     DEFAULT_CHANNEL_OPTIONS,
     DEFAULT_GRPC_CALL_TIMEOUT,
     MicrogridApiClient,
+    Validity,
 )
 from ._delivery_area import DeliveryArea, EnergyMarketCodeType
 from ._exception import (
@@ -69,4 +70,5 @@
     "ServiceUnavailable",
     "UnknownError",
     "UnrecognizedGrpcStatus",
+    "Validity",
 ]

src/frequenz/client/microgrid/_client.py

@@ -6,12 +6,15 @@
 from __future__ import annotations
 
 import asyncio
+import enum
 import itertools
 import math
+from collections.abc import Iterable
 from dataclasses import replace
 from datetime import datetime, timedelta
 from typing import Any, assert_never
 
+from frequenz.api.common.v1.metrics import bounds_pb2, metric_sample_pb2
 from frequenz.api.microgrid.v1 import microgrid_pb2, microgrid_pb2_grpc
 from frequenz.client.base import channel, client, conversion, retry, streaming
 from frequenz.client.common.microgrid.components import ComponentId
@@ -22,6 +25,8 @@
 from ._microgrid_info import MicrogridInfo
 from ._microgrid_info_proto import microgrid_info_from_proto
 from .component._component import Component
+from .metrics._bounds import Bounds
+from .metrics._metric import Metric
 
 DEFAULT_GRPC_CALL_TIMEOUT = 60.0
 """The default timeout for gRPC calls made by this client (in seconds)."""
@@ -307,6 +312,127 @@ async def set_component_power_reactive(  # noqa: DOC502 (raises ApiClientError i
 
         return None
 
+    async def add_component_bounds(  # noqa: DOC502 (Raises ApiClientError indirectly)
+        self,
+        component: ComponentId | Component,
+        target: Metric | int,
+        bounds: Iterable[Bounds],
+        *,
+        validity: Validity | None = None,
+    ) -> datetime | None:
+        """Add inclusion bounds for a given metric of a given component.
+
+        The bounds are used to define the acceptable range of values for a metric
+        of a component. The added bounds are kept only temporarily, and removed
+        automatically after some expiry time.
+
+        Inclusion bounds give the range that the system will try to keep the
+        metric within. If the metric goes outside of these bounds, the system will
+        try to bring it back within the bounds.
+        If the bounds for a metric are `[[lower_1, upper_1], [lower_2, upper_2]]`,
+        then this metric's `value` needs to comply with the constraints `lower_1 <=
+        value <= upper_1` OR `lower_2 <= value <= upper_2`.
+
+        If multiple inclusion bounds have been provided for a metric, then the
+        overlapping bounds are merged into a single bound, and non-overlapping
+        bounds are kept separate.
+
+        Example:
+            If the bounds are [[0, 10], [5, 15], [20, 30]], then the resulting bounds
+            will be [[0, 15], [20, 30]].
+
+            The following diagram illustrates how bounds are applied:
+
+            ```
+              lower_1  upper_1
+            <----|========|--------|========|-------->
+                                lower_2  upper_2
+            ```
+
+            The bounds in this example are `[[lower_1, upper_1], [lower_2, upper_2]]`.
+
+            ```
+            ---- values here are considered out of range.
+            ==== values here are considered within range.
+            ```
+
+        Note:
+            For power metrics, regardless of the bounds, 0W is always allowed.
+
+        Args:
+            component: The component to add bounds to.
+            target: The target metric whose bounds have to be added.
+            bounds: The bounds to add to the target metric. Overlapping pairs of bounds
+                are merged into a single pair of bounds, and non-overlapping ones are
+                kept separated.
+            validity: The duration for which the given bounds will stay in effect.
+                If `None`, then the bounds will be removed after some default time
+                decided by the server, typically 5 seconds.
+
+                The duration for which the bounds are valid. If not provided, the
+                bounds are considered to be valid indefinitely.
+
+        Returns:
+            The timestamp until which the given bounds will stay in effect, or `None` if
+                if it was not provided by the server.
+
+        Raises:
+            ApiClientError: If there are any errors communicating with the Microgrid API,
+                most likely a subclass of
+                [GrpcError][frequenz.client.microgrid.GrpcError].
+        """
+        extra_args = {}
+        if validity is not None:
+            extra_args["validity_duration"] = validity.value
+        response = await client.call_stub_method(
+            self,
+            lambda: self.stub.AddComponentBounds(
+                microgrid_pb2.AddComponentBoundsRequest(
+                    component_id=_get_component_id(component),
+                    target_metric=_get_metric_value(target),
+                    bounds=(
+                        bounds_pb2.Bounds(
+                            lower=bound.lower,
+                            upper=bound.upper,
+                        )
+                        for bound in bounds
+                    ),
+                    **extra_args,
+                ),
+                timeout=DEFAULT_GRPC_CALL_TIMEOUT,
+            ),
+            method_name="AddComponentBounds",
+        )
+
+        if response.HasField("ts"):
+            return conversion.to_datetime(response.ts)
+
+        return None
+
+
+class Validity(enum.Enum):
+    """The duration for which a given list of bounds will stay in effect."""
+
+    FIVE_SECONDS = (
+        microgrid_pb2.ComponentBoundsValidityDuration.COMPONENT_BOUNDS_VALIDITY_DURATION_5_SECONDS
+    )
+    """The bounds will stay in effect for 5 seconds."""
+
+    ONE_MINUTE = (
+        microgrid_pb2.ComponentBoundsValidityDuration.COMPONENT_BOUNDS_VALIDITY_DURATION_1_MINUTE
+    )
+    """The bounds will stay in effect for 1 minute."""
+
+    FIVE_MINUTES = (
+        microgrid_pb2.ComponentBoundsValidityDuration.COMPONENT_BOUNDS_VALIDITY_DURATION_5_MINUTES
+    )
+    """The bounds will stay in effect for 5 minutes."""
+
+    FIFTEEN_MINUTES = (
+        microgrid_pb2.ComponentBoundsValidityDuration.COMPONENT_BOUNDS_VALIDITY_DURATION_15_MINUTES
+    )
+    """The bounds will stay in effect for 15 minutes."""
+
 
 def _get_component_id(component: ComponentId | Component) -> int:
     """Get the component ID from a component or component ID."""
@@ -319,6 +445,17 @@ def _get_component_id(component: ComponentId | Component) -> int:
             assert_never(unexpected)
 
 
+def _get_metric_value(metric: Metric | int) -> metric_sample_pb2.Metric.ValueType:
+    """Get the metric ID from a metric or metric ID."""
+    match metric:
+        case Metric():
+            return metric_sample_pb2.Metric.ValueType(metric.value)
+        case int():
+            return metric_sample_pb2.Metric.ValueType(metric)
+        case unexpected:
+            assert_never(unexpected)
+
+
 def _delta_to_seconds(delta: timedelta | None) -> int | None:
     """Convert a `timedelta` to seconds (or `None` if `None`)."""
     return round(delta.total_seconds()) if delta is not None else None

tests/client_test_cases/add_component_bounds/error_case.py

@@ -0,0 +1,29 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Test add_component_bounds call with error."""
+
+from typing import Any
+
+from frequenz.client.common.microgrid.components import ComponentId
+from grpc import StatusCode
+
+from frequenz.client.microgrid import PermissionDenied
+from frequenz.client.microgrid.metrics import Bounds, Metric
+from tests.util import make_grpc_error
+
+client_args = (ComponentId(1), Metric.AC_VOLTAGE, [Bounds(lower=200.0, upper=250.0)])
+
+
+def assert_stub_method_call(stub_method: Any) -> None:
+    """Assert that the gRPC request matches the expected request."""
+    # We are not testing the request here, just the error handling
+
+
+grpc_response = make_grpc_error(StatusCode.PERMISSION_DENIED)
+
+
+def assert_client_exception(exception: Exception) -> None:
+    """Assert that the client exception matches the expected error."""
+    assert isinstance(exception, PermissionDenied)
+    assert exception.grpc_error == grpc_response

tests/client_test_cases/add_component_bounds/no_validity_case.py

@@ -0,0 +1,35 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Test data for add_component_bounds call without validity."""
+
+from typing import Any
+
+from frequenz.api.common.v1.metrics import bounds_pb2, metric_sample_pb2
+from frequenz.api.microgrid.v1 import microgrid_pb2
+from frequenz.client.common.microgrid.components import ComponentId
+
+from frequenz.client.microgrid.metrics import Bounds, Metric
+
+client_args = (ComponentId(1), Metric.AC_VOLTAGE, [Bounds(lower=200.0, upper=250.0)])
+
+
+def assert_stub_method_call(stub_method: Any) -> None:
+    """Assert that the gRPC request matches the expected request."""
+    stub_method.assert_called_once_with(
+        microgrid_pb2.AddComponentBoundsRequest(
+            component_id=1,
+            target_metric=metric_sample_pb2.Metric.METRIC_AC_VOLTAGE,
+            bounds=[bounds_pb2.Bounds(lower=200.0, upper=250.0)],
+            # No validity field
+        ),
+        timeout=60.0,
+    )
+
+
+grpc_response = microgrid_pb2.AddComponentBoundsResponse()
+
+
+def assert_client_result(result: Any) -> None:
+    """Assert that the client result is None as expected."""
+    assert result is None

tests/client_test_cases/add_component_bounds/success_case.py

@@ -0,0 +1,50 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Test data for successful component bounds addition."""
+
+from datetime import datetime, timezone
+from typing import Any
+
+from frequenz.api.common.v1.metrics import bounds_pb2, metric_sample_pb2
+from frequenz.api.microgrid.v1 import microgrid_pb2
+from frequenz.client.base.conversion import to_timestamp
+from frequenz.client.common.microgrid.components import ComponentId
+
+from frequenz.client.microgrid import Validity
+from frequenz.client.microgrid._client import DEFAULT_GRPC_CALL_TIMEOUT
+from frequenz.client.microgrid.metrics import Bounds, Metric
+
+client_args = (
+    ComponentId(1),
+    Metric.DC_VOLTAGE,
+    [Bounds(lower=200.0, upper=250.0)],
+)
+client_kwargs = {
+    "validity": Validity.FIFTEEN_MINUTES,
+}
+
+PbValidity = microgrid_pb2.ComponentBoundsValidityDuration
+
+valid_until = datetime(2023, 1, 1, 12, 0, 0, tzinfo=timezone.utc)
+
+
+def assert_stub_method_call(stub_method: Any) -> None:
+    """Assert that the gRPC request matches the expected request."""
+    stub_method.assert_called_once_with(
+        microgrid_pb2.AddComponentBoundsRequest(
+            component_id=1,
+            target_metric=metric_sample_pb2.Metric.METRIC_DC_VOLTAGE,
+            bounds=[bounds_pb2.Bounds(lower=200.0, upper=250.0)],
+            validity_duration=PbValidity.COMPONENT_BOUNDS_VALIDITY_DURATION_15_MINUTES,
+        ),
+        timeout=DEFAULT_GRPC_CALL_TIMEOUT,
+    )
+
+
+grpc_response = microgrid_pb2.AddComponentBoundsResponse(ts=to_timestamp(valid_until))
+
+
+def assert_client_result(result: datetime) -> None:
+    """Assert that the client result matches the expected valid_until datetime."""
+    assert result == valid_until

tests/test_client.py

@@ -122,3 +122,16 @@ async def test_set_component_power_reactive(
 ) -> None:
     """Test set_component_power_reactive method."""
     await spec.test_unary_unary_call(client, "SetComponentPowerReactive")
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "spec",
+    get_test_specs("add_component_bounds", tests_dir=TESTS_DIR),
+    ids=str,
+)
+async def test_add_bounds(
+    client: MicrogridApiClient, spec: ApiClientTestCaseSpec
+) -> None:
+    """Test add_bounds method."""
+    await spec.test_unary_unary_call(client, "AddComponentBounds")