Smarter commodity-context defaults and Commitment commodity field

.claude/agents/api-backward-compatibility-specialist.md

@@ -1,6 +1,7 @@
 ---
 name: api-backward-compatibility-specialist
 description: Protects users and integrators by ensuring API changes are backwards compatible, properly versioned, and well-documented
+model: sonnet
 ---
 
 # Agent: API & Backward Compatibility Specialist

.claude/agents/architecture-domain-specialist.md

@@ -1,6 +1,7 @@
 ---
 name: architecture-domain-specialist
 description: Guards domain model, invariants, and architecture to maintain model clarity and prevent erosion of core principles
+model: opus
 ---
 
 # Agent: Architecture & Domain Specialist

.claude/agents/coordinator.md

@@ -1,6 +1,7 @@
 ---
 name: coordinator
 description: Meta-agent that manages agent lifecycle, enforces structural standards, and maintains coherence across the agent system
+model: sonnet
 ---
 
 # Agent: Coordinator

.claude/agents/data-time-semantics-specialist.md

@@ -1,6 +1,7 @@
 ---
 name: data-time-semantics-specialist
 description: Prevents subtle bugs in time handling, units, and data semantics with focus on timezone-aware operations and unit conversions
+model: sonnet
 ---
 
 # Agent: Data & Time Semantics Specialist

.claude/agents/documentation-developer-experience-specialist.md

@@ -1,6 +1,7 @@
 ---
 name: documentation-developer-experience-specialist
 description: Ensures excellent documentation, clear error messages, and smooth developer workflows to keep FlexMeasures accessible
+model: sonnet
 ---
 
 # Agent: Documentation & Developer Experience Specialist

.claude/agents/performance-scalability-specialist.md

@@ -1,6 +1,7 @@
 ---
 name: performance-scalability-specialist
 description: Identifies performance bottlenecks, inefficient algorithms, and scalability issues to keep FlexMeasures fast under load
+model: sonnet
 ---
 
 # Agent: Performance & Scalability Specialist

.claude/agents/test-specialist.md

@@ -1,6 +1,7 @@
 ---
 name: test-specialist
 description: Focuses on test coverage, quality, and testing best practices without modifying production code
+model: sonnet
 ---
 
 # Agent: Test Specialist

.claude/agents/tooling-ci-specialist.md

@@ -1,6 +1,7 @@
 ---
 name: tooling-ci-specialist
 description: Reviews GitHub Actions workflows, pre-commit hooks, and CI/CD pipelines to ensure automation reliability
+model: sonnet
 ---
 
 # Agent: Tooling & CI Specialist

.claude/agents/ui-specialist.md

@@ -1,6 +1,7 @@
 ---
 name: ui-specialist
 description: Guards UI consistency, permission patterns, JavaScript interaction patterns, and template quality in the FlexMeasures web interface
+model: sonnet
 ---
 
 # Agent: UI Specialist

documentation/changelog.rst

@@ -18,7 +18,7 @@ New features
 * Sensor references in flex-model and flex-context support various ways of filtering by source [see `PR #2209 <https://www.github.com/FlexMeasures/flexmeasures/pull/2209>`_]
 * Let storage scheduling infer missing ``power-capacity`` from directional device capacities before falling back to site capacity, and default the missing opposite capacity to zero when only a non-zero ``consumption-capacity`` or ``production-capacity`` is configured [see `PR #2222 <https://www.github.com/FlexMeasures/flexmeasures/pull/2222>`_]
 * Support multiple feeders to a shared storage [see `PR #2001 <https://www.github.com/FlexMeasures/flexmeasures/pull/2001>`_ ]
-* The flex-context can now define multiple commodities, each specifying their own prices and grid capacities [see `PR #1946 <https://www.github.com/FlexMeasures/flexmeasures/pull/1946>`_, `PR #2172 <https://www.github.com/FlexMeasures/flexmeasures/pull/2172>`_, `PR #2235 <https://www.github.com/FlexMeasures/flexmeasures/pull/2235>`_ and `PR #2271 <https://www.github.com/FlexMeasures/flexmeasures/pull/2271>`_]
+* The flex-context can now define multiple commodities, each specifying their own prices and grid capacities [see `PR #1946 <https://www.github.com/FlexMeasures/flexmeasures/pull/1946>`_, `PR #2172 <https://www.github.com/FlexMeasures/flexmeasures/pull/2172>`_, `PR #2235 <https://www.github.com/FlexMeasures/flexmeasures/pull/2235>`_, `PR #2271 <https://www.github.com/FlexMeasures/flexmeasures/pull/2271>`_ and `PR #2272 <https://www.github.com/FlexMeasures/flexmeasures/pull/2272>`_]
 * CLI support for adding/editing account attributes [see `PR #2242 <https://www.github.com/FlexMeasures/flexmeasures/pull/2242>`_]
 * Extended ``GET /api/v3_0/jobs/<uuid>`` with a ``result`` field containing ``unresolved`` and ``resolved`` soft state-of-charge constraint analysis (``soc-minima``/``soc-maxima`` violations or satisfied constraints, keyed by asset ID) for scheduling jobs; both arrays are empty when no SoC constraints were defined [see `PR #2072 <https://www.github.com/FlexMeasures/flexmeasures/pull/2072>`_]
 

