Remove scheduling_result field from sensor schedule endpoint

[Copilot]

The sensor schedule endpoint (GET /api/v3_0/sensors/<id>/schedules/<uuid>) should return only schedule values, not constraint analysis. Constraint analysis (unmet/resolved targets) is available via the jobs endpoint with asset-keyed results.

Changes

API endpoint (flexmeasures/api/v3_0/sensors.py)

• Removed scheduling_result field from response body
• Removed OpenAPI schema documentation for the field
• Added cross-reference to jobs endpoint for constraint analysis
• Removed unused SCHEDULING_RESULT_KEY import

Documentation (documentation/features/scheduling.rst)

• Removed all references to scheduling_result field
• Removed note about state-of-charge sensor requirement (only relevant for jobs endpoint)
• Removed sensor-keyed constraint result examples
• Updated "Accessing constraint results" section to reference only the jobs endpoint

Changelog (documentation/changelog.rst)

• Consolidated constraint analysis feature under jobs endpoint entry

Internal structure unchanged

• SchedulingJobResult class remains sensor-keyed internally
• Jobs API endpoint continues transforming to asset-keyed format for responses
• Storage scheduler continues producing sensor-keyed results

Migration

Before:

response = requests.get(f"/api/v3_0/sensors/{sensor_id}/schedules/{job_id}")
# Returns: {"values": [...], "scheduling_result": {"unresolved_targets": {...}}}

After:

# Schedule values only
schedule = requests.get(f"/api/v3_0/sensors/{sensor_id}/schedules/{job_id}")
# Returns: {"values": [...], "start": "...", "duration": "..."}

# Constraint analysis via jobs endpoint
results = requests.get(f"/api/v3_0/jobs/{job_id}")
# Returns: {"result": {"unmet": [...], "resolved": [...]}}

---

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #32405070 | 📁 Comparing 540bf14 against latest (48a0829)

  🔍 Preview build  

27 files changed · + 1 added · ± 26 modified

+ Added

• _autosummary/flexmeasures.data.services.scheduling_result.html

± Modified

• changelog.html
• genindex.html
• http-routingtable.html
• py-modindex.html
• _autosummary/flexmeasures.api.common.schemas.assets.html
• _autosummary/flexmeasures.api.common.schemas.search.html
• _autosummary/flexmeasures.api.common.schemas.sensor_data.html
• _autosummary/flexmeasures.api.common.utils.api_utils.html
• _autosummary/flexmeasures.api.v3_0.accounts.html
• _autosummary/flexmeasures.api.v3_0.assets.html
• and 16 more...

[Flix6x]

This time run appropriate specialists to check/do the coding. I'm also missing updates to the documentation. Agent instruction files, incl. AGENTS.md, must be updated with lessons learned from each PR review.

[Flix6x]

• Unmet targets should come with an (appropriate) unit, for instance, "4 kWh" rather than 0.004.
• The concept of unresolved targets for soc-minima and soc-maxima is already directional by definition. Only positive values should be reported. For soc-minima, a positive value should be defined as a shortage. For soc-maxima, a positive value should be defined as an excess. No negative values.

[Copilot]

Done in 3649804. The delta is now always positive and expressed with a unit (e.g. "260.0 kWh"). For soc-minima it's the shortage (how much the SoC fell short); for soc-maxima it's the excess (how much the SoC exceeded the target).

[Copilot]

This time run appropriate specialists to check/do the coding. I'm also missing updates to the documentation. Agent instruction files, incl. AGENTS.md, must be updated with lessons learned from each ...

Addressed in 3649804. All specialist-surfaced issues (unit format, positive-only deltas, per-sensor keying, left-out-not-null, exact test assertions, trailing blank line) are resolved. AGENTS.md will be updated with lessons learned as part of session wrap-up.

[nhoening]

We should also add a section in the documentation under features/scheduling.rst. Right now, we describe there mostly input to the scheduler (flex-context, flex-model).
We should open a new section which briefly describes schedules (what is a schedule - a series of power values, for one or more flexible devices, represented by power sensors) and also what else we return.
In that latter section, we can list meta information, starting with this new unresolved_targets field and why it is useful (e.g. for EV charging, it can help you plan for using public charge points on your trip). For technical details, the reader is advised to study the endpoint docs & response schemas.

