chore: import upstream snapshot with attribution

docs-website/versioned_docs/version-2.24/pipeline-components/rankers/amazonbedrockranker.mdx

@@ -0,0 +1,101 @@
+---
+title: "AmazonBedrockRanker"
+id: amazonbedrockranker
+slug: "/amazonbedrockranker"
+description: "Use this component to rank documents based on their similarity to the query using Amazon Bedrock models."
+---
+
+# AmazonBedrockRanker
+
+Use this component to rank documents based on their similarity to the query using Amazon Bedrock models.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents such as a [Retriever](../retrievers.mdx) |
+| **Mandatory init variables** | `aws_access_key_id`: AWS access key ID. Can be set with AWS_ACCESS_KEY_ID env var.  <br /> <br />`aws_secret_access_key`: AWS secret access key. Can be set with AWS_SECRET_ACCESS_KEY env var.  <br /> <br />`aws_region_name`: AWS region name. Can be set with AWS_DEFAULT_REGION env var. |
+| **Mandatory run variables** | `documents`: A list of document objects  <br /> <br />`query`: A query string |
+| **Output variables** | `documents`: A list of document objects |
+| **API reference** | [Amazon Bedrock](/reference/integrations-amazon-bedrock) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/amazon_bedrock/ |
+
+</div>
+
+## Overview
+
+`AmazonBedrockRanker` ranks documents based on semantic relevance to a specified query. It uses Amazon Bedrock Rerank API. This list of all supported models can be found in Amazon’s [documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/rerank-supported.html). The default model for this Ranker is `cohere.rerank-v3-5:0`.
+
+You can also specify the `top_k` parameter to set the maximum number of documents to return.
+
+### Installation
+
+To start using Amazon Bedrock with Haystack, install the `amazon-bedrock-haystack` package:
+
+```shell
+pip install amazon-bedrock-haystack
+```
+
+### Authentication
+
+This component uses AWS for authentication. You can use the AWS CLI to authenticate through your IAM. For more information on setting up an IAM identity-based policy, see the [official documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/security_iam_id-based-policy-examples.html).
+
+:::info[Using AWS CLI]
+
+Consider using AWS CLI as a more straightforward tool to manage your AWS services. With AWS CLI, you can quickly configure your [boto3 credentials](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html). This way, you won't need to provide detailed authentication parameters when initializing Amazon Bedrock in Haystack.
+:::
+
+To use this component, initialize it with the model name. The AWS credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`) should be set as environment variables, configured as described above, or passed as [Secret](../../concepts/secret-management.mdx) arguments. Make sure the region you set supports Amazon Bedrock.
+
+## Usage
+
+### On its own
+
+This example uses `AmazonBedrockRanker` to rank two simple documents. To run the Ranker, pass a `query` and provide the `documents`.
+
+```python
+from haystack import Document
+from haystack_integrations.components.rankers.amazon_bedrock import AmazonBedrockRanker
+
+docs = [Document(content="Paris"), Document(content="Berlin")]
+
+ranker = AmazonBedrockRanker()
+
+ranker.run(query="City in France", documents=docs, top_k=1)
+```
+
+### In a pipeline
+
+Below is an example of a pipeline that retrieves documents from an `InMemoryDocumentStore` based on keyword search (using `InMemoryBM25Retriever`). It then uses the `AmazonBedrockRanker` to rank the retrieved documents according to their similarity to the query. The pipeline uses the default settings of the Ranker.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.rankers.amazon_bedrock import AmazonBedrockRanker
+
+docs = [
+    Document(content="Paris is in France"),
+    Document(content="Berlin is in Germany"),
+    Document(content="Lyon is in France"),
+]
+document_store = InMemoryDocumentStore()
+document_store.write_documents(docs)
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+ranker = AmazonBedrockRanker()
+
+document_ranker_pipeline = Pipeline()
+document_ranker_pipeline.add_component(instance=retriever, name="retriever")
+document_ranker_pipeline.add_component(instance=ranker, name="ranker")
+
+document_ranker_pipeline.connect("retriever.documents", "ranker.documents")
+
+query = "Cities in France"
+res = document_ranker_pipeline.run(
+    data={
+        "retriever": {"query": query, "top_k": 3},
+        "ranker": {"query": query, "top_k": 2},
+    },
+)
+```

docs-website/versioned_docs/version-2.24/pipeline-components/rankers/choosing-the-right-ranker.mdx

@@ -0,0 +1,60 @@
+---
+title: "Choosing the Right Ranker"
+id: choosing-the-right-ranker
+slug: "/choosing-the-right-ranker"
+description: "This page provides guidance on selecting the right Ranker for your pipeline in Haystack. It explains the distinctions between API-based, on-premise rankers and heuristic approaches, and offers advice based on latency, privacy, and diversity requirements."
+---
+
+# Choosing the Right Ranker
+
+This page provides guidance on selecting the right Ranker for your pipeline in Haystack. It explains the distinctions between API-based, on-premise rankers and heuristic approaches, and offers advice based on latency, privacy, and diversity requirements.
+
+Rankers in Haystack reorder a set of retrieved documents based on their estimated relevance to a user query. Rankers operate after retrieval and aim to refine the result list before it's passed to a downstream component like a [Generator](../generators.mdx) or [Reader](../readers.mdx).
+
+This reordering is based on additional signals beyond simple vector similarity. Depending on the Ranker used, these signals can include semantic similarity (with cross-encoders), structured metadata (such as timestamps or categories), or position-based heuristics (for example, placing relevant content at the start and end).
+
+A typical question answering pipeline using a Ranker includes:
+
+1. Retrieve: Use a [Retriever](../retrievers.mdx) to find a candidate set of documents.  
+2. Rank: Reorder those documents using a Ranker component.  
+3. Answer: Pass the re-ranked documents to a downstream [Generator](../generators.mdx) or [Reader](../readers.mdx).
+
+This guide helps you choose the right Ranker depending on your use case, whether you're optimizing for performance, cost, accuracy, or diversity in results. It focuses on selecting between different types of Rankers in Haystack, not specific models, but rather the general mechanism and interface that best suits your setup.
+
+## API Based Rankers
+
+These Rankers use external APIs to reorder documents using powerful models hosted remotely. They offer high-quality relevance scoring without local compute, but can be slower due to network latency and costly at scale.
+
+The pricing model varies by provider, some charge per token processed , while others bill by usage time or number of API calls. Refer to the respective provider documentation for precise cost structures.
+
+Most API-based Rankers in Haystack currently rely on cross-encoder models (currently, but might change in the future), which evaluate the query and document together to produce highly accurate relevance scores. Examples include [AmazonBedrockRanker](amazonbedrockranker.mdx), [CohereRanker](cohereranker.mdx) and [JinaRanker](jinaranker.mdx).
+
+In contrast, the [NvidiaRanker](nvidiaranker.mdx) uses large language models (LLMs) for ranking. These models treat relevance as a semantic reasoning task, which can yield better results for complex or multi-step queries, though often at higher computational cost.
+
+## On-Premise Rankers
+
+These Rankers run entirely on your local infrastructure. They are ideal for teams prioritizing data privacy, cost control, or low-latency inference without depending on external APIs. Since the models are executed locally, they avoid network bottlenecks and recurring usage costs, but require sufficient compute resources, typically GPU-backed, especially for cross-encoder models.
+
+All on-premise Rankers in Haystack use cross-encoder architectures. These models jointly process the query and each document to assess relevance with deep contextual awareness. For example:
+
+- [SentenceTransformersSimilarityRanker](sentencetransformerssimilarityranker.mdx) ranks documents based on semantic similarity to the query. In addition to the default PyTorch backend (optimal for GPU), it also offers other memory-efficient options which are suitable for CPU-only cases: ONNX and OpenVINO.  
+- [TransformersSimilarityRanker](transformerssimilarityranker.mdx) is its legacy predecessor and should generally be avoided in favor of the newer, more flexible SentenceTransformersSimilarityRanker.  
+- [HuggingFaceTEIRanker](huggingfaceteiranker.mdx) is based on the Text Embeddings Inference project: whether you have GPU resources or not, it offers high-performance for serving the models locally. In addition, you can also use this component to perform inference with reranking models hosted on Hugging Face Inference Endpoints.  
+- [FastembedRanker](fastembedranker.mdx) supports a variety of cross-encoder models and is optimal for CPU-only environments.  
+- [SentenceTransformersDiversityRanker](sentencetransformersdiversityranker.mdx) reorders documents to maximize diversity, helping reduce redundancy and cover a broader range of relevant topics.
+
+These Rankers give you full control over model selection, optimization, and deployment, making them well-suited for production environments with strict SLAs or compliance requirements.
+
+## Rule-Based Rankers
+
+Rule-Based Rankers in Haystack prioritize or reorder documents based on heuristic logic rather than semantic understanding. They operate on document metadata or simple structural patterns, making them computationally efficient and useful for enforcing domain-specific rules or structuring inputs in a retrieval pipeline. While they do not assess semantic relevance directly, they serve as valuable complements to more advanced methods like cross-encoder or LLM-based Rankers.
+
+For example:
+
+- [MetaFieldRanker](metafieldranker.mdx) scores and orders documents based on metadata values such as recency, source reliability, or custom-defined priorities.  
+- [MetaFieldGroupingRanker](metafieldgroupingranker.mdx) groups documents by a specified metadata field and returns every document in each group together, ensuring that related documents (for example, from the same file) are processed as a single block, which has been shown to improve LLM performance.  
+- [LostInTheMiddleRanker](lostinthemiddleranker.mdx) reorders documents after ranking to mitigate position bias in models with limited context windows, ensuring that highly relevant items are not overlooked.
+
+The **MetaFieldRanker** Ranker is typically used _before_ semantic ranking to filter or restructure documents according to business logic.
+
+In contrast, **LostInTheMiddleRanker and MetaFieldGroupingRanker** are intended for use _after_ ranking, to improve the effectiveness of downstream components like LLMs. These deterministic approaches provide speed, transparency, and fine-grained control, making them well-suited for pipelines requiring explainability or strict operational logic.