documentation/features/scheduling.rst

@@ -149,6 +149,32 @@ And if the asset belongs to a larger system (a hierarchy of assets), the schedul
           The flexible device can still have its own power limit defined in its flex-model.
 
 
+.. _commodity_context_defaults:
+
+Smart defaults for commodity-context grid connections
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For multi-commodity scheduling problems, each entry of the top-level ``commodities`` list is itself a flex-context (a "commodity context") describing the grid connection for that commodity.
+A commodity context that leaves out some or all of its grid-connection fields (``consumption-price``, ``production-price``, ``site-consumption-capacity``, ``site-production-capacity`` and ``site-power-capacity``) gets sensible defaults for the missing fields, rather than failing or silently leaving the grid unconstrained.
+
+As a rule of thumb, a price given for a direction (consumption or production) implies a grid connection in that direction, with an unlimited capacity unless a capacity is also given; a capacity given for a direction (without a price) implies a 0 price in that direction; and anything not implied by a given field defaults to "no connection" (0 capacity, as a soft constraint).
+The exception is ``site-power-capacity`` given on its own, which sets a *hard* (symmetric) capacity limit instead.
+
+This leads to the following defaults, depending on which fields are explicitly given:
+
+- **Nothing given** (e.g. just ``{"commodity": "gas"}``): both ``site-consumption-capacity`` and ``site-production-capacity`` default to 0, as soft constraints (a breach is possible, but penalized). ``site-power-capacity`` stays unlimited.
+- **Only** ``consumption-price``: ``site-power-capacity`` and ``site-consumption-capacity`` stay unlimited; ``site-production-capacity`` defaults to 0 (soft).
+- **Only** ``production-price``: the mirror image, for production.
+- **Only** ``site-consumption-capacity``: ``site-power-capacity`` stays unlimited; ``consumption-price`` defaults to 0; ``site-production-capacity`` (and, transitively, ``production-price``) default to 0.
+- **Only** ``site-production-capacity``: the mirror image, for production.
+- **Only** ``site-power-capacity``: a *hard* constraint at that capacity, with ``site-consumption-capacity`` and ``site-production-capacity`` both set equal to it, and ``consumption-price``/``production-price`` defaulting to 0.
+
+For any combination of explicitly given fields, these rules apply per direction (consumption/production) independently, filling in only the fields not already determined by a given field.
+As a safety net, ``consumption-price`` still defaults to 0 if it remains unset after applying the rules above, since the scheduler requires a resolvable consumption price.
+
+.. note:: Setting ``relax-constraints`` to ``False`` on a commodity context that ends up with a smart-defaulted 0 hard capacity can make the schedule infeasible; FlexMeasures logs a warning in that case.
+
+
 .. _flex_models_and_schedulers:
 
 The flex-models & corresponding schedulers

flexmeasures/data/models/planning/storage.py

@@ -35,6 +35,7 @@
     CommodityFlexContextSchema,
     FlexContextSchema,
     MultiSensorFlexModelSchema,
+    SharedSchema,
 )
 from flexmeasures.data.schemas.sensors import SensorReference, VariableQuantityField
 from flexmeasures.data.services.scheduling_result import SchedulingJobResult
@@ -1351,6 +1352,7 @@ def convert_to_commitments(
                 start, end, timing_kwargs["resolution"]
             )
             commitment_commodity = commitment_spec.get("commodity", "electricity")
+            bound_device_count = 0
             for d, flex_model_d in enumerate(flex_model):
                 device_commodity = flex_model_d.get("commodity", "electricity")
                 if device_commodity != commitment_commodity:
@@ -1361,6 +1363,15 @@ def convert_to_commitments(
                     **commitment_spec,
                 )
                 commitments.append(commitment)
+                bound_device_count += 1
+            if bound_device_count == 0:
+                current_app.logger.warning(
+                    f"Commitment '{commitment_spec.get('name')}' has commodity"
+                    f" '{commitment_commodity}', which matches none of the devices"
+                    " in the flex-model. This commitment will not bind any device"
+                    " (check for a typo in the commitment's `commodity` field, or in"
+                    " a device's `commodity` field in the flex-model)."
+                )
 
         return commitments
 
@@ -1408,9 +1419,17 @@ def _deserialize_flex_context(self):
                     commodity_flex_context
                 )
 
