deepset-ai--haystack/docs-website/reference/integrations-api/pyversity.md

title, id, description, slug

title	id	description	slug
pyversity	integrations-pyversity	pyversity integration for Haystack	/integrations-pyversity

haystack_integrations.components.rankers.pyversity.ranker

Haystack integration for pyversity <https://github.com/Pringled/pyversity>_.

Wraps pyversity's diversification algorithms as a Haystack @component, making it easy to drop result diversification into any Haystack pipeline.

PyversityRanker

Reranks documents using pyversity's diversification algorithms.

Balances relevance and diversity in a ranked list of documents. Documents must have both score and embedding populated (e.g. as returned by a dense retriever with return_embedding=True).

Usage example:

from haystack import Document
from haystack_integrations.components.rankers.pyversity import PyversityRanker
from pyversity import Strategy

ranker = PyversityRanker(top_k=5, strategy=Strategy.MMR, diversity=0.5)

docs = [
    Document(content="Paris", score=0.9, embedding=[0.1, 0.2]),
    Document(content="Berlin", score=0.8, embedding=[0.3, 0.4]),
]
output = ranker.run(documents=docs)
docs = output["documents"]

init

__init__(
    top_k: int | None = None,
    *,
    strategy: Strategy = Strategy.DPP,
    diversity: float = 0.5
) -> None

Creates an instance of PyversityRanker.

Parameters:

• top_k (int | None) – Number of documents to return after diversification. If None, all documents are returned in diversified order.
• strategy (Strategy) – Pyversity diversification strategy (e.g. Strategy.MMR). Defaults to Strategy.DPP.
• diversity (float) – Trade-off between relevance and diversity in [0, 1]. 0.0 keeps only the most relevant documents; 1.0 maximises diversity regardless of relevance. Defaults to 0.5.

Raises:

• ValueError – If top_k is not a positive integer or diversity is not in [0, 1].

to_dict

to_dict() -> dict[str, Any]

Serializes the component to a dictionary.

Returns:

• dict[str, Any] – Dictionary with serialized data.

from_dict

from_dict(data: dict[str, Any]) -> PyversityRanker

Deserializes the component from a dictionary.

Parameters:

• data (dict[str, Any]) – The dictionary to deserialize from.

Returns:

• PyversityRanker – The deserialized component instance.

run

run(
    documents: list[Document],
    top_k: int | None = None,
    strategy: Strategy | None = None,
    diversity: float | None = None,
) -> dict[str, list[Document]]

Rerank the list of documents using pyversity's diversification algorithm.

Documents missing score or embedding are skipped with a warning.

Parameters:

• documents (list[Document]) – List of Documents to rerank. Each document must have score and embedding set.
• top_k (int | None) – Overrides the initialized top_k for this call. None falls back to the initialized value.
• strategy (Strategy | None) – Overrides the initialized strategy for this call. None falls back to the initialized value.
• diversity (float | None) – Overrides the initialized diversity for this call. None falls back to the initialized value.

Returns:

• dict[str, list[Document]] – A dictionary with the following keys:
• documents: List of up to top_k reranked Documents, ordered by the diversification algorithm.

Raises:

• ValueError – If top_k is not a positive integer or diversity is not in [0, 1].