docs-website/versioned_docs/version-2.24/pipeline-components/rankers/cohereranker.mdx

@@ -0,0 +1,103 @@
+---
+title: "CohereRanker"
+id: cohereranker
+slug: "/cohereranker"
+description: "Use this component to rank documents based on their similarity to the query using Cohere rerank models."
+---
+
+# CohereRanker
+
+Use this component to rank documents based on their similarity to the query using Cohere rerank models.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents such as a [Retriever](../retrievers.mdx) |
+| **Mandatory init variables** | `api_key`: The Cohere API key. Can be set with `COHERE_API_KEY` or `CO_API_KEY` env var. |
+| **Mandatory run variables** | `documents`: A list of document objects  <br /> <br />`query`: A query string  <br /> <br />`top_k`: The maximum number of documents to return |
+| **Output variables** | `documents`: A list of document objects |
+| **API reference** | [Cohere](/reference/integrations-cohere) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cohere |
+
+</div>
+
+## Overview
+
+`CohereRanker` ranks `Documents` based on semantic relevance to a specified query. It uses Cohere rerank models for ranking. This list of all supported models can be found in Cohere’s [documentation](https://docs.cohere.com/docs/rerank-2). The default model for this Ranker is `rerank-english-v2.0`.
+
+You can also specify the `top_k` parameter to set the maximum number of documents to return.
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install cohere-haystack
+```
+
+The component uses a `COHERE_API_KEY` or `CO_API_KEY` environment variable by default. Otherwise, you can pass a Cohere API key at initialization with `api_key` like this:
+
+```python
+ranker = CohereRanker(api_key=Secret.from_token("<your-api-key>"))
+```
+
+## Usage
+
+### On its own
+
+This example uses `CohereRanker` to rank two simple documents. To run the Ranker, pass a `query`, provide the `documents`, and set the number of documents to return in the `top_k` parameter.
+
+```python
+from haystack import Document
+from haystack_integrations.components.rankers.cohere import CohereRanker
+
+docs = [Document(content="Paris"), Document(content="Berlin")]
+
+ranker = CohereRanker()
+
+ranker.run(query="City in France", documents=docs, top_k=1)
+```
+
+### In a pipeline
+
+Below is an example of a pipeline that retrieves documents from an `InMemoryDocumentStore` based on keyword search (using `InMemoryBM25Retriever`). It then uses the `CohereRanker` to rank the retrieved documents according to their similarity to the query. The pipeline uses the default settings of the Ranker.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.rankers.cohere import CohereRanker
+
+docs = [
+    Document(content="Paris is in France"),
+    Document(content="Berlin is in Germany"),
+    Document(content="Lyon is in France"),
+]
+document_store = InMemoryDocumentStore()
+document_store.write_documents(docs)
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+ranker = CohereRanker()
+
+document_ranker_pipeline = Pipeline()
+document_ranker_pipeline.add_component(instance=retriever, name="retriever")
+document_ranker_pipeline.add_component(instance=ranker, name="ranker")
+
+document_ranker_pipeline.connect("retriever.documents", "ranker.documents")
+
+query = "Cities in France"
+res = document_ranker_pipeline.run(
+    data={
+        "retriever": {"query": query, "top_k": 3},
+        "ranker": {"query": query, "top_k": 2},
+    },
+)
+```
+
+:::note[`top_k` parameter]
+
+In the example above, the `top_k` values for the Retriever and the Ranker are different. The Retriever's `top_k` specifies how many documents it returns. The Ranker then orders these documents.
+
+You can set the same or a smaller `top_k` value for the Ranker. The Ranker's `top_k` is the number of documents it returns (if it's the last component in the pipeline) or forwards to the next component. In the pipeline example above, the Ranker is the last component, so the output you get when you run the pipeline are the top two documents, as per the Ranker's `top_k`.
+
+Adjusting the `top_k` values can help you optimize performance. In this case, a smaller `top_k` value of the Retriever means fewer documents to process for the Ranker, which can speed up the pipeline.
+:::

docs-website/versioned_docs/version-2.24/pipeline-components/rankers/external-integrations-rankers.mdx