-            # Ensure all flex-contexts share the same currency unit
+            # Ensure all flex-contexts share the same currency unit. Contexts with
+            # no user-given price fields at all (shared_currency_unit_is_default)
+            # only carry a fallback "EUR" currency, which isn't a real constraint,
+            # so they're skipped here and instead backfilled below, once a real
+            # portfolio currency is known.
             shared_currency_unit = None
+            default_currency_contexts = []
             for commodity_flex_context in self.flex_context:
+                if commodity_flex_context.get("shared_currency_unit_is_default"):
+                    default_currency_contexts.append(commodity_flex_context)
+                    continue
                 context_currency_unit = commodity_flex_context["shared_currency_unit"]
                 if shared_currency_unit is None:
                     shared_currency_unit = context_currency_unit
@@ -1421,6 +1440,20 @@ def _deserialize_flex_context(self):
                         f"All prices in the flex-context must share the same currency unit (in this case: '{shared_currency_unit}')."
                     )
 
+            # Let price-free contexts inherit the portfolio's actual currency,
+            # where determinable (i.e. when at least one other context set one).
+            if shared_currency_unit is not None:
+                for commodity_flex_context in default_currency_contexts:
+                    SharedSchema._rebase_default_context_currency(
+                        commodity_flex_context, shared_currency_unit
+                    )
+            elif default_currency_contexts:
+                # No context anywhere gave an explicit price: fall back to the
+                # (shared) default currency already stamped on each of them.
+                shared_currency_unit = default_currency_contexts[0][
+                    "shared_currency_unit"
+                ]
+
             # Nest the flex-contexts per commodity under the commodity_contexts field
             self.flex_context = dict(
                 commodity_contexts=self.flex_context,

flexmeasures/data/models/planning/tests/test_commitments.py

@@ -17,6 +17,7 @@
 from flexmeasures.data.models.planning.linear_optimization import device_scheduler
 from flexmeasures.data.models.generic_assets import GenericAsset, GenericAssetType
 from flexmeasures.data.utils import save_to_db
+from flexmeasures.utils.unit_utils import ur
 
 
 def test_multi_feed_device_scheduler_shared_buffer():
@@ -1782,3 +1783,63 @@ def test_electricity_device_indices_exclude_other_commodities():
     assert mapping["electricity"] == [0, 2, 3, 4]
     assert mapping["gas"] == [1, 5]
     assert scheduler._electricity_device_indices() == [0, 2, 3, 4]
+
+
+def test_commitment_commodity_does_not_bind_other_commodity_devices():
+    """test_commitment_commodity_does_not_bind_other_commodity_devices: a commitment
+    listed under the flex-context's `commitments` should only bind devices of its own
+    `commodity` (defaulting to "electricity", like devices do). A gas commitment
+    should therefore not create a FlowCommitment against an electricity device, and
+    vice versa.
+
+    This is a DB-free, unit-level test of StorageScheduler.convert_to_commitments.
+    """
+    scheduler = object.__new__(StorageScheduler)
+    scheduler.flex_context = {
+        "shared_currency_unit": "EUR",
+        "commitments": [
+            {
+                "name": "gas commitment",
+                "commodity": "gas",
+                "baseline": ur.Quantity("1 MW"),
+            },
+            {
+                # No `commodity` given: defaults to "electricity", like devices do.
+                "name": "electricity commitment",
+                "baseline": ur.Quantity("2 MW"),
+            },
+        ],
+    }
+    # Flexible devices: 0 = electricity, 1 = gas.
+    flex_model = [
+        {"commodity": "electricity"},
+        {"commodity": "gas"},
+    ]
+
+    start = pd.Timestamp("2024-01-01T00:00:00+01:00")
+    end = pd.Timestamp("2024-01-01T03:00:00+01:00")
+    resolution = pd.Timedelta("1h")
+
+    commitments = scheduler.convert_to_commitments(
+        flex_model=flex_model,
+        query_window=(start, end),
+        resolution=resolution,
+        beliefs_before=None,
+    )
+
+    assert len(commitments) == 2
+
+    gas_commitment = next(c for c in commitments if c.name == "gas commitment")
+    electricity_commitment = next(
+        c for c in commitments if c.name == "electricity commitment"
+    )
+
+    # The gas commitment binds only the gas device (index 1), not the electricity
+    # device (index 0).
+    assert (gas_commitment.device == 1).all()
+    assert set(gas_commitment.device_group.unique()) == {"gas"}
+
+    # The electricity commitment (commodity defaulting to "electricity") binds only
+    # the electricity device (index 0), not the gas device (index 1).
+    assert (electricity_commitment.device == 0).all()
+    assert set(electricity_commitment.device_group.unique()) == {"electricity"}