frequenz-api-common 0.6.4__tar.gz → 0.7.0__tar.gz

{frequenz-api-common-0.6.4 → frequenz_api_common-0.7.0}/MANIFEST.in

@@ -6,7 +6,7 @@ exclude CODEOWNERS
 exclude CONTRIBUTING.md
 exclude mkdocs.yml
 exclude noxfile.py
-exclude src/conftest.py
+exclude py/frequenz/api/common/conftest.py
 recursive-exclude .github *
 recursive-exclude benchmarks *
 recursive-exclude docs *

{frequenz-api-common-0.6.4/py/frequenz_api_common.egg-info → frequenz_api_common-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: frequenz-api-common
-Version: 0.6.4
+Version: 0.7.0
 Summary: Frequenz common gRPC API and bindings
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License: MIT
@@ -18,15 +18,41 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Python: <4,>=3.11
 Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: protobuf<8,>=6.31.1
+Requires-Dist: grpcio<2,>=1.72.1
 Provides-Extra: dev-flake8
+Requires-Dist: flake8==7.2.0; extra == "dev-flake8"
+Requires-Dist: flake8-docstrings==1.7.0; extra == "dev-flake8"
+Requires-Dist: flake8-pyproject==1.2.3; extra == "dev-flake8"
+Requires-Dist: pydoclint==0.6.6; extra == "dev-flake8"
+Requires-Dist: pydocstyle==6.3.0; extra == "dev-flake8"
 Provides-Extra: dev-formatting
+Requires-Dist: black==25.1.0; extra == "dev-formatting"
+Requires-Dist: isort==6.0.1; extra == "dev-formatting"
 Provides-Extra: dev-mkdocs
+Requires-Dist: mike==1.1.2; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-gen-files==0.5.0; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-literate-nav==0.6.2; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-material==9.6.14; extra == "dev-mkdocs"
+Requires-Dist: mkdocstrings[python]==0.29.1; extra == "dev-mkdocs"
+Requires-Dist: frequenz-repo-config[api]==0.13.5; extra == "dev-mkdocs"
 Provides-Extra: dev-mypy
+Requires-Dist: mypy==1.16.0; extra == "dev-mypy"
+Requires-Dist: grpc-stubs==1.53.0.6; extra == "dev-mypy"
+Requires-Dist: frequenz-api-common[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-mypy"
 Provides-Extra: dev-noxfile
+Requires-Dist: nox==2025.5.1; extra == "dev-noxfile"
+Requires-Dist: frequenz-repo-config[api]==0.13.5; extra == "dev-noxfile"
 Provides-Extra: dev-pylint
+Requires-Dist: pylint==3.3.7; extra == "dev-pylint"
+Requires-Dist: frequenz-api-common[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-pylint"
 Provides-Extra: dev-pytest
+Requires-Dist: pytest==8.3.5; extra == "dev-pytest"
+Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.13.5; extra == "dev-pytest"
 Provides-Extra: dev
-License-File: LICENSE
+Requires-Dist: frequenz-api-common[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]; extra == "dev"
+Dynamic: license-file
 
 # Frequenz Common API
 

frequenz_api_common-0.7.0/RELEASE_NOTES.md

@@ -0,0 +1,124 @@
+# Frequenz Common API Release Notes
+
+## Summary
+
+This release introduces several breaking changes, new features, and improvements to the existing API. The most significant changes include renaming and restructuring of the `components` package to `electrical_components`, the introduction of new diagnostic codes, and the addition of new messages for communication components and streaming events.
+
+## Upgrading
+
+- Removed:
+
+    + `microgrid.components.ComponentStatus`, use `microgrid.electrical_components.ElectricalComponentControlMode` instead
+    + `ComponentErrorCode.UNDERVOLTAGE_SHUTDOWN`, use `ElectricalComponentDiagnosticCode.UNDERVOLTAGE` instead
+    + `microgrid.sensors.SensorMetric`, use `metrics.Metric` instead
+    + `microgrid.sensors.SensorMetricSample`, use `metrics.MetricSample` instead
+    + `microgrid.sensors.SensorCategory`, since it was not useful and potentially confusing
+
+        Sensors can report different sensor metrics, and they could belong to several of these categories simultaneously. This defeats the purpose of having singular categories for sensors. Some more useful categorization may be introduced again in the future.
+
+- Renamed several symbols to increase consistency and clarity:
+
+    + `microgrid.components`:
+
+        * The whole package and all proto files, messages, field, enums were renamed to `electrical_components`
+        * `ComponentCategoryMetadataVariant` to `ElectricalComponentCategorySpecificInfo`
+        * `ComponentCategory` to `ElectricalComponentCategory`
+        * `Component.category_type` to `ElectricalComponent.category_specific_info`
+        * `ComponentCategoryMetadataVariant.metadata` to `ElectricalComponentCategorySpecificInfo.kind`
+        * `ComponentErrorCode` to `ElectricalComponentDiagnosticCode`
+        * `ComponentState` to `ElectricalComponentStateSnapshot`
+        * `ComponentState.sampled_at` to `ElectricalComponentStateSnapshot.origin_time`
+        * `ComponentData` to `ElectricalComponentTelemetry` (to better specify its purpose of encapsulating general telemetry data from electrical components)
+        * `ComponentData.states` to `ElectricalComponentTelemetry.state_snapshots`
+        * Grid-related terms to clarify their meaning and purpose:
+
+            + `COMPONENT_CATEGORY_GRID` to `ELECTRICAL_COMPONENT_CATEGORY_GRID_CONNECTION_POINT`
+            + `ComponentCategoryMetadataVariant.metadata.grid` to `ElectricalComponentCategorySpecificInfo.kind.grid_connection_point`
+        * `InverterType.INVERTER_TYPE_SOLAR` to `InverterType.INVERTER_TYPE_PV` (to align with the more colloquial term "PV inverter")
+        * `ComponentCategory.COMPONENT_CATEGORY_RELAY` to `ElectricalComponentCategory.ELECTRICAL_COMPONENT_CATEGORY_BREAKER` (to better align with the common terminology used in electrical engineering).
+        * All contents of all the files in the `electrical_components` directory (previously `components`) are now moved into the `electrical_components.proto` file.
+
+    + `microgrid.sensors`:
+
+        * `SensorErrorCode` to `SensorDiagnosticCode`
+        * `SensorData` to `SensorTelemetry` (to better specify its purpose of encapsulating general telemetry data from sensors)
+        * `SensorState` to `SensorStateSnapshot`
+        * `SensorData.states` to `SensorTelemetry.state_snapshots`
+        * `SensorState.sampled_at` to `SensorStateSnapshot.origin_time`
+        * `SensorStateCode.SENSOR_STATE_CODE_ON` to `SensorStateCode.SENSOR_STATE_CODE_OK` (to better indicate that we do not control on/off state of sensors)
+
+    + `metrics`:
+
+        * The file `metric_sample.proto` to `metrics.proto`
+        * `MetricSample.source` to `MetricSample.connection`
+        * `MetricSample.sampled_at` to `sample_time`
+
+    + `metrics.Metric`:
+
+       * The enum variants to follow a more consistent naming scheme of core-concept to modifier.
+       * `METRIC_AC_APPARENT_POWER*` to `METRIC_AC_POWER_APPARENT*`
+       * `METRIC_AC_ACTIVE_POWER*` to `METRIC_AC_POWER_ACTIVE*`
+       * `METRIC_AC_REACTIVE_POWER*` to `METRIC_AC_POWER_REACTIVE*`
+       * `METRIC_AC_APPARENT_ENERGY*` to `METRIC_AC_ENERGY_APPARENT*`
+       * `METRIC_AC_ACTIVE_ENERGY*` to `METRIC_AC_ENERGY_ACTIVE*`
+       * `METRIC_AC_REACTIVE_ENERGY*` to `METRIC_AC_ENERGY_REACTIVE*`
+
+    + `types`:
+
+        * The whole package has been renamed to `type`.
+
+- Renumbered some enum values to remove unnecessary gaps:
+
+    + `microgrid.components.ComponentCategory` (`microgrid.electrical_components.ElectricalComponentCategory`)
+    + `microgrid.components.ComponentErrorCode` (`microgrid.electrical_components.ElectricalComponentDiagnosticCode`)
+    + `metrics.Metric`
+
+- The minimum allowed version of `protobuf` and `grpcio` has been updated to 6.31.1 and 1.72.1 respectively, you might also need to bump your dependencies accordingly.
+
+- The file `location.proto` has been moved to the `types` package, moving the message `Location` to `types.Location`.
+
+- The type of the field `metrics.MetricSample.connection` has been changed from `string` to `metrics.MetricConnection`. The latter is a newly added message that provides a better categorization of the connection type.
+
+- The `v1` package has been renamed to `v1alpha7`. The current `v1` package now consists of the contents the same directory from the v0.6.x branch, which is the latest stable version of the API.
+
+- The enum `ComponentCategory` (now `ElectricalComponentCategory`) has been extended with new variants.
+
+## New Features
+
+Added many new messages and enum values:
+
+- `microgrid.communication_components`: Package with message definitions for communication components
+
+    + `CommunicationComponentDiagnostic`: Message to represent warnings and errors in microgrid communication components
+    + `CommunicationComponentStateSnapshot`: Message to represent the state of communication components
+
+- `microgrid.electrical_components` (previously `microgrid.components`)
+
+    + `ElectricalComponentDiagnostic`: Message to represent warnings and errors in microgrid electrical components
+    + `ElectricalComponentDiagnosticCode` (previously `ComponentErrorCode`): New diagnostic codes to cover more cases, especially for inverters
+    + `InverterType.INVERTER_TYPE_WIND_TURBINE`: Enum value to represent wind turbine inverters
+
+- `microgrid.ElectricalComponentCategory` (previously `microgrid.ComponentCategory`) has been extended with new enum values:
+    + `ELECTRICAL_COMPONENT_CATEGORY_PLC`
+    + `ELECTRICAL_COMPONENT_CATEGORY_STATIC_TRANSFER_SWITCH`
+    + `ELECTRICAL_COMPONENT_CATEGORY_UNINTERRUPTIBLE_POWER_SUPPLY`
+    + `ELECTRICAL_COMPONENT_CATEGORY_CAPACITOR_BANK`
+    + `ELECTRICAL_COMPONENT_CATEGORY_SMART_LOAD`
+    + `ELECTRICAL_COMPONENT_CATEGORY_WIND_TURBINE`
+
+- `microgrid.sensors`
+
+    + Message linking microgrid and sensor IDs
+    + `SensorDiagnostic`: Message to represent warnings and errors in microgrid sensors
+    + Added warnings to sensor `SensorState`
+
+- `streaming`: Package with message definitions for streaming events
+
+    + `Event`: Enum to represent different types of streaming events (Created, Deleted, Updated)
+
+- `types`
+
+    + `Interval`: Message to standardize time interval filtering across APIs
+
+        This uses `start_time` (inclusive) and `end_time` (exclusive) fields, aligning with ISO 8601 and common programming conventions.
+

{frequenz-api-common-0.6.4 → frequenz_api_common-0.7.0}/proto/frequenz/api/common/v1/grid/delivery_area.proto

@@ -1,4 +1,4 @@
-// Frequenz definitions of grids as entites participating in trading.
+// Frequenz definitions of grids as entities participating in trading.
 //
 // Copyright 2023 Frequenz Energy-as-a-Service GmbH
 //

{frequenz-api-common-0.6.4 → frequenz_api_common-0.7.0}/proto/frequenz/api/common/v1/market/energy.proto

@@ -1,4 +1,4 @@
-// Frequenz definitions of energy for electricity trading.
+// Frequenz definitions of energy.
 //
 // Copyright 2023 Frequenz Energy-as-a-Service GmbH
 //
@@ -14,11 +14,11 @@ import "frequenz/api/common/v1/types/decimal.proto";
 // Represents a single unit of electricity.
 //
 // !!! note
-//     In these trading orders, the unit of energy is denominated in MWh
-//     (Megawatt-hours) as opposed to MW (Megawatts).  MWh is a unit of energy
-//     representing total output over a period, while MW is a unit of power that
-//     represents the rate of energy production or consumption.
+//     The unit of energy is denominated in MWh, which is a unit of energy
+//     representing total output over a period.(Megawatt-hours). This differs
+//     from MW (Megawatts), a unit of power representing the rate of energy
+//     production or consumption.
 message Energy {
-  // Represents energy unit in Megawatthours (MWh).
+  // Energy unit in Megawatthours (MWh).
   frequenz.api.common.v1.types.Decimal mwh = 1;
 }

frequenz_api_common-0.7.0/proto/frequenz/api/common/v1/market/power.proto

@@ -0,0 +1,30 @@
+// Frequenz definitions of power.
+//
+// Copyright 2024 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1.market;
+
+import "frequenz/api/common/v1/types/decimal.proto";
+
+// Represents a single unit of power.
+//
+// !!! note
+//     The power unit is denominated in MW (Megawatts), which is a unit of
+//     power representing the rate of energy production or consumption at any
+//     given moment. This differs from MWh (Megawatt-hours), which measures
+//     the total amount of energy delivered or consumed over a period.
+//
+// Example:
+//     A power plant running at 10 MW for 1 hour generates 10 MWh of energy.
+//
+// This message standardizes the representation of power in MW across all
+// market applications.
+message Power {
+  // Power amount in Megawatts (MW).
+  frequenz.api.common.v1.types.Decimal mw = 1;
+}

{frequenz-api-common-0.6.4 → frequenz_api_common-0.7.0}/proto/frequenz/api/common/v1/metrics/metric_sample.proto

@@ -63,6 +63,20 @@ message MetricValueVariant {
 }
 
 // List of supported metrics.
+//
+// !!! note
+// AC energy metrics information:
+//
+// * This energy metric is reported directly from the component, and not a
+//  result of aggregations in our systems. If a component does not have this
+//  metric, this field cannot be populated.
+//
+//  * Components that provide energy metrics reset this metric from time to
+//  time. This behaviour is specific to each component model. E.g., some
+//  components reset it on UTC 00:00:00.
+//
+//  * This energy metric does not specify the timestamp since when the energy
+//  was being accumulated, and therefore can be inconsistent.
 enum Metric {
   // Default value.
   METRIC_UNSPECIFIED = 0;

{frequenz-api-common-0.6.4 → frequenz_api_common-0.7.0}/proto/frequenz/api/common/v1/microgrid/components/components.proto

@@ -24,8 +24,7 @@ import "google/protobuf/timestamp.proto";
 
 // Enumrated component categories.
 enum ComponentCategory {
-  // An unknown component categories, useful for error handling, and marking
-  // unknown components in a list of components with otherwise known categories.
+  // The component category is unspecified. This should not be used.
   COMPONENT_CATEGORY_UNSPECIFIED = 0;
 
   // The point where the local microgrid is connected to the grid.

frequenz_api_common-0.7.0/proto/frequenz/api/common/v1/microgrid/lifetime.proto

@@ -0,0 +1,41 @@
+// Frequenz definition of entity lifetimes, based upon start and end timestamps.
+//
+// Copyright 2023 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1.microgrid;
+
+import "google/protobuf/timestamp.proto";
+
+// Lifetime captures the timestamps indicating the active operational period of
+// a microgrid asset, such as a component, connection, sensor, or any other
+// entity with a limited operational lifetime.
+//
+// It is normally used to track the historical evolution of assets, and it
+// determines the validity period for the asset's data.
+//
+// If the `start_timestamp` is not set, the asset is considered to be in
+// operation since the beginning of the system's operational history.
+//
+// If the `end_timestamp` is not set, the asset is considered to be in
+// operation indefinitely into the future.
+//
+// If the Lifetime message is completely missing, it means both timestamps are
+// not set, which means the asset is considered to be in operation since the
+// beginning of the system's operational history and indefinitely into the
+// future.
+message Lifetime {
+  // The timestamp when the asset became operationally active.
+  // If not set, the asset is considered to be in operation since the beginning
+  // of the system's operational history.
+  google.protobuf.Timestamp start_timestamp = 1;
+
+  // Optional timestamp when the asset's operational activity ceased.
+  // If not set, the asset is considered to be in operation indefinitely into
+  // the future.
+  google.protobuf.Timestamp end_timestamp = 2;
+}

{frequenz-api-common-0.6.4 → frequenz_api_common-0.7.0}/proto/frequenz/api/common/v1/microgrid/microgrid.proto

@@ -51,9 +51,15 @@ message Microgrid {
 
   // The delivery area where the microgrid is located, as identified by a
   // specific code.
+  //
+  // If a microgrid is not connected to the grid (it is an island) it does not
+  // belong to any delivery area and this field will be missing, but it could
+  // be missing for other reasons as well.
   frequenz.api.common.v1.grid.DeliveryArea delivery_area = 4;
 
   // Physical location of the microgrid, in geographical co-ordinates.
+  //
+  // If the location is not known, this field will be missing.
   frequenz.api.common.v1.Location location = 5;
 
   // The current status of the microgrid.

frequenz_api_common-0.7.0/proto/frequenz/api/common/v1/pagination/pagination_params.proto

@@ -0,0 +1,31 @@
+// Parameters for pagination.
+//
+// Copyright 2023 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1.pagination;
+
+// A message defining parameters for paginating list requests.
+// It can be appended to a request message to specify the desired page of
+// results and the maximum number of results per page.
+message PaginationParams {
+  oneof params {
+    // The maximum number of results to return in a single page. The service may
+    // return fewer results than requested. If unspecified, the service may
+    // choose a reasonable default.
+    // May only be specified in the first request.
+    uint32 page_size = 1;
+
+    // A token identifying a page of results to return. This should be the value
+    // of the `next_page_token` field in the previous response's PaginationInfo.
+    // For the first request, this field should be omitted.
+    //
+    // To avoid keeping remembering the page_size across requests, service
+    // implementations may choose to encode the page_size in the page_token.
+    string page_token = 2;
+  }
+}

frequenz_api_common-0.7.0/proto/frequenz/api/common/v1alpha7/grid/delivery_area.proto

@@ -0,0 +1,62 @@
+// Frequenz definitions of grids as entities participating in trading.
+//
+// Copyright 2023 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha7.grid;
+
+// CodeType specifies the type of identification code used for uniquely
+// identifying various entities such as delivery areas, market participants, and
+// grid components within the energy market. This enumeration aims to offer
+// compatibility across different jurisdictional standards.
+//
+// !!! note "Understanding Code Types"
+//     Different regions or countries may have their own standards for uniquely
+//     identifying various entities within the energy market. For example, in
+//     Europe, the Energy Identification Code (EIC) is commonly used for this
+//     purpose.
+//
+// !!! info "Extensibility"
+//     New code types can be added to this enum to accommodate additional
+//     regional standards, enhancing the API's adaptability.
+//
+// !!! caution "Validation Required"
+//     The chosen code type should correspond correctly with the `code` field in
+//     the relevant message objects, such as `DeliveryArea` or `Counterparty`.
+//     Failure to match the code type with the correct code could lead to
+//     processing errors.
+//
+enum EnergyMarketCodeType {
+  // Unspecified type. This value is a placeholder and should not be used.
+  ENERGY_MARKET_CODE_TYPE_UNSPECIFIED = 0;
+
+  // European Energy Identification Code Standard.
+  ENERGY_MARKET_CODE_TYPE_EUROPE_EIC = 1;
+
+  // North American Electric Reliability Corporation identifiers.
+  ENERGY_MARKET_CODE_TYPE_US_NERC = 2;
+}
+
+// DeliveryArea represents the geographical or administrative region, usually
+// defined and maintained by a Transmission System Operator (TSO), where
+// electricity deliveries for a contract occur.
+//
+// The concept is important to energy trading as it delineates the agreed-upon
+// delivery location. Delivery areas can have different codes based on the//
+// jurisdiction in which they operate.
+//
+// !!! note "Jurisdictional Differences"
+//     This is typically represented by specific codes according to local
+//     jurisdiction. In Europe, this is represented by an EIC
+//     (Energy Identification Code).
+message DeliveryArea {
+  // Code representing the unique identifier for the delivery area.
+  string code = 1;
+
+  // Type of code used for identifying the delivery area itself.
+  EnergyMarketCodeType code_type = 2;
+}

frequenz_api_common-0.7.0/proto/frequenz/api/common/v1alpha7/grid/delivery_duration.proto

@@ -0,0 +1,61 @@
+// Frequenz definitions of the time increment used for electricity
+// deliveries and trading.
+//
+// Copyright 2023 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha7.grid;
+
+import "google/protobuf/timestamp.proto";
+
+// DeliveryDuration represents the time increment, in minutes,
+// used for electricity deliveries and trading. These durations
+// serve as the basis for defining the delivery period in contracts,
+// and they dictate how energy is scheduled and delivered to meet
+// contractual obligations.
+//
+// !!! note "Compatibility Constraints"
+//     Not all delivery durations are universally
+//     compatible with all delivery areas or markets.
+//
+enum DeliveryDuration {
+  // Default value, indicates that the duration is unspecified.
+  DELIVERY_DURATION_UNSPECIFIED = 0;
+
+  // 5-minute duration
+  DELIVERY_DURATION_5 = 1;
+
+  // 15-minute contract duration.
+  DELIVERY_DURATION_15 = 2;
+
+  // 30-minute contract duration.
+  DELIVERY_DURATION_30 = 3;
+
+  // 1-hour contract duration.
+  DELIVERY_DURATION_60 = 4;
+}
+
+// DeliveryPeriod represents the time period during which the contract
+// is delivered. It is defined by a start timestamp and a duration.
+message DeliveryPeriod {
+  // Start UTC timestamp represents the beginning of the delivery period.
+  // This timestamp is inclusive, meaning that the delivery period starts
+  // from this point in time.
+  //
+  // !!! note
+  //     Delivery period start time constraints:
+  //     - 5-minute durations must start at times that are multiples of
+  //       5 minutes past the hour.
+  //     - 15-minute durations must start at :00, :15, :30, or
+  //       :45 past the hour.
+  //     - 30-minute durations must start at :00 or :30 past the hour.
+  //     - 60-minute durations must start at :00 past the hour.
+  google.protobuf.Timestamp start = 1;
+
+  // The length of the delivery period.
+  DeliveryDuration duration = 2;
+}

frequenz_api_common-0.7.0/proto/frequenz/api/common/v1alpha7/market/energy.proto

@@ -0,0 +1,24 @@
+// Frequenz definitions of energy.
+//
+// Copyright 2023 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha7.market;
+
+import "frequenz/api/common/v1alpha7/type/decimal.proto";
+
+// Represents a single unit of electricity.
+//
+// !!! note
+//     The unit of energy is denominated in MWh, which is a unit of energy
+//     representing total output over a period.(Megawatt-hours). This differs
+//     from MW (Megawatts), a unit of power representing the rate of energy
+//     production or consumption.
+message Energy {
+  // Energy unit in Megawatthours (MWh).
+  frequenz.api.common.v1alpha7.type.Decimal mwh = 1;
+}

frequenz_api_common-0.7.0/proto/frequenz/api/common/v1alpha7/market/power.proto

@@ -0,0 +1,30 @@
+// Frequenz definitions of power.
+//
+// Copyright 2024 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha7.market;
+
+import "frequenz/api/common/v1alpha7/type/decimal.proto";
+
+// Represents a single unit of power.
+//
+// !!! note
+//     The power unit is denominated in MW (Megawatts), which is a unit of
+//     power representing the rate of energy production or consumption at any
+//     given moment. This differs from MWh (Megawatt-hours), which measures
+//     the total amount of energy delivered or consumed over a period.
+//
+// Example:
+//     A power plant running at 10 MW for 1 hour generates 10 MWh of energy.
+//
+// This message standardizes the representation of power in MW across all
+// market applications.
+message Power {
+  // Power amount in Megawatts (MW).
+  frequenz.api.common.v1alpha7.type.Decimal mw = 1;
+}

frequenz_api_common-0.7.0/proto/frequenz/api/common/v1alpha7/market/price.proto

@@ -0,0 +1,53 @@
+// Frequenz definitions of price for electricity trading.
+//
+// Copyright 2023 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha7.market;
+
+import "frequenz/api/common/v1alpha7/type/decimal.proto";
+
+// Represents a monetary price for electricity trading, including
+// the amount and currency. The currency used should align with the
+// delivery area's standard currency.
+//
+// !!! caution "Validation Required"
+//     It's essential to ensure that the currency aligns with the
+//     standard currency of the associated delivery area. Failure to
+//     do so may result in the API service rejecting the request due to currency
+//     mismatches.
+//
+// !!! info "Relation to Delivery Area"
+//     The currency specified is intrinsically related to the delivery area
+//     for the contract. Make sure the chosen currency is compatible with
+//     the delivery area's currency standards.
+//
+message Price {
+  // List of supported currencies.
+  //
+  // !!! info "Extensibility"
+  //     New currencies can be added to this enum to support additional markets.
+  enum Currency {
+    CURRENCY_UNSPECIFIED = 0;
+    CURRENCY_USD = 1;
+    CURRENCY_CAD = 2;
+    CURRENCY_EUR = 3;
+    CURRENCY_GBP = 4;
+    CURRENCY_CHF = 5;
+    CURRENCY_CNY = 6;
+    CURRENCY_JPY = 7;
+    CURRENCY_AUD = 8;
+    CURRENCY_NZD = 9;
+    CURRENCY_SGD = 10;
+  }
+
+  // The amount of the price.
+  frequenz.api.common.v1alpha7.type.Decimal amount = 1;
+
+  // The currency in which the price is denominated.
+  Currency currency = 2;
+}

frequenz_api_common-0.7.0/proto/frequenz/api/common/v1alpha7/metrics/bounds.proto

@@ -0,0 +1,23 @@
+// Definitions for bounds.
+//
+// Copyright:
+// Copyright 2023 Frequenz Energy-as-a-Service GmbH
+//
+// License:
+// MIT
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha7.metrics;
+
+// A set of lower and upper bounds for any metric.
+// The units of the bounds are always the same as the related metric.
+message Bounds {
+  // The lower bound.
+  // If absent, there is no lower bound.
+  optional float lower = 1;
+
+  // The upper bound.
+  // If absent, there is no upper bound.
+  optional float upper = 2;
+}