@@ -0,0 +1,14 @@
+---
+title: "External Integrations"
+id: external-integrations-rankers
+slug: "/external-integrations-rankers"
+description: "External integrations that enable ordering documents by given criteria. Their goal is to improve your document retrieval results."
+---
+
+# External Integrations
+
+External integrations that enable ordering documents by given criteria. Their goal is to improve your document retrieval results.
+
+| Name | Description |
+| --- | --- |
+| [mixedbread ai](https://haystack.deepset.ai/integrations/mixedbread-ai) | Rank documents based on their similarity to the query using Mixedbread AI's reranking API. |

docs-website/versioned_docs/version-2.24/pipeline-components/rankers/fastembedranker.mdx

@@ -0,0 +1,116 @@
+---
+title: "FastembedRanker"
+id: fastembedranker
+slug: "/fastembedranker"
+description: "Use this component to rank documents based on their similarity to the query using cross-encoder models supported by FastEmbed."
+---
+
+# FastembedRanker
+
+Use this component to rank documents based on their similarity to the query using cross-encoder models supported by FastEmbed.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents such as a [Retriever](../retrievers.mdx) |
+| **Mandatory run variables** | `documents`: A list of documents  <br /> <br />`query`: A query string |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [FastEmbed](/reference/fastembed-embedders) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/fastembed |
+
+</div>
+
+## Overview
+
+`FastembedRanker` ranks the documents based on how similar they are to the query.  It uses [cross-encoder models supported by FastEmbed](https://qdrant.github.io/fastembed/examples/Supported_Models/).
+Based on ONXX Runtime, FastEmbed provides a fast experience on standard CPU machines.
+
+`FastembedRanker` is most useful in query pipelines such as a retrieval-augmented generation (RAG) pipeline or a document search pipeline to ensure the retrieved documents are ordered by relevance. You can use it after a Retriever (such as the [`InMemoryEmbeddingRetriever`](../retrievers/inmemoryembeddingretriever.mdx)) to improve the search results. When using `FastembedRanker` with a Retriever, consider setting the Retriever's `top_k` to a small number. This way, the Ranker will have fewer documents to process, which can help make your pipeline faster.
+
+By default, this component uses the `Xenova/ms-marco-MiniLM-L-6-v2` model, but you can switch to a different model by adjusting the `model` parameter when initializing the Ranker. For details on different initialization settings, check out the [API reference](/reference/fastembed-embedders) page.
+
+### Compatible Models
+
+You can find the compatible models in the [FastEmbed documentation](https://qdrant.github.io/fastembed/examples/Supported_Models/).
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install fastembed-haystack
+```
+
+### Parameters
+
+You can set the path where the model is stored in a cache directory. You can also set the number of threads a single `onnxruntime` session can use.
+
+```python
+cache_dir = "/your_cacheDirectory"
+ranker = FastembedRanker(
+    model="Xenova/ms-marco-MiniLM-L-6-v2",
+    cache_dir=cache_dir,
+    threads=2,
+)
+```
+
+If you want to use the data parallel encoding, you can set the parameters `parallel` and `batch_size`.
+
+- If `parallel` > 1, data-parallel encoding will be used. This is recommended for offline encoding of large datasets.
+- If `parallel` is 0, use all available cores.
+- If None, don't use data-parallel processing; use default `onnxruntime` threading instead.
+
+## Usage
+
+### On its own
+
+This example uses `FastembedRanker` to rank two simple documents. To run the Ranker, pass a `query`, provide the `documents`, and set the number of documents to return in the `top_k` parameter.
+
+```python
+from haystack import Document
+from haystack_integrations.components.rankers.fastembed import FastembedRanker
+
+docs = [Document(content="Paris"), Document(content="Berlin")]
+
+ranker = FastembedRanker()
+ranker.warm_up()
+
+ranker.run(query="City in France", documents=docs, top_k=1)
+```
+
+### In a pipeline
+
+Below is an example of a pipeline that retrieves documents from an `InMemoryDocumentStore` based on keyword search using `InMemoryBM25Retriever`. It then uses the `FastembedRanker` to rank the retrieved documents according to their similarity to the query. The pipeline uses the default settings of the Ranker.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.rankers.fastembed import FastembedRanker
+
+docs = [
+    Document(content="Paris is in France"),
+    Document(content="Berlin is in Germany"),
+    Document(content="Lyon is in France"),
+]
+document_store = InMemoryDocumentStore()
+document_store.write_documents(docs)
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+ranker = FastembedRanker()
+
+document_ranker_pipeline = Pipeline()
+document_ranker_pipeline.add_component(instance=retriever, name="retriever")
+document_ranker_pipeline.add_component(instance=ranker, name="ranker")
+
+document_ranker_pipeline.connect("retriever.documents", "ranker.documents")
+
+query = "Cities in France"
+res = document_ranker_pipeline.run(
+    data={
+        "retriever": {"query": query, "top_k": 3},
+        "ranker": {"query": query, "top_k": 2},
+    },
+)
+```

docs-website/versioned_docs/version-2.24/pipeline-components/rankers/huggingfaceteiranker.mdx

@@ -0,0 +1,105 @@
+---
+title: "HuggingFaceTEIRanker"
+id: huggingfaceteiranker
+slug: "/huggingfaceteiranker"
+description: "Use this component to rank documents based on their similarity to the query using a Text Embeddings Inference (TEI) API endpoint."
+---
+
+# HuggingFaceTEIRanker
+
+Use this component to rank documents based on their similarity to the query using a Text Embeddings Inference (TEI) API endpoint.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents, such as a [Retriever](../retrievers.mdx) |
+| **Mandatory init variables** | `url`: Base URL of the TEI reranking service (for example, "https://api.example.com"). |
+| **Mandatory run variables** | `query`: A query string  <br /> <br />`documents`: A list of document objects |
+| **Output variables** | `documents`: A grouped list of documents |
+| **API reference** | [Rankers](/reference/rankers-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/hugging_face_tei.py |
+
+</div>
+
+## Overview
+
+HuggingFaceTEIRanker ranks documents based on semantic relevance to a specified query.
+
+You can use it with one of the Text Embeddings Inference (TEI) API endpoints:
+
+- [Self-hosted Text Embeddings Inference](https://github.com/huggingface/text-embeddings-inference)
+- [Hugging Face Inference Endpoints](https://huggingface.co/inference-endpoints)
+
+You can also specify the `top_k` parameter to set the maximum number of documents to return.
+
+Depending on your TEI server configuration, you may also require a Hugging Face [token](https://huggingface.co/settings/tokens) to use for authorization. You can set it with `HF_API_TOKEN` or `HF_TOKEN` environment variables, or by using Haystack's [Secret management](../../concepts/secret-management.mdx).
+
+## Usage
+
+### On its own
+
+You can use `HuggingFaceTEIRanker` outside of a pipeline to order documents based on your query.
+
+This example uses the `HuggingFaceTEIRanker` to rank two simple documents. To run the Ranker, pass a query, provide the documents, and set the number of documents to return in the `top_k` parameter.
+
+```python
+from haystack import Document
+from haystack.components.rankers import HuggingFaceTEIRanker
+from haystack.utils import Secret
+
+reranker = HuggingFaceTEIRanker(
+    url="http://localhost:8080",
+    top_k=5,
+    timeout=30,
+    token=Secret.from_token("my_api_token")
+)
+
+docs = [Document(content="The capital of France is Paris"), Document(content="The capital of Germany is Berlin")]
+
+result = reranker.run(query="What is the capital of France?", documents=docs)
+
+ranked_docs = result["documents"]
+print(ranked_docs)
+>> {'documents': [Document(id=..., content: 'the capital of France is Paris', score: 0.9979767),
+>>                Document(id=..., content: 'the capital of Germany is Berlin', score: 0.13982213)]}
+```
+
+### In a pipeline
+
+`HuggingFaceTEIRanker` is most efficient in query pipelines when used after a Retriever.
+
+Below is an example of a pipeline that retrieves documents from an `InMemoryDocumentStore` based on keyword search (using `InMemoryBM25Retriever`). It then uses the `HuggingFaceTEIRanker` to rank the retrieved documents according to their similarity to the query. The pipeline uses the default settings of the Ranker.
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.rankers import HuggingFaceTEIRanker
+
+docs = [
+    Document(content="Paris is in France"),
+    Document(content="Berlin is in Germany"),
+    Document(content="Lyon is in France"),
+]
+document_store = InMemoryDocumentStore()
+document_store.write_documents(docs)
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+ranker = HuggingFaceTEIRanker(url="http://localhost:8080")
+ranker.warm_up()
+
+document_ranker_pipeline = Pipeline()
+document_ranker_pipeline.add_component(instance=retriever, name="retriever")
+document_ranker_pipeline.add_component(instance=ranker, name="ranker")
+
+document_ranker_pipeline.connect("retriever.documents", "ranker.documents")
+
+query = "Cities in France"
+document_ranker_pipeline.run(
+    data={
+        "retriever": {"query": query, "top_k": 3},
+        "ranker": {"query": query, "top_k": 2},
+    },
+)
+```

docs-website/versioned_docs/version-2.24/pipeline-components/rankers/jinaranker.mdx

@@ -0,0 +1,105 @@
+---
+title: "JinaRanker"
+id: jinaranker
+slug: "/jinaranker"
+description: "Use this component to rank documents based on their similarity to the query using Jina AI models."
+---
+
+# JinaRanker
+
+Use this component to rank documents based on their similarity to the query using Jina AI models.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents (such as a [Retriever](../retrievers.mdx) ) |
+| **Mandatory init variables** | `api_key`: The Jina API key. Can be set with `JINA_API_KEY` env var. |
+| **Mandatory run variables** | `query`: A query string  <br /> <br />`documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Jina](/reference/integrations-jina) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/jina |
+
+</div>
+
+## Overview
+
+`JinaRanker` ranks the given documents based on how similar they are to the given query. It uses Jina AI ranking models – check out the full list at Jina AI’s [website](https://jina.ai/reranker/). The default model for this Ranker is `jina-reranker-v1-base-en`.
+
+Additionally, you can use the optional `top_k` and `score_threshold` parameters with `JinaRanker` :
+
+- The Ranker's `top_k` is the number of documents it returns (if it's the last component in the pipeline) or forwards to the next component.
+- If you set the `score_threshold` for the Ranker, it will only return documents with a similarity score (computed by the Jina AI model) above this threshold.
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install jina-haystack
+```
+
+### Authorization
+
+The component uses a `JINA_API_KEY` environment variable by default. Otherwise, you can pass a Jina API key at initialization with `api_key` like this:
+
+```python
+ranker = JinaRanker(api_key=Secret.from_token("<your-api-key>"))
+```
+
+To get your API key, head to Jina AI’s [website](https://jina.ai/reranker/).
+
+## Usage
+
+### On its own
+
+You can use `JinaRanker` outside of a pipeline to order documents based on your query.
+
+To run the Ranker, pass a query, provide the documents, and set the number of documents to return in the `top_k` parameter.
+
+```python
+from haystack import Document
+from haystack_integrations.components.rankers.jina import JinaRanker
+
+docs = [Document(content="Paris"), Document(content="Berlin")]
+
+ranker = JinaRanker()
+
+ranker.run(query="City in France", documents=docs, top_k=1)
+```
+
+### In a pipeline
+
+This is an example of a pipeline that retrieves documents from an `InMemoryDocumentStore` based on keyword search (using `InMemoryBM25Retriever`). It then uses the `JinaRanker` to rank the retrieved documents according to their similarity to the query.
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack_integrations.components.rankers.jina import JinaRanker
+
+docs = [
+    Document(content="Paris is in France"),
+    Document(content="Berlin is in Germany"),
+    Document(content="Lyon is in France"),
+]
+document_store = InMemoryDocumentStore()
+document_store.write_documents(docs)
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+ranker = JinaRanker()
+
+ranker_pipeline = Pipeline()
+ranker_pipeline.add_component(instance=retriever, name="retriever")
+ranker_pipeline.add_component(instance=ranker, name="ranker")
+
+ranker_pipeline.connect("retriever.documents", "ranker.documents")
+
+query = "Cities in France"
+ranker_pipeline.run(
+    data={
+        "retriever": {"query": query, "top_k": 3},
+        "ranker": {"query": query, "top_k": 2},
+    },
+)
+```

docs-website/versioned_docs/version-2.24/pipeline-components/rankers/lostinthemiddleranker.mdx

@@ -0,0 +1,113 @@
+---
+title: "LostInTheMiddleRanker"
+id: lostinthemiddleranker
+slug: "/lostinthemiddleranker"
+description: "This Ranker positions the most relevant documents at the beginning and at the end of the resulting list while placing the least relevant Documents in the middle."
+---
+
+# LostInTheMiddleRanker
+
+This Ranker positions the most relevant documents at the beginning and at the end of the resulting list while placing the least relevant Documents in the middle.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents (such as a [Retriever](../retrievers.mdx) ) |
+| **Mandatory run variables**            | `documents`: A list of documents                                                                                   |
+| **Output variables**                   | `documents`: A list of documents                                                                                   |
+| **API reference**                      | [Rankers](/reference/rankers-api)                                                                                         |
+| **GitHub link**                        | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/lost_in_the_middle.py               |
+
+</div>
+
+## Overview
+
+The `LostInTheMiddleRanker` reorders the documents based on the "Lost in the Middle" order, described in the ["Lost in the Middle: How Language Models Use Long Contexts"](https://arxiv.org/abs/2307.03172) research paper. It aims to lay out paragraphs into LLM context so that the relevant paragraphs are at the beginning or end of the input context, while the least relevant information is in the middle of the context. This reordering is helpful when very long contexts are sent to an LLM, as current models pay more attention to the start and end of long input contexts.
+
+In contrast to other rankers, `LostInTheMiddleRanker` assumes that the input documents are already sorted by relevance, and it doesn’t require a query as input. It is typically used as the last component before building a prompt for an LLM to prepare the input context for the LLM.
+
+### Parameters
+
+If you specify the `word_count_threshold` when running the component, the Ranker includes all documents up until the point where adding another document would exceed the given threshold. The last document that exceeds the threshold will be included in the resulting list of Documents, but all following documents will be discarded.
+
+You can also specify the `top_k` parameter to set the maximum number of documents to return.
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.rankers import LostInTheMiddleRanker
+
+ranker = LostInTheMiddleRanker()
+docs = [
+    Document(content="Paris"),
+    Document(content="Berlin"),
+    Document(content="Madrid"),
+]
+result = ranker.run(documents=docs)
+
+for doc in result["documents"]:
+    print(doc.content)
+```
+
+### In a pipeline
+
+Note that this example requires an OpenAI key to run.
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.rankers import LostInTheMiddleRanker
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+
+## Define prompt template
+prompt_template = [
+    ChatMessage.from_system("You are a helpful assistant."),
+    ChatMessage.from_user(
+        "Given these documents, answer the question.\nDocuments:\n"
+        "{% for doc in documents %}{{ doc.content }}{% endfor %}\n"
+        "Question: {{query}}\nAnswer:",
+    ),
+]
+
+## Define documents
+docs = [
+    Document(content="Paris is in France..."),
+    Document(content="Berlin is in Germany..."),
+    Document(content="Lyon is in France..."),
+]
+
+document_store = InMemoryDocumentStore()
+document_store.write_documents(docs)
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+ranker = LostInTheMiddleRanker(word_count_threshold=1024)
+prompt_builder = ChatPromptBuilder(
+    template=prompt_template,
+    required_variables={"query", "documents"},
+)
+generator = OpenAIChatGenerator()
+
+p = Pipeline()
+p.add_component(instance=retriever, name="retriever")
+p.add_component(instance=ranker, name="ranker")
+p.add_component(instance=prompt_builder, name="prompt_builder")
+p.add_component(instance=generator, name="llm")
+
+p.connect("retriever.documents", "ranker.documents")
+p.connect("ranker.documents", "prompt_builder.documents")
+p.connect("prompt_builder.messages", "llm.messages")
+
+p.run(
+    {
+        "retriever": {"query": "What cities are in France?", "top_k": 3},
+        "prompt_builder": {"query": "What cities are in France?"},
+    },
+)
+```

docs-website/versioned_docs/version-2.24/pipeline-components/rankers/metafieldgroupingranker.mdx

@@ -0,0 +1,130 @@
+---
+title: "MetaFieldGroupingRanker"
+id: metafieldgroupingranker
+slug: "/metafieldgroupingranker"
+description: "Reorder the documents by grouping them based on metadata keys."
+---
+
+# MetaFieldGroupingRanker
+
+Reorder the documents by grouping them based on metadata keys.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents, such as a [Retriever](../retrievers.mdx) |
+| **Mandatory init variables**           | `group_by`: The name of the meta field to group by                                                               |
+| **Mandatory run variables**            | `documents`: A list of documents to group                                                                        |
+| **Output variables**                   | `documents`: A grouped list of documents                                                                         |
+| **API reference**                      | [Rankers](/reference/rankers-api)                                                                                       |
+| **GitHub link**                        | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/meta_field_grouping_ranker.py     |
+
+</div>
+
+## Overview
+
+The `MetaFieldGroupingRanker` component groups documents by a primary metadata key `group_by`, and subgroups them with an optional secondary key, `subgroup_by`.
+Within each group or subgroup, the component can also sort documents by a metadata key `sort_docs_by`.
+
+The output is a flat list of documents ordered by `group_by` and `subgroup_by` values. Any documents without a group are placed at the end of the list.
+
+The component helps improve the efficiency and performance of subsequent processing by an LLM.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.components.rankers import MetaFieldGroupingRanker
+from haystack import Document
+
+docs = [
+    Document(
+        content="JavaScript is popular",
+        meta={"group": "42", "split_id": 7, "subgroup": "subB"},
+    ),
+    Document(
+        content="Python is popular",
+        meta={"group": "42", "split_id": 4, "subgroup": "subB"},
+    ),
+    Document(
+        content="A chromosome is DNA",
+        meta={"group": "314", "split_id": 2, "subgroup": "subC"},
+    ),
+    Document(
+        content="An octopus has three hearts",
+        meta={"group": "11", "split_id": 2, "subgroup": "subD"},
+    ),
+    Document(
+        content="Java is popular",
+        meta={"group": "42", "split_id": 3, "subgroup": "subB"},
+    ),
+]
+
+ranker = MetaFieldGroupingRanker(
+    group_by="group",
+    subgroup_by="subgroup",
+    sort_docs_by="split_id",
+)
+result = ranker.run(documents=docs)
+print(result["documents"])
+```
+
+### In a pipeline
+
+The following pipeline uses the `MetaFieldGroupingRanker` to organize documents by certain meta fields while sorting by page number, then formats these organized documents into a chat message which is passed to the `OpenAIChatGenerator` to create a structured explanation of the content.
+
+```python
+from haystack import Pipeline
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.rankers import MetaFieldGroupingRanker
+from haystack.dataclasses import Document, ChatMessage
+
+docs = [
+    Document(
+        content="Chapter 1: Introduction to Python",
+        meta={"chapter": "1", "section": "intro", "page": 1},
+    ),
+    Document(
+        content="Chapter 2: Basic Data Types",
+        meta={"chapter": "2", "section": "basics", "page": 15},
+    ),
+    Document(
+        content="Chapter 1: Python Installation",
+        meta={"chapter": "1", "section": "setup", "page": 5},
+    ),
+]
+
+ranker = MetaFieldGroupingRanker(
+    group_by="chapter",
+    subgroup_by="section",
+    sort_docs_by="page",
+)
+
+chat_generator = OpenAIChatGenerator(
+    generation_kwargs={"temperature": 0.7, "max_tokens": 500},
+)
+
+## First run the ranker
+ranked_result = ranker.run(documents=docs)
+ranked_docs = ranked_result["documents"]
+
+## Create chat messages with the ranked documents
+messages = [
+    ChatMessage.from_system("You are a helpful programming tutor."),
+    ChatMessage.from_user(
+        f"Here are the course documents in order:\n"
+        + "\n".join([f"- {doc.content}" for doc in ranked_docs])
+        + "\n\nBased on these documents, explain the structure of this Python course.",
+    ),
+]
+
+## Create and run pipeline for just the chat generator
+pipeline = Pipeline()
+pipeline.add_component("chat_generator", chat_generator)
+
+result = pipeline.run(data={"chat_generator": {"messages": messages}})
+
+print(result["chat_generator"]["replies"][0])
+```

docs-website/versioned_docs/version-2.24/pipeline-components/rankers/metafieldranker.mdx

@@ -0,0 +1,91 @@
+---
+title: "MetaFieldRanker"
+id: metafieldranker
+slug: "/metafieldranker"
+description: "`MetaFieldRanker` ranks Documents based on the value of their meta field you specify. It's a lightweight Ranker that can improve your pipeline's results without slowing it down."
+---
+
+# MetaFieldRanker
+
+`MetaFieldRanker` ranks Documents based on the value of their meta field you specify. It's a lightweight Ranker that can improve your pipeline's results without slowing it down.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents, such as a [Retriever](../retrievers.mdx) |
+| **Mandatory init variables** | `meta_field`: The name of the meta field to rank by |
+| **Mandatory run variables** | `documents`: A list of documents  <br /> <br />`top_k`: The maximum number of documents to return. If not provided, returns all documents it received. |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Rankers](/reference/rankers-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/meta_field.py |
+
+</div>
+
+## Overview
+
+`MetaFieldRanker` sorts documents based on the value of a specific meta field in descending or ascending order. This means the returned list of `Document` objects are arranged in a selected order, with string values sorted alphabetically or in reverse (for example, Tokyo, Paris, Berlin).
+
+`MetaFieldRanker` comes with the optional parameters  `weight` and `ranking_mode` you can use to combine a document’s score assigned by the Retriever and the value of its meta field for the ranking. The `weight` parameter lets you balance the importance of the Document's content and the meta field in the ranking process. The `ranking_mode` parameter defines how the scores from the Retriever and the Ranker are combined.
+
+This Ranker is useful in query pipelines, like retrieval-augmented generation (RAG) pipelines or document search pipelines. It ensures the documents are ordered by their meta field value. You can also use it after a Retriever (such as the `InMemoryEmbeddingRetriever`) to combine the Retriever’s score with a document’s meta value for improved ranking.
+
+By default, `MetaFieldRanker` sorts documents only based on the meta field. You can adjust this by setting the `weight` to less than 1 when initializing this component. For more details on different initialization settings, check out the API reference for this component.
+
+## Usage
+
+### On its own
+
+You can use this Ranker outside of a pipeline to sort documents.
+
+This example uses the `MetaFieldRanker` to rank two simple documents. When running the Ranker, you pass the  `query`, provide the `documents` and set the number of documents to rank using the `top_k` parameter.
+
+```python
+from haystack import Document
+from haystack.components.rankers import MetaFieldRanker
+
+docs = [
+    Document(content="Paris", meta={"rating": 1.3}),
+    Document(content="Berlin", meta={"rating": 0.7}),
+]
+
+ranker = MetaFieldRanker(meta_field="rating")
+
+ranker.run(query="City in France", documents=docs, top_k=1)
+```
+
+### In a pipeline
+
+Below is an example of a pipeline that retrieves documents from an `InMemoryDocumentStore` based on keyword search (using `InMemoryBM25Retriever`). It then uses the `MetaFieldRanker` to rank the retrieved documents based on the meta field `rating`, using the Ranker's default settings:
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.rankers import MetaFieldRanker
+
+docs = [
+    Document(content="Paris", meta={"rating": 1.3}),
+    Document(content="Berlin", meta={"rating": 0.7}),
+    Document(content="Barcelona", meta={"rating": 2.1}),
+]
+document_store = InMemoryDocumentStore()
+document_store.write_documents(docs)
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+ranker = MetaFieldRanker(meta_field="rating")
+
+document_ranker_pipeline = Pipeline()
+document_ranker_pipeline.add_component(instance=retriever, name="retriever")
+document_ranker_pipeline.add_component(instance=ranker, name="ranker")
+
+document_ranker_pipeline.connect("retriever.documents", "ranker.documents")
+
+query = "Cities in France"
+document_ranker_pipeline.run(
+    data={
+        "retriever": {"query": query, "top_k": 3},
+        "ranker": {"query": query, "top_k": 2},
+    },
+)
+```

docs-website/versioned_docs/version-2.24/pipeline-components/rankers/nvidiaranker.mdx

@@ -0,0 +1,116 @@
+---
+title: "NvidiaRanker"
+id: nvidiaranker
+slug: "/nvidiaranker"
+description: "Use this component to rank documents based on their similarity to the query using Nvidia-hosted models."
+---
+
+# NvidiaRanker
+
+Use this component to rank documents based on their similarity to the query using Nvidia-hosted models.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents such as a [Retriever](../retrievers.mdx) |
+| **Mandatory init variables** | `api_key`: API key for the NVIDIA NIM. Can be set with `NVIDIA_API_KEY` env var. |
+| **Mandatory run variables** | `query`: A query string  <br /> <br />`documents`: A list of document objects |
+| **Output variables** | `documents`: A list of document objects |
+| **API reference** | [Nvidia](/reference/integrations-nvidia) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/nvidia |
+
+</div>
+
+## Overview
+
+`NvidiaRanker` ranks `Documents` based on semantic relevance to a specified query. It uses ranking models provided by [NVIDIA NIMs](https://ai.nvidia.com). The default model for this Ranker is `nvidia/nv-rerankqa-mistral-4b-v3`.
+
+You can also specify the `top_k` parameter to set the maximum number of documents to return.
+
+See the rest of the customizable parameters you can set for `NvidiaRanker` in our [API reference](/reference/integrations-nvidia).
+
+To start using this integration with Haystack, install it with:
+
+```shell
+pip install nvidia-haystack
+```
+
+The component uses an `NVIDIA_API_KEY` environment variable by default. Otherwise, you can pass an Nvidia API key at initialization with `api_key` like this:
+
+```python
+ranker = NvidiaRanker(api_key=Secret.from_token("<your-api-key>"))
+```
+
+## Usage
+
+### On its own
+
+This example uses `NvidiaRanker` to rank two simple documents. To run the Ranker, pass a `query`, provide the `documents`, and set the number of documents to return in the `top_k` parameter.
+
+```python
+    from haystack_integrations.components.rankers.nvidia import NvidiaRanker
+    from haystack import Document
+    from haystack.utils import Secret
+
+    ranker = NvidiaRanker(
+        model="nvidia/nv-rerankqa-mistral-4b-v3",
+        api_key=Secret.from_env_var("NVIDIA_API_KEY"),
+    )
+    ranker.warm_up()
+
+    query = "What is the capital of Germany?"
+    documents = [
+        Document(content="Berlin is the capital of Germany."),
+        Document(content="The capital of Germany is Berlin."),
+        Document(content="Germany's capital is Berlin."),
+    ]
+
+    result = ranker.run(query, documents, top_k=2)
+    print(result["documents"])
+```
+
+### In a pipeline
+
+Below is an example of a pipeline that retrieves documents from an `InMemoryDocumentStore` based on keyword search (using `InMemoryBM25Retriever`). It then uses the `NvidiaRanker` to rank the retrieved documents according to their similarity to the query. The pipeline uses the default settings of the Ranker.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.rankers.nvidia import NvidiaRanker
+
+docs = [
+    Document(content="Paris is in France"),
+    Document(content="Berlin is in Germany"),
+    Document(content="Lyon is in France"),
+]
+document_store = InMemoryDocumentStore()
+document_store.write_documents(docs)
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+ranker = NvidiaRanker()
+
+document_ranker_pipeline = Pipeline()
+document_ranker_pipeline.add_component(instance=retriever, name="retriever")
+document_ranker_pipeline.add_component(instance=ranker, name="ranker")
+
+document_ranker_pipeline.connect("retriever.documents", "ranker.documents")
+
+query = "Cities in France"
+res = document_ranker_pipeline.run(
+    data={
+        "retriever": {"query": query, "top_k": 3},
+        "ranker": {"query": query, "top_k": 2},
+    },
+)
+```
+
+:::note[`top_k` parameter]
+
+In the example above, the `top_k` values for the Retriever and the Ranker are different. The Retriever's `top_k` specifies how many documents it returns. The Ranker then orders these documents.
+
+You can set the same or a smaller `top_k` value for the Ranker. The Ranker's `top_k` is the number of documents it returns (if it's the last component in the pipeline) or forwards to the next component. In the pipeline example above, the Ranker is the last component, so the output you get when you run the pipeline are the top two documents, as per the Ranker's `top_k`.
+
+Adjusting the `top_k` values can help you optimize performance. In this case, a smaller `top_k` value of the Retriever means fewer documents to process for the Ranker, which can speed up the pipeline.
+:::

docs-website/versioned_docs/version-2.24/pipeline-components/rankers/pyversityranker.mdx

@@ -0,0 +1,160 @@
+---
+title: "PyversityRanker"
+id: pyversityranker
+slug: "/pyversityranker"
+description: "Use this component to rerank documents by balancing relevance and diversity using pyversity's diversification algorithms."
+---
+
+# PyversityRanker
+
+Use this component to rerank documents by balancing relevance and diversity using pyversity's diversification algorithms.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a dense [Retriever](../retrievers.mdx) with `return_embedding=True` |
+| **Mandatory init variables** | None |
+| **Mandatory run variables** | `documents`: A list of document objects, each with `score` and `embedding` set |
+| **Output variables** | `documents`: A list of document objects |
+| **API reference** | [Pyversity](/reference/integrations-pyversity) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/pyversity |
+
+</div>
+
+## Overview
+
+`PyversityRanker` reranks `Documents` using [pyversity](https://github.com/Pringled/pyversity)'s diversification algorithms. Unlike similarity-based rankers, it balances **relevance and diversity** - so the output isn't just the most relevant documents, but a varied selection that avoids redundancy.
+
+Documents must have both `score` and `embedding` populated. This makes it a natural fit after a dense retriever such as `InMemoryEmbeddingRetriever` configured with `return_embedding=True`. Documents missing either field are skipped with a warning.
+
+The key parameters are:
+
+- `strategy`: The diversification algorithm to use. Defaults to `Strategy.DPP` (Determinantal Point Process). `Strategy.MMR` (Maximal Marginal Relevance) is another popular option.
+- `diversity`: A float in `[0, 1]` controlling the relevance–diversity trade-off. `0.0` keeps the most relevant documents; `1.0` maximises diversity regardless of relevance. Defaults to `0.5`.
+- `top_k`: The number of documents to return. If `None`, all documents are returned in diversified order.
+
+### Installation
+
+To start using this integration with Haystack, install the package with:
+
+```shell
+pip install pyversity-haystack
+```
+
+## Usage
+
+### On its own
+
+This example uses `PyversityRanker` to rerank five documents. Each document must have a `score` and `embedding` set. The ranker returns the top 3 documents using the MMR strategy with a diversity of `0.7`.
+
+```python
+from haystack import Document
+from pyversity import Strategy
+
+from haystack_integrations.components.rankers.pyversity import PyversityRanker
+
+documents = [
+    Document(
+        content="Paris is the capital of France.",
+        score=0.95,
+        embedding=[0.9, 0.1, 0.0, 0.0],
+    ),
+    Document(
+        content="The Eiffel Tower is located in Paris.",
+        score=0.90,
+        embedding=[0.8, 0.2, 0.0, 0.0],
+    ),
+    Document(
+        content="Berlin is the capital of Germany.",
+        score=0.85,
+        embedding=[0.0, 0.0, 0.9, 0.1],
+    ),
+    Document(
+        content="The Brandenburg Gate is in Berlin.",
+        score=0.80,
+        embedding=[0.0, 0.0, 0.8, 0.2],
+    ),
+    Document(
+        content="France borders Spain to the south.",
+        score=0.75,
+        embedding=[0.5, 0.5, 0.0, 0.0],
+    ),
+]
+
+ranker = PyversityRanker(top_k=3, strategy=Strategy.MMR, diversity=0.7)
+result = ranker.run(documents=documents)
+
+for doc in result["documents"]:
+    print(f"{doc.score:.2f}  {doc.content}")
+```
+
+### In a pipeline
+
+Below is an example of a pipeline that embeds documents and stores them in an `InMemoryDocumentStore`. It then retrieves the top 6 documents using `InMemoryEmbeddingRetriever` and reranks them with `PyversityRanker` to return 3 diverse results.
+
+Note that the retriever must be configured with `return_embedding=True` so that documents have embeddings available for the ranker.
+
+```python
+from haystack import Document, Pipeline
+from haystack.components.embedders import (
+    SentenceTransformersDocumentEmbedder,
+    SentenceTransformersTextEmbedder,
+)
+from haystack.components.retrievers import InMemoryEmbeddingRetriever
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from pyversity import Strategy
+
+from haystack_integrations.components.rankers.pyversity import PyversityRanker
+
+# Index documents
+document_store = InMemoryDocumentStore()
+
+raw_documents = [
+    Document(content="Paris is the capital of France."),
+    Document(content="The Eiffel Tower is located in Paris."),
+    Document(content="Berlin is the capital of Germany."),
+    Document(content="The Brandenburg Gate is in Berlin."),
+    Document(content="France borders Spain to the south."),
+    Document(content="The Louvre is the world's largest art museum and is in Paris."),
+    Document(content="Munich is the capital of Bavaria."),
+    Document(content="The Rhine river flows through Germany and France."),
+]
+
+doc_embedder = SentenceTransformersDocumentEmbedder()
+documents_with_embeddings = doc_embedder.run(raw_documents)["documents"]
+document_store.write_documents(documents_with_embeddings)
+
+# Build pipeline
+pipeline = Pipeline()
+pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+pipeline.add_component(
+    "retriever",
+    InMemoryEmbeddingRetriever(
+        document_store=document_store,
+        top_k=6,
+        return_embedding=True,
+    ),
+)
+pipeline.add_component(
+    "ranker",
+    PyversityRanker(top_k=3, strategy=Strategy.MMR, diversity=0.7),
+)
+
+pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+pipeline.connect("retriever.documents", "ranker.documents")
+
+# Run
+result = pipeline.run(
+    {"text_embedder": {"text": "What are the famous landmarks in France?"}},
+)
+
+for doc in result["ranker"]["documents"]:
+    print(f"{doc.score:.4f}  {doc.content}")
+```
+
+:::note[Embeddings required]
+
+`PyversityRanker` requires documents to have both `score` and `embedding` set. When using a dense retriever, make sure to pass `return_embedding=True`. Documents missing either field are skipped with a warning.
+
+:::

docs-website/versioned_docs/version-2.24/pipeline-components/rankers/sentencetransformersdiversityranker.mdx

@@ -0,0 +1,99 @@
+---
+title: "SentenceTransformersDiversityRanker"
+id: sentencetransformersdiversityranker
+slug: "/sentencetransformersdiversityranker"
+description: "This is a Diversity Ranker based on Sentence Transformers."
+---
+
+# SentenceTransformersDiversityRanker
+
+This is a Diversity Ranker based on Sentence Transformers.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents such as a [Retriever](../retrievers.mdx) |
+| **Mandatory init variables** | `token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. |
+| **Mandatory run variables** | `documents`: A list of documents  <br /> <br />`query`: A query string |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Rankers](/reference/rankers-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/sentence_transformers_diversity.py |
+
+</div>
+
+## Overview
+
+The `SentenceTransformersDiversityRanker` uses a ranking algorithm to order documents to maximize their overall diversity. It ranks a list of documents based on their similarity to the query. The component embeds the query and the documents using a pre-trained Sentence Transformers model.
+
+This Ranker’s default model is `sentence-transformers/all-MiniLM-L6-v2`.
+
+You can optionally set the `top_k` parameter, which specifies the maximum number of documents to return. If you don’t set this parameter, the component returns all documents it receives.
+
+Find the full list of optional initialization parameters in our [API reference](/reference/rankers-api#sentencetransformersdiversityranker).
+
+## Usage
+
+### On its own
+
+```python
+from haystack import Document
+from haystack.components.rankers import SentenceTransformersDiversityRanker
+
+ranker = SentenceTransformersDiversityRanker(
+    model="sentence-transformers/all-MiniLM-L6-v2",
+    similarity="cosine",
+)
+ranker.warm_up()
+
+docs = [
+    Document(content="Regular Exercise"),
+    Document(content="Balanced Nutrition"),
+    Document(content="Positive Mindset"),
+    Document(content="Eating Well"),
+    Document(content="Doing physical activities"),
+    Document(content="Thinking positively"),
+]
+
+query = "How can I maintain physical fitness?"
+output = ranker.run(query=query, documents=docs)
+docs = output["documents"]
+
+print(docs)
+```
+
+### In a pipeline
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.rankers import SentenceTransformersDiversityRanker
+
+docs = [
+    Document(content="The iconic Eiffel Tower is a symbol of Paris"),
+    Document(content="Visit Luxembourg Gardens for a haven of tranquility in Paris"),
+    Document(
+        content="The Point Alexandre III bridge in Paris is famous for its Beaux-Arts style",
+    ),
+]
+document_store = InMemoryDocumentStore()
+document_store.write_documents(docs)
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+ranker = SentenceTransformersDiversityRanker(meta_field="rating")
+
+document_ranker_pipeline = Pipeline()
+document_ranker_pipeline.add_component(instance=retriever, name="retriever")
+document_ranker_pipeline.add_component(instance=ranker, name="ranker")
+
+document_ranker_pipeline.connect("retriever.documents", "ranker.documents")
+
+query = "Most famous iconic sight in Paris"
+document_ranker_pipeline.run(
+    data={
+        "retriever": {"query": query, "top_k": 3},
+        "ranker": {"query": query, "top_k": 2},
+    },
+)
+```

docs-website/versioned_docs/version-2.24/pipeline-components/rankers/sentencetransformerssimilarityranker.mdx

@@ -0,0 +1,112 @@
+---
+title: "SentenceTransformersSimilarityRanker"
+id: sentencetransformerssimilarityranker
+slug: "/sentencetransformerssimilarityranker"
+description: "Use this component to rank documents based on their similarity to the query. The SentenceTransformersSimilarityRanker is a powerful, model-based Ranker that uses a cross-encoder model to produce document and query embeddings."
+---
+
+# SentenceTransformersSimilarityRanker
+
+Use this component to rank documents based on their similarity to the query. The SentenceTransformersSimilarityRanker is a powerful, model-based Ranker that uses a cross-encoder model to produce document and query embeddings.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents such as a [Retriever](../retrievers.mdx) |
+| **Mandatory init variables** | `token` (only for private models): The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. |
+| **Mandatory run variables** | `documents`: A list of documents  <br /> <br />`query`: A query string |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Rankers](/reference/rankers-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/sentence_transformers_similarity.py |
+
+</div>
+
+## Overview
+
+`SentenceTransformersSimilarityRanker` ranks documents based on how similar they are to the query. It uses a pre-trained cross-encoder model from the Hugging Face Hub to embed both the query and the documents. It then compares the embeddings to determine how similar they are. The result is a list of `Document` objects in ranked order, with the Documents most similar to the query appearing first.
+
+`SentenceTransformersSimilarityRanker` is most useful in query pipelines, such as a retrieval-augmented generation (RAG) pipeline or a document search pipeline, to ensure the retrieved documents are ordered by relevance. You can use it after a Retriever (such as the `InMemoryEmbeddingRetriever`) to improve the search results. When using `SentenceTransformersSimilarityRanker` with a Retriever, consider setting the Retriever's `top_k` to a small number. This way, the Ranker will have fewer documents to process, which can help make your pipeline faster.
+
+By default, this component uses the `cross-encoder/ms-marco-MiniLM-L-6-v2` model, but it's flexible. You can switch to a different model by adjusting the `model` parameter when initializing the Ranker. For details on different initialization settings, check out the API reference for this component.
+
+You can set the `device` parameter to use HF models on your CPU or GPU.
+
+Additionally, you can select the backend to use for the Sentence Transformers mode with the `backend` parameter: `torch` (default), `onnx`, or `openvino`.
+
+### Authorization
+
+The component uses a `HF_API_TOKEN` environment variable by default. Otherwise, you can pass a Hugging Face API token at initialization with [Secret](../../concepts/secret-management.mdx) `token`:
+
+```python
+ranker = SentenceTransformersSimilarityRanker(token=Secret.from_token("<your-api-key>"))
+```
+
+## Usage
+
+### On its own
+
+You can use `SentenceTransformersSimilarityRanker` outside of a pipeline to order documents based on your query.
+
+This example uses the `SentenceTransformersSimilarityRanker` to rank two simple documents. To run the Ranker, pass a query, provide the documents, and set the number of documents to return in the `top_k` parameter.
+
+```python
+from haystack import Document
+from haystack.components.rankers import SentenceTransformersSimilarityRanker
+
+ranker = SentenceTransformersSimilarityRanker()
+docs = [Document(content="Paris"), Document(content="Berlin")]
+query = "City in Germany"
+ranker.warm_up()
+result = ranker.run(query=query, documents=docs)
+docs = result["documents"]
+print(docs[0].content)
+```
+
+### In a pipeline
+
+`SentenceTransformersSimilarityRanker` is most efficient in query pipelines when used after a Retriever.
+
+Below is an example of a pipeline that retrieves documents from an `InMemoryDocumentStore` based on keyword search (using `InMemoryBM25Retriever`). It then uses the `SentenceTransformersSimilarityRanker` to rank the retrieved documents according to their similarity to the query. The pipeline uses the default settings of the Ranker.
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.rankers import SentenceTransformersSimilarityRanker
+
+docs = [
+    Document(content="Paris is in France"),
+    Document(content="Berlin is in Germany"),
+    Document(content="Lyon is in France"),
+]
+document_store = InMemoryDocumentStore()
+document_store.write_documents(docs)
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+ranker = SentenceTransformersSimilarityRanker()
+ranker.warm_up()
+
+document_ranker_pipeline = Pipeline()
+document_ranker_pipeline.add_component(instance=retriever, name="retriever")
+document_ranker_pipeline.add_component(instance=ranker, name="ranker")
+
+document_ranker_pipeline.connect("retriever.documents", "ranker.documents")
+
+query = "Cities in France"
+document_ranker_pipeline.run(
+    data={
+        "retriever": {"query": query, "top_k": 3},
+        "ranker": {"query": query, "top_k": 2},
+    },
+)
+```
+
+:::note[Ranker top_k]
+
+In the example above, the `top_k` values for the Retriever and the Ranker are different. The Retriever's `top_k` specifies how many documents it returns. The Ranker then orders these documents.
+
+You can set the same or a smaller `top_k` value for the Ranker. The Ranker's `top_k` is the number of documents it returns (if it's the last component in the pipeline) or forwards to the next component. In the pipeline example above, the Ranker is the last component, so the output you get when you run the pipeline are the top two documents, as per the Ranker's `top_k`.
+
+Adjusting the `top_k` values can help you optimize performance. In this case, a smaller `top_k` value of the Retriever means fewer documents to process for the Ranker, which can speed up the pipeline.
+:::

docs-website/versioned_docs/version-2.24/pipeline-components/rankers/transformerssimilarityranker.mdx

@@ -0,0 +1,115 @@
+---
+title: "TransformersSimilarityRanker"
+id: transformerssimilarityranker
+slug: "/transformerssimilarityranker"
+description: "Use this component to rank documents based on their similarity to the query. The `TransformersSimilarityRanker` is a powerful, model-based Ranker that uses a cross-encoder model to produce document and query embeddings."
+---
+
+# TransformersSimilarityRanker
+
+Use this component to rank documents based on their similarity to the query. The `TransformersSimilarityRanker` is a powerful, model-based Ranker that uses a cross-encoder model to produce document and query embeddings.
+
+:::warning[Legacy Component]
+
+This component is considered legacy and will no longer receive updates. It may be deprecated in a future release, followed by removal after a deprecation period.
+Consider using SentenceTransformersSimilarityRanker instead, as it provides the same functionality and additional features.
+:::
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Most common position in a pipeline** | In a query pipeline, after a component that returns a list of documents such as a [Retriever](../retrievers.mdx) |
+| **Mandatory init variables** | `token` (only for private models): The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. |
+| **Mandatory run variables** | `documents`: A list of documents  <br /> <br />`query`: A query string |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Rankers](/reference/rankers-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/transformers_similarity.py |
+
+</div>
+
+## Overview
+
+`TransformersSimilarityRanker` ranks documents based on how similar they are to the query. It uses a pre-trained cross-encoder model from the Hugging Face Hub to embed both the query and the documents. It then compares the embeddings to determine how similar they are. The result is a list of `Document `objects in ranked order, with the Documents most similar to the query appearing first.
+
+`TransformersSimilarityRanker` is most useful in query pipelines, such as a retrieval-augmented generation (RAG) pipeline or a document search pipeline, to ensure the retrieved documents are ordered by relevance. You can use it after a Retriever (such as the `InMemoryEmbeddingRetriever`) to improve the search results. When using `TransformersSimilarityRanker` with a Retriever, consider setting the Retriever's `top_k` to a small number. This way, the Ranker will have fewer documents to process, which can help make your pipeline faster.
+
+By default, this component uses the `cross-encoder/ms-marco-MiniLM-L-6-v2` model, but it's flexible. You can switch to a different model by adjusting the `model` parameter when initializing the Ranker. For details on different initialization settings, check out the API reference for this component.
+
+You can also set the `device` parameter to use HF models on your CPU or GPU.
+
+### Authorization
+
+The component uses a `HF_API_TOKEN` environment variable by default. Otherwise, you can pass a Hugging Face API token at initialization with `token` – see code examples below.
+
+```python
+ranker = TransformersSimilarityRanker(token=Secret.from_token("<your-api-key>"))
+```
+
+## Usage
+
+### On its own
+
+You can use `TransformersSimilarityRanker` outside of a pipeline to order documents based on your query.
+
+This example uses the `TransformersSimilarityRanker` to rank two simple documents. To run the Ranker, pass a query, provide the documents, and set the number of documents to return in the `top_k` parameter.
+
+```python
+from haystack import Document
+from haystack.components.rankers import TransformersSimilarityRanker
+
+docs = [Document(content="Paris"), Document(content="Berlin")]
+
+ranker = TransformersSimilarityRanker()
+ranker.warm_up()
+
+ranker.run(query="City in France", documents=docs, top_k=1)
+```
+
+### In a pipeline
+
+`TransformersSimilarityRanker` is most efficient in query pipelines when used after a Retriever.
+
+Below is an example of a pipeline that retrieves documents from an `InMemoryDocumentStore` based on keyword search (using `InMemoryBM25Retriever`). It then uses the `TransformersSimilarityRanker` to rank the retrieved documents according to their similarity to the query. The pipeline uses the default settings of the Ranker.
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack.components.rankers import TransformersSimilarityRanker
+
+docs = [
+    Document(content="Paris is in France"),
+    Document(content="Berlin is in Germany"),
+    Document(content="Lyon is in France"),
+]
+document_store = InMemoryDocumentStore()
+document_store.write_documents(docs)
+
+retriever = InMemoryBM25Retriever(document_store=document_store)
+ranker = TransformersSimilarityRanker()
+ranker.warm_up()
+
+document_ranker_pipeline = Pipeline()
+document_ranker_pipeline.add_component(instance=retriever, name="retriever")
+document_ranker_pipeline.add_component(instance=ranker, name="ranker")
+
+document_ranker_pipeline.connect("retriever.documents", "ranker.documents")
+
+query = "Cities in France"
+document_ranker_pipeline.run(
+    data={
+        "retriever": {"query": query, "top_k": 3},
+        "ranker": {"query": query, "top_k": 2},
+    },
+)
+```
+
+:::note[Ranker `top_k`]
+
+In the example above, the `top_k` values for the Retriever and the Ranker are different. The Retriever's `top_k` specifies how many documents it returns. The Ranker then orders these documents.
+
+You can set the same or a smaller `top_k` value for the Ranker. The Ranker's `top_k` is the number of documents it returns (if it's the last component in the pipeline) or forwards to the next component. In the pipeline example above, the Ranker is the last component, so the output you get when you run the pipeline are the top two documents, as per the Ranker's `top_k`.
+
+Adjusting the `top_k` values can help you optimize performance. In this case, a smaller `top_k` value of the Retriever means fewer documents to process for the Ranker, which can speed up the pipeline.
+:::