Add soft constraint analysis (unresolved/resolved SoC constraints) to scheduling job results

[Copilot]

Description

Adds soft constraint analysis to scheduling job results: when a StorageScheduler job finishes, GET /api/v3_0/jobs/<uuid> now reports which soc-minima/soc-maxima targets could not be met (unresolved) and which were met, together with their remaining headroom (resolved). This makes it possible to inspect why a schedule looks the way it does without having to reverse-engineer it from the raw power/SoC series.

• Compute per-device soc-minima/soc-maxima violations and margins in StorageScheduler._compute_unresolved_targets (flexmeasures/data/models/planning/storage.py), keyed by asset ID.
• Introduce SchedulingJobResult (flexmeasures/data/services/scheduling_result.py) as the serializable container for unresolved/resolved, stored on the RQ job's return_value (flexmeasures/data/services/scheduling.py).
• Surface the result via the existing result field on GET /api/v3_0/jobs/<uuid> (flexmeasures/api/v3_0/jobs.py) — this is the only place constraint analysis is available; GET /api/v3_0/sensors/<id>/schedules/<uuid> continues to return power values only. The result field of the GET /api/v3_0/jobs/<uuid> endpoint is, for scheduling jobs, no longer a boolean, but an actual object where we can start returning more scheduling results. For now, it only contains unresolved/resolved info.
• Add a most_relevant_only: bool = False option to _compute_unresolved_targets: by default every violated/met slot is reported (chronologically ordered); set to True to get only the single most relevant slot (first violation, or tightest margin) — either way, each constraint key holds a list.
• Document the feature end-to-end: OpenAPI docstrings/spec, documentation/features/scheduling.rst ("Accessing constraint results" section, with a worked multi-asset example), and documentation/api/change_log.rst (v3.0-32).
• Added changelog item in documentation/changelog.rst
• Update the .github/agents/*.md specialist instructions with lessons learned during this PR (see "Changes to AI infra" below).

Response shape

{
  "status": "FINISHED",
  "message": "Scheduling job finished.",
  "result": {
    "unresolved": [
      {
        "asset": 42,
        "soc-minima": [
          {"datetime": "2024-01-01T10:00:00+00:00", "violation": "260.0 kWh"},
          {"datetime": "2024-01-01T10:15:00+00:00", "violation": "180.0 kWh"}
        ]
      }
    ],
    "resolved": []
  }
}

• unresolved/resolved are lists of per-asset dicts, keyed by asset ID (not sensor ID) — so a multi-asset scheduling job reports constraint results for every flexible device it scheduled, in one response.
• Each soc-minima/soc-maxima value is itself a list: one entry per violated slot (unresolved) or per met slot with its margin (resolved), chronologically ordered by default.
• soc-targets (hard constraints) are never reported here — the scheduler enforces them strictly, so a hard-constraint failure fails the job outright rather than appearing as a soft violation.

Changes to AI infra

Part of this PR's development happened by handing work back and forth between GitHub Copilot's coding agent and Claude Code, both operating against the same repo-local specialist-agent framework (AGENTS.md, .github/agents/*.md, .github/instructions/*.md). As a result, this PR also carries some infra changes unrelated to the feature itself but load-bearing for how the repo's AI agents operate:

• .github/agents/api-backward-compatibility-specialist.md, architecture-domain-specialist.md, documentation-developer-experience-specialist.md, test-specialist.md: appended "lessons learned" sections captured while building this feature (e.g. asset-keying/format-mismatch patterns, cross-document consistency checks, data-format-transformation test patterns).
• .github/instructions/feature-branch-sync.instructions.md (new): codifies checking git log --oneline origin/main...HEAD --left-right (not just git status) before starting implementation work, and merging origin/main in before proceeding — added after a session where the feature branch had drifted 10+ commits behind main.
• .github/instructions/docstrings.instructions.md: minor conventions (:returns: instead of :return:; line breaks only after punctuation).
• AGENTS.md: a session-lesson entry and a corresponding "branch in sync with main" pre-commit checklist item.
• .claude/agents/*.md (new, 9 files): thin stubs mirroring the .github/agents/*.md personas for Claude Code, added separately by the maintainer (not generated as part of the feature work).

None of this affects runtime behavior; it's process/tooling scoped to how AI coding agents work in this repo.

Look & Feel

Request:

GET /api/v3_0/jobs/5d28df1b-9f16-4177-ae43-6e750d80fad3

Response (finished scheduling job, one unresolved soc-minima violated at two slots, one resolved soc-maxima with margin):

{
  "status": "FINISHED",
  "message": "Scheduling job has finished.",
  "result": null,
  "func_name": "flexmeasures.data.services.scheduling.create_schedule",
  "origin": "scheduling",
  "enqueued_at": "2026-04-28T10:00:00+00:00",
  "started_at": "2026-04-28T10:00:01+00:00",
  "ended_at": "2026-04-28T10:00:05+00:00",
  "exc_info": null,
  "result": {
    "unresolved": [
      {
        "asset": 42,
        "soc-minima": [
          {"datetime": "2024-01-01T10:00:00+00:00", "violation": "260.0 kWh"},
          {"datetime": "2024-01-01T10:15:00+00:00", "violation": "180.0 kWh"}
        ]
      }
    ],
    "resolved": [
      {
        "asset": 42,
        "soc-maxima": [
          {"datetime": "2024-01-01T12:00:00+00:00", "margin": "40.0 kWh"}
        ]
      }
    ]
  }
}

If no SoC constraints were defined for any scheduled asset, both unresolved and resolved are empty lists.

How to test

Run the storage-scheduler test module, which covers unresolved/resolved reporting end to end (via StorageScheduler.compute()) as well as the most_relevant_only flag directly:

pytest flexmeasures/data/models/planning/tests/test_storage.py -v

Key test functions:

• test_unresolved_targets_soc_minima / test_unresolved_targets_soc_maxima — unresolved (violated) constraints are reported with the correct asset ID, datetime, and violation magnitude.
• test_unresolved_targets_none_when_met — met constraints are reported under resolved with a non-negative margin.
• test_unresolved_targets_no_soc_sensor — asset-keyed reporting still works for devices without a state-of-charge sensor in the flex model.
• test_unresolved_targets_most_relevant_only_flag_soc_minima_violations — default (most_relevant_only=False) reports every violated slot chronologically; most_relevant_only=True reports only the first.
• test_unresolved_targets_most_relevant_only_flag_soc_minima_resolved_margins — same distinction for resolved margins (all met slots vs. only the tightest).

End to end, also try triggering a real scheduling job with an unreachable soc-minima/soc-maxima (e.g. via POST /api/v3_0/assets/<id>/schedules/trigger) and then inspecting GET /api/v3_0/jobs/<uuid>.

Full suite (1346 passed, 4 xfailed at the time of writing) and pre-commit run --all-files should both be clean.

Further Improvements

• most_relevant_only is currently only a parameter of the private StorageScheduler._compute_unresolved_targets method (always called with the default from compute()); it is not yet exposed through the public flex-model/flex-context or the API. A follow-up could expose it if callers want the terser single-slot-per-constraint response.

Related Items

Closes/implements the "compute first unmet SoC targets" work tracked under this PR's branch name (copilot/compute-first-unmet-targets).

---

Sign-off

• I agree to contribute to the project under Apache 2 License.
• To the best of my knowledge, the proposed patch is not based on code under GPL or other license that is incompatible with FlexMeasures.

[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.

[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.

[Flix6x]

@nhoening I still need to deal with the 3 tests failing on Python 3.10 on a floating point imprecision, but nevertheless this is ready for review.

[nhoening]

Pretty nice!

As usual, my comments mainly are about the docs & naming.