[Flix6x]

Description

Since #2689 (with #2571), the result of a reporting or scheduling job counts the beliefs it saved, and no longer says how many it computed. So "0 saved" cannot tell a run that computed nothing from one that only repeated what is on record. This PR returns both, additively: the saved counts keep their v1.1.0 meaning and names.

• save_generator_results returns n_computed next to n_rows (saved) for each output. This reaches the result of reporting jobs (run_report_job), plugin automation jobs (execute_automation_job) and compute_and_save_report.
• make_schedule (and SchedulingJobResult) adds num-computed-beliefs next to num-beliefs, kebab-case like its neighbours. It is counted on a dry run too, where num-beliefs stays 0.
• "Computed" means every belief the data generator returned, before NaN values and beliefs already on record are left out. "Saved" leaves out both of those. The docstrings say so.
• The reporting job's log line gives both counts per output.
• flexmeasures add report and flexmeasures add schedule say both counts where they differ. add schedule no longer says "New schedule is stored." when a rerun saved nothing.
• GET /api/v3_0/jobs/<uuid> docs (and the regenerated OpenAPI spec) describe the new fields, including the reporting job's result, which was undocumented before.
• Changelog: extended the existing Let the service record what a data generator returns #2689/Consolidate report computation and persistence into one shared service function #2571 Bugfix entry in documentation/changelog.rst, since these counts change meaning within the unreleased v1.1.0. Also added lines to the API changelog (v3.0-34) and the CLI changelog.

Look & Feel

Scheduling job result (GET /api/v3_0/jobs/<uuid>), rerun of a schedule already on record:

before: {"unresolved": [], "resolved": [], "num-beliefs": 0}
after:  {"unresolved": [], "resolved": [], "num-beliefs": 0, "num-computed-beliefs": 96}

Reporting job result, rerun:

before: [{"sensor_id": 7, "n_rows": 0}]
after:  [{"sensor_id": 7, "n_computed": 5, "n_rows": 0}]

Reporting job log:

before: Report by <source> ran successfully, but every value it computed was already on record (0 values on sensor 7).
after:  Report by <source> ran successfully, but every value it computed was already on record (sensor 7: computed 5, saved 0).

CLI:

$ flexmeasures add report ...   # rerun
before: The report for sensor `x` repeats beliefs already on record, so nothing new was saved.
after:  The report for sensor `x` repeats beliefs already on record, so nothing new was saved (computed 5, saved 0).

$ flexmeasures add schedule ...   # first run, then a rerun
before: New schedule is stored.
        New schedule is stored.
after:  New schedule is stored: saved 96 beliefs.
        The new schedule repeats beliefs already on record, so nothing new was stored (computed 96, saved 0).

$ flexmeasures add schedule ... --dry-run
before: The schedule above was computed but not stored (because of --dry-run).
after:  The schedule above was computed but not stored (because of --dry-run): computed 96, saved 0.

How to test

Extended tests assert both counts, for a fresh run (computed == saved) and for a rerun that repeats what is on record (computed > 0, saved 0):

• flexmeasures/data/tests/test_generator_results_fresh_db.py, which also has a new test: a NaN value counts as computed, but not as saved.
• flexmeasures/data/tests/test_plugin_automations_fresh_db.py::test_plugin_job_reports_rows_saved
• flexmeasures/cli/tests/test_automations.py, including test_a_rerun_report_job_counts_what_it_saved_and_says_why_it_saved_nothing.
• flexmeasures/api/v3_0/tests/test_report_trigger_api_fresh_db.py: misaligned inputs give 20 computed NaN rows, 0 saved.
• flexmeasures/api/v3_0/tests/test_jobs_api.py: num-computed-beliefs on a finished scheduling job.
• flexmeasures/cli/tests/test_data_add_fresh_db.py: the add report rerun message, and add schedule as a dry run, then a first run, then a rerun.

I checked that each test can fail. For each changed source file in turn (generator_results.py; scheduling.py with scheduling_result.py; data_add.py), I copied it aside, restored the version on main, ran the tests (16, 16 and 2 failures respectively), and put the copy back.

Test runs on a sandboxed Postgres: flexmeasures/cli (285 passed, 1 xfailed), flexmeasures/data/tests (689 passed), the API job, automation, report and schedule tests (183 passed), and flexmeasures/data/models/planning plus flexmeasures/data/models/reporting (463 passed, 3 xfailed).

Further Improvements

• The forecasting path already reports both counts. The CLI's add forecasts message and save_forecast's log say how many beliefs were computed and saved. A forecasting job's result is its runtime, not a count, so it is unchanged here.

Related Items

Closes #2821. Raised in the review of #2818 (discussion).

---

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

🤖 Generated with Claude Code

https://claude.ai/code/session_01UBBvKZkzbfEPKctwTN8SDf

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #35648894 | 📁 Comparing 367bf2b against latest (f2dabe0)

  🔍 Preview build  

10 files changed · ± 10 modified

± Modified

• changelog.html
• genindex.html
• _autosummary/flexmeasures.data.automations.html
• _autosummary/flexmeasures.data.services.generator_results.html
• _autosummary/flexmeasures.data.services.reporting.html
• _autosummary/flexmeasures.data.services.scheduling.html
• _autosummary/flexmeasures.data.services.scheduling_result.html
• api/change_log.html
• api/v3_0.html
• cli/change_log.html

