fix: update Multiretriever params

[Amnah199]

Related Issues

• fixes https://linear.app/deepset/issue/BUI-1073/fix-multiretirver-init-params-in-haystack

Proposed Changes:

• Add top_k_per_retriever and forward it to each retriever as its top_k; filters and top_k_per_retriever are now only passed when set, so each retriever keeps its own defaults otherwise.
• Apply the overall top_k at merge time to truncate the combined results, using RRF for a consistent ranking; fixed a sorted shadowing bug in _merge_results.
• Mirror the same behavior in run_async.

How did you test it?

• Add/update tests for forwarding, truncation, and RRF fallback (sync + async).

Notes for the reviewer

Checklist

• I have read the contributors guidelines and the code of conduct.
• I have updated the related issue with new insights and changes.
• I have added unit tests and updated the docstrings.
• I've used one of the conventional commit types for my PR title: fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, test: and added ! in case the PR includes breaking changes.
• I have documented my code.
• I have added a release note file, following the contributors guidelines.
• I have run pre-commit hooks and fixed any issue.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
haystack-docs	Ignored	Preview	Jul 6, 2026 12:36pm

[claude]

Code review

Reviewed for bugs and CLAUDE.md / AGENTS.md compliance. Three issues found.

---

1. to_dict does not serialize the new top_k_per_retriever parameter (serialization round-trip bug)

__init__ adds and stores the new top_k_per_retriever init parameter, but to_dict was not updated to include it:

haystack/haystack/components/retrievers/multi_retriever.py

Lines 311 to 318 in 04abc65

	return default_to_dict(
	self,
	retrievers={name: component_to_dict(obj=r, name=name) for name, r in self.retrievers.items()},
	filters=self.filters,
	top_k=self.top_k,
	max_workers=self.max_workers,
	join_mode=self.join_mode,
	)

Since from_dict reconstructs via default_from_dict (which calls cls(**init_parameters) using only the keys present in the serialized dict), a MultiRetriever(top_k_per_retriever=...) will silently revert top_k_per_retriever to None after a to_dict() -> from_dict() round-trip (e.g. saving and reloading a pipeline), dropping the configured per-retriever truncation.

        return default_to_dict(
            self,
            retrievers={name: component_to_dict(obj=r, name=name) for name, r in self.retrievers.items()},
            filters=self.filters,
            top_k_per_retriever=self.top_k_per_retriever,
            top_k=self.top_k,
            max_workers=self.max_workers,
            join_mode=self.join_mode,
        )

---

2. test_init_default_parameters now fails — default top_k changed from 10 to None

This PR changes the __init__ default of top_k from 10 to None, but the existing (unmodified) test still asserts retriever.top_k == 10 for a default-constructed instance, so it will fail in CI:

haystack/test/components/retrievers/test_multi_retriever.py

Lines 101 to 106 in 04abc65

	retriever = MultiRetriever(retrievers=retrievers)
	assert retriever.retrievers == retrievers
	assert retriever.filters is None
	assert retriever.top_k == 10
	assert retriever.max_workers == 4
	assert retriever.join_mode == "reciprocal_rank_fusion"

        assert retriever.top_k is None

---

3. Missing release note (AGENTS.md adherence)

The root CLAUDE.md mandates following AGENTS.md, which requires:

Every user-facing PR (not docs, not CI) must include a release note

haystack/AGENTS.md

Lines 53 to 59 in 04abc65

	## Release Notes
	Every user-facing PR (not docs, not CI) must include a release note:
	hatch run release-note SHORT_DESCRIPTION
	Edit the generated file in `releasenotes/notes/`. Release notes use reStructuredText formatting; see the [release notes section in CONTRIBUTING.md](CONTRIBUTING.md#release-notes) for details.

This PR adds a new public parameter (top_k_per_retriever) and changes the semantics/default of the existing public top_k parameter on the MultiRetriever component, but no releasenotes/notes/*.yaml file is included. The @_experimental status does not exempt it — prior PRs to this same experimental component (its introduction and the join_mode/RRF addition) both included release notes. Please add one via hatch run release-note ....

[bogdankostic]

Looks already good in genral, let's just make sure to document the new behavior and update the serialization methods for the new parameter

[bogdankostic]

Let's document this in public facing docstrings, private methods are not in shown in our API reference.

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
haystack/components/retrievers
multi_retriever.py					137
haystack/core/pipeline
async_pipeline.py
Project Total

This report was generated by python-coverage-comment-action