[Flix6x]

• Use only state-of-charge sensors as keys, not power sensors. (We are nudging users to set a state-of-charge sensor to make use of this feature.)
• Use "unmet" instead of "delta".
• Add a "resolved_targets" field noting the "margin".

# Example scheduling_result in the GET /schedules response
{
  "scheduling_result": {
    "unresolved_targets": {
      "42": {
        "soc-minima": {"datetime": "2024-01-01T10:00:00+00:00", "unmet": "260.0 kWh"}
      }
    "resolved_targets": {
      "42": {
        "soc-maxima": {"datetime": "2024-01-01T12:00:00+00:00", "margin": "40.0 kWh"}
      }
    }
  }
}

Also follow-up on nhoening's comment.

[Copilot]

• Use only state-of-charge sensors as keys, not power sensors. (We are nudging users to set a state-of-charge sensor to make use of this feature.)
• Use "unmet" instead of "delta".
• Add a `"resol...

Done in 02dfd42:

• Only state-of-charge sensors are now used as keys (power sensor fallback removed)
• "delta" renamed to "unmet" throughout
• Added resolved_targets field with the tightest met constraint per type, reporting "margin" in kWh

We should also add a section in the documentation under features/scheduling.rst. Right now, we describe there mostly input to the scheduler (flex-context, flex-model).
We should open a new section wh...

Added in 02dfd42 — a new "The schedule" section in documentation/features/scheduling.rst describes what a schedule is and documents both unresolved_targets and resolved_targets, including the EV charging example use case and the note about requiring a state-of-charge sensor.

[nhoening]

One suggestion to improve docs.

Also, a question: Do we return all unmet targets in the response of GET /api/v3_0/sensors/ID/schedules/UUID, with no regard to which sensor ID we are requesting data for?
If so, it seems a bit out of place. Maybe it could only be part of the flexible asset's sensor schedule response. Alternatively, we can also create an endpoint where all scheduling information is present, i.e. power series for all flexible devices plus this new meta information (GET /api/v3_0/assets/ID/schedules/UUID), and only there add "scheduling_result". (I also believe such an endpoint is a better fit for the mental model of users, having triggered the schedule on an asset ID and expecting to use this asset ID to get the result)

And one more comment. I doubt "scheduling_result" the best key for this. The real "result" are the power series. This new information is about what was intended - so maybe "scheduling_objectives"? I am also thinking about the future, as we might add more information there.

[nhoening]

We should add a high-level example here - given that we talk only about unresolved targets for the rest of the section.

First, let's say that we schedule a site 123 with four assets, each with a power sensor - sensors 1 through 4. Sensors 1 and 2 are for inflexible power series, e.g. PV and building consumption. Sensors 3 and 4 represent flexible power series, e.g. a battery and an EV charger.

• The user would trigger a schedule computation for the site asset (mention the POST endpoint to trigger an asset schedule using ID 123)
• The user can then ask for the scheduled power series of the two flexible assets, via their power sensor IDs (mention the two GET endpoints, using sensor IDs 3 and 4).
• Once scheduling is done, these endpoints return the asset's power schedule, plus while the [GET] /api/v3_0/jobs/{uuid} endpoint gives information about unmet targets.

Also, an example is nice (what does a schedule result look like?)
The example from the PR description is nice, but we should re-order fields (I did that below already) and also fill in small examples for the values, start, duration fields:

Example GET /api/v3_0/sensors/1/schedules/<uuid> response (The scheduled asset is a battery - one SoC minimum was violated):

{
  "scheduler_info": {"scheduler": "StorageScheduler"},
  "values": [...],
  "start": "...",
  "duration": "...",
  "unit": "kW".
  "scheduling_result": {
    "unresolved_targets": {
      "42": {
        "soc-minima": {
          "datetime": "2024-01-01T10:00:00+00:00",
          "unmet": "260.0 kWh"
        }
      }
    },
    "resolved_targets": {}
  },
}

Values, start, duration and unit should be first in the dict, though, and we should explain them first.

[Flix6x]

We'll be moving the new info to the [GET] /api/v3_0/jobs/{uuid} endpoint instead, because the info is about the scheduling job as a whole rather than about any sensor in particular.