[Copilot]

Note

Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.

🟡 Changes recommended

A repository convention issue remains in flexmeasures/data/services/scheduling_result.py where multi-line docstring bullet continuation lines lack ending punctuation, reducing consistency and reviewability.

1 open issue

• Docstring bullets violate line-ending punctuation convention · New

What changed in this PR

This pull request improves observability for reporting, scheduling, and automation jobs by returning and displaying both how many beliefs were computed and how many were actually saved, so reruns that save nothing can be distinguished from runs that computed nothing. It propagates the new counts through job results, CLI output, API docs/OpenAPI spec, and test coverage (including NaN computed-but-not-saved behavior).

Changes:

• Extend generator result persistence to return n_computed alongside existing saved counts (n_rows), and propagate this through reporting jobs and plugin automation jobs.
• Add num-computed-beliefs to scheduling job results (including dry runs) next to num-beliefs, and update CLI messages to report computed vs saved where meaningful.
• Update Jobs API documentation/OpenAPI spec plus changelogs, and expand tests to cover fresh runs, reruns, and NaN/misaligned-input scenarios.

Review notes (nits):

• Changelog wording should reflect that the prior behavior reported saved counts (not “computed”) to avoid confusion.
• One reporting log message may over-claim “every computed value was already on record” now that “computed” includes NaNs; consider narrowing that statement.
• Docstring bullet formatting in scheduling_result.py should match repo conventions (line endings/punctuation).

File	Summary
flexmeasures/​ui/​static/​openapi-specs.json	Regenerated OpenAPI spec to include the new computed/saved fields and updated examples.
flexmeasures/​data/​tests/​test_plugin_automations_fresh_db.py	Updates/extends automation job tests to assert computed vs saved counts.
flexmeasures/​data/​tests/​test_generator_results_fresh_db.py	Adds coverage for computed-vs-saved semantics, including NaN counted as computed but not saved.
flexmeasures/​data/​services/​scheduling.py	Aggregates computed belief counts for scheduling runs (including dry runs) and exposes them in results.
flexmeasures/​data/​services/​scheduling_result.py	Extends scheduling result structure/serialization to include num-computed-beliefs.
flexmeasures/​data/​services/​reporting.py	Propagates computed vs saved counts into reporting job results and logging.
flexmeasures/​data/​services/​generator_results.py	save_generator_results now returns n_computed alongside n_rows per output while preserving saved-count semantics.
flexmeasures/​cli/​tests/​test_data_add_fresh_db.py	Updates CLI add-flow tests for schedule/report messaging with computed vs saved and dry-run behavior.
flexmeasures/​cli/​tests/​test_automations.py	Updates automation CLI tests to expect computed vs saved counts in outputs/results.
flexmeasures/​cli/​data_add.py	Improves add report / add schedule messages to report computed vs saved and avoid misleading “stored” messages on reruns.
flexmeasures/​api/​v3_0/​tests/​test_report_trigger_api_fresh_db.py	Adds/updates API test assertions for computed NaNs vs 0 saved rows on misaligned inputs.
flexmeasures/​api/​v3_0/​tests/​test_jobs_api.py	Validates num-computed-beliefs appears on finished scheduling job results.
flexmeasures/​api/​v3_0/​jobs.py	Documents the expanded job result payloads (scheduling and reporting) in the Jobs endpoint docs.
documentation/​cli/​change_log.rst	Notes CLI output changes for showing computed vs saved counts.
documentation/​changelog.rst	Updates unreleased v1.1.0 changelog entry to reflect the computed+saved reporting semantics.
documentation/​api/​change_log.rst	Adds API changelog entry documenting the new jobs-result fields (v3.0-34).

_{Review effort: Balanced}

[Copilot]

Note

Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.

🟢 Approval recommended

The change is supported by updated implementations, regenerated API/spec and documentation, and expanded tests covering reruns, dry runs, and NaN edge cases, with only minor formatting/diagnostic nits noted and no unresolved issues indicated.

No open issues 🎉

1 resolved since last review

• Docstring bullets violate line-ending punctuation convention

_{Review effort: Balanced}

[Copilot]

Note

Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.

🟡 Changes recommended

A critical unresolved issue remains because the change repurposes the num-beliefs metric to count computed items rather than saved beliefs, contradicting the stated intent to preserve v1.1.0 semantics and risking downstream/client breakage unless the metric meaning or accompanying documentation is corrected.

1 open issue

• num-beliefs now reports computed count, changing semantics · New

_{Review effort: Balanced}

[Copilot]

Note

Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.

🟡 Changes recommended

Outstanding review findings indicate the API response semantics for belief counts are inconsistent with the documented/expected meaning (computed vs saved) and the related documentation omits an important exclusion behavior, so the change needs correction and clarification before approval.

1 open issue

• Document NaN exclusion in num-saved-beliefs · New

1 resolved since last review

• num-beliefs now reports computed count, changing semantics

_{Review effort: Balanced}

[Copilot]

Note

Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.

🔵 Needs a closer look

The changes still include unresolved issues, most notably a mismatch with the stated dry-run behavior where num-beliefs is set to the computed total (altering its meaning and obscuring saved totals), along with a remaining docstring formatting nit that violates the repository’s punctuation-per-line convention.

1 open issue

• Document NaN exclusion in num-saved-beliefs

_{Review effort: Balanced}