Settle which source wins an event with one rule, in two steps

[Flix6x]

Description

Closes #2476, which found that three different rules decided which data source wins an event, and that
the one written down was not implemented.

A version only orders one source's releases. The choice between sources ranked every version in
the frame together, so a forecaster at v9 beat a scheduler at v1 on the strength of the number alone —
against a fresher belief, and against a caller that had asked for the scheduler:

no list                 -> forecaster v9 value=22.0
[scheduler, forecaster] -> forecaster v9 value=22.0
   (scheduler v1 = 11.0, believed at the event; forecaster v9 = 22.0, believed 12h earlier)

Sources are now grouped into families sharing a name, type and model — the same grouping
keep_latest_version already used — and versions are only compared inside one.

Between families, the caller's order decides. This is what the AggregatorReporter has documented
since #819, "the first source defined in the sources array is prioritized", and what it never did.
test_source_transition passed because source1 sorts alphabetically before source2; reversing the
list changed nothing. It does now, and that test says so.

What neither settles falls to the most recent belief, and then to the highest source id, which
does not move when a source is renamed.

So the whole rule, in one place:

	Within a family	Between families
1	latest version	the caller's order, where one was given
2	most recent belief	most recent belief
3	highest source id	highest source id

Also

The probabilistic path repeated the same ranking in pandas, carrying the same cross-family bug. It now
makes its beliefs deterministic and hands them to the one implementation, so there is a single rule to
read and to change.

keep_latest_version is skipped when one belief per event is asked for. That path settles versions
itself, family by family, and running it first would drop a fresher belief before the choice was made.

How to test

pytest flexmeasures/data/tests/test_search_postprocessing.py \
       flexmeasures/data/models/reporting/tests/test_aggregator.py

test_search_postprocessing.py pins each step of the chain in its own test, and cross-checks the
vectorised choice against a plainly written one over random frames spanning two families, with and
without a caller's preference. Each test was confirmed to fail with the rule it covers disabled:

• ignoring the caller's order fails the caller-order test and the equivalence test;
• comparing versions across families fails the cross-family test and the equivalence test.

test_source_transition now also asserts the reverse ordering, so the sentence in its docstring is
covered rather than merely stated.

Full suite green: 1863 passed.

Base

This is stacked on #2472, which touches the same file and documents the tie behaviour this PR changes.
It is not stacked on #2293, despite the shared subject matter: that branch touches none of these files,
and stacking there would make a core fix wait on a large feature PR.

• Added changelog item in documentation/changelog.rst

---

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 another incompatible license.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WS6V8nZyRzMxsvqGnNpUTk

[Copilot]

🟡 Changes recommended

A newly added docstring in time_series.py violates the repo’s line-break-after-punctuation convention and should be reflowed before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR consolidates “which data source wins an event” into a single, deterministic selection rule used consistently across deterministic and probabilistic belief-selection paths, aligning implementation with the documented AggregatorReporter behavior and fixing cross-family version comparisons.

Changes:

• Implement a two-step precedence algorithm in _select_latest_version_and_belief_per_event (within-source-family: version → recency → id; between families: caller order → recency → id), and route probabilistic selection through the same implementation after median-reduction.
• Expand/strengthen test coverage to pin the rule’s behavior (including caller source order and cross-family version non-comparability), plus update AggregatorReporter test to assert reversed precedence.
• Add a changelog entry describing the user-visible behavior change.

File summaries

File	Description
flexmeasures/data/tests/test_search_postprocessing.py	Adds deterministic reference implementation + focused tests asserting the new precedence rule and equivalence with the vectorized selector.
flexmeasures/data/models/time_series.py	Introduces the unified precedence implementation and routes selection paths through it; updates parameter docs accordingly.
flexmeasures/data/models/reporting/tests/test_aggregator.py	Strengthens test_source_transition to assert caller-provided source order affects the overlap event winner.
documentation/changelog.rst	Documents the bugfix and new deterministic precedence rule for end users.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #34450659 | 📁 Comparing 0ddc51c against latest (f303d7d)

  🔍 Preview build  

6 files changed · ± 6 modified

± Modified

• changelog.html
• genindex.html
• _autosummary/flexmeasures.data.models.parsing_utils.html
• _autosummary/flexmeasures.data.models.time_series.html
• api/v3_0.html
• views/asset-data.html

[Copilot]

🟡 Changes recommended

Source precedence can become unintentionally dependent on DB-return ordering when source is provided as a single name that expands to multiple DataSources, which can contradict the intended tie-break rules.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 2
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

Source-preference ranking can be incorrect when the caller includes unknown source ids/names, because empty preference groups can shift positions and cause explicitly listed sources to tie with (or fall behind) unlisted sources.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🟢 Approval recommended

The behavioral changes are well-covered by targeted tests and align the implementation with the stated precedence rules; remaining feedback is limited to minor typing/maintainability nits.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

flexmeasures/data/models/time_series.py:929

• The preferred_sources parameter is used as a list of entries (each entry being either a single DataSource or a group like list[DataSource]/tuple[DataSource, ...]), but the current annotation (list | None) is too loose and makes it easy to call this helper with the wrong element types (which would fail at runtime when accessing .id). Tighten the type to match the expected structure so callers and type-checking can catch mistakes earlier.

• Files reviewed: 5/5 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

The newly added “naive” reference implementation in test_search_postprocessing.py still doesn’t mirror the production selector’s per-entry (grouped) preference semantics, weakening it as a long-term oracle for equivalence tests.

Review details

Suppressed comments (1)

flexmeasures/data/tests/test_search_postprocessing.py:52

• naive_select_latest_version_and_belief_per_event still treats preferred_sources as a flat list and uses len(positions) as the “unlisted” sentinel, but the production selector now treats each entry as one preference (possibly a group) and uses the number of entries (including empty/unknown ones) as the sentinel. This makes the naive implementation a less faithful oracle for grouped preferences and can let future equivalence tests drift from production semantics.

    positions: dict = {}
    for position, source in enumerate(preferred_sources or []):
        positions.setdefault(source.id, position)
    unlisted = len(positions)

• Files reviewed: 5/5 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

The new preferred_sources type annotations allow nested generic Sequences, but the implementation only treats list/tuple as grouped entries, creating a mismatch that can lead to runtime errors unless the typing or the grouping check is aligned.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

flexmeasures/data/tests/test_search_postprocessing.py:54

• This reference implementation types preferred_sources as allowing nested Sequence[DataSource], but only treats (list, tuple) as a grouped entry. Align the runtime check with the annotation (or narrow the annotation), otherwise passing a non-list/tuple sequence would be treated as a single element and break at source.id.

        group = entry if isinstance(entry, (list, tuple)) else [entry]

• Files reviewed: 5/5 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

A small docstring mismatch remains in TimedBelief.search where the source parameter description doesn’t explicitly state that list order affects precedence in one_deterministic_belief_per_event mode.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

It changes core belief-selection semantics in a highly cross-cutting query path, so a final human review is warranted to validate the precedence rule against domain expectations and potential downstream effects.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Flix6x]

Restacked onto main after #2472 was squash-merged, without a rebase or a force-push.

A squash merge leaves main holding #2472's content as a single commit with no history in common with the commits this branch carries, so every overlapping hunk conflicts between two spellings of the same change. Merging main with -X ours settles those by construction — where the two sides overlap they say the same thing — while everything else from main comes in normally.

Checked by measuring this branch's own content before and after: 5 files, +399/-103 against the old stack base, and the same 5 files and +399/-103 against main now. Nothing from #2472 was duplicated and nothing here was dropped. 1574 data and API tests pass.

The base is now main, and the PR is mergeable again.