fix: validate join_mode in MultiRetriever

[hermanrous]

Related Issues

• No direct issue. Follow-up to the runtime validation work in fix: validate top_k in MultiRetriever #12719 (top_k in MultiRetriever) and fix: validate runtime top_k in MetaFieldRanker #12262 (MetaFieldRanker).

Proposed Changes:

MultiRetriever.__init__ accepted any join_mode value. Only the exact string "reciprocal_rank_fusion" selects RRF in _merge_results; every other value falls through to the concatenate branch:

if top_k is not None or self.join_mode == "reciprocal_rank_fusion":
    documents = _reciprocal_rank_fusion(document_lists)
    ...
return _deduplicate_documents([doc for docs in document_lists for doc in docs])

A typo such as "Concatenate", "rrf", or "reciprocal_rank_fusion " with a trailing space was therefore accepted silently and changed both the scores and the order of the merged documents, with nothing raised. The mistake also stays invisible in pipelines deserialized from YAML, where the Literal annotation on join_mode cannot be enforced.

This adds a ValueError in __init__ naming the two supported modes, using the same wording MetaFieldRanker uses for its Literal parameters.

JoinMode from haystack/components/joiners/document_joiner.py was deliberately not reused: it has four members (merge and distribution_based_rank_fusion included) while MultiRetriever implements only two, so JoinMode.from_str would let the other two fall into the very concatenate branch this PR fixes.

How did you test it?

• New test_init_with_invalid_join_mode_raises, parametrized over "Concatenate", "reciprocal-rank-fusion", "reciprocal_rank_fusion " and "rrf".
  • On unmodified main: 4 failed, with E Failed: DID NOT RAISE ValueError.
  • With the change: 4 passed.
• test/components/retrievers/test_multi_retriever.py: 54 passed, 6 skipped before, 58 passed, 6 skipped after.
• test/components/retrievers/: 254 passed, 11 skipped.
• Checked the deserialization path directly as well: component_from_dict with join_mode="Reciprocal_Rank_Fusion" used to return an instance silently and now raises.
• ruff check, ruff format --check and mypy are clean.

Environment caveat, same as #12262 and #12719: the suites were run in a plain venv built with pip rather than through Hatch, because the full Hatch environment could not be resolved locally.

Notes for the reviewer

• The :raises ValueError: docstring now also covers join_mode.
• Release note added under releasenotes/notes/.

Checklist

• I have read the contributors guidelines and the code of conduct.
• I have updated the related issue with new insights and changes. — N/A, there is no related issue.
• I have added unit tests and updated the docstrings.
• I've used a conventional commit type for my PR title: fix:.
• I have documented my code.
• I have added a release note file.
• I have run pre-commit hooks and fixed any issue.

This PR was fully generated with an AI assistant. I have reviewed the changes and run the relevant tests.

[CLAassistant]

All committers have signed the CLA.

[HaystackBot]

Hi @hermanrous, thanks a lot for your contribution! 🙏

We noticed that the Contributor License Agreement (CLA) check (license/cla) hasn't passed yet, so we've temporarily moved this PR to draft and paused the review assignment.

To get your PR reviewed, please sign the CLA via the link in the license/cla check below (or in the CLA bot comment). As soon as the check turns green, this PR will automatically be marked ready for review again and a reviewer will be re-assigned.

[HaystackBot]

Thanks for signing the CLA, @hermanrous! 🎉 This PR is now ready for review again and the reviewer has been re-assigned.